Data Mapping¶

The following instructions demonstrate how to build an integration that transforms a JSON payload into a different JSON structure using Ballerina Integrator Data Mapper. An HTTP service with a single resource (transform) will be created to receive a JSON payload and return the transformed result.

Step 1: Create a new integration project¶

Click on the Ballerina Integrator icon on the sidebar.
Click on the Create New Integration button.
Enter the project name as Transformer.
Select project directory location by clicking on the Select Location button.
Click on the Create New Integration button to create the integration project.

Step 2: Define input and output types¶

Click on the Add Artifacts button and select Type in the Other Artifacts section.
Click on + Add Type to add a new type.
Generate record types corresponding to the input and output JSON payloads given below.

Select Make Separate Record Definitions and click on the Import button.

Input

{
    "user": {
        "firstName": "John",
        "lastName": "Doe",
        "email": "[email protected]",
        "address": {
            "street": "123 Elm St",
            "city": "San Francisco",
            "state": "CA",
            "postalCode": 94107
        },
        "phoneNumbers": ["123-456-7890", "098-765-4321"]
    },
    "account": {
        "accountNumber": "A123456789",
        "balance": 2500,
        "lastTransaction": "2023-10-15T14:30:00Z"
    }
}

Output

{
    "fullName": "John Doe",
    "contactDetails": {
        "email": "[email protected]",
        "primaryPhone": "123-456-7890"
    },
    "location": {
        "city": "San Francisco",
        "state": "CA",
        "zipCode": "94107"
    },
    "accountInfo": {
        "accountNumber": "A123456789",
        "balance": 2500
    },
    "transactionDate":  "2023-10-15T14:30:00Z"
}

5. The final types will look like below. The source view can be accessed by clicking on the </> button in the top right corner.

Step 3: Create a HTTP service¶

Click on Home button to navigate back to the design view
In the design view, click on the Add Artifact button.
Select HTTP Service under the Integration as API category.
Select the + Listeners option from the Listeners dropdown to add a new listener.
Enter the listener name as transformListener, 8290 as the port and click on the Save button.
Add the service base path as / and select the Design from Scratch option as the The contract of the service.
Click on the Create button to create the new service with the specified configurations.

Step 4: Update the resource method¶

Click on Edit Resource button
Change the resource HTTP method to POST.
Change the resource name as transform.
Add a payload parameter named input to the resource of type Input.
Change the response status code to 201 and the return type to Output.
Click on the Save button to update the resource with the specified configurations.

Resource Method

To learn more about resources, see Ballerina Resources.

Step 5: Add data mapper¶

Click on the transform resource to navigate to the resource implementation designer view.
Delete the existing Return node in the flow diagram.
Hover to the arrow after start and click the ➕ button to add a new action to the resource.
Select Map Data from the node panel and click on Create Data Mapper button.
Fill in the required fields with the values given below and Create Mapping button to start data mapping.

Field Value

Data Mapper Name transformed

Input Input input

Output Output

Step 6: Create mappings¶

First click on the input field and then click on the desired output field to create a mapping.
When you are done click on the Go Back Button to return to the flow diagram.

Create simple mapping¶

Auto mapping¶

Many-to-one mapping¶

Edit mapping expression¶

Resolving errors¶

Step 7: Return the transformed payload¶

Hover to the arrow after the Data Mapper node in the flow diagram and click the ➕ button.
Select Return from the node panel.
Provide output as the return expression.

The final code will look like below. The source view can be accessed by clicking on the </> button in the top right corner.

import ballerina/http;

listener http:Listener transformListner = new (port = 8290);

service / on transformListner {
    resource function post transform(@http:Payload Input input) returns http:InternalServerError|Output|error {
        do {
            Output output = transform(input);
            return output;

        } on fail error err {
            // handle error
            return error("Not implemented", err);
        }
    }
}

Step 8: Run the integration¶

Click on the Run button in the top-right corner to run the integration.
The integration will start and the service will be available at http://localhost:8290/transform.

The service can be tested using a tool like Postman or cURL by sending a POST request with a JSON payload to the service endpoint.

curl -X POST "http://localhost:8290/transform" -H "Content-Type: application/json" -d '{
    "user": {
        "firstName": "John",
        "lastName": "Doe",
        "email": "[email protected]",
        "address": {
            "street": "123 Elm St",
            "city": "San Francisco",
            "state": "CA",
            "postalCode": 94107
        },
        "phoneNumbers": ["123-456-7890", "098-765-4321"]
    },
    "account": {
        "accountNumber": "A123456789",
        "balance": 2500,
        "lastTransaction": "2023-10-15T14:30:00Z"
    } 
}'

The response will be the transformed JSON payload.

{
    "fullName": "John Doe",
    "contactDetails": {
    "email": "[email protected]",
    "primaryPhone": "123-456-7890"
    },
    "location": {
    "city": "San Francisco",
    "state": "CA",
    "zipCode": "94107"
    },
    "accountInfo": {
    "accountNumber": "A123456789",
    "balance": 2500
    },
    "transactionDate":  "2023-10-15T14:30:00Z"
}

Field	Value
Data Mapper Name	`transformed`
Input	`Input input`
Output	`Output`