50 Integrating Oracle BAM with SOA Composite Applications

This chapter provides information about using the Oracle BAM Adapter in the SOA composite applications using Oracle JDeveloper.

This chapter contains the following topics:

50.1 Introduction to Integrating Oracle BAM with SOA Composite Applications

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).

Oracle BAM Adapter is configured in Oracle WebLogic Server Administration Console to provide any of these connection pools. See Section 50.2, "Configuring Oracle BAM Adapter" for more information.

Some configuration is required to connect SOA composite applications to Oracle BAM. See Section 50.4, "Creating a Design Time Connection to an Oracle BAM Server" for more information.

Oracle BAM Adapter can be used with various features in SOA composite applications by which you can send data to an Oracle BAM Server:

50.2 Configuring Oracle BAM Adapter

The Oracle BAM Adapter Java Naming and Directory Interface (JNDI) connection pools must be configured when you use the Oracle BAM adapter to connect with the Oracle BAM Server at runtime. For information about configuration see "Configuring the Oracle BAM Adapter" in Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle BPM Suite.

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.

When using an RMI connection between an SOA composite application and Oracle BAM Server, that is, when they are deployed in different domains, trusted domain configuration must be done in Oracle WebLogic Server Administrative Console. 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.3 Using Oracle BAM Monitor Express With BPEL Processes

The Monitor Express offering from Oracle BAM provides high level instrumentation of BPEL processes, automatically handling Oracle BAM data object deployment and population.

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.

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

  • Activity Monitors capture running time data for BPEL process activities, scopes, and human tasks. Activity Monitors can help identify bottlenecks in the 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.

  • 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.

  • Business Indicator monitoring objects capture a snapshot of BPEL variables or expressions at a specified activity event in the BPEL process.

When the SOA composite application is deployed, the Oracle BAM data objects corresponding to the BPEL process monitors are created or updated automatically.

This section contains the following topics:

Related Documentation

50.3.1 How to Access BPEL Designer Monitor View

To access BPEL Designer Monitor view, select Monitor in the BPEL Designer toolbar.

Description of bam_mon_menu.gif follows
Description of the illustration bam_mon_menu.gif

In Monitor view, the structure pane displays the Monitoring Objects folder. You can expand the folder to expose the Business Indicators, Intervals, and Counters folders.

monitor view structure pane
Description of the illustration bam_mon_struct.gif

50.3.2 How to Configure Activity Monitors

Configure and enable Activity Monitors to capture data on start and end times for the BPEL process including the individual BPEL activities, scopes, and human tasks.

To configure Activity Monitors:

  1. In the Monitor view of a BPEL process, click Activity Monitoring Configuration in the BPEL Designer tool bar.

    Description of bpel_mon_actconfig.gif follows
    Description of the illustration bpel_mon_actconfig.gif

  2. In the Activity Monitoring Configuration dialog, select Enable Activity Monitoring, and choose the Mode to configure the level of monitoring.

    Description of bpel_mon_actdialog.gif follows
    Description of the illustration bpel_mon_actdialog.gif

    • 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.

  3. Click OK.

    If Activity Monitors are enabled, data is sent to Oracle BAM data object at runtime. See Section 50.3.9, "What You Need To Know About Monitor Express Data Objects" for more information about Oracle BAM data objects for monitoring objects.

50.3.3 How To Create BPEL Process Monitoring Objects

Use the BPEL Designer Monitor view in Oracle JDeveloper to create BPEL process monitoring objects.

To create a BPEL process monitoring object:

  1. While in the Monitor view, open a context menu on an activity in the BPEL process diagram, select Create, and choose a monitoring object type from the list.

    activity shortcut menu
    Description of the illustration bam_mon_create_act.gif

    Alternatively, you can use the Monitoring Objects menu, located at the top left corner of the BPEL Designer window, to create monitoring objects.

    Description of bam_mon_create_menu.gif follows
    Description of the illustration bam_mon_create_menu.gif

    As another alternative, you can open a context menu for each Monitoring Objects type folder in the Structure pane to create a monitoring object.

    create from structure pane
    Description of the illustration bam_mon_create_struc.gif

    BPEL process configurable monitoring objects are available in three types: Counters, Intervals, and Business Indicators. See the following topics for more information.

  2. To enable the BPEL process monitoring objects at deployment, verify that the Enable Monitoring checkbox, located at the top left corner of the BPEL Designer Monitor view, is selected.

    Figure 50-1 Enable Monitoring Checkbox

    Description of Figure 50-1 follows
    Description of "Figure 50-1 Enable Monitoring Checkbox"

    When checked, the Enable Monitoring option in BPEL Designer enables all of the 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.

