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.
Enter ESBDataMappingProject as the name. Make sure the Connector Exporter Project option is not selected.
Click Finish.
You can see the following project files created in the Project Explorer tab:
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.
Select Create A New API Artifact, and then click Next as shown below.
Enter FoodMenuConversion as the name for the Synapse API Artifact, enter /convertMenu for Context and then click Finish as shown below.
Adding mediators
Drag and drop a Data Mapper mediator and a Respond mediator as shown below. We will configure the DataMapper later.
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.
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.
A new window opens with the graphical overview of the Datamapper.
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.
Select XML as the Resource Type as shown below. Click on file system and select the XML menu you just downloaded.
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.
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.
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.
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)
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.
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).
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.
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.
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
Change the method to POST and set the Media type to text/xml.
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 Tutorials, webinars or white papers for more technical information. Need support? We do deliver WSO2 Product Support, WSO2 Development Support, WSO2 Operational Support and WSO2 Training Programs.
