Troubleshooting process instance move

Before you begin troubleshooting

Gather the following information before contacting support or attempting to resolve issues:

• Source and target environment details (versions, database types, platforms)
• Error messages from Process Admin Console
• Relevant log files
• Export the contents of the following database tables:
  • BPM_APP_MOVE_TARGET (In source DB and In target DB)
  • BPM_APP_MOVE_META_DATA (In source DB and In target DB)
  • BPM_APP_MOVE_PROGRESS_STATUS (In target DB)

Cannot verify the target environment due to database connection errors

If the source environment fails to connect to the target environment:

Problem

The source environment cannot establish a JDBC connection to the target environment. This direct database connectivity is required for the source environment to execute data move operations.

Solution

1. Apply configuration changes: After adding or modifying target environment details (such as the hostname, port number), you must restart the source environment's Deployment Manager and Business Automation Workflow servers to make the changes effective.
2. Review automatic verification errors: The source environment automatically attempts to verify the target environment information. If a connection cannot be established, inspect the generated error message to identify the root cause and take the appropriate remediation actions.
3. Check SSL security requirements: Client SSL certificate authentication is only supported for PostgreSQL databases. Ensure that your security configuration aligns with the target environment type.

Pairing fails with ID conflicts

If the system detects identifier collisions between the source and target systems, the pairing process fails.

Problem

Process instance or runtime IDs used in the source environment conflict with existing, identical IDs already present in the target environment.

Solution

Review the pairing error message to identify the specific conflicting IDs. While some data conflicts can be remediated, others cannot be resolved dynamically. Choose one of the following remediation paths:

1. Option A (recommended): Select an alternative target environment, or ideally, provision and target a clean, brand-new target environment.
2. Option B: In the target environment, assuming that it is a non-production test environment, use the Swagger UI to delete the process instances, and then perform the pairing again.
3. Option C (for test environment only): Restore the target environment database from the backup that was taken previously. For more information, see Testing process instance move in a test environment
4. After resolving the conflicts or provisioning a clean target, re-attempt the environment pairing process.

Target environment pairing failures

If the environment pairing process fails, review the following common root causes to determine the appropriate remediation path.

Problem

The pairing operation can fail due to configuration mismatches, resource constraints, or environmental conflicts. Common causes include:

• Connectivity issues: Failure to establish a stable JDBC connection to the target database.
• Chronological mismatches: Discrepancies in system or database time or time zone settings between the source and target environments.
• Data obstacles: Identity or record conflicts (such as overlapping process instance IDs) between the two systems.
• Compatibility issues: Architecture or system-level incompatibilities between the deployment platforms.
• Existing pairings: Topology restrictions. A target environment can be paired only with a single source environment; if the target is already paired, it rejects new pairing requests.

Solution

Review the specific error logs generated during the failed pairing attempt. Depending on the root cause identified, follow the dedicated troubleshooting procedure (for example, verifying database credentials, aligning system clocks, or purging conflicting target data) to resolve the issue before re-attempting the pairing operation.

Pairing fails due to time or timezone differences

If the pairing environment operation fails with timestamp-related errors:

Problem

If the system time or time zones are not identical between the source and target environments, the scheduling of process instances move might be inaccurate. Therefore, both the system time and the specific time zone must match exactly across environments. This synchronization must be verified at both the Operating System (OS) level and the Database (DB) level.

The time zones must be identical to avoid scheduling discrepancies introduced by Daylight Saving Time (DST). For example, EST/New York and EST/Jamaica are considered two entirely different time zones because their DST rules differ, even though they might share standard time offset for part of the year.

CAUTION:

If an environment contains any existing process instances, you must not change the time zone of either the Database or the Operating System. Altering these configurations on an active system corrupt the scheduling data and lead to severe runtime scheduling errors. If a time zone mismatch is detected between the source and target environments, the only safe remediation path is to provision and configure a brand-new target environment. However, if it is a non-production environment and you do not care about the existing timestamps in the runtime tables, you can manually synchronize the system time or time zones at the OS and database levels.

Solution

1. Verify time synchronization between source and target environments. Both operating system and database server clocks must be synchronized.
2. On the source environment, check the system time:

   date

3. On the target environment, check the system time:

   date

