This page contains a detailed update procedure for updating the Dispatcher Paragon installation to a higher build.

The Dispatcher Paragon version was previously known as Dispatcher Paragon MUXX (Maintenance Update XX). We are changing naming, MU will be replaced with Build so the Dispatcher Paragon version will be known as Dispatcher Paragon Build XX. This page contains mixed naming as Dispatcher Paragon versions older than Build 32 are still referred to as MUXX.

Before the Update

Expected System Outage

  • It is expected that the system will be out of order until the update is finished.

Expected Data Loss

  • If executed as documented, no data loss is expected.
  • In the case of a rollback, the data between step 1.5 (database backup) and Rollback is lost. Users will need to reprint their jobs once the system is operational again.

General Requirements

  • When updating to a new build, all installed components (Dispatcher Paragon Management Servers, Dispatcher Paragon Spooler Controllers, Dispatcher Paragon FlexiSpoolers, Dispatcher Paragon Mobile Print Server, Dispatcher Paragon Workflow Processing Systems, Dispatcher Paragon Payment System, and Dispatcher Paragon Payment System plugins) have to be updated.
  • If one or more Dispatcher Paragon services have the state Disabled, enable them before starting. If necessary, you can disable them again once the update is finished.
  • Make sure that no processes or services (e.g., from third-party backup tools) are using resources from the Dispatcher Paragon directory. Files in those directories are about to be replaced and if they are locked by any process, the update will fail. A common cause of an update failure is having pgAdmin running while updating or uninstalling Management Server with an embedded PostgreSQL.
  • Make sure that the pgAdmin4 server is shut down
  • Make sure that you have enough free space on disk in case of the PostgreSQL 11 update. Two new copies of PGSQL and PGSQL-data folders will be created for the update process.
  • Make sure the server hosting Dispatcher Paragon still fulfills the minimal requirements for the new version (such as OS version, see Dispatcher Paragon server requirements)

Stop Dispatcher Paragon Services

  1. Stop all Dispatcher Paragon services in the whole environment (Management Servers, Site Servers) except the following (leave the services listed below running):

    1. Dispatcher Paragon Bundled PostgreSQL (available if an embedded PostgreSQL DB is used)

    2. pgAdmin4

Backing Up Databases

Back up the SQDB6 and SQDB6_IMS databases. If you are using a separated database for the data warehouse, also back up SQDB6_DWH. If you are using Dispatcher Paragon Payment System, back up the SQDB6_YPS database too.

See Backup of Databases for detailed instructions.

Backup Configuration Files

If you are using some local changes in your configuration files - for example, because of using some customizations, extensions, or applying your own security rules be aware to make a backup of your configuration files before the update.

See Backing Up Configuration and Binary Files and perform the procedure on all Management and Site Servers.

Create a Snapshot (Optional but Recommended)

If you have Dispatcher Paragon installed on virtual servers, create a snapshot of all Management and all Site servers to simplify the rollback procedure. Snapshots should be made with all Dispatcher Paragon servers being stopped completely or at least services stopped on all servers, as described above.)

Updating Procedure

Checking MS SQL Server Database Snapshot Isolation state

If you are using the PostgreSQL database, then please skip this part and go to the section Update Management Servers.

If you are using MS SQL database and if you are updating from Dispatcher Paragon MU23 or earlier or if the MS SQL Dispatcher Paragon databases were created manually (i.e. not by Dispatcher Paragon installer), then snapshot isolation needs to be enabled manually.

If the Payment System is in use, then snapshot isolation needs to be enabled for its database manually (if you did not do so before).

How to check snapshot isolation current state

  1. Connect to the SQL Server and run the following query:

    SELECT name, collation_name, state_desc, snapshot_isolation_state_desc, is_read_committed_snapshot_on, recovery_model_desc, containment_desc, is_trustworthy_on FROM sys.databases WHERE name like '%SQDB6%'
  2. If you see that snapshot_isolation_state_desc is OFF for Dispatcher Paragon databases, then please continue with the next section.

