Moving process instances between environments

Draft comment:
This topic is shared by BAW, CP4BA. Last updated on 2026-04-29

You can use process instance move feature to move in-flight process instances in a process application snapshot from traditional Business Automation Workflow environments to Business Automation Workflow on container environments without moving the entire database.

What is the process instance move

Process instance move is a capability that helps you to move in-flight process instances for a specific process application snapshot from traditional on-premises environments to Business Automation Workflow on container. Unlike a full database move, this approach supports a phased strategy helping you to move data snapshot by snapshot in a 'divide and conquer' fashion.

Key characteristics

Snapshot-level move of in-flight process instances (not entire database).
Transfers active, failed, and suspended instances; terminated and completed instances are not moved.
Preserves process instances state and data during the move.
After successful move, the snapshot in the source environment is deactivated, its active instances are suspended, and the snapshot can be removed from the source environment.
Supports cross-database and cross-platform move.

Why process instance move is needed

Moving from traditional Business Automation Workflow to containerized environments introduces challenges when handling high volumes of process instances. The process instance move capability addresses these problems by:

Minimize business disruption: Instead of moving all data during a single maintenance window while the server is shut down, customers can move data incrementally during non-peak hours while the server remains active.
Phased move: Move process instances for process application snapshots incrementally rather than all at once. This approach allows users to prepare, test, and move progressively in a "divide and conquer" fashion, significantly reducing the overall complexity of the system migration. Crucially, because the process instances are isolated by snapshot, a failure during the move of one snapshot does not disrupt or destroy the rest of the system.
Support hybrid environments: Run some applications on-premises while others run in containers. While certain applications can be easily migrated to Business Automation Workflow on containers, this feature helps you to seamlessly move those specific process instances from traditional Business Automation Workflow to the modernized Business Automation Workflow on container environment. Meanwhile, process instances that are incompatible with Business Automation Workflow on containers can continue running undisturbed on your traditional infrastructure.

Accessing the move capability

Access the process instance move capability from the Installed Apps page in the Process Admin Console of your source traditional Business Automation Workflow environment. From there, you can select a snapshot (either active or inactive) and initiate the move workflow. For more information, see Moving process instances (detailed procedure).

Move workflow

The process instance move workflow consists of four main phases:

Preparation: Complete all the required preparation steps in both the source and target environments. To ensure minimal operational impact, choose non-peak hours and back up both databases before proceeding with the move.
Validation: Run validation checks to identify potential issues before the move and ensure that all prerequisites are met. The validation process produces fatal errors under certain conditions, indicating that the move for that specific snapshot is not supported. It might also generate warnings, indicating that the move can proceed, but with caution.
Move: Users can initiate the move, monitor its progress, view the detailed move report, and retry the operation if there is a failure.
Go Live: Activate the snapshot in the target environment and resume the moved process instances. This action cannot be undone; therefore, final verification and specific manual operations are strictly required before officially going live.

Important: Following are the important operational notice for process instance move window:

Targeted operational pause: During the move phase, the execution of process instances strictly within the source snapshot is stopped to ensure absolute data consistency. Plan and schedule your move windows to accommodate this localized operational pause.

System availability reassurance: All process instances in other snapshots remain active and continue to run during this window.

Performance notice and scheduling: However, the overall system performance might be impacted while the move is executing. Because of this potential resource draw, it is highly recommended to schedule and execute your move windows during nonpeak hours to minimize any operational drag on active workflows.

The concept of freeze and unfreeze a snapshot

Before initiating a process instance move operation, execution of the process instances within the specific snapshot is stopped. This freezing operation ensures strict data consistency during the move process.

