Subbu: February 2014

Thursday, 6 February 2014

Oracle SOA Fault Management Framework

Oracle SOA Fault Management Framework :
http://ofmxperts.blogspot.in/2011/11/basics-of-fault-management-framework-in_23.html

http://docs.oracle.com/cd/E28280_01/dev.1111/e10224/bp_faults.htm

Handling Custom Faults in SOA 11g using fault policies

We will be using 2 BPEL processes here.
1) Fault BPEL - It will always throw a custom fault
2) Main BPEL - It will invoke the Fault BPEL and capture the custom fault using the fault policy.

FAULT BPEL PROCESS
=====================
1) Create a synchronous BPEL process with name FaultBPELProcess to throw business fault.
2) Customize the file FaultBPELProcess.xsd to add the fault message type.
COMPLEX TYPE
+++++++++++++
<element name="faultarea">
<complexType>
<sequence>
<element name="code" type="string"/>
                               <element name="summary" type="string"/>
                               <element name="details" type="string"/>
</sequence>
</complexType>
</element>
3) Customize the file FaultBPELProcess.wsdl to add the fault BusinessFault in the opertions and the fault message type.
a) <wsdl:message name="Fault">
       <wsdl:part name="payload" element="client:faultarea"/>
   </wsdl:message>
b) Under operations tag added
<wsdl:fault name="BusinessFault" message="client:Fault"/>

4) Now add Throw Activity with namespace 'http://xmlns.oracle.com/ErrorHandlingwoAIA/FaultBPEL/FaultBPELProcess' and LocalPart 'BusinessFault' and FaultVariable as 'FaultVar'.
5) Deploy the BPEL process to the application server.

MAIN BPEL PROCESS
==================

1) Create BPEL process with name MainBPELProcess to handle the fault thrown by FaultBPELProcess.
2) Customize file MainBPELProcess.xsd to add:
<element name="faultarea">
<complexType>
<sequence>
<element name="code" type="string"/>
                               <element name="summary" type="string"/>
                               <element name="details" type="string"/>
</sequence>
</complexType>
</element>
3) Customize file MainBPELProcess.wsdl to add:
a.     <wsdl:message name="Fault">
       <wsdl:part name="payload" element="client:faultarea"/>
   </wsdl:message>
4) Create a partnerlink and make a call to the FaultBPELProcess.
5) Add Invoke Activity to the Main Scope and do the following:
a. Point the invoke activity to the partnerlink used for calling FaultBPELProcess.
b. Create the input and output variables.
c. Click ok to save.
6) Add activity Assign before the invoke activity. Assign the input of the MainBPELProcess to the input variable used in the invoke activity.
7) To the Main Scope add the Catch Activity to catch the Business Fault. Add Reply Activity under the Catch to reply the calling party with the fault variable.
8) Change the composite.xml to add the following:
<property name="oracle.composite.faultPolicyFile">fault-policies.xml</property>
<property name="oracle.composite.faultBindingFile">fault-bindings.xml</property>
9) Deploy the BPEL process to the application server.

FAULT POLICY
============
1) Create fault-bindings.xml.
2) Add the following to it:
      <component faultPolicy="BusinessFault">
   <name>MainBPELProcess</name>
</component>
3) Create fault-policies.xml.
4) Add the following:
a. faultName, namespace - http://xmlns.oracle.com/ErrorHandlingwoAIA/FaultBPEL/FaultBPELProcess, the one thrown from the FaultBPELProcess.
b. name - BusinessFault, the local part of the throw activity in FaultBPELProcess.
c. Add the conditions and the actions in the fault policy.
5) Place both the files in MainBPELProcess folder.