Use the Counter dialog to configure a Counter monitoring object.

Description of bam_mon_countconfig.gif follows
Description of the illustration bam_mon_countconfig.gif

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

To attach a snapshot of a Counter to a BPEL activity, click the Add icon in the Counter dialog. Then select an activity from the list.

Description of bam_mon_countact.gif follows
Description of the illustration bam_mon_countact.gif

Next, choose an evaluation event (an event within the activity), by clicking the browsing icon.

choose evaluation opint
Description of the illustration bam_mon_evalbrowse.gif

The Evaluation Event Chooser opens to let you select one or more evaluation events.

event chooser dialog
Description of the illustration bam_mon_eventchooser.gif

When the Counter snapshot configuration is complete, it is displayed as an N icon next to activity in the BPEL process diagram.

Description of bam_mon_counticon.gif follows
Description of the illustration bam_mon_counticon.gif

The Counter and its snapshot are represented in the structure pane.

Description of bam_mon_countstruc.gif follows
Description of the illustration bam_mon_countstruc.gif

50.3.5 How to Configure Intervals

An Interval monitoring object captures the amount of time to go from one activity to another in the BPEL process. The start and end times are captured and sent to an Oracle BAM data object.

Use the Interval dialog to configure an Interval monitoring object.

interval configuration dialog
Description of the illustration bam_mon_intconfig.gif

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.

The Interval is represented in the structure pane.

Description of bam_mon_intstruc.gif follows
Description of the illustration bam_mon_intstruc.gif

On execution, the Interval start and end times are sent to Oracle BAM as a new record in a data object. See Section 50.3.9, "What You Need To Know About Monitor Express Data Objects" for information about the Oracle BAM data objects.

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.

business indicator dialog
Description of the illustration bam_mon_biconfig.gif

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.

define a metric
Description of the illustration bam_mon_bimetric.gif

You can enter an expression directly in the XPath field, or click Edit to open the Metric configuration dialog, and click Edit to use the Expression Builder.

Description of bam_mon_metric.gif follows
Description of the illustration bam_mon_metric.gif

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.

snapshot activity configuration
Description of the illustration bam_mon_bisnapact.gif

Note:

You can use empty Interval monitoring objects to uniquely identify snapshots of a particular Business Indicator. See Section 50.3.5, "How to Configure Intervals" for more information.

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.

Description of bam_mon_bi_icon.gif follows
Description of the illustration bam_mon_bi_icon.gif

The Business Indicator is also represented in the structure pane with its metrics and snapshots.

Description of bam_mon_bistruc.gif follows
Description of the illustration bam_mon_bistruc.gif

On execution, when a Business Indicator is encountered in the BPWL process, the metrics are evaluated and results sent to Oracle BAM as new records in a data object. See Section 50.3.9, "What You Need To Know About Monitor Express Data Objects" for information about the Oracle BAM data objects.

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:

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

    Description of bam_mon_add.gif follows
    Description of the illustration bam_mon_add.gif

  2. Select Counter or Business Indicator.

  3. Select one or more monitoring objects in the dialog and click OK. Press Shift-click to select multiple monitoring objects.

    select monitors
    Description of the illustration bam_mon_select.gif

  4. An icon appears within the activity boundary.

    Description of bam_mon_icon.gif follows
    Description of the illustration bam_mon_icon.gif

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.

Deployment is incremental, meaning that existing data objects are not deleted, and columns are added to data objects when required by the monitoring object configuration. See Section 50.3.9, "What You Need To Know About Monitor Express Data Objects" for details about the data objects.

To configure deployment properties:

In the Application Navigator project folder, open the monitor.config file for editing.

monitor configuration file
Description of the illustration bam_mon_config.gif

The monitor.config file defines deployment and runtime properties needed to connect with Oracle BAM Server to create and populate the data objects.

