SOA BPEL Sensors for Bam

Tech Note: Oracle BAM –BPEL Sensors webservice interface to BAM ADC

TechNote_BPELSensorsForBAM.doc of 18 Nov 6, 06 (version 10.1.3) Document version (5) Oracle confidential, All rights reserved

Supported Version: Oracle BAM 10.1.3 and Oracle BPEL 10.1.3

Objectives:

1. Understand Oracle BPEL process design for BAM sensor actions. 2. Configure Oracle BPEL process activities with BAM sensor definitions. 3. Configure and connect Jdev BPEL designer to BAM server connection. 4. Connect and browse BAM ADC data objects. 5. Define BPEL-BAM sensor action to populate BAM ADC data objects, including

insert/ update operation, mapping BPEL attributes to BAM ADC data object fields using XSLT translation.

Prerequisites:

1. Basic knowledge of BPEL and BAM. 2. Installed software – BPEL and BAM. 3. The sensor variables shouldn’t be defined inline in the WSDL and only import

xsd schema definitions are supported for BPEL-BAM sensors.

Assumptions:

1. Working installation of BPEL standalone server and BAM server on same machine. 127.OrderBooking tutorial is installed and working on the BPEL server.

2. User is familiar with BPEL and BAM technologies and XSLT transforms and Jdeveloper. OrderBooking process is used as an example in this document.

3. More details of BPEL sensors are given in the product documentation guide. 4. More details about OrderBooking Process are given in BPEL tutorial guide.

Introduction:

BPEL development environment has flexibility to directly send BPEL sensor data into BAM ADC for populating data objects without the use of Enterprise Link.

Initial State:

