Header Mediator:
The header mediator sets or removes a specified header from the current soap info-set. At the moment set header only supports simple valued headers.Syntax
<header name="qname" (value="literal" | expression="xpath") [action="set"]/> <header name="qname" action="remove"/>
The optional action attribute specifies whether the mediator should set or remove the header. If omitted, it defaults to a set-header.
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.
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 xmlns="https://www.yenlo.com"> 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 xmlns="https://www.yenlo.com"> 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:
- Grabbing data from the incoming message element "headerData"
<header xmlns:y="https://www.yenlo.com" expression="//headerData" name="y:header" scope="default"/>
- 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"/>
- 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>
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.
<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 xmlns="http://schemas.xmlsoap.org/ws/2002/04/secext"><UsernameToken xmlns="http://schemas.xmlsoap.org/ws/2002/04/secext">
<Username xmlns="http://schemas.xmlsoap.org/ws/2002/04/secext">{username}</Username><Password xmlns="http://schemas.xmlsoap.org/ws/2002/04/secext">{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" xmlns="http://schemas.xmlsoap.org/ws/2002/04/secext"> <UsernameToken> <Username>BackendUserPropertyData</Username> <Password>BackendPasswordPropertyData</Password> </UsernameToken> </Security> </soapenv:Header> <soapenv:Body> <headerData>Thisismyheaderdata</headerData> </soapenv:Body></soapenv:Envelope>