Caution:

Do not edit the BPELProcess.monitor file. It is an internal file, and it must not be edited manually. It stores the metadata for all of the BPEL process monitors in the specific BPEL process.

The default monitor.config file is shown in the following example.

<?xml version="1.0" encoding="UTF-8"?>
<MonitorConfig>
  <Connection>
    <BAM dataObjectsFolder="/Samples/Monitor Express/"
         adapterConnectionFactoryJNDI="eis/bam/rmi" batch="true"
         deploymentProtocol="http">
    </BAM>
  </Connection>
  <Deployment ignoreErrors="true"/>
</MonitorConfig> 

The properties are described in Table 50-1.

Define only one Connection block per BPEL project.

Table 50-1 Monitor Configuration Properties

Property Default Description

dataObjectsFolder

/Samples/Monitor Express/

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.

adapterConnectionFactoryJNDI

eis/bam/rmi

Oracle BAM Adapter connection pool configured in Oracle WebLogic Server Administration Console. Oracle BAM Adapter must be configured before deployment and runtime.

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.

See Section 50.2, "Configuring Oracle BAM Adapter" and Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle BPM Suite for more information.

batch

true

Indicates that batching using Oracle BAM Adapter is enabled. See Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle BPM Suite for information about batching configuration properties.

deploymentProtocol

http

The only valid value is http.

ignoreErrors

true

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 Monitor Express Data Objects

Oracle BAM data objects are deployed automatically when a SOA composite application containing enabled BPEL process monitors is deployed. Preseeded sample data objects are present in the Samples/Monitor Express/ directory.

You can use these data objects to construct Oracle BAM dashboards. See Oracle Fusion Middleware User's Guide for Oracle Business Activity Monitoring for information about creating dashboards in Oracle BAM Active Studio.

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.

Note:

Do not change the existing monitoring data object column names.

Oracle BAM Adapter Configuration

BPEL process monitors use Oracle BAM Adapter to convey messages to Oracle BAM Server. At deployment time, if Oracle BAM Server is unreachable, deployment fails. If Oracle BAM Server is unreachable at runtime, the retry behavior is determined by the Oracle BAM Adapter configuration. See Section 50.2, "Configuring Oracle BAM Adapter" and "Configuring Oracle BAM Adapter" in Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle BPM Suite for more information.

See the following sections for a detailed description of the data objects and troubleshooting information.

50.3.9.1 Understanding the COMPONENT Data Object

The COMPONENT data object is the main dimension table. It compiles information about how long a BPEL process instance takes to run, and if it has failed at least once.

This data object is always populated when at least one monitoring object is configured or if you have activity monitoring enabled.

Table 50-2 COMPONENT Data Object Fields

Column Name Description

COMPOSITE_INSTANCE_ID

SCA composite instance ID number.

COMPONENT_INSTANCE_ID

SCA component instance ID number. For BPEL it is the BPEL instance ID number.

DOMAIN_NAME

The partition name.

COMPOSITE_NAME

The name of the SOA composite application.

COMPOSITE_REVISION

The revision number of the SOA composite application.

COMPOSITE_LABEL

SOA composite application internal label.

This label is created every time you deploy even if you override the revision ID.

COMPONENT_TYPE

The component type (BPEL, for a BPEL process, for example).

COMPONENT_NAME

The component display name (The name of a BPEL process, for example).

COMPONENT_START_TIME

The date and time that the component started running.

COMPONENT_END_TIME

The date and time that the component stopped running.

COMPONENT_FAULT_FLAG

Indicates whether the component has faulted at least once. 1=faulted, 0=no fault.

FAULT_NAME

Name of the last fault that occurred.

COMPONENT_RUNNING_FLAG

Indicates whether the component is currently running. 1=the component is running, 0=the component is not running.

COMPONENT_RUNNING_TIME_IN_SEC

The calculated length of time between COMPONENT_START_TIME and COMPONENT_END_TIME in seconds.

COMPONENT_RUNNING_TIME_IN_MIN

The calculated length of time between COMPONENT_START_TIME and COMPONENT_END_TIME in minutes.

COMPONENT_COMPLETED_NO_FAULT_FLAG

Indicates whether the component completed with no faults. 1=completed with no fault, 0=either did not complete yet, or did complete with fault.

