cli

Command-Line Interface (CLI)

Command-Line Interface (CLI)

This document summarises the command-line interface of Datovka.

Background

Several users have been complaining about a missing CLI. Their wish was to have an interface that could:

send messages
check for new messages
extract a message
extract content of new messages

The client should not provide any means of sending messages via e-mail. Should only provide a command-line interface for the most common actions with ISDS so that these actions could be incorporated into scripts.

Inspiration

The command-line interface resembles the Thunderbird CLI. Also, there exists a command-line ISDS client called shigofumi 😺.

Basic command-line options

The following parameters are available in both the GUI application and for the special CLI application (available only on Windows).

Usage: datovka [ options ] [ zfo-file ]

Options:

-h, --help - Displays this help.
-v, --version - Displays version information.
-D, --debug - Enable logging of debugging information.
-L, --log-verbosity level - Set verbosity of logged messages to level.
-V, --debug-verbosity level - Set debugging verbosity to level.
--conf-subdir conf-subdir - Use conf-subdir subdirectory for configuration.
--load-conf conf - On start load conf file.
--save-conf conf - On stop save conf file.
--log-file file - Log messages to file. (in development branch)

Parameters:

zfo-file - ZFO file to be viewed.

Command-line options which affect the GUI application

These options are available only the graphical user interface application.

Options:

--compose <message-options> - Brings up the send message dialogue window and fills in the supplied data.

--compose option

This option was added in Datovka 4.11.

The --compose option takes a single argument 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.

Since version 4.13.0 Datovka provides the possibility to upload the sent message into the records management service via the upload_file service. In order to do so the following parameter have been added:

recMgmtUpload - Enables the upload into document service field. Accepted values: {0,1}.
recMgmtHierarchyId - Takes a string value which specifies the hierarchy location where to upload the data message into. If this parameter is not supplied, then the user will be asked for the location in a default way

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'"

The Windows executables datovka-cli.exe or datovka-cli-portable.exe don't support the --compose prameter because these executables don't provide a graphical user interface.

Executing ./datovka --compose "..." command will raise the send message dialogue in an already running GUI application process if such process has already been running. The command will terminate with no error.

Executing ./datovka --compose "..." when no other datovka GUI process is running will start the GUI application. The executed application will continue running even after the raised send message dialogue has been closed.

Command-line only options - databox/message operations

On Windows you must use the executable datovka-cli.exe or datovka-cli-portable.exe. The executable files datovka.exe and datovka-portable.exe don't allow printing service result to standard output when using Windows shell (cmd.exe) or PowerShell.

Usage: datovka --login "username='xxxxxx'" --service-name "parameter-list"

Login and account identification:

--login <string_of_parameters> - Login into databox. It is mandatory for following services. If Datovka already knows the login information for the related account then the supplied information will be ignored.

The following options (services) are related to actions that should be performed. "--login <string_of_parameters>" option must be present before service declaration.

Service Names:

--get-msg-list <string_of_parameters> - Download list of received/sent messages from ISDS (synchronization with ISDS).
--send-msg <string_of_parameters> - Create and send a new message to ISDS.
--get-msg <string_of_parameters> - Download from ISDS or get from local database complete message with signature and time stamp MV and export to ZFO file.
--get-delivery-info <string_of_parameters> - Download from ISDS or get from local database delivery info of message with signature and time stamp MV and export to ZFO file.
--get-user-info - Get information about user and its role and privileges.
--get-owner-info - Get information about owner and its databox.
--check-attachment - Get list of messages where attachment missing (local database only).
--get-msg-ids <string_of_parameters> - Get list of message IDs (received/sent) from local database (since version 4.9.2).
--find-databox <string_of_parameters> - Find a databox via several parameters.

string_of_parameters has format:

"param_1='value_1',param_2='value_2', .... param_n='value_n'"

List of supported parameters for options:

--login

username - Username. Length is 6 characters. [Mandatory]
password - Password. Maximal length is 50 characters. [Optional]
otpcode - Certificate password | Hardware security code. [Optional] WARNING: SMS security code not supported now!
certificate - Path to certificate file (DER, PEM). [Optional] WARNING: not supported now!

