The Oracle BAM Adapter is a Java Connector Architecture (JCA)-compliant adapter which can be used from a Java EE client to send data and events to the Oracle BAM Server. The Oracle BAM Adapter supports the following operations on Oracle BAM data objects: inserts, updates, upserts, and deletes.

The Oracle BAM Adapter can perform these operations over Remote Method Invocation (RMI) calls (if they are deployed in the same farm), direct Java object invocations (if they are deployed in the same container), or over Simple Object Access Protocol (SOAP) (if there is a fire wall between them).

Make note of the JDNI names that you configure in the Oracle BAM Adapter properties, so that you can use them in the Oracle BAM Adapter wizard, Monitor Express configuration, and the Oracle BAM sensor action configuration in Oracle JDeveloper.

Activity Monitors and Monitoring Objects are used to capture BPEL process metrics, which are sent to Oracle BAM Server, and then used for analysis and graphic display. All of the connection, design, and deployment configuration is accomplished in Oracle JDeveloper.

Monitor Express ships with sample dashboards to demonstrate solutions you can build on top of the automatically deployed data objects. You can also build custom dashboards on the data objects generated by Monitor Express using Oracle BAM Active Studio or with Oracle BAM data controls in an ADF application.

Using the BPEL Designer Monitor view in Oracle JDeveloper, you can create the following types of monitors on a BPEL process:

Counter monitoring objects capture the date and time when a particular BPEL activity event is encountered within the BPEL process. Counters may be useful for reporting the number of times a particular activity is executed over a period of time. See Section 50.3.4, "How to Configure Counters" for more information.

Interval monitoring objects capture the amount of time for the process to go from one BPEL activity event to another. Interval monitoring objects can help identify bottlenecks in the BPEL process. See Section 50.3.5, "How to Configure Intervals" for more information.

The All Activities option captures start and end time data for every activity in the BPEL process, including individual activities, scopes, and human tasks. An activity starts when the activation event for the activity is begun, and it ends when the completion event is finished.

The Scopes and Human Tasks Only option captures start and end time data for every scope and human task defined in the BPEL process. A scope starts when the first activity activation event within the scope is begun, and it ends when the final activity completion event within the scope is finished. A human task activity starts when the activation event for the human task activity is begun, and it ends when the completion event in the human task activity is finished.

The Human Tasks Only option captures start and end time data for every human task activity defined in the BPEL process.

The BPEL Process Only option captures start and end time data for the BPEL process.

You can disable Activity Monitors by deselecting the Enable Activity Monitoring checkbox.

When checked, the Enable Monitoring option in BPEL Designer enables all of the monitors and sensors in all BPEL processes in the current SOA composite application. It overrides any monitoring object-level enable flags.

When the Enable Monitoring option is not checked, a property called enableProcessSensors is added to composite.xml with the value false. That property disables all monitors and sensors in all BPEL processes in the current SOA composite application.

50.3.4 How to Configure Counters

Every time the BPEL process passes a snapshot of a Counter (which is attached to an activity in the BPEL process diagram), data is sent to Oracle BAM. The Counter indicates how often a BPEL activity is encountered, and creates a new record in an Oracle BAM data object with time data.

The Enabled checkbox enables or disables this particular monitoring object. If it is not enabled, the Interval is not evaluated during the BPEL process, therefore no data is sent to Oracle BAM.

The Start Activity defines the beginning of the Interval. Select a Start Activity from the list, and a single selection in the Evaluation Events list.

End Activity defines the end of the Interval. Select an End Activity from the list, and a single selection in the Evaluation Events list.

You can select Associated Indicators if a Business Indicator has been previously defined in the BPEL process. Selecting an associated indicator automatically provides two snapshots on the selected Business Indicator. This captures the Business Indicator metrics at the start and at the end of the Interval.

Note:

If you plan to include an associated indicator snapshot in the Interval, it is not recommended to use the main or receiveInput activities at the Activate evaluation event as the start or end points, because the variables in the XPath expression might not yet be populated.

BPEL activities of type receive, typically named receiveInput, allow the process to wait for a matching message to arrive. The arriving message is copied to a variable specified in the definition of the activity. The copy operation occurs between the activate and complete evaluation events, and not before or on activate. Therefore, caution must be taken when defining monitoring object snapshots on BPEL activities of type receive, especially if the activate evaluation event is chosen.

