BPMN Authoring Reference
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>
| Attribute | Required value |
|---|---|
xmlns | http://www.omg.org/spec/BPMN/20100524/MODEL |
xmlns:mbu | http://mambu.com/bpmn |
targetNamespace | process-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
authType | secureProperties fields | How it works |
|---|---|---|
BASIC | username, password | HTTP Basic Authorization header |
API_KEY | apiKey, headerName (optional) | Named header with the API key value. headerName defaults to api-key if omitted. |
OAUTH2_CLIENT_CREDENTIALS | tokenUrl, 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_CODE | tokenUrl, 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.
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):
| Variable | Type | Content |
|---|---|---|
myTask_status | Integer | HTTP response status code |
myTask_response | Map | Parsed JSON response body |
myTask_responseRaw | String | Raw response body string |
Access nested fields with dot notation: ${myTask_response.data.id}.
Errors and retries
| Outcome | Behavior |
|---|---|
HTTP 300 to 399 | BPMN error REDIRECT_NOT_FOLLOWED is thrown. Redirects are never followed and the output variables are not set. |
HTTP 400 or higher | The output variables are set for the final response, then BPMN error HTTP_ERROR is thrown. |
Connection failure, request timeout, HTTP 429 or 5xx | Retried 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-After | The delay from Retry-After (seconds or HTTP date) is used, capped at maxDelayMs of the retryPolicy. |
| Connection failure | BPMN error CONNECTION_ERROR is thrown. |
| Request timeout | BPMN error TIMEOUT is thrown. |
| Response body larger than the size limit | BPMN error RESPONSE_TOO_LARGE is thrown and the output variables are not set. |
| OAuth 2.0 token request timeout | BPMN 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>
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).
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.
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 attribute | Required | Description |
|---|---|---|
calledElement | Yes | Process key of the child. It must be a literal key: an expression (${...}) is rejected. The key must belong to a current process definition. |
mbu:in | No | Copies 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:out | No | Copies 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:businessKey | No | Business 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:async | No | "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}.
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 exampleflowable:in,flowable:outorflowable:inheritVariables; - any other element in
<extensionElements>, and any other attribute or child element onmbu:inormbu: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:
- Upload the child definition, then approve it and make it current.
- 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.
| Rule | errorSource |
|---|---|
calledElement is a current process definition | callActivity[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:outmappings and the rest of the parent then run in a background job. A process that reaches a<callActivity>therefore does not end during the:startcall: unless it set aprocessResultbefore the<callActivity>,:startreturns204 No Content, and thembu:outvalues appear in the parent a moment later. - Limits. Child instances count toward the running-instance limit and the start rate limit that
:startchecks. 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:startis. - Permissions and starter. A child starts without a check of the
:startpermission: the permission is checked on the top-level:startonly. A child has the starter (startUserId) of the top-level instance. An inbound callback for acall-destinationtask 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:startcall,:startreturns422 Unprocessable Entitywith theerrorSourcecallActivity[id='…']: maximum call depth of 5 exceeded when calling process '…'. In a background job, the job goes to the dead-letter queue.
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
| Failure | Result |
|---|---|
The child fails before its first wait state, while the :start call runs | The 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 step | The 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 ends | The 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 state | The parent's job goes to the dead-letter queue. No child instance is left. |
| The child ends with a BPMN error end event | A 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}returnsparentProcessInstanceId: the id of the parent instance, ornullfor a top-level instance.- To list the children of an instance, search with
parentProcessInstanceIdandEQUALS. To list top-level instances only, useIS_NULL. See the Process Instances API. - You cannot cancel a child instance on its own:
POST /api/processinstances/{processInstanceId}:cancelon a child returns400 Bad Requestwith 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
| Attribute | Required | Description |
|---|---|---|
mbu:assignedUser | Yes | Username or JUEL expression resolving to a username |
mbu:asyncLeave | Yes | Must be "true" — mandatory on every userTask |
mbu:priority | No | Integer 0–100; higher values appear first in the inbox |
mbu:dueDate | Yes | ISO 8601 duration (P1D) or instant (2026-12-31T00:00:00Z). A <userTask> without it is rejected at deploy with error 16023 |
mbu:taskLinkType | No | CBE entity type for a deep link in the inbox (e.g. DEPOSIT_ACCOUNT) |
mbu:taskLinkId | No | Entity ID for the deep link |
mbu:template | No | Name of a TASK notification message template |
mbu:replySchema | No | External 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 field | Process variable |
|---|---|
decision | approveWithdrawal_decision |
comment | approveWithdrawal_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:
| Attribute | Where 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 returns | Response |
|---|---|
The process set a processResult (a JSON object) during the call | 200 OK with the processResult |
No processResult is set, for example because the process continues in the background | 204 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:
| Header | Value |
|---|---|
X-Callback-Execution-Id | The execution ID the vendor must include in the callback URL |
X-Callback-Message | The 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.
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.
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 < for < and > for >:
<conditionExpression>${amount < 5000}</conditionExpression>
Or wrap in CDATA:
<conditionExpression><![CDATA[${amount < 5000}]]></conditionExpression>
In <mbu:path> and <mbu:payload>, use & for & in query strings:
<mbu:path>/v1/latest?from=GBP&to=EUR</mbu:path>
FEEL script tasks
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
| Element | Supported |
|---|---|
<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 event | Yes. 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 tasks | No |
| Signal events | No |
| Data objects | No |
What's next
- Worked Examples — five complete patterns: sync HTTP, async fire-and-forget, inbound callback, human approval loop, and calling another process
- Getting Started — step-by-step quickstart tutorial
- Mambu Flows API Overview — API categories and endpoint index