Tuesday, April 30, 2013

Working with BPEL Faults

Today I will show you one of the most important concept in any software developed using any programming language i.e "Handling Faults".Like in every other language there are number of mechanisms to handle exceptions that may arise while invoking certain piece of code. In BPEL as well there is a meachanism for handling faults.These faults should be handled and required actions should be taken in event of failure at any stage.There are two categories of BPEL faults:
  • Business Faults
  • Runtime Faults

Business faults are application-specific faults that are generated when there is a problem with the information being processed (for example, when a social security number is not found in the database). A business fault occurs when an application executes a throw activity or when an invoke activity receives a fault as a response. The fault name of a business fault is specified by the BPEL process service component.A business fault can be caught with a faultHandler using the faultName and a faultVariable.

<catch faultName="ns2:BusinessFault" faultVariable="BusinessFaultVar">

Runtime faults are the result of problems within the running of the BPEL process service component or web service (for example, data cannot be copied properly because the variable name is incorrect). These faults are not user-defined, and are thrown by the system. They are generated if the process tries to use a value incorrectly, a logic error occurs (such as an endless loop), a Simple Object Access Protocol (SOAP) fault occurs in a SOAP call, an exception is thrown by the server, and so on.

Several runtime faults are automatically provided. These faults are included in the http://schemas.oracle.com/bpel/extension namespace. These faults are associated with the messageType RuntimeFaultMessage. The WSDL file shown below defines the messageType:

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

  <message name="RuntimeFaultMessage">
   <part name="code" type="xsd:string" />
   <part name="summary" type="xsd:string" />
   <part name="detail" type="xsd:string" />

If a faultVariable (of messageType RuntimeFaultMessage) is used when catching the fault, the fault code can be queried from the faultVariable, along with the fault summary and detail.

A bindingFault is thrown inside an activity if the preparation of the invocation fails. For example, the WSDL of the process fails to load. A bindingFault is not retryable. This type of fault usually must be fixed by human intervention.


A remoteFault is also thrown inside an activity. It is thrown because the invocation fails. For example, a SOAP fault is returned by the remote service.


A replayFault replays the activity inside a scope. At any point inside a scope, this fault is migrated up to the scope. The server then re-executes the scope from the beginning.

In this example I'll demonstrate how to handle different types of BPEL faults inside any BPEL process and take required actions.BPEL process will be created based on a schema and it will be exposed as web service.To showcase diferent types of faults we will be using primarily two activities such as Throw and Catch.

Throw Activity is used to generates a fault from inside the business process.
Catch Activity is used to catch specific faults indiviually such as business,runtime or binding fault.Catch All activity catches all the faults that are not being catch in other catch activities.

Kindly download below artifacts required for this tutorial:

RuntimeFault WSDL
BusinessFault WSDL
Employee Schema
Fault Schema

Lets start with the tutorial

1. Create a new SOA project with name "FaultHandling".Drag and drop BPEL process onto the components lane.Pop will open up, give BPEL process the name "FaultHandlingProcess" and in tmplate select "Base on a WSDL". 

2. Click the cog icon next to WSDL URL to generate WSDL from schema.Create WSDL pop will open up.
 3. In the input section, click on "+" icon to add message part.In the next window change the partname to paylaod and click the torch button.

4. Type chooser window will come up.Drill down to Employee.xsd  and select "EmployeeDetails" and click OK.

5. Click OK again.

6. BPEL process is configured based on WSDL.Click Finish.

7. Since we have chose the option to expose as web service.Our composite will look like this.

8.Double click and open up the BPEL process.Drag and drop switch activity after receive activity.

9. We will be using this switch activity to throw different faults explicitly.Add a switch case.

10. Under first switch case, add the condition to check for City name "Canada".

11. Similarly for the second switch case do it for "London".

12.Save all.Your BPEL process will look like this so far.

13. Drag and drop throw activity inside first switch case. In this activity we will be throwing Business Fault.

14. Open up your BusinessFault.wsdl and copy namesapce from there "http://xmlns.example.com/service/fault/businessfault".

15. Double click the throw activity and under namespace URI paste the copied namespace and give local name as "BusinessFault".What this activity does is it will throw a business fault and all the details of the fault such as faultcode, details and summary will be stored under "Fault Variable".

16. Create new variable "BusinessFaultVar" of message type as "Business Fault Message".

17. Inside throw activity browse for fault variable that we just created.Click OK.

18. Inside second switch case drag and drop one more throw activity.And for Fault QName click Browse.

19. Window that will pop up, you will see number of system faults that cane be there.Since we are throwing binding fault in this switch case.Select Binding Fault.

