Subprocess

A subprocess embeds a complete BPMN flow inside a parent process. It has its own start event, end events, tasks, and gateways.

<subProcess id="orderFulfillment" name="Order Fulfillment">
  <startEvent id="subStart" />
  <serviceTask id="reserveInventory" activiti:topic="reserveInventory" />
  <endEvent id="subEnd" />
  <sequenceFlow sourceRef="subStart" targetRef="reserveInventory" />
  <sequenceFlow sourceRef="reserveInventory" targetRef="subEnd" />
</subProcess>

Variable scoping

Subprocesses share the parent instance’s variable scope — there is no separate child scope. Variables written inside the subprocess are immediately visible to the parent and persist after the subprocess completes.

Execution behavior

1. The engine creates a child engine initialized with the parent’s current variables
2. The child engine runs to completion (or pauses on a waiting element)
3. When the child completes, its variables are merged back into the parent
4. The parent token advances past the subprocess element

If the child hits a waiting state (service task, timer, message), the child’s active tokens are added to the parent’s token set and stored in a subprocess frame stack. When the external event resolves, execution delegates back to the innermost subprocess frame.

Error handling

If the subprocess fails (error end event or failing service task), the parent:

1. Checks for an error boundary event on the subprocess — specific code match first, then catch-all
2. If found: cancels remaining child tokens and routes to the boundary’s outgoing flow
3. If not found: marks the parent instance as Failed and propagates the error code upward

<boundaryEvent id="handleFulfillmentError" attachedToRef="orderFulfillment" cancelActivity="true">
  <errorEventDefinition errorRef="FulfillmentError" />
</boundaryEvent>

Escalation handling

Escalations propagate differently from errors:

1. Check for an escalation boundary event on the subprocess — specific code first, then catch-all
2. If found: route to boundary (interrupting) or fork (non-interrupting)
3. If not found: check for an escalation event subprocess in the parent
4. If neither: execution continues normally past the subprocess (escalations do not fail the process)