This chapter describes how to use sensors to select BPEL activities, variables, and faults to monitor during runtime in a BPEL process. It also describes how to create sensor actions to publish the values of sensors to an endpoint.
This chapter includes the following sections:
For more information about sensors, see the following sections:
Section 53.7, "Integrating BPEL Sensors Using Oracle BAM Sensor Action" for how to create sensor actions in Oracle BPEL Process Manager to publish sensor data as data objects in an Oracle BAM Server
Appendix D, "Understanding Sensor Public Views and the Sensor Actions XSD"
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.
Activity sensors are used to monitor the execution of activities within a BPEL process. For example, they can 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 are used to monitor variables (or parts of a variable) of a BPEL process. For example, variable sensors can monitor the input and output data of a BPEL process.
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.
These sensors are exposed through the following public SQL views:
BPEL_ACTIVITY_SENSOR_VALUES
BPEL_FAULT_SENSOR_VALUES
BPEL_VARIABLE_SENSOR_VALUES
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:
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 18.2.2, "How to Configure Sensors" and Section 18.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:
Name
The publish type specifies the destination in which the sensor data must be presented. You can publish sensor data to the following destination 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 53.7, "Integrating BPEL Sensors Using Oracle BAM Sensor Action."
In Oracle JDeveloper, sensor actions and sensors are displayed as part of Monitor view.
To access sensors and sensor actions:
Select Monitor at the top of Oracle BPEL Designer, as shown in Figure 18-1.
Figure 18-2 shows the sensor actions and sensors in the Structure window.
Figure 18-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.
Add sensor actions by right-clicking the Sensor Actions folders and selecting Create > Sensor Action.
Add activity sensors, variable sensors, or fault sensors as follows:
Expand the Sensors folder.
Right-click the appropriate Activity, Variable, or Fault subfolder.
Click Create.
Add sensors to individual activities by right-clicking an activity and selecting Create > Sensor. Figure 18-3 provides details.
The following sections describe how to configure sensors and sensor actions.
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 18-4.
Select Monitor at the top of Oracle BPEL Designer.
In the Structure window, expand the Sensors folder.
Right-click Activity, and select Create.
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.
Activities that have sensors associated with them are identified with a magnifying glass in Oracle BPEL Designer.
The Evaluation Time list shown in Figure 18-4 controls the point at which the sensor is fired.
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 18-1:
Example 18-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>
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.
In the Structure window, expand the Sensors folder.
Right-click Variable, and select Create.
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 18-5.
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 18-2:
Example 18-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 (for this example, from the identity service), you can create a fault sensor.
In the Structure window, expand the Sensors folder.
Right-click Fault, and select Create.
Click the Browse icon above the Namespace field to select to create a fault sensor, as shown in Figure 18-6.
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 18-3:
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 18-5 to a JMS queue), then create a sensor action, as shown in Figure 18-7, and associate it with the LoanApplicationSensor variable.
In the Structure window, right-click the Sensor Actions folder.
Select Create > Sensor Action.
Enter the details described in Table 18-1.
Table 18-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 18.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:
|
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 18-9 and Example 18-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. |
A new entry is created in the bpel_process_name
_sensorAction.xml
file, as shown in Example 18-4:
Example 18-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 <
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 18-8, and associate it with both CreditRatingSensor and LoanApplicationSensor.
Figure 18-8 Creating an Additional Sensor Action
A new entry is created in the bpel_process_name
_sensorAction.xml
file, as shown in Example 18-5:
Example 18-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 18-9. There is no design-time validation of the filter query. You must ensure the query is correct.
Figure 18-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 18-6:
Example 18-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 18-10. The name in the Publish Target field denotes a fully qualified Java class name that must be implemented. For more information, see Section 18.2.5, "How to Create a Custom Data Publisher."
Figure 18-10 Using the Custom Publish Type
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 18-11.
Figure 18-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.
To create a custom data publisher, perform the following steps:
To create a custom data publisher:
In the Application Navigator, double-click the BPEL project.
The Project Properties dialog appears.
Click Libraries and Classpath.
Browse and select the following:
SOA_ORACLE_HOME\lib\java\shared\oracle.soainfra.common\11.1.1\orabpel.jar
Figure 18-12 provides details.
Create a new Java class.
The package and class name must match the publish target name of the sensor action.
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.
Using the Oracle JDeveloper editor, implement the publish method of the DataPublisher interface, as shown in the sample custom data publisher class in Figure 18-13.
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.
Oracle JDeveloper automatically updates the composite.xml
file to include appropriate properties for sensors and sensor actions, as shown in Example 18-7:
Example 18-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 18-7.
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 Business Process Management 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.