Upgrade Semarchy xDI Designer

Follow the instructions on this page to upgrade Semarchy xDI Designer.

Pre-upgrade steps

Review the release notes

The release notes contain the latest information about the Semarchy xDI release such as added features, bug fixes, or breaking changes.

System requirements

Review the system requirements for the new release.

Pay attention to the list supported Java versions, as you may need to install a different Java version depending on which Designer version you are upgrading from.

Close the Designer

Before upgrading, stop the entire Designer environment:

  1. Stop the local runtime.

  2. Close all editors.

  3. Exit xDI Designer.

Backup your installation

Make a backup of your current xDI Designer installation:

  1. Make a ZIP file of the current xDI Designer installation.

  2. Make a ZIP file of your workspaces.

Upgrade your local License Server

Semarchy xDI Designer 2023.1.x and later can only communicate with a License Server running version 5.3 or later.

If you are using a local License Server, make sure to upgrade it before continuing the xDI Designer upgrade process.

Get a compatible license key

If you are upgrading from a Designer version earlier than 5.3, contact Semarchy support or your account representative to change your license key.

Upgrade steps

Download and install the new version

Download the newer version of Semarchy xDI Designer from the Semarchy website.

Extract the files to a new directory. Make sure it is not the same as the previous Designer directory.

Copy modules

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

  1. In your previous Designer installation, find your runtime modules directory.

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

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

  2. Make a copy of the modules directory.

  3. Navigate to the new Designer installation path.

  4. Create a directory named runtime, and enter it.

  5. Add or paste the modules directory from the previous installation.

Run the new version

Do the following steps:

  1. Start the new version of xDI Designer.

  2. Select the previous workspace directory, and click Launch.

  3. Review and accept the terms of use, 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 a 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 about license modes.

  5. Click Register.

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

  7. Open the Utilities menu and run Rebuild Cache and Clean Projects.

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

Reinstall components

To reinstall components, follow the procedure described on the components page, and restart the Designer when prompted.

When Designer restarts, the modules you copied from the previous installation update their libraries to the most recent versions from the related components (if any).

Reinstall other plugins

If needed, reinstall any other plug-in used in the previous installation, such as for version control system.

Final steps and cleanup

Follow these steps to finish the upgrade:

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

  2. Follow the post-upgrade steps.

  3. Put your backup of the previous installation in a safe location.

  4. Remove the previous installation directory.

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 script to run Designer commands, change which command runs your scripts to use the current Designer CLI syntax.

The current syntax replaces the legacy java -jar …​ method.

Upgrading from versions prior to 5.3.0

Follow the upgrade steps detailed in the upgrade guide on the support site.

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

Starting from version 5.3.0, your license key contains new permissions. If you notice problems such as disabled components and features, contact Semarchy support.

Rebuild the project cache

After an upgrade, your project cache may be invalid, or may have broken internal references. This may cause problems when executing an integration flow.

It is a good idea to rebuild the Designer cache, clean your projects, and rebuild mappings after any version upgrade. This rebuild may take a while if you have complex projects and integration flows.

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 features, fix issues, or improve performance. These updates are typically 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 appears on their Designer icon to indicate they are out-of-date. A separate warning also appears in the Problems view, with the same warning symbol.

Screenshot of Designer showing off yellow warning triangles on various elements

Upgrading older metadata, mapping or process files happens 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 to remove the warning.

To explicitly upgrade the internal model for metadata, mappings, or processes, follow these steps:

  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.

Your selection can also contain elements that are not upgradable. The Upgrade Models option ignores anything that does not need upgrades.

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