Generate custom Error messages with WSO2 ESB

In this blogpost we will be looking at how to generate a soap fault using the makefault mediator. In addition to that I will show how to embed a custom message within that soap fault. Inorder to achieve this goal we will be using the makefault mediator and a script mediator.

The Synapse configuration used:

<?xml version="1.0" encoding="UTF-8"?>
<definitions xmlns="http://ws.apache.org/ns/synapse">
<localEntry key="detailsTransformScript" src="file:repository/samples/resources/script/detailTransform.js"/>
<sequence name="myFaultHandler">
    <property name="uniqueKey" value="123" scope="default" type="STRING"/>
    <property name="customErrorCode" value="8719" scope="default" type="STRING"/>
    <property name="customErrorText" value="Issue has " scope="default" type="STRING"/>
    <property name="customTime" expression="get-property('SYSTEM_DATE')" scope="default" type="STRING"/>
    <script language="js" key="detailsTransformScript" function="transformDetail"/>
    <log level="custom">
        <property name="Detail" expression="get-property('customErrorDetail')"/>
    </log>
    <makefault version="soap11">
        <code xmlns:tns="http://www.w3.org/2003/05/soap-envelope" value="tns:Receiver"/>
        <reason expression="get-property('ERROR_MESSAGE')"/>
        <detail expression="get-property('customErrorDetail')"/>
    </makefault>
    <send/>
</sequence>
<sequence name="fault">
    <log level="full">
        <property name="MESSAGE" value="Executing default "fault" sequence"/>
        <property name="ERROR_CODE" expression="get-property('ERROR_CODE')"/>
        <property name="ERROR_MESSAGE" expression="get-property('ERROR_MESSAGE')"/>
    </log>
    <drop/>
</sequence>
<sequence name="main" onError="myFaultHandler">
    <in>
        <switch xmlns:m0="http://services.samples" source="//m0:getQuote/m0:request/m0:symbol">
            <case regex="MSFT">
                <send>
                    <endpoint name="endpoint_urn_uuid_F3FC39CF93F681A11649593938524451942754528">
                        <address uri="http://bogus:9000/services/NonExistentStockQuoteService"/>
                    </endpoint>
                </send>
            </case>
            <case regex="SUN">
                <send>
                    <endpoint name="endpoint_urn_uuid_F3FC39CF93F681A1164959398253284-1608236576">
                        <address uri="http://localhost:9009/services/NonExistentStockQuoteService"/>
                    </endpoint>
                </send>
            </case>
        </switch>
        <drop/>
    </in>
    <out>
        <send/>
    </out>
</sequence>
</definitions>

The javascript file used in the script mediator:

 function transformDetail(mc) {
     var symbol = mc.getPayloadXML()..*::Code.toString();
     var errorCode = mc.getProperty("customErrorCode");
     var errorText = mc.getProperty("customErrorText");
     var time = mc.getProperty('customTime');
     mc.setProperty("customErrorDetail", <AppErrorCode><TimeStamp>{time}</TimeStamp><ErrorCode>{errorCode}</ErrorCode><ErrorText>{errorText}</ErrorText></AppErrorCode>);
  }

Instructions to run the sample.
1) Copy the attached javascript file to ESB_HOME/repository/samples/resources/script/ directory.

2) Startup the ESB instance. Copy the attached synapse configuration to source view of the Management UI and hit update.

3) Start the Axis2 server and deploy the SimpleStockQuoteService if not already done.

4) Execute the client using following command.

ant stockquote -Daddurl=http://localhost:9000/services/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/ -Dsymbol=MSFT

5) Monitor the response message with TCPMon.

HTTP/1.1 500 Internal Server Error
Content-Type: text/xml; charset=UTF-8
Host: 127.0.0.1:8281
SOAPAction: "urn:getQuote"
Date: Thu, 21 Oct 2010 09:52:23 GMT
Transfer-Encoding: chunked

338
<?xml version='1.0' encoding='UTF-8'?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
  <soapenv:Header xmlns:wsa="http://www.w3.org/2005/08/addressing">
     <wsa:MessageID>urn:uuid:952C448142FB1B1FE925278283667424-1166645935</wsa:MessageID>
     <wsa:Action>urn:getQuote</wsa:Action>
     <wsa:RelatesTo>urn:uuid:6DDD0BCE4CDCFB5AFD1287654743750</wsa:RelatesTo>
  </soapenv:Header>
  <soapenv:Body>
     <soapenv:Fault>
        <faultcode xmlns:tns="http://www.w3.org/2003/05/soap-envelope">tns:Receiver</faultcode>
        <faultstring>Connection refused or failed for : bogus:9000, IO Exception occured : bogus</faultstring>
        <detail>
<AppErrorCode>
<TimeStamp>10/21/10 3:22 PM</TimeStamp>
<ErrorCode>8719</ErrorCode>
<ErrorText>A custom issue has occured</ErrorText>
</AppErrorCode></detail>
     </soapenv:Fault>
  </soapenv:Body>
</soapenv:Envelope>0

As you can see we have added a custom details element which is containing some information that you would like to generate.

Further Reading

[1] - Refer transport ERROR codes in https://svn.apache.org/repos/asf/synapse/trunk/java/modules/core/src/main/java/org/apache/synapse/SynapseConstants.java

[2] - Property Mediator section of the WSO2 ESB Configuration language
http://wso2.org/project/esb/java/3.0.1/docs/configuration_language.html#property

[3] - WSO2 ESB error handling samples.
http://wso2.org/project/esb/java/3.0.1/docs/samples/message_mediation_samples.html#Sample4
http://wso2.org/project/esb/java/3.0.1/docs/samples/message_mediation_samples.html#Sample5

[4] - We are having built in Error Codes for transport related errors. Say for instance that you need to handle an error related to an XML format error. That kind of issues can be resolved by using fault handlers.
eg: If a sequence fail in an XSLT transformation phase due to to an XML format error, you can register a fault handler for a sequence to handle it. For more information read Error Handling with Sequences and Proxy Services .