Skip to main content

BPMN Authoring Reference

Non-Production Preview

Mambu Flows is currently available as a Non-Production Preview (NPP) feature, available to a limited number of customers. You should not process production data with NPP features. To request access, contact your Mambu Customer Success Manager. For more information, see Mambu Release Cycle — Feature Release Status.


This page is the complete authoring reference for Mambu Flows BPMN files. For a step-by-step introduction, see Getting Started.

BPMN file structure​

Every process definition must declare the Mambu BPMN extension namespace and set the correct targetNamespace:

<?xml version="1.0" encoding="UTF-8"?>
<definitions xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL"
xmlns:mbu="http://mambu.com/bpmn"
targetNamespace="process-orchestration">

<process id="myProcess" name="My Process" isExecutable="true">
<!-- process elements go here -->
</process>
</definitions>
AttributeRequired value
xmlnshttp://www.omg.org/spec/BPMN/20100524/MODEL
xmlns:mbuhttp://mambu.com/bpmn
targetNamespaceprocess-orchestration

The targetNamespace value is a fixed technical identifier, so it doesn't match the product name. Use it exactly as shown.

The process/@id is the key used when starting an instance — see Process Instances API for the endpoint reference.


Destinations​

A destination is a named, authenticated HTTP connection registered via the Destinations API. BPMN tasks reference destinations by their externalId; credentials are managed server-side and never appear in the BPMN file itself.

Authentication types​

authTypesecureProperties fieldsHow it works
BASICusername, passwordHTTP Basic Authorization header
API_KEYapiKey, headerName (optional)Named header with the API key value. headerName defaults to api-key if omitted.
OAUTH2_CLIENT_CREDENTIALStokenUrl, clientId, clientSecret, scope (optional)Mambu gets an access token with the OAuth 2.0 client credentials grant and sends it as Authorization: Bearer <token>.
OAUTH2_AUTHORIZATION_CODEtokenUrl, authorizationUrl, clientId, clientSecret (optional), refreshToken (required at call time)For providers that use the OAuth 2.0 authorization code flow. The consent and code exchange are done once, outside Mambu, and give a refresh token. Mambu uses this refresh token to get access tokens and sends them as Authorization: Bearer <token>.

Not all OAuth 2.0 flows are supported. For example, Mambu does not handle the authorization code consent redirect, PKCE or refresh token rotation. See the Destinations API for the full list of supported flows, token handling and the optional retryPolicy and circuitBreakerPolicy settings.

Destination lifecycle​

DRAFT → :submit → PENDING_APPROVAL → :approve → APPROVED (enabled = true)
└→ :reject → REJECTED
APPROVED → :make-current → current = true

current and enabled are boolean fields, not statuses. Running process instances use the revision that was made current with :make-current. Changing a destination (for example, rotating a credential) needs a new revision, which must be approved and made current again.

caution

Deleting a destination that is referenced by a running process instance causes those steps to fail. Check active instances before deleting.


Service tasks​

Service tasks perform work within the process. Set mbu:type on a <serviceTask> to select the task type.

call-destination — HTTP request​

Makes an authenticated HTTP request to an external system via a registered destination.

<serviceTask id="myTask" name="Call External API" mbu:type="call-destination">
<extensionElements>
<mbu:destination>my-destination-code</mbu:destination>
<mbu:method>POST</mbu:method>
<mbu:path>/api/resource/${processInput.resourceId}</mbu:path>
<mbu:header name="Content-Type" value="application/json"/>
<mbu:header name="X-Tenant" value="${processInput.tenantId}"/>
<mbu:payload>{"amount": ${processInput.amount}}</mbu:payload>
</extensionElements>
</serviceTask>

Output variables (auto-created for task id myTask):

VariableTypeContent
myTask_statusIntegerHTTP response status code
myTask_responseMapParsed JSON response body
myTask_responseRawStringRaw response body string

Access nested fields with dot notation: ${myTask_response.data.id}.

Errors and retries