An empty Interval, one in which the start and end activities and evaluation events are the same, is valid, and it can be used to label Business Indicator snapshots. The Interval can be used to uniquely identify multiple snapshots for a single Business Indicator. Instead of configuring snapshots in the Business Indicator dialog, you can create an empty Interval for each snapshot you want to create for a Business Indicator, and select the Business Indicator's indicator reference in each Interval.

50.3.6 How to Configure Business Indicators

A Business Indicator monitoring object captures a snapshot of BPEL variables, specified by the metrics in the Business Indicator, or evaluates expressions, when the events specified in the Business Indicator are encountered in the BPEL process.

Use the Business Indicator dialog to configure a Business Indicator monitoring object.

The Enabled checkbox enables or disables this particular monitoring object. If it is not enabled, the configured expression in the Business Indicator is not evaluated during the BPEL process, therefore no data is sent to Oracle BAM.

Metrics are defined to evaluate an expression or variable when the events specified in the Business Indicator are encountered in the BPEL process.

Click the green plus icon to configure a metric. Metrics have a name, data type, and XPath expression.

Snapshots associate the Business Indicator with activities in the BPEL process. The snapshot tells the BPEL process at what point to evaluate the Business Indicator metrics. To create a snapshot, click the green plus icon.

Evaluation Events indicate at what point during the activity to evaluate the Business Indicator metrics. Select a Snapshot in the table and click Edit to select one or more evaluation events. You can pick multiple evaluation events within the BPEL activity on which to evaluate the metric.

Note:

Configuring a snapshot on the main or receiveInput activities at the Activate evaluation event is not recommended because the variables in the XPath expression might not yet be populated.

When the configuration is saved, a Business Indicator icon is displayed in the top right corner of the associated activity in the BPEL process diagram.

50.3.7 How to Add Existing Monitoring Objects to Activities

You can add previously created Counters and Business Indicators to activities in the BPEL process with a shortcut menu provided in the BPEL Designer Monitor view. This creates a new snapshot in the selected Counter or Business Indicator.

To add a monitor to an activity:

Right-click the activity to which you want to add the monitor, and select Add.

50.3.8 How To Configure BPEL Process Monitors for Deployment

When any BPEL process in the current SOA composite application contains monitoring objects, during the deployment of that composite, Oracle BAM data objects are created in Oracle BAM Server in the location specified in the monitor.config file.

Note:

The monitor.config file is created on demand. If there are no monitors configured in the BPEL process, there is no monitor.config file.

The monitor.config file does not appear automatically in Oracle JDeveloper Application Navigator when the first monitor object is created. The user must save all of the files in the project (using Save All), and then refresh the Application Navigator.

Path to the location of the data objects for the monitors configured in all of the BPEL process for the SOA composite application. If the directory does not exist, it is created during deployment. The path is relative to the root data object folder in Oracle BAM Server.

Note that there is only one data objects folder per SOA composite application. The application can contain many BPEL processes. All of the data objects associated with all of the BPEL processes in the application are created in this location.

When using the RMI protocol, as when Oracle SOA Server and Oracle BAM Server are deployed in separate domains, you must also configure trusted domain credentials for both Oracle SOA Server and Oracle BAM Server domains.

If Oracle BAM Server is unreachable or there are any problems with the deployment of the Oracle BAM data objects, and this property is set to true, deployment of the composite does not halt. If set to false and Oracle BAM Server is unavailable, the deployment fails.

This property corresponds to the Ignore BPEL Monitor deployment errors checkbox in the deployment configuration wizard.

50.3.9 What You Need to Know About Using the Monitor Express Dashboard

Oracle BAM provides a sample dashboard that you can use to monitor your BPEL process out of the box.

The Monitor Express dashboard and data object samples allow users to enable Oracle BAM for your SOA composite applications in relatively few steps from within Oracle JDeveloper. The ready-to-use dashboards provide a single integrated view to track Key Performance Indicators (KPIs) in real-time and promote operational efficiency. The rich user experience for monitoring is delivered by BPEL Monitor instrumentation in Oracle JDeveloper.

The data objects are located in the Samples/Monitors/ data object directory in Oracle BAM Architect, and the sample reports are located in the Shared Reports/Samples/Monitor Express/ folder in Oracle BAM Active Viewer.

If the samples are not installed on your system, the installation script and instructions are located in the SOA_ORACLE_HOME/bam/samples/bam/monitorexpress directory.

You can add columns and indexes to the data objects using Oracle BAM Architect. The custom columns and indexes you add in Oracle BAM Architect are preserved when a revised SOA composite application containing changes to BPEL process monitor configuration is deployed. See Chapter 52, "Defining and Managing Oracle BAM Data Objects" for information about adding columns and indexes.

