Use Entity Varaiable and FlowN in BPEL Process – SOA 11g

In this post, I am going to show how to use Entity variables and FlowN in BPEL Process. The entity variable that I am creating here is based on SDO’s of Employees table of hr schema.

Pre-requisite: Setup EmpDeptService as described on my earlier blog post.

Entity Variable: An entity variable is a type of variable created in BPEL process where you can directly attach it with the underlying data provider service. For eg, in earlier versions, when you want to get an employee record from employees table, you can directly use a DB adapter. Or you can define a service to do the CRUD operation and return XML as appropriate DOM. Where as, with entity variable, you can directly connect the variable to the data provider service through SDOs.

FlowN: FlowN is an activity in BPEL process that is used to execute flows in parallel. Eg, when you have list of employees to process in BPEL, instead of processing them one-by-one, using a FlowN activity, you can process all the employees in parallel.

Use case for this post: A list of employee id and employee salary is given as input to BPEL Process. The BPEL fetches the data of those employees using the Employee SDO created in earlier ADF BC Service using entity variables and update those employees salary in the data base using that ADF BC Service. This update would happen for all employees in parallel.

Complete project: http://kavin-sample-apps.googlecode.com/files/EntityVariablePlusFlowNInBPEL.rar

Description:

The composite exposes a service EntityVaraiableProcessService_ep, has a BPEL process and a reference to EmpDeptService. EntityVaraiableProcessService_ep has “oracle/wss_saml_or_username_token_service_policy” security policy attached with it and EmpDeptService reference has oracle/wss10_saml_token_client_policy security policy attached with it.

BPEL Process takes list of employees message as input. It has employeeId and employeeSalary.

<?xml version="1.0" encoding="windows-1252" ?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:ns1="http://go2kavinkumar.com/soa/sample/EntityVariableInBPEL/EmployeeUpdateProcessMessage"
targetNamespace="http://go2kavinkumar.com/soa/sample/EntityVariableInBPEL/EmployeeUpdateProcessMessage"
elementFormDefault="qualified">
<xsd:element name="EmployeeDetails">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="employees" maxOccurs="unbounded">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="employeeID" type="xsd:string"/>
<xsd:element name="employeeSalary" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>

In BPEL Process, add a FlowN Activity from Oracle Extensions section of Component Palette. Name this as IterateEmployeesFlowN. This activity is basically used to iterate through the list of employees sent to the BPEL Process.

Using expression builder, select the count of employees coming in the incoming message/payload and the counter variable.

‘

Now the variable “IterateEmployeesFlowN_Variable” keeps track of the counter. Now add a scope in this flowN in which we will code the business process. Let’s call this scope “EntityVariableUsageScope”.

Now create a variable in BPEL Process. To make this entity variable, choose element type and browse through Partner links -> EmpDeptService -> Inline Schemas -> employeesVOSDO. Select the entity variable check box and bind it to the EmpDeptService partner link to bind it with underlying data provider service which owns this SDO. This makes this element variable as an entity variable.

NOTE: When you are using an entity variable in FlowN, always make sure you create the entity variable inside the scope which is inside FlowN. Inside the FlowN scope, DO NOT use the entity variable which is defined outside the scope of FlowN.

Now we must bind the incoming employeeId to the data provider service so that this variable is bound to that particular employee record. To do that, drag and drop a BindEntity activity inside the scope. Also we need to update the salary of this employee to the incoming employeeSalary payload value. Hence drag and drop an Assign activity following BindEntity activity. NOTE that both these must be inside EntityVariableUsageScope scope.

Now let’s map the incoming employeId to the Entity variable using BindEntity activity. Edit the Bind Entity activity. First Browse and select the entity variable to be used for this Bind Entity activity.

Next click on (+) icon next to Unique Keys to select the primary key of this entity variable and pass the primary key value, employeeId in our case, so that this variable is bound to that employee record using the SDO service.

Now browse and select the Key Local Part -> This would be the primary key attribute name that you must be selecting from the entity variable. Once you select this, the value for Key Namespace URI would get defaulted. Now from the incoming payload that has employeeId, select the employeeId for Key Value. If the incoming payload is directly having the id of only one employee, then you can directly map the id here. But in our case, the incoming payload carries a list of employee ids and hence we must select employee id of appropriate index/counter that is getting processed in the FlowN. So you can specify this value like,

bpws:getVariableData(‘inputVariable’,’payload’,’/ns4:EmployeeDetails/ns4:employees[$IterateEmployeesFlowN_Variable]/ns4:employeeID’)

[$IterateEmployeesFlowN_Variable] -> This is the counter variable of FlowN which says take the employee id of say 3rd employee in the incoming list. That’s how each and every employee from the incoming list would be processed using the FlowN index variable at runtime.

So that completes the configuration for BindEntity. This binds the entity variable in BPEL process to the underlying DB data through SDO Service.

Now any changes made on this variable would get automatically updated in DB. In our case, we need to update the salary of this employee with the incoming salary. Hence update the assign activity. Using expression builder, map the incoming Salary payload value to the salary attribute of entity variable.

