Oracle Service Bus, Generic fault handling

The input we will send to this service will be in the format of
[sourcecode language=”xml”]

{$body}
{$inbound}
{$fault}

[/sourcecode]

The flow will eventually look something like this

Let’s look at the individual steps

1. retrieveErrorMetadata

The first step will contain 2 assigns.

The first assign will assign the ErrorRepository.xq to variable errorList

The content of the ErrorRepository.xq is the next
[sourcecode language=”xml”]
xquery version “1.0” encoding “Cp1252″;
(:: pragma type=”xs:anyType” ::)

declare namespace xf = “http://nl.xenta/services/errorRepository”;

declare function xf:service_error_handling()
as element(*) {


BEA-382505
VALIDATE-9999
Validation of the XML payload failedOSB
ErrorHandling/errorRepository/GenericFault_To_SOAPFault
Y
N

Y
Y


BEA-380000
GENERIC-1234
General transport error occuredSYSTEM-X
ErrorHandling/errorRepository/GenericFault_To_SOAPFault2
Y
N

Y
Y


DEFAULT
XXX_DEFAULT_ERROR
Something went wrong!NA
ErrorHandling/errorRepository/GenericFault_To_SOAPFault
Y
N

Y
Y


};

xf:service_error_handling()

[/sourcecode]

At this point we have the list of faults together with metadata about what to execute when they occure available in the Message Flow.

In the second assign we retrieve only the the metadata from our occured fault, so we just retrieve 1 error-element from the list.

For this we execute the lookupError xquery which receives the errorList content and the errorCode and will return the error-element.
If we can’t retrieve any metadata based on the errorCode we will return a default set of metadata (the error-element of which the code = DEFAULT).
The result we will assign to the errorMetadataDetails variable.

Content of lookupError xquery
[sourcecode language=”xml”]
(:: pragma bea:global-element-parameter parameter=”$errorList” element=”err:service_error_handling” location=”ErrorRepository.xsd” ::)
(:: pragma bea:global-element-return element=”ns0:error” location=”ErrorRepository.xsd” ::)

declare namespace err = “http://nl.xenta/services/errorRepository”;
declare namespace xf = “http://nl.xenta/services/faults/lookupError/”;

declare function xf:lookupError2($errorCode as xs:string,
$errorList as element(err:service_error_handling))
as element(err:error) {

if(string-length($errorList/err:error[err:code=$errorCode]) > 0)
then (
let $resolvedError := $errorList/err:error[err:code=$errorCode]
return $resolvedError
) else (
let $resolvedError := $errorList/err:error[err:code=’DEFAULT’]
return $resolvedError
)
};

declare variable $errorCode as xs:string external;
declare variable $errorList as element(err:service_error_handling) external;

xf:lookupError2($errorCode,$errorList)
[/sourcecode]

2. conditionalReporting

In all the conditional stages we will now re-use the errorMetadataDetails variable to verify if we want to execute certain login.

If we configurated the indReporting=Y in the error repository xquery file then the if-then loginc will evaluate to the if-tree and the Report-activty will be executed.
In the same way all the other condition stages (conditionalAlert, conditionalSomethingElse) will work. We re-use the errorMetadataDetails-variable and just do a simple if-then check to see if certain logic needs to be executed.

3. constructResponse

The last step of the message flow is the step in which we construct the response of the errorHandler process back to the client process.
In this step we will be using Dynamic Xquery to be able the construct response messages based on the incoming fault.
The example of our ErrorReposity defines 2 faults and 1 default.
In case for example error BEA-380000 occures, we will use the xquery located at ErrorHandling/errorRepository/GenericFault_To_SOAPFault2 to be executed. This xquery will construct our soap fault.

To be able to use Dynamic Xquery all the to be used xquery transformations need to have the same interface. Depending on the backend system and the returning faults from it we will use different tranformation files.
But all of them will be using the input paramters ‘body, inbound and fault’. In the expression field we will use the faultTransformer-element from the errorMetadataDetails. So for every fault for which we want to create a
different fault response we do need to define a faultTransformer-value in the errorRepository.

And that’s all what is needed to implement in the errorHandler process to receive the metadata, handle the fault and construct the response.

Testcase

For this testcase we created a simple EmployeeService. Create a new proxy service based on the next wsdl/xsd content.
[sourcecode language=”xml”]

































[/sourcecode]
[sourcecode language=”xml”]




Comment describing your root element























[/sourcecode]

And the message flow will eventually look like this

The first assign will assign the body to body_temp so in case of an error situation we still have the original body content stored

The second activity is the validation activity. This one we will be using lateron to trigger a fault which will be processed by the errorHandler process.
Based on the same wsdl as the proxy service i defined a new business service. In the EmployeeService proxy we will be routing to this business service.
Since we won’t be implementing any logic on this side we just update the endpoint of the business service to something useless so the route will fail on this one.

