In our previous post, Evolving Workflows Without the Baggage, we introduced cross-Business Service migration in BAMOE 9.6.0. That capability established the recommended process evolution model: one Business Service, one process version, allowing teams to evolve process definitions across separate service deployments while sharing the same underlying database.

While interactive migration through BAMOE Management Console works well for planned maintenance windows, modern deployment strategies such as Blue/Green deployments require process migrations to happen automatically as part of the deployment itself.

To bridge this gap, BAMOE 9.6.0 introduces Automatic Startup Migration for the BAMOE Process Instance Migration (PIM) Add-on. This feature enables pre-validated migration plans to execute automatically during Business Service startup, delivering a zero-touch, pipeline-friendly workflow evolution path.

Authoring and Validating Migration Plans in Staging

Automatic Startup Migration separates plan authoring from production execution. The recommended practice is to author and test your migration plan in a non-production staging environment where realistic test instances exist:

1. Connect your staging services to the BAMOE Management Console.
2. Navigate to Process Instance Migration and author your plan by mapping nodes between the source and target process definitions.
3. Test the migration on staging instances to ensure it completes successfully and that instances reach the expected state.
4. Click the new Export button in the Management Console (or call GET /pim/plan/{id}/export) to download the portable JSON Migration Plan Spec file.

Automatic Migration Execution at Startup

Automatic Startup Migration relies on Migration Plan Specs—portable JSON files that capture process coordinates, node mappings, and optionally source process definitions.

{
  "name": "Hiring process v1 to v2",
  "sourceProcessId": "hiring",
  "sourceProcessVersion": "1.0",
  "targetProcessId": "hiring",
  "targetProcessVersion": "2.0",
  "sourceProcessXml": "...", // Optional: included when exported with "Include source process XML"
  "nodeMapping": [
    { "sourceId": "_nodeA", "targetId": "_nodeB" }
  ]
}

The Startup Execution Flow

When a Business Service boots with bamoe.pim.migrate-on-start.enabled=true, the PIM Add-on runs through the following sequence before completing startup:

1. Migration Plan Spec Discovery: The configured plans-path directory is scanned for *.json Migration Plan Spec files.
2. Upfront Batch Validation: All discovered Migration Plan Specs are validated upfront before any database records are modified.
3. Plan Processing: The discovered Migration Plan Specs are processed in execution order. For each plan:
   • Plan Registration (INSTALLED type): The Migration Plan Spec is registered as an INSTALLED Migration Plan in the database, or reused when a matching checksum is already present.
   • Plan Execution: The migration runs sequentially, moving active process instances, user tasks, and scheduled jobs to the target version.
4. Readiness Completion: Startup migration finishes, allowing health readiness probes to transition to READY (200 OK).

Strict Upfront Validation & Fail-Fast

Before applying any changes, all Migration Plan Specs are validated upfront:

• Directory and format checks: Verifies that the configured plans directory exists and that all discovered Migration Plan Spec files are valid JSON documents.
• Migration stack integrity: Ensures the discovered plans form a consistent migration path and that no duplicate coordinates, self-loops, or circular migration relationships exist.
• Target definition existence: Verifies that every target process definition exists in the running application.
• Optional XML validation: If a Migration Plan Spec includes sourceProcessXml, the XML structure is verified against the target process definition.

Any validation failure is fatal: startup stops immediately, and all Business Service replicas terminate before serving any requests.

Deterministic Execution Order

When multiple Migration Plan Spec files exist in the plans directory, they are executed in alphabetical filename order. Using clear file naming prefixes gives you full control over the sequence when migrating multiple processes or evolving across multiple versions in a single deployment:

/opt/pim/plans/
├── 001-hiring-v1-to-v2.json
├── 002-order-fulfillment-v1-to-v2.json
└── 003-hiring-v2-to-v3.json

Coordination in Distributed Environments

In production deployments running multiple Business Service replicas, the PIM Add-on coordinates execution automatically across all starting replicas:

• Migration Executor: The first Business Service replica to begin the startup sequence assumes responsibility for running the migration. It performs upfront validation, registers the installed plans, and executes the migration.
• Waiting Replicas: Other Business Service replicas detect that migration is already in progress, pause their startup, and wait for the Migration Executor to complete.
• Readiness Probes: All Business Service replicas report NOT READY via integrated health checks (SmallRye Health on Quarkus, Spring Boot Actuator on Spring Boot). No traffic is routed to the new version until migration completes successfully.
• Fail-Fast Safety: If a migration or validation fails, the Migration Executor fails startup, and all waiting replicas terminate immediately. This fail-fast design guarantees that no Business Service ever serves traffic against an un-migrated or inconsistent database state.
• Idempotent Restarts: Once a Business Service version completes migration with SUCCESS, subsequent restarts or scale-out events skip migration entirely and become ready immediately.