What is frozen: The specific process application snapshot is deactivated, and its active process instances are suspended.
What remains active: Other process applications and unaffected snapshots in the source environment continue to operate normally.
Duration: After going live in the target environment, the snapshot remains frozen indefinitely in the source environment. Administrators can choose to remove or archive them at their discretion.
User impact: While the source process instances are frozen, users cannot start new process instances, nor can they modify or interact with existing process instances belonging to that frozen snapshot.
Rollback and recovery: If you decide to cancel the move process and revert to the original state:
- Before the move starts: You can unfreeze the snapshot in the source environment to restore normal operations.
- After the move starts or completes (but before going live): You can remove the moved data from the target environment and unfreeze the snapshot in the source environment to return it to normal operation.

Preparation Checklist

Before initiating a process instance move, thoroughly verify the following prerequisites. Ensure that all process instance move testing is successfully completed in a non-production (test) environment before scheduling any production move.

Application readiness

Deployment and compatibility: Ensure the process application and its dependent toolkits are enabled for both traditional and container environments, and successfully deployed to both the source and target environments. Once deployed, run Instance Migration to migrate all existing instances in the source environment to the new snapshot.
Functional validation: The process application must pass all functional tests in the target container environment.
Target environment cleanup: The process application snapshot in the target environment must be deactivated. Any associated test process instances must be terminated and deleted. To understand how to prepare the test environment, see Testing process instance move in a test environment

Environment configuration

Messaging architecture: Do not use the embedded JMS server within the target Business Automation Workflow on containers deployment. Use an independent, stand-alone JMS pod instead. For configuration details, see Customizing an independent JMS server.
Storage capacity: Ensure that the target database has sufficient disk space that is allocated to accommodate the volume of moved data.
Network topology: Verify robust, low-latency network connectivity between the source and target environments.
Time synchronization: System clocks must be strictly synchronized between the source and target infrastructures across both the operating system and database servers.
Important: Time zones across environments must be mathematically identical; for example, America/New_York is distinct from America/Jamaica due to differing Daylight Saving Time rules. Because you cannot change the time zone on an existing IBM Business Automation Workflow server that have in-flight process instances. You cannot reconfigure an existing target environment if its time zone mismatches the source. Therefore, if your existing target environment has a conflicting time zone, you must provision and use a brand-new, fresh installation as your target environment.
Identity management: Both the source and target environments must connect to and use the exact same LDAP server.
Database connection scaling: The target database must be configured to support an increased connection load. The source environment requires approximately 50 more concurrent connections to the target database during the move process. Ensure that you increase the maximum allowed database connections and optimize relevant database-level transaction parameters (for example, max_prepared_transactions in PostgreSQL).

Version requirements

To ensure API and schema compatibility, your environments must meet or exceed the following version thresholds:

Source environment: Traditional Business Automation Workflow 26.0.0.0 or later
Target environment: Business Automation Workflow on Containers 26.0.0.0 or later

User access and privileges

Ensure that the migration team provisioned the following administrative permissions before execution:

Console access: Full administrative access to the Process Admin Console in both the source and target environments.
Database privileges: Database Administrator (DBA) access to both databases for validation, performance monitoring, and troubleshooting.
Cluster privileges: Kubernetes or Red Hat OpenShift cluster administrator access (required for inspecting logs, tracking pods, and troubleshooting target container infrastructure).

Test before moving production data

Important: Test the process instance move in a non-production environment before performing an instance move in the production environment. For testing instructions, see Testing process instance move in a test environment.

This testing phase is a critical prerequisite before performing a production instance move. Executing a test move provides the following key benefits:

Validate environment compatibility: Verify that the instance move can complete successfully between the designated source and target environments.
Ensure runtime state continuity: Verify that all moved process instances (Active, Failed, and Suspended) can seamlessly resume, retry, or continue execution to completion in the target environment with zero errors and total parity with the source environment.
Refine manual procedures: Identify and document any environmental anomalies, validate prerequisite configurations, and ensure that the deployment team is fully familiar with all required manual steps.
Establish baseline benchmarks: Estimate the execution duration to accurately plan your production move window. Because every environment features a unique combination of hardware, database performance, and network infrastructure, move speeds vary. For Business Automation Workflow environments with a high volume of active process instances, baseline testing is essential to determine whether the move takes minutes or hours.
Validate rollback and recovery strategies: Test the process instance move cancellation and snapshot unfreezing procedures. Mastering these recovery steps during testing is crucial for mitigating risks and handling unexpected failures during the production window.