How to set up the database

  1. If the database name does not equal SQDB6, please change the name according to the end customer configuration. Connect to SQL Server and run the following commands:

    ALTER DATABASE [SQDB6] SET ALLOW_SNAPSHOT_ISOLATION ON
    ALTER DATABASE [SQDB6] SET READ_COMMITTED_SNAPSHOT ON
     
    ALTER DATABASE [SQDB6_IMS] SET ALLOW_SNAPSHOT_ISOLATION ON
    ALTER DATABASE [SQDB6_IMS] SET READ_COMMITTED_SNAPSHOT ON

  2. If the end-customer environment has a separate database for the data warehouse, reconfigure it as well:

    ALTER DATABASE [SQDB6_DWH] SET ALLOW_SNAPSHOT_ISOLATION ON
    ALTER DATABASE [SQDB6_DWH] SET READ_COMMITTED_SNAPSHOT ON

  3. The same applies to the Payment System database if Payment System is in use:

    ALTER DATABASE [SQDB6_YPS] SET ALLOW_SNAPSHOT_ISOLATION ON
    ALTER DATABASE [SQDB6_YPS] SET READ_COMMITTED_SNAPSHOT ON

    See Microsoft documentation of Snapshot Isolation in SQL Server for more information.

Update Management Servers

For other types of installations see Updating Using the Server Installer for detailed instructions.

On some systems, the following issue may appear: during installation of the Dispatcher Paragon Workflow Processing System, the service is "marked for removal". In the Workflow Processing Server install log (<install_dir>\WPS\WPS-install.log), there is an error saying that the service is already installed, and after restarting, the service is removed. If you encounter it, let Customer Support Services know about it. A workaround is to install the service manually after the restart by running WpsService.exe install from the elevated command line.

Re-activate the Dispatcher Paragon license

Re-activate the Dispatcher Paragon license once the update of Management Server(s) is finished. See Management Interface - License Activation for detailed instructions.

Additional steps

If you want to change any Dispatcher Paragon configuration, you can do it now in System > Configuration.

If you are using the Management Server cluster which replicates users from secured LDAP and you are updating from Dispatcher Paragon Build34 or earlier, make sure that the LDAP server certificate is imported in trust store on all Management Server nodes. Any node can start scheduled LDAP replication now.

You should verify LDAP replication functionality by testing replication from the Dispatcher Paragon management interface of each node:

  • System > LDAP integration > Test tab > TEST SETTINGS button

If you are using failover/load balancing of terminals and updating from Dispatcher Paragon MU27 or earlier, make sure that enableNetworkLoadBalancer property is enabled in Dispatcher Paragon settings:

  1. Log in to the Dispatcher Paragon management interface with sufficient rights to administer printers (for example, "admin").
  2. Go to System > System settings
  3. Set enableNetworkLoadBalancer property to enabled and save the configuration.


Updating Site Servers

See Updating Using the Server Installer for detailed instructions.

If you are using a third-party load balancer:

  1. If you are updating from Dispatcher Paragon MU28 or earlier, make sure that scanServerIp is configured in TerminalServer.exe.config on each node:
    1. Edit the file <install_dir>\SPOC\terminalserver\TerminalServer.exe.config.

    2. Into the AppSettings section of the config file add a new scanServerIp parameter and set it to the physical IP address of the local TS node. 

      <add key="scanServerIp" value="physical_IP_address" />
    3. Save the file.
    4. Restart Dispatcher Paragon Terminal Server services to apply the settings
  2. And you are updating from Dispatcher Paragon Build 37 or earlier to Build 38 and higher:
    1. Due to the security patch of the Dispatcher Paragon Spooler Controller Group Service, the service does not answer on TCP-based port 9999 anymore and thus all your servers will be considered down by the load balancer.
    2. The recommended solution is to change the configuration of the load balancer and to remove the monitoring of port 9999.
    3. Alternative solution is to change value of the system parameter spocJmxNetworkInterface to 0.0.0.0 (default is 127.0.0.1).
      1. Please note that such configuration decreases the security of the system and is not recommended!


If you are using Dispatcher Paragon Payment System and you are updating from Dispatcher Paragon Build 43 or earlier:

From Build 44 the system property terminalServerListeningAddress is set to the tcp://127.0.0.1:5556 for security reasons. With this setting Dispatcher Paragon Spooler Controller will not answer to calls made against the real server address, which may cause inability of Dispatcher Paragon Payment System to load the configuration and to function well.

If you face issues with accessing the Payment System website after the update, the recommended solution is:

  • if the Dispatcher Paragon Payment System runs on the same server as Dispatcher Paragon Spooler Controller
    • edit <Dispatcher Paragon Payment System>\ps-conf\environment-configuration.properties and set the SPOC address as follows:
      safeq.authentication.address=tcp://127.0.0.1:5556
    • restart Dispatcher Paragon Payment System service
  • if the Dispatcher Paragon Payment System runs on a server without Dispatcher Paragon Spooler Controller
    • edit <SPOC>\conf\modules\spoc.conf and add this line at the end of file:
      terminalServerListeningAddress=tcp://<physical_IP_accessible_from_payment_server>:5556
    • restart Dispatcher Paragon Spooler Controller service