Step-by-Step: The Zero-Touch Migration Process

The following moments illustrate the end-to-end lifecycle from staging authoring to production cutover:

Moment 0 — Baseline (Production)

Business Service v1 is live in production with hiring:1.0, actively processing customer requests and persisting instances in the shared database.

Moment 1 — Author & Export (Staging, in parallel)

In parallel with production operations, developers update the process definition to hiring:2.0. In the staging environment, the team uses BAMOE Management Console to author the migration plan, validate it on staging data, and export the resulting Migration Plan Spec JSON file.

Moment 2 — Deploy Business Service v2 with Autostart (Production)

The CI/CD pipeline deploys Business Service v2 (hiring:2.0) with bamoe.pim.migrate-on-start.enabled=true. The exported Migration Plan Spec file is mounted into the deployment filesystem (e.g., via a Kubernetes ConfigMap or volume at /opt/pim/plans). Business Service v2 boots and coordinates startup migration before becoming ready to receive traffic.

To ensure a consistent migration, process instances being migrated should not receive user interactions while startup migration is in progress.

Moment 3 — Startup Migration, Cutover, and Cleanup

During startup, Business Service v2 validates the Migration Plan Spec and automatically migrates active instances from 1.0 to 2.0. Once migration completes:

1. Health readiness probes transition to READY (200 OK).
2. Traffic switches seamlessly to Business Service v2.
3. Business Service v1 is safely decommissioned.

Error handling and recovery: Because startup migration runs before health readiness probes pass, any failure causes the service to fail fast—preventing live traffic from reaching an unready deployment. If an error occurs, operators should fix the Migration Plan Spec or configuration in staging, clear the failure lock in the PIM database schema, and trigger a fresh deployment. For full recovery details, refer to the BAMOE documentation. ⚠️

Prerequisites and Configuration

Shared Database

Important: Cross-Business Service migration requires both Business Services to connect to the same database. Without a shared database, the PIM Add-on in the target service cannot access the process instances it needs to migrate. Apply the BAMOE 9.6.0 DDL migration scripts before running migrations to update your schema and create the required PIM tables.

Maven Dependencies

Add the BAMOE PIM Add-on dependency to your Business Service pom.xml:

For Quarkus:

<dependency>
    <groupId>com.ibm.bamoe</groupId>
    <artifactId>bamoe-addons-quarkus-pim</artifactId>
</dependency>

For Spring Boot:

<dependency>
    <groupId>com.ibm.bamoe</groupId>
    <artifactId>bamoe-addons-spring-boot-pim</artifactId>
</dependency>

Tip: In your staging environment, ensure the source Business Service includes the source files add-on (kie-addons-quarkus-source-files or kie-addons-springboot-source-files) so BAMOE Management Console can load the source BPMN definitions during plan authoring.

Configuration Properties

Configure startup migration in application.properties:

# Enable automatic PIM execution at startup (default: false)
bamoe.pim.migrate-on-start.enabled=true

# (Optional, defaults to '/opt/pim/plans') Absolute filesystem path to the directory containing Migration Plan Spec *.json files
bamoe.pim.migrate-on-start.plans-path=/opt/pim/plans

# (Quarkus only, optional) Maximum migration transaction timeout in seconds (default: 3600)
bamoe.pim.transaction-timeout=3600

Best Practices

• Always author and test migration plans in staging: Validate node mappings and run test migrations on staging instances before exporting Migration Plan Specs for production.
• Ensure both services share the same database: Cross-Business Service migration relies on the target service having direct database access to source process instances.
• Prevent user interactions during migration: To ensure data consistency, traffic to the source Business Service should be stopped while migration is in progress, preventing users from interacting with active process instances being migrated.
• Use clear naming conventions for Migration Plan Specs: Prefix file names (such as 001-..., 002-...) to make intended multi-step or multi-process execution order deterministic.
• Back up the database before major production rollouts: While fail-fast protections prevent traffic routing on failure, backups remain standard practice for enterprise database operations.

Wrapping Up

Automatic Startup Migration in BAMOE 9.6.0 completes the process evolution story for containerized, cloud-native deployments. By combining visual plan authoring in staging with automated, pre-readiness execution in production, teams can safely evolve long-running workflows within modern CI/CD and Blue/Green pipelines while benefiting from zero manual intervention and built-in safeguards.

For more technical details, check out the updated BAMOE documentation.