fb
WSO2 Enterprise Integrator 9 minutes

Mediation using the Data Mapper Mediator

Weit Hamersma
Weit Hamersma
Integration Consultant
Data mapping
Scroll

Data mappingThis sample demonstrates how to create a mapping configuration for different data formats using the Data Mapper mediator. It uses a simple WSO2 ESB configuration with only a Data Mapper mediator, and a Respond mediator to check the converted message. The input employee message in XML format, and the output engineer message in JSON format, which is sent to the client as the response.

Creating the ESB configuration project

Follow the steps below to create an ESB configuration project to contain the Data Mapping configurations using the WSO2 Developer Studio ESB Tool.

Open the Dashboard and select ESB Solution project.

WSo2 Developer Studio - ESB Project

Enter ESBDataMappingProject as the name. Make sure the Connector Exporter Project option is not selected.

ESB Solution Project

Click Finish.

You can see the following project files created in the Project Explorer tab:

Project explorer Data mapping

Creating the Food Menu Conversion API

Either right click ESBDataMappingProject workspace entry in the project explorer, click New, and then click REST API as shown below. or use the Dashboard to create a new REST API. Keep in mind that when using the dashboard, you need to store the API in the ESBDataMappingProject.

Project explorer Data mapping new

Select Create A New API Artifact, and then click Next as shown below.

New Synapse API

Enter FoodMenuConversion as the name for the Synapse API Artifact, enter /convertMenu for Context and then click Finish as shown below.

New Synapse API

Adding mediators

Drag and drop a Data Mapper mediator and a Respond mediator as shown below. We will configure the DataMapper later.

Developer Studio Dashboard

We are now going to add the resource to the API. Click on the API Resource, and then click on its Properties tab and select True as the value for the Post method as shown below, to create the API resource listening to POST requests. Also set Url Style to URL_MAPPING.

API Resource

Note that you cannot save the configuration yet. We must configure the data mapper first.

Configuring the DataMapper

Double click on the Data Mapping mediator, to configure it. Call the configuration FoodMapping and save in the ESBDataMappingProjectRegistry. Click OK to continue.

Data mapper configuration - create new configuration

A new window opens with the graphical overview of the Datamapper.

Developer studio dashboard - datamaper diagram

Use the breakfastmenu_DataMapper.xml file url, which you can download as the sample content of a food menu. Download this file and save it in your local file system, for instance on the desktop or downloads folder.

This is the contents of the file. Note that it is well-formed XML.

<breakfast_menu>
    <food>
        <name>Belgian Waffles</name>
        <price>$5.95</price>
        <description>Two of our famous Belgian Waffles with plenty of real
maple syrup</description>
        <calories>650</calories>
        <orgin>Belgian</orgin>
        <veg>true</veg>
    </food>
    <food>
        <name>Strawberry Belgian Waffles</name>
        <price>$7.95</price>
        <description>Light Belgian waffles covered with strawberries and whipped cream</description>
        <calories>900</calories>
        <orgin>Belgian</orgin>
        <veg>true</veg>
    </food>
    <food>
        <name>Berry-Berry Belgian Waffles</name>
        <price>$8.95</price>
        <description>Light Belgian waffles covered with an assortment of fresh berries and whipped cream</description>
        <calories>900</calories>
        <orgin>Belgian</orgin>
        <veg>true</veg>
    </food>
    <food>
        <name>French Toast</name>
        <price>$4.50</price>       
<description>Thick slices made from our homemade sourdough bread</description>
        <calories>600</calories>
        <orgin>French</orgin>
        <veg>true</veg>
    </food>
    <food>
        <name>Homestyle Breakfast</name>
        <price>$6.95</price>
        <description>Two eggs, bacon or sausage, toast, and our ever
popular hash browns</description>
        <calories>950</calories>
        <orgin>French</orgin>
        <veg>false</veg>
    </food>
</breakfast_menu>

Right-click on the top title bar of the Input box and, click Load Input as shown below. The operation palettes that appear on the left-hand side allows you to provide the input message format to begin the mapping.

Datamapper Load input

Select XML as the Resource Type as shown below. Click on file system and select the XML menu you just downloaded.

Load input - resource type

You can select one out of the following resource types, to load the input and output message formats to Data Mapper.

  • XML: to load a sample XML message and WSO2 Data Mapper Editor will generate the JSON schema to represent the XML according to the WSO2 Data Mapper Schema specification.
  • JSON: to load a sample JSON message.
  • CSV: to load a sample JSON/CSV message. For CSV you need to provide the column names as the first record.
  • XSD: to load an XSD schema file, which defines your XML message format.
  • JSONSCHEMA: to load a JSON schema for your message according to the WSO2 Data Mapper schema specification.
  • CONNECTOR: to map a message, which is an output of a Connector. Select the Connector Type in the Input box, and it will list down all available connectors. Then, select the operation from the menu that appears in front of Data Mapper mediator.

After selecting the breakfastmenu_DataMapper.xml file, you will see an input window like this.

Input datamapper

