Adjust source code
Camunda 8 has a different workflow engine than Camunda 7 - Zeebe. As a result, you must migrate some of your code to work with the Zeebe API, especially code that does the following:
- Uses the Client API (e.g. to start process instances)
- Implements service tasks, which can be:
- External tasks, where workers subscribe to the engine.
- Java code attached to a service task and called by the engine directly (in-VM).
For example, to migrate an existing Spring Boot application, take the following steps:
- Adjust Maven dependencies:
- Remove Camunda 7 Spring Boot Starter and all other Camunda dependencies.
- Add the Spring Zeebe SDK.
- Adjust config:
- Set Camunda 8 credentials (for example, in
src/main/resources/application.yaml) and point it to an existing Zeebe cluster. - Remove existing Camunda 7 settings.
Add
@ZeebeDeployment(resources = "classpath*:**/*.bpmn")to automatically deploy all BPMN models.Adjust your source code and process model as described in the sections below.
Client API
The Zeebe API (e.g. the workflow engine API - start process instances, subscribe to tasks, or complete them) has been completely redesigned and is not compatible with Camunda 7. While conceptually similar, the API uses different method names, data structures, and protocols.
If this affects large parts of your code base, you could write a small abstraction layer implementing the Camunda 7 API delegating to Camunda 8, probably marking unavailable methods as deprecated. We welcome community extensions that facilitate this but have not yet started our own efforts.
Service tasks as external tasks
External task workers in Camunda 7 are conceptually comparable to job workers in Camunda 8. This means they are generally easier to migrate.
The "external task topic" from Camunda 7 is directly translated in a "task type name" in Camunda 8, therefore camunda:topic gets zeebe:taskDefinition type in your BPMN model.
The community-supported Camunda 7 Adapter picks up your @ExternalTaskHandler beans, wraps them into a JobWorker, and subscribes to the camunda:topic you defined as zeebe:taskDefinition type.
Service tasks with attached Java code (Java delegates, expressions)
In Camunda 7, there are three ways to attach Java code to service tasks in the BPMN model using different attributes in the BPMN XML:
- Specify a class that implements a JavaDelegate or ActivityBehavior:
camunda:class. - Evaluate an expression that resolves to a delegation object:
camunda:delegateExpression. - Invoke a method or value expression:
camunda:expression.
Camunda 8 cannot directly execute custom Java code. Instead, there must be a job worker executing code.
The community-supported Camunda 7 Adapter implements such a job worker using the Spring Zeebe SDK. It subscribes to the task type camunda-7-adapter. Task headers are used to configure a delegation class or expression for this worker.
You can use this worker directly, but more often it might serve as a starting point or simply be used for inspiration.
The community-supported Camunda 7 to Camunda 8 Converter will adjust the service tasks in your BPMN model automatically for this adapter.
The topic camunda-7-adapter is set and the following attributes/elements are migrated and put into a task header:
camunda:classcamunda:delegateExpressioncamunda:expressionandcamunda:resultVariable