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

ONE Runtime Server Upgrade Procedure

Introduction

This guide is intended to upgrade the product and all related configurations to the latest version. The procedure is generally applicable when upgrading between minor and bugfix versions as well as major versions.

What is covered in the upgrade procedure

This upgrade procedure covers two areas:

The upgrade of the software itself:
1. Product on a desktop computer (IDE + runtime package).
2. Product core on the standalone (Linux) server.
The upgrade of plans and web service configurations and steps to test the upgraded solution for backward compatibility and integration issues.

Upgrade effort

Upgrade effort depends heavily on the configuration complexity: the number of environments (development, test, production), the number of plans, the number of custom scripts and integrations that need to be tested, and so on.

When upgrading between minor and bugfix releases, expect several person-days. When upgrading between major releases, expect tens of person-days.

Preparation

Do not perform any configuration changes during the upgrade process in order to avoid misleading conclusions of the upgrade impact on cleansing and unification outputs.
Get the latest versions of all configurations used on your Ataccama product server environments (plans, reference data sources and lookups used in the configurations, and scripts and database procedures to be influenced by the upgrade procedure) to your Ataccama product desktop workspace. Do one of the following:
- Copy the latest versions of plans used on your server environments to the projects in your current workspace.
- If you use version control plugins (SVN, Git, TFS), check out the latest commit of each of your projects to your current workspace folder.
Make a backup of all of your product workspaces containing projects you want to upgrade.
Create a data sample for all entities processed with source product projects (Party, Address, and so on).
Make sure to reserve enough space for the upgrade transformation process:
1. Filesystem of the application server: Minimum twice the size of the current repository (even for the product with the database repository: temporary files are created on the application server during the repository reload).
2. Database (applicable for product projects with the database repository):
  1. User tablespace: Twice the size of the current repository.
  2. UNDO + TEMP: The upgrade process can consume up to tens of GB, depending on the source product repository size. For example: repository size 55 GB (55m instances), TEMP 32 GB (autoextend 64 GB), UNDO 5 GB (autoextend 30 GB).

Requirements

Third-party software

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

Upgrading on desktop

This part of the upgrade procedure describes how to upgrade the desktop installation of ONE Runtime Server.

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.

(recommendation: no accents in the whole path to the product installation folder).  +

Make sure the path to the installation folder is at most 125 characters. Otherwise, the fully qualified paths to the Eclipse libraries may exceed the Windows limit of 260 characters and IDE 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.

Transfer workspace configuration

This section contains the steps necessary to move all workspace settings from the old installation to the new one.

Runtime configuration

Start the old Ataccama product.
Export your workspace configuration (such database connections, folder shortcuts, server connections, and more): select File > New > Runtime Configuration. Select the destination folder in the Container field and select Finish.
Switch to the new product.
Import your workspace configuration: select File > Import… and in the subsequent dialog, select Ataccama <product> > Runtime Configuration. Next, specify the path to the previously generated file and finish the import.

Custom database drivers

If you use custom database drivers, reconfigure their classpaths in the new installation under Window > Preferences > Ataccama > Database.

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.

Configuration files

These instructions are intended to preserve various Ataccama product configuration files that are usually not part of your projects. If you are using any of the following configurations on your desktop installation, make sure they are preserved and made available to the new installation. All the default configurations are located in <installation_directory>/runtime/server/etc.

Server Configuration: The default file is default.serverConfig.
Runtime Configuration: The default file is default.runtimeConfig.
Logging Configuration: The default file is logging.xml.
users.xml
role-mapping.xml
custom-pages.xml

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.

Upgrading DQC on Server

This part of the upgrade procedure describes how to upgrade the standalone ONE Runtime 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 ONE Runtime Server is running, stop it.
Copy or download the ONE Runtime Server archive (server-assembly-[version].[date]-[releaseID].tar|zip) to your server and extract it to your desired location, for example, <product>:
```
unzip server-assembly-[version].[date]-[releaseID].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 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).

Solution upgrade checklist

Upgrade of lookup generators.
- Upgrade all lookup generators (plans that produce final .lkp files).
- Run all upgraded generators to obtain the final upgraded version of lookups (this task requires all lookup source data to be available from the frozen copy of the source Ataccama product workspace).
- Check lookup contents: the number of records compared to the original source file (depending on the logic in the generator, the format of lookup keys, and so on).
Upgrade of cleansing and unification plans (address, party, contact, and so on). This process is partially automatic, partially manual (for example, unification configuration needs to be upgraded and verified manually).
- Upgrade and verify complex configurations plans per component or plan.
Unification and repository transformation. This is usually a more complex task and is considered as a standalone task in the upgrade process (this requires rebuilding the repository with the upgraded product).
- If a file-based repository is used, upgrade it to a database repository (upgrading from the Unification step to the Extended Unification step).
Check that any custom shell or SQL scripts (for starting plans, workflows, online services) integrate and work as expected with the upgraded product.
Web services transformation. After upgrading web service configurations, some additional work might be needed in order to guarantee backward compatibility (depending on the conditions of the projects and flexibility of the web service target and consuming systems).
Optionally, replace obsolete steps.

Verification and testing checklist

Compare results between the old product version and upgraded version with a small dataset. Includes comparison tests of cleansing outputs and unification outputs (IDs, roles).
Comparison of results with a large dataset. Temporary or auxiliary plans can be made in order to perform "bulk comparison", or you can do it in a simplified way (for example, by profiling the two outputs).
Backward compatibility test and integration test.
- Web services, batch interfaces, workflows: Each part can be tested separately.
- End-to-end test: Regular batch and online processing, starting in the source system and ending in the consuming system, all this using the final upgraded product environment (workflow, plans, repository, interfaces).
Performance test.
- Batch processing of an increment against the whole repository.
- Online or web services performance (can include heavy or overload traffic testing, long-term (days) traffic testing, testing of online traffic while concurrently running batch processing).

Was this page useful?