If a data object already exists in the configured location at deployment time, it is used as is, or updated with the appropriate additional columns to accommodate messages from the BPEL process monitors.

Oracle BAM data objects cannot be changed if they are in use. If there are Oracle BAM dashboards open against BPEL process monitor data objects, and the data objects require changes upon deployment, the data object updates fail.

Date and time recorded when the Interval or Activity Monitor start activity was encountered.

INTERVAL_END_TIME

Date and time recorded when the Interval or Activity Monitor end activity was encountered.

START_SUBCOMPONENT_ID

An internal value that is used as a key field.

START_SUBCOMPONENT_TYPE

The type of the BPEL process activity being monitored by an interval. The human task type is used for Human Task activities.

START_SUBCOMPONENT_NAME

The display name of the process activity being monitored by an interval.

START_EVALUATION_EVENT

The event within the life cycle of the BPEL activity (activate, for example) at which the data is captured.

END_SUBCOMPONENT_ID

An internal value that is used as a key field.

END_SUBCOMPONENT_TYPE

The type of the BPEL process activity being monitored by an interval. The human task type is used for Human Task activities.

END_SUBCOMPONENT_NAME

The display name of the process activity being monitored by an interval.

END_EVALUATION_EVENT

The event within the life cycle of the BPEL activity (activate, for example) at which the data is captured.

SUBCOMPONENT_CREATOR

For future use.

INTERVAL_RUNNING_FLAG

Indicates if the Interval or Activity Monitor end activity is running. 1 indicates that the end activity has not been encountered. 0 indicates otherwise.

INTERVAL_RUNNING_TIME_IN_SEC

The length of time between the INTERVAL_START_TIME and INTERVAL_END_TIME in seconds.

INTERVAL_RUNNING_TIME_IN_MIN

The length of time between the INTERVAL_START_TIME and INTERVAL_END_TIME in minutes.

50.3.10.4 Understanding Business Indicator Data Objects

The data objects containing data captured by all of the Business Indicator metrics configured in a BPEL process are named BI_Partition_Name_Composite_Name_BPELPROCESS_Name.

A separate data object is created for each BPEL process in the SOA composite application that contains Business Indicator monitoring objects.

If a Business Indicator is referenced by an Interval monitoring object, some of the data related to the Interval (INTERVAL_NAME, INTERVAL_START_FLAG, and INTERVAL_END_FLAG) is captured in the Business Indicator data object.

Note:

If one of the metrics fails at the time of evaluation (snapshot) the data is not sent to Oracle BAM; however, the remaining metrics configured in the Business Indicator are evaluated at the snapshot. If the failed Business Indicator metric is encountered at another snapshot, the BPEL engine attempts to evaluate it.

Type of the subcomponent (invoke indicates a BPEL invoke activity, for example) where the Business Indicator data was captured. The human task type is used for Human Task activities.

SUBCOMPONENT_NAME

Name of the subcomponent (callbackClient, for example) where the Business Indicator data was captured

EVALUATION_EVENT

The event within the life cycle of the BPEL activity (activate, for example) at which the data is captured.

INTERVAL_NAME

The name of the Business Indicator-instrumented Interval monitoring object that lead to the Business Indicator data capture.

The field is null if the data was captured within an Activity Monitor.

INTERVAL_START_FLAG

Indicates whether the data was captured at the Interval start activity. 1=yes, NULL=otherwise.

The field is null if the data was captured within an Activity Monitor.

INTERVAL_END_FLAG

Indicates whether the data was captured at the Interval end activity. 1=yes, NULL=otherwise.

The field is null if the data was captured within an Activity Monitor.

LATEST

Indicates (with value "Y") the latest snapshot of a Business Indicator record for a particular composite/component instance (based on COMPOSITE_INSTANCE_ID and COMPONENT_INSTANCE_ID).

Allows the creation of dashboards that filter Business Indicator records so only the latest is used (a Business Indicator can have many snapshots in the same process, but LATEST indicates the most recent at any point in time).

METRIC_NAME

Contains the result of the XPath expression evaluated in the NAME metric.

Each METRIC_NAME field is the data type configured in the metric.

The NAME portion of these column names is the display name of the metrics configured in the Business Indicators.

There are as many METRIC_NAME fields as there are metrics configured in the BPEL process.

Metric names must be unique within a BPEL process to avoid name collisions in this data object.

50.3.10.5 Troubleshooting

This section contains Monitor Express troubleshooting information.

50.3.10.5.1 Controlling Oracle BAM Data Object Size

