WSO2 ESB Tips & Tricks 05: Error Handling with Sequences and Proxy Services

The job of an Enterprise Service Bus is to act as the backbone of an organization’s SOA. It is the spine through which all the systems and applications within the enterprise communicate with each other. At times an ESB might even help to integrate internal systems with external applications so that complex cross cutting business tasks such as supply chain management and customer relationship management can be carried out with precision and in perfect synchronism. As such an ESB often has to deal with many wire level protocols, messaging standards and remote APIs. But applications and networks are full of errors. Applications often crash due to various bugs. Network routers and links often get into states where they cannot pass messages through with the expected efficiency. These error conditions are very likely to cause a fault or trigger a runtime exception in the ESB. A good ESB should provide simple yet powerful mechanisms for dealing with such errors. So today, I’m going to discuss a little bit about error handling options provided in WSO2 ESB.

WSO2 ESB gives you the concept of fault sequences. A fault sequence is just like any other sequence, a collection of mediators. A fault sequence can be associated with another sequence or a proxy service. When the sequence or the proxy service encounters an error during mediation or while forwarding a message out, the message which triggered the error will be delegated to the specified fault sequence. Using the available mediators we can log the erroneous message, forward it to a special error tracking service, send a SOAP fault back to the client indicating the error or even send a mail to the system admin. It is not mandatory to associate each sequence and proxy service with a fault sequence. In situations where a fault sequence is not specified explicitly, a default fault sequence will be used to handle errors. Sample 4 in WSO2 ESB documentation shows how to specify a fault sequence with a regular mediation sequence.

Whenever an error occurs in WSO2 ESB, the mediation engine attempts to provide as much information as possible on the error to the user. This is done by initializing a set of property values on the erroneous message. These properties are:

• ERROR_CODE
• ERROR_MESSAGE
• ERROR_DETAIL
• ERROR_EXCEPTION

Within the fault sequence we can access these property values using the get-property XPath function. Sample 4 uses the log mediator as follows to log the actual error message:

<log level="custom">
  <property name="text" value="An unexpected error occured"/>
  <property name="message" expression="get-property('ERROR_MESSAGE')"/>       
</log>

Note how the ERROR_MESSAGE property is being used to get the error message text. You can also write special custom mediators for error handling tasks. In such cases you can use the MessageContext API to retrieve above mentioned property values from the message.

String errorMsg = (String) messageContext.getProperty(“ERROR_MESSAGE”);

Exception e = (Exception) messageContext.getProperty(“ERROR_EXCEPTION”);

WSO2 ESB also makes it possible to send a SOAP fault back to the client whenever an exception occurs in the ESB. This is done using the makeFault mediator. The makeFault mediator converts the current message into a SOAP fault. The user can specify the error code and the reason statement to be included in the fault message. Once the SOAP fault is constructed it can be sent to the client using the send mediator. Sample 5 in WSO2 ESB documentation shows exactly how to do this. Here’s the makeFault mediator configuration from sample 5:

<makefault>
  <code value="tns:Receiver" xmlns:tns="http://www.w3.org/2003/05/soap-envelope"/>           
  <reason expression="get-property('ERROR_MESSAGE')"/>
</makefault>

Note how the ERROR_MESSAGE property is used to set the original error message as the reason phrase of the SOAP fault. Keep in mind that the makeFault mediator only converts the message into a fault message. To send it to a client or an endpoint you need to use the send mediator. In sample 5 we mark the message as a response using the property mediator and invoke the send mediator so that it is sent back to the client which sent the original request.

Assume you want to send an E-Mail to the system admin whenever the ESB encounters an error. How do you do it? You simply need to enable the mail transport sender in the ESB configuration (by editing the axis2.xml file or using the UI). Configure the transport sender with the appropriate mail server settings. Then in your fault sequence you can simply use the send mediator as follows to send an E-Mail out.

<property name="Subject" value="An Error Occurred in the ESB" scope="transport"/>
<property name="OUT_ONLY" value="true"/>
<send>   
  <endpoint>       
     <address uri=”mailto:admin@yourdomain.com”/>
  </endpoint>
</send>

So these are the error handling options available for sequences and proxy services in WSO2 ESB. It also provides some more error handling options for endpoints. That however is a different matter entirely and hence I’m leaving it for a future blog post.