This documentation is for WSO2 Enterprise Integrator version 6.4.0 . View documentation for the latest release in the 6.x.x family and the latest release in the 7.x.x family.
Transforming Message Content - WSO2 Enterprise Integrator 6.4.0 - WSO2 Documentation

All docs This doc
||
Skip to end of metadata
Go to start of metadata

Message transformation is necessary when the message format sent by the client is different from the message format expected by the back-end service. The Message Translator architectural pattern in the ESB of WSO2 Enterprise Integrator (WSO2 EI) describes how to translate from one data format to another.

In this tutorial, you send a request message to a back-end service where the payload is in a different format when compared to the request payload expected by the back-end service. The Data Mapper mediator in the ESB is used to transform the request message payload to the format expected by the back-end service.

See the following topics for a description of the concepts that you need to know when creating ESB artifacts:

Before you begin,

  1. Install Oracle Java SE Development Kit (JDK) version 1.8.* and set the JAVA_HOME environment variable.
  2. Download the product installer from here, and run the installer.
    Let's call the installation location of your product the <EI_HOME> directory. This is located in a place specific to your OS as shown below:
    OSHome directory
    Mac OS/Library/WSO2/EnterpriseIntegrator/6.4.0
    WindowsC:\Program Files\WSO2\EnterpriseIntegrator\6.4.0\
    Ubuntu/usr/lib/wso2/EnterpriseIntegrator/6.4.0
    CentOS/usr/lib64/EnterpriseIntegrator/6.4.0
  3. Select and download the relevant WSO2 EI tooling ZIP file based on your operating system from here and then extract the ZIP file. 
    The path to this folder will be referred to as <EI_TOOLING> throughout this tutorial

    Getting an error message? See the troubleshooting tips given under Installing Enterprise Integrator Tooling.

  4. If you did not try the Routing Requests Based on Message Content tutorial yet, open the WSO2 EI Tooling environment, click File, and then click Import. Next, select Existing WSO2 Projects into workspace under the WSO2 category, click Next and upload the pre-packaged project. This contains the configurations of the Routing Requests Based on Message Content tutorial so that you do not have to repeat those steps.
  5. Download the MSF4J service from here and copy the JAR file to <EI_HOME>/wso2/msf4j/deployment/microservices folder. The back-end service is now deployed in the MSF4J profile of WSO2 EI.

Let’s assume this is the format of the request sent by the client:

{
  "name": "John Doe",
  "dob": "1940-03-19",
  "ssn": "234-23-525",
  "address": "California",
  "phone": "8770586755",
  "email": "johndoe@gmail.com",
  "doctor": "thomas collins",
  "hospital": "grand oak community hospital",
  "cardNo": "7844481124110331",
  "appointment_date": "2017-04-02"
}

However, the format of the message must be as follows to be compatible with the backend service.

{
  "patient": {
    "name": "John Doe",
    "dob": "1990-03-19",
    "ssn": "234-23-525",
    "address": "California",
    "phone": "8770586755",
    "email": "johndoe@gmail.com"
    "cardNo": "7844481124110331"
  },
  "doctor": "thomas collins",
  "hospital": "grand oak community hospital"
  "appointment_date": "2017-04-02"
}

The client message format must be transformed to the back-end service message format within the In sequence.

Let's get started!

This tutorial contains the following sections:

Creating the deployable artifacts

