User Community Service Desk Downloads
If you can't find the product or version you're looking for, visit

RDM Upgrade Procedure

This section describes the procedure for upgrading the Ataccama product to the latest version.

Before every upgrade, we highly recommend reviewing the Known Issues section of the relevant Release Notes.

Determine your upgrade path

As the first step, determine your upgrade path. To do this, you will need to check version specific upgrades for each release between the one you currently have installed, and the one you wish to install.

These can be found in the Upgrade section of the RDM documentation.


Make sure you have the following:

  • New builds, as can be found here. Download packages for ONE Reference Data Management.

  • Valid license keys:

    • Server license keys for your web application server and the server with RDM Runtime (whether it is the same server or not), for example, license_[your_company]_DEV_v14.plf. You need a separate license for each environment, like development, testing, and production.

    • User license key for solution development on a local workstation.,for example: license_[your_company]_USER_v[version].plf.


Third-party software

For the recommended and supported versions of Java and Keycloak, see Supported Third-Party Components.

If Keycloak is not deployed as a service, service account roles associated with the RDM Admin client must be added manually as they are not created automatically. If these roles are missing, you might have issues accessing the RDM Admin console.

Step 1: Upgrade ONE Desktop for project development

The following section provides instructions for upgrading the RDM installation on a local Windows machine used for solution development. The following components are upgraded: the Ataccama IDE, RDM Runtime, and the RDM model project.

Basic installation procedure

  1. Download the Ataccama ONE Desktop package.

  2. Extract the package to any desired location.

    Make sure the path to the installation folder:

    • Does not contain any accents.

    • Is at most 125 characters. Otherwise, the fully qualified paths to the Eclipse libraries might exceed the Windows limit of 260 characters and ONE Desktop will not start.

  3. If you are upgrading between minor or bugfix versions, copy your license key from runtime/license_keys to the same location in the new product installation folder. If you are upgrading between major versions, place a new license into runtime/license_keys.

Transfer workspaces

Transfer (connect to) the old workspaces.

  • Your old workspace is inside the old product installation folder

  • Your old workspace is outside the old product installation folder

  1. Start the newly installed Ataccama ONE Desktop and, if asked to choose the workspace location, keep the suggested option and select OK. The workspace will be created inside the folder with the newly installed product.

  2. Copy any projects from the old workspace to the new workspace folder.

  3. In the File Explorer, right-click DQ Projects and select Refresh to see the copied projects.

Start the newly installed Ataccama ONE Desktop and, if prompted, enter the location of the source workspace and select OK. If not prompted, go to File > Switch Workspace > Other and choose the location of your workspace.

In this case, you also need to update paths to database driver classpaths for all used database types under Window > Preferences > Ataccama > Database.

Reinstall plugins

If you have previously used custom plugins for the Eclipse IDE like SVN connector or EGit, reinstall them. See Collaboration and Version Control.

Step 2: Upgrade the model project

The following section provides instructions for upgrading the RDM model project to the latest version.

  1. Back up your model project by exporting it into an .mdc file. For instructions, see Model Projects, section Export a model project.

  2. Start the upgraded ONE Desktop.

  3. Switch to the Model Explorer view.

  4. Right-click [your project] > Upgrade Template.

  5. Select Built-in template and then Next. Wait for the upgrade procedure to finish.

  6. Select Finish.

  7. Import the runtime configuration from Files/etc/rdm.runtimeConfig via File > Import > Ataccama RDM > Runtime Configuration. For more information, see Export and Import Runtime Configuration.

Upgrade plans, web services, and workflows

This section covers the upgrade procedure for Ataccama product plans (.plan and .comp files), web service configurations (.online files), and workflows (.ewf files).

  1. Right-click the project name, select Batch Actions > Change Versions.

  2. Keep all the plans and components selected.

  3. Optionally, select the Backup File field and specify where the backup zip file should be stored.

  4. Correct the possible errors in the upgraded plans and components.

  5. Correct the possible errors in the upgraded workflows.

  6. If you are using version control tools, commit the latest change.

Step 3: Upgrade standalone Runtime Server

This part of the upgrade procedure describes how to upgrade ONE Runtime Server on a server machine. The following instructions assume all the previous steps have been completed.

  1. On the standalone server, back up project folders (in your workspace) and the runtime folder (located in <ATACCAMA_HOME>).

  2. If the Runtime Server is running, stop it.

  3. Copy or download the archive server-assembly-[version].[date]-[releaseID]-[distribution].zip to your server and extract it to your desired location, for example, <product>:

    unzip server-assembly-[version].[date]-[releaseID]-[distribution].zip -d <product>
  4. Give the execute permission for the scripts in the <product>/bin folder to all users by executing the following command:

    chmod +x <product>/bin/*.sh
  5. If you had any configuration files in the old <ATACCAMA_HOME> folder, copy them to the respective folders in the new installation.

  6. Copy all custom libraries and JDBC drivers used from the old <ATACCAMA_HOME>/lib folder to the same location in the new installation.

  7. If you are upgrading between major versions, place a new valid license file (.plf) into the <ATACCAMA_HOME>/license_keys folder of the product installation.

  8. Copy the project folders with the upgraded plans and workflows and other configuration files for your project to the workspace on the server (or copy the whole project folder).

    • If you are using version control tools, check out the latest commit of all of your projects (with upgraded plans).

Copy project files

Some optional configurations like RDM synchronization result in generating files like ONE plans (.plan), workflows (.ewf), schedules (.sch), and web service configurations (.online).

By default, these files are generated to the Files folder of the RDM project. After you have upgraded your project and cleaned up the Files folder, copy it to the server that contains the RDM Runtime.

Check runtime and server configuration

After you copied the Files folder to your RDM server, check and correct the paths in the following components in your Server Configuration files:

The paths should point to relevant files in the subfolders of the Files folder. Check whether your runtime configuration file contains the definitions of servers and databases that you use for RDM synchronization, initial loads, and validation and enrichment services. The same applies to folder shortcuts.

See Export and Import Runtime Configuration to learn how to export these definitions directly from ONE Desktop.


We highly recommend rebuilding all lookups (.lkp files) used in the solution.

Step 4: Upgrade RDM Webapp

The following section provides instructions for upgrading the RDM web application to the latest version.

From version 13 onwards, the RDM Webapp is deployed on a SpringBoot server. If you are upgrading from version 12.x to version 13.x, set up your Keycloak settings and ports in the RDM Application Properties as described in the rdm-13-0-0-upgrade-notes.adoc.

  1. On the web application server, back up the directory where RDM Webapp is deployed.

  2. Shut down the server.

  3. Deploy the new version of the RDM Webapp.

  4. Transfer the RDM Webapp from the backup into the new version.

  5. If you have custom libraries or JDBC drivers in your old /WEB-INF/lib directory, copy them to the new lib directory.

  6. Restart the application server.

Deploy a new configuration to the RDM Webapp

To complete the upgrade, generate the new web application configuration from ONE Desktop and deploy it to the RDM web application. See How to Deploy an RDM Web App Configuration.

Was this page useful?