OutcomeBehavior
HTTP 300 to 399BPMN error REDIRECT_NOT_FOLLOWED is thrown. Redirects are never followed and the output variables are not set.
HTTP 400 or higherThe output variables are set for the final response, then BPMN error HTTP_ERROR is thrown.
Connection failure, request timeout, HTTP 429 or 5xxRetried first when the destination has a retryPolicy that allows more attempts. Each try uses one attempt. When no attempts are left, the matching BPMN error (CONNECTION_ERROR, TIMEOUT or HTTP_ERROR) is thrown. Without a retryPolicy, there is only one attempt.
HTTP 429 with Retry-AfterThe delay from Retry-After (seconds or HTTP date) is used, capped at maxDelayMs of the retryPolicy.
Connection failureBPMN error CONNECTION_ERROR is thrown.
Request timeoutBPMN error TIMEOUT is thrown.
Response body larger than the size limitBPMN error RESPONSE_TOO_LARGE is thrown and the output variables are not set.
OAuth 2.0 token request timeoutBPMN error TIMEOUT is thrown. Not retried.
Other OAuth 2.0 token failure (non-2xx token response, no access_token, missing credential)The activity fails. A boundary error event cannot catch this failure. For OAUTH2_AUTHORIZATION_CODE, an invalid_grant response means the refresh token is no longer valid: get a new refresh token from the provider and store it in a new destination revision.

Use a boundary error event to handle these BPMN errors.

Optional: callback declaration — see Inbound callbacks below.

assign-variable — set process variables​

Sets one or more process-scoped variables. Values are JUEL expressions evaluated at execution time.

<serviceTask id="setVars" name="Set Variables" mbu:type="assign-variable">
<extensionElements>
<mbu:variable name="loanId" value="${processInput.loanId}"/>
<mbu:variable name="fee" value="${processInput.baseFee * 1.2}"/>
<mbu:variable name="counter" value="${counter == null ? 0 : counter + 1}"/>
</extensionElements>
</serviceTask>

build-json — construct a JSON variable​

Builds a JSON string variable by merging a template with a values map. Use this to construct API payloads or the final processResult.

<serviceTask id="buildPayload" name="Build Payload" mbu:type="build-json">
<extensionElements>
<mbu:jsonTemplate>{"clientId": "${c}", "amount": ${a}, "currency": "${cur}"}</mbu:jsonTemplate>
<mbu:jsonValues>{"c": "${clientId}", "a": "${amount}", "cur": "${currency}"}</mbu:jsonValues>
<mbu:resultVariable>apiPayload</mbu:resultVariable>
</extensionElements>
</serviceTask>
Limitation: root must be a JSON object

mbu:jsonTemplate must resolve to a JSON object ({...}) at the root. A root-level array is not supported, and fails at runtime with an unhelpful, low-level error.

Works:

{"clientId": "abc123", "amount": 500}
{"operations": [{"op": "add", "path": "/foo", "value": "bar"}]}

Does not work:

[{"op": "add", "path": "/foo", "value": "bar"}]
["abc123", "def456"]

If you need an array as the payload (for example, a JSON Patch body), wrap it in an object and reference the array field:

<mbu:jsonTemplate>{"operations": [${ops}]}</mbu:jsonTemplate>
<mbu:jsonValues>{"ops": "..."}</mbu:jsonValues>
<mbu:resultVariable>patchPayload</mbu:resultVariable>

Then pass ${patchPayload.operations} downstream, or reference ${patchPayload} as a whole if the consuming call accepts the wrapper object.

The result is stored as a string in apiPayload. Pass it as a <mbu:payload> in a subsequent call-destination task: <mbu:payload>${apiPayload}</mbu:payload>.

To set the process output returned to the caller, set <mbu:resultVariable>processResult</mbu:resultVariable>.

parse-json — parse a JSON string into a Map​

Converts a raw JSON string variable into a traversable Map (or List, for a JSON array).

note

parse-json can parse a root-level JSON array into a List, but build-json cannot produce one — see the limitation note above.

<serviceTask id="parseResponse" name="Parse Response" mbu:type="parse-json">
<extensionElements>
<mbu:input>${myTask_responseRaw}</mbu:input>
<mbu:outputVariable>parsedResponse</mbu:outputVariable>
</extensionElements>
</serviceTask>

After parsing, use dot notation: ${parsedResponse.data.id}, or index notation for an array: ${parsedResponse[0].name}.

businessRuleTask — DMN decision table​

Evaluates a DMN decision table deployed to the engine, referenced by its decision key.

