Documentation Index

Fetch the complete documentation index at: https://docs.turbo360.com/llms.txt

Use this file to discover all available pages before exploring further.

Configuring stages in a transaction

  • 5 minute(s) read
Prev Next

Overview

Stage configuration in the Data Queries type lets you define the milestones that make up a business transaction. The configuration approach differs depending on the designer mode selected when the transaction was created — Auto-Generate or Manual.

Business value

Configuring stages in a Data Queries transaction lets BAM track integration activity by querying your existing observability data stores — Application Insights, Azure Data Explorer (ADX), or Log Analytics — rather than requiring custom instrumentation. You get end-to-end transaction visibility without modifying your integration code.

Prerequisites

Required permissions

Action Required permission
View stages within a transaction View transactions
Configure, edit, and delete transaction stages Manage transactions

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

How it works

Each stage in a Data Queries transaction has a tracking name and a friendly name. The tracking name is used internally by BAM; the friendly name appears in the transaction diagram and instance views.

The stage configuration experience depends on the designer mode chosen when the transaction was created:

  • Auto-Generate — you configure the transaction-level query and field mapping directly in the transaction panel. BAM automatically builds the stage diagram from a child query at runtime. There is no separate stage creation dialog.
  • Manual — you add each stage individually using the Create stage dialog, specifying the data source type and an optional conditional flag for each stage. The transaction diagram is built by connecting stages manually in the designer.

The optional settings for Data Queries stages include:

  • Correlation properties — properties that BAM uses to correlate query results to the correct transaction instance.
  • Stage status threshold — defines the conditions under which BAM marks the stage as completed or failed based on query result counts.

Steps

Use the following steps to configure stages within a Data Queries transaction. Navigate to your business process in Business Activity Monitoring and select Transactions to get started.

Configure stages (Auto-Generate mode)

In Auto-Generate mode, stage configuration is done at the transaction level in the transaction panel. After creating the transaction and executing the query, configure the field mapping and status conditions directly in the panel.

  1. Open the transaction in the Transactions section.
  2. Enter the Stages source query in the query editor and click Execute to validate it returns results.
  3. Map the following fields from the query result columns:
    • Stage name — the query column that identifies the stage.
    • Shape name — the query column used to map stages to diagram shapes.
    • Instance id — the query column that uniquely identifies each transaction instance.
    • Started at — the query column that represents the transaction start time.
    • Completed at — the query column that represents the transaction completion time.
    • Duration — the query column that represents transaction duration.
  4. In the Status section, define the conditions for each transaction status. For each row (Failure, Cancelled, In progress, Success), specify the Field, Condition, and Values from the query result that correspond to that status.
  5. In the Shape name mapping section, click + Add Mapping to map Shape name column values to event source stages. Conditions are evaluated in priority order — if the first condition matches a record, subsequent conditions are not evaluated for that record. For each mapping, specify the Condition, Values, and Executed at.
  6. Click Save to save the transaction configuration.

Create a stage (Manual mode)

In Manual mode, you add each stage individually using the Create stage dialog and build the transaction flow by connecting stages in the designer.

  1. Open the transaction in the Transactions section.
  2. Click + Add in the transaction designer to open the Create stage dialog.
  3. Enter a Tracking name and a Friendly name for the stage.
  4. Optionally, enable Is conditional stage? if this stage should only execute when a specific condition is met.
  5. Select the data source type from the Type dropdown — choose Application insight, Log analytics, or Azure data explorer.
  6. Click + Add to save the stage.
  7. Repeat for each stage in the transaction.
  8. Connect the stages in the transaction flow diagram to represent the processing sequence.

Example scenario

A data engineering team tracks API Management pipelines through a Data Queries transaction called Order Enrichment Pipeline. The transaction has three stages: Receive Request, Call Enrichment API, and Write to Data Lake.

Each stage is configured with a Log Analytics query that filters the relevant operation logs by a shared correlation ID extracted from the request headers. The stage status threshold is set to require at least one query result for the stage to be marked as completed. When no results are returned within the monitoring window, BAM marks the stage as failed, alerting the team to a gap in the pipeline.

Limitations

  • Stage properties, index creation, and reprocess configuration are not available in Data Queries transactions. These features are exclusive to Custom Logging type transactions.
  • The stage query must return results within the configured monitoring window for BAM to register the stage as completed.
  • Stage dependency configuration requires the parent stage to be defined before you can select it as a dependency.
  • Shape name mapping conditions are evaluated in priority order. Once a condition matches a record, subsequent conditions are not evaluated for that record.

Troubleshooting

  1. Stage query returns no results after the transaction runs
    Cause: The query may reference incorrect field names, an incorrect data source, or a time range that does not include the transaction.
    Fix: Test the query directly in App Insights, ADX, or Log Analytics using the same time range. Verify the correlation property values match the data in the store.

  2. Stage status is not updating after the monitoring cycle
    Cause: The monitoring cycle runs on a schedule. The stage may be correctly configured but the cycle has not yet run since the transaction executed.
    Fix: Wait for the next monitoring cycle to complete. Check the BAM dashboard to confirm the cycle is running.

  3. Dependent stage is not executing after the parent stage completes
    Cause: The dependency configuration may be referencing the wrong parent stage, or the parent stage is marked as failed and is blocking downstream execution.
    Fix: Review the stage dependency setting and confirm the parent stage is completing successfully before the dependent stage is expected to run.

  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 the transaction designer 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