Process instance migration fits a running process instance to a different process definition. This can be useful when the process definition of a running process instance needs changes due to bugs or updated requirements.
To repair a broken process instance without making changes to the process definition, use process instance modification instead.
Use the migration command to change the process model of a running process instance.
You can also migrate your process instances using Operate's UI by following the user guide.
Changing the process instance flow for inactive parts
Process instance migration allows you to adjust the process model of your process instance to fit to new requirements.
Let's consider an example.
The process instance below contains a completed start event, an active service task
A, and an end event.
Once you complete the service task
A, the process will reach the end event.
However, the requirements of our process have changed.
Instead of completing the process, we want to add a user task
B after the service task
A and before the end event.
We can create new process instances according to this new process model after deploying it, but we also want our active process instances to receive the update and reach user task
B when service task
A is completed.
To achieve this, we can migrate our process instance from its current process to the newly deployed one. You must provide a migration plan with mapping instructions to the target process definition to clarify your intentions.
In our example, we'll provide a mapping instruction from source element ID
A to target element ID
A. This means we expect any active element instances of element with ID
A to be migrated to the element with ID
A in the target process.
Therefore, our process instance will continue to be active at service task
After migrating our process instance, we can now complete the service task
A to reach user task
Process instance migration allows you to change the inactive parts of the process instance. In our example, we placed a user task
B between the active service task
A and the inactive end event. We did not change the active service task
A, just the steps that follow.
Changing the active elements
Sometimes your requirements change so much that the currently active element no longer exists in the new process version.
Consider the following example: the process contains a completed exclusive gateway, taking the sequence flow to the service task
A which is currently active.
It did not take the sequence flow to service task
B, so it is inactive.
Due to changed requirements, our process model no longer contains the exclusive gateway, nor the service tasks
Instead, it only contains a new service task
We can migrate the active service task
A to this new service task
C by providing a mapping instruction from source element ID
A to target element ID
You cannot map an element to an element of a different type. An active service task of a process instance can only be mapped to a service task in the target process. It cannot be mapped to a user task as this changes the element type.
Also note that the jobs, expressions, and input mappings are not recreated.
So, while service task
C is active in the target process, the associated job still has the job type from when it was associated to service task
If you need to adjust the job type to its new element, you can use process instance modification to recreate the service task. Simply cancel the service task instance, and add a new instance of the service task.
Process definitions and versions
So far, we've only discussed migrating a process instance to a new version of its process definition.
You are free to migrate your process instance:
- From an older version to a newer version of the same process definition.
- From a newer version to an older version of the same process definition.
- To a different process definition altogether.
You do not have to provide a mapping instruction from the process instance's process ID to the target process ID.
Jobs, expressions, and input mappings
We do not recreate jobs, reevaluate expressions, and reapply input mappings of the active elements. Any existing variables and jobs continue to exist with the same values as previously assigned.
Let's consider an active service task that created a job when it was activated with type
In the target process definition, the job type expression is changed as follows:
However, on migrating the process instance this new job type expression is not evaluated. Instead, the job keeps all properties it had before the migration, including the job type.
You can use process instance modification to terminate and activate the service task if you want to create the job according to the new service task's definitions. This results in new keys for the service task as well as the job.
Not all process instances can be migrated to another process definition. In the following cases, the process instance can't apply the migration plan and rejects the migration command.
- Process instance migration can only migrate active process instances, i.e. existing process instances that have not yet been completed, terminated, or banned.
- All active elements require a mapping.
- The number of active elements cannot be changed. You can use process instance modification to achieve this instead.
- The target process definition must exist in Zeebe, i.e. it must be deployed and not yet deleted.
- The migration plan can only map each
- A mapping instruction's
sourceElementIdmust refer to an element existing in the process instance's process definition.
- A mapping instruction's
targetElementIdmust refer to an element existing in the target process definition.
The following limitations exist that may be supported in future versions:
- Only elements of the following types can be migrated:
- A process instance
- A service task
- The following scenarios cannot be migrated:
- A process instance with an incident
- A process instance that is started from a call activity, i.e. a child process instance
- A process instance with an active service task that has a boundary event
- A process instance with an active service task that has a boundary event in the target process definition
- A process instance that contains an event subprocess
- A target process definition that contains an event subprocess
- An element that becomes nested in a newly added sub-process
- An element that was nested in a sub-process is no longer nested in that sub-process
- Mapping instructions cannot change the element type
- The process instance must be in a wait state, i.e. waiting for an event or external input like job completion. It may not be taking a sequence flow or triggering an event while migrating the instance
A full overview of error codes can be found in the migration command.
If your specific case is not (yet) supported by process instance migration, you can use cancel process instance and create and start at a user-defined element to recreate your process instance in the other process definition. Note that this results in new keys for the process instance and its associated variables, element instances, and other entities.