> ## Documentation Index
> Fetch the complete documentation index at: https://docs.roark.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Variables
> Feed dynamic values into customer flows and run plans with {{variable}} placeholders
Variables let you reuse the same customer flow with different data on every run. Instead of hardcoding details into a flow's brief or steps, you write `{{variableName}}` placeholders that get replaced with real values at runtime.
Variables show up in three places:
1. **On a flow variant** — key/value entries the simulator hands to the customer-side model, so the simulated customer can answer the agent's questions consistently
2. **On a run plan** — named variables with a type and an optional default, referenced as `{{name}}`, with per-attachment overrides when you attach flows
3. **At runtime** — a modal collects any values that still need filling in before the run starts
***
## 1. Variables on a flow variant
Each variant of a customer flow carries its own set of variables — key/value entries like `name`, `account_id`, or `last_visit` that the simulator gives to the customer-side model. When the agent asks "Can I get your account number?", the simulated customer answers with the value you set, consistently, every run.
### Editing variant variables
Open the variant and click the **Variables** chip (next to the Persona and Environment chips). From there you can:
* **Add variable** — add a key/value row inline
* **Apply a test profile** — replace the variant's entries with a saved test profile's properties in one click
### `{{variable}}` autocomplete
Text fields in the flow editor — the customer setup brief in Improv mode, step text in Scripted mode — support `{{variable}}` tokens with autocomplete sourced from your project's property definitions:
* `{{name}}` — flow-scoped properties, resolved from the variant's variables
* `{{persona.name}}` — persona-scoped properties, resolved from the variant's persona
Type `{{` to open the autocomplete and pick a property, or keep typing to reference a new one.
***
## 2. Variables on a run plan
Run plans define their own variables in the **Advanced** section of the create-run page. Each run-plan variable has:
| Field | Description |
| :---------- | :--------------------------------------------------------------- |
| **Name** | Referenced as `{{name}}` in attached flows |
| **Type** | The value type (string, number, boolean, date) |
| **Default** | Optional. If omitted, the value must be provided before each run |
Variables with defaults let a plan run unattended — on a schedule or from the API — without prompting anyone. Variables without defaults turn the plan into a parameterized suite: every run asks for fresh values.
### Per-attachment overrides
When you attach customer flows to a plan via the **Attach flows** picker, each attachment can override `{{variable}}` values for that flow. Overrides win over the values stored on the variant, so you can attach the same flow with different data — for example, one attachment with `appointmentType: urgent` and another with `appointmentType: routine checkup` — and each becomes its own set of test calls.
***
## 3. Providing values at runtime
If any variable lacks a value when you start a run — **Run now**, ⌘↵, or a "Fresh run" re-run — a modal collects the missing values first. It gathers, in one place:
* **Run-plan variables** without defaults
* **Flow variant values** — per-variant values for attached scripted flows
* **Persona property values** — values for `{{persona.*}}` references, which persist onto the persona for future runs
Once every required value is filled in, the run starts.
**"Re-run with same data"** replays a run's exact captured snapshot, so it never prompts for variables. **"Fresh run"** builds new test calls from the plan as configured today and collects unresolved variables first.
***
## Reserved variables
Some variable names are reserved for system use and resolved automatically:
| Variable | Resolves to |
| :---------------------- | :------------------------------------------------------------ |
| `{{persona.*}}` | Properties of the variant's persona (e.g. `{{persona.name}}`) |
| `{{phoneNumberToDial}}` | The phone number to dial for outbound simulations |
| `{{simulationJobId}}` | The current simulation job's ID |
Don't define your own variables with these names.
***
## Setting variables via the API
The REST API keeps the older naming: flows are passed in a `scenarios` field, and runtime overrides are keyed by `scenarioId`.
### Pre-set variables when creating a plan
Add a `variables` object to each entry in `scenarios` when [creating a run plan](/api-reference/simulation-run-plan/create-a-run-plan). The same flow ID can appear multiple times with different values — each entry becomes a separate test case:
```json POST /v1/simulation/plan theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
{
"name": "Patient Scheduling - Multi Profile",
"direction": "INBOUND",
"iterationCount": 2,
"maxSimulationDurationSeconds": 300,
"scenarios": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"variables": {
"patientName": "John Doe",
"appointmentType": "urgent",
"insuranceProvider": "Aetna"
}
},
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"variables": {
"patientName": "Jane Smith",
"appointmentType": "routine checkup",
"insuranceProvider": "Blue Cross"
}
}
],
"personas": [{ "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8" }],
"agentEndpoints": [{ "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7" }],
"metrics": [{ "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479" }],
"autoRun": false
}
```
### Override variables when triggering a run
Runtime values are passed in the request body when [triggering a job](/api-reference/simulation-run-plan-job/run-a-simulation-plan). They override any values stored on the plan.
**Global format** — the same values apply to every flow in the plan:
```json POST /v1/simulation/plan/:planId/job theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
{
"variables": {
"orderNumber": "12345",
"environment": "staging"
}
}
```
**Per-flow format** — different values per flow, keyed by `scenarioId`:
```json POST /v1/simulation/plan/:planId/job theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
{
"variables": [
{
"scenarioId": "550e8400-e29b-41d4-a716-446655440000",
"variables": {
"orderNumber": "12345",
"claimType": "damaged item"
}
},
{
"scenarioId": "7a3d2e1f-c4b5-6a89-0d1e-2f3a4b5c6d7e",
"variables": {
"orderNumber": "67890",
"claimType": "missing package"
}
}
]
}
```
If everything has a stored value or default, the body is optional — `POST /v1/simulation/plan/:planId/job` with no body starts the run as configured.
***
## Related
Author the flows and variants that variables plug into
Compose flows, personas, metrics, and variables into a reusable suite
Trigger runs and follow them live
The customer identities behind {"{{persona.*}}"} values