Skip to content
DataMaker Docs

Scenarios

A scenario is a Python script that runs on DataMaker’s hosted Python workers. Use a scenario when a single template-and-export step isn’t enough. Typical reasons:

  • Referential integrity — generate customers first, then orders that reference real customer IDs.
  • Conditional logic — different generation strategy per country, per environment.
  • Multi-target seeding — push to Postgres, then to a REST API, then validate the result.
  • External calls — hit a non-DataMaker API mid-flow.
  • Reusable building blocks — turn a multi-step seeding flow into a single button your team can click.

A minimal scenario

from datamaker import DataMaker


dm = DataMaker()


# 1. Generate 100 customers and seed Postgres.
customers = dm.generate(template_id="tmpl_customer", count=100)
dm.connection("conn_postgres").insert(table="customers", rows=customers)


# 2. Generate 500 orders, each referencing a real customer.id.
customer_ids = [c["id"] for c in customers]
orders = dm.generate(
    template_id="tmpl_order",
    count=500,
    overrides={"customer_id": dm.pick_from(customer_ids)},
)
dm.connection("conn_postgres").insert(table="orders", rows=orders)


print(f"✓ seeded {len(customers)} customers and {len(orders)} orders")

Save it from the Scenarios view, click Run, watch the live log stream.

Sub-pages

  • Python environment — what’s pre-installed, how to add packages, what’s not there.
  • Scenario API — full reference for dm.generate, dm.connection, dm.template, etc.
  • Workspace files — uploading CSVs, JSON, lookup tables for use inside scenarios.
  • Logs & retries — how live logging works, retry policy, idempotency.

Triggering a scenario

Scenarios are not just for manual UI runs. Each scenario gets:

  • A REST endpoint — POST /scenarios/{id}/run triggers a run, optionally with parameters.
  • An MCP tool — the DataMaker MCP server exposes execute_scenario so your AI agent can run scenarios.
  • A chat hook — "run the regression seeding scenario" works in any chat where the scenario is in scope.

For CI, the REST endpoint is the path of least friction:

Terminal window
curl -X POST https://api.datamaker.automators.com/scenarios/$SCN_ID/run \
  -H "Authorization: Bearer $DM_API_KEY" \
  -d '{"params": {"environment": "regression"}}'

Scenarios vs templates

Use a template when:

  • One schema generates one shape of row.
  • The target system accepts that shape directly (or with a saved mapping).

Use a scenario when:

  • More than one template is involved in a coherent unit of work.
  • You need to compose results between steps.
  • You need network calls, retries, or branching.
  • You want a single button (or a single API call) to do all of the above.

Authoring scenarios

You write scenarios in DataMaker’s web Monaco editor — full Python syntax highlighting, type completions for the dm SDK, and live console output below the editor. You can also git pull your scenarios via the REST API if you’d rather keep them under version control.