Subprocesses
Subprocesses group related activities and give them an explicit scope for variables, events, error handling, compensation, and reuse. Choose the subprocess type according to its lifecycle rather than only to make a large diagram visually smaller.
Choosing a Subprocess Type
| Type | Use it when | Key behavior |
|---|---|---|
| Embedded Subprocess | Steps belong only to the parent process | Runs inside the parent instance and deployment |
| Call Activity | A reusable process has its own version and lifecycle | Starts another deployed process and waits or continues according to configuration |
| Event Subprocess | An event must interrupt or supplement an active scope | Starts when its message, signal, timer, error, or escalation event occurs |
| Ad-hoc Subprocess | Activities may run in a flexible order | Enabled activities run zero or more times until the completion condition is met |
| Agentic Subprocess | AI selects from explicitly allowed activities | A governed ad-hoc loop with limits, persistence, and audit |
| Transaction Subprocess | A group of work has modeled compensation | Supports cancel and compensation behavior for completed activities |
| Multi-instance Activity or Subprocess | The same work repeats for a collection or count | Creates sequential or parallel instances with an optional completion condition |
Embedded Subprocess
An embedded subprocess is part of the parent process definition. It has no independently deployed version and cannot be started by another process.
Use it to:
- group a coherent phase such as validation or fulfilment;
- attach one boundary event to several internal activities;
- isolate local variables used only within the phase;
- collapse detail in the main diagram.
The subprocess completes when all active internal paths reach an end event or are otherwise completed. An unhandled error propagates to the parent scope.
Call Activity
A Call Activity invokes a separately deployed process definition. Use it when the child process is a reusable business capability with its own owner, version, tests, and operational lifecycle.
Configure:
- called process code and version-binding policy;
- business key propagation or mapping;
- input variables copied into the child instance;
- output variables copied back after completion;
- tenant and target-module rules;
- error, cancellation, and compensation behavior.
Prefer an explicit version or deployment binding for regulated and long-running processes. A floating “latest” binding can change the child behavior without changing the parent process version.
The parent and child are separate process scopes. Do not assume that business changes made in different services share one database transaction. Use idempotent operations, messages, and SAGA compensation across service boundaries.
Event Subprocess
An Event Subprocess is enabled while its containing scope is active. Its start event determines when it runs:
- interrupting — cancels the current work in the containing scope before starting;
- non-interrupting — starts alongside the current work and may run multiple times.
Typical patterns include timeout escalation, external cancellation, customer updates, security review, and compensating cleanup. The start event must be an event type supported for event subprocesses; it is not a normal none start event.
Use correlation keys for messages. A signal is broadcast and can activate every matching scope, so it should not be used where only one business instance must react.
Ad-hoc Subprocess
An ad-hoc subprocess contains activities without a fixed sequence flow. The runtime selects enabled activities and evaluates a completion condition.
Configure:
- the activities available in the scope;
- sequential or parallel ordering behavior;
- activity input/output mappings;
- completion condition;
- whether an activity can repeat;
- scope-level timeout and boundary events.
A deterministic ad-hoc subprocess can be controlled by process data or user choice. An Agentic Subprocess adds a governed agent that selects the next activity.
Agentic Subprocess
An Agentic Subprocess is a specialized ad-hoc subprocess. Each eligible child activity becomes a typed tool visible only inside that scope. The agent observes approved context and completed tool results, then proposes the next activity or finishes the scope.
The Process Engine enforces model-call, activity, repetition, concurrency, duration, token, cost, approval, and data limits. See Agentic Subprocess for complete configuration and runtime behavior.
Transaction and Compensation Subprocess
A transaction subprocess models a business transaction that can require compensation. It does not create a distributed ACID transaction across external systems.
Compensation reverses or mitigates already completed work using explicitly modeled compensation handlers. Every side-effecting activity should define:
- its idempotency key;
- what constitutes successful completion;
- whether and how it can be compensated;
- how a failed compensation is escalated.
Compensation runs in the order required by the process model and has its own audit and incidents. For cross-service patterns, see Process Transactions.
Multi-instance Execution
Multi-instance configuration repeats one activity or subprocess for a collection or a fixed count.
| Mode | Behavior | Use it when |
|---|---|---|
| Sequential | Starts the next instance after the previous one finishes | Ordering, rate, or shared-resource constraints matter |
| Parallel | Starts eligible instances concurrently | Items are independent and concurrency is bounded |
Configure the collection, element variable, optional index, output aggregation, concurrency policy, and completion condition. Do not put an unbounded business collection directly into a parallel multi-instance scope. Apply a platform limit or process batches.
For agent activities, each multi-instance item creates a separate Agent Run unless the subprocess explicitly defines one shared coordinator. Token, cost, and concurrency limits apply both per run and to the containing process.
Variable Scope
- Variables written locally belong to the subprocess or activity scope.
- Explicit output mapping copies selected values to the parent.
- A Call Activity receives and returns only mapped variables.
- Agentic scopes receive only allow-listed context variables; internal Agent Run state is not a normal process variable.
- Use stable document or artifact references instead of copying large binary or conversation data.
- Avoid using the same output variable from parallel paths without an explicit merge rule.
Boundary Events
A subprocess can have boundary events for timeout, message, signal, error, escalation, or compensation behavior. An interrupting boundary event cancels active child executions. A non-interrupting boundary event starts another path while the subprocess continues.
When canceling external, agent, or A2A work, the Process Engine records the cancellation request and ignores late results unless the process explicitly models reconciliation. Cancellation of a remote operation is not assumed to undo side effects already performed.
Design Checklist
- Does the subprocess own a clear business outcome?
- Should it be embedded or independently versioned as a Call Activity?
- Which variables are inputs, local state, and outputs?
- Where are the wait states and transaction boundaries?
- How do timeout, error, cancellation, and compensation leave the scope?
- Can parallel paths write the same data?
- Is every loop and multi-instance collection bounded?
- If the scope is agentic, are all activities typed, risk-classified, and protected by limits?