Return

[status] - 0 is success, 1 error.
if an error then error code and its description are writing into stderr.

Example:

datovka --login "username='xxxxxx',password='yyyyyyyy',certificate='C:\temp\certificate.pem',otpcode='zzzzzzz'"

List of supported parameters for services:

--get-msg-list

dmType - Type of messages. Values: {sent,received,all}, default is received. [Mandatory]
dmStatusFilter - Filter focused on the message status. Value: {1,2,...,10} - see ISDS for more info, default is -1 = (all message status). [Optional]
dmLimit - Limit of returned messages. Maximal value is 10000. [Optional]
dmFromTime - Delivery time from. Format: YYYY-MM-DD. [Optional] WARNING: not supported now!
dmToTime - Delivery time to. Format: YYYY-MM-DD. [Optional] WARNING: not supported now!
complete - Automatically download complete messages (may be slow). Values: {yes,no}, default is no. NOTE: Complete message including attachments will be stored only to database (without saving attachments/ZFO to disk). Message wont set as locally read. [Optional]

Return

[status] - 0 is success, 1 error.
newMsgIdList - print to terminal (stdout) a list of new message IDs separated by white space.
if an error then error code and its description are writing into stderr.

Example:

datovka --login "username='xxxxxx',password='yyyyyyyy'" --get-msg-list "dmType='received',dmStatusFilter='6',complete='yes'"

--send-msg

dbIDRecipient - List of recipient Box ID separated by semicolons. Length of one Box ID is 7 characters. At least one must be specified. [Mandatory]
dmAnnotation - Subject (title) of the message. Maximal length is 255 characters. [Mandatory]
dmToHands - Person in recipient organisation. Maximal length is 50 characters. [Optional]
dmRecipientRefNumber - Czech: číslo jednací příjemce. Maximal length is 50 characters. [Optional]
dmSenderRefNumber - Czech: číslo jednací odesílatele. Maximal length is 50 characters. [Optional]
dmRecipientIdent - Czech: spisová značka příjemce. Maximal length is 50 characters. [Optional]
dmSenderIdent - Czech: spisová značka odesílatele. Maximal length is 50 characters. [Optional]
dmLegalTitleLaw - Number of act mandating authority. Maximal length is 4 characters. [Optional]
dmLegalTitleYear - Year of act issue mandating authority. Maximal length is 4 characters. [Optional]
dmLegalTitleSect - Section of act mandating authority (paragraf). Maximal length is 10 characters. [Optional]
dmLegalTitlePar - Paragraph of act mandating authority (odstavec). Maximal length is 10 characters. [Optional]
dmLegalTitlePoint - Point of act mandating authority (písmeno). Maximal length is 1 characters. [Optional]
dmPersonalDelivery - If true, only person with higher privileges can read this message. Values: {0,1}, default is 1.
dmAllowSubstDelivery - Allow delivery through fiction. Values: {0,1}, default is 1.
dmType - Message type (commercial subtypes or government message). Maximal length is 1 character. Values: {I,K,O,V} [Optional]
dmOVM - OVM sending mode. Values: {0,1}, default is 1.
dmPublishOwnID - Allow sender to express his name shall be available to recipient. Values: {0,1}, default is 0.
dmAttachment - Full path to target files separated by semicolons. NOTE: "Semicolon" is not allowed in attachment path or file name! It can cause failure during parse of parameter string. [Mandatory]

Return

[status] - 0 is success, 1 error.
msgID - print to terminal (stdout) sent message ID.
if an error then error code and its description are writing into stderr.

Example:

datovka --login "username='xxxxxx'" --send-msg "dbIDRecipient='yyyyyyy;zzzzzzz',dmAnnotation='Example',dmPersonalDelivery='1',dmAllowSubstDelivery='1',dmOVM='0',dmPublishOwnID='0',dmAttachment='C:\temp\info.doc;C:\temp\food.doc'"

--get-msg

