How to Use WSO2 Data Mapping Mediator in ESB

Please find the updated post from here

https://nuwanpallewela.wordpress.com/2016/07/16/how-to-use-wso2-data-mapping-mediator-in-esb-updated/

INTRODUCTION

WSO2 data mapper is a data mapping solution that convert and transform one format of data to a different format. It provides a WSO2 Developer Studio based tool to create the graphical mapping configuration and generate the files needed to execute the mapping configuration by the WSO2 Data mapper engine as shown in the below diagrams. As the this is really useful feature in message mediation, WSO2 ESB comes with a data mapper mediator which can be integrate into a mediation sequence since WSO2 ESB 5.0.0.

PREREQUISITES

First we need to have the data mapper mediator supported ESB distribution. WSO2 ESB 5.0.0 is the distribution packed with data mapper mediator. You can download alpha pack from here.

And also we need to have a data mapping editor supported Developer Studio ESB Tool. You can follow this article to install the WSO2 Developer Studio ESB Tool 5.0.0.

OVERVIEW

This post will focus on how to create a configuration with Data Mapper mediator. So I will chose a very simple ESB configuration with only a data mapper mediator and respond mediator to check the converted message.

 

Our Employee message will be a xml message and we will send a JSON response to the client. We will use the Postman as out client to send the requests.

Creating Data Mapping Configuration

Lets create a ESB Configuration project named “DataMapperEmployeeToEngineerConfig” from the WSO2 Developer Studio ESB Tool and create a Rest API as follows.

Then we can add the Data Mapper Mediator in to the API resource and a Respond mediator to send the converted message back to client.

Then double click on the data mapper mediator to configure the mapping. It will open a dialog box asking to create a Registry Resource project. This is to save and deploy the required configuration and schema files in the ESB Server to read at the runtime when message conversion happens. So name the configuration file as “EmployeeToEngineerMapping” and registry resource project as “EmployeeToEngineerRegistryResource”.It will open the Data Mapper Diagram Editor where we should do the mapping.

But first we need to complete the API configuration. So go back to ESB Diagram editor with the API Resource and click on the Data Mapper mediator. You will see the configurations of the Data Mapper mediator on the property table.

As you can see there are five configurations listed. They are

• Input Type : Expected input message type (xml/json/csv)
• Output Type: Target Output message type (xml/json/csv)
• Configuration : This file contain the script file used to execute the mapping
• Input Schema: JSON schema which represent input message format
• Output Schema: JSON schema which represent the output message format

As we are going to convert xml message to json message change the output type to json.

And then click on the API resource and  go to the property table. And change the configurations to following.

• Url Style : URL_MAPPING
• URL-Mapping : /employeetoengineer
• Methods : POST

Save the API configuration. Now lets move to data mapper editor to create the mapping from employee message to engineer.

First we need to load the input and output message formats into editor. For the right click on the input box title bar and select load input schema command.

Then following dialog box appears and you will have multiple ways to load the input message format.

You can select the resource type as XML, JSON, XSD or JSONSCHEMA.

If you selects XML, you can load a sample xml message you expect and WSO2 Data Mapper Editor will generate the JSON schema to represent the xml accoring to the WSO2 Data Mapper Schema specification.

Same as for XML, if you select  JSON as resource type you can load a sample JSON message.

If you have a xsd schema which defines you xml message format, you can select the resource type as XSD and load the xsd file.

And also if you have the JSON schema for your message according to the WSO2 Data Mapper schema specification you can load it by selecting resource type as JSON schema.

Lets use a sample xml message to load input format to the data mapper editor. Use following xml as the sample input.

