Friday 29 August 2014
SOA-->Handling Rejected Messages - SOA 11G
Was busy past couple of months due to work and all. Finally got time to wrtie a new blog. Today, I would be explaining how do you handle rejection messages in BPEL. Rejection messages are basically the messages your composite receives but its not as per the format expected by your service , due to which BPEL instance do not get created. So your flow doesnot goes into your BPEL and there is no way to handle that exception in your code.
Below is the extract taken from Oracle:
The messages that error out before being posted to the service infrastructure are referred to asrejected messages. For example, the Oracle File Adapter selects a file having data in CSV format and tries to translate it to XML format (using NXSD). If there is any error in the translation, this message is rejected and are not be posted to the target composite.
Primarily, adapters and binding components are the generators of rejected messages.
To handle such scenarios where you need to take specific action if you get rejected messages, you can use fault management framework. Lets do it step by step.
To illustrate this, I have created sample interface that reads a CSV file from a location and there is only single receive activity inside the BPEL that will receive the input.
Based on the CSV file , I have created a sample schema and configured our File adapter to read the file based on this schema.
My composite is already deployed on EM. Lets test it. This is the file that I have placed in input directory.
Instance will be created , since the file is in correct format. Verify by opening the instance and checking your input.
Now create a Fault Policy file and fault bindings file and place it in the folder that has composite.xml.
Open the fault policy file and define a fault policy for the rejected messages in the
Now associate the fault policy with a service endpoint of the composite in
Deploy your composite and place some file in the input directory thats not as per the schema.
New instance wont get genereate. Instead you will see error message under "Faults and Rejected Messages". Click on the error message and open payload.
Now this failed message will be writtten to the file and the location that we gave in our fault policy. Go to that location and verify the same.
This way , we can handle rejection messages and take appropriate actions depending upon the requirements.
For more information please refer Oracle Documentation: Rejection Messages
Below is the extract taken from Oracle:
The messages that error out before being posted to the service infrastructure are referred to asrejected messages. For example, the Oracle File Adapter selects a file having data in CSV format and tries to translate it to XML format (using NXSD). If there is any error in the translation, this message is rejected and are not be posted to the target composite.
Primarily, adapters and binding components are the generators of rejected messages.
To handle such scenarios where you need to take specific action if you get rejected messages, you can use fault management framework. Lets do it step by step.
To illustrate this, I have created sample interface that reads a CSV file from a location and there is only single receive activity inside the BPEL that will receive the input.
Based on the CSV file , I have created a sample schema and configured our File adapter to read the file based on this schema.
My composite is already deployed on EM. Lets test it. This is the file that I have placed in input directory.
Instance will be created , since the file is in correct format. Verify by opening the instance and checking your input.
Now create a Fault Policy file and fault bindings file and place it in the folder that has composite.xml.
Open the fault policy file and define a fault policy for the rejected messages in the
fault-policies.xml file, stored with the composite.xml file in the JDeveloper project directory. In the file add the name of your service adapter in the faultname section. In our case it is "readFile". And the action define "writeTofile" that will write the rejected message in the location specified with the filename that is given.Now associate the fault policy with a service endpoint of the composite in
fault-bindings.xml, as is done in the following screenshot:Deploy your composite and place some file in the input directory thats not as per the schema.
New instance wont get genereate. Instead you will see error message under "Faults and Rejected Messages". Click on the error message and open payload.
Now this failed message will be writtten to the file and the location that we gave in our fault policy. Go to that location and verify the same.
This way , we can handle rejection messages and take appropriate actions depending upon the requirements.
For more information please refer Oracle Documentation: Rejection Messages
SOA-->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 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"
targetNamespace="http://schemas.oracle.com/bpel/extension"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns="http://schemas.xmlsoap.org/wsdl/">
<message name="RuntimeFaultMessage">
<part name="code" type="xsd:string" />
<part name="summary" type="xsd:string" />
<part name="detail" type="xsd:string" />
</message>
</definitions>
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.
bindingFault
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.
remoteFault
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.
replayFault
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.
- 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"
targetNamespace="http://schemas.oracle.com/bpel/extension"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns="http://schemas.xmlsoap.org/wsdl/">
<message name="RuntimeFaultMessage">
<part name="code" type="xsd:string" />
<part name="summary" type="xsd:string" />
<part name="detail" type="xsd:string" />
</message>
</definitions>
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.
bindingFault
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.
remoteFault
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.
replayFault
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.
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.
Subscribe to:
Posts (Atom)