Adjusting BPMN models
Ensure your BPMN process models are adjusted as follows to migrate them from Camunda 7 to Camunda 8:
- The namespace of extensions has changed from
http://camunda.org/schema/1.0/bpmn
tohttp://camunda.org/schema/zeebe/1.0
. - Different configuration attributes are used between Camunda versions, as described for each BPMN element below.
- Camunda 8 has a different coverage of BPMN elements (see Camunda 8 BPMN coverage versus Camunda 7 BPMN coverage), which might require some model changes. Note that the coverage of Camunda 8 will increase over time.
The following sections describe the capabilities of the existing community-supported backend diagram converter for relevant BPMN symbols, including unsupported element attributes that cannot be migrated.
General considerations​
The following attributes/elements cannot be migrated:
camunda:asyncBefore
: Every task in Zeebe is always asyncBefore and asyncAfter.camunda:asyncAfter
: Every task in Zeebe is always asyncBefore and asyncAfter.camunda:exclusive
: Jobs are always exclusive in Zeebe.camunda:jobPriority
: There is no way to prioritize jobs in Zeebe (yet).camunda:failedJobRetryTimeCycle
: You cannot yet configure the retry time cycle. Alternatively, you can modify your code to use theretryBackOff
timeout (in ms) for the next retry.
Service tasks​
Migrating a service task is described in adjusting your source code. You will have both BPMN and source code changes.
A service task might have attached Java code. In this case, the following attributes/elements are migrated and put into a task header:
camunda:class
camunda:delegateExpression
camunda:expression
andcamunda:resultVariable
The topic camunda-7-adapter
is set.
camunda:failedJobRetryTimeCycle
: Here, the amount of defined retries is set to thezeebe:taskDefinition retries
attribute.
A service task might leverage external tasks instead. In this case, the following attributes/elements are migrated:
camunda:topic
becomeszeebe:taskDefinition type
.
The following attributes/elements cannot be migrated:
camunda:taskPriority
Service tasks using camunda:connector
will be migrated with the following changes:
camunda:connectorId
becomeszeebe:taskDefinition type
- All inputs and outputs are treated like all other inputs and outputs.
Send tasks​
In both engines, a send task has the same behavior as a service task. A send task is migrated exactly like a service task.
Gateways​
Gateways rarely need migration. The relevant configuration is mostly in the expressions on outgoing sequence flows.
Expressions​
Expressions must be in friendly-enough expression language (FEEL) instead of Java unified expression language (JUEL).
Migrating simple expressions is doable (as you can see in these test cases), but not all expressions can be automatically converted.
The following is not possible:
- Calling out to functional Java code using beans in expressions
- Registering custom function definitions within the expression engine
- Using SPIN library (the FEEL data structure behaves like JSON natively, so SPIN can be omitted or replaced)
- Using the
execution
ortask
User tasks​
Human task management is also available in Camunda 8, but uses a different Tasklist user interface and API.
In Camunda 7, you have different ways to provide forms for user tasks:
- Embedded Task Forms (embedded custom HTML and JavaScript)
- External Task Forms (link to custom applications)
- Camunda Forms
Only Camunda Forms are currently supported in Camunda 8 and can be migrated.
The following attributes/elements can be migrated:
- Task assignment (to users or groups):
bpmn:humanPerformer
bpmn:potentialOwner
camunda:assignee
camunda:candidateGroups
camunda:formKey
, but Camunda 8 requires you to embed the form definition itself into the root element of your BPMN XML models, see this guide.
The following attributes/elements cannot yet be migrated:
- Form handling:
camunda:formHandlerClass
camunda:formData
camunda:formProperty
camunda:taskListener
camunda:dueDate
camunda:followUpDate
camunda:priority
Business rule tasks​
Camunda 8 supports the DMN standard just as Camunda 7 does, so the business rule task can be migrated with the following slight changes:
The following attributes/elements can be migrated:
camunda:decisionRef
tozeebe:calledDecision decisionId
camunda:resultVariable
tozeebe:calledDecision resultVariable
The following attributes are not yet supported:
camunda:decisionRefBinding
,camunda:decisionRefVersion
, andcamunda:decisionRefVersionTag
(always use the latest version)camunda:mapDecisionResult
(no mapping happens)camunda:decisionRefTenantId
A business rule task can also behave like a service task to allow integration of third-party rule engines. In this case, all attributes described above for the service task migration can also be converted.
Call activities​
Call activities are generally supported in Zeebe. The following attributes/elements can be migrated:
camunda:calledElement
will be converted intozeebe:calledElement
- Data mapping
camunda:in
tozeebe:input
camunda:out
tozeebe:output
The following attributes/elements cannot be migrated:
camunda:calledElementBinding
: Currently Zeebe always assumes 'late' binding.camunda:calledElementVersionTag
: Zeebe does not know a version tag.camunda:variableMappingClass
: You cannot execute code to do variable mapping in Zeebe.camunda:variableMappingDelegateExpression
: You cannot execute code to do variable mapping in Zeebe.
Script task​
Only FEEL scripts can be executed by Zeebe. The converter will create internal scripts as long as you are using FEEL scripts.
If you require a different scripting language, a script task can behave like normal service tasks instead, which means you must run a job worker that can execute scripts. One available option is to use the Zeebe Script Worker, provided as a community extension.
If you do this, the following attributes/elements are migrated:
camunda:scriptFormat
camunda:script
camunda:resultVariable
The task type is set to script
.
Message receive events and receive tasks​
Message correlation works slightly different between the two products:
Camunda 7 waits for a message, and the code implementing that the message is received queries for a process instance the message will be correlated to. If no process instance is ready to receive that message, an exception is raised.
Camunda 8 creates a message subscription for every waiting process instance. This subscription requires a value for a
correlationKey
to be generated when entering the receive task. The code receiving the external message correlates using the value of thecorrelationKey
.
This means you must inspect and adjust all message receive events or receive tasks in your model to define a reasonable correlationKey
. You also must adjust your client code accordingly.
The bpmn message name
is used in both products and doesn't need migration.
Multi-instance activities​
Multi-instance activities do exist in the same flavor in Camunda 8 as they did in Camunda 7 (parallel and sequential multi-instance are supported, a loop is not.)
For implementation, the only current limitation is that a loop cardinality is not supported.
These elements cannot be migrated:
bpmn:loopCardinality
These elements can still be used:
bpmn:completionCondition
: Here, the expression has to be transformed to FEEL.
These elements will be converted:
bpmn:multiInstanceLoopCharacteristics camunda:collection
tozeebe:loopCharacteristics inputCollection
bpmn:multiInstanceLoopCharacteristics camunda:elementVariable
tozeebe:loopCharacteristics inputElement
Additionally, there is now a built-in way to collect results using zeebe:loopCharacteristics outputCollection
and zeebe:loopCharacteristics outputElement
. You should consider this before using a workaround (for example, collecting local variables to a collection in parent scope in an exclusive job).