dmID - Message ID. Maximal length 20 characters. [Mandatory]
dmType - Type of messages. Values: {sent,received}, default is received. [Mandatory]
zfoFile - Full path where message ZFO file will be saved. If not specified, message will be stored only to database. [Optional]
attachmentDir - Full path to folder where attachment files will be saved. If not specified, message will be stored only to database without files saving. Must be terminated by \ or /. [Optional]
download - Values: {yes,no,ondemand}. Specifies whether to download the message from ISDS server (no = never download, use from database if present; yes = always download even if does already exist in database; ondemand = download only if doesn't exist in database). Default is ondemand. [Optional]
markDownload - Set message as locally read. Values: {yes,no}, default is no. [Optional]

Return

[status] - 0 is success, 1 error.
Insert/update message data in the message database and set message as locally read if it was set.
Message ZFO file saved to target path if was set.
All attachment files saved to target path if was set.
if an error then error code and its description are writing into stderr.

Example:

datovka --login "username='xxxxxx'" --get-msg "dmID='123456789',dmType='received',zfoFile='C:\temp\message.zfo',attachmentDir='C:\temp\save\'"

--get-delivery-info

dmID - Message ID. Maximal length 20 characters. [Mandatory]
zfoFile - Full path where delivery info ZFO file will be saved. If not specified, delivery info will be stored only to database. [Optional]
download - Values: {yes,no,ondemand}. Specifies whether to download the message from ISDS server (no = never download, use from database if present; yes = always download even if does already exist in database; ondemand = download only if doesn't exist in database). Default is ondemand. [Optional]

Return

[status] - 0 is success, 1 error.
Insert/update delivery info data in the message database.
Delivery info ZFO file saved to target path if was set.
if an error then error code and its description are writing into stderr.

Example:

datovka --login "username='xxxxxx',password='yyyyyyyy'" --get-delivery-info "dmID='123456789',zfoFile='C:\temp\dinfo.zfo'"

--get-user-info

Return

[status] - 0 is success, 1 error.
Insert/update user info in the account database.
if an error then error code and its description are writing into stderr.

Example:

datovka --login "username='xxxxxx',password='yyyyyyyy',otpcode='zzzzzzz'" --get-user-info

--get-owner-info

Return

[status] - 0 is success, 1 error.
Insert/update owner info in the account database.
if an error then error code and its description are writing into stderr.

Example:

datovka --login "username='xxxxxx',password='yyyyyyyy'" --get-owner-info

--check-attachment

Return

[status] - 0 is success, 1 error.
newMsgIdList - print to terminal (stdout) a list of message IDs separated by white space where attachment missing.
if an error then error code and its description are writing into stderr.

Example:

datovka --login "username='xxxxxx'" --check-attachment

--get-msg-ids

dmType - Type of messages. Values: {sent,received,all}, default is all. [Mandatory]

Return

[status] - 0 is success, 1 error.
msgIdList - print to terminal (stdout) a list of message IDs separated by white space.
if an error then error code and its description are writing into stderr.

Example:

datovka --login "username='xxxxxx',password='yyyyyyyy'" --get-msg-ids "dmType='received'"

--find-databox

dbType - type of databox. Values: {OVM,PO,PFO,FO} [Mandatory]
dbID - id of databox. Must contains string with length 7. [Optional]
ic - identification number of firm/company. Must contains string of numbers. Maximal length is 8. [Optional]
firmName - name of firm/company. Minimal length: 3 chars; maximal length: 50 chars. [Optional]
pnFirstName - first name of databox owner. Minimal length: 3 chars; maximal length: 50 chars. [Optional]
pnLastName - last name of databox owner. Minimal length: 3 chars; maximal length: 50 chars. [Optional]
adZipCode - zip code of databox owner address. Must contains string of numbers with length 5 without space. [Optional]

NOTE: at least one optional parameter must be specified for this service

Return

[status] - 0 is success, 1 error.
databoxInfo - print to terminal (stdout) information about databox if success.
if an error then error code and its description are writing into stderr.

Example:

datovka --login "username='xxxxxx'" --find-databox "dbType='OVM',ic='12345678'"

datovka --login "username='xxxxxx'" --find-databox "dbType='FO',pnFirstName='Petr',pnLastName='Novák',adZipCode='61200'"