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.

101 - Sending data to the BAM API

  • 4 minute(s) read
Prev Next

Overview

Business Activity Monitoring (BAM) tracks your integration flows by receiving events at two API endpoints: StartTransaction and CheckPoint. You call these endpoints from any HTTP-capable service — Logic Apps, Function Apps, API Management, or custom code — to record the start, progress, and completion of a transaction instance.

This article shows you how to send API calls to the BAM API Function App using the sample Cab-Booking-Process that is pre-configured after installation.

Business value

Calling the BAM API directly gives you language-agnostic integration. Any service that can issue an HTTP POST request can participate in BAM tracking without installing a library or connector. This makes BAM accessible from legacy systems, third-party services, and custom runtimes where SDK-based options are not practical.

Prerequisites

  • A BAM environment deployed in your Azure subscription.
  • A business process configured in the Turbo360 portal (the sample Cab-Booking-Process is pre-configured after installation).
  • Your BAM Host URL and Functions App Key, available in Configuration > Connection details in the Turbo360 portal.

Required permissions

Permission Role
Read BAM configuration BAM Reader or higher
Send API calls to BAM endpoints BAM Contributor or higher

How it works

The BAM API Function App exposes three HTTP endpoints:

  • StartTransaction — opens a new transaction instance and returns a TransactionInstanceId used to correlate all subsequent stages.
  • CheckPoint — updates the status of an existing transaction at a named stage. Uses the TransactionInstanceId from the start call.
  • CheckPoint with Correlation — updates a transaction by matching a tracked property value rather than by TransactionInstanceId, which is useful for async flows where the original ID is unavailable.

Each call passes transaction metadata in HTTP headers (business process name, transaction name, stage name, stage status) and optional message data in the request body.

The code samples in this article use the VS Code REST Client extension, which lets you run .http files directly from the editor. Install it with:

code --install-extension humao.rest-client

Steps

The following steps show how to start a transaction and add checkpoints using the pre-configured Cab-Booking-Process. Navigate to Configuration > Connection details in the Turbo360 portal to obtain your Host URL and Functions App Key before starting.

Start a transaction

Starting a transaction opens a new tracking instance and returns the TransactionInstanceId needed for all subsequent checkpoint calls.

# @name StartTransaction
POST {{scheme}}://{{host}}/api/StartTransaction
x-functions-key: {{functionsKey}}
Content-Type: application/json
SL360-BusinessProcess: Cab-Booking-Process
SL360-Transaction: Details-Validator
SL360-Stage: Booking-Submission
SL360-StageStatus: Success
SL360-IsTransactionComplete: false

{
  "messageBody": {
    "AmountPayable": 2500,
    "BookingId": "BKG123456",
    "CustomerId": "CUST78910",
    "DropLocation": "Airport Terminal 3",
    "PickUpLocation": "Downtown Hotel"
  },
  "messageHeader": {}
}

The response includes the TransactionInstanceId. Capture this value — you pass it in the SL360-TransactionInstanceId header of every subsequent CheckPoint call.

Add a checkpoint

A checkpoint updates the transaction at a new stage, correlating it to the original instance via the TransactionInstanceId returned by the StartTransaction call.

# @name CheckpointBookingValidation
POST {{scheme}}://{{host}}/api/CheckPoint
x-functions-key: {{functionsKey}}
Content-Type: application/json
SL360-TransactionInstanceId: {{StartTransaction.response.body.$.TransactionInstanceId}}
SL360-Stage: Booking-Validation
SL360-StageStatus: Success
SL360-IsTransactionComplete: false

{
  "messageBody": {},
  "messageHeader": {}
}

Example scenario

The following script executes a complete cab-booking transaction: one StartTransaction call followed by two CheckPoint calls. Replace the placeholder values with your actual BAM host name and functions key from Configuration > Connection details.

# Variables
@scheme = https
@host = [Add BAM Host Name for API Functions Here]
@functionsKey = [Add Functions App Key Here]


# Start Transaction
# Notes:
# - Here we are starting a new transaction for the Cab Booking Process.
# - We pass in a message body which is parsed by BAM to promote some properties
# @name StartTransaction
POST {{scheme}}://{{host}}/api/StartTransaction
x-functions-key: {{functionsKey}}
Content-Type: application/json
SL360-BusinessProcess: Cab-Booking-Process
SL360-Transaction: Details-Validator
SL360-Stage: Booking-Submission
SL360-StageStatus: Success
SL360-IsTransactionComplete: false

{
  "messageBody": {
    "AmountPayable": 2500,
    "BookingId": "BKG123456",
    "CustomerId": "CUST78910",
    "DropLocation": "Airport Terminal 3",
    "PickUpLocation": "Downtown Hotel"
  },
  "messageHeader": {}
}

###

# Checkpoint to update that we are at the Booking-Validation stage
# Notes:
# - We pass in the transaction instance ID from the start transaction response to correlate this checkpoint with the ongoing transaction.
# @name CheckpointBookingValidation
POST {{scheme}}://{{host}}/api/CheckPoint
x-functions-key: {{functionsKey}}
Content-Type: application/json
SL360-TransactionInstanceId: {{StartTransaction.response.body.$.TransactionInstanceId}}
SL360-Stage: Booking-Validation
SL360-StageStatus: Success
SL360-IsTransactionComplete: false

{
  "messageBody": {},
  "messageHeader": {}
}

###

# Checkpoint to update that we are at the Booking-Accepted stage
# Notes:
# - Here we pass in the booking status as "Accepted" in the message header to indicate that the booking has been accepted.
# - We pass in the transaction instance ID from the start transaction response to correlate this checkpoint with the ongoing transaction.
# @name CheckpointBookingAccepted
POST {{scheme}}://{{host}}/api/CheckPoint
x-functions-key: {{functionsKey}}
Content-Type: application/json
SL360-TransactionInstanceId: {{StartTransaction.response.body.$.TransactionInstanceId}}
SL360-Stage: Booking-Accepted
SL360-StageStatus: Success
SL360-IsTransactionComplete: true

{
  "messageBody": {},
  "messageHeader": {
    "BookingStatus": "Accepted"
  }
}

Troubleshooting

  1. BAM API returns a 401 Unauthorized error.
    Cause: The x-functions-key header is missing or contains an incorrect Functions App Key.
    Fix: Copy the correct key from Configuration > Connection details in the Turbo360 portal and ensure it is passed as the x-functions-key header value.

  2. StartTransaction returns a 404 Not Found error.
    Cause: The BAM host URL is incorrect or the Function App is not running.
    Fix: Verify the host URL from Configuration > Connection details. Confirm the Function App is deployed and running in the Azure portal.

  3. TransactionInstanceId is null in the StartTransaction response.
    Cause: The request body or required headers are malformed.
    Fix: Ensure Content-Type: application/json is set and the SL360-BusinessProcess, SL360-Transaction, and SL360-Stage headers are present and match names configured in the Turbo360 portal.

  4. Checkpoint does not appear under the expected transaction instance.
    Cause: The SL360-TransactionInstanceId header value is incorrect or missing.
    Fix: Confirm the TransactionInstanceId value is copied exactly from the StartTransaction response and passed without modification.

  5. Stage status shows as failed when success was sent.
    Cause: The SL360-StageStatus header value does not match the expected casing (Success, Failure, or InProgress).
    Fix: Use the exact casing shown — Success, Failure, or InProgress.

Related articles