Variables and Placeholders

Keep this page open while you author a Blueprint. It covers the variables a run publishes back to the test, and how a {token} inside the Blueprint resolves to a value.

For writing the document itself, see Building a Blueprint. For validating and running one, see Running a Blueprint.

Output variables

Every field the Blueprint declares becomes a variable after the run. A find or a matched ensure publishes only the columns the Blueprint named, so a column that exists on the matched row but is not declared as a field never reaches the Scenario.

Case	Variable key
Single-instance entity	blueprint-{entity}-{field}
Multi-instance entity using count	blueprint-{entity}[{index}]-{field}
Grouped entity	blueprint-{group}[{index}]-{entity}-{field}
Rendered template file	blueprint-generated-file-path

An entity named order with a field named ordnum produces blueprint-order-ordnum. A count: 2 entity named order_line produces blueprint-order_line[0]-prtnum and blueprint-order_line[1]-prtnum. A part entity in a group named line produces blueprint-line[0]-part-prtnum and blueprint-line[1]-part-prtnum.

A grouped entity has no plain blueprint-{entity}-{field} key at all, not even for the first iteration. Reach for the indexed form whenever an entity carries a count or sits in a group, and reserve the plain form for a single-instance entity. Another entity in the same Blueprint can still reuse a grouped value while the run is in progress, but only the indexed keys leave the run.

Placeholders

Placeholders written as {token} appear in op commands, paths, bodies, file names, and MongoDB map values. Two scopes exist, and the difference matters.

Read-side ops, meaning a field find source, a verify, a teardown, and a retry conflict_check, resolve against the broad run scope in this order:

1. Fields already acquired in this entity and instance.
2. The current iteration's co-group values.
3. Any entity's already-realized fields, as {entity.field}.
4. Values the caller passed at run time.
5. defaults.vars, including values folded in from a system configuration.

A bare {field} reaches only the current instance's own values, the caller's inputs, and defaults.vars. Reading a value another entity realized takes the dotted {entity.field} form.

Create ops resolve only against the entity's own acquired fields. This is the single most common authoring mistake. A value in defaults.vars does not reach a create op directly, so bind it as a field first.

fields:
  - name: wh_id
    source: { var: { key: wh_id } }   # now {wh_id} resolves inside this entity's create op

Escaping

Escaping is automatic and depends on where the value lands.

• A MOCA or SQL command doubles single quotes. A SQL command on a MySQL connection also escapes backslashes, because MySQL treats one as an escape introducer.
• An API path is URL-escaped and its body is JSON-escaped.
• A MongoDB document or filter map is substituted raw, because the driver serializes the value rather than parsing it as a command.
• A flat-file path or filter, and an API result_path, are also substituted raw. Each is a structural value rather than a value inside a command.