CLI Device Replicator

This external utility is used for device replication from files into the internal YSoft SafeQ Management Service database.

At a Glance

See YSoft Shell for information on how to run shell.

CLI Device Replicator

The command for replicator is "device replicate".

The device replicator has these parameters:

  • --username Name of the user connected to the rest service (administrator user name)

  • --password User password

  • --tenant Tenant domain identification (if not set, the default value is 'tenant_1')

  • --host URL of YSoft SafeQ Management Service (if not set, the default value is https://localhost The port number may be omitted as well, default is 80)

An example of command line arguments

images/download/attachments/160784349/image2018-2-27_12-37-16.png

With the parameters above, the .bat file for fast run can be created:

call "c:\SafeQ6\Management\utilities\Import tool\import_tool.bat" device replicate --username admin --password admin --tenant tenant_1 --host https://localhost

The following steps are needed to enable CSV file replication:

  1. Configure the replication source directory by editing the deviceReplicationDir configuration property through System Settings. Usually, it is an absolute path on the local computer.

    An example of a root folder for replication files

    images/download/attachments/160784349/image2018-11-7_11-24-5.png

  2. Configure the incrementalDeviceReplication property—if disabled (default), the replicator will delete all devices created by the previous replication. If enabled, the replicator will only update existing devices.

  3. Configure sending emails when replication fails—see Replicator e-mail configuration page.

  4. Create CSV files according to the structure described in the next chapter. Use UTF-8 for CSV file encoding.

  5. Start the replicator by running the command line (for its parameters, see above).

  6. For regular synchronization with the CSV file, schedule the import via system scheduled tasks.

  7. Information about replication results will be saved into the log file (ysoft-shell.log) stored next to the import_tool.bat file.

Supported file formats: CSV (separated with ';'), Microsoft Excel (XLS and XLSX).

File Structure

  • Before replication, the respective files must be stored in the directory according to the configuration (see above).

  • These files must be stored in the format shown below. The files are processed in alphabetical order based on their names. (For replication, only some of them may be used.)

  • Optional values may be left blank. In this case, they will be obtained from the device template

  • All names are "case-sensitive", i.e., small and capital letters are distinguished. Example: group "default" is not the same as "Default".

Format of a row - single item entry

<device name>;<spooler controller group name>;<template unique ID>;<network address>;<device group name>;[direct queues];[reporting cost center number];[location or description];[Equipment ID];[Service Agreement ID];[Contact person];[ZIP code];[terminal network address];[terminal serial number]

Column specification

  • Device name – the name of a device. This parameter does not have to be unique in the device group. If device name is not specified, the device will not be replicated.

  • Spooler controller group name – name of a spooler controller group to which the device will be assigned. If no group exists or specified group does not exist then device will not be replicated.

  • Template unique ID – ID of device template from which the values not specified in the CSV file will be taken. All missing parameters (in the case of a new device) are taken over from it. If the template does not exist or is not specified, the device will not be replicated.

  • Device network address – the network address must be unique. If the device network address is not specified or is not unique, the device will not be replicated.

  • Device group name – the name of a device group to which the device will be assigned. If no group exists or the specified group does not exist, the device will not be replicated.

  • Direct queues – if the value is filled out, then direct queues will be assigned to the device. If updating the device, then all previously assigned direct queues will be removed and newly specified queues added. The individual names must be separated by commas (if multiple queues are to be assigned). The direct queue must be unique within all of YSoft SafeQ. If a device with the same direct queue exists, the new device will not be replicated.

  • Reporting cost center number– the cost center to which the device will be assigned if the value is specified. In the case of a new device, if the value is incorrect (the cost center has already been deleted or renamed) or the value is not specified, the value is taken from the template. If no such cost center number exists (the cost center in the template is also incorrect), the device will not be replicated.

  • Location or description description – a description of the device. If no value is specified, then the value from the template is taken (in the case of a new device).

  • Equipment ID – the equipment number of the device. If no value is specified, then the value stays empty.

  • Service Agreement ID – the maintenance contract number. If no value is specified, then the value stays empty.

  • Person to contact – the n ame, email, or phone number of the contact person. If no value is specified, then the value from the template is taken (in the case of a new device).

  • ZIP code – the zip code of the city where the device is. If no value is specified in the CSV file, then the value from the template is taken (in the case of a new device).

  • Terminal network address - the network address of the terminal. If the terminal network address is not specified, device network address is used. It's possible to alter value only for Terminal Professional version 4 terminal type.

  • Terminal serial number - the serial number of Terminal professional 3.5, Terminal ultralight or Cloud terminal. In the case of a Cloud terminal, the serial number must be unique and this value cannot be changed via replicator if the cloud terminal is already successfully installed.


There are two types of item in the row format prescription:

  • items in "< >" are required

  • items in "[ ]" are optional

Sample row:

Printer24;Spooler1;zQhcyz3dxa;10.0.10.12;MFDs;;0;Corridor B, near kitchen;;125498541000454;;;10.0.10.12;SQPR12345678900

If replicated devices use an embedded terminal, admin will have to install the embedded terminal manually after replication. The embedded settings are preconfigured, and admin just has to click the reinstall button in the device settings or the special page where all terminals can be reinstalled.