WSO2 ESB - Mediator Catalog [ Documentation Index ]

WSO2 Enterprise Service Bus (ESB) Mediator Catalog

Mediators are the basic component of a mediation framework and the WSO2 ESB has a comprehensive set of mediators. This guide will walk you through the genral concept of mediation inside the WSO2 ESB and will also describe each and every mediator shipped with WSO2 ESB, one by one



Message mediation is a fundamental part of any ESB. WSO2 ESB achieves message mediation through it's mediators. ESB comes with a rich set of 30 plus mediators to support the most common mediation functionalities as well as advanced functionalities.

Built in mediator capabilities of ESB provide functionality to match incompatible protocols, data formats and interaction patterns across different resources. Data can be split, cloned, aggregated and enriched, allowing ESB to match the different capabilities of services. XQuery and XSLT allows rich transformations on the messages. Rule based message mediation allows user to cope with the uncertainty of business logic. Content based routing using XPath filtering is supported in different flavors, allowing users to get the most convenient configuration experience. Built in capability to handle transactions allows message mediation to be done transactionally inside the ESB. With the Eventing capabilities of ESB, EDA based components can be easily interconnected. With features like throttling and caching integrated in to the message mediation, powerful interconnections can be made, allowing ESB to be used in the front end of organizations SOA infrastructure.

ESB mediation framework is designed from the ground up to be extensible. Everyday users write their own custom mediators to facilitate their custom requirements.

Now let's briefly look at how the mediation framework works.

How does a mediator work?

A mediator is a full powered processing unit in ESB. In run-time it has access to all the parts of ESB along with the current message. Usually a mediator is configured using XML. Different mediators have their own XML configurations.

At the run-time a Message is injected in to the mediator with the ESB run-time information. Then this mediator can do virtually anything with the message. Here are some examples of mediator functionalities.

Wide range usage of mediators is visible through the above few examples.

Also mediators are considered as one of the main mechanisms for extending ESB. A user can write a mediator and put it in to ESB. This custom mediator and any other built in mediator will be exactly same from the API and the privileges.


Sequence is a List Mediator of the ESB. That means it can hold other mediators and execute them. It is a part of the core of ESB and message mediation cannot live without this mediator. When a message is delivered to a sequence, it sends the message through all it's child mediators.

There are two types of sequences.

In-line Sequences

<sequence name="string">other mediators</sequence>

In-line sequences has their child mediators defined inside the sequence itself.

Named Sequences

<sequence key="name"/>

Named sequences refer other sequences using a key. This allows re-using of sequences.

There are two predefined sequences. They are called "main" and "fault". If a user doesn't specify these two sequences in the configuration, default sequences will be created automatically.

Here are the default configurations for main and fault


  <syn:sequence name="main" xmlns:syn="">


  <syn:sequence name="fault" xmlns:syn="">
      <syn:log level="full">
      <syn:property name="MESSAGE" value="Executing default&quot;fault&quot; sequence"/>
      <syn:property name="ERROR_CODE" expression="get-property('ERROR_CODE')"/>
      <syn:property name="ERROR_MESSAGE" expression="get-property('ERROR_MESSAGE')"/>

All the messages that are not for proxy services, will be sent through the Main Sequence.

A sequence can have an error handler. Error handler is again another sequence. If an error occurs while executing a sequence, its error handler will be called. Every sequence has an error handler. If one isn't explicitly specified, fault sequence will be treated as the error handler.

How does a message comes to a mediator?

There are two operational modes in the ESB. They are message mediation and proxy services. Message mediation is all about mediators. Proxy services can use message mediation as well.

Message Mediation

A message comes to the main sequence of the ESB if the message is not for any of the proxy services defined in the ESB.

Then this message goes through each of the mediators inside the main sequence.

If the message is sent to an Endpoint from the main sequence, response message will also comes to the main sequence.

Response message will also go through every child mediator of main sequence

If an error occurs in a sequence, message will go through sequence's fault sequence.

Proxy Services

Proxy service can have 3 sequences. Depending on the message path these three sequences can be executed. All the three sequences are optional.

  1. In Sequence : A request message coming to a proxy service will go through this sequence if the sequence is specified.
  2. Out Sequence : A response message coming from the actual endpoint will go through this sequence if the sequence is specified.
  3. Fault Sequence : If an error occurs withing the proxy service operation, message will go through this sequence

As mentioned earlier, every sequence is a collection of mediators. A message delivered to a sequence will go through all its child mediators.

WSO2 ESB has a built in sequence editor which helps user to develop/edit sequences. The Sequence Editor Guide gives an introduction to the usage of the sequence editor. Following is the catalog of the built in mediators of WSO2 ESB.

The Mediator Catalog

Category Name Description
Core Send Send a message out
Log Logs a message
Property Set or remove properties associated with the message
Sequence Refer a sequence
Event Send event notifications to an event source
Drop Drops a message
Enrich Enriches a message
Enqueue Create a enqueue meadiator
Filter Filter Filter a messages using XPath, If else kind of logic
Out Inbuilt filter for choosing messages in ESB out path
In Inbuilt filter for choosing messages in ESB in path
Switch Filter messages using XPath, Switch logic
Router Route messages based on XPath filtering
Conditional Router Route messages based on 'Condition'
Validate Schema validation for messages
Transform XSLT XSLT transformations
XQuery XQuey
Header Sets or remove SOAP headers
Fault Create SOAP Faults
Rewrite Create a rewrite meadiator
Advanced Cache Evaluate messages based on weather the same message came to the ESB
Clone Clones a message
Iterate Splits a message
Aggregate Combines messages
Callout Blocking web services calls
Transaction Executes a set of mediators transactionally
Throttle Limit the number of messages
RMSequence Reliable messaging
DBReport Writes data to a database
DBLookup Retrieve information from a database
Rule Executes Rules
Entitlement Fine grain authorization
OAuth 2-legged OAuth support
Extension Class Create and execute a custom mediator
POJOCommand Executes a custom command
Script Executes a mediator written in a Scripting language
Spring Create a mediator managed by Spring
Smooks Create a smooks meadiator
Store Create Mediator to Store messages in a Message store