<?xml version='1.0' encoding='utf-8'?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body><ns1:employees xmlns:ns1="http://wso2.employee.info" xmlns:ns2="http://wso2.employee.address">
<ns1:employee>
<ns1:firstname>Mike</ns1:firstname>
<ns1:lastname>Jhonson</ns1:lastname>
<ns2:addresses>
<ns2:address location="home" >
<ns2:city postalcode="30000">KS</ns2:city>
<ns2:road>main rd</ns2:road>
</ns2:address>
<ns2:address location="office" >
<ns2:city postalcode="10003">NY</ns2:city>
<ns2:road>cross street</ns2:road>
</ns2:address>
</ns2:addresses>
</ns1:employee>
<ns1:employee>
<ns1:firstname>Patric</ns1:firstname>
<ns1:lastname>Jane</ns1:lastname>
<ns2:addresses>
<ns2:address location="home" >
<ns2:city postalcode="60000" >Melborne</ns2:city>
<ns2:road>park street</ns2:road>
</ns2:address>
<ns2:address location="office" >
<ns2:city postalcode="10003">NY</ns2:city>
<ns2:road>cross street</ns2:road>
</ns2:address>
</ns2:addresses>
</ns1:employee>
<ns1:employee>
<ns1:firstname>Thelesa</ns1:firstname>
<ns1:lastname>Lisbon</ns1:lastname>
<ns2:addresses>
<ns2:address location="home" >
<ns2:city postalcode="60000">Madrid</ns2:city>
<ns2:road>Palace street</ns2:road>
</ns2:address>
<ns2:address location="office" >
<ns2:city postalcode="10003">NY</ns2:city>
<ns2:road>cross street</ns2:road>
</ns2:address>
</ns2:addresses>
</ns1:employee>
</ns1:employees>
</soapenv:Body>
</soapenv:Envelope>

And use following JSON message as the sample output and load output message format to data mapper editor.

{
"engineers":{
"engineerList":[
{
"fullname":"Mike Jhonson",
"addresses":{
"address":[
{
"location":"home",
"city":{
"postalcode":30000,
"text":"AA"
},
"road":"BB"
},
{
"location":"office",
"city":{
"postalcode":10003,
"text":"BB"
},
"road":"CC"
}
]
}
},
{
"fullname":"Mike Jhonson",
"addresses":{
"address":[
{
"location":"home",
"city":{
"postalcode":30000,
"text":"AA"
},
"road":"BB"
},
{
"location":"office",
"city":{
"postalcode":10003,
"text":"BB"
},
"road":"CC"
}
]
}
}
]
}
}

Now the editor will have the input and output message formats as bellow.

Now we can specify how the output message should build by using the input message. We have several operations given in the operations pallet in the left side.

Click on the operator and it will come to the editor. Then construct the mapping as the following diagram.

You can only connect primitive data values such as Strings, numbers, boolean and etc. Array and object values can not be mapped.

• {}  – represent object elements
• []   – represent array elements
• <> – primitive field values
• A   – xml attribute values

After loading the message formats you have to observe whether the formats are correctly identified by the data mapper diagram editor.

Now save the all configurations. We can now deploy the created REST API in the ESB server and test our mapping.

Deploy the REST API in ESB Server

We can create a CAPP including the WSO2 synapse configurations and the registry resource files as below.

Start ESB server and add it to Developer Studio ESB Tool servers and deploy.

Then go to API’s list from the ESB management console and confirm the REST API invocation URL.

Invoke Created REST API

Open Postman and create the client message as follows.

• URL : http://192.168.1.3:8280/convert/employeetoengineer
• Method : POST
• Body : raw xml/application
• Message : Put the sample xml file without the soap envelope and body elements.

Send the message from Postman and you will receive the respond message but in the xml format. This is since though we converted the message to type json in the axis2 level we need to change the property “messageType” to “application/json” too.

So add a property mediator and configure the following parameters.

• Property Name : messageType
• Value : application/json
• Property Scope : axis2

Then redeploy the CAPP and send the employee message again from the Postman. Then you will receive the expected json message as follows.

{
"engineerList": [
{
"addresses": {
"address": [
{
"city": {
"postalcode": 30000,
"text": "KS"
},
"location": "home",
"road": "main rd"
},
{
"city": {
"postalcode": 10003,
"text": "NY"
},
"location": "office",
"road": "cross street"
}
]
},
"fullname": "Mike Jhonson"
},
{
"addresses": {
"address": [
{
"city": {
"postalcode": 60000,
"text": "MELBORNE"
},
"location": "home",
"road": "park street"
},
{
"city": {
"postalcode": 10003,
"text": "NY"
},
"location": "office",
"road": "cross street"
}
]
},
"fullname": "Patric Jane"
},
{
"addresses": {
"address": [
{
"city": {
"postalcode": 60000,
"text": "MADRID"
},
"location": "home",
"road": "palace street"
},
{
"city": {
"postalcode": 10003,
"text": "NY"
},
"location": "office",
"road": "cross street"
}
]
},
"fullname": "Thelesa Lisbon"
}
]
}

Now you have the basic end to end knowledge to develop a ESB configuration with a data mapper mediator. So you can try this and report the bugs and suggest improvements from the following link as JIRAs.

I will discuss more advanced discussion about how things work inside and mapping configuration is generated from the diagram which will help to understand the behavior of the data mapper and the limitations.

• esb
• wso2