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 contain the latest information about the Semarchy xDI release, such as new features, bug fixes, breaking changes, and removals.

System requirements

Review the system requirements for the new release. Take special note of supported Java versions, as you may need to install a newer one depending on which Designer version you are upgrading from.

Close the Designer

Before upgrading, completely close the Designer environment:

  1. Stop the local runtime.

  2. Close all editors.

  3. Exit xDI Designer.

Backup your installation

Perform a backup of your current installation of xDI Designer:

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

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

Upgrade the License Server

Semarchy xDI Designer 2023.1.x and newer can only receive their license from a local License Server running version 5.3 or newer.

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

Get a compatible license key

If you are upgrading from a Designer version older than 5.3.x, contact 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 on top of the existing one. We recommend you back up and remove the previous version, or installing the new one in a different directory.

Copy modules

Before the first startup, copy the Modules directory from the previous installation to the new one.

  • Under Windows or Linux, the default directory for Modules is <Designer root directory>/runtime/modules.

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

Run the new version

When starting the new version for the first time, perform the following steps:

  1. Start the new version of 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 it prompts you to.

When the Designer restarts, all modules copied from the previous installation are automatically updated to the latest version from the related component (if any).

Reinstall other plugins

If needed, reinstall any other plugin used in the previous installation (version control system or other).

Finalize and clean up

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

A workspace that was opened with a newer version of xDI Designer should not be reopened in a previous version.

Post-upgrade steps

Version-specific upgrade steps

Depending on the Semarchy xDI version you are upgrading from, you may need to perform certain actions after the upgrade is complete.

Actions are listed incrementally. Please read all the subsections until you reach your current Semarchy xDI product version, and perform all actions up to that point. For example, when upgrading from S19 to 2023.1.6, install version 2023.1.6 then follow post-upgrade steps for S19 to 5.3.x, and then for 5.3.x to 2023.1.x.

If your version is not listed, no further action is needed.

Upgrading from versions prior to 2023.1.0

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

Upgrading from versions prior to 5.3.0

Follow the upgrade steps detailed in the upgrade guide.

For each workspace that was used in a Designer version prior to 5.3.0, upgrade the workspace by starting Designer from a command line with the -clearPersistedState option.

Starting from version 5.3.0, the license key contains component and feature permissions. If you notice problems such as unexpectedly disabled components and features, please contact Semarchy.

Rebuild the project cache

After an upgrade, project cache may be invalid, or may have internal references that no longer match. This may cause problems when executing an integration flow. It is a good idea to have Designer rebuild the cache, clean your projects, and rebuild mappings after any version upgrade, especially if you are going to run them right away. Note that this may take a while if you have many complex projects.

To rebuild cache and clean projects:

  1. In Designer, open the Utilities menu.

  2. Click on Rebuild Cache and Clean Projects.

  3. Click OK to confirm.

  4. Wait for the rebuild to finish.

Upgrade metadata, mappings and processes

Metadata, mappings and processes have their own internal model and version numbers. They are sometimes updated to add new features, fix issues, or improve performance. These updates are usually available following major releases, but may also be available in patches for Long-Term Support (LTS) releases.

When metadata, mappings or processes need an internal update, a Yellow triangle icon with an exclamation point warning symbol will appear on their icon to indicate their model is out-of-date. A separate warning will also appear in the Problems view with the same icon.

Screenshot of Designer showing off yellow warning triangles on various elements

Upgrading older metadata, mapping or process files will happen automatically when they are modified and saved. You can continue using your projects as-is. However, you can run a batch upgrade if you want to upgrade the files immediately and remove the warning.

To upgrade the internal model for metadata, mappings or processes:

  1. Go to the Designer Project Explorer.

  2. Select one or more elements or folders that need an upgrade.

  3. Right-click your selection.

  4. Select the Upgrade Models option from the context menu.

Note that your selection can contain both upgradable and up-to-date elements. The Upgrade Models option will not have an effect on anything that is already up-to-date.

Screenshot of the Designer Project Explorer showing off the Upgrade Models option for selected elements