COMPONENT_INCOMPLETE_FLAG

Indicates that the component has not completed, and has faulted at least once. 1=has not completed, and has faulted at least once, 0=otherwise.


50.3.9.2 Understanding the COUNTER Data Object

The COUNTER data object contains data captured by all of the Counter monitoring objects encountered in the BPEL processes.

Table 50-3 COUNTER Data Object Fields

Column Name Description

COMPOSITE_INSTANCE_ID

SCA composite instance ID number.

COMPONENT_INSTANCE_ID

SCA component instance ID number. For BPEL it is the BPEL instance ID number.

DOMAIN_NAME

Lookup to DOMAIN_NAME field in COMPONENT data object.

COMPOSITE_NAME

Lookup to COMPOSITE_NAME field in COMPONENT data object.

COMPOSITE_REVISION

Lookup to COMPOSITE_REVISION field in COMPONENT data object.

COMPOSITE_LABEL

Lookup to COMPOSITE_LABEL field in COMPONENT data object.

COMPONENT_TYPE

Lookup to COMPONENT_TYPE field in COMPONENT data object.

COMPONENT_NAME

Lookup to COMPONENT_NAME field in COMPONENT data object.

COMPONENT_START_TIME

Lookup to COMPONENT_START_TIME field in COMPONENT data object.

COMPONENT_END_TIME

Lookup to COMPONENT_END_TIME field in COMPONENT data object.

COMPONENT_FAULT_FLAG

Lookup to COMPONENT_FAULT_FLAG field in COMPONENT data object.

FAULT_NAME

Lookup to FAULT_NAME field in COMPONENT data object.

COUNTER_NAME

The name of the Counter monitoring object.

SUBCOMPONENT_ID

An internal value that is used as a key field.

SUBCOMPONENT_TYPE

Type of the sub-component (sequence indicates a BPEL sequence activity, for example) where the Counter data was captured. The human task type is used for Human Task activities.

SUBCOMPONENT_NAME

Name of the sub-component (receiveInput, for example) where the Counter data was captured. In BPEL it is the name of the activity.

EVALUATION_EVENT

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

SNAPSHOT_TIME

Date and time when the Counter data was captured.


50.3.9.3 Understanding the INTERVAL Data Object

The INTERVAL data object contains data captured by all of the Interval monitoring objects and Activity Monitors configured in the BPEL processes.

Table 50-4 INTERVAL Data Object Fields

Column Name Description

COMPOSITE_INSTANCE_ID

SCA composite instance ID number.

COMPONENT_INSTANCE_ID

SCA component instance ID number. For BPEL it is the BPEL instance ID number.

DOMAIN_NAME

Lookup to DOMAIN_NAME field in COMPONENT data object.

COMPOSITE_NAME

Lookup to COMPOSITE_NAME field in COMPONENT data object.

COMPOSITE_REVISION

Lookup to COMPOSITE_REVISION field in COMPONENT data object.

COMPOSITE_LABEL

Lookup to COMPOSITE_LABEL field in COMPONENT data object.

COMPONENT_TYPE

Lookup to COMPONENT_TYPE field in COMPONENT data object.

COMPONENT_NAME

Lookup to COMPONENT_NAME field in COMPONENT data object.

COMPONENT_START_TIME

Lookup to COMPONENT_START_TIME field in COMPONENT data object.

COMPONENT_END_TIME

Lookup to COMPONENT_END_TIME field in COMPONENT data object.

COMPONENT_FAULT_FLAG

Lookup to COMPONENT_FAULT_FLAG field in COMPONENT data object.

FAULT_NAME

Lookup to FAULT_NAME field in COMPONENT data object.

INTERVAL_NAME

Display name of the Interval monitoring object, or the name of the activity, human task, or scope being monitored by Activity Monitors.

INTERVAL_TYPE

Indicates the type of BPEL process monitor where the data was captured.

CUSTOM indicates an Interval monitoring object configured with custom start and end times. Interval monitoring objects are described in Section 50.3.5, "How to Configure Intervals."

SUBCOMPONENT indicates an Activity Monitor. Activity Monitors are described in Section 50.3.2, "How to Configure Activity Monitors."

INTERVAL_START_TIME

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.9.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.

