This is the latest release in the 6.x.x family. For EI 7.0.0, click here.

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 profile of WSO2 Enterprise Integrator (WSO2 EI) describes how to translate data from one 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 profile is used to transform the request message payload to the format expected by the back-end service.

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

Before you begin,

  • 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.6.0
    WindowsC:\Program Files\WSO2\EnterpriseIntegrator\6.6.0\
    Ubuntu/usr/lib/wso2/EnterpriseIntegrator/6.6.0
    CentOS/usr/lib64/EnterpriseIntegrator/6.6.0
  • Select the relevant WSO2 Integration Studio based on your operating system and download it from here.
    The path to this folder is referred to as <EI_TOOLING> throughout this tutorial.

    Getting an error message? See the troubleshooting tips given under Installing WSO2 Integration Studio.

  • If you did not try the Routing Requests Based on Message Content tutorial yet,
    1. Download the pre-packaged project that contains the configurations of the Routing Requests Based on Message Content tutorial.
    2. Open WSO2 Integration Studio, click File, and click Import.
    3. Next, expand the WSO2 category and select Existing WSO2 Projects into workspace, click Next, and upload the project file.

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": "[email protected]",
  "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": "[email protected]"
    "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 Integration Studio, add a Data Mapper mediator just after the Property mediator in the In Sequence of the API resource.

  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 that already exists in your project explorer will be selected by default.

  3. Click OK. View the data mapping editor:

  4. 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": "[email protected]",
      "doctor": "thomas collins",
      "hospital": "grand oak community hospital",
      "cardNo": "7844481124110331",
      "appointment_date": "2025-04-02"
    }

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

  5. Click Load Input File to open the Load Input dialog and select JSON as the Resource Type as shown below.

  6. Click file system, select the JSON file (i.e., input.json) you saved in your local file system, and click OK
    You can view the input format loaded in the Input box of the editor as shown below. 

    the input format 

  7. Create another JSON file (e.g., output.json ) by copying the following sample content of the request message expected by the back-end 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": "[email protected]"
      },
      "doctor": "thomas collins",
      "hospital": "grand oak community hospital",
      "appointment_date": "2025-04-02"
    }
  8. Click Load Output File to open the Load Output dialog and select JSON as the Resource Type as shown below.
  9. Click file system, select the JSON file (i.e., output.json) you saved in your local file system, and click OK
    You can view the output format loaded in the Output box of the editor as shown below.  

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

    • {} - represents object elements
    • [] - represents array elements
    • <> - represents primitive field values
    • A - represents XML attribute value
  10. 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:
  11. Save and close the configuration.

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

    • Input Type: JSON
    • Output Type: JSONInput and output can be tested as below. 

  13. Save the REST API configuration.

Packaging the artifacts

Since we created a new Registry Resource project, it needs to be packaged in the composite application project.

  1. Open the pom.xml file of the SampleServicesCompositeApplication project, which is already included in the project explorer.
  2. Select the artifact that needs to be included into the CAR file.

    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

If you do not already have an ESB server added to WSO2 Integration Studio, follow the instructions in the first tutorial.

If you have already added the ESB profile server and deployed SampleServicesCompositeApplication (in a previous tutorial):

  1. Go to the Servers tab and click  to start the server. 
  2. Right-click SampleServicesCompositeApplication and click Redeploy as shown below.

The server Console will indicate that the CApp has been redeployed successfully.

Starting the back-end service

Download and start the back-end service that will process appointment requests:

  1. Download the JAR file of the back-end service.
  2. Open a terminal and navigate to the location where your saved the back-end service.

  3. Execute the following command to start the service:

    java -jar Hospital-Service-JDK11-2.0.0.jar

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": "[email protected]",
    "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":"[email protected]"},
      "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 back-end service using the Data Mapper mediator.

  • No labels