1. Start Oracle BAM server. (Version check- administrator window – about button, this should show - = 10g Release 3 (10.1.3) Build 3 5 5684 0 (or higher).

2. Start Oracle BPEL PM server. (*Version 10.1.3 or higher*) 3. Open Jdev, and open OrderBooking tutorial example. (Note- recommended to

copy 127.OrderBooking from BPEL/samples/tutorial subdirectory to c:\temp directory and open OrderBookingTutorial.jws in Jdeveloper.

4. Open Oracle BAM dashboard in IE browser (http://localhost/oraclebam) 5. Verify BAM webservice is available (open URL in IE browser

http://localhost/OracleBAM/inspection.wsil) -given at end of the document.

Creating BAM data objects:

We have to manually create the BAM ADC data objects for the OrderBooking Tutorial. Detailed steps for manually creating ADC data object is given in a separate tech note or tutorial document. (see Tutorial document for Creating Data Objects).



Implementing Sensors and Sensor Actions in JDeveloper BPEL Designer

In JDeveloper BPEL Designer, sensors and sensor actions are displayed as part of the process tree structure, as shown in figure below. 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. Note: The schema has to be imported in the BPEL WSDL file, it cannot be an inline defined schema. Using OrderBookingTutorial as an example, the following sections describe how to configure sensors and sensor actions. This tutorial does not disturb the process flow or other sensor activities defined in OrderBooking tutorial. You should have created a set of sensors (example in 127.OrderBookingTutorial) before adding the BPEL-BAM sensor actions. Note you can only add BPEL-BAM sensor “action” to the sensors that are already defined. JMSSensorAction is not a prerequiste for defining BAM sensor



Using OrderBookingTutorial as an example, the following sections describe how to configure sensors and sensor actions. This tutorial does not disturb the process flow or other sensor activities defined in OrderBooking tutorial.

Definitions of BAM sensor.

Sensor = Details of attributes to publish to sensor action, when the activity is complete (default setting – is activity complete). Sensor Action = The definition of action to take when a sensor is triggered. Note - To define a BAM sensor, it is required to define at least 1 BAM sensor. BAM sensor can only be defined from the structure window panel. (see below)

Creating the BAM server connection:

In the Jdesigner, select the connections panel (Menu-View-Connections). Right click on “New BAM Server Connection”, and in the server connection properties dialog box, provide the BAM server connection details as follows:

Host Name = ssondur-lap (your complete machine name)

Port Number = 80 (default BAM port)

User Name = ssondur (this should have admin rights to write into ADC objects)

Password = your_bam_password

Domain Name = SSONDUR-LAP (your windows domain in capitals, case sensitive) Click on Next, and click on Test to verify connection, and click on OK to save & close this definition.

Go back to the applications panel, click on the OrderBooking BPEL process diagram window. This will open the structures panel, scroll down to the Sensor Actions tab. Select Sensor Action, and click on create. The next section explains the steps to define a sensor to populate the timestamp of this sensor activity (Note – we need to know the time when this activity occurred).



Note: Evaluation Time has to be Completion. Other options are not suppported. Sensor variable has to be BPEL variable only, do not drill down to payload or other attribute or sub-node level

First Sensor: (process start)

Creating the first sensor: (by default, this is pre-designed, create this, if this is not pre-designed). Double click on receiveInput, and click on sensors tab. Give this a name – “InstanceComplete”. Click on create (or edit if sensor exists), and add an data variable for this sensor. Click on create (or edit if sensor data exists), and select inputVariable, and select evaluation time –Completion. Close these dialog boxes by clicking OK.

Next define the Sensor Action for the above sensor. Note that in the BAM Sensor Action definition, it is required to define one sensor action for each sensor activity because of the transformation involved. Also, it is required to define one sensor action for each of the data objects you need to populate. Note that the definition of sensor actions does not affect the performance of the main process execution. To define a sensor action, click on the process diagram and view the structure window. In the structure window, scroll down to sensor actions, and select Create – BAM Sensor. Give the sensor action a name: SensorActionRecieveInput. In the BAM Sensor Action create window, select the “sensor” – InstanceStart. Select the data object lookup button (torch button) and in the “BAM data object chooser” select the data object “/StudentLab/BPELOrderBookingTimeStamp” and click OK.



The “Enable Batching” check box, enables batched flush of data from BPEL to BAM. The batch size can be set by the user, (default is 50ms). Use this option as required. In this example, it is recommended not to check this box. IMPORTANT: the variable selected for the sensor framework should be the higher level node (example = $inputVariable), it cannot be the final attribute value (example = OrderPrice)

Click OK to select the data object that you wish to populate. This data object contains the time stamps of various activities, and we will populate the receiveInput_TS data field. In the sensor action definition, “uncheck” the enable-batch operation (since we want this in real time). Select “insert” operation (since this is a new insert into the data object), and give the XSLT translation a clear name (file name only – receiveInput.xsl, do not change directory), and press “create mapping”, as shown in the figure below. In the XSLT mapping window, map the attributes as shown below. Right click on both the sides and expand all nodes in the schema. Drag and drop instanceId from left schema to right side. Similarly map the timestamp to receiveInput_TS. Note: the above operation defines / manages the different events “co-relation” to the same data object, and completes the definition (data population) of the data object. In this case it explains how the BPEL process sends the instance start time to the ADC object.



Close the XSLT mapping (by clicking on Save & X mark on the horizontal tab marker).



Last Sensor: (process end)

Next we create the sensor that marks the end of the process. Double click on callbackClient, and click on sensors tab. Give this a name – “InstanceComplete”. Click on create (or edit if sensor exists), and add an data variable for this sensor. Click on create (or edit if sensor data exists), and select inputVariable, and select evaluation time –Completion. Close these dialog boxes by clicking OK.



Next define the Sensor Action for the callbackClient sensor. Click on the process diagram and view the structure window. In the structure window, scroll down to sensor actions, and select Create – BAM Sensor. Select the sensor – “InstanceCompletion”. In the BAM Sensor Action create window, give this sensor action a clear name – SensorActionCompleteInstance. Select the data object lookup button (torch button) and in the “BAM data object chooser” select the data object “/StudentLab/BPELOrderBookingTimeStamp” and click OK. Note that in this action, we do correlation to the InstanceId of the process and populate only the end time (update only – not insert new). This is correlation of two events about same instance – arriving at different points of time – and populating the same “row” in the data object.

Click OK to select the data object that you wish to populate. This data object contains the time stamps of various activities, and we will populate the callbackClient_TS data field. In the sensor action definition, “uncheck” the enable-batch operation (since we want this in real time), select “Update” on operation, and give the XSLT translation a clear name



(file name only – callbackClient.xsl, do not change directory, and press “create mapping”, as shown in the figure below. Note that this is “update” ONLY operation. In the XSLT mapping window, map the attributes as shown below. Right click on both the sides and expand all nodes in the schema. Drag and drop instanceId from left schema to right side. Similarly map the timestamp to callbackClient _TS. Note: the above operation defines / manages the different events “co-relation” to the same data object, and completes the definition (data population) of the data object. In this case it explains how the BPEL process sends the instance end time to the ADC object. Close the XSLT mapping (by clicking on Save & X mark on the horizontal tab marker).



Populating Other Activity TimeStamps:

Follow the steps give above and create a BAM sensor action for updating (not insert) the timestamp fields of BPELOrderBookingTimeStamp dataobject from different activity sensor actions. Alternately, you can use a xsl:if condition statement in the mapping logic and use a single XSLT translation file to populate all the ADC data object fields. An example of such translation is given below (source code is given at end of this document).

Populating the OrderBooking Data Object

This section gives the steps to create a BAM sensor action for inserting (not update) the new row in BPELOrderBookingDataObject dataobject with values from a completed activity. The data is populated from the attributes of the process at the callbackClient activity. Click on the process diagram and view the structure window. In the structure window, scroll down to sensor actions, and select Create – BAM Sensor. Select the sensor – “InstanceCompletion”. In the BAM Sensor Action create window, give this sensor action a clear name – InstanceCompletionData. Select sensor as “InstanceCompletion”. Select the data object lookup button (torch button) and in the “BAM data object chooser” select the data object “/StudentLab/BPELOrderBookingDataObject” and click OK. Choose the operation “Insert” (this is not update) to insert a new row in the BAM data object. Define the mapping file for mapping BPEL process attributes to BAM ADC data object fields. Click on “create mapping” button.



In the xslt translation design window, map the process attributes to the BAM ADC object fields as shown below .

BPEL Process

Attributes

BAM ADC data

object fields.

InstanceId InstanceId ProcessName ProcessName ProcessName updaterName SupplierName SupplierName



SupplierPrice SupplierPrice OrderPrice OrderPrice OrderStatus OrderStatus Timestamp OrderDateTime Mathematical Expression – Minus (OrderPrice-SupplierPrice)

Profit

The mapping XSLT design is shown below. Save this design (click on save all icon) and close this window (with the X mark in the top corner).

This completes the design steps for mapping all the sensors to the BAM sensor actions, and defining the BAM ADC data object mappings. The BPEL process is ready for compilation and deployment to the BPEL server. Compile and deploy the process to the BPEL server.



Verification steps:

Stop the BAM enterprise link server and BAM plan monitor server components ONLY. This ensures that the BPEL server can only communicate directly with the BAM server using web service definitions. (not jms bus or plans or monitoring logic). Using the BPEL process test console, initiate an instance of the OrderBooking process with sample data. Complete the process flow logic for OrderBooking tutorial, following all the required steps. (SelectManufacturing, OrderApproval etc). Open the BAM console, Architect window and browse the data objects. Observe that the BPEL process instance details are populated in the BAM ADC. Match these values to the process attributes in the BPEL console.



Verifying BAM ADC WebService inspection wsil:

URL - http://ssondur-lap/OracleBAM/inspection.wsil

Verification Of BAM web service operations wsdl:

URL-http://localhost/OracleBAM/Services/DataObject/DataObjectOperations.asmx?wsdl

Source Code for XSLT file:

Source Code for Single XSLT translation file using xsl:if condition to populate all the timing logic fields from BPEL process sensors. Design

Source Code:

<?xml version="1.0" encoding="UTF-8" ?>

<?oracle-xsl-mapper



<mapSources>

<source type="XSD">

<schema location="../SensorActionSensorAction_1.xsd"/>

<rootElement name="actionData" namespace="http://xmlns.oracle.com/bpel/sensor"/>

</source>

</mapSources>

<mapTargets>

<target type="WSDL">



</xsl:if>

<xsl:if test="contains(/tns:actionData/tns:header/tns:sensor/@sensorName,'UserReviewStart')">

<_invokePOA_TS>


</_invokePOA_TS>

</xsl:if>

<xsl:if test="contains(/tns:actionData/tns:header/tns:sensor/@sensorName,'UserReviewComplete')">

<_receivePOA_TS>


</_receivePOA_TS>

</xsl:if>

<xsl:if test="contains(/tns:actionData/tns:header/tns:sensor/@sensorName,'InstanceCompletion')">

<_callbackClient_TS>


</_callbackClient_TS>

</xsl:if>

</_BPELOrderBookingTimestamp>

</_BPELOrderBookingTimestampCollection>

</xsl:template>

</xsl:stylesheet>

[Note – the above source for XSD depends on BPEL version. Verify and use the

source XSD generated by BPEL automatically during BPEL sensor definitio]

Summary:

1. Understand Oracle BPEL process design, process activities and sensor definition for BAM sensor actions.

2. Configure and connect Jdev BPEL designer to BAM server connection. 3. Define BPEL-BAM sensor action to populate BAM ADC data objects, including

insert/ update operation, mapping BPEL attributes to BAM ADC data object fields using XSLT translation.

4. Complete project of this tech note is given in BAMOrderBooking example.

For better performance:

It is recommended to use ‘batch parameters’ and ‘upsert’ operation with unique key for better performance on the BPEL server. The batch parameter can be left default. For details – see BPEL documentation on BAM sensors. This configuraiton is shown in the figure below. Do not use VMWare images or Window XP platform for any high level loads or performance and scalability testing.



Questions & Clarifications:

If you have any comments or need additional information, please communicate through the Oracle BAM forum at: http://forums.oracle.com/forums/forum.jspa?forumID=252

SOA BPEL Sensors for Bam

Documents

Transcript of SOA BPEL Sensors for Bam