In Oracle BAM Server data objects, older data can be purged with an alert rule, so that the data object does not grow too large.

50.5 Using Oracle BAM Adapter in a SOA Composite Application

The Oracle BAM Adapter is used as a reference that enables the SOA composite application to send data to an Oracle BAM Server external to the SOA composite application.

50.5.1 How to Use Oracle BAM Adapter in a SOA Composite Application

You can add Oracle BAM Adapter references that enable the SOA composite application to send data to Oracle BAM Servers external to the SOA composite application.

To add an Oracle BAM Adapter reference:

In the Component Palette, select SOA.

Drag the BAM Adapter to the right swim lane.

This launches the Adapter Configuration wizard.

In the Service Name page, provide a Service Name and an optional Description.

In the Data Object Operation and Keys page,

Select a Data Object using the BAM Data Object Chooser dialog box.

When you click Browse the Data Object Chooser dialog box opens allowing you to browse the available Oracle BAM Server connections in the BAM Data Object Explorer tree. Select a data object and click OK.

Choose an Operation from the list.

Insert adds a row to the data object.

Upsert inserts new data into an existing row in a data object if the row exists. If the row does not exist a new row is created. You must select a key from the Available column to upsert rows in a data object.

Delete removes a row from the data object. You must select a key from the Available column to delete rows in a data object.

Update inserts new data into an existing row in a data object. You must select a key from the Available column to update rows in a data object.

Provide an appropriate display name in the Operation Name field for this operation in your SOA composite application.

To select Enable Batching select the checkbox.

The data cached in memory by the Oracle BAM Adapter of the Oracle BPEL Process Manager runtime is flushed (sent) to Oracle BAM Server periodically. The Oracle BAM component may decide to send data before a batch timeout if the cache has some data objects between automatically defined lower and upper limit values.

50.6 Using Oracle BAM Adapter in a BPEL Process

50.6.1 How to Use Oracle BAM Adapter in a BPEL Process

You can add the Oracle BAM Adapter to a BPEL process to send data to Oracle BAM as a step in the process. The Oracle BAM Adapter is used as a partner link and connected to an activity in the BPEL process.

To add an Oracle BAM partner link:

In the SOA Composite Editor in Oracle JDeveloper, double-click the BPEL process icon to open it in the BPEL Process Designer.

In the Component Palette, expand the BPEL Services panel.

Drag and drop the Oracle BAM Adapter into the Partner Links swim lane on the right side of the BPEL Process Designer.

In the Adapter Configuration wizard, enter a display name in the Service Name field and click Next.

When the wizard completes, a Web Services Description Language (WSDL) file by this name appears in the Application Navigator for the BPEL process or Oracle Mediator message flow. This file includes the adapter configuration settings you specify with this wizard.

In the Data Object Operation and Keys page,

Select a Data Object using the BAM Data Object Chooser dialog box.

When you click Browse the Data Object Chooser dialog box opens allowing you to browse the available Oracle BAM Server connections in the BAM Data Object Explorer tree. Select a data object and click OK.

Choose an Operation from the list.

Insert adds a row to the data object.

Upsert inserts new data into an existing row in a data object if the row exists. If the row does not exist a new row is created.

Delete removes a row from the data object.

Update inserts new data into an existing row in a data object.

Provide an appropriate display name in the Operation Name field for this operation in your SOA composite application.

To select Enable Batching select the checkbox.

The data cached in memory by the Oracle BAM Adapter of the Oracle BPEL Process Manager runtime is flushed (sent) to Oracle BAM Server periodically. The Oracle BAM component may decide to send data before a batch timeout if the cache has some data objects between automatically defined lower and upper limit values.

In the BPEL Process add an activity that you can use to map the source data to the new variable you created.

In the BPEL Process add an Invoke activity to send data to the Oracle BAM Adapter partner link you created. Add the variable you just created as the Input Variable.

Save all of the project files.

50.7 Integrating BPEL Sensors Using Oracle BAM Sensor Action

You can create sensor actions in Oracle BPEL Process Manager to publish sensor data into existing data objects on an Oracle BAM Server. When you create the sensor action, you can select an Oracle BPEL Process Manager variable sensor or activity sensor to get the data from and the data object in Oracle BAM Server in which you want to publish the sensor data.

The Oracle BAM Adapter supports batching of operations, but behavior with batching is different from behavior without batching. As the Oracle BAM Adapter is applied to BPEL sensor actions, the Oracle BAM sensor action is not part of the BPEL transaction. When batching is enabled, BPEL does not wait for an Oracle BAM operation to complete. It is an asynchronous call.

