Configuring stages in a transaction

Overview

Stage configuration in the Custom Logging type lets you define the milestones that make up a business transaction. For each transaction, you add one or more stages, configure their tracking properties, and connect them in the transaction flow diagram to represent the sequence of processing steps.

Business value

Configuring stages accurately maps your integration workflow to observable checkpoints in BAM. When a transaction fails, the stage configuration determines how granular your visibility is — and whether your support team can reprocess the failure directly from the affected stage rather than re-triggering the entire integration.

Prerequisites

Required permissions

The Manage transactions permission is also granted to users with the Account owner, Contributor, or Reader role.

How it works

Each stage in a Custom Logging transaction has a tracking name and a friendly name. The tracking name is used by BAM to correlate incoming data with the stage; the friendly name appears in the transaction diagram and instance views.

After creating a stage, you can configure custom properties on it. Properties extract values from the message payload as it passes through the stage — using XPath, JSON path, constant values, HTTP headers, or BizTalk context properties. These tracked values appear in the transaction instance view and can be used for filtering and correlation.

Optional settings per stage:

• Is Conditional Stage — renders the stage as a decision box in the transaction diagram. Use when the stage represents a branching condition.
• Mark transaction instance as completed — marks the transaction as complete when this stage executes, regardless of the IsTransactionComplete parameter in the checkpoint connector.
• Mark transaction instance as failed — marks the transaction as failed when this stage executes, regardless of the StageStatus parameter in the checkpoint connector.

Steps

Use the following steps to create and configure stages within a Custom Logging transaction. Navigate to the relevant business process in Business Activity Monitoring > Business Processes, then open the transaction you want to configure.

Create a stage

Adding a stage defines a new milestone in the transaction flow and makes it available for tracking and property configuration.

1. Go to the Transactions section in the business process.
2. Click Edit transaction flow on the relevant transaction.
3. Click Add Stage.
4. Enter a Tracking name and a Friendly name for the stage.
5. Configure optional settings if required (see How it works above).
6. Select the resource where this stage executes from the Executed at dropdown.
7. Click Add Property to add a Stage property or Global property if needed.
8. Click Add to save the stage.

After saving, connect the stage to other stages in the transaction flow as needed.

Configure properties

Configuring properties on a stage lets you extract and track specific values from the message payload at that milestone.

1. Go to the Transactions section in the business process.
2. Click Edit transaction flow on the relevant transaction.
3. Right-click the target stage and select Configure properties.
4. Click Add Property and choose Stage property or Global property.
5. Enter the Property Name, Property DataType, and Property Source (XPath, JSON, Constant, HTTP Header, or BizTalk Context).
6. Enter the Property Path for the value to extract.
7. Optionally, enter a regular expression in Extract value using regular expression to further filter the extracted value.
8. Click Add to save the property.

Enable index creation

Enabling index creation on a stage property improves query performance and BAM correlation when the property is used in CorrelationCheckpoint actions during instrumentation.

1. Open Configure properties for the stage (see above).
2. Enable the Create index option on the property.
3. Click Add to save.

Configuration

Property sources

The following property source types are available for stage properties in Custom Logging transactions:

Extract value using regular expression

To further filter an extracted property value, enter a valid regular expression in the Extract value using regular expression field.

Examples:

• [^\/:*?"<>|\r\n]+$ — extracts the file name from a path.
• ^[a-zA-Z]+$ — accepts only alphabetic characters.

Example scenario

A logistics company tracks order shipments through a Custom Logging transaction called Ship Order. The transaction has six stages: Receive Order, Is High Value, Notify High Value Team, Add to Power App, Add to SAP, and Add to Peoplesoft.

The Is High Value stage is configured as a conditional stage. The Receive Order stage has a stage property configured with a JSON path to extract the order value from the incoming message payload. Index creation is enabled on this property to support correlation queries.

When a shipment transaction fails at the Add to SAP stage, the support team can view the tracked order value in the transaction instance and reprocess directly from that stage to SAP without involving the source system.

Limitations

• Property configuration is only available in Custom Logging type transactions. Data Queries transactions do not support custom stage properties, index creation, or reprocess configuration.
• Stage connections in the transaction flow must be set manually. BAM does not infer flow order from the stage creation sequence.

Troubleshooting

1. Stage properties are not appearing in the transaction instance view.
   Cause: The property source path may be incorrect, or the message payload does not contain the expected field at that path.
   Fix: Verify the XPath or JSON path against a sample payload. Use the constant source type to confirm the stage is executing correctly before re-adding the expression-based source.

2. Index creation option is not available.
   Cause: Index creation is only available for stage properties, not global properties.
   Fix: Ensure you are adding a Stage property (not a Global property) and that the business process type is Custom Logging.

3. Conditional stage is not rendering as a decision box.
   Cause: The Is Conditional Stage option may not have been saved, or the transaction diagram has not refreshed.
   Fix: Re-open the stage editor, confirm the option is enabled, save, and reload the transaction flow.

4. Stage does not appear in the transaction diagram after creation.
   Cause: The stage was created but not connected to any other stage in the flow.
   Fix: Open Edit transaction flow and manually connect the new stage to the appropriate upstream and downstream stages.

5. Zoom in/Zoom out or Undo/Redo is not working in the transaction diagram.
   Cause: The transaction diagram editor requires keyboard focus.
   Fix: Click inside the diagram area to ensure it has focus, then use the Zoom and Undo/Redo controls.

Related articles

• Transaction stages
• Managing business transactions
• Configuring reprocess for transaction stages
• Querying transaction instances