Camunda’s default behavior of any given process instance is to follow the exact version of a process definition that was there the moment the instance started.
However, sometimes process may change and the change should be applied not only for newly created instances, but also for instances created before this change.
In this case existing process instances should be updated not only to bind to the new process definition, but some process state modifications may also be required.
This is what we call “process migration” and what Camunda7-migration library was created for.
- Process state manipulation via Camunda API
- Incremental migration strategy with SemVer support
- Ability to change process schema without rolling out a new version of a process definition — works great for testing and debugging on Dev-environments
- Appropriate migrations are applied on application start-up automatically and in a declarative manner — no need for explicit invocation of any routine
- Migrations are applied in the same transaction in which new process definitions are loaded — this prevents data corruption due to incompatibility of process state with process schema.
#Compatibility
Camunda7-migration library works on java 8 and higher, camunda 7 and spring 5/spring boot 2.
A few steps should be completed in order to configure and start using Camunda7-migration library.
Add Camunda7-migration dependency to pom.xml
<dependency>
<groupId>com.atomazing.alba</groupId>
<artifactId>camunda7-migration</artifactId>
<version>{camunda7-migration.version}</version>
</dependency>Add @EnableCamundaMigration to configuration class
@Configuration
@EnableCamundaMigration
public class CamundaMigrationConfiguration {
}Camunda7-migration library uses version tag for managing process definition versions, so start with adding it to a process definition in bpmn schema:
<bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL" xmlns:bpmndi="http://www.omg.org/spec/BPMN/20100524/DI" xmlns:dc="http://www.omg.org/spec/DD/20100524/DC" xmlns:camunda="http://camunda.org/schema/1.0/bpmn" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:di="http://www.omg.org/spec/DD/20100524/DI" id="Definitions_1uko44i" targetNamespace="http://bpmn.io/schema/bpmn" exporter="Camunda Modeler" exporterVersion="5.14.0">
<bpmn:process id="process-id" name="ProcessName" isExecutable="true" camunda:versionTag="01.01.01">
...
</bpmn:process>
</bpmn:definitions>While version tag may have any format, it should be sortable. For example, Maven versions may be used. All process definitions should have a version tag. Consider the following requirements for subprocess versioning:
- Subprocess should have version tag
- If parent process changed, child process may keep old version
- If subprocess changed, parent process should be updated
- A subprocess should be called from a parent process with specific version defined (Call Activity Shape > Binding > Version Tag)
Implement migration logic in a Java class implementing com.atomazing.alba.camunda7.migration.api.CamundaMigration interface and add it as a component to a Spring application context.
@Component
class AcmeProcessMigration implements CamundaMigration {
@Override
public String key() {
return "acme-process"; // process definition key
}
@Override
public String source() {
return "1.1.0"; // source version tag
}
@Override
public String target() {
return "1.2.2"; // target version tag
}
@Override
public void migrate(CamundaMigrationContext context) {
// Migration code.
}
}Where:
- method
key()returns process definition id for which this migration should be applied, - method
source()returns a source version of process definition, - method
target()returns target version, - method
migrate(CamundaMigrationContext context)implements migration with using Camunda API: Process Instance Migration, Process Instance Modification
@Override
public void migrate(CamundaMigrationContext context) {
// Getting source process definition id
String sourceDefinitionId = context.getSourceDefinition().getId();
// Getting target process definition id
String targetDefinitionId = context.getTargetDefinition().getId();
RuntimeService runtimeService = context.getProcessEngine().getRuntimeService();
// Creating migration plan from source to target by using Camunda migration api
runtimeService.newMigration(runtimeService
.createMigrationPlan(sourceDefinitionId, targetDefinitionId)
.mapEqualActivities()
.build())
.processInstanceIds(context.getProcessIds()) // context includes process instance ids on source process definition version
.skipCustomListeners()
.skipIoMappings()
.execute();
}@Override
public void migrate(CamundaMigrationContext context) {
// Getting source process definition id
String sourceDefinitionId = context.getSourceDefinition().getId();
// Getting target process definition id
String targetDefinitionId = context.getTargetDefinition().getId();
RuntimeService runtimeService = context.getProcessEngine().getRuntimeService();
TaskService taskService = context.getProcessEngine().getTaskService();
// Creating migration plan from source to target by using Camunda migration api
runtimeService.newMigration(runtimeService
.createMigrationPlan(sourceDefinitionId, targetDefinitionId)
.mapEqualActivities()
// All instnces on old shape 'fill-data' map to shape 'fill-data-migration' in new version
.mapActivities("fill-data", "fill-data-migration")
.build())
.processInstanceIds(context.getProcessIds())
.skipCustomListeners()
.skipIoMappings()
.execute();
// Closing task fill-data-migration
taskService.createTaskQuery()
.processInstanceIdIn(context.getProcessIds().toArray(String[]::new))
.list().stream()
.filter(task -> task.getTaskDefinitionKey().equals("task-migration"))
.map(Task::getId)
.forEach(taskService::complete);
}Camunda7-migration uses incremental strategy for migration.
For example, we have process with versions 01.01.01, 01.01.02 and 01.02.01 and migration scripts from 01.01.01 to 01.01.02 and from 01.01.02 to 01.02.01.
On service startup Camunda7-migration library will find all instances with version 01.01.01 and apply migration to 01.01.02. Migrated process instances will get version 01.01.02. Then library will find all instances with version 01.01.02 and apply migration to 01.02.01. Migrated process instances will finally get version 01.02.01.
It's recommended to use version in bpmn file name. Also, it is best practice combining process definitions with same version in one directory. Example:
- src/main/resources/bpmn
- 0101
- acme-process-01.01.01.bpmn
- subprocess-01.01.01.bpmn
- 0102
- acme-process-01.02.01.bpmn
- 0101