Manual Data Mapping¶

This guide shows how to build an integration that transforms a JSON payload into a different JSON structure using WSO2 Integrator: BI Data Mapper. You will create an HTTP service with a single resource (transform) to receive a JSON payload and return the transformed result.

Step 1: Create a new integration project¶

Click on the WSO2 Integrator: BI icon on the sidebar.
Click on the Create New Integration button.
Enter the integration name as datamapper.
Select integration directory location by clicking on the Select Path button.
Click on the Create Integration button to create the integration project.

Step 2: Create an HTTP service¶

In the design view, click on the Add Artifact button.
Select HTTP Service under the Integration as API category.
Click on the Create button to create the new service with the default configurations.

Step 3: Add the resource method¶

Click Add Resource and select POST method.
Set the resource path as transform.

Configure the request payload by pasting the JSON sample below. Set the type name as Input and the variable name to 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"
    }
}

Change the response body schema of the 201 response to Output.
To create the type named Output, click Create New Type within the Message Body Type editor.

Switch to Import mode and provide the following JSON to create the BI type named 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"
}

Click Save to apply the response configuration.
Finally, click Save to update the resource with the specified configurations.

Resource Method

To learn more about resources, see Ballerina Resources.

Reusable vs inline data mappers

There are two ways to create data mappers in WSO2 Integrator: BI. You can create reusable data mappers that can be used anywhere within the integration project, or inline data mappers that are specific to a particular resource or function. In this guide, Step 5 demonstrates how to create a reusable data mapper, and Step 6 (optional) demonstrates how to create an inline data mapper.

Step 5: Add a reusable data mapper¶

Click on the transform resource to navigate to the resource implementation designer view.
Hover over 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 the Create Data Mapper button.
Fill in the required fields with the values below and click the Create button to create the data mapper.

Field Value

Data Mapper Name transformed

Inputs Input input

Output Output
Your newly created data mapper appears under Current Integration. Click it to add it to the sequence.
Set payload as the Input and outputResult as the Result, then save.
Click the kebab menu on the Map Data node and choose View to open the visual data mapper.

Step 6 (Optional): Add an inline data mapper¶

Click on the transform resource to navigate to the resource implementation designer view.
Hover over the arrow after start and click the ➕ button to add a new action to the resource.
Select Declare Variable from the node panel.
Provide output as the Name and select Output as the Type.
Once you select the type, the Open in Data Mapper button appears. Click it to open the visual data mapper.

Step 7: Create mappings¶

Click a source field, then click the desired target field to create a mapping.

Create simple mapping¶

AI data mapping¶

Click the Auto Map button to automatically create AI mappings. The BI Copilot panel opens to assist you.

AI Data Mapper

To learn more about AI-powered data mapping capabilities, see AI Data Mapping.

Many-to-one mapping¶

You can map multiple source fields to a single target field. For example, create the fullName field in the output by combining the firstName and lastName fields from the input.

Edit mapping expression¶

Click the <> button on any link, or use the context menu on any output field, to edit the mapping expression.

Array mapping¶

BI Data Mapper offers several ways to map arrays. You can map entire arrays, specific elements, or use functions to manipulate array data. To map the first phone number from the phoneNumbers array in the input to the primaryPhone field in the output, create a mapping from phoneNumbers to primaryPhone and pick "Extract Single Element From Array" to get the first element.

Step 8: Return the transformed payload¶

After you complete the mappings, click the Go Back button to return to the resource designer view.
Hover over the arrow after the Map Data node in the flow diagram and click the ➕ button.
Select Return from the node panel.
Provide outputResult as the return expression.

The final code looks like this. The source view can be accessed by clicking the </> button in the top right corner.

import ballerina/http;

listener http:Listener httpDefaultListener = http:getDefaultListener();

service / on httpDefaultListener {
    resource function post transform(@http:Payload Input payload) returns error|json|http:InternalServerError {
        do {
            Output outputResult = transform(payload);
            return outputResult;
        } on fail error err {
            // handle error
            return error("unhandled error", err);
        }
    }
}

Step 9: Run the integration¶

Click the Run button in the top-right corner to run the integration.
Confirm the Test with Try it Client prompt. The integration starts running and serving at http://localhost:9090/transform.

Verify the integration by sending a POST request to the /transform endpoint with the following JSON payload.

curl -X POST "http://localhost:9090/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`
Inputs	`Input input`
Output	`Output`