4. If times differ by more than a few seconds, synchronize the clocks by using NTP (Network Time Protocol) or your organization's time synchronization service.
5. Verify database server time synchronization:

   For Db2

   db2 "VALUES CURRENT TIMESTAMP"

   For Oracle

   SELECT SYSDATE FROM DUAL;

   For SQL Server

   SELECT GETDATE();

   For PostgreSQL

   SELECT NOW();

6. After synchronizing the clocks, retry the pairing operation.

Move blocked due to IBM_BPM_Document documents in IBM BPM document store

If the move is blocked because IBM_BPM_Document documents exist in the IBM BPM document store:

Problem

The pre-move validation fails with an error indicating that documents of type IBM_BPM_Document exist in the IBM BPM document store (DOCS object store). This scenario is not supported for move.

Solution

The move is not supported when IBM_BPM_Document documents exist in the IBM BPM document store. Use one of the following approaches:

1. Remove or migrate IBM_BPM_Document documents from the IBM BPM document store before attempting move.
2. Use an alternative document storage approach:
   • Configure documents to use the IBM BPM target store (default target object store) instead of the IBM BPM document store. Documents in the IBM BPM target store are supported but require manual move.
   • Configure documents to use external ECM servers with CMIS endpoint URLs. External ECM server documents are supported and do not require manual move if properly configured.
3. Contact IBM Support for guidance on migrating IBM_BPM_Document documents to a supported document store type.

Important: For more information about supported and unsupported document store types, see Moving process instances between environments.

Process instance move failure and rollback

If the moving operation fails, you must completely clean the target environment before attempting the move again.

Problem

The move operation was interrupted or failed to complete. The target environment contains partial data and must be cleaned before it can accept a new move attempt.

Solution

1. Review error logs: Go to the Process Instance Move page to review the specific error messages. Take any necessary corrective actions based on the failure details to prevent a repeat occurrence.
2. Purge partial data: Click Remove moved data to clean the target environment database and restore it to a receptive state.
3. Retry operation: When the target environment cleanup finishes successfully, you might re-initiate the data move operation.

Important: If the automated rollback process fails or hangs, do not attempt manual database cleanup. Contact IBM Support immediately for assistance.

Move is sluggish or appears stuck

If the data move process takes longer than anticipated or the progress indicator ceases to advance:

Problem

When moving large volumes of process instance data naturally requires extended processing time, an operation might genuinely experience an infrastructure issue. If the progress bar shows no movement for an extended period, and you believe that the moving operation is progressing unreasonably slowly or beyond your anticipated window.

Solution

1. Verify whether the process is genuinely stuck: Even if the progress bar appears to be frozen, you can run the following queries to verify actual database activity:
   • If the progress bar is below 50%: Run this query multiple times to see whether rows_read and rows_copied in the last few rows continue to increase:

     SELECT table_name, total_rows, rows_read, rows_copied, rows_deleted, status, error
     FROM BPM_APP_MOVE_PROGRESS_STATUS
     WHERE action_type = 0
     AND started_time IN (
         SELECT MAX(started_time)
         FROM BPM_APP_MOVE_PROGRESS_STATUS
         WHERE action_type = 0
     )
     ORDER BY started_time DESC, status, total_rows;

   • If the progress bar is above 50%: Run this query multiple times to see whether rows_read and rows_copied in the last few rows continue to increase:

     SELECT table_name, total_rows, rows_read, rows_copied, rows_deleted, status, error
     FROM BPM_APP_MOVE_PROGRESS_STATUS
     WHERE action_type = 1
     AND started_time IN (
         SELECT MAX(started_time)
         FROM BPM_APP_MOVE_PROGRESS_STATUS
         WHERE action_type = 1
     )
     ORDER BY started_time DESC, status, total_rows;

2. Halt the operation: Stop the current move attempt.
3. Analyze the logs: Review the move report to identify any underlying errors or warnings, and resolve any discovered issues.
4. Audit environment health: Verify that both the source and target systems are operating normally. Specifically check:
   • CPU and memory usage on the host infrastructure.
   • Database performance metrics and active connection pools.
   • Network routing stability and bandwidth constraints.
5. Purge interrupted data: Click Remove Moved Data to completely clean the partial payload from the target environment.
6. Re-attempt move: Restart the data move process.