Skip Headers
Oracle® Fusion Middleware Developer's Guide for Oracle SOA Suite
11g Release 1 (11.1.1.5.0)
Part Number E10224-09
Go to Documentation Home
Home		 Go to Book List
Book List		 Go to Table of Contents
Contents		 Go to Index
Index		 Go to Feedback page
Contact Us
Go to previous page
Previous		 Go to next page
Next
PDF · Mobi · ePub

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:

For more information about sensors, see the following sections:

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 be sent to the BAM adapter.

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

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

These sensors are exposed through the following public SQL views:

These views can be joined with the BPEL_PROCESS_INSTANCES view to associate the sensor value with the BPEL process instance that created the sensor values. For more information, see Appendix D, "Understanding Sensor Public Views and the Sensor Actions XSD."

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

See Section 17.2.2, "How to Configure Sensors" and Section 17.2.3, "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 a specified destination. If no sensor action is defined for a sensor, then nothing happens at runtime.

The following information is required 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 50.7, "Integrating BPEL Sensors Using Oracle BAM Sensor Action."

17.2 Configuring Sensors and Sensor Actions in Oracle JDeveloper

In Oracle JDeveloper, sensor actions and sensors are displayed as part of Monitor view.

17.2.1 How to Access Sensors and Sensor Actions

To access sensors and sensor actions:

  1. Select Monitor at the top of Oracle BPEL Designer, as shown in Figure 17-1.

    Figure 17-1 Monitor View

    Description of Figure 17-1 follows
    Description of "Figure 17-1 Monitor View"

    Figure 17-2 shows the sensor actions and sensors in the Structure window.

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

    Description of Figure 17-2 follows
    Description of "Figure 17-2 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.

  2. Add sensor actions by right-clicking the Sensor Actions folders and selecting Create > Sensor Action.

  3. Add activity sensors, variable sensors, or fault sensors as follows:

    1. Expand the Sensors folder.

    2. Right-click the appropriate Activity, Variable, or Fault subfolder.

    3. Click Create.

  4. Add sensors to individual activities by right-clicking an activity and selecting Create > Sensor. Figure 17-3 provides details.

    Figure 17-3 Creating an Activity Sensor

    Description of Figure 17-3 follows
    Description of "Figure 17-3 Creating an Activity Sensor"

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

17.2.2 How to Configure Sensors

This section describes how to configure activity, variable, and fault sensors.

To configure an activity sensor:

Assume you are monitoring a loan flow 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-4.

  1. Select Monitor at the top of Oracle BPEL Designer.

  2. In the Structure window, expand the Sensors folder.

  3. Right-click Activity, and select Create.

  4. To the right of the Activity Name field, click the Browse icon to select the activity for which to create the sensor. This is a required field.

    Figure 17-4 Creating an Activity Sensor

    Description of Figure 17-4 follows
    Description of "Figure 17-4 Creating an Activity Sensor"

    Activities that have sensors associated with them are identified with a magnifying glass in Oracle BPEL Designer.

    The Evaluation Time list shown in Figure 17-4 controls the point at which the sensor is fired.

  5. 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="GetCreditRating">

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

  6. If you want to create a variable sensor on the activity, then in the Activity Variable Sensors section, click the Add icon. This is an optional field.

To configure a variable sensor:

If you want to record all the incoming loan requests, you can create a variable sensor.

  1. In the Structure window, expand the Sensors folder.

  2. Right-click Variable, and select Create.

  3. Click the Edit icon to the right of the Target field to create a variable sensor for a variable (for this example, named input), as shown in Figure 17-5.

    Figure 17-5 Creating a Variable Sensor

    Description of Figure 17-5 follows
    Description of "Figure 17-5 Creating a Variable Sensor"

    Based on your selection for the Target field, the Output Namespace and Output Datatype fields are automatically filled in.

    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>

To configure a fault sensor:

If you want to monitor faults (for this example, from the identity service), you can create a fault sensor.

  1. In the Structure window, expand the Sensors folder.

  2. Right-click Fault, and select Create.

  3. Click the Browse icon above the Namespace field to select to create a fault sensor, as shown in Figure 17-6.

    Figure 17-6 Creating a Fault Sensor

    Description of Figure 17-6 follows
    Description of "Figure 17-6 Creating a Fault Sensor"

