cli send msg dlg

Open Send Message Dialogue from Command Line

The providers of a records management service want to be able to open the send message dialogue in datovka from their application to provide more comfort for their users.

The application should be able to open the send message dialogue with already filled-in content. The content of the dialogue form should be passed via the command line interface.

Brief Function Description

The user of the records management service application selects documents he/she wants to send via Datovka. He/she then triggers the operation to send the documents via Datovka.

1a. The records management service application creates temporary files containing the documents which are required to be sent via Datovka.

1b. The records management service application passes the paths to the created temporary files to Datovka by calling the application executable with suitable command-line arguments.
Datovka starts (if it has not been already running) and displays the send message dialogue. The dialogue form must contain all documents which have been specified by the user in the records management service application.

2a. The user is notified if some documents could not be added into the form (e.g., files could not be read or do not exist, etc.).
The user then specifies in the send message dialogue all required missing information such as message annotation, recipient or sender box, etc.
The user should be provided with the opportunity to send the created ISDS data message back into the records management service if this service is configured within the Datovka application.

4a. In order to upload the sent message to the records management service the newly sent message must be acquired from the ISDS server. The user is presented (at the bottom of the send message dialogue) with the choice to do so if he desires it.

4b. If the user has chosen to upload the newly sent message into the records management service then the upload to records management dialogue is automatically presented to him after the sent message has been successfully downloaded.

4c. The user proceeds as usual with the upload of the data message into the records management service.

Implementation Details

Detecting Datovka in the System

Implemented in development branch.

Datovka didn't advertise its presence in any of the supported operating systems.

On UNIX-like systems (excluding macOS) it is commonly installed into the default application path - unless the administrator specifies otherwise. In such case it is the administrator's job to retain all of the required functionality and we are not to be blamed for any error.

On macOS the Datovka package is usually installed to the following location: /Applications/datovka.app. However the application may also reside somewhere in a path specified by the system user. The order of preference detection could be:

primarily, launch Datovka from PATH
secondarily, launch Datovka from the default package location

On Windows we provide three ways of how Datovka is distributed:

installer version (stores data in home directory)
portable version in a zip archive (stores data in application directory)
normal version in a zip archive (stores data in home directory)

The testing build of the Windows installer (msi) sets a registry value (similar to values specified here) which advertise the location of the installed application. The installer sets the following two registry keys AppLocation and AppLocationCLI which hold a full path to the installed executables. Both keys are located in the path HKEY_LOCAL_MACHINE\Software\CZ.NIC\Datovka\. The installer may instead in future set these values in the HKEY_CURRENT_USER tree - but this is not the case now.

Datovka is a 32-bit application. You may therefore on 64-bit Windows need to check values in the WOW6432Node subtree (i.e. HKEY_LOCAL_MACHINE\Software\WOW6432Node\CZ.NIC\Datovka\).

Datovka location could also be set in the environment PATH variable. However, setting the value of the PATH variable is left on the user. This may be the needed in the case of Datovka applications which have been extracted from the zip archives.

The default installed location of Datovka on 64-bit Windows is c:\Program Files (x86)\CZ.NIC\Datovka.

A preferred way of Detecting Datovka on Windows would presumably be:

Look for a registry values in HKEY_LOCAL_MACHINE an then HKEY_CURRENT_USER.
Try launching Datovka via the PATH environment variable.
Try launching Datovka from some guessed 'standard' paths.

Of course, the records management service application could ask the user to directly specify Datovka location if it could not be acquired otherwise.

Passing Required Data

Implemented in development branch.

A development version of Datovka supports the --compose command-line option. The option is similar to the already present --send-msg CLI option. Most of the arguments are similar.

The --compose command-line option is available only for the GUI application because it raises the send message dialogue window. On Windows we are also distributing separate CLI applications datovka-cli.exe (or datovka-cli-portable.exe) because of various issues with the usage of the command line and GUI application on Windows. These specialised CLI applications don't and won't support the --compose command-line option.

--compose The argument to the --compose parameter consists of a single string containing value assignments to the following keys:

