Skip to main content

Overview

Process instance migration moves running instances from the build they started on to a different build of the same process, so a fix or change made in a newer build applies to instances that are already in flight. It is an operational corrective action, alongside updating process variables - you use it to fix forward without asking end users to restart. Migration runs from the Corrective Actions page as a bulk migration. To move one instance, start a bulk migration and paste its UUID (see Choosing which instances to move).

Eligibility

Only instances that are still running can be migrated: | UI Flow sessions | UI Flow sessions are not migrated (see Limitations). |

Prerequisites

Migrating process instances is a workspace-level corrective action. The acting user needs the Process instance corrective actions permission in the workspace, granted by the Workspace corrective actions editor role. workspace_admin includes it by default. See Corrective actions role. For the full permission breakdown, see the Roles and permissions matrix and Workspaces access rights.

Corrective actions role

Migration is governed by the Process instance corrective actions permission, granted by the Workspace corrective actions editor role. This role replaces the Workspace operations editor role, and users and groups that had the old role are moved to the new one automatically. workspace_admin includes the permission, and organization admins have it through their workspace admin access. See the Workspace corrective actions editor permission matrix.

Migrate instances in bulk

Bulk migration moves every eligible instance on a source build to a target build in one action.
1

Open Bulk Migration

Go to Runtime → Runtime Control → Corrective Actions, open the menu (three dots, top right) and select Bulk Migration.
2

Configure the migration

In the Migrate Instances modal, choose the Source Build and the Target Build. Both lists are ordered newest first (descending by build creation date). Then, under Which instances do you want to move?, pick a selection mode and fill in its fields; see Choosing which instances to move. Click Continue.
The Migrate Instances modal with Source Build and Target Build selectors and the three selection modes, with All active instances selected
3

Review the Migration Configuration page

The Migration Configuration page shows the source and target builds (read-only) and lists the Processes with running instances, each with a resolution. See Process resolutions.
4

Map unmatched nodes

For each process that needs it, choose where tokens on nodes missing from the target build should go, per the node mapping rules. Optionally, set where blocked tokens resume after the migration, see Set active token destination. Click Continue.
5

Start the migration

The Bulk Migration Summary modal groups the processes by outcome: those that migrate to the target build, and those that remain on the source build and whose instances move to TERMINATED. Click Start Migration to run it. A migration can’t be undone once it starts.
Keep a single bulk run at or below roughly 10,000 instances. Runs of that size perform acceptably. Substantially larger runs degrade and are not recommended.

Choosing which instances to move

Bulk migration no longer means “everything on the build”. The modal offers three selection modes, and you pick one: Specific instance UUIDs shows a Process Instance UUID field taking comma-separated UUIDs, up to 100 in one run. More than that is rejected rather than truncated.
The Migrate Instances modal with Specific instance UUIDs selected and its Process Instance UUID field
Instances matching filters selects by where an instance currently sits, not by its overall state. The three fields cascade: pick a process first, and each later field offers only values relevant to the earlier ones.
The Migrate Instances modal with Instances matching filters selected, showing the Process Name, Current Node Name, and Instance status fields
Before you start the run, the modal reports how many instances the selection matches, and calls out any UUIDs you pasted that can never match so you can correct them rather than wonder why the count is short.
Reach for Instances matching filters when a fix targets a known failure point, such as every instance stuck on one Service Task. It is the difference between moving the instances that need the fix and moving the whole build.

Process resolutions

Set active token destination

Under Set active token destination (post-migration), you can bulk-move tokens that are blocked on a node to another node once the migration completes. For each row, pick the Blocked on Node from the source build and the Resume at Node in the target build. This option is not offered for a process that is not found on the target build.

Node mapping (when a node is missing)

When an active token sits on a node that does not exist in the target build, the mapping defaults to Last visited node: the token is repositioned to the previously visited node. You can pick a specific target node instead. Start nodes and parallel gateways must be mapped to a node of the same kind; Last visited node is not allowed for them. Specific node types have additional effects:

Track the run

Each run appears on the Corrective Actions page with the Migration Bulk type and its status: Draft, Initialized, Pending, In Progress, Completed, or Failed. Click a run to open Migration Status. It shows the source and target builds, the corrective action ID and the per-instance outcome, with Success and Failed filters. The table lists each instance’s Process instance UUID, Process Name, Status, Error and Updated at. The run reaches Completed even when some instances failed to migrate, so check the Failed filter. A run ends in Failed only when it could not dispatch all of its instances.

After migration

On the Process instance page of a migrated instance:
  • Tokens that were active on the source build are shown with the Migrated status.
  • Tokens created after migration are shown with their current status.
  • Nodes on the canvas are color-coded based on the newly created and active tokens.

Audit trail

Every bulk migration is recorded in the audit log, attributed to the user who started it:
  • One entry for the run itself, with the Bulk Migrate Process Instances subject and the Migrate event. The entry records success, or an error with the number of instances that failed to migrate.
  • One Migrate entry per migrated instance, with the Process Instance subject and the instance identifier. A root instance and its subprocesses are audited individually, all with the same outcome: the tree migrates, and rolls back on failure, as a single unit.
To view the run entries, go to Runtime → Runtime Control → Corrective Actions, open the menu (three dots, top right) and select Audit Logs. That view lists corrective action entries only. The per-instance entries appear on each instance’s Audit Log tab.

Limitations

  • UI Flow sessions are not migrated. Any UI Flow session tied to the instance does not carry over to the target build.
  • No undo of a successful migration. Rollback is automatic only if a migration fails; there is no snapshot restore for a migration that succeeded. To correct a bad migration, fix the target build and migrate the instance again (fix-forward).
  • The parallel gateway itself must still exist in the target build. You can change nodes inside the parallel branches and migrate normally. You cannot migrate onto a build where the parallel gateway nodes themselves (the split and the join) no longer exist. A start node or parallel gateway left on Last visited node, or mapped to a different kind of node, is rejected when you start the migration.

Process instance

Monitor instance status, tokens, and canvas color coding.

Update process variables

The other in-flight corrective action for running instances.

Roles and permissions matrix

The corrective actions permission that governs migration.
Last modified on November 9, 2026