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 HTTP headers from the Unified API call.

• query

  • Description: Mapped query parameters.

• rawQuery

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

• 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).
  • 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 HTTP headers from the Unified API call.

• 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

Request Path Mapping Configuration:

{
  "userId": query.user_id
}

Explanation:

• query.user_id accesses the mapped user_id parameter.
• userId is used to construct or modify the request path.

Error Bindings

Available Bindings

• error

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

• headers

  • Description: The HTTP headers from the Unified API call.

• 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

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 associated with the Unified API call.

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 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).
    • 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

• query

  • Description: Mapped query parameters.

• rawQuery

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

• 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.

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: Mapped query parameters.

• step

  • Description: The step in before after/steps

    The step object has the following attributes -

    • type - The type of the step
    • name - The name of the step
    • run_if - If the step runs on certain conditions

• 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"
  }
}