Elements Overview
This section documents the BPMN 2.0 elements supported by the engine, organised by family.
Element families
| Family | What's in it |
|---|---|
| Sequence flow | Connections between flow nodes, conditions, defaults |
| Events | Start, end, intermediate (catch/throw), and boundary events with all event definitions |
| Tasks | Service, user, script, business-rule, send, receive, manual, generic |
| Gateways | Exclusive, parallel, inclusive, event-based, complex |
| Structure | Embedded / event / ad-hoc sub-processes, call activities, multi-instance and standard loops |
XML namespaces
Examples in these pages use the standard BPMN and Camunda-style prefixes:
xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL"
xmlns:quantum="http://quantumbpm.com/schema/quantum/bpmn/1.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
Namespace prefixes are resolved by local name, so the same elements work without a prefix (bare <process>, <startEvent>, etc.). Diagrams authored against a Camunda namespace parse without changes — only Camunda-specific runtime extensions need to be mapped to their quantum: equivalents.
Process root
Every executable process lives inside a <definitions> root with one or more <process> children:
<bpmn:definitions
xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL"
xmlns:quantum="http://quantumbpm.com/schema/quantum/bpmn/1.0"
id="Definitions_1"
targetNamespace="http://bpmn.io/schema/bpmn">
<bpmn:message id="Msg_Payment" name="PaymentReceived" />
<bpmn:error id="Err_Timeout" name="TimeoutError" errorCode="ERR_TIMEOUT" />
<bpmn:escalation id="Esc_Review" name="NeedsReview" escalationCode="ESC_REVIEW" />
<bpmn:signal id="Sig_Abort" name="AbortSignal" />
<bpmn:process id="my-process" isExecutable="true">
<!-- flow elements -->
</bpmn:process>
</bpmn:definitions>
A process with isExecutable="true" is the only kind that can be started by the engine. Each process must contain at least one start event. Node IDs must be unique within a process, and every sequence flow's sourceRef and targetRef must resolve to a node in the same scope.
Global definitions
Top-level <message>, <error>, <escalation>, and <signal> elements declare the vocabulary that events and tasks reference by ID. They live at the <definitions> root, outside any <process>.
Message
| Attribute | Required | Notes |
|---|---|---|
id | yes | Used by messageRef on event definitions and message-aware tasks |
name | yes | Logical message name used at runtime for correlation |
Optional quantum:subscription extension declares a FEEL correlationKey expression evaluated per instance to produce the correlation key. Without one, the workflow ID is used. Optional quantum:ttl declares an expiry for buffered messages — an ISO 8601 duration (PT1H), a duration string (1h30m), or an absolute timestamp (2024-12-31T23:59:59Z).
<bpmn:message id="Msg_Payment" name="PaymentReceived">
<bpmn:extensionElements>
<quantum:subscription correlationKey="=orderId" />
<quantum:ttl>PT1H</quantum:ttl>
</bpmn:extensionElements>
</bpmn:message>
Error
| Attribute | Required | Notes |
|---|---|---|
id | yes | Referenced by errorRef on error event definitions |
name | yes | Human-readable name |
errorCode | recommended | Code matched at runtime when an error is thrown; must be unique if boundary events distinguish errors by code |
<bpmn:error id="Err_Timeout" name="TimeoutError" errorCode="ERR_TIMEOUT" />
Escalation
| Attribute | Required | Notes |
|---|---|---|
id | yes | Referenced by escalationRef on escalation event definitions |
name | yes | Human-readable name |
escalationCode | recommended | Code matched at runtime when escalation is thrown |
<bpmn:escalation id="Esc_Review" name="NeedsReview" escalationCode="ESC_REVIEW" />
Signal
| Attribute | Required | Notes |
|---|---|---|
id | yes | Referenced by signalRef on signal event definitions |
name | yes | The broadcast name; must be unique across all signals |
Optional quantum:ttl declares an expiry for buffered signals (same formats as message).
<bpmn:signal id="Sig_Abort" name="AbortSignal">
<bpmn:extensionElements>
<quantum:ttl>PT30M</quantum:ttl>
</bpmn:extensionElements>
</bpmn:signal>
For the runtime semantics — point-to-point delivery for messages, broadcast for signals — see Messages and signals.
Lanes and pools
Lanes are visual groupings only. Each node in a lane is annotated with its lane assignment, but execution is not affected. Pools (participant inside collaboration) similarly map a participant to a process for diagram purposes.
<bpmn:laneSet id="LaneSet_1">
<bpmn:lane id="Lane_Manager" name="Manager">
<bpmn:flowNodeRef>approve-task</bpmn:flowNodeRef>
</bpmn:lane>
<bpmn:lane id="Lane_Clerk" name="Clerk">
<bpmn:flowNodeRef>start</bpmn:flowNodeRef>
<bpmn:flowNodeRef>data-entry-task</bpmn:flowNodeRef>
</bpmn:lane>
</bpmn:laneSet>
Common extensions
The quantum: namespace adds runtime metadata that doesn't belong in the standard BPMN schema. Two extensions appear on most flow nodes and are documented here once.
I/O mappings (quantum:ioMapping)
I/O mappings control which variables enter and leave an element's scope.
Input mappings are evaluated before the element executes. Each input creates or overwrites a variable in the element's local scope.
| Attribute | Type | Notes |
|---|---|---|
source | FEEL expression | Evaluated against the current scope (e.g. =orderId, =customer.email, ="active") |
target | string | Variable name in the local scope to assign the result to |
Output mappings are evaluated after the element completes, writing values back to the parent scope.
| Attribute | Type | Notes |
|---|---|---|
source | FEEL expression | Evaluated against the local scope after execution |
target | string | Variable name in the parent scope |
If no input mappings are defined, the element inherits the full parent scope. If no output mappings are defined, local variables are merged back into the parent scope (or discarded for a call activity with propagateAllChildVariables="false").
<quantum:ioMapping>
<quantum:input source="=order.customerId" target="customer_id" />
<quantum:input source="="PENDING"" target="initialStatus" />
<quantum:output source="=paymentResult.transactionId" target="transactionId" />
<quantum:output source="=if approved then "APPROVED" else "REJECTED"" target="decision" />
</quantum:ioMapping>
source is FEEL, so literals must be prefixed with = (e.g. ="active", =42). target must be a plain variable name, not an expression.
Task headers (quantum:taskHeaders)
Task headers are static key/value pairs embedded in the process definition and passed to a worker alongside each job. Unlike I/O mappings, they are plain strings — no FEEL evaluation, no runtime variable substitution.
<quantum:taskHeaders>
<quantum:header key="template" value="order-confirmation" />
<quantum:header key="priority" value="high" />
<quantum:header key="retryBackoff" value="PT30S" />
</quantum:taskHeaders>
Header keys must be unique within a single taskHeaders block.
Validation
Every BPMN definition is validated when it's deployed. Validation produces two severity levels:
| Severity | Effect |
|---|---|
| Error | Deployment fails; the definition is not registered |
| Warning | Deployment succeeds; the issue is recorded for inspection |
The validator enforces structural and semantic correctness — reference integrity (every messageRef/signalRef/errorRef/escalationRef must point at a definition that exists), gateway rules, link-event pairing, scope rules for sub-processes, required extension attributes for tasks, and the multi-instance / standard-loop mutual exclusion. Specific checks are listed on each element page.