Querying transaction instances

Overview

Querying transaction instances lets you search and filter tracking data for the Custom Logging type in Business Activity Monitoring (BAM). You can locate specific transactions by property values, status, duration, tags, or exception details — without browsing records manually.

Business value

BAM's query interface answers the operational question "Where is the message?" in real time. Structured queries against tracked properties, exception codes, and elapsed time reduce the time spent diagnosing failures and allow you to narrow thousands of tracked transactions to the specific instance needing attention.

Prerequisites

Required permissions

How it works

Query data for the Custom Logging type is sourced from the SQL database set up for the BAM environment.

The Tracking section displays the latest 1,000 records for a given business process, ordered by transaction start time in descending order. You can adjust the number of records displayed per page using the Select Top field, and navigate to the next set of results using the Next button in the footer.

To retrieve the oldest records first, use an ascending sort: Order by = "ascending".

Query language

Turbo360 uses a Domain-Specific Language (DSL) for tracking queries. All properties defined in the business process configuration are searchable. BAM validates each query element and notifies you of any syntax errors.

Exact match

SenderId = "Milford"

Wildcard characters

SenderId like "%Milford%"
SenderId not like "%Milford%"
SenderId like "%Mi_ford%"

Comparison operators (integer properties)

Price > 10

Null values

Status = NULL

Combinations

SenderId = "Milford" and Price > 10

Groupings

(SenderId="Milford" and Price > 10) or (ReceiverId="Miles" and Price<10)

Assigned transactions

AssignedTo = "me"
AssignedTo = "mail_id"

These two queries are supported only in the Assigned Transactions tab.

Status and duration

Status = "inprogress" and TransactionDuration > "1min"

Free text search

You can search by entering a value directly in the query field rather than constructing a full query expression. BAM searches across all global properties and returns every transaction instance where any property matches the value you entered.

• Integer data types: enter the value without double quotes.
• String data types: enclose the value in double quotes.
• Date type: enter "getdate(MM/dd/yyyy HH:mm:ss)" in the query field.

Search by elapsed time

BAM supports querying transaction instances by elapsed time. The elapsed time appears in the Duration column on the Tracking page. You can also use this query in Query monitors to monitor transaction duration.

Supported time units: ms, s, min, hr, d.

Examples:

TransactionDuration < "1 ms"
TransactionDuration < "1 s"
TransactionDuration < "1 min"
TransactionDuration < "1 hr"
TransactionDuration < "1 d"

Search by exceptions

You can query transaction instances by exception code and exception message to track instances where exceptions occurred.

Prerequisites for exception queries

Before using exception-based queries, complete the following configuration:

1. Create global properties for exceptioncode and exceptionmessage — define these as data types NUMBER and STRING respectively.
2. Assign these global properties to a stage in the target transaction.

Example exception queries

exceptioncode = 100
exceptionmessage = "exception100"
exceptionmessage like "%exce%"

Search by tags

You can query transaction instances by the tags attached to them. The available tags are Ignored and Reprocessed.

Reprocessed = "true"
Ignored = "false"
Reprocessed = "false"
Ignored = "true"

Search by date properties

Use the getdate() function to search tracked properties of type Date.

Example — transactions where a date property is before a specific timestamp:

RaisedAt <= "getdate(04/25/2020 09:24:26)"

To search relative to the current time:

RaisedAt <= "currenttime()"

Advanced query

Use advanced queries when you need to search across many values for the same property. Instead of writing a long combination query, you choose a property and enter multiple values using commas, tabs, or new lines as delimiters.

Supported delimiters:

• Comma separated: value1, value2, value3
• Tab-separated: value1 value2 value3
• New line: one value per line

Steps

Use the following steps to save, import/export, and lock queries in the Tracking section. Navigate to Business Activity Monitoring > Tracking to get started.

Save a query

Saving a query stores your search criteria so you can reuse it without re-entering parameters each session.

1. Run a query for the required time period.
2. Click the dropdown arrow next to Save and select an option:
   • Save — saves the query under its current name. Use this to update an existing saved query.
   • Save As — saves the query as a new entry. Use this when saving a query for the first time or creating a variant of an existing one.
3. Enter a name for the query and click Save.

You can access saved queries using the Saved queries option at the top of the Tracking page. You can also set a query as the default by selecting the checkbox in the save blade.

Import or export a query

Importing and exporting queries lets you reuse saved query definitions across environments or share them with other users.

• To import: click Import in the Saved queries blade and select a downloaded query file in JSON format.
• To export: click Export in the Saved queries blade to download the saved query as a JSON file.

Lock a query

Locking a saved query prevents other users from editing or deleting it until the lock is released.

1. Open Saved queries.
2. Click the Actions menu next to the query you want to lock.
3. Select Lock.

Limitations

• The Custom Logging search interface supports wildcard characters, global properties, assigned transaction queries, and advanced multi-value search. These capabilities are not available in the Data Queries type.
• Advanced query is available only in the Custom Logging type.
• The Tracking page displays a maximum of 1,000 records per query execution.

Troubleshooting

1. Query returns no results after entering a search term.
   Cause: The property name used in the query does not match the tracked property name configured in the business process.
   Fix: Navigate to the business process configuration and verify the exact property names. Property names are case-sensitive in the DSL.

2. IntelliSense does not appear when typing a property name.
   Cause: Tracked properties have not been enabled for the business process, or the process has no configured transactions.
   Fix: Confirm that tracked properties are enabled in the business process configuration and that at least one transaction has been saved.

3. Exception-based query returns no results.
   Cause: The exceptioncode or exceptionmessage global properties have not been created or assigned to a stage.
   Fix: Create the global properties with the correct data types (NUMBER and STRING) and assign them to the relevant stage in the transaction configuration.

4. Date query returns unexpected results.
   Cause: Date values are entered in the wrong format, or the timezone offset is not accounted for.
   Fix: Use the format MM/DD/YYYY HH:mm:ss inside the getdate() function. Use currenttime() for relative queries.

5. Saved query is not visible to another user.
   Cause: Saved queries in the Custom Logging type are personal to the user who created them unless shared.
   Fix: Export the query as a JSON file and share it with the other user, who can then import it via the Saved queries blade.

Related articles

• Transaction instances
• Actions in transaction instances
• Assigning users to transaction instances
• Global property management