> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voxworks.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Field Mapping & Context

> Understand how data flows through an automation pipeline using the shared context object and field mappings with dot-notation paths.

## The Automation Context

Every automation execution has a shared **context** — a data object that steps read from and write to as the pipeline runs. When a trigger fires, the context is initialized with the trigger data. Each step can add to or modify the context, and subsequent steps see the updated data.

Think of it as a growing data bag that accumulates information as it passes through each step.

***

## Context Field Paths

Field mappings and variable interpolation use **dot-notation paths** to reference data in the context. Here is every field path available:

### Trigger Data

Available from the moment the automation starts.

| Path        | Description                                                                                                                                                                                                       |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `trigger.*` | Raw fields from the trigger payload. For webhooks, these match the JSON keys in the POST body. For call events, these include `call_id`, `call_type`, `call_status`, `contact_name`, `phone_user`, `actual_time`. |

**Example:** If a webhook sends `{ "phone": "+61400111222", "name": "John" }`, the fields are `trigger.phone` and `trigger.name`.

### Contact

Available after an **Upsert Contact** step runs, or automatically hydrated for Call Completed and Call Scheduled triggers.

| Path                   | Description                  |
| ---------------------- | ---------------------------- |
| `contact.id`           | Contact UUID                 |
| `contact.phone_number` | Phone number in E.164 format |
| `contact.first_name`   | First name                   |
| `contact.last_name`    | Last name                    |
| `contact.full_name`    | Full name (first + last)     |
| `contact.email`        | Email address                |
| `contact.address`      | Street address               |
| `contact.location`     | City / region / country      |

### Objects

Available after an **Upsert Object** step runs, or automatically hydrated for call event triggers.

| Path                    | Description                                                 |
| ----------------------- | ----------------------------------------------------------- |
| `objects.{type_name}.*` | Data fields of the linked object, keyed by object type name |

**Examples:**

* `objects.monday_item.CRM_ID` — The Monday.com item ID
* `objects.monday_item.board_id` — The Monday.com board ID
* `objects.hubspot_deal.deal_id` — A HubSpot deal ID

### Source Data

Available after a **Source** step runs.

| Path       | Description                  |
| ---------- | ---------------------------- |
| `source.*` | Fields from the API response |

**Examples:** `source.notes`, `source.deal_stage`, `source.priority`

### Mapped Data

Available after a **Transform** step runs.

| Path       | Description                         |
| ---------- | ----------------------------------- |
| `mapped.*` | Fields output by the transform step |

### Call Record

Available in post-call steps (steps after a Create Call step) and in Call Completed / Call Scheduled trigger automations.

| Path                      | Description                                                                                                                     |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `call.id`                 | Call UUID                                                                                                                       |
| `call.script_id`          | Script used for the call                                                                                                        |
| `call.status`             | Outcome: `completed`, `failed`, `voicemail`, `dropout`, `hang-up`, `rang-out`, `User unavailable`, `User rejected`, `cancelled` |
| `call.duration`           | Call duration in seconds                                                                                                        |
| `call.actual_time`        | When the call took place                                                                                                        |
| `call.call_summary`       | AI-generated narrative summary                                                                                                  |
| `call.transcript`         | Full transcript as plain text                                                                                                   |
| `call.transcript_json`    | Structured transcript with speaker turns                                                                                        |
| `call.structured_data`    | AI-extracted structured fields (per your Script's data collection schema)                                                       |
| `call.objectives`         | Objective evaluation results (JSON)                                                                                             |
| `call.success_evaluation` | Overall success evaluation                                                                                                      |
| `call.end_reason`         | Why the call ended: `user hangup`, `ai hangup`, `voicemail`, `failed`                                                           |
| `call.notes`              | Agent-generated call notes                                                                                                      |

### Destination Results

Available after **Destination** steps run.

| Path                 | Description                                           |
| -------------------- | ----------------------------------------------------- |
| `results[].status`   | HTTP status or success indicator from the destination |
| `results[].response` | Response data from the destination                    |

***

## Using Field Paths in Mappings

Field mappings appear in Transform, Upsert Contact, Upsert Object, and Destination steps. Each mapping has a **source** (where to read data) and a **target** (where to write it).

**Example — Transform step mapping webhook data to contact fields:**

| Source               | Target                 | Transform   |
| -------------------- | ---------------------- | ----------- |
| `trigger.phone`      | `contact.phone_number` |             |
| `trigger.first_name` | `contact.first_name`   |             |
| `trigger.last_name`  | `contact.last_name`    | `uppercase` |

### Available Transforms

| Transform     | What It Does                                         |
| ------------- | ---------------------------------------------------- |
| `uppercase`   | Convert text to UPPERCASE                            |
| `lowercase`   | Convert text to lowercase                            |
| `truncate:N`  | Truncate text to N characters (e.g., `truncate:100`) |
| `date:FORMAT` | Format a date string (e.g., `date:YYYY-MM-DD`)       |
| `to_string`   | Convert a number or boolean to a string              |
| `to_number`   | Convert a string to a number                         |

***

## Variable Interpolation in Templates

Email templates, SMS templates, webhook body templates, and URL fields support `{{variable}}` interpolation. Use the same dot-notation paths:

**Email subject:**

```text theme={null}
Your call summary - {{contact.full_name}}
```

**SMS template:**

```text theme={null}
Hi {{contact.first_name}}, thanks for your time. Your call summary is ready.
```

**Webhook body:**

```json theme={null}
{
  "call_id": "{{call.id}}",
  "status": "{{call.status}}",
  "summary": "{{call.call_summary}}",
  "contact_name": "{{contact.full_name}}"
}
```

***

## Sample Payloads and the Field Picker

For webhook-triggered automations, the field picker in the pipeline editor uses a **sample payload** to show you which `trigger.*` fields are available.

To set a sample payload:

1. Open the automation editor
2. Click **Test Webhook** in the trigger panel
3. Send a POST request to the webhook URL with representative data
4. When the payload arrives, click **Use as Sample**

The sample payload is stored on the automation and powers the dropdown suggestions when you configure field mappings. You can update it at any time by sending a new test payload.