The Dispatcher Paragon Spooler Controller cache recovery mechanism on a standalone SPOC with the recommended hardware is processing on average 3000 jobs per minute. That means with 60 000 jobs the recovery will take about 20 minutes. SPOC is not fully functional until the recovery is finished. To see how many jobs is going to be recovered use the following SQL query:

-- query to be launched on SQDB6 database
-- use proper tenant prefix at smartq_jobs table
-- use proper server_guid, SPOC guid can be found on Dispatcher Paragon management interface -> tab Spooler Controller groups
SELECT count(1) FROM tenant_1.smartq_jobs where server_guid = 'j1dvczklt5l5hm69' and cur_status in (1,2,4,8,16,32,64,128,256,512)


End User Interface

If you use a custom configuration in the <install_dir>\SPOC\EUI\conf\server.xml, review the sc-install.log for possible issues with the update of server.xml. The update process tries to merge the old configuration with the new one. In some cases the merging is impossible and a new server.xml is generated, in such a case it is needed to do the custom configuration again based on the current documentation. The old file is available for manual review in the same folder with the name server.xml.bak .

Starting from Build 39 the generated Terminal Server certificate was changed from self-signed to certificate signed by Certification Authority.
In case the certificates need to be refreshed, remove these files SafeQTerminalServer.pfx and SafeQTerminalServer.crt found in the following path: <install_dir>\SPOC\terminalserver\Certificates\ prior to updating. In the case of Build 38 or earlier only SafeQTerminalServer.pfx will be present. After updating both of the aforementioned certification files should be created again.

Updating Other Products

Updating SafeQube 2

See Updating YSoft SafeQube 2 for detailed instructions.

Updating Terminals

See Updating Terminals for detailed instructions.

After update steps

After a successful update, don't forget to apply back your local changes (if you are using any) of configuration files from their backups (made in point Back Up Configuration Files).

Verifying the Functionality

Verify the basic functionality such as Printing, Copying, Scanning, Accounting, and Charging.

Rollback

Should you face issues during or after updating that block you from using Dispatcher Paragon, revert to the version prior to the update.

If a Snapshot of Servers Is Available

  1. Stop Dispatcher Paragon services on all Management and Site Servers.
  2. If an external database server is being used, restore the Dispatcher Paragon databases SQDB6, SQDB6_IMS, SQDB6_DWH, SQDB6_YPS to the state prior to the update.
  3. Revert Management Servers to the state prior to the update (one by one).
  4. Re-activate the Dispatcher Paragon license.
  5. Revert Site Servers to the state prior to the update.

If a Snapshot of Servers Is Not Available

  1. Stop Dispatcher Paragon services on all Management and Site Servers.
  2. Uninstall Management and Site Servers.
  3. Delete all Dispatcher Paragon folders.
  4. Perform a clean installation of Management Server(s) of the previous Dispatcher Paragon version – use the same Local GUID that was used before.
    1. Restore Dispatcher Paragon databases.
    2. Restore the configuration files from backup – do not restore the file safeq.properties, keep the new one.
  5. Re-activate the Dispatcher Paragon license.
  6. Perform a clean installation of Site Servers.
    1. Restore the configuration files from backup.
  7. If you were using custom certificates (e.g., for Web Interface or Terminal Server), set them up again according to the documentation.

Troubleshooting

Device Is Unable to Establish a Secure Connection with Terminal Server in MU17 and Newer, Although It Worked with the Previous MU

A new, more secure certificate was introduced with MU17. Older devices may be unable to establish a secure connection with the Terminal Server.

Solution: Generate a new certificate compatible with the device and configure Terminal Server to use it. See Configuring secured connection between terminals and Terminal Server for detailed instructions.

FlexiSpooler Installation is Stuck During the Update

Installation is stuck on installing FlexiSpooler during the update without any obvious error. In installation log is the following exception: Exception calling "DeserializeObject" with "1" argument(s): "Unrecognized escape sequence."

Solution: Open the spooler.config and ensure that there are only forward slashes in jobStorePath. (e.g., change "jobStorePath":"<install_dir>\Spool\JobStore" to "jobStorePath":"<install_dir>/Spool/JobStore").