Complete this validation before you begin the production procedure in Moving process instances (detailed procedure). For a detailed testing procedure, see Testing process instance move in a test environment.

Supported configurations

Process instance move supports the following configurations:

Database combinations

16 database combinations are supported, allowing move from any supported source database to any supported target database. See Supported database combinations for process instance move for the complete matrix.

Document repositories

No automated document move in 26.0.0.
Manual move required: IBM BPM target stores documents, external document repositories, and custom storage solutions.

Limitations and restrictions

Documents added from a process can be stored in any of the following document stores:

IBM BPM document store: Typically it is the DOCS object store in a Business Automation Workflow environment. Documents can be added to the DOCS object store and are of the type IBM_BPM_Document class.
IBM BPM target store: Typically the default target object store created in a Business Automation Workflow environment. Documents can be added from the context of a Case solution, but can also be added from a process.
External ECM server object store: Object stores that are configured with an external CMIS endpoint URL and defined as an environment variable in the process application.

Supported scenarios

Process instance move is supported for external ECM server object stores (scenario 3 under Limitations and restrictions). Configure the connection to the external ECM server and establish a successful connection from the target container environment.

Process instance move does not copy documents from the source environment to the target environment. Documents must be manually copied from the source IBM BPM target store to the target IBM BPM target store.

Not supported scenarios

Warning: Snapshot-based process instance move is strictly unsupported if process documents are stored in the IBM BPM document store (DOCS object store). Because these instance-associated documents can be accessed and modified concurrently by process instances running on other snapshots (which are not part of the move operation), proceeding would compromise data consistency. To prevent this cross-snapshot data conflict, the system will not allow the process instance move operation if documents of type IBM_BPM_Document class are detected in the DOCS store.

Manual steps after moving process instances

Important: In version 26.0.0, the following data types and components are not included in automated move workflows and require manual handling before activating the application snapshot in the target environment:

IBM BPM target store documents: Documents that are stored in the source IBM BPM target store do not automatically move. Manually copy these documents to the target environment's store based on your specific application snapshot logic. Ensure all process instances leveraging these documents are fully moved and available in the target environment.
Local group memberships: Manually reconcile local group memberships in the target environment to resolve any discrepancies with the source. Failure to align these groups results in broken ownership and authorization issues.
Custom configuration files: Application-specific configuration and property files must be manually moved to the target server directory structure.
Integration endpoints: External service connections and endpoints must be manually updated and reconfigured to point to target environment resources.
LDAP configuration: User registry settings, directory mappings, and LDAP server connections must be manually replicated and tested in the target environment.

Verification step: Thoroughly validate all preceding components before proceeding with the final "go-live" step of activating the snapshot in the target environment.

Other limitations

Use the Process Admin Console UI: Using the Instance Move REST APIs that are available in Swagger UI can be error-prone. To avoid unnecessary errors, use the out-of-the-box (OOB) Instance Move UI in the Process Admin Console.
Workflow Process Service not supported: Process instances running on a Workflow Process Service architecture cannot be moved by using this utility.
LDAP configuration in source environment are not replicated: LDAP configuration must be manually replicated to the target environment.
Case-related runtime data move is not supported: Use Moving case instances from traditional Business Automation Workflow to Business Automation Workflow on containers for case instance move.
Single-Source to Multiple-Targets only: This capability supports moving only from a single source environment to one or more target environments. Consolidating or merging process instances from multiple distinct source environments into a single target environment is strictly unsupported.
One-time operation: Each process app snapshot can be moved only one time.
Business Automation Insights limitation: If Business Automation Insights is enabled in the target environment, moved instances are not to be available in the target BAI. However, new process instances that are created in the target environment is available in the target BAI as expected.