Skip to content

JSONata bindings in Truto Unified APIs

Bindings are the building blocks you use in Truto Unified APIs to access and work with different parts of an API request and response. They're especially useful when writing JSONata expressions to transform data. When a JSONata expression runs, it uses these bindings to get the input data it needs. For example, query gives you access to all query parameters in a request. In this section, we will go through the JSONata Bindings available in Truto Unified APIs by each Mapping Type.

You can refer to Truto JSONata to know more about the JSONata methods supported.

Query Mapping

Available Bindings

  • query

    • Description: Contains the query parameters sent as part of the Unified API call

  • body

    • Description: The request body associated with the Unified API call.

  • context

    • Description: A unified object that gathers all the information your API call needs. It merges:
      • Account Settings from integratedAccount.context: These are persistent configurations specific to the connected account.
      • Information from baseContext: This is used for passing certain info in Sync Jobs, such as the number of records for pagination (e.g., total_records_size).

    You can access these properties directly in your integration logic. For example, to access the authToken, use context.authToken.

  • before

    • Description: Contains the result of the before steps call.

  • id

    • Description: Can be used for cases when id is present in Query Params, for example in /crm/accounts/:id

Example

Scenario: User inputs contact.id which is mapped to person_id that the underying Salesforce API accepts. Here, contact is the Unified API resource that maps to Persons in Salesforce. To filter Accounts with a particular contact, we use the following query mapping

Query Mapping Configuration:

{
  "person_id": query.contact.id
}

Explanation:

  • query.contact.id accesses the contact.id parameter from the user's request.
  • person_id is the internal parameter used by Salesforce.

Example Unified Request:

GET /unified/crm/accounts?contact[id]=12345

Mapped Query Parameters:

{
  "person_id": "12345"
}

Body Mappings

Available Bindings

  • body

    • Description: The request body associated with the Unified API call.

  • query

    • Description: Mapped query parameters.

  • rawQuery

    • Description: The query parameters from the user's request before query mapping.

  • context

    • Description: A unified object that gathers all the information your API call needs. It merges:
      • Account Settings from integratedAccount.context: These are persistent configurations specific to the connected account.
      • Information from baseContext: This is used for passing certain info in Sync Jobs, such as the number of records for pagination (e.g., total_records_size).

    You can access these properties directly in your integration logic. For example, to access the authToken, use context.authToken.

  • before

    • Description: Contains the result of the before steps call.

  • id

    • Description: Can be used for cases when id is present in Query Params, for example in /crm/accounts/:id

Example

Body Mapping Configuration:

{
  "fullName": body.name
}

Explanation:

  • body.name accesses the name field from the request body.
  • fullName is the field used by the underlying API.

Header Bindings

Available Bindings

  • headers

    • Description: The headers Truto has prepared for the request to the underlying API. Only content-type is carried over from the Unified API call; custom headers you send to the Unified API are not passed in.

  • query

    • Description: Mapped query parameters.

  • rawQuery

    • Description: The query parameters from the user's request before query mapping.

  • body

    • Description: The request body after Body Mapping, as it will be sent to the underlying API.

  • requestBody

    • Description: The request body sent in the Unified API call, before Body Mapping.

  • context

  • Description: A unified object that gathers all the information your API call needs. It merges:

    • Account Settings from integratedAccount.context: These are persistent configurations specific to the connected account.
    • Information from baseContext: This is used for passing certain info in Sync Jobs, such as the number of records for pagination (e.g., total_records_size).
    • Dynamic Runtime Values:
      • id: The unified model id that uniquely identifies the record.
      • before: The before steps that run immediately before the API request.

You can access these properties directly in your integration logic. For example, use context.id to get the unified model id, check context.before for the pre-request steps.

Example

Header Mapping Configuration:

{
  "Authorization": context.authToken
}

Explanation:

  • context.authToken accesses the authentication token from the API call context.
  • Authorization header is set with the token for Salesforce authentication.

Request Path Bindings

Available Bindings

  • headers

    • Description: The headers for the request to the underlying API, after Header Mapping.

  • body

    • Description: The request body after Body Mapping, as it will be sent to the underlying API.

  • query

    • Description: Mapped query parameters.

  • rawQuery

    • Description: The query parameters from the user's request before query mapping.

  • context

    • Description: A unified object that gathers all the information your API call needs. It merges:
      • Account Settings from integratedAccount.context: These are persistent configurations specific to the connected account.
      • Information from baseContext: This is used for passing certain info in Sync Jobs, such as the number of records for pagination (e.g., total_records_size).

    You can access these properties directly in your integration logic. For example, to access the authToken, use context.authToken.

  • before

    • Description: Contains the result of the before steps call.

  • id

    • Description: Can be used for cases when id is present in Query Params, for example in /crm/accounts/:id

Example

The expression must return the path as a string.

Request Path Mapping Configuration:

"/users/" & query.user_id

Explanation:

  • query.user_id accesses the mapped user_id parameter.
  • The returned string, for example /users/12345, is used as the path of the request to the underlying API.

Error Bindings