<businessRuleTask id="applyRules" name="Apply Credit Rules">
<extensionElements>
<dmn:field name="decisionTableReferenceKey">
<dmn:string>creditScoringRules</dmn:string>
</dmn:field>
</extensionElements>
</businessRuleTask>

The <definitions> root element must also declare the xmlns:dmn="http://mambu.com/bpmn/dmn" namespace. The output of the DMN table is stored as process variables named after the DMN table's output columns.


Flow control​

Exclusive gateway (XOR)​

Routes execution to exactly one outgoing path based on conditions. Set a default sequence flow as the fallback when no condition matches.

<exclusiveGateway id="checkStatus" default="fallbackFlow"/>

<sequenceFlow sourceRef="checkStatus" targetRef="approvedTask">
<conditionExpression>${myTask_status == 201}</conditionExpression>
</sequenceFlow>

<sequenceFlow id="fallbackFlow" sourceRef="checkStatus" targetRef="errorTask"/>

Use <![CDATA[...]]> for conditions containing < or >:

<conditionExpression><![CDATA[${amount > 10000}]]></conditionExpression>

Parallel gateway (AND)​

Splits execution into all outgoing paths simultaneously. A matching join gateway waits for all branches to complete before continuing.

<!-- Split -->
<parallelGateway id="split"/>
<sequenceFlow sourceRef="split" targetRef="taskA"/>
<sequenceFlow sourceRef="split" targetRef="taskB"/>

<!-- Join (waits for both taskA and taskB) -->
<parallelGateway id="join"/>
<sequenceFlow sourceRef="taskA" targetRef="join"/>
<sequenceFlow sourceRef="taskB" targetRef="join"/>

Inclusive gateway (OR)​

Routes execution to one or more outgoing paths where the condition is true. Like a parallel gateway for conditional multi-branch execution.

note

A process that contains a <callActivity> cannot fork with a parallel or inclusive gateway. See the single path rule.


Call another process (callActivity)​

A <callActivity> starts another process definition as a child instance. The calling process (the parent) waits at the <callActivity> until the child ends. Use it to keep shared steps, for example a KYC check, in one process definition that many processes call.

<callActivity id="checkKyc" name="Check KYC" calledElement="kycCheckDemo" mbu:businessKey="${clientId}">
<extensionElements>
<mbu:in source="clientId" target="clientId"/>
<mbu:in sourceExpression="${loanAmount * 1.1}" target="limit"/>
<mbu:out source="kycStatus" target="kycStatus"/>
</extensionElements>
</callActivity>
Element or attributeRequiredDescription
calledElementYesProcess key of the child. It must be a literal key: an expression (${...}) is rejected. The key must belong to a current process definition.
mbu:inNoCopies one value from the parent into the child before the child starts. Set target (the child variable name) and exactly one of source (a parent variable name) or sourceExpression (a JUEL expression evaluated on the parent). Add one mbu:in per value.
mbu:outNoCopies one value from the child into the parent when the child ends. Set target (the parent variable name) and exactly one of source (a child variable name) or sourceExpression (a JUEL expression evaluated on the child). Add one mbu:out per value.
mbu:businessKeyNoBusiness key of the child instance. JUEL is supported, evaluated on the parent. Without it, the child has no business key: it does not take the parent's.
mbu:asyncNo"true" starts the child in a background job of the parent. See Async execution and Failure behavior.

Variables. The child does not see the parent's variables. Only the mbu:in values go into the child, and only the mbu:out values come back to the parent. Other child variables stay on the child instance. The child has no processInput: the mbu:in targets are its top-level variables, so the child in the example reads ${clientId} and ${limit}.

note

Use the mbu: elements and attributes only. These are rejected when you upload the definition, with 400 Bad Request and an errorSource that names the <callActivity> id and the cause:

  • any flowable: attribute or element, for example flowable:in, flowable:out or flowable:inheritVariables;
  • any other element in <extensionElements>, and any other attribute or child element on mbu:in or mbu:out;
  • multi-instance on the <callActivity> (multiInstanceLoopCharacteristics).

Deploy order​

The called process must be current before you upload the process that calls it. Deploy the child first:

  1. Upload the child definition, then approve it and make it current.
  2. Upload the parent definition, then approve it and make it current.