Based on your selection, the Namespace and Local Parts fields are automatically filled in.

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.3 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 the LoanApplicationSensor variable sensor created in Figure 17-5 to a JMS queue), then create a sensor action, as shown in Figure 17-7, and associate it with the LoanApplicationSensor variable.

To configure a sensor action:

  1. In the Structure window, right-click the Sensor Actions folder.

  2. Select Create > Sensor Action.

  3. Enter the details described in Table 17-1.

    Table 17-1 Sensor Actions Dialog

    Field Description

    Name

    Enter a name or accept the default name.

    Publish Type

    Select the destination to which to publish sensor data. For more information, see section Section 17.1, "Introduction to Sensors."

    JMS Connection Factory

    If your publish type is JMS Queue, JMS Topic, or JMS Adapter, specify the connection factory.

    Publish Target

    If your publish type is JMS Queue, JMS Topic, Custom, or JMS Adapter, specify the publish target. The publish target represents different things depending on the publish type specified:

    • If the publish type is a database, this field is left blank.

    • If the publish type is JMS Queue, JMS Topic, or JMS Adapter, this represents the JMS destination's JNDI name.

    • If the publish type is Custom, this represents the fully-qualified Java class name.

    Filter

    Enter filter logic as a boolean expression. A filter enables you to monitor sensor data within a specific range. For an example of a configured filter, see Figure 17-9 and Example 17-6.

    Enable

    Deselect this checkbox to disable a sensor action. By default, sensor actions are enabled. If you disable a sensor action by deselecting this checkbox, the action does not publish data.

Figure 17-7 Creating a Sensor Action

Description of Figure 17-7 follows
Description of "Figure 17-7 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>

Note:

You cannot specify a < (less than) sign in the Filter field of the Sensor Action dialog. If you do, Oracle JDeveloper translates the < sign to &lt; in the bpel_process_name_sensorAction.xml file. In addition, you cannot specify a < sign by directly editing the filename_sensorAction.xml file. This action causes an error.

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-8, and associate it with both CreditRatingSensor and LoanApplicationSensor.

Figure 17-8 Creating an Additional Sensor Action

Description of Figure 17-8 follows
Description of "Figure 17-8 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 was 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-9. There is no design-time validation of the filter query. You must ensure the query is correct.

Figure 17-9 Creating a Sensor Action with a Filter

Description of Figure 17-9 follows
Description of "Figure 17-9 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 bpel_process_name_sensorAction.xml configuration file. For example, assume you have a customer XML-schema element with namespace "http://myCustomer" and you want to create a filter on the customer age element. Therefore, you must manually declare the namespace for "http:/myCustomer" in the file before you can use it in your filter. Otherwise, it is not possible to create a valid query. Add xmlns:ns1="http://myCustomer" in the attribute declaration part of the file. You can then use ..../ns1:customer/ns1:age/... in your query.

  • 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-10. The name in the Publish Target field denotes a fully qualified Java class name that must be implemented. For more information, see Section 17.2.5, "How to Create a Custom Data Publisher."

Figure 17-10 Using the Custom Publish Type

Description of Figure 17-10 follows
Description of "Figure 17-10 Using the Custom Publish Type"

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

Figure 17-11 Using the JMS Adapter Publish Type

Description of Figure 17-11 follows
Description of "Figure 17-11 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 editing in 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.5 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-12 provides details.

    Figure 17-12 Project Properties Dialog

    Adding a BPEL library to a BPEL project
    Description of "Figure 17-12 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-13.

    Figure 17-13 Custom Data Publisher Class

    Sample custom data publisher class
    Description of "Figure 17-13 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 class path.

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

The Oracle Enterprise Manager Fusion Middleware Control 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 and Oracle BPM Suite.

Notes:

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

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

Go to previous page
Previous		 Go to next page
Next
Go to Documentation Home
Home		 Go to Book List
Book List		 Go to Table of Contents
Contents		 Go to Index
Index		 Go to Feedback page
Contact Us