Skip to main content
Scenario variables let you create reusable scenario templates with dynamic values that change between simulation runs. Instead of hardcoding specific details into your scenario steps, you define placeholders like {{orderNumber}} or {{appointmentDate}} that get replaced with real values at runtime. Variables follow a three-stage lifecycle:
  1. Define: Add {{variableName}} placeholders to your scenario steps
  2. Pre-set (optional): Configure default values when building a run plan
  3. Provide at runtime: Pass final values when triggering a simulation job

​
1. Defining Variables in a Scenario

Variables are defined by typing {{variableName}} directly into scenario step content. Any text wrapped in double curly braces is treated as a template variable.

​
In the UI

When editing a scenario step, you can add variables in two ways:
  • Type {{ in the step content to trigger the autocomplete dropdown, then select an existing variable or create a new one
  • Click the “Add variable” button on the step card to insert a variable at the cursor position
From the autocomplete dropdown, you can:
  • Select an existing variable from the dropdown list
  • Create a new variable by typing a name and selecting a type (STRING, NUMBER, BOOLEAN, or DATE)
Variables are highlighted in the editor: purple for defined variables and red for undefined ones (variables referenced in content but not yet created as property definitions). Scenario editor with template variables

​
Via the API

Variables are defined in scenario content. When you create or update a scenario via the API, include {{variableName}} placeholders in your step content. The system automatically detects and registers them as variable definitions.

​
Reserved variables

Some variable names are reserved for system use and are automatically resolved:
  • {{persona.*}}: All persona. prefixed variables are reserved for persona properties (e.g. {{persona.name}}, {{persona.backstoryPrompt}})
  • {{phoneNumberToDial}}: The phone number for outbound simulations
  • {{simulationJobId}}: The current simulation job ID

​
2. Pre-setting Variables on a Run Plan

When configuring a run plan, you can optionally pre-set default values for variables. This is useful when you want the same scenario to run multiple times with different data, for example testing with different appointment types or insurance providers.

​
In the UI

When selecting scenarios in the run plan creation wizard, any scenario that contains variables will show a Pre-set variables section inline. You can enter default values for each variable directly on the scenario card. Variables left blank will show as “Not set (required at runtime)”. If you want to add multiple instances of the same scenario, each with a different set of variables, click Add instance with different variables + below the scenario card. This step is optional. If you don’t pre-set variables at the run plan level, you will be prompted to provide them when running the plan. Pre-setting variables on a run plan

​
Via the API

Pre-set variables when creating or updating a run plan by adding a variables object to each scenario entry:

​
Create a run plan with pre-set variables

POST /v1/simulation/plan

{
  "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" }],
  "evaluators": [{ "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479" }],
  "autoRun": false
}
Note how the same scenario ID appears twice with different variable values. Each entry becomes a separate test case in the run plan’s test matrix.

​
3. Passing Variables at Runtime

When triggering a simulation job, you must provide values for any variables that were not pre-set at the run plan level.

​
In the UI

When you click Run on a run plan that has variables, a modal appears showing:
  • Variables that already have defaults (marked with a green badge)
  • Variables that still need values (highlighted as required)
You can provide values in two modes:
  • Global mode: Enter each variable value once, applied to all scenarios
  • Per-scenario mode: Enter different values for each scenario
Runtime variables modal

​
Via the API

Runtime variables are passed in the request body when triggering a job: 
POST /v1/simulation/plan/:planId/job

​
Option 1: Global variables

Apply the same values to all scenarios in the plan: 
{
  "variables": {
    "orderNumber": "12345",
    "environment": "staging"
  }
}

​
Option 2: Per-scenario variables

Provide different values for specific scenarios: 
{
  "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"
      }
    }
  ]
}

​
No variables needed

If all variables have pre-set defaults and you don’t need to override anything, the body is optional: 
POST /v1/simulation/plan/:planId/job