To see which processes call a definition, get its staged definition with GET /api/stagedprocessdefinitions/{id}. The calledBy field lists the keys of the current process definitions that call it. A process definition cannot be deleted while any deployed version of another process calls it, also an older version: DELETE returns 409 Conflict, and the error details name all the callers. Delete the callers first. See the Staged Process Definitions API and the Process Definitions API.

Upload and make-current rules​

The engine checks these rules when you upload a definition (POST /api/stagedprocessdefinitions) and again when you make it current (:make-current). A definition that breaks a rule returns 400 Bad Request with BPMN_ELEMENT_NOT_SUPPORTED.

RuleerrorSource
calledElement is a current process definitioncallActivity[id='…']: process '…' is not a current definition
No call cycle: a process cannot call itself, directly or through other processes (for example A → B → A)Ends with (call cycle)
A call chain has at most 5 processes. The check counts the longest chain of current callers above the process, the process itself, and the longest chain of processes it calls below it.Ends with (maximum call depth)

Single path rule​

A process that contains a <callActivity> must run one path at a time. This applies at any level of the process, including inside a <subProcess>. When you upload such a process or make it current, these are rejected:

  • multi-instance (multiInstanceLoopCharacteristics) on any element;
  • a node with more than one outgoing sequence flow, except an <exclusiveGateway> or an <eventBasedGateway>, where only one outgoing path runs. This includes a <parallelGateway> or <inclusiveGateway> fork, and an implicit fork from a task or event with more than one outgoing sequence flow;
  • a boundary event with cancelActivity="false". An error boundary event always interrupts and is allowed;
  • an event subprocess start event with isInterrupting="false".

The upload returns 400 Bad Request with BPMN_ATTRIBUTE_VALUE_INVALID and an errorSource such as <element>[id='…'] (line N): '<construct>' is not supported in a process that contains a callActivity. A process without a <callActivity> is not affected.

Runtime behavior​

  • Child version. The engine starts the latest current version of calledElement.
  • Parent continues in the background. The child runs in the same call as the parent until the child reaches a wait state or its end event. The end of the child, the mbu:out mappings and the rest of the parent then run in a background job. A process that reaches a <callActivity> therefore does not end during the :start call: unless it set a processResult before the <callActivity>, :start returns 204 No Content, and the mbu:out values appear in the parent a moment later.
  • Limits. Child instances count toward the running-instance limit and the start rate limit that :start checks. A parent that waits at a <callActivity> does not count as running, and neither does a child at a wait state. A <callActivity> is never rejected by these limits, only :start is.
  • Permissions and starter. A child starts without a check of the :start permission: the permission is checked on the top-level :start only. A child has the starter (startUserId) of the top-level instance. An inbound callback for a call-destination task in a child goes to the child, as in any other process.
  • Call depth. The maximum call depth is 5, and a top-level instance is at depth 1. A <callActivity> that would start an instance at depth 6 fails. During the :start call, :start returns 422 Unprocessable Entity with the errorSource callActivity[id='…']: maximum call depth of 5 exceeded when calling process '…'. In a background job, the job goes to the dead-letter queue.
Changing a called process

A new version of a child takes effect for new calls at once. The upload does not check that the new version still uses the variable names in the mbu:in and mbu:out mappings of the processes that call it. Before you make a new child version current, check its calledBy list and the mappings of those callers.

Failure behavior​

FailureResult
The child fails before its first wait state, while the :start call runsThe parent and the child are rolled back. :start returns the error, for example 422 Unprocessable Entity.
The child fails after a wait state, for example after an asynchronous stepThe child's job goes to the dead-letter queue, and the parent stays at the <callActivity>. This is the same with or without mbu:async="true" on the <callActivity>.
The parent fails after the child endsThe parent's job goes to the dead-letter queue. The end of the child is in the same job, so the child stays at its end event until you retry the job. This is the same with or without mbu:async="true" on the <callActivity>.
The parent reaches the <callActivity> in a background job (mbu:async="true" on the <callActivity>, or after a wait state), and the child fails before its first wait stateThe parent's job goes to the dead-letter queue. No child instance is left.
The child ends with a BPMN error end eventA boundary error event on the parent's <callActivity> with the same errorCode catches it.

