Using Flex Fields in Oracle BPM 11g

While designing BPM Processes we might have a need to create Human Workflows. If we use the OOTB support to Auto Generate Task UI’s we get the standard Inbox view that in turn have standard data columns.

There may be a need to create a similar inbox like view but some additional task display columns may be required (preferably from the Task payload) to prioritize tasks in the inbox. The support of Flex fields can easily help us achieve this.

Human workflow flex fields store and query use case-specific custom attributes. These custom attributes typically come from the task payload values. Storing custom attributes in flex fields provides the following benefits:

• They can be displayed as a column in the task listing
• They can filter tasks in custom views and advanced searches
• They can be used for a keyword-based search

The demonstration below will show a simple CardApproval business process and how Flex Fields is used in it.

Prerequisites

• Oracle JDeveloper 11gR2 and above
• Oracle SOA Suite and Oracle BPM Suite Domain with running managed servers

The Process

We have a very basic Business Process for Credit Card Approval similar to the one below



The process has starts with a MessageStart event thats is based on the below CreditInformation .xsd

<xsd:schema xmlns:xsd="<a href="http://www.w3.org/2001/XMLSchema"
xmlns="http://www.beatechnologies.wordpress.com/card"
targetNamespace="http://www.beatechnologies.wordpress.com/card" elementFormDefault="qualified">
<xsd:element name="CreditInformation">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="cardNumber" type="xsd:string"/>
<xsd:element name="holderSsn" type="xsd:string"/>
<xsd:element name="holderFirstName" type="xsd:string"/>
<xsd:element name="holderLastName" type="xsd:string"/>
<xsd:element name="brand" type="xsd:string"/>
<xsd:element name="creditLimitRequested" type="xsd:double"/>
<xsd:element name="creditLimitGranted" type="xsd:double"/>
<xsd:element name="latePaymentCount" type="xsd:int"/>
<xsd:element name="creditScoringResult" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>

The Approve or Reject Card Application Human task is also based on the same input data type. Additionally also create a string input to the task as shown under.



Now the next part is to assign a value from the original payload to the creditLimitRequested variable of the Task Input form.



You can now create an Auto Generated Task Form from the ApproveCard.task file. The complete JDeveloper process used for this demo can be downloaded from here.



Deploy the completed Process and the UI to a running soa server.

The process being deployed now we can now create Flex Fields for the Task UI.

Open in a browser the BPM Workspace and login as an admin user.

http://host:port/bpm/workspace/faces/jsf/worklist/worklist.jspx

Once the Custom Inbox open go to the top right and click on the Adminstrator link. Click on the Public Flex Fields link under Flex Fields heading.



Once on the Public Flex Fields screen click on the green Add icon to create a new Label.

We can choose any predefined attribute type for creating a Label. Create a label called Limit Requested as under.



The second step will be to map this Label with the simple variable coming as part of the input to the Task form. For this check the “Edit Mappings by task type” radio button and follow the screen shot below.



Now the field created as a label is associated with the input variable customerCreditLimit of the Task form. This will now hold the value of credit limit requested for the credit card.

We can now create a custom view so that we can also see the column for the Limit Requested column in the inbox. For the same view we will also sort the tasks based on the limit amount so that the users can prioritize it.

Go to the Worklist Views heading and click on the green Add icon to create a custom Inbox/View.

Create a view called ‘Priority Approvals’.



Now click on the Display Tab to select the Limit Requested label as a column in the Task view. Also sort the tasks by the same field in a descending order.



Well that is pretty much it. Now you can test the Process as well as the Custom View by initiating the process with a simple request. Go to the EM console and locate the CardApproval composite. Test the composite from the EM console with some values.



Click on Test Web Service to test this. The Business Rules component allows automatic approval for Credit Limit Requests for VISA cards upto 20,000. The ones above it are sent for Manual Approval. So this request lands up in the user inbox.

You can now click on the ‘Priority Approvals’ view to see the custom Flex field added an column in the Task view.



You can find the BPM Process and UI Application at this location here.

Triggering an OSB Message Flow with Email

Often in our business processes/integrations we might have a situation where in we would need to trigger our message flow/process with an Email.

