How to Debug WSO2 ESB Mediation Flow

How to Debug WSO2 ESB Mediation Flow


WSO2 Enterprise Service Bus is a lightweight, high performance, and comprehensive ESB. 100% open source, the WSO2 ESB effectively addresses integration standards and supports all integration patterns, enabling interoperability among various heterogeneous systems and business applications.

And now it also contains message mediation debugging support with the release version 5.0.0. In this post I will deploy a simple proxy on WSO2 ESB and debug the message mediation flow.


First we need to have the mediation debugger supported ESB distribution. WSO2 ESB 5.0.0 is the distribution packed with mediation debugger. You can download latest pack from here.

And also we need to have a debugger supported Developer Studio ESB Tool. You can follow this article to install the WSO2 Developer Studio ESB Tool 4.1.0.


Lets create a simple scenario where we have a  client, ESB Server and Service.

ESB Debugger Simple USecase(1)

We can use WSO2 try it tool or SOAP UI to send a request from client side. And as this is just to check the ESB Mediation Debugger functionality we will use WSO2 server inbuilt echo service as our service.

Creating Proxy Service

So first now we have to built a proxy service to WSO2 ESB which will get the client request and do some modifications on the received message and sent it to our echo service and get the response from the echo service and sent it back to client after some modifications.

So start WSO2 Developer Studio ESB Tool and create a proxy service with name “EchoServiceWithName”.

It will simply get the following request from the client.


Modify it to following message before sending it to echo service.

<echoString xmlns:ns1=""><in>Mike</in>

And we will receive a message like below.

<echoStringResponse xmlns:ns="">Mike</ns:echoStringResponse>



Then we will modify it to following message and send it back to client.

<end>for WSO2 technologies !!!</end>

This is done by the following configuration.

<proxy name="EchoServiceWithName" startOnLoad="true" trace="disable" transports="http https" xmlns="">
<property expression="/login/user/displayname" name="Name" scope="default" type="STRING"/>
<payloadFactory media-type="xml">
<ns1:echoString xmlns:ns1="">
<arg evaluator="xml" expression="get-property('Name')"/>
<address trace="disable" uri="http://localhost:8280/services/echo"/>
<property expression="/ns:echoStringResponse" name="EchoName" scope="default" type="STRING" xmlns:ns=""/>
<payloadFactory media-type="xml">
<end>for WSO2 technologies !!!</end>
<arg evaluator="xml" expression="get-property('EchoName')"/>

After creating proxy service with above configuration it should be as follows.


Now we are all set to debug. We have all components ready to test out proxy service with debugger.

Starting WSO2 ESB Server with Developer Studio ESB Tool to Debug

There are two ways to start a wso2 esb server.

  • First way is from the terminal we can navigate to server file location bin folder and execute as follows.startserverterminal
  • Second way is we can start esb server from Developer Studio ESb Tool by adding it from the Servers view.serverTab


But to support mediation debugging we need to provide command line arguments as “-Desb.debug=true”.

Then the ESB server will listen on two ports to connect with Developer Studio ESB Mediation Debugger as configured in the [esbserver]/repository/conf/ file.

#configuration for the external debugger channels if server is started in debug mode

Then we have to connect developer studio esb tool with esb server by execution above created debug configuration. We have roughly 1 minute time span to connect, otherwise esb server will stop listening and start the server without connecting with debugger tool.

So we should first build the debug configuration from the WSO2 Developer Studio ESB Tool before starting the ESB Server in the debug mode.

Go to Debug Configurations in the Developer Studio and you will see a type of debug configuration named ESB Mediation Debugger


Then double click on ESB Mediation Debugger and you will get configuration dialog as below.


It will contain the default command port and event port as 905 and 9006 with your local host name.

If you want to change the default ports, you should modify both server file and this configuration parameters.

And you can remote debug a server which is running in a different host by modifying the Server host with it’s ip.

Now start the ESB Server in the mediation debug mode with the command “sh -Desb.debug=true” and click the Debug button when server listing to the ports as bellow.


Deploy Created Artifacts in Server

Now we have to deploy the previously created proxy service in ESB Server. For that we can create a CAPP using developer studio.


To deploy it from developer studio we need to have the ESB server in the Servers of developer studio. If you started the ESB server from developer studio you can noe directly add the CAPP. Otherwise add the ESB server by going to Servers view-> Add New Server -> WSO2 -> carbon remote server , and specify the host name as follows.newServer.pngremoteip.png

Now you can add and deploy the capp in the server.


Our use case should work. So go to the ESB Server Management Console and select our proxy service try this service tool.

And send the request message as we discussed above. But we will not get the expected output.


Our response doesn’t contain the name. So lets debug the message flow. Put debug breakpoints by right click on the mediators.


And send the request again. ESB Message mediation will stop at the first breakpoint position.


There you can see in the variables table under Synapse Scope Properties “Name” property we defined  is empty. There should be an error of out expression. Oh!! yap, it is wrong the expression should be start with double slashes like this “//login/user/displayname” .

Lets look that do we have more errors. If above expression was correct now we have a the value of property “Name” as Mike. So put the value in the variable table and enter. Now the property  value will be changed to “Mike” in the ESb Server.


Lets resume the process. It will stop at send mediator. And we will have the expected message after the payload factory mediator. So we can continue.

Oh then another mistake. The returned message from the Echo service is not what we expected.


It contain another element named “return” inside the “echoStringResponse” element. So we need to modify the expression of the  property mediator in the out sequence too. It should be “//ns:echoStringResponse/return”.

Lets again put the property value as “Mike” for the property “EchoName” so that we could check the next steps.


Now we can see the final message is what we expect. So save the modifications done and redeploy the proxy to the server.

And send the request again. We now get the expected response. Great!!!

You will observe that after we redeploy the proxy ESB didn’t suspended at the breakpoints. That is because when the configuration changed in the ESB Server all breakpoint information will be lost. So if we want to debug it we have to re send the breakpoints. For that you only need to right click on ESB diagram editor and in the context menu you will see command Resend ESb Breakpoints. Thats it.



We will discuss more on other features of WSO2 ESB Mediation Debugger in the next post. Since this covers the how to debug ESB Mediation you can also self observe the other features.

You can try this and report the bugs and suggest improvements from the following link as JIRAs.



Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s