To retry a dead-letter job, call POST /api/processinstances/{processInstanceId}/jobs/{jobId}:retry on the instance that owns the job. See the Process Instances API.

Child instances and cancellation​

  • GET /api/processinstances/{processInstanceId} returns parentProcessInstanceId: the id of the parent instance, or null for a top-level instance.
  • To list the children of an instance, search with parentProcessInstanceId and EQUALS. To list top-level instances only, use IS_NULL. See the Process Instances API.
  • You cannot cancel a child instance on its own: POST /api/processinstances/{processInstanceId}:cancel on a child returns 400 Bad Request with the id of the top-level instance. Cancel the top-level instance instead.
  • These events cancel the whole call tree, from the top-level instance down, and delete the open CBE tasks of the instances in the tree:
    • you cancel the top-level instance;
    • a CBE task of a child instance is deleted;
    • a job of an instance in the tree runs longer than the active execution timeout;
    • the top-level instance runs longer than the maximum instance duration.
  • An interrupting boundary event on a <callActivity> ends only that call. See Timer boundary event.

Human tasks​

A <userTask> pauses the process and creates an item in the Mambu Tasks inbox. Execution resumes when the assignee completes the task via the Process Tasks API.

<userTask id="approveWithdrawal"
name="Approve Counter Withdrawal"
mbu:assignedUser="${processInput.approverUsername}"
mbu:priority="50"
mbu:dueDate="P1D"
mbu:asyncLeave="true"
mbu:taskLinkType="DEPOSIT_ACCOUNT"
mbu:taskLinkId="${processInput.depositAccountId}"
mbu:template="WithdrawalApproval"
mbu:replySchema="withdrawalReplySchema"/>

User task attributes​

AttributeRequiredDescription
mbu:assignedUserYesUsername or JUEL expression resolving to a username
mbu:asyncLeaveYesMust be "true" — mandatory on every userTask
mbu:priorityNoInteger 0–100; higher values appear first in the inbox
mbu:dueDateYesISO 8601 duration (P1D) or instant (2026-12-31T00:00:00Z). A <userTask> without it is rejected at deploy with error 16023
mbu:taskLinkTypeNoCBE entity type for a deep link in the inbox (e.g. DEPOSIT_ACCOUNT)
mbu:taskLinkIdNoEntity ID for the deep link
mbu:templateNoName of a TASK notification message template
mbu:replySchemaNoExternal ID of a JSON Schema that validates the completion payload

Completing a task​

The assignee calls:

curl -X POST "https://YOUR_HOST/api/processtasks/{taskId}:complete" \
-H "Content-Type: application/vnd.mambu.v2+json" \
-u "APPROVER_USER:APPROVER_PASSWORD" \
-d '{"decision": "APPROVED", "comment": "Verified at counter"}'

Every field in the completion body is stored as a process variable prefixed by the task id. For a task with id approveWithdrawal:

Completion fieldProcess variable
decisionapproveWithdrawal_decision
commentapproveWithdrawal_comment

Downstream gateways can read these directly: ${approveWithdrawal_decision == 'APPROVED'}.


Async execution​

Async execution is set on individual BPMN elements (the start event, service tasks, user tasks, a <callActivity>), not on the process as a whole. Two attributes control it:

AttributeWhere the engine does the work
mbu:async="true"Before the element runs, the engine hands the work to its worker pool. The element then runs in the background, in its own transaction, and the API caller does not wait for it.
mbu:asyncLeave="true"After the element finishes, the engine saves its result to the database and continues the process in a new transaction.

Fire-and-forget process start​

To return 204 No Content to the caller immediately and continue execution on the engine's worker pool, set mbu:async="true" on the <startEvent>:

<startEvent id="start" mbu:async="true"/>

Without it, the engine runs the process during the :start call until the process ends or reaches a step that continues in the background: a wait state such as a <userTask>, a timer or a message catch event, an asynchronous step, or the end of a <callActivity> child. The response depends on whether the process set a processResult, which usually happens when it ends:

When :start returnsResponse
The process set a processResult (a JSON object) during the call200 OK with the processResult
No processResult is set, for example because the process continues in the background204 No Content

Both responses carry the processInstanceId and processInstanceStatus (COMPLETED or RUNNING) headers.