This part is used to the second fault triggering moment in our process. Also this situation will fail and the occured fault will get processed by the errorHandler.

The ‘normal’ message flow of our proxy service is now done.
Let’s have a look at the service error handler.

The first assign will use the next xquery and assign the result to errorhandler_request
[sourcecode language=”xml”]
xquery version “1.0” encoding “Cp1252″;
(:: pragma parameter=”$body” type=”xs:anyType” ::)
(:: pragma parameter=”$fault” type=”xs:anyType” ::)
(:: pragma parameter=”$inbound” type=”xs:anyType” ::)
(:: pragma type=”xs:anyType” ::)

declare namespace xf = “http://tempuri.org/ErrorHandling/proxy/constructErrorHandlingInput/”;

declare function xf:constructErrorHandlingInput($body as element(*),
$fault as element(*),
$inbound as element(*))
as element(*) {

{$body}
{$inbound}
{$fault}

};

declare variable $body as element(*) external;
declare variable $fault as element(*) external;
declare variable $inbound as element(*) external;

xf:constructErrorHandlingInput($body, $fault, $inbound)
[/sourcecode]

In the binding we will use the body_temp variable so we have the original body content of the process.

The next activity is the service callout to the errorHandler process

The third activity is an assign which will assign the constructed body from the errorHandler process to the body variable

And the last activity will be a ‘Reply with Failure’

Testrun

In the ErrorRepository we defined 2 faults, BEA-382505 and BEA-380000.
For both faults we defined a different faultTransformer.

BEA-382505 = ErrorHandling/errorRepository/GenericFault_To_SOAPFault
BEA-380000 = ErrorHandling/errorRepository/GenericFault_To_SOAPFault2

GenericFault_To_SOAPFault will return
[sourcecode language=”xml”]

soapenv:Server
(:{data($errorMetadataDetails/err:omschrijving)}🙂
some resource path
{fn:concat($inbound/ctx:transport/ctx:request/tp:headers/http:Host/text(),”/”,$inbound/ctx:transport/ctx:uri/text())}

{$body, $fault, $inbound}


[/sourcecode]

GenericFault_To_SOAPFault2 will return
[sourcecode language=”xml”]

soapenv:Server
(:{data($errorMetadataDetails/err:omschrijving)}🙂
some resource path
{fn:concat($inbound/ctx:transport/ctx:request/tp:headers/http:Host/text(),”/”,$inbound/ctx:transport/ctx:uri/text())}

{$body, $fault, $inbound}


[/sourcecode]

Deploy the process.

Now test the process either by using the testconsole of some testclient.

The first testcase will have a valid input message. So the process will pass the Validation activity and will fail when routing to the business service.
Since we used a non-existing host in here the process will trigger a BEA-380000 fault. As we defined in the errorRepository this errorCode will have the next set of metadata configured
[sourcecode language=”xml”]

BEA-380000
GENERIC-1234
General transport error occuredSYSTEM-X
ErrorHandling/errorRepository/GenericFault_To_SOAPFault2
Y
N

Y
Y

[/sourcecode]

The generated soap fault is correct. It contains the custom_details2-element, which is generated by the GenericFault_To_SOAPFault2 transformer.
Next check the sbconsole to see if there is also a report triggered for this error (indReporting=Y).

Next check the weblogic console to see if the alert got executed (indAlert=Y). For this one i created an alert with JMS Destionation.

For the second testcase we will use an invalid input message. The validation will throw an error (BEA-382505).
Check the generated soap fault (custom_details-element should get generated now).

And verify the alert and report too, to see if they got handled correctly.

Extensibility

In our xsd definition of the errorRepository we only defined a few settings just to show how it could work.
Eventually this model can be extend with every setting you need in your error handling processes. Since all the logic of reading those settings and decide what logic to execute is defined on only
one place, the errorHandler proxy service itself, it’s little work to extend the current logic for handlin the errors with new functionality. Just a new if-then activities for new settings and you’re ready to go.

Conclusion

The functionality as defined in the blog for handling the errors and creating a single point of error processing was enough for my testcase.
I needed all the logic on one place and not in every process. I needed a single place in which i could define all the errors i wanted to handle and what actions to execute when such an error occurs.
Besides that i needed a way in which other persons could easily add new defined errors to the file and the process would just ‘handle’ them without adding extra logic to processes.
In case you don’t want someone else to manipulate the errorRepository file directly from within the sbconsole itself we could also just read the content of this file from some other external location by use of the doc() function, see this blog.

I hope the solution described will help you a bit on implementation error handling in the Oracle Service Bus.
As i’m always keen on learning from others, please leave comments on how to make the implementation better, or if the solution is totally useless please say so too 🙂

download : OracleServiceBusGenericErrorHandling.zip