# JSONata bindings in Truto Unified APIs

> Source: https://truto.one/docs/guides/unified-apis/mapping-bindings/

**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](https://www.npmjs.com/package/@truto/truto-jsonata#custom-functions) 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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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`.


![Is Partial Response](https://docs-assets.truto.one/is_partial_response.png)


## 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:**
```json
{
  "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:**
```json
{
  "person_id": "12345"
}
```

#### Step 2: Define Response Mapping

**Option 1: Using `query` Binding**

**Response Mapping Configuration:**
```json
{
  "contact": {
    "id": query.person_id
  }
}
```

**Resulting API Response:**
```json
{
  "contact": {
    "id": "12345"
  }
}
```

**Option 2: Using `rawQuery` Binding**

**Response Mapping Configuration:**
```json
{
  "contact": {
    "id": rawQuery.contact.id
  }
}
```

**Resulting API Response:**
```json
{
  "contact": {
    "id": "12345"
  }
}
```