Lesson06-Fault Management

In this tutorial we will examine how to handle run time and business faults, in case of synchronous and asynchronous requests. Here is the flow chart of the use-case we’ll implement.

 Client sends a one-way synchronous request message through Mediator.
 If Mediator detects invalid XML message  (schema validation) runtime exception is directly returned to the client.
 Mediator sends a request to BPEL process through “queued” type routing rule. This is equivalent to starting an asynchronous process.
 BPEL exceptions (both runtime and business faults) are sent back to Mediator. These exceptions are handled as per policies defined in Fault Management Framework.
 When faults are corrected through human intervention/retry, control goes back to the component that raised the exception initially and request completes successfully.

---

Above flow chart describes an Address validation process. A BPEL process and Mediator are created based on an existing WSDL. High level definition of Address Validation process artefacts:
Address schema contains definitions for Address Line1, Line2, City, State, Zipcode and Country. Each of these elements have a length restriction of 16.

<xsd:element name="address" type="tAddress"/>
<xsd:complexType name="tAddress">
<xsd:sequence>
<xsd:element name="line1" type="tFixedLengthString"/>
<xsd:element name="line2" type="tFixedLengthString"/>
<xsd:element name="city" type="tFixedLengthString"/>
<xsd:element name="state" type="tFixedLengthString"/>
<xsd:element name="zip" type="tFixedLengthString"/>
<xsd:element name="country" type="tFixedLengthString"/>
</xsd:sequence>
</xsd:complexType>
<xsd:simpleType name="tFixedLengthString">
<xsd:restriction base="xsd:string">
<xsd:maxLength value="16"/>
</xsd:restriction>
</xsd:simpleType>

Address Fault is defined as follows:

<xsd:complexType name="tAddressFault">
<xsd:sequence>
<xsd:element name="code" type="xsd:string"/>
<xsd:element name="name" type="xsd:string"/>
<xsd:element name="desc" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>

Address Validation process has one operation that includes a business fault along with request and response messages.

<wsdl:portType name="AddressValidationProcess">
<wsdl:operation name="process">
<wsdl:input message="client:AddressValidationProcessRequestMessage"/>
<wsdl:output message="client:AddressValidationProcessResponseMessage"/>
<wsdl:fault name="AddressBusinessFault" message="client:AddressValidationProcessFaultMessage"/>
</wsdl:operation>
</wsdl:portType>

Initial sanity check is performed in Mediator component. Mediator performs following checks:
1. Input XML content validation as per schema. If any of the field has more than 16 characters, ValidationError is thrown. Since it is a synchronous request, error is directly returned to the client. Do note that Schema validation happens even before any routing rule is triggered. So, Mediator inherits the transaction of the requestor.
2. Schematron Validation for post code: Post code should contain 6 to 8 characters. Otherwise, Schematron Validation error is thrown. However, since Schematron validation happens for a payload of a routing rule that is of “queued” type. This makes the Validation Error propogated to Fault Management Framework.

ORAMED-01301:[Payload custom validation]Schematron validation fails with error <ns1:ValidationErrors xmlns:ebo="http://orafmwschool.com/training/faultmanagement/xsd/AddressValidation" xmlns:ebm="http://orafmwschool.com/training/faultmanagement/ebm/AddressValidation" xmlns:ns1="http://xmlns.oracle.com/pcbpel/validationservice"> <error>Zip code should be atleast 6 characters long.</error> </ns1:ValidationErrors> Possible Fix:Fix the payload.

If these checks are successful, request is sent to BPEL process that is designed to throw two of the following exceptions:
Validation Exception: XML content validation can also be performed in BPEL through “Validation” activity. In such cases invalidVariable runtime fault is thrown. This fault is sent back to Mediator and handled through fault policy defined in fault management framework.

System Fault :

