17 Using Oracle BPEL Process Manager Sensors

This chapter describes how to use sensors to select BPEL activities, variables, and faults to monitor during runtime. This chapter describes how to use and set up sensors for a BPEL process.

This chapter includes the following sections:

• Section 17.1, "Introduction to Sensors"

• Section 17.2, "Configuring Sensors and Sensor Actions in Oracle JDeveloper"

• Section 17.3, "Viewing Sensors and Sensor Action Definitions in Oracle Enterprise Manager Fusion Middleware Control Console"

For more information about sensors, see the following sections:

• Appendix D, "Understanding Sensor Public Views and the Sensor Actions XSD"

• Section 32.6, "Integrating BPEL Sensors with Oracle BAM" for how to create sensor actions in Oracle BPEL Process Manager to publish sensor data as data objects in an Oracle BAM Server

17.1 Introduction to Sensors

Sensors are used to declare interest in specific events throughout the life cycle of a BPEL process instance. In a business process, that can be the activation and completion of a specific activity or the modification of a variable value in the business process.

When a sensor is triggered, a specific sensor value is created. For example, if a sensor declares interest in the completion of a BPEL scope, the sensor value consists of the name of the BPEL scope and a time stamp value of when the activity was completed. If a sensor value declares interest in a BPEL process variable, then the sensor value consists of the value of the variable at the moment it was modified, a time stamp when the variable was modified, and the activity name and type that modified the BPEL variable.

The data format for sensor values is normalized and well-defined using XML schema.

A sensor action is an instruction on how to process sensor values. When a sensor is triggered by Oracle BPEL Process Manager, a new sensor value for that sensor is created. After that, all the sensor actions associated with that sensor are performed. A sensor action typically persists the sensor value in a database or sends the normalized sensor value data to a JMS queue or topic. For integration with Oracle Business Activity Monitoring, the sensor value can sent to the BAM adapter.

You can define the following types of sensors, either through Oracle JDeveloper or manually by providing sensor configuration files.

• Activity sensors

  Activity sensors are used to monitor the execution of activities within a BPEL process. For example, they can be used to monitor the execution time of an invoke activity or how long it takes to complete a scope. Along with the activity sensor, you can also monitor variables of the activity.

• Variable sensors

  Variable sensors are used to monitor variables (or parts of a variable) of a BPEL process. For example, variable sensors can be used to monitor the input and output data of a BPEL process.

• Fault sensors

  Fault sensors are used to monitor BPEL faults.

You typically add or edit sensors as part of the BPEL modeling of activities, faults, and variables.

When you model sensors in Oracle JDeveloper, two new files are created as part of the BPEL process archive:

• bpel_process_name_sensor.xml

  Contains the sensor definitions of a BPEL process

• bpel_process_name_sensorAction.xml

  Contains the sensor action definitions of a BPEL process

See Section 17.2.1, "How to Configure Sensors" and Section 17.2.2, "How to Configure Sensor Actions" for how these files are created.

After you define sensors for a BPEL process, you must configure sensor actions to publish the sensor data to an endpoint. You can publish sensor data to the BPEL dehydration store schema, to a JMS queue or topic, or to a custom Java class.

The following information is required for a sensor action:

• Name

• Publish type

  The publish type specifies the destination in which the sensor data must be presented. You can configure the following publish types:

  • Database

    Publishes the sensor data to the reports schema in the database. The sensor data can then be queried using SQL.

  • JMS queue

    Publishes the sensor data to a JMS queue. The XML data is posted in accordance with the Sensor.xsd file. This file is included with Oracle JDeveloper in the JDEV_HOME\jdeveloper\integration\seed\soa\shared\bpel directory.

  • JMS topic

    Publishes the sensor data to a JMS topic. The XML data is posted in accordance with the same Sensor.xsd file used with JMS queues.

  • Custom

    Publishes the data to a custom Java class.

  • JMS Adapter

    Uses the JMS adapter to publish to remote queues or topics and a variety of different JMS providers. The JMS queue and JMS topic publish types only publish to local JMS destinations.

