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:
- 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. - If you did not try the Routing Requests Based on Message Content tutorial yet:
- Download the pre-packaged project.
- Open WSO2 Integration Studio and go to File -> Import.
- 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.
- Go to the WSO2 Micro Integrator website.
- Click Download -> Other Resources and click CLI Tooling to download the tool.
- Extract the downloaded ZIP file. This will be your
MI_CLI_HOME
directory. - 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 themi
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.
-
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.
-
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.
-
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.
-
Click Load Input File to open the Load Input dialog box shown below.
Enter the following information:
- Select JSON as the Resource Type.
- 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.
-
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" }
-
Click Load Output File to open the Load Output dialog box and enter the following information:
- Select JSON as the resource type.
- 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
-
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:
-
Save and close the configuration.
-
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. -
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.
- Open the
pom.xml
file in the composite application project POM editor. -
Ensure that the following projects and artifacts are selected in the POM file.
- SampleServicesCompositeApplicationProject
HealthcareAPI
ClemencyEP
GrandOakEP
PineValleyEP
- SampleServicesRegistryProject
- SampleServicesCompositeApplicationProject
-
Save the project.
Step 4: Build and run the artifacts¶
To test the artifacts, deploy the packaged artifacts in the embedded Micro Integrator:
- Right-click the composite application project and click Export Project Artifacts and Run.
- In the dialog box that opens, select the artifacts that you want to deploy.
- 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¶
- Download the JAR file of the back-end service from here.
- Open a terminal, navigate to the location where your saved the back-end service.
-
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.
-
Open a terminal and execute the following command to start the tool:
mi
-
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!
-
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:
-
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.
-
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.
-
The URI-Template format that is used in this URL was defined when creating the API resource:
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": "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 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