The YSoft SafeQ 5 to YSoft SafeQ 6 Upgrade Tool

The YSoft SafeQ 5 to YSoft SafeQ 6 upgrade tool is intended for completely upgrading YSoft SafeQ 5 to YSoft SafeQ 6. This tool runs automatically Installing YSoft SafeQ 6 Server from the Server installer, but if the upgrade process fails, it can also be run manually.

Under the hood, it runs the database procedures and imports a special Rule-based Engine file to migrate data from the older version to the newer one.

Please note that in case the embedded PostgreSQL database is used in a time zone other than GMT, the following workaround to the known limitation must be applied.

Configuring the PostgreSQL Time Zone for Correct Print Job and Report Data

Overview

The upgrade tool drives the whole process of an upgrade from YSoft SafeQ 5 to YSoft SafeQ 6. It runs a set of upgrade steps, checks their results, and decides if the next step runs or the upgrade process aborts. The main purpose of the upgrade process is to migrate the database. The migration is divided into particular steps that have to be run in a set order. If any step fails, the migration process aborts, data from the particular step rolls back, and the manual intervention of an administrator is required. The administrator can check logs (and the upgrade report) and decide if the upgrade process can be continued by ignoring the step's result or whether the whole step can be skipped. Ignoring the step result means that the step is processed, data is probably partially migrated, and the execution of the next steps can be attempted. When the step cannot be finished due to technical reasons, the step can be completely ignored, but the administrator must explicitly exclude the step after careful consideration.

Prerequisites

  • Java (minimal version Java 11) must be installed on the server with the YSoft SafeQ 5 to YSoft SafeQ 6 upgrade tool (alternatively, configure the JAVA_HOME system property and path to the upgrade tool in <SAFEQ6_HOME>/Management/upgrade/sq5-upgrade-tool.bat if it is not configured automatically by the installer).

  • Installed YSoft SafeQ 6 (fulfilled by the installer).

  • Restored/visible original databases from YSoft SafeQ 5 as the data source, typically SQDB5 and SQDB5_SQDW. A new database for YSoft SafeQ 6 must be prepared as the data target. These prerequisites should be fulfilled by the installer.

  • The upgrade tool must be configured before the first run—so all properties in <SAFEQ6_HOME>/Management/upgrade/conf/sq5-upgrade-tool.properties must be filled (the installer will set the configuration automatically, but they can be changed).

  • Database engines of both old and new installation must aligned (PostgreSQL→ PostgreSQL, MS SQL→MS SQL). Migration between database engines is not supported.

Configuration properties (with example values):

  • YSoft SafeQ 6 section - the installed upgraded version

    • sq6.configuration.file = c:/SafeQ6/Management/conf/safeq.properties - Path to Management Service configuration file.

    • sq6.database.tenantDomain = tenant_1 - Tenant domain name where data from the older version of YSoft SafeQ will be migrated.

    • sq6.localSpoolerController.guid = <GUID> - Generated unique ID of the Spooler Controller if it is presented on the same server as Management Service. This value can be empty if at least one ORS server exists in the upgraded YSoft SafeQ 5.

    • sq6.localSpoolerController.network.address = <network addres> - Network address of the Spooler Controller if is presented on the same server as Management Service. This value can be empty if at least one ORS exists in the upgraded YSoft SafeQ 5. If the sq6.localSpoolerController.guid property is filled, it must also be filled.

  • YSoft SafeQ 5 section - the installed version to upgrade

    • sq5.rbeRules.file = c:/SafeQ5/conf/rools.drl - Path to RBE rules file.

    • sq5.database.host = 127.0.0.1 - Database host.

    • sq5.database.name = SQDB5 - Name of the database.

    • sq5.database.dwh.name = SQDB5_SQDWH - Name of the warehouse database.

    • sq5.database.port = 1433 - Port of the connection to the database.

    • sq5.database.username = username - Database user name.

    • sq5.database.password = *** - Database password.

Each time the upgrade tool is reconfigured, it must be restarted.

The properties sq5.database.username, sq5.database.password, sq5.database.host, sq5.database.port are ignored in the case of the MSSQL database because YSoft SafeQ 5 databases must be on the same database machine and credentials for YSoft SafeQ 6 are used instead. The properties must, however, still be set even if they have no effect (this is a known limitation of the upgrade tool).

How to Run

The Management Service and other services connected with YSoft SafeQ must be stopped before the upgrade runs.

Run the upgrade tool shell with <SAFEQ6_HOME>/Management/upgrade/sq5-upgrade-tool.bat and then run the required shell command (for supported commands, see next, run help for list of possible commands, or see documentation at Spring shell documentation page)

