Overriding Unified API mappings

To support use cases where some of your customers might be using a specific custom fields for a resource, you can override the Unified API mappings on an Integrated account level (applies to only that specified integrated account) or Environment level (applies to multiples integrated accounts in that environment). This will allow you to map the custom fields to the Unified API fields.

How overrides are applied

Overrides only need to specify the mappings that you need to change or add or remove.

1. Truto applies the environment unified mapping overrides if available or base mapping from the Unified API to the raw API response (remote_data).
2. Overrides from the integrated account are applied to the same remote_data.
3. If there are any attributes returned from Step 2 which are also returned from Step 1, then they are overwritten. Any new attributes from Step 3 are added to the unified API response.

How to specify an override for an Integrated account

Let's take an example of HiBob, where we want to specify an override to get the date_of_birth for an employee and adding a query_param name.

To do this,

1. Get the integrated account ID from the UI or the API where you want to apply the override.
2. Make a PATCH request on the integrated account resource with the override details.

For the example mentioned before, you'll have to make the following API request,

curl --location --request PATCH 'https://api.truto.one/integrated-account/<integrated_account_id>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <your_api_key>' \
--data '{
    "unified_model_override": {
        "hris": {
            "employees": {
                "list": {
                    "query_mapping": "{ \"fullName\": query.name }",
                    "response_mapping": "{ \"date_of_birth\": response.personal.shortBirthDate }"
                }
            }
        }
    }
}'

The request body contains the following,

• unified_model_override This is the object which specifies the overrides
  • hris This is the name of the Unified Model. You can find this on the Unified Model details page in the UI.
  • employees This is the resource you want to specify the override for.
  • list The overridden method
  • query_mapping Since we want to add query_param name to filter the results based on the name input, we specify the query_mapping which is a JSONata expression. name is mapped to the query parameter fullName which is accepted by the HiBob API.
  • response_mapping Since we want to change the response, we specify the response_mapping which is a JSONata expression. The remote_data is present in response object within the JSONata expression.

Now you can go ahead and make the LIST /unified/hris/employees API request for the integrated account and it should return you the data with date_of_birth added to it.

How to specify an override for an Environment

Let's take an example of HiBob, where we want to specify an override to get the date_of_birth for an employee.

To do this,

1. Get the installed unified model ID by specifying the name of unified_model in the following API request

curl --location 'https://api.truto.one/environment-unified-model?unified_model.name=<unified_model_name>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <your_api_key>'

2. Make a PATCH request on the installed unified model resource with the override details.

For the example mentioned before, you'll have to make the following API request,

curl --location --request PATCH 'https://api.truto.one/environment-unified-model/<installed_unified_model_id>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <your_api_key>' \
--data '{
    "override": {
        "resources": {
            "employees": {
                "integration_mapping": {
                    "hibob": {
                        "list": {
                            "query_mapping": "{ \"fullName\": query.name }",
                            "response_mapping": "{ \"date_of_birth\": response.personal.shortBirthDate }"
                        }
                    }
                }
            }
        }
    }
}'

The request body contains the following,

• override This is the object which specifies the overrides
  • resources This is the object which specifies the overrides for multiple resources.
  • employees This is the resource you want to specify the overrides for.
  • integration_mapping Since we want to add the overrides for integration, we specify integration_mapping which is an object.
  • hibob This is the integration name you want to specify the overrides for.
  • list The overridden method
  • query_mapping Since we want to add query_param name to filter the results based on the name input, we specify the query_mapping which is a JSONata expression. name is mapped to the query parameter fullName which is accepted by the HiBob API.
  • response_mapping Since we want to change the response, we specify the response_mapping which is a JSONata expression. The remote_data is present in response object within the JSONata expression.

Now you can go ahead and make the LIST /unified/hris/employees API request for the integrated accounts in the environment and it should return you the data with date_of_birth added to it for all of the integrated accounts in the specified environment.

Bindings available to use in response_mappings

Bindings are the data that are sent in the Unified API call, which can be used in response_mappings to apply overrides as per your needs.

• rawQuery This is the object that contains the raw query parameters sent in the Unified API request.

{
  "fullName": rawQuery.name
}

• query This is the object which specified the query params after mapping is applied as needed by the integration.

{
  "fullName": query.name
}

INFO

Consider an example of query_mapping where the contact resource is mapped to person_id in the following way -

{
  "person_id": rawQuery.contact.id
}

Now, if you need to map the contact resource in the response_mapping, you can do in the following ways -

{
  "contact": {
    "id": query.person_id
  }
}

or

{
  "contact": {
    "id": rawQuery.contact.id
  }
}

• body This is the object that contains the body sent in the Unified API request.

{
  "fullName": body.name
}

• context This is the object that contains all the variables stored in your Integrated account.

{
  "fullName": context.name
}

JSONata methods to transform the raw API response

These JSONata methods are lifesavers while writing overrides for transforming the raw API response to the Unified API response schema.

Here are the following methods,

• $firstNonEmpty(...args) - Returns the first non-empty value from the list of arguments passed. Consider an example response as following

{
 "response": {
   "username": "uday",
   "name": "",
   ...
 }
}

If you need to map response for this to get first available value to the name field, you would do in the following way in JSONata expression,

{
  "name": $firstNonEmpty(response.name, response.username)
}

• $removeEmptyItems(<array>) - Removes the empty items from the array passed to it. Consider an example response as following

{
 "response": {
   "teams_assigned": ["12", "", "13"],
 }
}

If you need to map response for this to remove empty values from the team_assigned and map it to team, you would do in the following way in JSONata expression,

{
  "teams": $removeEmptyItems(response.teams_assigned)
           //returns ["12","13"] 
}

• $fromMillis(<epoch>) - Returns the date and time in ISO 8601 format. Consider an example response as following

{
 "response": {
   "createdAt": 1715160105000,
   ...
 }
}

If you need to convert createdAt from milliseconds to ISO 8601 format and map it to created_at, you would do in the following way in JSONata expression,

{
  "created_at": $fromMillis(response.createdAt)
                //returns "2024-05-08T14:51:45+05:30"
}

• $dtFromFormat(arg,'<format>') - Returns the date and time in ISO 8601 format for the argument passed which is in mentioned format. Consider an example response as following

{
 "response": {
   "updated_at": "Wed, 08 May 2024 14:59:04 +05:30",
   ...
 }
}

If you need to convert createdAt from RFC 2822 format to ISO 8601 format and map it to updated_at, you would do in the following way in JSONata expression,

{
  "updated_at": $dtFromFormat(response.updated_at,'RFC2822')
                //returns "2024-05-08T14:51:45+05:30"
}