Upgrade the Semarchy xDI Runtime

This document provides instructions to upgrade the Semarchy xDI Runtime.

Pre-Upgrade Steps

This section describes the operations to perform before upgrading Semarchy xDI Designer.

Review the Release Notes

The Release Notes provides the latest information about the Semarchy xDI Release, including new features, bug fixes, and breaking changes.

System Requirements

Review the system requirements for this new release.

Runtime 2023.3 and above requires a JDK 17. If you are using an older version, upgrade to JDK 17. The supported Java versions are listed in the system requirements.

Stop the Runtime

Stop the current Runtime if it is running.

Backup the Runtime

Upgrade Steps

Get and Install the Runtime

  1. Download the new version of the Semarchy xDI Runtime from the Semarchy website.

  2. Uncompress the downloaded file and move the content to a new installation folder.

  3. Check and set the execute permission on all the .bat (Windows) and .sh (Linux or macOS) scripts located at the root of the new installation directory.

  4. Replicate the read/write permissions for other files from the previous installation folder. In particular, check and set write permissions for the following sub-directories:

    • ./temp

    • ./build

    • ./sessions

  5. Copy the content of the following folders from the previous Runtime installation to the new installation:

    • ./build/deliveries

    • ./build/packages

    • ./scheduler (if you are using the Runtime’s scheduler)

    • ./sessions (if you use the Runtime’s internal log database)

    • ./temp (if your Processes store specific files in this directory)

Copy Modules

Copy the Modules from the previous installation to the new installation folder.
In the default configuration, Modules are in the ./modules sub-folder of the Runtime installation folder.

Configure the Runtime

Configure the new Runtime based on the previous Runtime’s configuration.

When upgrading the Semarchy xDI Runtime to version 2023.x, you should pay attention to the following points:

  • Support for the RMI protocol has been discontinued, and RMI-related parameters have been removed or renamed. See the Release Notes for more details.

  • JDBC Connection management and pooling have been reviewed and certain parameters have changed. See the Release Notes for more details.

  • A new user role named ExecuteAPI is added to run deliveries through the API endpoints and the Execute loses this privilege. If running deliveries through the REST or SOAP API, make sure to configure users with the new role. See Configure Authenticated Access and the Release Notes for more details.

  • Semarchy xDI Runtime now uses Log4J2 for logging. If you customized the previous Log4J1 configuration, adapt it to the Log4J2 configuration format. See Migrating Logging Configurations to Log4J2 format for more details.

  • The Java Management Extensions (JMX) is now disabled by default. See Java Management Extensions (JMX) Variable for more details.

  • Runtime Access Restriction configuration is now forbidden by default when using HTTP instead of HTTPS. See Access Restriction Configuration for more details.

  • The Semarchy xDI Runtime built-in H2 database is now, by default, only accessible from the runtime itself. See Built-in H2 database.

  • The Semarchy xDI Runtime built-in H2 database default user and password have changed. If you want to keep using your previous H2 log and scheduler database data, see Built-in H2 database.

  • The Semarchy xDI Runtime scheduler configuration is now defined in the main runtime configuration file engineParameters.xml instead of the standalone engineScheduler.properties file, which has been removed. See Runtime Scheduler.

Update the Scheduler Database

If you upgrade from a version before 2023.1.0, and you are using the Semarchy xDI Runtime Scheduler, you must manually update the Scheduler database before starting the upgraded Semarchy xDI Runtime.

The database structure has changed following an upgrade of the third-party library used for the Scheduler, which requires an update of the database structure.

Start the New Runtime

Start the new Runtime.

Post-Upgrade Steps

Depending on the version of Semarchy xDI from which you upgrade, you need to perform actions after the upgrade procedure.

The actions are listed incrementally, please read all the sub-sections in this document until you reach your current Semarchy xDI product version. If no action is indicated in this document for your versions, then no specific action is required.

For example, when upgrading from S17 to 2023.1.x, install version 2023.1.x and follow the upgrade steps for S20, for 5.3.x, then for 2023.1.x.

Generic Steps

Once you have validated the new Runtime is running properly, perform the following operations:

  1. Remove the old Runtime folder.

Upgrading from Versions Before 2023.2.0

The thread count for the runtime scheduler thread pool was changed from 50 to 3. If you are copying over a configuration, make sure you are not using the old value.

In the new engineParameters.xml file, this number is found with the org.quartz.threadPool.threadCount parameter.

Upgrading from Versions Before 2023.1.0

If you are upgrading from a version before 2023.1.0:

  • Switch from RMI to HTTP:

    • Replace all connections to the Semarchy xDI Runtime from RMI to HTTP protocol.

      • Replace rmi(s)://hostname:port with http(s)://hostname:port in all applicable locations.
        If you were accessing the runtime without specifying the protocol, HTTP is now the default protocol used. In this situation, you only need to change the port.

      • Replace the RMI port with the HTTP port. The default port for HTTP is 42200.

    • Fine below a list of the Semarchy xDI locations where this must be changed:

  • Update Jython scripts:
    The default Jython third-party library shipped with Semarchy xDI Runtime has been upgraded.

    • The related jythonVersion Runtime parameter has been commented by default for the Runtime to use the shipped version by default.

    • The new Jython version shipped replaces the javos with the os module. Scripts using that module must be updated accordingly.

Upgrading from Version S17

If you are upgrading from version S17, follow the upgrade steps of all the major intermediate versions between your version and 2023.1.x version.

Appendix

Update the Scheduler Database Structure

Summary

If you upgrade from a version before 2023.1.0, and you are using the Semarchy xDI Runtime Scheduler, you must manually update the scheduler database before starting the upgraded Semarchy xDI Runtime.

The database structure has changed following an upgrade of the third-party library used for the Scheduler, which mandates a manual update of the database structure.

The procedure differs if you are using the built-in H2 database or an external database.

Update the built-in H2 Scheduler database

If you are using the default, built-in H2 scheduler database:

  1. Stop the Runtime.

  2. Back up the scheduler database by copying or making a zip archive of the ./runtime/scheduler folder.

  3. Open the Semarchy xDI Runtime configuration file engineParameters.xml and set to false the launchSchedulerEngine parameter. This allows starting the Runtime with the scheduler off.

  4. Start the Runtime.

  5. Update the built-in H2 scheduler database by running the SQL script runtime/scripts/scheduler/upgrade/2023.1.0/upgrade_tables_h2.sql.
    Run this script on the H2 built-in database using Semarchy xDI Designer or an external query tool, with the following connection settings:

    • JDBC URL: jdbc:h2:file:scheduler/internalDb;SCHEMA=SCHEDULER

    • JDBC User: sa

    • JDBC Password: <no password>

    • Schema: SCHEDULER

  6. Stop the Runtime.

  7. Open the Semarchy xDI Runtime configuration file engineParameters.xml and set the launchSchedulerEngine parameter to true.

  8. Start the Runtime.

Update an External Scheduler database

If you are using an external Scheduler database:

  1. Stop the Semarchy xDI Runtime.

  2. Back up the database.

  3. Update the database by running the SQL script corresponding to your provider. The scripts are located in runtime/scripts/scheduler/upgrade/2023.1.0/upgrade_tables_<database-provider>.sql.

    Run this script on the H2 built-in database using Semarchy xDI Designer or an external query tool.