WSO2 Header Mediator

When building SOAP or HTTP services using the WSO2 Enterprise Integrator or WSO2 Enterprise Service Bus it is sometimes necessary to either remove or add specific headers to a message which is being transmitted. To make this easy, the WSO2 product has the <header> mediator to help you accomplish this task. In this blog, I will tell you how to use this mediator.

For each example in this blog I use the following input message:

<soapenv:Envelope xmlns_soapenv="http://schemas.xmlsoap.org/soap/envelope/">   <soapenv:Header/>
   <soapenv:Body>
      <headerData>Thisismyheaderdata</headerData>
   </soapenv:Body>
</soapenv:Envelope>

Http headers

Http headers are fairly simple to produce with the header mediator, you can choose the header name using the “name” property of the mediator.

As the “value” property the header value can be added and in the case of HTTP headers the “scope” property should be “transport”.

In the case of an “Accept” header it would look like this:

    <header name="Accept" value="text/xml" scope="transport"/>

SOAP headers

SOAP headers have a bit more variation in what’s possible so not everything is covered by the header mediator.

First, we will cover what is possible with the header mediator.

Adding a simple SOAP header can be accomplished using something like the following header mediator configuration:

  <header scope="default">
     <myHeaderName >
          Iwanttosendthisheader
     </myHeaderName>
  </header>

This is the result:

<?xml version='1.0' encoding='utf-8'?>
<soapenv:Envelope xmlns_soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <soapenv:Header>
      <myHeaderName >
          Iwanttosendthisheader
      </myHeaderName>
    </soapenv:Header>
    <soapenv:Body/>
</soapenv:Envelope>

As shown above this will of course result in a hardcoded header, for something more dynamic you can use both (regular and synapse) xpath functionalities provided by the ESB.

For example:

1. Grabbing data from the incoming message element “headerData”
   <header xmlns_y="https://www.yenlo.com"  expression="//headerData" name="y:header" scope="default"/>
2. Using Synapse xpath functionality to retrieve data from a property called “headerData”
   <header xmlns_y="https://www.yenlo.com"  expression="$ctx:headerData" name="y:header" scope="default"/>
3. Or a combination of both where we specifically retrieve headerData from the body of the message.
       <header xmlns_y="https://www.yenlo.com" expression="$body/headerData" name="y:header" scope="default"/>

Culminating into the following message (the headerData is also in the body as we did not change the initial incoming message):

<?xml version='1.0' encoding='utf-8'?>
<soapenv:Envelope xmlns_soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <soapenv:Header>
        <y:header xmlns_y="https://www.yenlo.com">
         Thisismyheaderdata
        </y:header>
    </soapenv:Header>
    <soapenv:Body>
        <headerData>Thisismyheaderdata</headerData>
    </soapenv:Body>
</soapenv:Envelope> 

More info about synapse xpath functionality can be found here.

Apart from dynamically adding data it is also possible to add more complex XML constructions inside the header if necessary.

<header>
    <m:complexHeader xmlns_m="https://www.yenlo.com">
        <subPartOne expression="Some expression"/>
        <subPartTwo value="Some value"/> 
   </m:complexHeader>
</header>

As I mentioned earlier, there are things the header mediator doesn’t support. This is the case when there is a need for dynamic headers inside a complex xml structure. Below there is an example shown where a security header UsernameToken needs to be filled, this can be done using the script mediator.

Within the script mediator a <![CDATA[some stuff]]> block is used because we need to create xml elements, the CDATA block functions to sure that they aren’t interpreted as XML so the script can be executed.

To add the header the script mediator first retrieves the username and password from their specific properties. In this case the password is retrieved from the secure vault within the ESB. For more information about the secure vault I can refer you to this blog, written by my colleague Jan Timmerman.

<property value="myUserName" name="BackendUser" scope="default" type="STRING"/>

<property expression="wso2:vault-lookup(SomePasswordKey)" name="BackendPassword" scope="default" type="STRING"/>

<script language="js">
<![CDATA[var password = mc.getProperty("BackendPassword");
 var username = mc.getProperty("BackendUser");
 mc.addHeader(false,
<Security >
<UsernameToken  >
<Username >
{username}
</Username>
<Password >
{password}
</Password>
</UsernameToken>
</Security>);]]>
</script>

The resulting message looks as follows:

<soapenv:Envelope xmlns_soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Header>
      <Security soapenv_mustUnderstand="0" >
         <UsernameToken>
            <Username>BackendUserPropertyData</Username>
            <Password>BackendPasswordPropertyData</Password>
         </UsernameToken>
      </Security>
   </soapenv:Header>
   <soapenv:Body>
      <headerData>Thisismyheaderdata</headerData>
   </soapenv:Body>
</soapenv:Envelope>

This concludes a showcase of the functionalities of the header mediator. I hope this post helps some people along with their ESB/EI projects! For any remarks or questions don’t hesitate to place a comment below.

Yenlo is the leading, global, multi-technology integration specialist in the field of API-management, Integration technology and Identity Management. Known for our strong focus on best-of-breed hybrid and cloud-based iPaaS technologies.

Yenlo is the product leader and multi-award winner in WSO2, Boomi, MuleSoft and Microsoft Azure technologies and offers best-of-breed solutions from multiple leading integration vendors.