> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrate process instances

> Move running process instances from one build to another to apply a corrected process definition without restarting them.

## 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](https://docs.flowx.ai/6.x/docs/projects/runtime/active-process/update-process-variables.md) - 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](#choosing-which-instances-to-move)).

## Eligibility

Only instances that are still running can be migrated:

| Condition | Rule |
| - | - |
| **Instance status** | Only instances in **STARTED** or **ON HOLD** status are eligible. Finished, terminated, expired, and failed instances are not migrated. |
| **Build selection** | The **active** build cannot be the **source**, since its instances are the ones the active policy is serving. It can be the **target**. The only build excluded from the target list is the one already picked as the source. |

\| **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](#corrective-actions-role).

For the full permission breakdown, see the
[Roles and permissions matrix](https://docs.flowx.ai/6.x/setup-guides/access-management/roles-permissions-matrix.md) and
[Workspaces access rights](https://docs.flowx.ai/6.x/setup-guides/access-management/workspaces-access-rights.md).

### 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](https://docs.flowx.ai/6.x/setup-guides/access-management/roles-permissions-matrix.md#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](#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](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/bulk-migration-all-active.png)

**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](#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](#node-mapping-when-a-node-is-missing). Optionally, set
where blocked tokens resume after the migration, see
[Set active token destination](#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.

> [!WARNING]
>
> 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:

| Mode | Use it when |
| - | - |
| **Specific instance UUIDs** | You already know which instances are affected, so you paste their UUIDs. |
| **Instances matching filters** | You know the shape of the problem but not the UUIDs. |
| **All active instances** | You want every eligible instance moved. Instances that cannot be moved are skipped rather than failing the run. |

**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](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/bulk-migration-specific-uuids.png)

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

| Filter | Required | What it matches |
| - | - | - |
| **Process Name** | Yes | Instances of that process definition. |
| **Current Node Name** | No | Instances whose active token sits on that node. |
| **Instance status** | No | The token's status on that node. Pick a node first, since a status on its own has nothing to apply to. |

![The Migrate Instances modal with Instances matching filters selected, showing the Process Name, Current Node Name, and Instance status fields](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/bulk-migration-matching-filters.png)

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.

> [!TIP]
>
> 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

| Resolution | Meaning |
| - | - |
| **Ready** | Every active node exists in the target build. Nothing to map. |
| **Need node mapping** | At least one active node does not exist in the target build. Map it before you continue. |
| **Not found on target** | The process does not exist in the target build. All of its running instances are moved to the **TERMINATED** state. Root instances that do not use this process migrate normally. |
| **Swimlanes Mismatch** | A swimlane of the source process no longer exists in the target build. The migration is rejected when you start it, for every process in the run. |

### 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:

| Active node not in target build | Result |
| - | - |
| **General rule** | The active migrated token remains on the previously visited node. |
| **Start Parallel Gateway** | Not supported. The parallel gateway must still exist in the target build. See [Limitations](#limitations). |
| **Embedded subprocess** | Token moves to the previously visited node. All previously visited nodes in the embedded context are removed from token history. |
| **Call Activity** | Token moves to the previously visited node. All started subprocess instances from that node are cancelled. |
| **Node with a boundary event** | Token moves to the previously visited node. |

## 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](https://docs.flowx.ai/6.x/docs/platform-deep-dive/core-extensions/audit.md), 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

> [!WARNING]
>
> * **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.

## Related resources

> [card] [Process instance](https://docs.flowx.ai/6.x/docs/projects/runtime/active-process/process-instance.md)
>
> Monitor instance status, tokens, and canvas color coding.

> [card] [Update process variables](https://docs.flowx.ai/6.x/docs/projects/runtime/active-process/update-process-variables.md)
>
> The other in-flight corrective action for running instances.

> [card] [Roles and permissions matrix](https://docs.flowx.ai/6.x/setup-guides/access-management/roles-permissions-matrix.md)
>
> The corrective actions permission that governs migration.


## Related topics

- [FlowX.AI 5.12.0 Release Notes](https://docs.flowx.ai/release-notes/v5.x/v5.12.0-september-2026/v5.12.0-september-2026.md)
- [Move tokens](https://docs.flowx.ai/6.x/docs/projects/runtime/active-process/move-token.md)
- [FlowX.AI Audit](https://docs.flowx.ai/6.x/docs/platform-deep-dive/core-extensions/audit.md)
- [FlowX.AI 6.0.0 Release Notes](https://docs.flowx.ai/release-notes/v6.x/v6.0.0-october-2026/v6.0.0-october-2026.md)
- [Notification center](https://docs.flowx.ai/6.x/docs/flowx-designer/notification-center.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.