Now download the second XML file (breakfastmenu_DataMapper_2nd..xml)with a short sample from the bit.ly URL. Add the XML to the output window like with the input window.

Output datamapper

Note that the two samples look the same but are different. The differences lie in the tagnames and order of fields.

<menu>
    <item>
        <name>Belgian Waffles</name>
        <price>$5.95</price>
        <calories>650</calories>
        <orgin>Belgian</origin>
        <veg>true</veg>
        <description>Two of our famous Belgian Waffles with plenty of real maple syrup</description>
    </item>
    <item>
        <name>Strawberry Belgian Waffles</name>
        <price>$7.95</price>
        <calories>900</calories>
        <orgin>Belgian</origin>
        <veg>true</veg>
        <description>Light Belgian waffles covered with strawberries and whipped cream</description>
    </item>
    <item>
        <name>Berry-Berry Belgian Waffles</name>
        <price>$8.95</price>
        <calories>900</calories>
        <orgin>Belgian</origin>
        <veg>true</veg>
        <description>Light Belgian waffles covered with an assortment of fresh berries and whipped cream</description>
    </item>
    <item>
        <name>French Toast</name>
        <price>$4.50</price>
        <calories>600</calories>
        <orgin>French</origin>
        <veg>true</veg>
        <description>Thick slices made from our homemade sourdough bread</description>
    </item>
    <item>
        <name>Homestyle Breakfast</name>
        <price>$6.95</price>
        <calories>950</calories>
        <orgin>French</origin>
        <veg>false</veg>
        <description>Two eggs, bacon or sausage, toast, and our ever
popular hash browns</description>
    </item>
</menu>

Check the Input and Output boxes with the sample messages, to see if the element types (i.e. (Arrays, Objects and Primitive values) are correctly identified or not. Following signs will help you to identify them correctly.

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

Do the mapping as preferred using operators as shown in the example below.

This entails the following mappings:

  • A Constant with a value of 1.12 (shown as “1.12”) (use Constant from Common palette, right-click on the created element and select Configure Constant Operator to set the value. See figure below)
  • A Constant with a value of 6.75 (shown as “6.75”)
  • An Uppercase connection between name (I) and name(O)
  • Direct connections (Data Mapper Links) between price, description, origin and veg;
  • Multiply, Add and Round boxes with links connecting input and output.

Developer studio configure constant operator

Note: You can only connect primitive data values such as Strings, numbers, booleans, etc. You cannot map Array and object values.

The mapping done in the below example is that, name is mapped via uppercase operator and calories undergoes a mathematical calculation to get the output as follows:

output calories =Round((calories*1.12) + 6.75)

Mapping example

Press Ctrl+S keys in each tab, to save all the configurations.

Deploying the configurations

After creating the Data Mapper configurations, follow the steps below to deploy the created REST API and the configurations in the WSO2 ESB server by including them in a C-App.

Expand the C-App project that was created when you created the ESB Solution project (i.e. ESBDataMappingProjectCompositeApplication) and double-click on the POM file. You will see the following screen to select project files into the C-App. Select all files and press Select All.

ESB Data Mapping Project Composite Application

Click on the Data Mapper mediator in the graphical representation of the FoodMenuConversion API. You view the following in the Properties tab of the Data Mapper mediator configuration as shown below.

  • Configuration: Script file that is used to execute the mapping.
  • Input Schema: JSON schema, which represents the input message format.
  • Output Schema: JSON schema, which represents the output message format.
  • Input Type: Expected input message type (xml/json/csv).
  • Output Type: Target output message type (xml/json/csv).

DataMapperMediationProperties

If your mapping fails during runtime, check if the input type and output type are set correctly in the mediator configuration.

Start WSO2 ESB server within Developer Studio. If no server is available, click the link to create a new server. Start the server if not started. Add the CAR file to the server with right-click on the server / Add or Remove.

  • To create a new server, enter the URL of WSO2 ESB for Server URL and click Finish as shown below.
    You see the WSO2 ESB server added in the Servers tab as shown below.
  • After adding the CAR file, you see the C-App added to the WSO2 ESB server as shown below.

ESB Data Mapping add CAR file

Log in to the WSO2 ESB Management Console using the following URL and admin/admin credentials: https://localhost:9443/carbon

Click Main and then click APIs in the Service Bus menu. You view the deployed REST API invocation URL as shown below.

Deployed APIs

Invoking the created REST API

You can use SoapUI, Postman or Advanced Rest Client to test invoking the created REST API. We show the setup for SoapUI.

Start SoapUI and create a new Rest Project

Enter http://localhost:8280/convertMenu (see the API definition above) as URL

New REST Project

Change the method to POST and set the Media type to text/xml.

Datamapping request 1

Copy the first XML to the payload area and click on send.

See the response. The layout is different, and the calories have been calculated according to the configured rule.

If you have any questions about this blogpost contact us via the comments section below. View also our WSO2 Tutorialswebinars or white papers for more technical information. Need support? We do deliver WSO2 Product SupportWSO2 Development SupportWSO2 Operational Support and WSO2 Training Programs.