Other elements can also carry mbu:async="true", independently of the start event.

Async leave on individual tasks​

mbu:asyncLeave="true" on a task causes the engine to save the task's result to the database and continue the process in a new transaction. This is required on all <userTask> elements and is useful on long-running call-destination tasks to ensure their results are durable even if the engine node restarts.


Inbound callbacks​

Use an <intermediateCatchEvent> with a <messageEventDefinition> to park the process until an external system delivers a callback. This pattern is used for async vendor integrations — AML screening, KYC checks, credit bureau lookups.

<!-- Declare the message -->
<message id="kycResultMessage" name="kyc_result"/>

<!-- Make the outbound call, declaring the expected callback message -->
<serviceTask id="requestKyc" mbu:type="call-destination">
<extensionElements>
<mbu:destination>kyc-vendor</mbu:destination>
<mbu:method>POST</mbu:method>
<mbu:path>/verify</mbu:path>
<mbu:payload>{"clientId": "${processInput.clientId}"}</mbu:payload>
<mbu:callback message="kyc_result"/>
</extensionElements>
</serviceTask>

<!-- Park here until the vendor delivers the callback -->
<intermediateCatchEvent id="awaitKycResult">
<messageEventDefinition messageRef="kycResultMessage"/>
</intermediateCatchEvent>

When <mbu:callback message="..."/> is declared, the engine automatically injects two HTTP headers onto the outbound request:

HeaderValue
X-Callback-Execution-IdThe execution ID the vendor must include in the callback URL
X-Callback-MessageThe message name to deliver

The vendor resumes the process by calling:

POST /api/processexecutions/{executionId}/messages/{messageName}:deliver

The callback payload is available as {catchEventId}_response (Map) and {catchEventId}_responseRaw (String) in subsequent steps.

note

The call-destination task with <mbu:callback> and the <intermediateCatchEvent> must share the same execution token. Do not split them across a parallel gateway — this is validated at deploy time.


Timer events​

Timer start event​

Starts the process on a schedule.

<!-- Fixed date/time -->
<startEvent id="start">
<timerEventDefinition>
<timeDate>2026-12-31T23:59:59Z</timeDate>
</timerEventDefinition>
</startEvent>

<!-- Recurring (cron) -->
<startEvent id="start">
<timerEventDefinition>
<timeCycle>0 0 2 * * ?</timeCycle>
</timerEventDefinition>
</startEvent>

Timer boundary event​

Adds a timeout to a task. When the timer fires, execution leaves the task via the boundary event's sequence flow.

<userTask id="approveTask" name="Approve" mbu:asyncLeave="true" mbu:assignedUser="${approver}"/>

<!-- Non-interrupting: fires after 1 day but does not cancel the task -->
<boundaryEvent id="approvalTimeout" attachedToRef="approveTask" cancelActivity="false">
<timerEventDefinition>
<timeDuration>P1D</timeDuration>
</timerEventDefinition>
</boundaryEvent>

<sequenceFlow sourceRef="approvalTimeout" targetRef="sendReminder"/>

Set cancelActivity="true" (the default) to interrupt and cancel the task when the timer fires.

When an interrupting boundary event ends a <userTask> or a <callActivity>, the engine deletes the open CBE tasks of the user tasks that it ends, including user tasks in the called process. The rest of the process continues on the boundary event's path.

note

A process that contains a <callActivity> cannot use non-interrupting boundary events. See the single path rule.

Timer intermediate catch event​

Pauses execution for a fixed duration.

<intermediateCatchEvent id="wait30s">
<timerEventDefinition>
<timeDuration>PT30S</timeDuration>
</timerEventDefinition>
</intermediateCatchEvent>

Error handling​

Boundary error events​

Attach a boundary error event to any <serviceTask> to catch HTTP errors (non-2xx responses) from a call-destination task, or any thrown error from other task types. The error variables ({taskId}_status, {taskId}_response) are still populated and available on the boundary path.

On a <callActivity>, a boundary error event catches a BPMN error end event of the child: see Failure behavior. The child's variables are not available on the boundary path. Use the error code to tell why the child ended.

<serviceTask id="callApi" mbu:type="call-destination">
<!-- ... -->
</serviceTask>

