Skip to main content
Version: 8.4

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.


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.

The process instance is waiting at the active service task A.

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.

In the new process version the service task A flows to a user task B.

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.

Once the service task A is completed, the process instance will flow to the user task B.

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.

The process instance is waiting at the active service task A while service task B 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.

The target process only contains a 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.

After migrating the process instance, it is waiting at service task C.


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.


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.

The process instance can be modified to recreate the service task's job.

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


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