• List of sensors

  The sensors for a sensor action.

Oracle BAM sensors publish information and events from Oracle BPEL Process Manager to Oracle BAM. Oracle BAM can display the data in rich real-time dashboards for end-to-end monitoring of an application. For more information, see Section 32.6, "Integrating BPEL Sensors with Oracle BAM."

17.2 Configuring Sensors and Sensor Actions in Oracle JDeveloper

In Oracle JDeveloper, sensor actions and sensors are displayed as part of the process tree structure, as shown in Figure 17-1.

Figure 17-1 Sensors and Sensor Actions Displayed in Oracle JDeveloper

Description of "Figure 17-1 Sensors and Sensor Actions Displayed in Oracle JDeveloper"

You typically add or edit sensors as part of the BPEL modeling of activities, faults, and variables. You can add sensor actions by right-clicking the Sensor Actions folders and selecting Create > Sensor Action. To add activity sensors, variable sensors, or fault sensors, expand the Sensors folder, right-click the appropriate Activity, Variable, or Fault subfolder, and click Create.

The following sections describe how to configure sensors and sensor actions.

17.2.1 How to Configure Sensors

Assume you are monitoring a LoanFlow application, and want to know the following:

• When a scope named getCreditRating is initiated

• When it is completed

• At completion, what is the credit rating for the customer

The solution is to create an activity sensor for the getCreditRating scope in Oracle BPEL Designer, as shown in Figure 17-2. Activities that have sensors associated with them are identified with a magnifying glass in Oracle BPEL Designer.

Figure 17-2 Creating an Activity Sensor

Description of "Figure 17-2 Creating an Activity Sensor"

The Evaluation Time list shown in Figure 17-2 controls the point at which the sensor is fired. You can select from the following:

• All:

  The sensor monitors during the activation, completion, fault, compensation, and retry phases.

• Activation

  The sensor is fired just before the activity is executed.

• Completion

  The sensor is fired just after the activity is executed.

• Fault

  The sensor is fired if a fault occurs during the execution of the activity. Select this value only for sensors that monitor simple activities.

• Compensation

  The sensor is fired when the associated scope activity is compensated. Select this value only for sensors that monitor scopes.

• Retry

  The sensor is fired when the associated invoke activity is retried.

A new entry is created in the bpel_process_name_sensor.xml file, as shown in Example 17-1:

Example 17-1 bpel_process_name_sensor.xml file

<sensor sensorName="CreditRatingSensor"

classname="oracle.tip.pc.services.reports.dca.agents.BpelActivitySensorAgent"
          kind="activity" 
          target="callbackClient">

  <activityConfig evalTime="all">
    <variable outputNamespace="http://www.w3.org/2001/XMLSchema"
              outputDataType="int" 
              target="$crOutput/payload//services:rating"/>
  </activityConfig> 
</sensor>

If you want to record all the incoming loan requests, create a variable sensor for the variable input, as shown in Figure 17-3.

Figure 17-3 Creating a Variable Sensor

Description of "Figure 17-3 Creating a Variable Sensor"

A new entry is created in the bpel_process_name_sensor.xml file, as shown in Example 17-2:

Example 17-2 bpel_process_name_sensor.xml file

<sensor sensorName="LoanApplicationSensor" 
    classname="oracle.tip.pc.services.reports.dca.agents.BpelVariableSensorAgent"
    kind="variable" 
    target="$input/payload">
  <variableConfig outputNamespace="http://www.autoloan.com/ns/autoloan"
                  outputDataType="loanApplication"/> 
</sensor>

If you want to monitor faults from the identity service, create a fault sensor, as shown in Figure 17-4.

Figure 17-4 Creating a Fault Sensor

Description of "Figure 17-4 Creating a Fault Sensor"

A new entry is created in the bpel_process_name_sensor.xml file, as shown in Example 17-3:

Example 17-3 bpel_process_name_sensor.xml file

<sensor sensorName="IdentityServiceFault"
        classname="oracle.tip.pc.services.reports.dca.agents.BpelFaultSensorAgent"
        kind="fault" 
        target="is:identityServiceFault">
    <faultConfig/>