The Data Mapper mediator transforms the message within the In sequences. The Data Mapper mediator is a data mapping solution that can be integrated into a mediation sequence. It converts and transforms one data format to another, or changes the structure of the data in a message. 

  1. In WSO2 EI Tooling, add a Data Mapper mediator just after the Property mediator in the In Sequence of the API resource.
    add the data mapper mediator

  2. Double-click the Data Mapper mediator icon and provide the following name for the data mapping configuration file that will be created.

    • Configuration Name: RequestMapping

    The SampleServicesRegistry project is created at the time of creating the ESB Solution project and will get auto-picked here.

    Click OK. You view the data mapping editor.

  3. Create a JSON file (e.g., input.json) by copying the following sample content of the request message sent to the API Resource, and save it in your local file system.

    { "name": "John Doe",
      "dob": "1990-03-19",
      "ssn": "234-23-525",
      "address": "California",
      "phone": "8770586755",
      "email": "johndoe@gmail.com",
      "doctor": "thomas collins",
      "hospital": "grand oak community hospital",
      "cardNo": "7844481124110331",
      "appointment_date": "2025-04-02"
    }

    You can create a JSON schema manually for input and output using the Data Mapper Diagram editor.

  4. Right-click on the top title bar of the Input box and click Load Input as shown below. 

  5. Select JSON as the Resource Type as shown below.

  6. Click the file system link in Select resource from, select the JSON file (i.e., input.json) you saved in your local file system in step 5, and click Open
    You view the input format loaded in the Input box in the editor as shown below. 

    the input format 

  7. Create another JSON file (e.g., out put.json ) by copying the following sample content of the request message expected by the backend service, and save it in your local file system.  

    {
      "patient": {
        "name": "John Doe",
        "dob": "1990-03-19",
        "ssn": "234-23-525",
        "address": "California",
        "phone": "8770586755",
        "email": "johndoe@gmail.com"
      },
      "doctor": "thomas collins",
      "hospital": "grand oak community hospital",
      "appointment_date": "2025-04-02"
    }
  8. Right-click on the top title bar of the Output box and click Load Output as shown below. 
  9. Select JSON as the resource type.
  10. Click the file system link in Select resource from, select the JSON file you saved in your local file system in step 7, and click Open.  
    You view the input format loaded in the Output box in the editor as shown below. 
    the output box

    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 value
  11. Do the mapping by dragging arrows from field values in the input box to the relevant field values in the output box. The final mapping is as follows:
    mapping the input and output
  12. Save and close the configuration.

  13. Go back to the Design View of the API Resource and select the Data Mapper Mediator and edit the following in the Properties tab:

    • Input Type: JSON
    • Output Type: JSON

  14. Save the REST API configuration.

    REST API configuration

We are now ready to package and deploy the C-App and send the request.

Packaging the artifacts

Since we created a new Registry Resource project, this will need to be packaged into our existing C-App.

Package the C-App names SampleServicesCompositeApplication project with the artifacts created. 

Ensure the following artifact check-boxes are selected in the Composite Application Project POM Editor.

  • SampleServices
    • HealthcareAPI
    • ClemencyEP
    • GrandOakEP
    • PineValleyEP
  • SampleServicesRegistry

Starting the ESB profile and deploying the artifacts

Assuming you have already added a server for the ESB profile in Eclipse, on the Servers tab, expand the WSO2 Carbon server, right-click SampleServicesCompositeApplication, and choose Redeploy. The Console window of the ESB profile will indicate that the CApp has been deployed successfully.

Starting the MSF4J profile

To be able to send requests to the back-end service (which is an MSF4J service deployed in the MSF4J profile), you need to first start the MSF4J runtime:

  1. Open a terminal and navigate to the <EI_HOME>/wso2/msf4j/bin directory.
  2. Start the runtime by executing the MSF4J startup script as shown below.

    Open a terminal and execute the following command:

    wso2ei-6.4.0-msf4j

    Go to Start Menu -> Programs -> WSO2 -> Enterprise Integrator 6.4.0 MSF4J. This will open a terminal and start the MSF4J profile.

The Healthcare service is now active and you can start sending requests to the service.

Sending requests to the ESB

  1. Create a JSON file names request.json with the following request payload.

    {
    "name": "John Doe",
    "dob": "1990-03-19",
    "ssn": "234-23-525",
    "address": "California",
    "phone": "8770586755",
    "email": "johndoe@gmail.com",
    "doctor": "thomas collins",
    "hospital": "grand oak community hospital",
    "cardNo": "7844481124110331",
    "appointment_date": "2025-04-02"
    }
  2. Open a command line terminal and execute the following command from the location where request.json file you created is saved:

    curl -v -X POST --data @request.json http://localhost:8280/healthcare/categories/surgery/reserve --header "Content-Type:application/json"

    This is derived from the URI-Template defined when creating the API resource.

    http://<host>:<port>/categories/{category}/reserve

    You will see the response as follows:

    {"appointmentNumber":1,
      "doctor":
           {"name":"thomas collins",
            "hospital":"grand oak community hospital",
            "category":"surgery","availability":"9.00 a.m - 11.00 a.m",
            "fee":7000.0},
      "patient":
          {"name":"John Doe",
           "dob":"1990-03-19",
           "ssn":"234-23-525",
           "address":"California",
           "phone":"8770586755",
           "email":"johndoe@gmail.com"},
      "fee":7000.0,
      "confirmed":false}

You have now explored how the ESB profile of WSO2 EI can receive a message in one format and transform it into the format expected by the backend service using the Data Mapper mediator.

  • No labels