Trigger Mapping

View as Markdown

Trigger mapping controls how incoming event data becomes Agent run input. It is the contract between the event that starts a run and the variables the Agent expects.

Use trigger mapping for:

incoming webhook triggers
upload-triggered Agents
sub-agent calls from another Agent

Schedules usually use variable sets instead of payload mapping.

Mapping Basics

A mapping connects a payload value to an Agent variable.

Each mapping should define:

Payload key: where the value appears in the incoming event
Agent variable: the variable that receives the value
Required status: whether the run should fail if the value is missing
Expected type or format: how the Agent should interpret the value

Payload keys can use dot notation for nested objects. For example, customer.name can read the name field from a nested customer object.

Incoming Webhook Mapping

Webhook mapping is useful when another system starts an Agent run.

Example payload:

{
  "account": {
    "name": "Northwind Partners",
    "tier": "Enterprise"
  },
  "dateRange": {
    "start": "2026-06-01",
    "end": "2026-06-30"
  }
}

Example mapping:

Payload key	Agent variable	Required
`account.name`	`clientName`	Yes
`account.tier`	`clientTier`	No
`dateRange.start`	`startDate`	Yes
`dateRange.end`	`endDate`	Yes

Use strict payload validation when the webhook payload is treated as an API contract. With strict validation enabled, unmapped top-level fields are rejected. Without it, extra fields are ignored while required mapped fields are still enforced.

Default Sites

Webhook and sub-agent triggers can define default Sites. Default Sites help keep triggered runs grounded in the correct approved content even when the incoming payload does not include a Site scope.

Use default Sites when:

the trigger always applies to a known workspace
an external system should not choose arbitrary Sites
a customer, matter, client, or project has a fixed approved Site

Do not use default Sites as a shortcut around permissions. The run still depends on the Agent, user, organization policy, and Site settings.

Upload Trigger Mapping

Upload triggers start an Agent when files are added to a configured Site or folder. The upload event can map upload details into Agent variables.

Common upload-triggered values include:

uploaded file name
file ID or content ID
folder
Site
uploader
upload timestamp

Upload trigger applicability, including Site and folder rules, is configured in Site Settings > Extraction Workflows.

Use upload triggers for:

metadata extraction
document classification
intake checks
automatic summaries
filing quality checks

See Extraction Workflows.

Sub-Agent Trigger Mapping

Sub-agent trigger mapping lets a parent Agent call a child Agent with explicit values.

Use sub-agent mapping when:

a reusable child Agent needs different values per parent run
the child Agent should use a narrower source scope
a larger process needs modular review or quality checks

Map only the values the child Agent needs. Avoid passing broad context when a smaller value or source is enough.

Testing Trigger Mapping

Before using a trigger in production:

Create a representative test payload or event.
Confirm every required Agent variable receives a value.
Confirm optional variables behave correctly when omitted.
Test strict validation if enabled.
Confirm default Sites and source policy are correct.
Run the Agent and inspect the run evidence.

If the run fails, check missing required variables, payload key spelling, nested field paths, access key scope, and Site permissions.

Best Practices

Treat mappings as API contracts for production integrations.
Keep payload keys stable.
Prefer explicit mappings over asking the Agent to infer values from raw payloads.
Use required fields for values that materially change the output.
Keep default Sites narrow.
Re-test mappings when variables are renamed.
Document the expected payload for external teams.