</sensor>

17.2.2 How to Configure Sensor Actions

When you create sensors, you identify the activities, variables, and faults you want to monitor during runtime. If you want to publish the values of the sensors to an endpoint (for example, you want to publish the data of LoanApplicationSensor to a JMS queue), then create a sensor action, as shown in Figure 17-5, and associate it with the LoanApplicationSensor.

Figure 17-5 Creating a Sensor Action

Description of "Figure 17-5 Creating a Sensor Action"

A new entry is created in the bpel_process_name_sensorAction.xml file, as shown in Example 17-4:

Example 17-4 bpel_process_name_sensorAction.xml file

<action name="BAMFeed"
        enabled="true"
        publishType="JMSQueue"
        publishTarget="jms/bamTopic"> 
  <sensorName>LoanApplicationSensor</sensorName>
  <property name=“JMSConnectionFactory“> 
    weblogic.jms.ConnectionFactory
  </property>
</action>  
 

If you want to publish the values of LoanApplicationSensor and CreditRatingSensor to the reports schema in the database, create an additional sensor action, as shown in Figure 17-6, and associate it with both CreditRatingSensor and LoanApplicationSensor.

Figure 17-6 Creating an Additional Sensor Action

Description of "Figure 17-6 Creating an Additional Sensor Action"

A new entry is created in the bpel_process_name_sensorAction.xml file, as shown in Example 17-5:

Example 17-5 bpel_process_name_sensorAction.xml file

<action name="PersistingAction"
     enabled="true" 
     publishType="BPELReportsSchema">
  <sensorName>LoanApplicationSensor</sensorName> 
  <sensorName>CreditRatingSensor</sensorName>
</action

The data of one sensor can be published to multiple endpoints. In the two preceding code samples, the data of LoanApplicationSensor is published to a JMS queue and to the reports schema in the database.

If you want to monitor loan requests for which the loan amount is greater than $100,000, you can create a sensor action with a filter, as shown in Figure 17-7.

Figure 17-7 Creating a Sensor Action with a Filter

Description of "Figure 17-7 Creating a Sensor Action with a Filter"

A new entry is created in the bpel_process_name_sensorAction.xml file, as shown in Example 17-6:

Example 17-6 bpel_process_name_sensorAction.xml file

<action name="BigMoneyBAMAction"
        enabled='true' 
        filter="boolean(/s:actionData/s:payload
                        /s:variableData/s:data
                        /autoloan:loanAmount > 100000)"
        publishType="JMSQueue" 
        publishTarget="jms/bigMoneyQueue">
  <sensorName>LoanApplicationSensor</sensorName> 
  <property name=“JMSConnectionFactory“>
    weblogic.jms.ConnectionFactory 
  </property>
</action>   

Notes:

• You must specify all the namespaces that are required to configure an action filter in the sensor action configuration file.

• You must specify the filter as a boolean XPath expression.

If you have special requirements for a sensor action that cannot be accomplished by using the built-in publish types (database, JMS queue, JMS topic, and JMS Adapter), then you can create a sensor action with the custom publish type, as shown in Figure 17-8. The name in the Publish Target field denotes a fully qualified Java class name that must be implemented.

Figure 17-8 Using the Custom Publish Type

Description of "Figure 17-8 Using the Custom Publish Type"

17.2.3 How to Publish to Remote Topics and Queues

The JMS queue and JMS topic publish types only publish to local JMS destinations. If you want to publish sensor data to remote topics and queues, use the JMS adapter publish type, as shown in Figure 17-9.

Figure 17-9 Using the JMS Adapter Publish Type

Description of "Figure 17-9 Using the JMS Adapter Publish Type"

In addition to enabling you to publish sensor data to remote topics and queues, the JMS adapter supports a variety of different JMS providers, including:

• Third-party JMS providers such as Tibco JMS, IBM WebSphere MQ JMS, and SonicMQ

• Oracle Enterprise Messaging Service (OEMS) providers such as memory/file and database