================================================================
FAULT POLICY
+++++++++++++
<?xml version="1.0" encoding="UTF-8"?>
<faultPolicies xmlns="http://schemas.oracle.com/bpel/faultpolicy" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<faultPolicy version="3.0" id="BusinessFault"
                 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:bns="http://xmlns.oracle.com/ErrorHandlingwoAIA/FaultBPEL/FaultBPELProcess"
                 name="bns:BusinessFault">
        <condition>
          
          <action ref="ora-retry"/>
        </condition>
      </faultName>
    </Conditions>
    <Actions>
        
        <Action id="ora-retry">
            <retry>
                <retryCount>3</retryCount>
                <retryInterval>2</retryInterval>
                <exponentialBackoff/>
                <retryFailureAction ref="aia-ora-java"/>
                <retrySuccessAction ref="aia-ora-java"/>
            </retry>
        </Action>
        
        <Action id="aia-ora-retry">
        <retry>
            <retryCount>7</retryCount>
            <retryInterval>2</retryInterval>
            <exponentialBackoff/>
            <retryFailureAction ref="aia-ora-java"/>
            <retrySuccessAction ref="aia-ora-java"/>
        </retry>
        </Action>
        
        <Action id="ora-replay-scope">
               <replayScope/>
        </Action>
        
        <Action id="ora-rethrow-fault">
                <rethrowFault/>
        </Action>
        
        <Action id="ora-human-intervention">
                <humanIntervention/>
        </Action>
        
        <Action id="ora-terminate">
                <abort/>
        </Action>
        <Action id="aia-ora-java">
            <javaAction className="oracle.apps.aia.core.eh.CompositeJavaAction" defaultAction="ora-rethrow-fault">
            <returnValue value="REPLAY" ref="ora-terminate"/>
            <returnValue value="RETHROW" ref="ora-rethrow-fault"/>
            <returnValue value="ABORT" ref="ora-terminate"/>
            <returnValue value="RETRY" ref="aia-ora-retry"/>
            <returnValue value="MANUAL" ref="ora-human-intervention"/>
        </javaAction>
        </Action>
        <Action id="aia-no-action">
            <javaAction className="oracle.apps.aia.core.eh.CompositeJavaNoAction" defaultAction="ora-rethrow-fault">
            <returnValue value="REPLAY" ref="ora-terminate"/>
            <returnValue value="RETHROW" ref="ora-rethrow-fault"/>
            <returnValue value="ABORT" ref="ora-terminate"/>
            <returnValue value="RETRY" ref="aia-ora-retry"/>
            <returnValue value="MANUAL" ref="ora-human-intervention"/>
        </javaAction>
        </Action>
    </Actions>
</faultPolicy>
</faultPolicies>
---------------------------------------------------------------------------------------------------------------

FAULT BINDINGS
++++++++++++++

<?xml version="1.0" encoding="UTF-8"?>
<faultPolicyBindings version="3.0"
                     xmlns="http://schemas.oracle.com/bpel/faultpolicy"
                     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
       <component faultPolicy="BusinessFault">
        <name>MainBPELProcess</name>
    </component>
</faultPolicyBindings>

Now you are ready to go and test the custom fault handling using fault policies.

Happy Learning ..!!!!!

SOA 11g - Transaction Behavior and Delivery Policy in BPEL

Oracle SOA Suite 11gR1 (11.1.1.6.0) includes new features.Some of them are new delivery and transaction properties that you can set when creating a BPEL process.These configuration properties have a significant impact on the behavior of a BPEL process. You can now set these properties as part of the BPEL component creation process within JDeveloper. The wizard presents these properties and sets the default values based on the context. For example, the oneWayDeliveryPolicy property only shows up for one way processes and the transaction property only shows up for synchronous processes.

Delivery: The possible values are:

    async.persist: Messages into the system are saved in the delivery store before being picked up by the service engine.
    async.cache: Messages into the system are saved in memory before being picked up by the service engine.
    sync: The instance-initiating message is not temporarily saved in the delivery layer. The service engine uses the same thread to initiate the message.

Transaction: The possible values are:

    requiresNew: A new transaction is created for the execution, and the existing transaction (if there is one) is suspended. This behavior is true for both request/response (initiating) environments and one-way, initiating environments in which the Delivery list value (oneWayDeliveryPolicy property) is set to sync
    required: In request/response (initiating) environments, this setting joins a caller's transaction (if there is one) or creates a new transaction (if there is no transaction). In one-way, initiating environments in which the Delivery list value (oneWayDeliveryPolicy property) is set to sync, the invoke message is processed using the same thread in the same transaction.

For more information please refer this LINK.

Happy Learning !!!!!!!!!!!

SOA 11G - Getting and Setting JMS Header Properties in BPEL process

Sometimes there is requirement where you are required to set some JMS header values and then send the jms message to the client or consumer may interact with you via jms queue and sends some user defined properties in the JMS header.In BPEL 11G, we can easily set or retreive these values.

Setting JMS Header Values

Step1: Click on the invoke activity inside your BPEL process that is calling your JMS adapter for publishing messages in the jms queue.Then click on the source tab of BPEL.