With OSB’s Email transport listening to a mailbox and triggering a message flow is very simple and comes out of the box.

The following article will explain as a tutorial how can this be achieved.

Prerequisites

The prerequisites for this tutorial are as under :

1. Oracle Service Bus 11g (Link)
2. Apache James Server (Link) that can act as a Mail server.

Getting Started

Setting Up Apache James

The first thing to get started would be to download the Apache James binary from here. Apache James would act as the email server through which we can send/receive emails.

Copy the James binary at any location on your computer. The binaries would come with a bin folder. Navigate to the bin folder to locate the run.bat file.

Apache James need JDK 1.5 and above so make sure JAVA_HOME is added with the JDK directory in the list of environment variables before running James.

Open a command prompt and run the run.bat file.

We can now see that Apache James server is up and running. Pretty simple.



Next we can verify by doing a telnet to the James Management port i.e. 4555. Login to James using the default Login Id and Password.

Login Id: root
Password: root

We can add user inboxes by the following command

adduser <username> <password>

After you add users the next thing you can do to verify this is use the command listusers that  will give you all users in the server.



Having done this we are good with the email server part. By default James runs both the SMTP server to send mail and a POP3 server that can be used to retrieve mails.

Creating the OSB Message Flow

The next thing would be to create a Message flow in OSB that can be triggered with the Email event.

Make sure that Oracle Service Bus domain is created and a server is up and running.

Open http:host:port/sbconsole and login with the username and password configured for the OSB domain.

The first step would be to create a SMTP server configuration. This is required as we would create a dummy Business Service to post a message to the configured inbox.

Once you have logged in to the OSB console go to System Administration –> SMTP Servers –> Add and create a SMTP server as under



Click on Save to save the configuration.

Now go to project explorer and create a project and name it EmailSub. Create an XML Schema resource from the Create Resource Icon based on the following XSD.

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified"
attributeFormDefault="unqualified" targetNamespace="http://www.beatechnologies.com/xsd/salesapp"
xmlns:sales="http://www.beatechnologies.com/xsd/salesapp">
<xsd:complexType name="ContentType">
<xsd:sequence>
<xsd:element name="MimeType" type="xsd:string" default="text/plain" minOccurs="0"/>
<xsd:element name="ContentBody" type="sales:OrderIndicatorType"/>
<xsd:element name="ContentEncoding" type="xsd:string" nillable="true"/>
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="EmailPayloadType">
<xsd:sequence>
<xsd:element name="FromAccountName" type="xsd:string" minOccurs="0"/>
<xsd:element name="To" type="xsd:string" minOccurs="0"/>
<xsd:element name="ReplyToAddress" type="xsd:string" minOccurs="0"/>
<xsd:element name="Subject" type="xsd:string"/>
<xsd:element name="Content" type="sales:ContentType"/>
<xsd:element name="Cc" type="xsd:string" minOccurs="0"/>
<xsd:element name="Bcc" type="xsd:string" minOccurs="0"/>
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="OrderIndicatorType">
<xsd:sequence>
<xsd:element name="OrderID" type="xsd:string" minOccurs="0"/>
<xsd:element name="OrderAmount" type="xsd:string" minOccurs="0"/>
<xsd:element name="CustomerID" type="xsd:string" minOccurs="0"/>
<xsd:element name="QuoteID" type="xsd:string"/>
<xsd:element name="BusinessUnitID" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
<xsd:element name="EmailPayload" type="sales:EmailPayloadType"/>
</xsd:schema>

Create a Business Service based on Messaging Service Type called SendEmailBS



Configure rest of the service as under



Save the service and activate the session. Test the business service that we just created. Also configure an email client to see whether you get this email.

Here is a test payload

<sal:EmailPayload xmlns:sal="http://www.beatechnologies.com/xsd/salesapp">
<sal:Content>
<sal:ContentBody>
<sal:OrderID>2003138758424</sal:OrderID>
<sal:OrderAmount>452617</sal:OrderAmount>
<sal:CustomerID>2000001120268</sal:CustomerID>
<sal:QuoteID>2002795866809</sal:QuoteID>
<sal:BusinessUnitID>4747</sal:BusinessUnitID>
</sal:ContentBody>
</sal:Content>
</sal:EmailPayload>
<pre>