If you select the JMS Adapter publish type, you must create an entry in the weblogic-ra.xml file, which is updated through the Oracle WebLogic Server Administration Console. Each JMS connection factory (pool) entry created in this console corresponds to one JNDI entry in weblogic-ra.xml. Update the Sensor Actions dialog with the chosen JNDI name selected during the creation of the JMS connection factory (pool).

For more information about the JMS adapter, see Oracle Fusion Middleware User's Guide for Technology Adapters.

17.2.4 How to Create a Custom Data Publisher

To create a custom data publisher, perform the following steps:

To create a custom data publisher:

1. In the Application Navigator, double-click the BPEL project.

   The Project Properties dialog appears.

2. Click Libraries and Classpath.

3. Browse and select the following:

   SOA_ORACLE_HOME\lib\java\shared\oracle.soainfra.common\11.1.1\orabpel.jar
   

   Figure 17-10 Project Properties Dialog

   
   Description of "Figure 17-10 Project Properties Dialog"
   
   

4. Create a new Java class.

   The package and class name must match the publish target name of the sensor action.

5. Implement the com.oracle.bpel.sensor.DataPublisher interface.

   This updates the source file and fills in the methods and import statements of the DataPublisher interface.

6. Using the Oracle JDeveloper editor, implement the publish method of the DataPublisher interface, as shown in the sample custom data publisher class in Figure 17-11.

   Figure 17-11 Custom Data Publisher Class

   
   Description of "Figure 17-11 Custom Data Publisher Class"
   
   

7. Ensure that the class compiles successfully.

   The next time that you deploy the BPEL process, the Java class is added to the SOA archive (SAR) and deployed.

Note:

Ensure that additional Java libraries needed to implement the data publisher are in the CLASSPATH.

Oracle BPEL Process Manager can execute multiple process instances simultaneously, so ensure that the code in your data publisher is thread safe, or add appropriate synchronization blocks. To guarantee high throughput, do not use shared data objects that require synchronization.

17.2.5 How to Register the Sensors and Sensor Actions in composite.xml

Oracle JDeveloper automatically updates the composite.xml file to include appropriate properties for sensors and sensor actions, as shown in Example 17-7:

Example 17-7 composite.xml File

<composite name="JMSQFComposite" applicationName="JMSQueueFilterApp"
   revision="1.0" label="2007-04-02_14-41-31_553" mode="active" state="on">
  <import namespace="http://xmlns.oracle.com/JMSQueueFilter"
  location="JMSQueueFilter.wsdl" importType="wsdl"/>
    <service name="client">          
      <interface.wsdl interface="http://xmlns.oracle.com/
         JMSQueueFilter#wsdl.interface(JMSQueueFilter)"/>
      <binding.ws
      port="http://xmlns.oracle.com/JMSQueueFilter#wsdl.endpoint(client/
         JMSQueueFilter_pt)"/>
    </service>
    <component name="JMSQueueFilter">
    <implementation.bpel src="JMSQueueFilter.bpel"/>
    <property name="configuration.sensorLocation" type="xs:string"
    many="false">JMSQueueFilter_sensor.xml</property>
    <property name="configuration.sensorActionLocation" type="xs:string"
    many="false">JMSQueueFilter_sensorAction.xml</property>
</component>
<wire>
   <source.uri>client</source.uri>
   <target.uri>JMSQueueFilter/client</target.uri>
</wire>
</composite>

You can specify additional properties with <property name= ...>, as shown in Example 17-7.

17.3 Viewing Sensors and Sensor Action Definitions in Oracle Enterprise Manager Fusion Middleware Control Console

The Oracle Enterprise Manager Fusion Middleware Control Console provides support for viewing the metadata of sensors, sensor actions, and the sensor data created as part of the process execution.

For more information, see Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite.

Notes:

• For this release, BAM sensor actions are not shown in Oracle Enterprise Manager Fusion Middleware Control Console.

• Only sensors with an associated database sensor action are displayed in Oracle Enterprise Manager Fusion Middleware Control Console. Sensors associated with a JMS queue, JMS topic, remote JMS, or custom sensor action are not displayed