dbIDRecipient - List of recipient data-box identifiers separated by semicolons. The length of the box identifiers is 7 characters. At least one must be specified.
dmAnnotation - Message subject string. Maximal length is 255 characters.
dmToHands - Name of preferred recipient person in recipient organisation. Maximal length is 50 characters.
dmRecipientRefNumber - Czech: číslo jednací příjemce. Maximal length is 50 characters.
dmSenderRefNumber - Czech: číslo jednací odesílatele. Maximal length is 50 characters.
dmRecipientIdent - Czech: spisová značka příjemce. Maximal length is 50 characters.
dmSenderIdent - Czech: spisová značka odesílatele. Maximal length is 50 characters.
dmLegalTitleLaw - Number of act mandating authority. Maximal length is 4 characters.
dmLegalTitleYear - Year of act issue mandating authority. Maximal length is 4 characters.
dmLegalTitleSect - Section of act mandating authority (Czech: paragraf). Maximal length is 10 characters.
dmLegalTitlePar - Paragraph of act mandating authority (Czech: odstavec). Maximal length is 10 characters.
dmLegalTitlePoint - Point of act mandating authority (písmeno). Required length is 1 character.
dmPersonalDelivery - If true, only person with higher privileges can read this message. Accepted values: {0,1}.
dmAllowSubstDelivery - Allow delivery through fiction. Accepted values: {0,1}.
dmPublishOwnID - Allow sender to express his name shall be available to recipient. Accepted values: {0,1}.
dmAttachment - Full path to target files separated by semicolons. NOTE: The semicolon character ';' is not allowed in a legal attachment path or file name.

The values to the specified keys are assigned using the following syntax: key1='val1',key2='val2',...,keyn='valn'. The assignments are separated using a comma (,) character. Each assignment is specified by a substring key='val'. (The quotation marks around the val statement are mandatory.)

The val statement may consist of a list of values. In such the entries are separated by a semicolon (;).

The command

./datovka --compose "dbIDRecipient='a5s8ee1',dmAnnotation='Test message',dmPersonalDelivery='1',dmAttachment='/tmp/xsda558/request.pdf;/tmp/xsda558/explanation.pdf'"

will raise the send message dialogue window and will fill in the annotation, the recipient and will add the two attachment files (if they are found in the specified locations) in the same sequence as they have been specified.

If you just want to raise the send message dialogue window and pass a single file you then the following command is fully sufficient:

./datovka --compose "dmAttachment='/tmp/xsda558/request.pdf'"

Passing Documents

The records management service application will write files in a usual temporary files location and pass these file locations via the proposed command-line option into Datovka. In order to avoid any clashes in file naming, all such files will be located in a uniquely-named sub-directory within the normal location for temporary files.

Handling the Open Dialogue Request in Datovka

Calling Datovka with --compose option will:

When Datovka is already running then all required data are passed to the main Datovka process.

1a. The invoked Datovka process checks the supplied arguments for basic sanity and if no errors (e.g. unknown arguments) have been detected then all data are going to be passed to the already running Datovka process. The invoked process exist successfully if no errors have been detected. The invoked Datovka process terminates before the actual sending of the message.

1b. The main process will collect the passed data and notify the user about any further error (e.g. non-existent file). A pre-filled send message dialogue window is presented to the user if no critical errors occur.
The command with --compose option will start the Datovka application when it has not been running. The started process does not create a separate child process to detach from the calling environment. It is left to the calling environment to detach the newly created process. The calling environment must assure that the Datovka process is left running in order to let the user to finish the sending operation.

2a. After Datovka starts, the supplied parameters are checked for basis sanity. If errors are detected the the application exists with an error.

2b. After the application GUI starts the send message dialogue is presented to the user. The user may be warned about any potential error (e.g. non-existent file).

2c. The application does not terminate by itself when the send message dialogue is confirmed by the user and the message has been sent.

Passing Sent Data Message into the Records Management Service

The user is provided with an option to upload the created data message back into the document service.

In such case the sent data message is needed to be downloaded immediately after it has been successfully sent. This is because we need to obtain a ZFO with necessary timestamps.