Skip to content
3

@miragon/rules/async-continuations โ€‹

Reports Camunda 7 save points (camunda:asyncBefore, camunda:asyncAfter) that are missing where your save-point policy requires them, or set where it forbids them. The default policy follows Camunda's recommendations, and every BPMN element can be configured on its own.

Examples โ€‹

An order payment process in Camunda 7: a user approves the order, then the card is charged. Each blue bar is a transaction boundary, drawn by camunda-transaction-boundaries: Camunda 7 commits there and a new transaction starts.

async-continuations/invalid.bpmn

Invalid model: no transaction boundary before Charge card

Valid model: a transaction boundary before Charge card

1 finding
  • serviceTask_chargeCard Add camunda:asyncBefore so a failing call rolls back to this task, not the last wait state

Invalid: no boundary in front of "Charge card", so a failing payment shows up as an incident on the job after "Approve order" instead of on "Charge card"

Valid: "Charge card" starts behind its own boundary, so its retries and incidents belong to it

The same, as XML. ๐Ÿ‘Ž wrong:

xml
<bpmn:serviceTask id="serviceTask_chargeCard" name="Charge card"
  camunda:delegateExpression="${chargeCardDelegate}" />

๐Ÿ‘ right:

xml
<bpmn:serviceTask id="serviceTask_chargeCard" name="Charge card"
  camunda:asyncBefore="true" camunda:delegateExpression="${chargeCardDelegate}" />

Why โ€‹

Camunda 7 runs a process in one database transaction from wait state to wait state. When a step fails, everything since the last wait state rolls back. Without a save point a user's task completion is undone because a service call after it failed, a side effect runs a second time on retry, or the incident shows up in Cockpit at an activity that did nothing wrong. An on-call operator then retries the wrong step, and the user has to complete the same task again.

None of this is visible in the modeler: a diagram with and without save points looks the same. An asyncBefore on a wait state goes the other way. The engine already commits there, so the extra job only adds load on the job executor.

Why this matters for agentic BPMN โ€‹

An agent generating a Camunda 7 process writes the delegate expressions and form keys it was asked for and leaves the transaction attributes out, because nothing in the request mentions them. The model deploys and runs on the happy path, so the missing boundaries surface only in production when the first remote call fails.

Typical AI artifact without this rule: <bpmn:serviceTask id="serviceTask_chargeCard" camunda:delegateExpression="${chargeCardDelegate}"> directly after a user task without asyncAfter, so a failing payment rolls the user's approval back.

What this rule guarantees: every Camunda 7 element carries the save points your policy requires and none it forbids. By default that is Camunda's recommendation: a save point where Camunda asks for one, and no redundant asyncBefore on a wait state.

Scope โ€‹

The rule only checks Camunda 7 diagrams: modeler:executionPlatform="Camunda Platform" on the definitions, or no execution platform but the camunda: namespace declared. Camunda 8 and plain BPMN diagrams are skipped.

Every flow node maps to exactly one key: the most specific one that fits, so an external service task is externalServiceTasks, not serviceTasks. Each key has two slots, before (camunda:asyncBefore, or the legacy camunda:async) and after (camunda:asyncAfter), and each slot is one of:

  • required: reported when the flag is missing
  • allowed: never reported
  • forbidden: reported when the flag is set

The rule only looks at the element itself, never at its neighbours.

On a multi-instance activity there are two levels:

  • the flags on the element belong to the multi-instance body, once before and once after all instances, and follow multiInstanceBodies
  • the flags on its multiInstanceLoopCharacteristics belong to each single instance and follow the key of the activity itself, so a multi-instance user task needs asyncAfter on its loop characteristics and a multi-instance service task asyncBefore on both levels

Start events of sub-processes and event sub-processes, and complex gateways, have no key and are not checked.

Defaults โ€‹

KeyElementbeforeafter
serviceTasksservice taskrequiredallowed
externalServiceTasksservice task with camunda:type="external"forbiddenallowed
sendTaskssend taskrequiredallowed
externalSendTasksexternal send taskforbiddenallowed
businessRuleTasksbusiness rule taskallowedallowed
externalBusinessRuleTasksexternal business rule taskforbiddenallowed
scriptTasksscript taskrequiredallowed
userTasksuser taskforbiddenrequired
receiveTasksreceive taskforbiddenallowed
manualTasksmanual taskallowedallowed
undefinedTaskstask without a typeallowedallowed
callActivitiescall activityallowedallowed
subProcessessub-processallowedallowed
startEventsstart event directly inside a processrequiredallowed
timerStartEventstimer start event directly inside a processforbiddenallowed
intermediateCatchEventsintermediate catch eventforbiddenallowed
intermediateThrowEventsintermediate throw event without a messageallowedallowed
messageIntermediateThrowEventsmessage intermediate throw eventrequiredallowed
externalMessageIntermediateThrowEventsmessage intermediate throw event with an external messageforbiddenallowed
endEventsend event without a messageallowedallowed
messageEndEventsmessage end eventrequiredallowed
externalMessageEndEventsmessage end event with an external messageforbiddenallowed
boundaryEventsboundary event (no before slot)โ€”allowed
parallelGatewaysforking parallel gatewayallowedallowed
parallelJoinsparallel gateway with more than one incoming flowrequiredallowed
inclusiveGatewaysforking inclusive gatewayallowedallowed
inclusiveJoinsinclusive gateway with more than one incoming flowrequiredallowed
exclusiveGatewaysexclusive gatewayallowedallowed
eventBasedGatewaysevent-based gatewayforbiddenallowed
multiInstanceBodiesmulti-instance activity, flags on the elementrequiredallowed

A timer start event already fires as a job, so there is no caller to hand the instance back to, and an asyncBefore there only adds a second job. External tasks are wait states: the worker fetches them from the engine, so an asyncBefore on them is redundant.

Configuration โ€‹

"preset": "minimal" turns every default allowed into forbidden and keeps every required, for teams that want as few save points as possible. A key set to an object overrides the slots it names, and a key set to false allows both of its slots. An unknown key or value stops the lint run with an error, so a mistyped or outdated option never falls back to the defaults unnoticed:

json
{
  "rules": {
    "@miragon/rules/async-continuations": [
      "error",
      {
        "preset": "minimal",
        "callActivities": { "before": "allowed" },
        "externalServiceTasks": { "after": "required" },
        "userTasks": false
      }
    ]
  }
}

With minimal, a task with asyncAfter directly in front of a multi-instance body with asyncBefore is reported for its asyncAfter, and the body's asyncBefore stays required.

Migrating from 0.20 โ€‹

BeforeNow
serviceTasks: falseserviceTasks: false, plus sendTasks, scriptTasks, messageIntermediateThrowEvents and messageEndEvents set to false if those were meant too
userTasks: falseuserTasks: { "after": "allowed" }
startEvents: falsestartEvents: false
joins: falseparallelJoins: false, inclusiveJoins: false
multiInstance: falsemultiInstanceBodies: false
waitStates: falsefalse on receiveTasks, intermediateCatchEvents, eventBasedGateways and the external* keys, and userTasks: { "before": "allowed" }

Further reading โ€‹