Process instance migration

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.

tip

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.

note

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 A.

After migrating our process instance, we can now complete the service task A to reach user task B.

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 A and B. Instead, it only contains a new service task C.

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 C.

note

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 A.

tip

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.

note

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 send_mail. In the target process definition, the job type expression is changed as follows:

= order.next_step

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.

tip

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.

Limitations

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 sourceElementId once.
• A mapping instruction's sourceElementId must refer to an element existing in the process instance's process definition.
• A mapping instruction's targetElementId must 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 subprocess
  • An element that was nested in a subprocess is no longer nested in that subprocess
• 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.

tip

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.

Use at your own risk

Process instance migration is a powerful tool to change your process instances. However, use it with care. You can migrate the process instance to create situations that are not reachable by the regular execution. Consider the following example:

The process instance completed the first tasks A and B and waits on task C.

We could apply the following migrations, but the process instance may end up in an unintended situation:

• If we map task C to A, the process instance is stuck on the parallel gateway.
• If we map task C to D, the variables that would be provided by the message are not set, the task D could be processed with the wrong input.

The process instance doesn't detect these situations. It is up to you to apply suitable migrations.

When in doubt, we recommend testing your migration on a non-production cluster, or using zeebe process test.

tip

Often it's safer to migrate in multiple smaller steps rather than in one big migration. For example, you can start by migrating the process instance introducing changes to the inactive parts only to keep the current situation unchanged.

In some cases it's useful to prepare the process instance before migrating. If your process needs specific variables immediately after migrating, you can set these before migrating the process instance. Both global and local variables are migrated automatically. Before migrating, you can also use process instance modification activating an element to avoid the process instance getting stuck on a parallel gateway, or terminate an element instance to get rid of a parallel flow.