How to Transform Message Content¶

What you'll build¶

Message transformation is necessary when the message format sent by the client differs from the format expected by the back-end service. The Message Translator architectural pattern in WSO2 Micro Integrator describes how to translate from one data format to another.

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

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_id": "grandoaks",
  "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_id": "grandoaks",
  "hospital": "grand oak community hospital",
  "appointment_date": "2017-04-02"
}

The client message format must be transformed into the back-end service message format within the mediation flow before making the back-end service call.

Let's get started!¶

Step 1: Set up the workspace¶

You need Visual Studio Code (VS Code) with the Micro Integrator for VS Code extension installed.

Info

See the Install Micro Integrator for VS Code documentation to learn how to install Micro Integrator for VS Code.

Step 2: Develop the integration artifacts¶

Create an integration project¶

The Integration project will contain all the required artifacts for the integration solution.

Launch VS Code with the Micro Integrator extension installed.
Click on the Micro Integrator icon on the Activity Bar of the VS Code editor.
Click Create New Project on Design View.

Next, the Project Creation Form will be opened.
In the Project Creation Form, enter TransformMessageTutorial as the Project Name.
Provide a location under Select Project Directory.
Click Create.

Now let's start designing the integration by adding the necessary artifacts.

Create a REST API¶

In the Add Artifact interface, under Create an Integration, click on API. This opens the API Form.

Enter the details given below to create a new REST API.

Property	Value	Description
Name	`HealthcareAPI`	The name of the REST API.
Context	`/healthcare`	Here you are anchoring the API in the `/healthcare` context. This will become part of the name of the generated URL used by the client when sending requests to the Healthcare service. For example, setting the context to `/healthcare` means that the API will only handle HTTP requests where the URL path starts with `http://host:port/healthcare`.

Click Create. This will open the Service Designer interface.

You can now start configuring the API resource.
On the Service Designer, click on the three dots (⋮) and then Edit to access the Properties of the default API resource.

Enter the following details:

Property	Value	Description
Resource Path	`/categories/{category}/reserve`	The request URL should match this resource path. The `{category}` variable will be replaced with the value sent in the request.
Methods	`POST`	This API resource will accept POST requests.

Click Update.

Create the mediation logic¶

Let's configure the API resource with the data transformation logic.

Open the Resource View of the API resource by clicking the POST resource under Available resources on Service Designer.
Once you open the Resource View, click on the + icon on the canvas to open the Mediator Palette.
Under Mediators, select the Data Mapper mediator.
In the pane that appears, click + Add New, enter RequestMapping as the name, and click Create in the Create New Data Mapper form.
Click Add to insert the Data Mapper into the integration flow. You will then be directed to the Data Mapping Editor.
Click on the Import input schema to import the input schema. Since this scenario involves JSON to JSON mapping, you can import from either a JSON sample or a JSON schema. In this guide, we will be using the Import from JSON option.

Copy the following sample request message sent to the API resource, paste it into the editor, and click Save.

{ 
    "name": "John Doe",
    "dob": "1990-03-19",
    "ssn": "234-23-525",
    "address": "California",
    "phone": "8770586755",
    "email": "[email protected]",
    "doctor": "thomas collins",
    "hospital_id": "grandoaks",
    "hospital": "grand oak community hospital",
    "cardNo": "7844481124110331",
    "appointment_date": "2025-04-02"
}

Next, to set the output JSON, click Import Output Schema and then click Import from JSON.
Copy the following sample request message expected by the back-end service, paste it into the editor, and click Save.

{
    "patient": {
        "name": "John Doe",
        "dob": "1990-03-19",
        "ssn": "234-23-525",
        "address": "California",
        "phone": "8770586755",
        "email": "[email protected]"
    },
    "doctor": "thomas collins",
    "hospital_id": "grandoaks",
    "hospital": "grand oak community hospital",
    "appointment_date": "2025-04-02"
}

Now, you can create the mappings by connecting the values in the Input box to the corresponding values in the Output box.

Tip

The Micro Integrator Data Mapper includes AI capabilities to automatically generate mappings. With a simple button click, your mappings can be completed in seconds. For more information, see Data Mapping using AI.

The completed mapping will appear as follows:
Click on /categories/{category}/reserve in the MI Project Explorer to open the HealthcareAPI resource.

Now that we have the message formatted as expected by the back-end service, let's use the HTTP connector to send a POST request to the hospital services backend.
Click on the + icon after the Data Mapper mediator and search for post in the Mediator Palette to add the HTTP POST operation for invoking the hospital services backend.
Click + Add new connection to create a new connection.

Select HTTP and fill in the following details to create a connection to the Hospital service. Finally, click Add in the Add New Connection form to create the connection.

Property	Value	Description
Connection Name	`HospitalConnection`	The name of the connection.
Base URL	`http://localhost:9090`	The base URL for the back-end service. In the next step, we will see how to construct the full URL using the Relative Path.

Provide /${payload.hospital_id}/categories/${params.pathParams.category}/reserve as the Relative Path, and click Submit to add the operation to the integration flow.

Note

We will leave the rest of the configurations as defaults: Content Type set to JSON, Request Body as ${payload}, and Overwrite Message Body checked.
Click on the + icon after the HTTP POST operation and select the Respond mediator from the Mediator Palette to send the response back to the client.

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

Step 3: Build and run the artifacts¶

Now that you have developed an integration using the Micro Integrator for the Visual Studio Code plugin, it's time to deploy the integration to the Micro Integrator server runtime.

Click the Build and Run icon located in the top right corner of VS Code.

Step 4: Test the use case¶

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

Start the back-end service¶

Download the JAR file of the back-end service from here.
Open a terminal, navigate to the location where you have saved the back-end service.
Execute the following command to start the service:
```
java -jar Hospital-Service-JDK11-2.0.0.jar
```

Send the client request¶

Now, let's test the integration service. For that, you can use the inbuilt try-it functionality in the MI for VS Code extension.

When you run the integration artifact as in Step 3, the Runtime Services interface is opened up. You can see all the available services.

Select the HealthcareAPI you have developed and test the resource using the following category and payload.

Category surgery

Payload


            {
                "name": "John Doe",
                "dob": "1990-03-19",
                "ssn": "234-23-525",
                "address": "California",
                "phone": "8770586755",
                "email": "[email protected]",
                "doctor": "thomas collins",
                "hospital_id": "grandoaks",
                "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 date of appointment.

Optionally, you can use Postman or cURL to send the request. You can refer to the following request information.

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://host:port/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_id": "grandoaks", "hospital": "grand oak community hospital", "cardNo": "7844481124110331", "appointment_date": "2025-04-02" }`

Analyze the response¶

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

{
    "appointmentNumber": 5,
    "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 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.