Process Instance Migration

The migration page can be found by opening the process definition or the instance view of a process that has multiple versions. Here, currently running process instances can be migrated to another version of their process definition, or even a completely different process definition.

Migration Plan

Performing a migration consists of four steps:

• Map the activities of the source definition to the target definition
• Select currently running instances you want to migrate
• Confirm the migration
• Check the results of the migration and possible errors

Open the Process Instance you want to migrate via Cockpit - Processes and find the process to migrate. From the Actions tab, you can directly choose the Migrate icon. Alternatively, open the process by clicking the name or the Process key. Find the definition version you want to migrate from in the History Versions tab on the left and select it. Now click on the Migrate icon on the right. You will be presented with the migration page. Here, the version and the definition key for the source and the target definition are already preset and you can change them to your requirements. After selecting the versions, the respective diagrams are shown below. The left side shows the selected currently running source. The right side shows the target definition we are migrating to. When you select the Show Migration Plan toggle, a default migration plan is automatically generated. Successfully mapped activities show a green checkmark. Green lines visualize the mapping.

If there are activities that are not currently mapped to a target activity but have running instances, they will be flagged with an orange warning marker. Create a mapping for these activities, otherwise migrating that instance will fail.

Creating a mapping

to create a mapping just hover over the activity and click the arrow button. you can now drag the line over to the target definition and connect it with the respective activity on the right side. By clicking an activity with an existing mapping, you can toggle the green line being shown in the diagrams.

incorrect mappings

An incorrect mapping will be indicated by a red line and an X on both activities. This could be the case if you try to map activity types that do not match, e.g. a user task to a start event.

To correct this, hover over the source activity and click the X in the right corner. This will remove the mapping.

if you uncheck the Link Diagrams Navigation toggle, you can move and zoom the definitions diagrams separately.

Set Variables

When the mapping is done, you can click on Set Variables for the next step. Here you can add variables into the process instance scope if needed. To do so click the Add Variable button and enter the variable name, variable type and variable value.

After adding the variable, you can always edit it again by clicking the Edit Variable button. It is also possible to delete it via the Remove Variable button.

Select Instances

The next step allows you to choose the instances you want to migrate. All possible instances of the source process definition are listed here. you can filter them via the search bar. Here you can choose between different search criteria to narrow down the instance you want to migrate. Once all relevant instances are selected, you can move to the next step and migrate the selected instances.

Confirm and migrate instances

Click the Mirgrate Selected Instances button. The label of the button also reflects how many instances will be migrated. On the Confirm tab, you will see a summary of the chosen migration.

In the Options section, per default the 3 options

• Asynchronous
• Skip Custom Listeners
• Skip IO Mappings

are selected.

The Summary section shows how many and which instances will be migrated. It displays the source process definition ID and the target process ID. In the Migration Plan section you will see a table with two columns, containing the source activities and the mapped target activities.

If you have added process variables, these will be shown aswell as the last section on this page.

Check Migration Result

After executing the Migration, the result screen will be displayed. If the migration was performed successfully, that is indicated on this page. For asynchronous migrations, a link to the batch page is displayed where the progress of the batch can be observed.

If the migration failed, it will be indicated here aswell. Any validation errors in the migration plan will be shown listed so you can go back and fix these errors.

If the migration plan is correct but it could not be applied to a certain instance, there will also be an error message containing the instance ID that caused the error along with the reason for the failure.