When batching is disabled, BPEL waits for the Oracle BAM operation to complete before proceeding with the BPEL process, but it does not roll back or stop when there is an exception from Oracle BAM. The Oracle BAM sensor action logs messages to the same sensor action logger as BPEL. See "Configuring Oracle BAM Batching Properties" in Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle BPM Suite for information about batching behavior.

These instructions assume you have installed and configured Oracle BAM.

Notes:

Connection factory configuration must be completed before using Oracle BAM sensor actions. Also, if the Oracle BAM Adapter is using credentials rather than a plain text user name and password, in order for the Oracle BAM Adapter (including Oracle BAM sensor actions used in BPEL) to connect to the Oracle BAM Server the credentials must also be established and mapped. See "Configuring the Oracle BAM Adapter" in Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle BPM Suite for more information.

50.7.1 How to Create a Sensor

Before you can create an Oracle BAM sensor action, you must first create a sensor in the BPEL process. You must create a sensor before creating a Oracle BAM sensor action.

Variable sensor

Restrictions: A Variable sensor's variable must be defined in a standalone XSD. This variable must not be defined inline in the WSDL file. If the variable has message parts, then there must be only one message part.

An Activity sensor containing exactly one sensor variable

Restrictions: Because you map the sensor data to a single Oracle BAM Server data object, the Activity sensor must contain only one variable. All of the Variable sensor restrictions also apply.

Note:

Any sensor that does not conform to these rules are be filtered from the Oracle BAM sensor action configuration dialog box. Also, if a sensor is created conforming to the restrictions, but the variable is deleted (rendering the sensor invalid), it does not appear in Oracle BAM sensor action configuration dialog box.

50.7.2 How to Create an Oracle BAM Sensor Action

When you create the Oracle BAM sensor action, you select the BPEL variable sensor or activity sensor from which to get data, and you select the data object in Oracle BAM Server to which you want to publish the sensor data.

Click the Browse icon to open the BAM Data Object Chooser dialog box to select the data object in Oracle BAM Server in which you want to publish the sensor data.

If you have not created a connection to Oracle BAM Server to select data objects, click the icon in the upper right corner of the BAM Data Object Chooser dialog box.

Operation

Select to Delete, Update, Insert, or Upsert a row in the Oracle BAM Server database. Upsert first attempts to update a row if it exists. If the row does not exit, it is inserted.

Available Keys/Selected Keys

If you selected the Delete, Update, or Upsert operation, you must also select a column name in the Oracle BAM Server database to use as a key to determine the row with which this sensor object corresponds. A key can be a single column or a composite key consisting of multiple columns. Select a key and click the > button. To select all, click the >> button.

Map File

Provide a file name to create a mapping between the sensor data (selected in the Sensor list) and the Oracle BAM Server data object (selected in the Data Object list). You can also invoke a mapper dialog box by clicking the Create Mapping icon (second icon) or Edit Mapping icon (third icon).

Filter

Enter an XPath expression to filter sensor action data that is sent to Oracle BAM. At runtime the XPath expression entered in the field is evaluated, and it must return true for the sensor action to be fired.

Enter filter logic as a boolean expression. A filter enables you to monitor sensor data within a specific range. For example, you may want to monitor loan requests in which the loan amount is greater that $100,000. In this case, you can enter an expression such as the following:

The data accumulated by the Oracle BAM component of the Oracle BPEL Process Manager runtime is flushed (sent) to Oracle BAM Server periodically. The Oracle BAM component may decide to send data before a batch timeout if the queue has some data objects between automatically defined lower and upper limit values.

If batching is enabled, performance is dramatically improved, but there is no transaction guarantee. The BPEL process continues to run without waiting for the data to get to the Oracle BAM Server.

If batching is not enabled, the BPEL process waits until the Oracle BAM Server confirms that the record operation was completed; however, if there is a failure, the exception from Oracle BAM Server is logged and the BPEL process continues. BPEL does not roll back the operation or stop when there is an exception from Oracle BAM.

You can use BPEL JMS sensor actions to send data to Oracle BAM from a SOA composite application by way of a JMS topic or queue, using Oracle BAM Enterprise Message Sources.

You can also use the generic JMS adapter at the SOA composite or BPEL level, and Enterprise Message Sources can read that data into Oracle BAM.

XSL must be used to transform the payload from the BPEL JMS sensor action. You can use the advanced XML processing option in Oracle BAM Enterprise Message Sources, including using XSL, to get to any attribute or node in the XML.