Upgrade the Semarchy xDI Designer

This document provides instructions to upgrade Semarchy xDI Designer.

Pre-Upgrade Steps

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

Review the Release Notes

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

System Requirements

Review the system requirements for this release.

Semarchy xDI Designer 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.

Close the Designer

Before upgrading, completely close the Designer environment:

  1. Stop the local runtime.

  2. Close all editors.

  3. Exit Semarchy xDI Designer.

Backup your Installation

Perform a backup of your current installation of Semarchy xDI Designer:

  1. Make a zip archive of the current Semarchy xDI Designer installation.

  2. Make a zip archive of your workspace(s).

Upgrade the License Server

Semarchy xDI Designer 2023.1.x can only receive its license from a local License Server running version 5.3 or higher.

If you are using a local License Server in your configuration, make sure to upgrade that license server before upgrading Semarchy xDI Designer.

Get a Compatible License Key

Semarchy xDI Designer 2023.1.x requires a 5.3.x or 2023.1.x compatible license key.

If upgrading from a Designer version older than 5.3.x, contact the Semarchy support or your account representative to get a compatible license key.

Upgrade Steps

Download and Install the New Version

Download and install the new version of Semarchy xDI Designer from the Semarchy website.

Do not install the new Designer version on top of an existing one. It is recommended to back up and remove the previous version, or rename it prior to installing the new one.

Copy Modules

Before the first startup, copy the Modules folder from the previous installation to the new one:

  • Under Windows/Linux: the default folder for Modules is <Designer root folder>/runtime/modules.

  • Under macOS: the default folder for Modules is <Designer root folder>/Contents/Eclipse/runtime/modules.

Run the New Version

Perform the following operations for the first startup of the new version:

  1. Start the new version of Semarchy xDI Designer (see instructions for Windows, Linux, macOS).

  2. Select the workspace directory and click Launch.

  3. Review and accept the License Terms, and then click Finish.

  4. The Register License dialog opens.

    • If you are using a local license key:

      1. Select the License Key File option.

      2. Click the Browse button next to the License Key File field to select the local key file.

    • If you are registering through an on-premises license server:

      1. Select the Local License Server option.

      2. Enter the License Server URL and the License Key.

    • If you are registering through the Semarchy License Server:

      1. Select the Semarchy License Server Option.

      2. Enter your License Key.

        Refer to Manage the Designer License for more information on license modes.

  5. Click Register.

  6. On the Welcome Page, click Hide to show the design environment.

  7. Launch the Rebuild Cache and Clean Projects operation from the Utilities menu.

Re-Install Components

To re-install components, follow the procedure described in Install Components and restart the Designer when you are prompted to.

When the Designer restarts, all Modules copied from the previous installation are automatically updated with the latest version included in the related component (if any).

Re-install other Plugins

If needed, re-install any other plugin used by the previous installation (version control system or other).

Finalize and cleanup

Perform the following operations to finalize the upgrade:

  1. In the Modules Manager check that all modules have been migrated successfully.

  2. Follow the Post-Upgrade Steps.

  3. Remove the old installation folder.

A workspace that has been opened with a newer version of Semarchy xDI Designer should not be re-opened with a previous version of Designer.

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 S19 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.

Upgrading from Versions Before 2023.1.0

If you are using the command-line script to run Designer commands, adapt the command used to run your scripts with the new Designer CLI syntax, which replaces the legacy java -jar …​ method.

Upgrading from Versions Before 5.3.0

Upgrade all workspaces by starting Designer from a command line interface command line with the -clearPersistedState option, for each of the workspaces running a Designer version before 5.3.0.

Starting with version 5.3.0, the license key contains permissions to components and features. If you notice issues such as unexpectedly disabled components and features, please contact Semarchy.

Upgrading from Versions S17, S18 or S19

Follow the upgrade steps of all the major intermediate versions.