WSO2 ESB - Data Mapper Mediator

Scenario:

Tools:

• WSO2 ESB 5.0.0
• WSO2 Developer Studio ESB Tool 5.0.0

Creating the ESB configuration project

1. 1. Open the WSO2 Developer Studio ESB Tool.

1. 2. Right click on the Project Explorer area, click New, and then click  ESB Solution Project 
2. 3. Enter a name for the project, and untick Create Connector Exporter Project (since you do not need Connectors in your configuration)  in the following wizard page.
   
   

        4. click Finish.You view the following project files created in the Project Explorer tab.

1. 
   5. Right click DataMappingExample project workspace file, click New, and then click REST API, to create a new REST API project in WSO2 ESB.
2. 6. Select Create A New API Artifact, and then click Finish as shown below.
3. 
   7. Enter a name for the Synapse API Artifact, enter /convertMenu for Context to configure the REST API project to listen for POST requests on the /convertMenu URL, and then click Finish  as shown below.
4. 
   8. Drag and drop a Data Mapper mediator and a Respond mediator as shown below. 
5. 
   9. 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. 
6. 
   
   
7. 10. Double click on the Data Mapping mediator. You can see a dialog box to create a registry resource project.
8. 
   
9. 11. Enter a name for the configuration, and point the Registry Resource project to save it.
10. 
    
11. 12. This configuration name is the prefix used for the configuration files that you deploy to the ESB server related to the Data Mapper. Since you created an ESB Solution project, it directly points you to that project to save in it. Otherwise, you need to click the Create new project link, to create a new Registry Resource project and then point to it.
1. 
   
   
12. 13. Click  OK. You view the following Data Mapper diagram editor in the new WSO2 Data Mapper Graphical perspective. 
13. 
14. 
    
15. 14. Create an XML file by copying the following sample content of a food menu and save it in your local file system.

1. 
   

1. Use this sample XML message to load the input format to the Data Mapper editor.   

1. <?xml version="1.0" encoding="UTF-8"?>
   <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>

2. 14. Right-click on the top title bar of the Input box and, click Load Input. The operation palettes that appear on the left-hand side allows you to provide the input message format to begin the mapping
   • 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. 
3. 
   
15. Click the file system link in Select resource from, select the XML file you saved in your local file system and click Open.  
You view the input format loaded in the Input box in the editor.
4. 
1. 
   

   Select XML as the Resource Type.
5. 16. Create another XML file by copying the following sample content of a food menu, and save it in your local file system.
6. Use this sample XML message to load the output format to the Data Mapper editor. 
7. 
   

9. <?xml version="1.0" encoding="UTF-8"?>
   <menu>
      <item>
         <name>Belgian Waffles</name>
         <price>$5.95</price>
         <calories>650</calories>
         <orgin>Belgian</orgin>
         <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</orgin>
         <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</orgin>
         <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</orgin>
         <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</orgin>
         <veg>false</veg>
         <description>Two eggs, bacon or sausage, toast, and our ever-popular hash browns</description>
      </item>
   </menu>

11. 17. Right-click on the top title bar of the Output box and, click   Load Output  as shown below . The operation palettes that appear on the left-hand side allows you to provide the output message format.
    Click the file system link in Select resource from, select the XML file you saved in your local file system, and click Open.  You view the input format loaded in the Output box in the editor as shown below.

14. 18. Check the Input and Output boxes with the sample messages, to see if the element types (Ex:Arrays, Objects and Primitive values) are correctly identified or not. Following signs will help you to identify them correctly. 
15. {} - represents object elements
16. [] - represents array elements
17. <> - represents primitive field values
18. A - represents XML attribute values
19. 
    
20. 19. Do the mapping as preferred using operators as shown in the example below.
21. You can only connect primitive data values such as Strings, numbers, boolean and etc. You cannot map Array and object values.
22. 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.13) + 6.75)
23. 
    
24. 
25. 
    
26. 20. Press Ctrl+S keys in each tab, to save all the configurations

Deploying the configurations

1. 1. 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.
2. 2. Open the WSO2 Developer Studio ESB Tool.
3. 3. Expand the C-APP project the was created when you created the ESB solution project (Ex: DataMapperExampleCompositeApplication) and double-click on the POM file. You view the following screen to select project files into the C-APP.
4. Configuration: Script file that is used to execute the mapping.
5. Input schema: JSON schema which represents the input message format.
6. Output schema: JSON schema which represents the output message format.
7. 
   
