Creating a business transaction definition

Create a business transaction definition in the web user interface by adding message flows to the canvas, then defining business events.

Before you begin

Ensure that the following prerequisites are in place:

WebSphere® MQ is installed and a queue manager is specified on the integration node. For more information about specifying a queue manager, see mqsicreatebroker command.
The default queues have been created on the queue manager. If they do not exist, you can create them by running the iib_createqueues script; for more information, see Creating the default IBM Integration Bus queues on a WebSphere MQ queue manager.
A database has been installed and configured for recording monitoring events and business transaction data. You can use a DB2® or Oracle database. Configure the database connection to the integration node by using the mqsisetdbparms command.
The message flows that are included in your business transaction are created and deployed.
Monitoring is enabled. Use the mqsireportflowmonitoring command to check whether it is active; if it is disabled, enable it by specifying the -c active parameter of the mqsichangeflowmonitoring command. For more information, see Activating monitoring.
Monitoring events are attached to the node, and the correlation information is set correctly. To be part of a business transaction, a flow must have events that are correctly defined and enabled, and that contain a global transaction ID when they are emitted by the flow. The global transaction ID is a unique ID such as a reference number or an order processing number, which is used to correlate all the events for a single business transaction. The global ID can either be derived from a previous node in the flow by using the automatic setting, or it can be set explicitly by using an XPath expression to specify a location in the message. A global transaction ID links events from a message flow to one or more related message flows or external applications. For more information, see Configuring monitoring event sources by using monitoring properties.
The web user interface is configured. For more information, see Configuring the IBM Integration Bus web user interface.

For background information about business transaction monitoring, see Business transaction monitoring.

About this task

A business transaction is a self-contained business function; for example, the booking of an airline ticket. A business transaction can consist of multiple message flows.

The business transaction definition contains information about the flows that participate in the transaction and the events that describe the transaction. This definition includes information such as which flows mark the beginning and end of a transaction, and which events correspond to a failure in the transaction.

To create a business transaction definition, complete the following steps:

Procedure

Run the DataCaptureSchema.sql script (or BIPRRDB JCL script on z/OS®) to create the monitoring events tables that are required for business transaction monitoring.
If these tables have already been created for use by the record and replay function, you can use the same tables for business transaction monitoring events. However, if the tables do not exist, or if you want to use a different schema for business transaction monitoring from the one that you use for record and replay, you must run the DataCaptureSchema.sql (or BIPRRDB) script as described in the relevant topic:
- Creating and configuring a DB2 database for recording data
- Creating and configuring an Oracle database for recording data
Run the BusinessCaptureSchema.sql script (or BIPBTMDB JCL script on z/OS) to create the database table that is required for recording and storing business transaction data, as shown in the following example:
```
db2 -tvf BusinessCaptureSchema.sql
```
The script is stored in the following location, depending on your database and operating system:
DB2
Windows: install_dir\server\ddl\db2\BusinessCaptureSchema.sql

Linux® or UNIX: install_dir/server/ddl/db2/BusinessCaptureSchema.sql

z/OS : the JCL script is in the data set and member SBIPPROC(BIPBTMDB). You must customize this script for your environment.
Oracle
Windows: install_dir\server\ddl\oracle\BusinessCaptureSchema.sql

Linux or UNIX: install_dir/server/ddl/oracle/BusinessCaptureSchema.sql
where install_dir is the location of your IBM Integration Bus installation.
The database tables are now ready to be used for recording and storing your business transaction data.
Access the web user interface, as described in Accessing the web user interface.
In the Navigator view for the relevant integration node, expand Business, then click Business Transactions.
The Configuration tab is displayed.
In the Configuration tab, select the data source name that will be used for your business transactions and then click Save. The database that is associated with the selected data source name is used for all business transactions in the integration node.
The default DataCapture policy is updated automatically with the data source name that you select in this tab. If you want to modify any additional properties in the default DataCapture policy, follow the instructions in Updating the default DataCapture policy.
To create your new business transaction definition, click the arrow next to Business Transactions, then click Create.
Enter a name and description for the business transaction, then click OK.

The name of the business transaction must be unique for the integration node. The name can contain only letters, numbers, and underscore (_) characters.

An empty business transaction definition is created on the Define tab. You can view the name and description of the business transaction by clicking the Business Transaction Details icon: . After you select the monitoring events that are relevant to your business transaction, these events are shown in this information pane. You can also view this information by clicking Details.
Populate the business transaction definition by adding the appropriate message flows to the business transaction profile.
In the Business Transaction section, click Add flow.
Select a flow from a list of available flows, or select all flows in a selected application, integration service, or REST API service, and then click Add.
If you add multiple message flows with the same name, from different applications, you can distinguish between them by viewing the deployment information that is displayed in the dialog, including the integration server and application name. You can also hover the cursor over each flow in the canvas to view the full path of that flow, including the application name.
If you need to remove a message flow from your definition, select the flow, then click Remove flow.
View the nodes and connections in a flow by selecting the flow in the business transaction profile section and expanding the Message Flow section. The Message Flow section shows icons on the nodes that have monitoring events.
Click an icon in the Message Flow section to see a tooltip with a definition of the monitoring events for the node. Click the icon in the tooltip to navigate to the appropriate event definition in the table.

When you select a flow in your business transaction, the Event Definitions table shows the monitoring events that are defined for that flow. If you click the white space around the flows in the Business Transaction section, the table shows all flows in the business transaction. Expand a flow to see the monitoring events that are defined for that flow.
Flag the monitoring event definitions that represent the start, end, failure, and progress of your business transaction.
1. In the Event Definitions table, expand the appropriate flow and identify an appropriate monitoring event.
2. In the Flag As column for that monitoring event, select Start, End, Failure, or Progress.
  - A start business transaction event signifies that when a message is received on that node, the business transaction starts. You can choose any monitoring event to represent the start of a business transaction.
  - An end business transaction event signifies that when a message is received on that node, the business transaction is complete. You can choose any monitoring event to represent the end of a business transaction.
  - A failure business transaction event typically corresponds with a node that handles error processing. This event signifies that when a message reaches this node, the business transaction has failed.
  - A progress business transaction event can correspond with any type of node in a message flow. This event is used to monitor the progress of a transaction instance and signifies that a message has reached a particular node in the flow.
  Relevant icons are added to the flow in the Message Flow section. Monitoring events that are set to Do not flag are not stored in the business transaction definition.
3. Click or hover over the icons to see what business events are defined for each flow.
  The Business Transaction Definition icon also lists the business events for the business transaction.
The business transaction definition requires a start event and an end event, and a warning message is displayed if they have not been defined. A warning message is also displayed if the flows have no monitoring events defined, or if no global ID has been specified for the events. The monitoring events must also be enabled; you can check whether an event is enabled or disabled by clicking More details, which displays the event properties. If these properties have not been set correctly, the flows cannot be monitored as part of the business transaction.
Save the business transaction definition.
The business transaction definition is shown in the Navigator view, beneath Business > Business Transactions.
Optional: If message flows are changed, update the business transaction definition with these changes by clicking Refresh.

What to do next

View the results of a business transaction on the View tab (see Viewing the results of business transaction monitoring).