If you can't find the product or version you're looking for, visit support.ataccama.com/downloads

MDM 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 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 MDM documentation.

Preparation

Make sure you have the following:

New builds, as can be found here. Download packages for ONE Master Data Management.
Valid license keys:
- Server license keys for your web application server and the server with MDM 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.

Before starting the upgrade, make sure there are no active tasks. To achieve this, stop sending WRITE requests to MDM and wait for event handlers to finish publishing. You can check the status in Admin Center > MD Process Monitoring.

Requirements

Third-party software

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

Step 1: Upgrade ONE Desktop for Project Development

The following section provides instructions for upgrading the ONE Desktop installation on a local Windows machine used for solution development.

Basic installation procedure

Download the Ataccama ONE Desktop package.

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.

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

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.
Copy any projects from the old workspace to the new workspace folder.
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 MDM model project to the latest version.

Back up your model project by exporting it into an .mdc file. For instructions, see Model Projects, section Export a model project.
Start the upgraded ONE Desktop.
Switch to the Model Explorer view.
Right-click [your project] > Upgrade Template.
Select Built-in template and then Next. Wait for the upgrade procedure to finish.
Select Finish.
Import the runtime configuration from Files/etc/mdm.runtimeConfig via File > Import > Ataccama MDM > 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).

Right-click the project name, select Batch Actions > Change Versions.
Keep all the plans and components selected.
Optionally, select the Backup File field and specify where the backup zip file should be stored.
Correct the possible errors in the upgraded plans and components.
Correct the possible errors in the upgraded workflows.
If you are using version control tools, commit the latest change.

Step 3: Upgrade MDM Server

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

On the standalone server, back up project folders (in your workspace) and the runtime folder (located in <ATACCAMA_HOME>).
If the Runtime Server or MDM Server is running, stop it.
Copy or download the archive mdm-server-assembly-[version].[date]-[releaseID]-[distribution].zip to your server and extract it to your desired location, for example, <product>:
```
unzip mdm-server-assembly-[version].[date]-[releaseID]-[distribution].zip -d <product>
```
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
```
If you had any configuration files in the old <ATACCAMA_HOME> folder, copy them to the respective folders in the new installation.
Copy all custom libraries and JDBC drivers used from the old <ATACCAMA_HOME>/lib folder to the same location in the new installation.
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.
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).

Lookups

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

Step 4: Upgrade MDM Webapp

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

From version 13 onwards, the MDM 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 MDM Web App Application Properties as described in the mdm-13-0-0-upgrade-notes.adoc.

On the web application server, back up the directory where MDM Webapp is deployed.
Shut down the server.
Deploy the new version of the MDM Webapp.
Transfer the MDM Webapp application.properties from the backup into the new version.

Add new default MDM clients to Keycloak via the Admin Console.

Between version 12 and 13 new clients were added and role prefixes were changed.

Your .json file should now look this:

Click here to expand

   {
   "users": [
    {
      "username": "service-account-mdm-admin-client",
      "enabled": true,
      "totp": false,
      "emailVerified": false,
      "email": "service-account-mdm-admin-client@ataccama.com",
      "serviceAccountClientId": "mdm-admin-client",
      "credentials": [],
      "disableableCredentialTypes": [],
      "requiredActions": [],
      "realmRoles": [
        "offline_access"
      ],
      "clientRoles": {
        "realm-management": [
          "impersonation",
          "view-realm",
          "manage-users",
          "view-users",
          "manage-realm"
        ],
        "account": [
          "view-profile",
          "manage-account"
        ]
      },
      "notBefore": 0,
      "groups": []
    }],

    "clients": [
    {
      "clientId": "mdm-admin-client",
      "standardFlowEnabled": false,
      "directAccessGrantsEnabled": true,
      "serviceAccountsEnabled": true,
      "publicClient": false,
      "enabled": true,
      "secret": "mdm-admin-client-s3cret",
      "protocol": "openid-connect"
    }
    ,
      {
      "clientId": "mdm-token-client",
      "bearerOnly": false,
      "publicClient": false,
      "standardFlowEnabled": true,
      "directAccessGrantsEnabled": true,
      "enabled": true,
      "secret": "mdm-token-client-s3cret",
      "redirectUris": [
        "*"
      ],
      "protocol": "openid-connect"
    },
    {
      "clientId": "mdm-webapp-public-client",
      "name": "MDM Webapp Auth Client",
      "enabled": true,
      "redirectUris": [
        "*"
      ],
      "webOrigins": [
        "*"
      ],
      "bearerOnly": false,
      "consentRequired": false,
      "standardFlowEnabled": true,
      "implicitFlowEnabled": false,
      "directAccessGrantsEnabled": false,
      "serviceAccountsEnabled": false,
      "publicClient": true,
      "frontchannelLogout": false,
      "protocol": "openid-connect"
    }]}

Restart the application server.

Was this page useful?