20. Like we did for business fault ,similarly create variable for binding fault as well.But this time it should be of "RunTimeFaultmessage" type.
Because binding fault is a part of runtime fault.Its details will be captured using this variable only.

21. Click OK.

22.In the otherwise case configure thorw activity to throw remote fault.

23. Now add 3 catch blocks for the main scope activity,by clicking the "Add Catch branch."

24. Similarly add one catch All activity.

25. Your process will look like this.As explained earlier, we will be using three catch activities to handle business,remote and binding faults indiviually and all other remaining fault that may come will be catch by CatchAll activity.

27. Double click first catch activity.Populate the fields like we did for throw activity.In the first catch we will be catching Binding Fault.

28. Similary catch remote and business fault in other two catch activities.

29. Now we will assign values to these variables that will be used inside catch activities.As we are explicitly throwing faults thats why we are populating these fault variables,otherwise in real case scenario thses will get automatically populated.Drag and drop three assign activiies under each throw activity.

30. In the first assign in case of Business Fault we will populate "BusinessFaultVar".

31. Same for Binding and remote fault.

32. Create a variable of FaultMessage type using FaultSchema.xsd.Now we will assing the fault details such as code, summary to this fault variable just to show how to fetch the fault details in case of any Fault.

33. Drag and drop assign activity under each catch and catchAll activity and map Fault details to the FaultMessage variable.

34. Now our composite will look like this.

35. Save all, compile and deploy it.Open EM and drill down to your SOA Composite.Click on Test Button.First we will check Binding Fault.So enter City name = "Canada" rest other any random details.Test WebService.

37. Open up the flow trace.You will see binding fault being thrown and it is being caught in Catch Binding Fault block.

38. Similarly like this test Business and remote fault as well.

So, in this way you handle faults in any BPEL process. Please note in real case scenarios you dont have to explicitly use throw activity to throw faults such as binding or remote fault.Only use throw activity whenever you want to raise Business exception such as invalid credit card no or negative balance for instance.Binding or remote or any other fault that may raise during execution of code can be catch using catch activity and remaining using CatchAll activity.

Hope you guys enjoyed it.....Any doubt please feel free to ask me.Ill be more than happy to help you.
Stay tuned in for my next blog.

Happy Learning,

Sunday, April 28, 2013

Understanding Service Oriented Architecture(SOA)

Service-oriented architecture (SOA) is a software design methodology based on structured collections of discrete software modules, known as services, that collectively provide the complete functionality of a large or complex software application.

SOA defines how to integrate widely disparate applications for a Web-based environment and uses multiple implementation platforms. Rather than defining an API, SOA defines the interface in terms of protocols and functionality. An endpoint is the entry point for such a SOA implementation. XML is often used for interfacing with SOA services.

Oracle SOA Suite 

Oracle SOA Suite is a comprehensive, hot-pluggable software suite to build, deploy and manage Service-Oriented Architectures (SOA). The components of the suite benefit from common capabilities including consistent tooling, a single deployment and management model, end-to-end security and unified metadata management. Oracle SOA Suite enables system developers to set up and manage services and to orchestrate them into composite applications and business processes.


The products contained in this suite are listed below:

BPEL Process Manager: BPEL is the standard for assembling a set of discrete services into an end-to-end process flow, radically reducing the cost and complexity of process integration initiatives. Oracle BPEL Process Manager offers a comprehensive and easy-to-use infrastructure for creating, deploying and managing BPEL business processes. 

Business Rules: Oracle Business Rules is a high performance lightweight business rules product that addresses the requirements for agility, business control, and transparency. It is part of the Fusion Middleware stack and integrates seamlessly across the entire Oracle SOA Suite and BPM Suite stack. It is also a core component for present and future Oracle Fusion Middleware and Fusion Applications products.

Oracle Service Bus: Oracle Service Bus transforms complex architectures into agile integration networks by connecting, mediating, and managing interactions between services and applications. Oracle Service Bus delivers low-cost, standards-based integration for mission critical SOA environments where extreme performance and scalability are requirements.

Oracle Web Service Manager: Oracle Web Services Manager offers a comprehensive and easy-to-use solution for policy management and security of service infrastructure. It provides visibility and control of the policies through a centralized administration interface offered by Oracle Enterprise Manager.

Human Workflow: Human Workflow component is responsible for managing the lifecycle of human tasks, including creation, assignment, expiration, deadlines, and notifications, as well as its presentation to end users. It supports sophisticated dynamic task routing leveraging declarative patterns and tight integration with business rules. The three main sub-components of Human Workflow are a Task editor, Task Service Engine, and a Worklist application.

