Overview
A transaction stage is a named checkpoint within a Push Model business transaction. Stages define the discrete steps BAM tracks as a workflow progresses — for example, "Received", "Validated", "Dispatched", and "Completed" in an order fulfilment flow.
Together, the stages of a transaction define its expected lifecycle. Each stage is triggered when your integration solution emits an event to the BAM API at that point in the workflow. BAM matches the event to the stage, updates the corresponding transaction instance, and advances its tracked state.
Business value
Stages make it possible to pinpoint exactly where in a workflow a failure or delay occurred. Instead of knowing only that a transaction failed, your team can see which stage it reached last — and which one it never arrived at — reducing time spent diagnosing integration issues and enabling faster, more targeted incident response.
How it works
Each stage is part of a Custom Logging transaction and is reached when your integration emits an event to the BAM API containing the stage's tracking property values.
A stage has the following configuration:
- Name — A label that identifies the step (e.g. "Validated", "Sent to ERP"). The tracking name is used internally by BAM to match incoming events; the friendly name appears in the transaction diagram and instance views.
- Tracking properties — Key-value pairs extracted from the event payload at this stage. BAM uses these to correlate the event into the correct transaction instance. Property names must match exactly across all stages in a transaction.
- Conditional stage — Marks the stage as optional. If no event is received for this stage, BAM does not treat the transaction instance as incomplete or failed.
- Mark complete — When set, reaching this stage immediately marks the transaction instance as complete, regardless of whether other stages have been reached.
- Mark failed — When set, reaching this stage immediately marks the transaction instance as failed. Use this for explicitly instrumented error paths in your integration.
BAM does not require events to arrive in stage order. Events arriving out of sequence are still correlated into the same instance using the shared tracking property value. If an expected stage event is never received within the transaction's configured monitoring window, BAM can raise a duration alert.
Stage sequence and correlation
Stages are ordered within a transaction to define the expected execution sequence. A shared tracking property — such as an order ID or message correlation token — must appear in every stage event so that BAM can assemble the full instance across all stage calls. This correlation value is what links a "Received" event and a "Dispatched" event into a single, coherent transaction instance.
Limitations
- Tracking property names must match exactly across all stages in a transaction. A mismatch prevents BAM from correlating events into a complete instance.
- Each stage belongs to exactly one transaction. Stages cannot be shared across transactions.
- Deleting a stage removes all historical data associated with that stage from existing transaction instances. This action cannot be undone.
- Reordering stages after transactions have been tracked does not retroactively reorder historical instance data.
- Stage data is retained according to the purging policy configured on the business process.