WSO2 API Manager for message mediation

Even though the API Manager’s primary focus is to manage and expose API’s to different API consumers, it a common scenario to have the API Manager to perform some level of message mediation for both message requests and responses. The gateway component of the WSO2 API Manager is essentially a lightweight ESB that can perform almost all mediation activities that can be done by a regular ESB.

Newer releases of WSO2 API Manager provides the ability to attach mediation sequence to the request, response or the fault sequence of an API. The sequence gets executed when a request is made or a response is received to a request. Let’s look at how to add a message mediation to an API.

  1. Firstly you need to create message mediation sequence. Lets create the following sequence that would add a header to an out-going message. Save this sequence as setHeader.xml`
<sequence xmlns=""  name="SetHeader">
<header name="TempHeader" value="Test Header Value" action=set/>
  1. Log-in to the management console of the API Manager. You can access the management console via the following URL https://{IP}:9443/carbon You will find multiple options in the left hand navigation bar, select the ‘Browse’ icon in the Resources tab as shown below to access the internal registry.


  1. Once inside the registry, navigate into ‘/_system/governance/apimgt/customsequences/in/’ folder in the registry and add the newly created setHeader.xml. Similarly if you have any sequence that needs to be added to the out sequence or the fault sequence you can do so by going into each of these folders under ‘customsequences’ folder. You can upload a sequence by selecting ‘Add Resource’ button and upload this file as shown below.


  1. Once this is done, you can go to the publisher of the API Manager, and create a new API. Enter the required information in ‘Design’ and ‘Implement’ tabs and move to the ‘Manage’ tab. In the ‘Manage’ tab tick on the ‘message mediation policies’ and select the ‘SetHeader’ from the inflow dropdown as shown below. Once this is done Save & Publish the API to the API Store.


  1. You can now invoke the API from the API Store. You will see that the new header called ‘TempHeader’ is added to the message request before the backend API is invoked.

Implementing a Data Diode with WSO2 ESB

Data Diode is the data pattern that ensures unidirectional data flow between networks and is useful for enterprises who want to connect networks with different security levels. This patterns will be used to ensure that data is only allowed to flow from the low side (low security network) to high side (high security network). This type of a dataflow, in most cases is controlled at the network level, but if a need arise to control this at a data layer this EIP pattern can be used. Let’s look at the image below


As you can see in this diagram, two WSO2 ESB’s reside on two sides of the network. The ESB in the unsecure network is connected to different applications in the unsecured network. It also connects to the ESB in the secure network and the communication is encrypted (if needed integrity and non-repudiation can also be ensured) using WS-Security.

The ESB in the secure network has all its outbound transports (except JMS transport) removed, hence the ESB can only receive messages from the unsecured network whilst it can only send out messages to a pre-designated message queue.

Consumers of this data can listen to the queue and pull messages from the queue once they are queued.

Setting up the ESB to work in this pattern would require the execution of following steps

  1. Remove/Disable all out-going transports except the JMS and local transport. This can be done by disabling/removing all transportSenders from the following configuration file.

The transportSender section of the configuration file should only have the two transports below.

<transportSender name="local" class="org.wso2.carbon.core.transports.local.CarbonLocalTransportSender"/>
<transportSender name="jms" class="org.apache.axis2.transport.jms.JMSSender"/>
  1. Configure a message queue, you can configure a JMS or AMQP based message queue. More instruction on how to configure the queue can be found in the following link

  1. Create a Proxy service as given below.
  1. Finally Secure the proxy service, you can follow the instructions below to secure a proxy service using the WSO2 ESB.

You can now try to invoke the DiodeProxy from the unsecure network, you will notice that no response would be received back from this proxy. Even if a new proxy service is created in the secured ESB, the communication would still be blocked by the ESB as all but the JMS is blocked in the secured ESB.

ESB Guaranteed Delivery with client acknowledgement for synchronous clients

ESB Guranteed Delivery

A typical guaranteed delivery scenario covered as an Enterprise Integration ensures the delivery of a message to a given backend endpoint. As per this pattern the ESB would attempt to delivers the message to the backend endpoint and if it fails, the message would be stored and delivered once the backend endpoint becomes available. If the above guaranteed delivery mechanism is implemented to a message flow that is synchronous the client would be waiting for a response from the ESB until the message times out. To accommodate synchronous clients in a guaranteed delivery scenario, it is possible for the ESB to respond to the client with a fault message in case the message is not delivered and stored for later delivery. The following diagram depicts the message flow of the guaranteed delivery scenario with client acknowledgement using the WSO2 ESB.


  1. Client sends the message to the ESB.
  2. ESB try to deliver the message to the backend system, and the message fails
  3. ESB stores the message in a message queue
  4. ESB sends a response back to the client (response can be customized as required)
  5. ESB picks the message from the queue and try to deliver the message to the backend system; ESB retry can be customized to retry a given number of attempts.

The following synapse configuration can be used to configure this scenario. The configuration includes a proxy service, message broker, message processor, sequences and endpoints required to create the required mediation flow. Please note that the configuration is based on storing messages in an ActiveMQ based message queue. Hence it is required to follow the steps mentioned in the following link [1] setting up ActiveMQ with WSO2 ESB. [1]

IP based filtering for Proxy services exposed by WSO2 ESB

WSO2 ESB provides the ability to filter messages based on different parameters. These parameters include data in the message header, message content or even data relating to the message sender. This blog looks into how WSO2 ESB can be used to filter a message based on the IP Address of a client. The below ESB configuration would filter a message and send it to the beackend service only if it arrives from a pre-defined IP address range (192.168.1.*). If the message is recieved from any other IP address the message is dropped. This type of IP based filtering can be applied to secure a backend service from unauthorized access.

Using WSO2 ESB to modify messages with text content

WSO2 ESB provides 1st class support to SOAP and REST message formats. The WSO2 ESB is also capable of mediating messages with plain text contents. This can be done using a script mediator. You can read more about the script mediator from this link[1]. For this scenario I would be sending a text payload over HTTP. The ESB would extract the message payload and perform text manipulation using the script mediator and send the modified payload to the backend service. The script used in the script mediator is Javascripts. The following diagram illustrates the message flow.

Given below is a sample synapse configuration for the scenario. In the example below HTTP POST with a payload “Text send by Nadeesha” is sent to the ESB, which would be replaced as “Text from Nadeesha” and sent to the backend service.

The same functionality can also be done using a class mediator where by a Java class can be written to perform the same task.