Available Bindings

  • error

    • Description: The error object containing error details returned by the underlying API.

  • headers

    • Description: The headers sent in the request to the underlying API, after Header Mapping.

  • body

    • Description: The request body after Body Mapping, as sent to the underlying API.

  • query

    • Description: Mapped query parameters.

  • rawQuery

    • Description: The query parameters from the user's request before query mapping.

  • context

    • Description: A unified object that gathers all the information your API call needs. It merges:
    • Account Settings from integratedAccount.context: These are persistent configurations specific to the connected account.
    • Information from baseContext: This is used for passing certain info in Sync Jobs, such as the number of records for pagination (e.g., total_records_size).

    You can access these properties directly in your integration logic. For example, to access the authToken, use context.authToken.

  • before

    • Description: Contains the result of the before steps call.

  • id

    • Description: Can be used for cases when id is present in Query Params, for example in /crm/accounts/:id

Response Bindings

Used in: Response Mapping
Purpose: Transform the API response into a user-friendly format.

Available Bindings

  • response

    • Description: The raw API response returned by the API call.

  • query

    • Description: Mapped query parameters.

  • rawQuery

    • Description: The raw query parameters from the user's request.

  • context

    • Description: A unified object that gathers all the information your API call needs. It merges:
      • Account Settings from integratedAccount.context: These are persistent configurations specific to the connected account.
      • Information from baseContext: This is used for passing certain info in Sync Jobs, such as the number of records for pagination (e.g., total_records_size).
      • Dynamic Runtime Values:
        • id: The unified model id that uniquely identifies the record.
        • before: The before steps that run immediately before the API request.

    You can access these properties directly in your integration logic. For example, use context.id to get the unified model id, check context.before for the pre-request steps.

  • headers

    • Description: HTTP headers in the API response.

  • body

    • Description: The request body after Body Mapping, as sent to the underlying API.

Example

Response Mapping Configuration:

{
  "id": Id,
  "owner": { "id": OwnerId },
  "name": Name
}

Explanation:

  • Id maps Salesforce's Id to the API's id.
  • OwnerId maps to a nested owner.id.
  • Name maps directly to name in the response.

Final API Response:

{
  "id": "0012w000024KwDeAAK",
  "owner": {
    "id": "0052w00000CkYXHAA3"
  },
  "name": "Truto-Archith-Test"
}

Response Header Bindings

Used in: Response Header Mapping
Purpose: Manage HTTP headers in the API response.

Available Bindings

  • headers

    • Description: HTTP headers in the API response.

  • query

    • Description: Mapped query parameters related to the response headers.

  • rawQuery

    • Description: The raw query parameters from the user's request.

  • body

    • Description: The request body after Body Mapping, as sent to the underlying API.

  • context

    • Description: A unified object that gathers all the information your API call needs. It merges:
      • Account Settings from integratedAccount.context: These are persistent configurations specific to the connected account.
      • Information from baseContext: This is used for passing certain info in Sync Jobs, such as the number of records for pagination (e.g., total_records_size).
      • Dynamic Runtime Values:
        • id: The unified model id that uniquely identifies the record.
        • before: The before steps that run immediately before the API request.

    You can access these properties directly in your integration logic. For example, use context.id to get the unified model id, check context.before for the pre-request steps.

Is Partial Response?

Sometimes, the APIs you call may not return all the data you need in a single response. In such situations, you might need to make an additional API call to another endpoint to fetch the remaining data. To handle this, you can enable the Is partial response? option in the Advanced Settings of the Response Mapping configuration.

By default, this value is set to true when you enable this option. You can also define a JSONata expression that returns a boolean to validate whether the response is partial.

Available Bindings

  • data

    • Description: The unified response after Response Mapping.

  • query

    • Description: Mapped query parameters.

  • rawQuery

    • Description: The raw query parameters from the user's request.

  • requestBody

    • Description: The request body sent in the Unified API call.

  • before

    • Description: Contains the result of the before steps call.

  • id

    • Description: Can be used for cases when id is present in Query Params, for example in /crm/accounts/:id

  • rawBody

    • Description: Contains an Array Buffer of the body. Useful if the underlying API accepts data in a different formats like base64.

Is Partial Response

Before/After Steps

Available Bindings

  • id

    • Description: Can be used for cases when id is present in Query Params, for example in /crm/accounts/:id

  • query

    • Description: The query parameters from the user's request, before Query Mapping.

  • data

    • Description: The output of the previous step. In before steps, the first step starts with an empty object. In after steps, the first step starts with the unified response.

  • step

    • Description: The results of the earlier steps, keyed by step name (or by the step's position when it has no name). For example, step.get_owner is the result of the step named get_owner.

  • context

    • Description: Contains all the variables stored in your Integrated Account.

  • body

    • Description: The request body associated with the Unified API call.

Practical Example

Scenario: Mapping Contact Resource

Map contact.id to the internal person_id used by Salesforce and then map it back in the response.

Step 1: Define Query Mapping

Query Mapping Configuration:

{
  "person_id": query.contact.id
}

Explanation:

  • query.contact.id accesses the contact.id parameter from the user's request.
  • person_id is the internal parameter used by Salesforce.

Example Request:

GET /unified/crm/accounts?contact[id]=12345

Mapped Query Parameters:

{
  "person_id": "12345"
}

Step 2: Define Response Mapping

Option 1: Using query Binding

Response Mapping Configuration:

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

Resulting API Response:

{
  "contact": {
    "id": "12345"
  }
}

Option 2: Using rawQuery Binding

Response Mapping Configuration:

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

Resulting API Response:

{
  "contact": {
    "id": "12345"
  }
}