Upgrade the Semarchy xDI Designer

This document provides instructions for the upgrade of Semarchy xDI Designer.

The following procedure describes the steps to upgrade from 20.x or 5.3.x to 5.3.y. For other upgrade scenarios, refer to this article.

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 and bug fixes.

System Requirements

Review the system requirements for this release.

Semarchy xDI Designer 5.3 requires a JDK 11.0.2 or higher. If you are using an anterior version, migrate to Java 11.0.2 or above (review the supported Java versions in System Requirements).

Close the Designer

Before upgrading, you must 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 5.3 requires to obtain its license from a license server 5.3 or higher.

If licenses in the current installation are obtained using a local license server 1.x, you must upgrade the License Server before upgrading Semarchy xDI Designer.

Obtain a new License Key

Semarchy xDI Designer 5.3 requires a 5.3 compatible license key.

When upgrading from a prior version, reach your usual contact to get your new compatible license key. This new license key is mandatory for the new license manager window of Semarchy xDI Designer.

Upgrade Steps

Get and Install the New Version

Perform the following operations to download and install the new version of Semarchy xDI Designer:

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

  2. Uncompress the archive in a temporary folder.

  3. Move the archive’s content to the target installation folder:

    • Windows: Copy the content to your Program Files folder.

    • Linux: Copy to your user folder.

    • macOS: Copy to your Applications folder.

      If you are prompted to replace, or keep a previous application having the same name, it is recommended to stop the process, rename the previous application, and move the new version to the Applications folder again.

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.

        For more details about license modes, refer to Manage the Designer License.

  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

Starting from 5.3.0, components in Semarchy xDI Designer are installed and updated using an update site.

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

Post-Upgrade Steps

Generic Post-Upgrade Steps

The following post-upgrade operations must be performed for all upgrade scenarios.

  1. Check in the Modules Manager that all modules have been migrated successfully.

  2. Remove the old installation folder.

Post-Upgrade Steps - Upgrading from Versions Before 5.3.0

If your are upgrading from a version prior to 5.3.0:

  • Upgrade all workspaces: Run the designer in command line with the -clearPersistedState option for each of your pre-5.3.0 workspaces.

  • The User License is now holding the Components/Features permissions. If you notice any issue with Components/Features that are unexpectedly disabled and forbidden in your Designer, contact Semarchy.

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