migrate-on-deployment

Migration on Deployment of New Process Version

This example demonstrates how to use the Java API for process instance migration to migrate process instances whenever a new version of a process is deployed.

How to Use It?

1. Download, install, and start up a Camunda distribution
2. Checkout the project with Git
3. Import the project into your IDE
4. Build it with maven
5. Deploy the resulting web application to the application server (Note: the example is only compatible with WildFly ≤26)
6. Go to Camunda Tasklist (http://localhost:8080/camunda/app/tasklist/default/#/) and start a process instance of the Example Process
7. Modify the process model (src/main/resources/exampleProcess.bpmn), for example by adding another user task
8. Build it again with maven
9. Re-deploy the web application
10. Go to Camunda Cockpit (http://localhost:8080/camunda/app/cockpit/default/#/) and see that the process instance was migrated

How Does It Work?

The process application class ExampleProcessApplication declares a @PostDeploy hook. This is called whenever the application is deployed. The implementation then identifies the latest versions of the deployed process definitions. The migration from the second-latest to the latest version is implemented in #migrateInstancesFromPreviousVersion:

protected void migrateInstances(ProcessEngine processEngine,
    ProcessDefinition sourceDefinition,
    ProcessDefinition targetDefinition) {

  RuntimeService runtimeService = processEngine.getRuntimeService();

  MigrationPlan migrationPlan = runtimeService
    .createMigrationPlan(sourceDefinition.getId(), targetDefinition.getId())
    .mapEqualActivities()
    .build();

  LOG.info("Migrating all process instances from " + sourceDefinition.getId() + " to " + targetDefinition.getId());

  runtimeService
    .newMigration(migrationPlan)
    .processInstanceQuery(runtimeService.createProcessInstanceQuery().processDefinitionId(sourceDefinition.getId()))
    .execute();
  // .executeAsync() for asynchronous execution in a batch (useful for large numbers of instances)
}

What Else is There to Know?

• The migration plan is generated by calling #mapEqualActivities on the migration plan builder. See the documentation on migration plan generation for which kind of instruction this method can generate. The example can be extended to explicitly provide instructions via mapActivities to support advanced use cases. Such instructions could be parsed from an accompanying deployment descriptor.
• The implementation is not robust when the process instances to migrate are modified in parallel. Migration may fail with an OptimisticLockingException and roll back in such a case.