8. 4. You need to refresh the screen to view the registry resource files. Once you refresh the screen, you can see all the artifacts in the workspace.
9. Select the REST API file and the three registry resource files containing the mapping configuration, input schema, and output schema.
10. 
11. 5. Click on the Data Mapper mediator.  You can see 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).
12. 
    
13. 
14. 
    
15. 6. To Export as a C-APP right click on the DataMapperExampleCompositeApplication and select export. Then you can see below dialog box.
    
    Select Composite Application Archive [CAR] and click next.
16. 
    
    
17. 7.  Give export destination and click finish.
18. 8. Go to ESB management console (https://localhost:9443/carbon/).
19. 9. Go to carbon Applications in main tab and select Add. Click Choose File and give the C-App which we have already exported and finally click Upload.
    
20. 
    
21. 
    

Invoking the created REST API

1. 1. Open Postman REST client.
2. 2. Enter the following details to create the client message, enter the content of the XML file as the payload in the text area provided, and click send as below.

1. • URL:  http://<ESB_HOST>:<ESB_PORT>/convertMenu (Ex: http://172.17.0.1:8280/convertMenu)
   • Method: POST
   • Body: raw xml/application
• Message: Enter the input
2. 
   
3. 
4. 
   
5. You view the expected JSON message received as shown below. 
6. 
   
7. 

WSO2 Admin Services.

WSO2 products are internally manage by using SOAP Web services known as Admin Services. WSO2 products come with a management console UI, which communicates with these admin services to facilitate administration capabilities through the UI.

A service in WSO2 products is defined by the following components:

• Service component: provides the actual service
• UI component: provides the Web user interface to the service
• Service stub: provides the interface to invoke the service generated from the service WSDL

There can be instances where you want to call back-end Web services directly. For example, in test automation, to minimize the overhead of having to change automation scripts whenever a UI change happens, developers prefer to call the underlying services in scripts. 

Discovering WSO2 Admin Services:

By default, the WSDLs of admin services are hidden from consumers. So we are going to discover them using OSGI console. Please follow below steps: 

1. Set the <HideAdminServiceWSDLs> element to false in <PRODUCT_HOME>/repository/conf/carbon.xml file.

2. Go to <PRODUCT_HOME>/bin/  folder and start the WSO2 product as follows,

• In Linux environment:  sh wso2server.sh -DosgiConsole
• In Windows environment:  wso2server.bat -DosgiConsole

3. When the server is started, hit the enter/return key several times to get the OSGI shell in the console.
4. In the OSGI shell, type: listAdminServices
5. The list of admin services of your product are listed as follows:

6. To see the WSDL of any admin service, select the admin service's URL and paste it in your browser with ?wsdl at the end. For example: https://SL-PRABODP:8243/services/InboundAdmin?wsdl Note : Replace SL-PRABODP with your local IP or localhost. Then you can see it as below And also you can create a soap project in SoapUI as well Then you can see as below in soapUI Then you can check all available functionalities using this soapUI

Invoking WSO2 admin service

WSO2 Admin services are secured using common types of security protocols. ex:

• HTTP basic auth
• WS-Security username token
• session based authentication

For example,  UserAdmin service is secured with HTTP basic auth. to invoke a service, follow these steps:

1. Authenticate yourself and get the session cookie.
2. Generate client stubs to access the back-end web services.

How to generate client stubs:

There are several methods / tools to generate client stubs:

• Using Axis2 client API - I will explain in this blog.
• Using SoapUI (4.5.1 or later)
• Using wsdl2java

Generate Client stubs using Axis2 client API

First you need to create AdminService.wsdl file for which admin service you need to create stubs. For an example here i'm going to create for stubs for InboundAdmin service.

wsdl file for InboundAdmin service: 

To create a client using ADB execute the following steps:

1. Download and unpack the Apache Axis2 Standard Distribution.

2. Create the client stub with the following command:

%AXIS2_HOME%\bin\wsdl2java -uri InboundAdmin.xml -p wso2.adminservices.stubs -d adb -s

Assuming that you have InboundAdmin.xml file on your current directory.

wso2.adminservices.stubs - you can change this as your package name.

Generated stubs files

3. Create the client (for example Client.java), a java application that uses the generated stub, and save it in wso2/adminservices/inboundadmin directory.

4. Build the client by typing: ant jar.client

5. Assuming you have a corresponding service, run the client by adding the generated InboundAdmin-test-client.jar file located in build/lib to the classpath and type: java wso2.adminservices.inboundadmin.Client

Sample reference for Client.java