Table 50-5 Business Indicator Data Object Fields

Column Name Description

COMPOSITE_INSTANCE_ID

SCA composite instance ID number.

COMPONENT_INSTANCE_ID

SCA component instance ID number. For BPEL it is the BPEL instance ID number.

DOMAIN_NAME

Lookup to DOMAIN_NAME field in COMPONENT data object.

COMPOSITE_NAME

Lookup to COMPOSITE_NAME field in COMPONENT data object.

COMPOSITE_REVISION

Lookup to COMPOSITE_REVISION field in COMPONENT data object.

COMPOSITE_LABEL

Lookup to COMPOSITE_LABEL field in COMPONENT data object.

COMPONENT_TYPE

Lookup to COMPONENT_TYPE field in COMPONENT data object.

COMPONENT_NAME

Lookup to COMPONENT_NAME field in COMPONENT data object.

COMPONENT_START_TIME

Lookup to COMPONENT_START_TIME field in COMPONENT data object.

COMPONENT_END_TIME

Lookup to COMPONENT_END_TIME field in COMPONENT data object.

COMPONENT_FAULT_FLAG

Lookup to COMPONENT_FAULT_FLAG field in COMPONENT data object.

FAULT_NAME

Lookup to FAULT_NAME field in COMPONENT data object.

BI_NAME

Name of the Business Indicator.

SNAPSHOT_TIME

Date and time recorded when the Business Indicator data was captured.

SUBCOMPONENT_ID

An internal value that is used as a key field.

SUBCOMPONENT_TYPE

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.

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.9.5 Troubleshooting

This section contains Monitor Express troubleshooting information.

50.3.9.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.

See Chapter 57, "Creating Oracle BAM Alerts" for general information alerts, and see Section F.3.7, "Delete rows from a Data Object" for information about configuring the delete action.

50.3.9.5.2 Using the Logs

Monitor Express runtime logs messages using the oracle.soa.bpel.engine.sensor logger. For more information, see Configuring Log Files in Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle BPM Suite.

50.3.10 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.

50.4 Creating a Design Time Connection to an Oracle BAM Server

You must create a connection to an Oracle BAM Server to browse the available data objects and construct transformations while you are designing your applications in Oracle JDeveloper.

Note:

Oracle BAM Server connections should be created in Application Resources, directly, or by copying an existing connection from the Resource Catalog.

50.4.1 How to Create a Connection to an Oracle BAM Server

You create a connection to an Oracle BAM Server to browse data objects available on that server.

To create a connection to an Oracle BAM Server:

  1. From the File main menu in Oracle JDeveloper, select New.

    The New Gallery dialog box opens.

  2. From the General category, choose Connections.

  3. From the Items list, select BAM Connection, and click OK.

    The BAM Connection wizard opens.

  4. Ensure that Application Resources is selected.

  5. Provide a name for the connection.

  6. Click Next.

  7. Enter the connection information about the Oracle BAM Server host described in Table 50-6.

    Table 50-6 Oracle BAM Server Connection Information

    Field Description

    BAM Web Host

    Enter the name of the host on which the Oracle BAM Report Server and web applications are installed. In most cases, the Oracle BAM web applications host and Oracle BAM Server host are the same.

    BAM Server Host

    Enter the name of the host on which the Oracle BAM Server is installed.

    User Name

    Enter the Oracle BAM Server user name.

    Password

    Enter the password of the user name.

    HTTP Port

    Enter the port number or accept the default value of 9001. This is the HTTP port for the Oracle BAM web applications host.

    JNDI Port

    Enter the port number or accept the default value of 9001. The JNDI port is for the Oracle BAM report cache, which is part of the Oracle BAM Server.

    Use HTTPS

    Select this checkbox to use secure HTTP (HTTPS) to connect to the Oracle BAM Server during design time. Otherwise, HTTP is used.


  8. Click Next.

  9. Test the connection by clicking Test Connection. If the connection was successful, the following message appears:

    Testing HTTP connection ... success.
    Testing Data Object browsing ... success.
    Testing JNDI connection ... success.
     
    3 of 3 tests successful.
    
  10. Click Finish.

