2. BPMN Modelling Guide

BPMN 2.0 is a diagram standard that the engine can execute. This guide takes the basics in BPMN and Workflow Engines further: the full element set, the patterns used most, and how to model so others can read it. Running example: a small order process with service tasks and error events (the same shape as the simple models used when trying Camunda).

The order process

flowchart LR
    S(("Order received")) --> A["Check inventory"]
    A --> B["Charge payment method"]
    B --> C["Ship items"]
    C --> E(("Order shipped"))
    A -. "error: item not in stock" .-> N(("Order not shipped"))
    B -. "error: payment failed" .-> N

Each service task has a task definition type; any worker subscribed to that type picks up the job (Writing Job Workers).

Elements you will use

Events (circles)

• Interrupting boundary events cancel the task; non-interrupting ones (dashed) run alongside it (for example, send a reminder but keep waiting).
• Event-based gateway waits for the first of several events (a reply message or a timeout).

Tasks (rounded rectangles)

Gateways (diamonds)

Containers

• Embedded subprocess: group steps, scope variables, and attach one boundary event to the whole group. In the HZV example the whole "In Quarantine" loop can be cancelled by one timer.
• Event subprocess: a mini-process that starts when an event occurs anywhere inside its parent (for example "cancel order").
• Call activity: reuse a process (a "credit check") from many parents.
• Multi-instance: run a task for every item in a list, in parallel or in turn.
• Pools and lanes: who does what; the engine executes one pool.

Patterns that come up constantly

1. Wait for a person, escalate if late

flowchart LR
    S(("Start")) --> U["Review request"]
    U --> E(("Done"))
    U -. "timer P3D, non-interrupting" .-> R["Remind manager"]

2. Retry loop with a limit

flowchart LR
    A["Call external service"] --> G{"Succeeded?"}
    G -- yes --> OK(("Done"))
    G -- no --> W["Wait PT10M"]
    W --> C{"Tries left?"}
    C -- yes --> A
    C -- no --> M["Manual review"]

3. Parallel work, then continue

flowchart LR
    S(("Start")) --> F{"+"}
    F --> A["Check credit"]
    F --> B["Verify identity"]
    A --> J{"+"}
    B --> J
    J --> D["Decide"]

4. Run for each item (multi-instance) A service task with a multi-instance marker, input collection =order.items, input element item, and an output collection that gathers each result.

5. Compensation (undo) If shipping fails after payment, a compensation or refund path reverses the payment. Model the undo explicitly. Check your Camunda version's list of supported elements for the exact compensation features.

6. Start by message, correlate later messages A message start event creates the instance; later messages find their instance through a correlation key (for example =order_id). See Writing Job Workers.

7. Timers ISO 8601 values: PT30M (30 minutes), P2D (2 days), R3/PT10M (repeat 3 times every 10 minutes), a fixed date-time, or a FEEL expression such as =quarantine_duration (see the HZV example in the tutorial).

Modelling style: make it readable

Anti-patterns - Spaghetti with lines jumping back (loops without a named reason). - Everything in one pool with no lanes, so nobody knows who owns a step. - Gateways that do work: a gateway only chooses a path. - Business data hidden in variables nobody documents: write down the variables each task reads and writes. - Using the engine as a database: store big data elsewhere and pass references (Best Practices).

Variables and data

• Variables live on the process instance (and on scopes such as subprocesses).
• Tasks can map inputs and outputs so each task sees only what it needs.
• Conditions and mappings use FEEL expressions starting with =: =order.total > 1000, =customer.country = "ZA". Details: DMN and FEEL.
• Keep payloads small: IDs and key facts, not documents.

Reading the XML (when you need to)

<bpmn:serviceTask id="check" name="Check inventory">
  <bpmn:extensionElements>
    <zeebe:taskDefinition type="check-inventory" />
  </bpmn:extensionElements>
</bpmn:serviceTask>

<bpmn:boundaryEvent id="out_of_stock" name="Item not in stock" attachedToRef="check">
  <bpmn:errorEventDefinition errorRef="Error_out_of_stock" />
</bpmn:boundaryEvent>

Tools