Definition #
Agent Data Model explains how runtime data is stored and used across a journey, including candidate fields, candidate metadata, and workflow-level variables.
Why it matters #
Most journey issues come from data misunderstandings.
Clear data modeling improves reliability, merge output accuracy, and troubleshooting speed.
How it works #
- Candidate input is captured at widget level.
- Values are saved into configured targets (field, metadata, variable).
- Later steps read those values for routing, rendering, and outcomes.
- Completion logic uses final state to determine result and follow-up actions.
Configuration fields #
- Save target per widget response
- Candidate standard fields mapping
- Custom metadata keys and labels
- Workflow variable names and scopes
- Merge token references
- Validation and default value rules
Example scenario #
A candidate selects preferred territory in an options step.
That value is saved to metadata, used in a confirmation step via merge fields, and later used by a gate decision for path routing.
Common mistakes #
- Saving to one target but reading from another
- Inconsistent naming between metadata key and merge token
- Missing refresh behavior after update
- Overloading one variable for multiple meanings
Troubleshooting checklist #
- Identify expected source of truth for each value
- Confirm write operation succeeded in backend
- Verify read operation references the same key
- Check merge rendering for prompt/display fields
- Validate path/gate conditions against stored value
- Re-run flow with clean test data