NOTE that the salary value from the incoming payload should be used as below with appropriate FlowN index variable.

bpws:getVariableData(‘inputVariable’,’payload’,’/ns4:EmployeeDetails/ns4:employees[$IterateEmployeesFlowN_Variable]/ns4:employeeSalary’)

Reason is same as what I described for EmployeeId. Now right click and deploy the composite to SOA server.

Test your work:

select * from employees where employee_id in (100,101);

Launch soa-infra URL and access EntityVaraiableProcessService_ep service. Enter weblogic/weblogic1 in WS-Security section. Enter employeeId and employeeSalary for 1 pair as 100 and 98000. Add one more employee using (+) icon and enter employeeId and employeeSalary as 101 and 78000. Basically we expect to update the salaries of employees with id 100 and 101. Click Invoke button.

Now run the same SQL query again and make sure this data is updated in DB.

select * from employees where employee_id in (100,101);

Check instance on EM:

Now access this composite instance through EM. On the flow trace, make sure the BPEL Process has reached Completed state. On drilling further down into BPEL, you can see that two employes are processed in two parallel branches.

You can re-execute similar test case with 1 and 3 different employees and see how it appears on flow trace and BPEL flow details.

Insights:

1) When you want to see more logs related to entity variables, you can enable the logger oracle.soa.bpel.entity level to TRACE:32 from EM.

2) When you use BindEntity activity, Entity variable internally uses findXXX operation of the SDO service. Example, in below case, it binds to employee id 100.

<ns2:findEmployeesVO1 xmlns:ns2="http://go2kavinkumar.com/adf/sample/model/applicationModule/common/types/" xmlns:ns1="/kavin/adf/sample/model/view/common/" xmlns:ns0="http://xmlns.oracle.com/adf/svc/types/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<ns2:findCriteria xmlns:tns="http://xmlns.oracle.com/adf/svc/errors/">
<ns0:fetchStart>0</ns0:fetchStart>
<ns0:fetchSize>-1</ns0:fetchSize>
<ns0:filter>
<ns0:group>
<ns0:conjunction>And</ns0:conjunction>
<ns0:upperCaseCompare>false</ns0:upperCaseCompare>
<ns0:item>
<ns0:upperCaseCompare>false</ns0:upperCaseCompare>
<ns0:attribute>EmployeeId</ns0:attribute>
<ns0:operator>=</ns0:operator>
<ns0:value>100</ns0:value>
</ns0:item>
</ns0:group>
</ns0:filter>
<ns0:excludeAttribute>false</ns0:excludeAttribute>
</ns2:findCriteria>
<ns2:findControl xmlns:tns="http://xmlns.oracle.com/adf/svc/errors/">
<ns0:retrieveAllTranslations>false</ns0:retrieveAllTranslations>
</ns2:findControl>
</ns2:findEmployeesVO1>

3) When updates happens through Assign activity, entity variable internally uses processCSXXX Operation of SDO Service. Example, below updates salary of employeeId 100 from 200 to 2000.

<ns2:processCSEmployeesVO1 xmlns:ns2="http://go2kavinkumar.com/adf/sample/model/applicationModule/common/types/" xmlns:ns1="/kavin/adf/sample/model/view/common/" xmlns:ns0="http://xmlns.oracle.com/adf/svc/types/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<ns2:processData xmlns:tns="http://xmlns.oracle.com/adf/svc/errors/">
<ns0:Value xsi:type="ns1:EmployeesVOSDO">
<ns1:EmployeeId>100</ns1:EmployeeId>
<ns1:FirstName>Steven</ns1:FirstName>
<ns1:LastName>King</ns1:LastName>
<ns1:Email>SKING</ns1:Email>
<ns1:PhoneNumber>515.123.4567</ns1:PhoneNumber>
<ns1:HireDate>1987-06-16T18:30:00.0Z</ns1:HireDate>
<ns1:JobId>AD_PRES</ns1:JobId>
<ns1:Salary>2000</ns1:Salary>
<ns1:CommissionPct xsi:nil="true"/>
<ns1:ManagerId xsi:nil="true"/>
<ns1:DepartmentId>90</ns1:DepartmentId>
</ns0:Value>
<ns0:ChangeSummary xmlns:sdo="commonj.sdo">
<ns0:Value sdo:ref="#/ns2:processCSEmployeesVO1/ns2:processData/ns0:Value[1]">
<ns1:Salary>200</ns1:Salary>
</ns0:Value>
</ns0:ChangeSummary>
</ns2:processData>
<ns2:processControl xmlns:tns="http://xmlns.oracle.com/adf/svc/errors/">
<ns0:partialFailureAllowed>false</ns0:partialFailureAllowed>
</ns2:processControl>
</ns2:processCSEmployeesVO1>

Follow up:

In my next post, I will talk about how to create and remove data using entity variables in BPEL Process. Feel free to comment your feedback.

Keep Smiling and Thanks for Reading 🙂

Kavin.