ORAMED-03303:[Unexpected exception in case execution]Unexpected exception in request response operation "process" on reference "AddressValidationProcess.AddressValidationService". Possible Fix:Check whether the reference service is properly configured and running or look at exception for analysing the reason or contact oracle support. Cause:faultName: {{http://schemas.oracle.com/bpel/extension}invalidVariables} parts: {{ summary=<summary>Failed to validate bpel variable. validation of variable inputVariable failed. The reason was: Invalid text ‘This is a long string.’ in element: ‘line1′. Pleasehandle the exception in bpel. </summary>}

This fault can be recovered.

AddressBusinessFault: When City name is London, BPEL process will throw AddressBusinessFault. This fault is declared in WSDL. Mediator will catch this exception and is automatically handled through fault management framework.

Error Message: Encountered a business fault(Qname – {http://orafmwschool.com/training/faultmanagement/service/AddressValidation}AddressBusinessFault).

faultName: {{http://orafmwschool.com/training/faultmanagement/service/AddressValidation}AddressBusinessFault} messageType: {{http://orafmwschool.com/training/faultmanagement/service/AddressValidation}AddressValidationProcessFaultMessage} parts: {{ payload=<AddressFault xmlns="http://orafmwschool.com/training/faultmanagement/ebm/AddressValidation"/>}

If these checks are successful, request is sent to BPEL process that is designed to throw two of the following exceptions:

Following Fault Policies are defined in fault-policies.xml:

When AddressBusinessFault occurs, request is sent for human intervention through fault management framework. This request can be accessed through Enterprise Manager.

<faultName xmlns:addr="http://orafmwschool.com/training/faultmanagement/service/AddressValidation"
           name="addr:AddressBusinessFault">
  <condition>
    <action ref="ora-human-intervention"/>
  </condition>
</faultName>

<Action id="ora-human-intervention">
  <humanIntervention/>
</Action>

When any other runtime fault occurs in BPEL or Schematron validation error,  it is mapped to MediatorFault. Fault Policy is defined to retry such requests for three times. If issue is still unresolved, it will be sent for human intervention.

<faultName xmlns:medns="http://schemas.oracle.com/mediator/faults"
           name="medns:mediatorFault">
  <condition>
    <action ref="ora-retry"/>
  </condition>
</faultName>

<Action id="ora-retry">
  <retry>
    <retryCount>3</retryCount>
    <retryInterval>5</retryInterval>
    <exponentialBackoff/>
    <retryFailureAction ref="ora-human-intervention"/>
    <retrySuccessAction ref="ora-terminate"/>
  </retry>
</Action>

For any other fault, validation error is mapped to generic fault handler and is sent for human intervention.

<faultName>
  <condition>
    <action ref="ora-terminate"/>
  </condition>
</faultName>

---

Here are the steps to install and test this sample:

1. Download complete JDeveloper project from here and open FaultManagementExample.jpr
2. Deploy FaultManagementExample project to SOA Suite 11g.
3. Use “Test” button in Enterprise Manager to perform following tests on the composite:

Testcase 1: Schematron Validation causing Mediator Fault to be thrown.
Enter post code of either less than 6 characters or more than 8 characters. Sample payload:

<ns1:AddressValidationRequest>
<ns2:address>
<ns2:line1>TEST</ns2:line1>
<ns2:line2>TEST</ns2:line2>
<ns2:city>TEST</ns2:city>
<ns2:state>TEST</ns2:state>
<ns2:zip>E10</ns2:zip>
<ns2:country>TEST</ns2:country>
</ns2:address>
</ns1:AddressValidationRequest>

A Mediator Fault will be thrown and Fault Management framework retries the process three times, before sending for human intervention. You can see that the process status as “Recovery Needed”.
Testcase 2: Invalid XML document – Input String more than 16 characters.
Give a value of more than 16 characters for “line1” element. Sample payload:

<ns1:AddressValidationRequest>
<ns2:address>
<ns2:line1>This is a long string.</ns2:line1>
<ns2:line2>Address Line2</ns2:line2>
<ns2:city>City</ns2:city>
<ns2:state>State</ns2:state>
<ns2:zip>E10 5QS</ns2:zip>
<ns2:country>UK</ns2:country>
</ns2:address>
</ns1:AddressValidationRequest>

BPEL throws invalidVariables fault that will be sent to Mediator. Mediator maps it to MediatorFault. As per policy, Fault Management framework retries this process three times, before sending for human intervention. You can see that the process status as “Recovery Needed”.
Testcase 3: AddressBusinessFault – Specify London as city name.
BPEL process is designed to perform a check for city name. If city is “London” then BPEL thrown a business fault: AddressBusinessFault that will be caught by Mediator. Since this fault is already declared in WSDL, Mediator will not map it to MediatorFault.
As per the fault policy defined, this request will be sent for human intervention and can be accessed through Enterprise Manager.
Sample payload:

<ns1:AddressValidationRequest>
<ns2:address>
<ns2:line1>test</ns2:line1>
<ns2:line2>test</ns2:line2>
<ns2:city>London</ns2:city>
<ns2:state>test</ns2:state>
<ns2:zip>E10 5QS</ns2:zip>
<ns2:country>UK</ns2:country>
</ns2:address>
</ns1:AddressValidationRequest>

Hope this sample was useful in understanding Fault Management in SOA Suite 11g.