Translating Message Formats¶

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 request payload differs from what the back-end service expects. The Data Mapper mediator transforms the request message payload to 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 to the back-end service message format within the In sequence.

Let's get started!¶

Step 1: Set up the workspace¶

The following software and configurations are required to proceed with this tutorial:

Visual Studio Code (VS Code): with the Micro Integrator extension installed.
Java Development Kit (JDK): Version 11 or 17 is required. Ensure the JDK is properly configured in your system's PATH environment variable.
Apache Maven: Ensure Apache Maven is installed and its path is correctly set within the system's PATH environment variable.

Info

Follow the Install Micro Integrator for VS Code documentation for a complete installation guide.

Step 2: Develop the integration artifacts¶

Create an integration project¶

An Integration project is a maven multi module project containing all the required modules for the integration solution.

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 SampleServices 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 new endpoint¶

An Endpoint artifact is required to expose the URL that connects to the back-end service.

Navigate to the MI Project Explorer > Endpoints.
Hover over Endpoints and click the + icon that appears.
Next, select HTTP Endpoint type from the Create Endpoint Artifact interface.

In the HTTP Endpoint Form that appears, specify the following values to create the new endpoint.

Property	Value	Description
Endpoint Name	`HospitalServicesEP`	This is a single endpoint configured to forward requests to the relevant hospital by reading the hospital specified in the request payload.
URI Template	`http://localhost:9090/{uri.var.hospital}/categories/{uri.var.category}/reserve`	The template for the request URL expected by the back-end service. The following two variables will be replaced by the corresponding values in the request message: {uri.var.hospital} {uri.var.category}
Method	`POST`	Endpoint HTTP REST Method.

Click Create.

Create a REST API¶

Go to MI Project Explorer > APIs.
Hover over APIs and click the + icon that appears to open 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.

Click on the GET API resource under Available resources on the Service Designer.

You will now see the graphical view of the HealthcareAPI with its default API Resource.

Click the Edit icon to edit the API resource.

Specify values for the required resource properties:

Property	Description
URI-Template	`/categories/{category}/reserve` This defines the request URL format. In this case, the full request URL format is `http://host:port/categories/{category}/reserve` where `{category}` is a variable.
Url Style	`URI_TEMPLATE`
Methods	`POST` This defines that the API resource only handles requests where the HTTP method is POST.

Click Update.

Create the mediation logic¶

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

To get started, click on the + icon to add the first mediator to the sequence.
Select Property mediator.

Info

This is used to extract the hospital name from the request payload.

Once you select the Property mediator, the Property panel will be opened. Fill in the information in the table below:

Property	Value	Description
Property Name	`uri.var.hospital`	The name that will be used to refer this property's values.
Property Action	`set`	The property action.
Property Data Type	`STRING`	The property action.
Property Scope	`default`	The scope of the property.
Value (Expression)	`json-eval($.hospital_id)`	Follow the steps given below to specify the expression value: Click the Ex button before the Value field. This specifies the value type as expression. Enter `json-eval($.hospital_id)` as the expression value. Note: This is the JSONPath expression that will extract the hospital from the request payload.

Click Submit to save the Property mediator configuration.
Click on the + icon under Property mediator. Add a Data Mapper mediator just after the Property mediator in the In Sequence of the API resource.
Once you select the Data Mapper mediator, the Property panel will be opened. Select New Mapping and Fill name as RequestMapping. Click Create Mapping. You can view the data mapping editor.

Click + on Import Input Schema. Then, click Import from JSON. Copy the following sample content of the request message sent to the API resource 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"
}

Click + on Import Output Schema. Then, click Import from JSON. Copy the following sample content of the request message expected by the back-end service 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 draw the mapping by clicking the values in the Input box to the relevant values in the Output box.

The completed mapping will look as follows:
Save and close the configuration. Go back to HealthcareAPI resource.
Open API resource. Add a Call mediator next to the Data mapper from the Mediators palette and select the HospitalServicesEP endpoint from the dropdown list. Click Submit.
Add a Respond mediator next to the Call mediator to return the response from the health care service back to the client. Click Submit.
Save the REST API configuration.

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

Step 3: Build and run the artifacts¶

Prerequisites

Before you begin, install Micro Integrator on your machine:

Go to the WSO2 Micro Integrator web page, click Download, provide necessary details, and then click Zip Archive to download the Micro Integrator distribution as a ZIP file.
Extract the ZIP file. The extracted folder will be referred as the <MI_HOME> folder.

Once you have downloaded and set up the Micro Integrator locally, follow the steps given below. Use one of the below two methods.

Click on the Command Palette on the top of the VS Code.
Type > to show the available commands.
Select MI: Add MI server.
Select Add MI server.
Select the folder where <MI_HOME> is located. This wll be set as the current server path.
Run the project.

Use one of the following two options to build and run the project:

Option 1

Click on the Command Palette on the top of the VS Code.
Type > to show the available commands.
Select MI: Build and Run.

Option 2

Click the Build and Run icon located on the top right corner of the 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¶

Let's send a request to the API resource to make a reservation. You can use Postman or any other HTTP Client:

Open the Postman application. If you do not have the application, download it from here : Postman

Add the request information as shown below and click the Send button.

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" }` This JSON payload contains details of the appointment reservation, which includes patient details, doctor, hospital, and date of appointment.

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

Install and set up cURL as your REST client.

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

Open a terminal and navigate to the directory where you have saved the request.json file.

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 by 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.