Scenarios

A Scenario is a reusable packet of sample entity data for testing templates and blueprints. Think of it as a predefined set of test inputs representing a specific situation — "New Customer - Pro Plan", "High-Value Deal - Enterprise Tier", "International Client".

Why Scenarios?

When you design templates with dynamic expressions or blueprints with conditional logic, you need realistic data to verify the results. Running full workflows just to test is slow. Scenarios give you instant feedback:

• Template preview — See how fields render with specific data
• Blueprint simulation — Step through the workflow, see which steps are included/skipped
• Edge case coverage — Quickly switch between scenarios to test different data conditions
• AI-generated test data — When generating contracts with AI, scenario data is created automatically based on your schema definitions

Shape

metadata:
  key: enterprise_hire
  version: 1.0.0
  name: Enterprise Hire (Senior Engineer)
  description: Senior engineer role with all signing branches active
  labels:
    role: senior

spec:
  entities:
    - entityKey: employee
      data:
        firstName: Jane
        lastName: Doe
        email: jane@acme.com

    - entityKey: position
      data:
        title: Senior Engineer
        level: 5
        salary: 180000
        startDate: 2026-05-01

    - entityKey: company
      data:
        name: Acme Corp
        representative:
          name: Bob Smith
          email: bob@acme.com

metadata.key identifies the scenario; spec.entities[].entityKey matches the input keys consumed by templates and blueprints at runtime.

Using Scenarios

Studio

In the resource editor for a template or blueprint, the Preview tab shows a scenario dropdown. Picking a scenario re-renders the preview against that data. The same dropdown also appears in the Run modal — pick a scenario to seed the workflow's entity data, or fill in the form by hand.

If no scenarios are linked yet, Studio auto-generates one from the resource's input schemas using AI.

CLI

# Preview a blueprint with a specific scenario
signstack preview employee_onboarding@1.0.0 --scenario high_value_deal

# Run a workflow with scenario data
signstack run employee_onboarding@1.0.0 --scenario test_onboarding

# List available scenarios
signstack preview --list-scenarios

Mutability

Unlike every other SignStack primitive, scenarios are not versioned. They're mutable test data — edit a scenario in place, the next preview or run picks up the change. This is intentional: scenarios are sample data for design-time iteration, not production artifacts whose behavior must be reproducible across releases.

Each scenario entity has an entityKey matching the input key consumed by templates/blueprints at runtime, plus the data payload.

AI-Assisted Generation

When a template or blueprint has no scenarios yet, Studio generates one from the resource's input schemas using AI. The CLI does the same when you preview without --scenario. You can iterate on the generated data, save it, or discard it — it's just a starting point so you don't have to hand-author sample data before you can preview.

Best Practices

1. Create scenarios for each branch — If your blueprint has conditional logic, create a scenario that triggers each branch.
2. Test boundary values — Create scenarios at the edges (deal value just above/below thresholds).
3. Name scenarios descriptively — enterprise_high_value_international is better than test_1.
4. Reuse across templates — A single scenario can test multiple templates that share the same inputs.

Related Concepts

• Blueprints — Scenarios provide test data for blueprint simulation
• Templates — Scenarios power instant template preview
• Schemas — Scenarios contain entity data validated against schemas