Oracle BAM: Oracle Business Activity Monitoring (Oracle BAM) gives business executives the ability to monitor their business services and processes in the enterprise, to correlate KPIs down to the actual business process themselves, and most important, to change business processes quickly or to take corrective action if the business environment changes.

Useful Links...

Below are some links that might be helpful to you:

Tuesday, April 16, 2013

Working With FILE Adapter

Hi Everyone,

In today's post Ill show you  how to use the Oracle File Adapter, which work with Oracle BPEL Process Manager and Oracle Mediator.File adapter is basically used to read,write files locally on your server.
There are mainly 4 operations in FILE adpater namely:
  • READ: its an inboun operation that reads a file from given dir path
  • WRITE: outbound operation to write files to a location specified under directory path
  • SYNCHRONUS READ: outbound operation used to read a file in middle of the process
  • LIST FILE: outbound operation to list all the files in a given directory

In our usecase,we will be using read and write operations. We will create BPEL process that will poll for new files and after reading the files it will write them to differnet location. 2 file adpaters one inbound and one outbound and 1 BPEL process will be used for implementing this scenario.

STEPS to follow:

1. Create a new SOA project.Click new SOA project.I will be using same application for this usecase "SOALabs" as used in other tutorials.
 2. Give the project name as "FileAdapterLab" and click next.
3. Choose "Empty Composite" template and finish.
4.Drag and drop file adpater from component pallette to exposed services lane.
 5. File adapter configuration window will pop up.Click next.
6. Give the service name as "pollFile" and click next.
7. We will not be doing any transformation neither we our file that we read conforms to any schema, so leave adapter interface default and move next.
8. Since we are reading for new records in a file.Choose operation type as "Read" and click next.Other setting leave as it is.Their significance will be explained in coming posts.
9. Enter directory path from where file adapter will poll for new files.If you want to delete files after successful read, check "Deletd files after successful retreival".Also, provide the location for archiving the file as well and move next.
10. Now in this part we will provide the name of the files that we want to read. I have given as "test*.*" which means it will read all the files starting with test.Leave other settings default and click next.
11. In this window we define polling frequency which means after how many seconds or minutes our file adapter will poll for new files.Also, if you want your file adapter not to read all the files as they are written on the server, use the minimum file age option.Click next.
 12. We will be writing the file as it is read, so choose opaque schema option.
13.Click next and finish.
14. In the similar manner,drag and drop another file adapter this time to external references lane for writing file purposes.File configuration wizard will open up.
15. Give service name as "WriteFile" and click next.
16. Click next again and choose operation name as "Write File" and click next.
17. Specify the directory path where you want your files to be written and file naming convention to be used for files written.If you want that each record is being written to existing file only use "Append to existing File" option. Otherwise leave it default and click next.
18. Again opaque schema will be used and click finish.

19. Now drag and drop a BPEL process onto the components lane.
20. Choose BPEL process as define interface later and give "FileBPELProcess" name to your BPEL process.
21. Wire both the file adapters to the BPEL process created and save all.
22. Double click the BPEL process and open up BPEL designer.In the BPEL designer drag and drop one Receive activity and wire it to the "readFile" partner link.
23. Window will pop up for configuring receive activity.As done in JMS adpater tutorial check mark "Create Instance" and create input variable by clicking on "+" icon.
24. Leave the name for variable as default and click OK.
25. Recieve activty will look like this.Click finish.
26. Drag and drop invoke activity below receuive activity and wire it to the "WriteFile" partner link.
27. Invoke window will pop up.In the same manner like we did for receive activity create input variable for invoke activity.
28. Invoke activity will look like this click OK.
29. As of now BPEL process will look like this.
30. Drag and drop the assing activity between recieve and invoke activity.
31. Double click the assing activity and map receive activity input variable to invoke activity input variable means same contents are being copied to output.
32. SAVE ALL.Compile and deploy the SOA Composite. If you don't know how to deploy click HERE:
33.Now to test create one file at input dir that you gave while configuring "readFile" FILE adpater with name as test.
34.Open up your EM and drill down to your deployed composite.Keep refreshing and after sometime you will see one instance get created.

35. Click open the instance to see the flow trace of the invoked SOA composite.

36. Verify file is dleted from its source path and it is archived to the archive location.Also verify that a file is written at a path given while configuring "WriteFile" adaper with name as "test_file.txt"

Thats it guys.Today we learned how to configure and work with file adapters using read and write operation.stay tuned in for more tutorials.Till then take care

Happy Learning,
cheers !!!