Process Migration

This tutorial describes the way how you can do migration for Process Instances from one definition version to another definition version. To understand the background of the need of migration the Model Migration overview gives a general overview.

Different APIs to Execute Migration

There are different levels to execute migration:

1. Migrating a single process instance
2. Migrating all process instances from a process definition
3. Batch migration of all process instances from a process definition

To execute the migration you need to specify a migration document which then can be executed in the different environments.

The same APIs also exist as Java APIs as part of the ProcessMigrationService. The migration document is available in a builder pattern on the different operations.

Migration Document

Specifying the Destination Definition

Property	Description
toProcessDefinitionId	Id of the process definition to migrate to, this ID is unique and the other toProcessDefinition-properties do not need to be provided. The ID is typically different in different environments.
toProcessDefinitionKey	The key of the process definition which should be migrated to, this must be specified together with the version.
toProcessDefinitionVersion	The version number of the destination process definition. Please be aware that this version number might be different between different environments.
toProcessDefinitionTenantId	Tenant in which the source and destination process definition are. Only required in case of migration in a multi-tenant environment and without the toProcessDefinitionId.

Changing the Execution State

Before the migration, the execution of the process instance will be in a wait state at a certain activity of the process definition (e.g. a user task). If the process instance should stay in the wait state on the same activity after the migration, no specific activity mappings are needed.

However, if the execution needs to be moved to another activity, an activity mapping needs to be defined. This is also required if the current activity that the execution is on is deleted in the new process definition, for example.

Activity mappings

The activity mappings need to be defined under the activityMappings array property in the migration document.

Each activity mapping should have a fromActivityId(s) property and a toActivityId(s) property configured. The following properties can be used in the activity mappings:

Property	Description
fromActivityId	Activity Id of the activity in the original process definition. Can be used in combination with toActivityId or toActivityIds.
fromActivityIds	Array of Activity Ids in the original process definition. To be used in combination with toActivityId.
toActivityId	Activity Id of the activity in the destination process definition. Can be used in combination with fromActivityId or fromActivityIds.
toActivityIds	Array of Activity Ids in the destination process definition. To be used in combination with fromActivityId.
localVariables	Optional property to define local variables to be added locally to the activity or activities referenced in toActivityId or toActivityIds during the migration.
newAssignee	Optional property to define the user that should be the assignee of the activity referenced by the toActivityID after the migration. To be used in combination with toActivityId.

One-to-one mapping

When fromActivityId and toActivityId are used, this is called a one-to-one mapping.

For example, migrating from

to

Example of migration document:

{
  "toProcessDefinitionKey": "processWithTwoTasks",
  "activityMappings": [
    {
      "fromActivityId": "userTask1",
      "toActivityId": "userTask2",
      "newAssignee": "myUserId",
      "localVariables": {
        "additionalContext": "Test process level",
        "numberOfDays": 5
      }
    }
  ]
}

Many-to-one mapping

When fromActivityIds and toActivityId are used, this is called a many-to-one mapping. In this migration, one or more executions will be removed.

For example, migrating from

to

Example of migration document:

{
  "toProcessDefinitionKey": "processWithTwoParallelTasks",
  "activityMappings": [
    {
      "fromActivityId": "userTask1",
      "toActivityIds": ["parallelTask1", "parallelTask2"]
    }
  ]
}

One-to-many mapping

When fromActivityId and toActivityIds are used, this is called a one-to-many mapping. In this migration, one or more executions will be added.

For example, migrating from

to

Example of migration document:

{
  "toProcessDefinitionKey": "processWithTwoParallelTasks",
  "activityMappings": [
    {
      "fromActivityIds": ["parallelTask1", "parallelTask2"],
      "toActivityId": "userTask1"
    }
  ]
}

Moving an execution to and from call activity child process

It is also possible to move an execution from a parent process to an activity inside a call activity child process. Alternatively, an execution can be moved from a call activity child process back to an activity in the parent process. To specify this, the following properties can be used:

Property	Description
inParentProcessOfCallActivityId	Id of the call activity in the parent process which has the toActivityId that the execution should move to.
inSubProcessOfCallActivityId	Id of the call activity that calls the child process which has the toActivityId that the execution should move to.
callActivityProcessDefinitionVersion	Optional property to define which version of called process should be used. To be used in combination with callActivityProcessDefinitionVersion

For example, migrating from

to

with child process

Example of migration document:

{
  "toProcessDefinitionKey": "processWithCallActivity",
  "activityMappings": [
    {
      "fromActivityId": "userTask1",
      "toActivityId": "childTask",
      "inSubProcessOfCallActivityId": "callActivity",
      "callActivityProcessDefinitionVersion": 3
    }
  ]
}

Example of migration document of the opposite migration:

{
  "toProcessDefinitionKey": "processWithCallActivity",
  "activityMappings": [
    {
      "fromActivityId": "childTask",
      "toActivityId": "userTask1",
      "inParentProcessOfCallActivityId": "callActivity"
    }
  ]
}

Enable new Event subprocess activity

To enable a new event subprocess during the migration, the enableActivityMappings property can be used. Only one property has to defined in an enableActivityMapping:

Property	Description
activityId	Event subprocess definition id in the new version.

Example:

{
  "toProcessDefinitionKey": "processWithEventSubprocess",
  "enableActivityMappings": [
    {
      "activityId": "eventSubprocess1"
    }
  ]
}

Process Instance Variables

To set additional variables on the process instance, the property processInstanceVariables is available. It is possible to provide a map with different fields as a payload.

Example:

{
  "toProcessDefinitionId": "CAS-4ce9eaf6-6287-11ef-ae73-e68ac21327db",
  "processInstanceVariables": {
    "showUserInfo": true,
    "additionalContext": "Test process level",
    "numberOfDays": 5
  }
}

Pre- and Post-Upgrade Options

Property	Description
preUpgradeJavaDelegate	Name of a Java Delegate. This Java Delegate will be executed before the migration.
postUpgradeJavaDelegate	Name of a Java Delegate. This Java Delegate will be executed after the migration.
preUpgradeJavaDelegateExpression	Expression that will be evaluated at runtime and should resolve to the name of a Java Delegate. This Java Delegate will be executed before the migration.
postUpgradeJavaDelegateExpression	Expression that will be evaluated at runtime and should resolve to the name of a Java Delegate. This Java Delegate will be executed after the migration.
preUpgradeScript	Script to be executed before the migration
postUpgradeScript	Script to be executed after the migration

The -UpgradeScript properties are an object themselves with properties:

Property	Description
language	Language of the script
script	The code of the script

Example:

{
  "toProcessDefinitionId": "CAS-4ce9eaf6-6287-11ef-ae73-e68ac21327db",
  "preUpgradeJavaDelegateExpression": "${myJavaDelegate}",
  "postUpgradeScript": {
    "language": "groovy",
    "script": "execution.setVariable(\"additionalContext\", \"Test process level\")"
  }
}