Run the upgrade tool shell with the required command immediately— run <SAFEQ6_HOME>/Management/upgrade/sq5-upgrade-tool.bat <command>

The upgrade can take time depending on the size of the database (especially based on, e.g., the number of devices, jobs in reports, etc.).

After Running

See the console output and also the log files and upgrade report.

These are the possible results of running the upgrade tool (in the console or log output):

  • SUCCESS - the upgrade process ended successfully with nothing to solve.

  • WARNING - the upgrade process ended successfully but has changed the system configuration (by design). It is strongly recommended to review the changes and adjust them to match business requirements.

  • FAILED - there were some critical problems during the upgrade process that must be solved with support.

  • Because of upgrade does not solve licensing of migrated devices and entities in general, there can be the notification that re-licensing of the product is necessary for Management Service notifications (after administrator signs in). Reactivation must be done within 10 days after upgrade otherwise the devices can be removed from the system. Also, devices will not work until reactivation because of technical limitations. See how to activate new license after upgrade.

  • Check in general that migrated data are as expected.

  • If YSoft SafeQ 6 manages printing devices, all device terminals must be reinstalled (use Devices > Printers > select all devices > Actions > Reinstall terminal). After re-installation check that devices working properly.

The "Upgrade" Command

The command for running the whole upgrade is: upgrade

The upgrade command has optional parameters:

  • --ignore-steps-result - A comma-separated list of step names that result will be ignored during the upgrade (i.e., when the step fails, the upgrade can continue to the next step).

  • --ignore-steps - A comma-separated list of step names that will be ignored during the upgrade. Use this option as the last possibility to continue with the upgrade only when the consequences the of the ignored step are well known.

Example of command line arguments

upgrade --ignore-step-result TENANT.DEVICES,DWH.STATS --ignore-steps TENANT.COMMON


images/download/attachments/160480292/image2017-1-18_11_15_5.png

Steps names have to be in the format <upgrade scheme>.<upgrade step>

Allowed upgrade schemes:

  • CLUSTER - scheme for cluster management steps loaded automatically for the "tenant_1" database scheme

  • TENANT - scheme for upgrading the tenant database

  • DWH - scheme for upgrading the tenant's warehouse database

Allowed upgrade steps:

  • INITIALIZE: This step creates database entities for migration and cleans logging tables.

  • COMMON: This step prepares common data for migration (id conversion tables).

  • POOL: This step migrates data about a file pool to be deleted.

  • CONFIGURATIONS: This step migrates the system/tenant configuration.

  • USERS: This step migrates users data.

  • DEVICES: This step migrates devices data, including terminals.

  • DEVICE_TEMPLATES: This step migrates device templates data, including terminal templates.

  • QUEUES: This step migrates queues data.

  • PRICELISTS: This step migrates price lists data.

  • PROJECTS: This step migrates billing codes data.

  • JOBS: This step migrates jobs data.

  • STATS: This step migrates the metadata of reports (web reports, management reports, scheduled reports to email and file, ...).

  • REPORTS: This step migrates reporting data.

  • RBE_RULES: This step migrates the RBE data file into the database.

  • SCAN_WORKFLOWS: This step migrates scanning workflows.

See a detailed step description for more information about particular steps.

The "Rules Import" Command

The RBE rules import is a part of the upgrade process, but the import can be run separately with the command: rule import

The rule import command has an optional parameter:

  • -- file The path to the YSoft SafeQ 5 RBE rules file to import. If this option is not set, the default file from the upgrade tool's configuration is used.

Example of command line arguments

rule import --file C:/path/rbe.drlimages/download/attachments/160480292/image2017-1-18_11_26_23.png

The Upgrade Tool File Structure and Logs

The <SAFEQ6_HOME>/Management/upgrade structure:

  • /bin - The folder with necessary binaries for internal purposes

  • /conf/

    • sq5-upgrade-tool.properties - Configuration of the upgrade

    • log4j2.xml - Configuration of the logging (the upgrade tool must be restarted when the configuration changes)

  • /lib - Necessary libraries for internal purposes

  • /logs - The folder with the log files

    • upgrade-tool.log<timestamp> - The log with technical notes from run

    • upgrade-tool-history.log - A history of commands

    • sq5-upgrade-tool-rbe-rules.log<timestamp> - The extracted results of the RBE rules import

    • Upgrade-report-<timestamp>.xlsx - A report of the upgrade (a steps overview with details for each step)

  • sq5-upgrade-tool.bat - The main runner of the upgrade tool