Message Transformation

What you'll build

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 WSO2 Micro Integrator describes how you can translate one data format to another.

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

Let’s assume that the client sends the following message format:

{
  "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 compatible with the back-end service is as follows:

{
  "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's message format within the In sequence.

Let's get started!

Step 1: Set up the workspace

Set up WSO2 Integration Studio as follows:

  1. Download the relevant WSO2 Integration Studio based on your operating system. The path to the extracted/installed folder is referred to as MI_TOOLING_HOME throughout this tutorial.
  2. If you did not try the Routing Requests Based on Message Content tutorial yet:
    1. Download the pre-packaged project.
    2. Open WSO2 Integration Studio and go to File -> Import.
    3. Select Existing WSO2 Projects into workspace under the WSO2 category, click Next, and then upload the pre-packaged project.

Optionally, you can set up the CLI tool for artifact monitoring. This will later help you get details of the artifacts that you deploy in your Micro Integrator.

  1. Go to the WSO2 Micro Integrator website.
  2. Click Download -> Other Resources and click CLI Tooling to download the tool.
  3. Extract the downloaded ZIP file. This will be your MI_CLI_HOME directory.
  4. Export the MI_CLI_HOME/bin directory path as an environment variable. This allows you to run the tool from any location on your computer using the mi command. Read more about the CLI tool.

Step 2: Develop the integration artifacts

Let's update the API resource that was used in the previous tutorial by adding a Data Mapper mediator to configure the data transforrmation logic.

  1. In WSO2 Integration Studio, open the HealthcareAPI and 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 specify the following details:

    Property Description
    Configuration Name Enter RequestMapping as the name.
    Save in project Specify the Registry Resource project where the data mapper configuration should be saved. The SampleServicesRegistry project that already exists in the project explorer is selected by default.

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

    Info

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

  4. Click Load Input File to open the Load Input dialog box shown below.

    Enter the following information:

    1. Select JSON as the Resource Type.
    2. Click file system, select the JSON file (i.e., input.json ) that you saved in your local file system, and click Open.

    You can view the input format loaded in the Input box of the editor as shown below.

  5. Create another JSON file (e.g., output.json) with the following content (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"
}

  6. Click Load Output File to open the Load Output dialog box and enter the following information:

    1. Select JSON as the resource type.
    2. Click file system, select the JSON file you saved in your local file system, and click Open.

    You can view the output format loaded in the Output box in the editor as shown below.

    Info

    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. The following symbols will help you to identify them correctly.

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

  7. Now, you need to map the input message with the output message. There are two ways to do the mapping:

    • If you click Apply, the mapping will be generated by the AI Data Mapper. You have the option to manually change the mapping after it is generated.
    • You can also manually draw the mapping by dragging arrows from the values in the Input box to the relevant values in the Output box.

    The completed mapping will look as follows:

  8. Save and close the configuration.

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

    Property Description
    Input Type Select JSON.
    Output Type Select JSON.

  10. Save the REST API configuration.

You have successfully created all the artifacts that are required for this use case.

Step 3: Package the artifacts

Package the artifacts in your composite application project (SampleServicesCompositeApplication project) and the registry resource project (SampleRegistryResource project) to be able to deploy the artifacts in the server.

  1. Open the pom.xml file in the composite application project POM editor.

  2. Ensure that the following projects and artifacts are selected in the POM file.

    • SampleServicesCompositeApplicationProject
      • HealthcareAPI
      • ClemencyEP
      • GrandOakEP
      • PineValleyEP
    • SampleServicesRegistryProject

  3. Save the project.

Step 4: Build and run the artifacts

To test the artifacts, deploy the packaged artifacts in the embedded Micro Integrator:

  1. Right-click the composite application project and click Export Project Artifacts and Run.
  2. In the dialog box that opens, select the artifacts that you want to deploy.
  3. Click Finish. The artifacts will be deployed in the embedded Micro Integrator and the server will start. See the startup log in the Console tab.

Step 5: Test the use case

Let's test the use case by sending a simple client request that invokes the service.

Start the backend service

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

  3. Execute the following command to start the service:

    java -jar Hospital-Service-2.0.0-EI7.jar

Get details of deployed artifacts (Optional)

Let's use the CLI Tool to find the URL of the REST API (that is deployed in the Micro integrator) to which you will send a request.

Tip

Be sure to set up the CLI tool for your work environment as explained in the first step of this tutorial.

  1. Open a terminal and execute the following command to start the tool: 

    mi

  2. Log in to the CLI tool. Let's use the server administrator user name and password: 

    mi remote login admin admin

    You will receive the following message: Login successful for remote: default!

  3. Execute the following command to find the APIs deployed in the server: 

    mi api show

    You will receive the following information:

    NAME : HealthcareAPI
    URL : http://localhost:8290/healthcare

Similarly, you can get details of other artifacts deployed in the server. Read more about using the CLI tool.

Send the client request

Let's send a request to the API resource to make a reservation. You can use the embedded HTTP Client of WSO2 Integration Studio as follows:

  1. Open the HTTP Client of WSO2 Integration Studio.

    Tip

    If you don't see the HTTP Client tab, go to Window -> Show View - Other and select HTTP Client to enable the client.

  2. Enter the request information as given below and click the Send icon ().

    Method POST
    Headers Content-Type=application/json
    URL http://localhost:8290/healthcare/categories/surgery/reserve

    • The URI-Template format that is used in this URL was defined when creating the API resource: http://:/categories/{category}/reserve.
    Body
    { "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" }

    • This JSON payload contains details of the appointment reservation, which includes patient details, doctor, hospital, and data of appointment.

If you want to send the client request from your terminal:

  1. Install and set up cURL as your REST client.
  2. Create a JSON file named 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"
}
  3. Open a terminal and navigate to the directory where you have saved the request.json file.
  4. Execute the following command. 
    curl -v -X POST --data @request.json http://localhost:8290/healthcare/categories/surgery/reserve --header "Content-Type:application/json"

Analyze the response

You will see the following response received to your HTTP Client:

{"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,
  "appointmentDate":"2025-04-02"
}

You have now explored how the Micro Integrator can receive a message in one format and transform it into the format expected by the back-end service using the Data Mapper mediator.

Top