Automatic migration of a full Talend Runtime installation (recommended)

Most versions of Talend Runtime that cannot be obtained from a patch, such as 7.3.1-R2022-09-RT and 8.0.1-R2022-10-RT, can be migrated automatically with the migration tool. This tool automatically migrates configuration and installed features from the existing Talend Runtime to its new long-term support version.

Before you begin

Your runtime version is 8.0 onwards.
The version you want to migrate to is not 8.0.1-R2023-08-RT. To migrate to this version, see Manual migration of a full Talend Runtime installation.
Applying an upgrade patch, the recommended approach, is too complicate to be feasible and thus you have received a full installer from Talend.
You have installed the new version of Talend Runtime. Note that the new version should be installed the same way as the version to be upgraded. In other words, either the new and the old versions are installed as a service or both of them are unzipped in given directories as a standalone program.

About this task

Perform this migration in a non-production environment first to ensure that the output contains all the important custom resources, especially those you manually installed, of the old version to be fully functional.
By default, the migration tool is stored in a folder called migration in the patch files, so this is the location used in this article. You can store it in a different directory of your choice.

Procedure

Ensure that the Talend Runtime to be upgraded is running.

Run the migration tool using one of the following commands, depending on your operating system and how your Runtime was installed.

Talend Runtime installed as a service:

On Windows, start a PowerShell with Administrator privileges in the migration directory and run the following command:

./talendRuntimeMigration.ps1 talend-runtime-8.0.1-XXXX talend-runtime-8.0.1-YYYY

An example of the expected output reads like this:

PS C:\Users\IEUser\Desktop\TalendRuntime\migration> .\talendRuntimeMigration.ps1 talend-runtime-8.0.1-R2022-07-RT talend-runtime-8.0.1-R2022-10-RT
2023-01-19 22:17:19.651 Exporting data from current Talend Runtime
2023-01-19 22:17:44.666 Copying exported data to the new Talend Runtime
2023-01-19 22:17:44.995 Stopping current Talend Runtime
WARNING: Waiting for service 'Talend Runtime 8.0.1-R2022-07-RT (talend-runtime-8.0.1-R2022-07-RT)' to stop...
WARNING: Waiting for service 'Talend Runtime 8.0.1-R2022-07-RT (talend-runtime-8.0.1-R2022-07-RT)' to stop...
WARNING: Waiting for service 'Talend Runtime 8.0.1-R2022-07-RT (talend-runtime-8.0.1-R2022-07-RT)' to stop...
WARNING: Waiting for service 'Talend Runtime 8.0.1-R2022-07-RT (talend-runtime-8.0.1-R2022-07-RT)' to stop...
WARNING: Waiting for service 'Talend Runtime 8.0.1-R2022-07-RT (talend-runtime-8.0.1-R2022-07-RT)' to stop...
2023-01-19 22:17:57.620 Starting new Talend Runtime
2023-01-19 22:18:22.073 Importing data into the new Talend Runtime
2023-01-19 22:18:23.088 Migration completed successful

On Linux, run the following command:

./talendRuntimeMigration.sh talend-runtime-8.0.1-XXXX talend-runtime-8.0.1-YYYY

An example of the expected output reads like this:

root@talend-VirtualBox:/home/talend/Downloads/migration# ./talendRuntimeMigration.sh talend-runtime-8.0.1-R2022-07-RT talend-runtime-8.0.1-R2022-10-RT
2023-01-23 15:51:27.464 Exporting data from current Talend Runtime
2023-01-23 15:51:29.472 Copying exported data to the new Talend Runtime
2023-01-23 15:51:29.475 Stopping current Talend Runtime
2023-01-23 15:51:57.709 Starting new Talend Runtime
2023-01-23 15:52:14.405 Importing data into the new Talend Runtime
2023-01-23 15:52:16.425 Migration completed successfully

Talend Runtime installed manually (the standalone mode):
- On Windows, run the following command:
```
./talendRuntimeMigration.ps1 "path_to_current_karaf"  "path_to_new_karaf"
```
- On Linux, run the following command:
```
./talendRuntimeMigration.sh "path_to_current_karaf"  "path_to_new_karaf"
```

The script of the migration tool then orchestrates the following steps:

Install the export bundle
Stop the current Talend Runtime
Start the new Talend Runtime
Install the import bundle

Troubleshooting: If you encountered issues during or after the migration, try the following steps.

Verify the error log in log/tesb.log of both the Talend Runtime versions.
On Windows, you can add $DebugPreference = 'Continue' to PowerShell before the script line to generate the specific debugging logs.
If errors happen during the migration, do the following to roll back:
1. Stop the new Talend Runtime engine.
2. Start the old one.

When you need to resume the migration, do the following:

Stop the old and the new Talend Runtime instances.
Delete and then re-install the new Talend Runtime version.
Clear the log/tesb.log file.
Restart the old Talend Runtime instance and run the migration script as explained above.

What to do next

See Migrated configurations to review the list of configurations migrated by the tool and manually migrate any remaining item. Then test the new Talend Runtime to ensure that it works correctly. After this, repeat the procedure above to migrate your Talend Runtime for the production environment. You can then patch this new installation with the latest patch by following the procedure described in the corresponding patch notes.

Did this page help you?

If you find any issues with this page or its content – a typo, a missing step, or a technical error – let us know how we can improve!

Leave your feedback here