Off course this is a very basic way of testing. You can also go on and create a front ending proxy service to pass the content payload, subject and other email headers dynamically.



For the second part we need to configure a Proxy Service that can poll this mail box and instantiate its message flow whenever an email arrives.

The first step for this would be to configure a Service Account of Type ‘Static’ that will basically have the user name and password for the mail box.



We would need to attach this Service Account while configuring the Proxy Service required to poll this mail box.

Next create a Messaging type Proxy Service based on the same Email.xsd as under





Lastly go and edit the Proxy Service Message Flow. Add a Pipeline Pair and in the Request Pipeline add a Stage.

Add some simple action to extract the payload from the body variable and log the body to validate whether we receive an email.



Well we are now almost done.

Use the dummy Business Service that we created and push one more message to the user Inbox. This time you will notice that the Proxy Service picks up the message and logs it to the server log.

Open the domain AdminServer.log file to see the message getting logged.



That is pretty much it. Now you can create your own message flow that can be executed with the trigger of an Email.

Lightweight introduction to Oracle SOA Suite 11g : Part II

Coming to Fault Handling Oracle SOA Suite allows fault handling based on policies

• Using Fault Policies
• Using Fault Bindings

Catch and throw faults at the process level. Handle different types of faults if you have to.

Add the fault bindings and fault policies file in the same directory where the composite.xml is.



Here is a sample custom example Fault Policies

<faultPolicies xmlns="http://schemas.oracle.com/bpel/faultpolicy">
<faultPolicy version="2.0.1" id="SalesCompositeFaultPolicy" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns="http://schemas.oracle.com/bpel/faultpolicy" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Conditions>
<faultName xmlns:bpelx="http://schemas.oracle.com/bpel/extension" name="bpelx:remoteFault">
<condition>
<test>$fault.code/code="WSDLReadingError"</test>
<action ref="ora-rethrow-fault"/>
</condition>
<condition>
<action ref="ora-retry"/>
</condition>
</faultName>
<faultName xmlns:bpelx="http://schemas.oracle.com/bpel/extension" name="bpelx:bindingFault">
<condition>
<action ref="ora-rethrow-fault"/>
</condition>
</faultName>
<faultName xmlns:medns="http://schemas.oracle.com/mediator/faults" name="medns:mediatorFault">
<condition>
<action ref="ora-rethrow-fault"/>
</condition>
</faultName>
<faultName xmlns:bpelx="http://schemas.oracle.com/bpel/extension" name="bpelx:runtimeFault">
<condition>
<action ref="ora-human-intervention"/>
</condition>
</faultName>
</Conditions>
<Actions>
<!-- This is an action will mark the work item to be "pending recovery from console"-->
<Action id="ora-human-intervention">
<humanIntervention/>
</Action>
<!--This is an action will bubble up the fault-->
<Action id="ora-rethrow-fault">
<rethrowFault/>
</Action>
<!--This action will attempt 5 retries with intervals of 4 seconds retry after 120, 240, 360 seconds -->
<Action id="ora-retry">
<retry>
<retryCount>3</retryCount>
<retryInterval>5</retryInterval>
<retryFailureAction ref="ora-human-intervention"/>
</retry>
</Action>
<!--This action will cause the instance to terminate-->
<Action id="ora-terminate">
<abort/>
</Action>
</Actions>
</faultPolicy>
</faultPolicies>

And Fault Bindings

<faultPolicyBindings version="2.0.1" xmlns="http://schemas.oracle.com/bpel/faultpolicy" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<composite faultPolicy="SalesCompositeFaultPolicy"/>
</faultPolicyBindings>

And finally add these lines as properties inside the composite.xml



We can also create DVMs (Domain Value Maps) used to lookup cross system data that can be edited at runtime using the SOA composer UI just like we can edit Business Rules



We can also use the OOTB User Messaging Serviceto configure notification channels such as

• Email
• Voice Mail
• IM
• SMS

 

Setup user inbox to receive the notification emails.




This is pretty much it for now. Hope this gives an overview of what we can try and do with Oracle SOA Suite 11g.