Best Practices

1 Make Error Paths Explicit

Make error paths explicit and visible in the diagram rather than hiding them in worker code. On the hosted service nothing raises a BPMN error today: the job API has no call to throw one (a job can only be completed or failed), and an error end event is read as a plain end, so an error boundary event deploys but never fires. What works today: the worker completes the job with an outcome variable and an exclusive gateway after the task routes on it, one outgoing flow per outcome (declined, invalid, approved). A technical failure (a timeout, a network error) is reported with fail; once the retries are spent the instance becomes an incident you resolve from the dashboard or the API.

<serviceTask id="processPayment" name="Process Payment"> ... </serviceTask>
<sequenceFlow sourceRef="processPayment" targetRef="paymentOutcome" />
<exclusiveGateway id="paymentOutcome" default="toFulfil" />
<sequenceFlow id="toDeclined" sourceRef="paymentOutcome" targetRef="notifyDeclined">
  <conditionExpression>=paymentStatus = "declined"</conditionExpression>
</sequenceFlow>
<sequenceFlow id="toFulfil" sourceRef="paymentOutcome" targetRef="fulfilOrder" />

2 Use Compensation Handlers

For multi-step transactional processes, attach a compensation boundary event to each task that needs rollback, associated with a handler activity marked isForCompensation="true". Compensation is thrown explicitly: route the failure path (for example the gateway branch a declined payment takes) to an intermediate throw or end event carrying a compensateEventDefinition. The handlers then run for the tasks that actually completed, in reverse order (e.g., release reserved inventory when payment fails). A later failure does not trigger compensation by itself.

3 Always Use Explicit End Events

Every process path should end at an explicit End Event. Never leave a path hanging at a task with no outgoing sequence flow. Implicit ends are confusing and can mask bugs where a token gets stuck.

4 Externalize Decisions to DMN

Business rules change frequently. Move complex routing logic (discount tiers, approval thresholds, risk scores) out of BPMN gateway conditions into DMN decision tables. This lets business analysts update rules without modifying the process model.

5 Use Message Correlation Keys

When using message catch events, always define a correlation key based on a stable business identifier (order ID, customer ID). Avoid using internal system keys that may change. The key is declared on the message and names one process variable. This fragment goes inside a document that declares the bpmn and zeebe namespaces:

<bpmn:message id="Message_PaymentReceived" name="PaymentReceived">
  <bpmn:extensionElements>
    <zeebe:subscription correlationKey="=orderId" />
  </bpmn:extensionElements>
</bpmn:message>

The hosted API does not publish messages yet: a message wait is completed by a worker as an ordinary job, and the worker must check the business identifier itself. See the Correlation guide.

6 Make Service Tasks Idempotent

Design your worker handlers so that running them twice with the same inputs produces the same result, keyed on the job key. If a job is retried after a partial failure (e.g., payment was charged but completion failed), the worker should detect the existing state and not charge twice. A completion that already went through answers 404 when repeated, so read the instance to reconcile instead of retrying blindly.

7 Use Parallel Gateways for True Concurrency

When multiple tasks can run simultaneously (e.g., send email AND update CRM), use a Parallel Gateway to split the flow. This is faster than sequential execution and makes the parallelism explicit in the model.

8 Use Call Activities for Reuse

If the same sequence of tasks appears in multiple processes, extract it into a separate process definition and invoke it via a Call Activity. This avoids copy-paste and ensures all callers benefit from improvements.

9 Add Timer Escalation for User Tasks

Human tasks without deadlines create hidden bottlenecks. Attach a non-interrupting timer boundary event to every user task with a reasonable escalation timeout. Route the escalation path to notify a supervisor or escalate to the next approver.

10 Use Meaningful, Consistent Naming

Name every element in your BPMN diagram clearly. Use verb-noun format for tasks ("Validate Order", "Send Notification"), question format for gateways ("Amount Approved?"), and event names for events ("Payment Received"). Consistent naming makes processes readable by business stakeholders.