Step2: Inside the invoke activity code add this property <bpelx:inputProperty name="jca.jms.JMSProperty.propertyname" variable="variablename"/>
where propertyname: name of the property you want to set and variablename: variable from which you are passing value to this property.For instance,in out usecase I am setting following properties:

      <bpelx:inputProperty name="jca.jms.JMSProperty.MSG_ID" variable="TransID"/>
      <bpelx:inputProperty name="jca.jms.JMSProperty.FROM_SYSTEM" variable="FROM_SYSTEM"/>
      <bpelx:inputProperty name="jca.jms.JMSProperty.ServiceName" variable="ServiceName"/>
Make sure you populate all these properties before calling invoke activity,otherwise these properties will contain null/blank values.

Step3: Deploy and test your code.Verify that these values are getting set by looking into the flow trace of your composite.

Step4: Also,you can verify the message in jms queue as well and see if the properties are properly set or not.

Getting JMS Header Values

Step5:Inside your BPEL process,click on the receive activity that is receiving input from the jms adapter and click on source.

Step6: Add this property inside your receive activity: <bpelx:outputProperty name="jca.jms.JMSProperty.propertyname" variable="variablename"/>. It is same as we did for setting the property except the outputProperty tag.In my example, I am retreiving the value of jms header that I set previously.

      <bpelx:outputProperty name="jca.jms.JMSProperty.MSG_ID" variable="TransID"/>
      <bpelx:outputProperty name="jca.jms.JMSProperty.FROM_SYSTEM" variable="FROM_SYSTEM"/>
      <bpelx:outputProperty name="jca.jms.JMSProperty.ServiceName" variable="ServiceName"/>

Create the variables that will store the values of these properties.

Step7: Deploy your code and test your composite.Inside flow trace verify you are able to retreive the jms properties headers value from the JMS message.

In this way you guys can set and get the header properties of any JMS message in SOA 11G.Apart from accessing these values from BPEL,you can also access these values from Mediator.In mediator, they are accessed in the assign step using:

Inbound: $in.property.jca.jms.JMSProperty.<propertyname>
Outbound: $out.property.jca.jms.JMSProperty.<propertyname>

Hope this post of some help to you.

Happy Learning..!!!!!!!!!!

SOA 11g - Setting and getting Preferences in SOA BPEL Process.

Deployment descriptors are BPEL process service component properties used at runtime by Oracle WebLogic Server, Oracle Enterprise Manager, or both.

Oracle has provided the functionality to add preferences to your bpel process.Preferences are like a variable whose value can be changed from EM console requiring no code change.For instance,consider one use case for File adapter.Suppose in test environment we are writing the files to /test/source location.Now once the code is migrated to production environment, now you want to write the files to /prod/source location.

These type of properties can be set using preferences, where you have to just update the value of preference variable for dircetory location on EM and there you go.We dont have to explicitly make changes in the code to point it to new location and deploy it again.

Depends upon requirement,what type of variables in BPEL can be declared as preferences.Ill be demonstrating how to set and get the values of these preference variables and how to change them using Enterprise Manager.

Step1: I will be using "HelloWorld" tutorial for this that we created in my first post.Open up your Hello World BPEL process.

Step2: Got to source of composite.xml and add "<property name="bpel.preference.MyVar">Old Value in Response</property>" in component section.Here we are setting the value for variable "MyVar" which we will be using in our BPEL process.

Step3: Now double click and open your BPEL process.Open the assign action.We will be populating the result of our BPEL process using this preference variable.Double click on result of our output variable to open up the expression window.Drill down to BPEL XPath Extension Functions and insert getPreference into expression field.Add the preference var in the function asora:getPreference("MyVar").Make sure you enclose your preference variable using double quotes.Click OK.

Step4: your assign action will look like this.Click OK.

Step5: Now deploy your composite on EM and test it passing any random input and open the flow trace of invoke composite.In the assign action you will see value of result as "Old Value in Response".It is the same value that we set inside composite.xml.

Step6: Now we will change this value from EM to some other value.Right click on SOA-Infra --> Administration --> System MBean Browser.

Step7: Drill down to your composie following this path oracle.soa.config-->Mgd Sever --> SCAComposite-->HeloWorld-->SCacomponnt.SCAComposite-->HelloWorldProcess.

Step8: Click on the properties tab on the right hand side and expand properties tab to find out element containg your defined preference variable

Step9: Change its value and click "Apply"

Step10: Test your interface again and thsi time you will see the updated value in the result.

In this way you can define n number of preference variables in your composite.xml and use them in your BPEL process.Should you guys have any question ,feel free to ask.

SOA 11g - BPEL Fault Handling

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"
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.

Hope you guys enjoyed it.....Any doubt please feel free to ask me...!!!!