50.5 Using Oracle BAM Adapter in an 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 an 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:

  1. In the Component Palette, select SOA.

  2. Drag the BAM Adapter to the right swim lane.

    This launches the Adapter Configuration wizard.

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

  4. In the Data Object Operation and Keys page,

    1. 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.

    2. 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.

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

    4. 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.

      Batching properties are configured in BAMCommonConfig.xml. See Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle BPM Suite for more information.

  5. In the JNDI Name page, specify the JNDI Name for the Oracle BAM Server connection.

    The JNDI name is configured in the Oracle WebLogic Server Administration Console. See "Configuring the Oracle BAM Adapter" in Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle BPM Suite for more information.

  6. Click Finish.

50.6 Using Oracle BAM Adapter in a BPEL Process

The Oracle BAM Adapter is used as a partner link in a BPEL process to send data to Oracle BAM as a step in the process.

For more information, see Section 4.3, "Introduction to Partner Links."

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:

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

  2. In the Component Palette, expand the BPEL Services panel.

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

  4. 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.

  5. In the Data Object Operation and Keys page,

    1. 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.

    2. 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.

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

    4. 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.

      Batching properties are configured in BAMCommonConfig.xml. See Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle BPM Suite for more information.

  6. In the JNDI Name page, specify the JNDI Name for the Oracle BAM Server connection.

    The JNDI name is configured in the Oracle WebLogic Server Administration Console. See "Configuring the Oracle BAM Adapter" in Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle BPM Suite for more information.

  7. Click Finish.

  8. Create a new Process Variable in the BPEL process of type Message Type, and browse the Type Chooser dialog box to select the WDSL for the data object you want to write to on the Oracle BAM Server.

    For more information about using the Oracle BPEL Process Manager see Chapter 4, "Getting Started with Oracle BPEL Process Manager."

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

  10. 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.

  11. 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.

For more information about creating sensors, see Section 18.2, "Configuring Sensors and Sensor Actions in Oracle JDeveloper."

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.

To create an Oracle BAM sensor action:

  1. Go to your BPEL process in Oracle JDeveloper.

  2. Select Monitor from the BPEL Designer menu in the upper right corner.

    bpel designer menu
    Description of the illustration bam_mon_menu.gif

  3. In the Structure window, select and right-click Sensor Actions.

    structure pane
    Description of the illustration bam_sens_struct.gif

    If the Structure window is not open, select View > Structure Window to open it.

  4. Select Create > BAM Sensor Action.

    The Create Sensor Action dialog box appears.

    create sensor action dialog
    Description of the illustration bp_sensors_bam.gif

  5. Enter the details described in Table 50-7:

    Table 50-7 Create Sensor Action Dialog Box Fields and Values

    Field Description

    Action Name

    Enter a unique and recognizable name for the sensor action.

    Enable

    Select this option to enable the sensor action. When disabled no sensor action data is sent to Oracle BAM.

    Sensors can be also be disabled using the Oracle Fusion Middleware Control console.

    Sensor

    Select a BPEL sensor to monitor. This is the sensor that you created in Section 50.7.1, "How to Create a Sensor" for mapping sensor data to a data object in Oracle BAM Server.

    Data Object

    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:

    boolean(/s:actionData/s:payload/s:variableData/s:data/autoloan:loanAmount > 100000)
    

    See Figure 18-9, "Creating a Sensor Action with a Filter" for an example.

    BAM Connection Factory JNDI

    Specify the JNDI name for the Oracle BAM Server connection factory.

    The JNDI name is configured in the Oracle WebLogic Server Administration Console. See "Configuring the Oracle BAM Adapter" in Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle BPM Suite for more information.

    Enable Batching

    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.

    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.


    WARNING:

    If you restart Oracle BPEL Server, any messages currently being batched are lost. Ensure that all messages have completed batching before restarting Oracle BPEL Server.

    Notes:

    After you click the Create Mapping or Edit Mapping, or the OK button on the Create Sensor Action dialog box, you must explicitly save the BPEL file.
  6. Click OK to close the Create Sensor Action dialog box.

    You must complete the XSLT mapping the sensor action XML schema to the Oracle BAM data object schema.

50.8 Integrating SOA Applications and Oracle BAM Using Enterprise Message

You can use BPEL JMS sensor actions to send data to Oracle BAM from an 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.

See the following documentation for the relevant details: