In this recipe, we will examine how to define composite sensors for tracing purposes. Further, we will also show you the ways to define sensors in a BPEL process. We define composite sensors at the level of SCA when we want to monitor input and output messages of a BPEL process. Composite sensors also provide a convenient way of tracking fields on messages.
As a starting point, we need a BPEL process. We can define a new one or reuse an existing one. For this recipe, we will extend the BPEL process that we used in the Creating a custom logger in a BPEL process recipe.
In this recipe, we will walk through the steps needed to define a composite sensor in SCA:
- Initially, open the composite of the BPEL process. In the composite, select the BookHotelSvc service. Then, right-click and select Configure Sensors… from the toolbar as shown in the following screenshot:
- We choose to add the sensor to the composite and fill the dialog with the data as shown in the following screenshot:
- Then, click and get the sensor defined at the composite. Spot the sensor icon at the top right corner of the following screenshot:
The most interesting part of the composite sensor definition is the Add dialog. The fields in the dialog have the following meaning:
- Name: In this field, we enter the name of the composite sensor. We see the sensor name later in the flow trail of the Oracle SOA Suite Enterprise Manager Console.
- Operation: In this field, we specify which operation on a web service that sensor will monitor.
- Expression: In this field, we define the expression that sensor will evaluate. The expressions can be as follows:
- variables: The sensor gets the value of the variable we select from the variables dialog
- expressions: The sensor gets the value of the expression we define through the Expression Builder
- properties: The sensor gets the value of the message header property
- Filter: In this field, we define when the sensor is triggered. We can define, for example, whether the sensor is triggered when a customer wants approval for a loan of a predefined amount at the bank.
- Composite Sensor Action: In this field, we define where the value of the sensor will be reported. For composite sensors, the values can only be reported to the database.
The Oracle SOA Suite also provides the ability to define the sensors inside a BPEL process. Three types of sensors can be defined: variable, activity, and fault. We use the BPEL sensors to collect information that is interesting to us during the BPEL process instance lifecycle. Within the business process, we can check the activation and completion of a specific activity or monitor a modification of a variable value inside the BPEL process. The activity sensors are used to monitor the execution of an activity. It is also possible to monitor the variables of an activity. Variables sensors are used to monitor the variable of a BPEL process, for example, input and output messages. Fault sensors are used to monitor BPEL process faults.
In JDeveloper, in the top-right of the BPEL layout window, we click on the Monitor button. We are going to define a variable sensor to monitor the room price in the BPEL process:
- The following window is shown in JDeveloper as part of the process tree structure. We can see the sensors section with three subsections (Activity, Variable, and Fault) in the following screenshot:
- Select the Variable subsection, right-click, and choose Create. The dialog opens, and inside this dialog, we define the following fields:
- Name: In this field, we enter the name of the sensor (
RoomPriceSensor) - Target: This field is used to specify the BPEL process variable for the sensor (
$GetRoomPrice_getPrice_InputVariable/parameters/ns2:getPrice) - Configuration: In this field, we enter the specification of the sensor variable (see
VariableConfigtag in next code) - Sensor Action: This field defines where the information about sensor values will be stored
<sensor sensorName="RoomPriceSensor" classname="oracle.tip.pc.services.reports.dca.agents.BpelVariableSensorAgent" kind="variable" target="$GetRoomPrice_getPrice_InputVariable/parameters/ns2:getPrice"> <variableConfig outputDataType="getPrice" outputNamespace="http://axis.ws.packt.org"/> </sensor>
- Name: In this field, we enter the name of the sensor (
- Finally, when you click on OK, the variable sensor is defined in the BPEL process. We can see that we get a new file in the top level project structure named
BPELProcessSeq_sensor.xml. This file holds the sensor definitions.
Similar to defining a variable sensor, we can define an activity sensor in BPEL as shown in the following steps:
- In the Activity subsection, right-click and choose Create. The dialog opens and we fill it with the following data:
- Name: This field is used to specify the name of the sensor (
RoomPriceSensorActivity). - Activity Name: This field is used to specify the activity for the sensor (
GetRoomPrice). - Configuration: In this field, we enter the specification of the sensor variable (see the variable tag in the next code snippet). We define which variable will be used for the sensor and the time when the evaluation for the sensor will be performed. The evaluation time is defined as shown in the following table:
Evaluation time
Description
Activation
This evaluation is performed just before the activity is executed.
Completion
As opposed to the Activation, this evaluation is performed immediately after the activity is executed.
Fault
The sensor is evaluated in case of fault occurrence during the activity execution.
Compensation
The sensor is evaluated when the associated scope is compensated. When the BPEL process has a compensation handler defined and the fault occurs in the BPEL process, the compensation handler procedure is executed. At the start of the compensation activity, the event is fired to monitor the activity.
Retry
The sensor is evaluated when the activity is retried.
All
The sensor includes all of the above situations.
- Sensor Action: This field defines where the information about sensor values will be stored.
We define the activity sensor of the
GetRoomPriceInvoke activity. We will check the sensor value upon the completion of the activity as shown in the following code:<sensor sensorName="RoomPriceSensorActivity" classname="oracle.tip.pc.services.reports.dca.agents.BpelActivitySensorAgent" kind="activity" target="GetRoomPrice"> <activityConfig evalTime="all"> <variable outputDataType="RoomPrice" outputNamespace="http://axis.ws.packt.org/xsd" target="$GetRoomPrice_getPrice_OutputVariable/parameters/ns2:getPriceResponse/ns2:return"/> </activityConfig> </sensor>
- Name: This field is used to specify the name of the sensor (
- Click on OK and you'll get the activity sensor defined in the BPEL process.
Similar to defining a variable and activity sensor, we can define a fault sensor in BPEL as shown in the following steps:
- In the Fault subsection, we right-click and choose Create. The dialog opens and we fill it with the following data:
- Name: This field is used to specify the name of the sensor (
CarFaultSensor) - Fault QName: This field is used to specify the fault used for the sensor (
sns1:BookCarServiceInvalidDatesException) - Sensor Action: This field defines where the information about sensor values will be stored
<sensor sensorName="CarFaultSensor" classname="oracle.tip.pc.services.reports.dca.agents.BpelFaultSensorAgent" kind="fault" target="sns1:BookCarServiceInvalidDatesException"/>
- Name: This field is used to specify the name of the sensor (
- Click on OK and you'll get the fault sensor defined in the BPEL process.
The sensors in BPEL have a wider range of sensor actions than the ones in composite. The sensor actions define where the sensor data will be published. Depending on the sensor action we define, the sensor data gets published into the defined endpoint. The sensor actions that can be associated with BPEL sensors are as follows:
- Database: This is where the sensor data is stored into the database
- JMS queue: This is where the sensor data is published via the JMS queue
- JMS topic: This is where the sensor data is published via the JMS topic
- Custom: This is where the sensor data is sent to the custom Java class
- JMS adapter: This is where the sensor data is published to the JMS queue/topic of various providers