<boundaryEvent id="apiError" attachedToRef="callApi">
<errorEventDefinition/>
</boundaryEvent>

<sequenceFlow sourceRef="apiError" targetRef="handleError"/>

Compensating transactions​

Use compensation boundary events and compensation tasks to undo completed work when a later step fails. This is the BPMN equivalent of a saga pattern.

<!-- Mark the initial task as compensatable -->
<serviceTask id="createLoan" name="Create Loan" mbu:type="call-destination">
<!-- ... -->
</serviceTask>

<boundaryEvent id="compensateCreateLoan" attachedToRef="createLoan">
<compensateEventDefinition/>
</boundaryEvent>

<!-- Compensation handler: called when compensation is triggered -->
<serviceTask id="cancelLoan" name="Cancel Loan" isForCompensation="true" mbu:type="call-destination">
<!-- ... -->
</serviceTask>

<association sourceRef="compensateCreateLoan" targetRef="cancelLoan"/>

<!-- Trigger compensation from an error path -->
<intermediateThrowEvent id="triggerCompensation">
<compensateEventDefinition/>
</intermediateThrowEvent>

Expression language (JUEL)​

Process variable values and BPMN condition expressions use JUEL (${...} syntax).

String operations​

${processInput.firstName.concat(" ").concat(processInput.lastName)}
${myTask_response.status}
${"pending".equals(loanStatus)}

Numeric operations​

${processInput.baseFee * 1.15}
${counter + 1}
${processInput.amount > 10000}

Map access​

${myTask_response.data.id}
${myTask_response.rates.EUR}

Use get() for keys with special characters:

${myTask_response.get("client-id")}

List access​

${myList.get(0)}
${myList.size()}

Null-safe defaults​

${counter == null ? 0 : counter + 1}
${processInput.comment == null ? "No comment" : processInput.comment}

XML escaping​

In XML attributes and element values, use &lt; for < and &gt; for >:

<conditionExpression>${amount &lt; 5000}</conditionExpression>

Or wrap in CDATA:

<conditionExpression><![CDATA[${amount < 5000}]]></conditionExpression>

In <mbu:path> and <mbu:payload>, use &amp; for & in query strings:

<mbu:path>/v1/latest?from=GBP&amp;to=EUR</mbu:path>

FEEL script tasks​

warning

Only FEEL script tasks are supported. General-purpose scripting (for example scriptFormat="javascript" or "groovy") is not available: a <scriptTask> with any other scriptFormat is rejected when the definition is deployed.

Use <scriptTask scriptFormat="feel"> for collection operations that JUEL cannot express — filtering, mapping, and aggregating lists.

<scriptTask id="sumAmounts" name="Sum Amounts" scriptFormat="feel">
<script>
sum(for item in loanList return item.amount)
</script>
<extensionElements>
<mbu:resultVariable>totalAmount</mbu:resultVariable>
</extensionElements>
</scriptTask>

The FEEL expression has read access to all current process variables. The result is stored in totalAmount.


Supported BPMN elements​

ElementSupported
<startEvent>Yes
<endEvent>Yes
<serviceTask>Yes
<userTask>Yes
<scriptTask scriptFormat="feel">Yes (FEEL only)
<scriptTask> with any other script format (JavaScript, Groovy, and so on)No — rejected at deploy
<businessRuleTask> (DMN)Yes
<exclusiveGateway>Yes
<parallelGateway>Yes. Not in a process that contains a <callActivity>: see the single path rule
<inclusiveGateway>Yes. Not in a process that contains a <callActivity>: see the single path rule
<eventBasedGateway>Yes
<subProcess>Yes
Event subprocess (<subProcess triggeredByEvent="true">) with an error or timer start eventYes. Message and signal start events are not supported
<callActivity>Yes (mbu:in, mbu:out, mbu:businessKey, mbu:async; flowable: attributes and elements are rejected). See Call another process
<boundaryEvent> (error, timer, compensate)Yes
<intermediateCatchEvent> (message, timer)Yes
<intermediateThrowEvent> (compensate)Yes
<sequenceFlow> with <conditionExpression>Yes
<association> (compensation)Yes
<message>Yes
Manual tasks, receive tasksNo
Signal eventsNo
Data objectsNo

What's next​