> ## 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, individually or in bulk.

export const release_0 = "5.11"

<Badge color="blue" icon="cloud">SaaS · {release_0}</Badge>

<Info>
  **Available on SaaS with FlowX.AI {release_0}.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.
</Info>

## 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](./update-process-variables) - you use it to fix forward
without asking end users to restart.

You can migrate:

* **A single instance** - from its contextual menu on the Process instances page.
* **Instances in bulk** - all eligible instances on a source build, from the Operations page.

<Frame>
  ![Migrate process instances](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/migrate-process-instances.png)
</Frame>

## 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 **Operations** action. The acting user needs
the **Operations** permission in the workspace. The built-in `operations_editor`
(`workspace_operations_editor`) role grants it, and `workspace_admin` includes it by default.

For the full permission breakdown, see the
[Roles and permissions matrix](/5.9/setup-guides/access-management/roles-permissions-matrix) and
[Workspaces access rights](/5.9/setup-guides/access-management/workspaces-access-rights).

## Migrate a single instance

<Steps>
  <Step title="Open the process instance menu">
    Go to **Runtime → Active Process → Process instances**, then open the contextual menu
    (three dots) on the instance you want to migrate and select **Migrate**.
  </Step>

  <Step title="Choose the target build">
    Select the **target build** to migrate the instance to. Builds are listed newest first
    (descending by build creation date).
  </Step>

  <Step title="Map unmatched nodes">
    On the Migration page, review how the instance's active node maps into the target build.
    If the active node does not exist in the target build, the token is repositioned per the
    [node mapping rules](#node-mapping-when-a-node-is-missing).
  </Step>

  <Step title="Start the migration">
    Confirm to run the migration. When it completes, the instance runs on the target build and
    its previously active tokens are marked **Migrated** (see [After migration](#after-migration)).
  </Step>
</Steps>

## Migrate instances in bulk

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

<Steps>
  <Step title="Open Bulk migrate">
    Go to **Runtime → Operations**, open the menu (three dots, top right) and select
    **Bulk migrate**.
  </Step>

  <Step title="Select source and target builds">
    In the modal, choose the **Source build** and the **Target build**. Both lists are ordered
    newest first (descending by build creation date). Click **Continue**.
  </Step>

  <Step title="Review the Migration page">
    The Migration page shows the number of **running instances** eligible for migration
    (instances in STARTED or ON HOLD status), the source and target builds (read-only), and the
    node mapping section.
  </Step>

  <Step title="Map unmatched nodes">
    Resolve any active nodes that do not exist in the target build, per the
    [node mapping rules](#node-mapping-when-a-node-is-missing).
  </Step>

  <Step title="Start the migration">
    Click **Start** to run the bulk migration.
  </Step>
</Steps>

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

## Node mapping (when a node is missing)

When an active token sits on a node that does not exist in the target build, the token is
repositioned to the previously visited node. 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, so this is not a case you should migrate into. 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.                                                                                                               |

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

## 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.
</Warning>

## Related resources

<CardGroup cols={2}>
  <Card title="Process instance" icon="diagram-project" href="./process-instance">
    Monitor instance status, tokens, and canvas color coding.
  </Card>

  <Card title="Update process variables" icon="pen-to-square" href="./update-process-variables">
    The other in-flight corrective action for running instances.
  </Card>

  <Card title="Roles and permissions matrix" icon="shield-halved" href="/5.9/setup-guides/access-management/roles-permissions-matrix">
    The Operations permission that governs migration.
  </Card>
</CardGroup>


## Related topics

- [Process definition](/5.9/docs/building-blocks/process/process-definition.md)
- [Process instance](/5.9/docs/projects/runtime/active-process/process-instance.md)
- [Get build info by process instance](/5.9/docs/api/start-process/build-info-by-process-instance.md)
- [Start process and copy data from another instance](/5.9/docs/api/start-process/start-with-copy-data.md)
- [Process Designer](/5.9/docs/building-blocks/process/process.md)