Templating & Runs
How {{...}} tokens resolve against the case, alert, rule and entity context captured when a playbook attaches to a case
Use {{...}} tokens to bind playbook steps to the case, alert, rule, and entities. When you attach a playbook, nano creates a run and resolves the tokens against a snapshot of that context.
The same grammar applies to hand-written playbooks, adaptive playbooks that pivt composes, and what an AI agent sees when it works a run.
To see a run with its tokens substituted, call GET /api/playbook-runs/{id}/resolved. The response carries a has_context flag (false for runs attached without context) and the list of paths that did not resolve.
The run-context snapshot
When a playbook attaches to a case, nano stores a run_context JSON snapshot on the run. It is captured once, at attach time, and never recomputed.
{
"case": { "id": "case_01hz…", "title": "Root key used outside bastion", "severity": "high" },
"alert": { "id": "alert_01hz…", "severity": "high" },
"rule": { "id": "rule_01hz…", "name": "aws_root_key_outside_bastion", "severity": "high" },
"top_matched_event": { "...": "the first matched event of the alert, as stored" },
"entities": {
"user": ["jsmith"],
"ip": ["203.0.113.40"],
"host": ["ws-jsmith"]
}
}- Alert-driven attach (a rule fires, a case is created and the rule's playbook attaches):
case,alert,rule,top_matched_eventandentitiesare filled. The top matched event is the first entry of the alert's matched events.entitiescomes from the same extraction that fills case entities. - Manual attach (an analyst attaches a playbook from the case): only
caseandentitiesare filled.entitiesholds the entities already on the case, primary entities first.{{alert.*}},{{rule.*}}and{{event.*}}render as empty strings.
Token grammar
| Token | Resolves to |
|---|---|
{{case.id}}, {{case.title}}, {{case.severity}} | The case |
{{alert.id}}, {{alert.severity}} | The alert (empty on manual attach) |
{{rule.id}}, {{rule.name}}, {{rule.severity}} | The firing rule (empty on manual attach) |
{{entity.<type>}} | The first extracted entity of that type |
{{entity.<type>[N]}} | The entity at index N (empty if there isn't one) |
{{entities.<type>}} | The whole list, for use with join |
{{event.<key>}} | A top-level key of the top matched event — see the limitation below |
{{alert.<key>}} | Same as {{event.<key>}} for any key other than id and severity |
Entity types
{{entity.*}} uses entity types, not field paths. Extraction folds the source and destination sides of an event into one type: src_endpoint.ip and dst_endpoint.ip both become ip, and actor.user.name and user.name both become user.
| Type | Typical OCSF sources |
|---|---|
user | actor.user.name, user.name |
host | device.hostname, src_endpoint.hostname, dst_endpoint.hostname, internal domains |
ip | src_endpoint.ip, dst_endpoint.ip |
domain | http_request.url.hostname, url.hostname, query.hostname |
hash | file.hashes.value, process.file.hashes.value, actor.process.file.hashes.value |
url | http_request.url.url_string, url.url_string |
file | file.path, file.name, process.file.path, actor.process.file.path |
process | process.name, process.cmd_line, actor.process.name, actor.process.cmd_line |
email | email addresses in event values |
So {{entity.ip}} is valid; {{entity.src_endpoint.ip}} is not. See Entities & Entity Graph for how extraction works, and OCSF field reference for the paths.
{{event.*}} reads top-level keys only
Helpers
| Helper | Usage | Result |
|---|---|---|
lower | {{lower entity.user}} | Lowercased |
upper | {{upper entity.host}} | Uppercased |
default | {{default entity.user "n/a"}} | The value, or the fallback if empty |
join | {{join entities.ip ","}} | A list joined with the separator |
Resolution rules
- Missing value → empty string.
{{entity.hash}}on a case with no hash renders as"". It is not an error and does not stop the run. - Missing list → empty list.
{{join entities.hash ","}}renders as"". - Unknown name → flagged. An unknown namespace (
{{widget.foo}}), an unknown key undercaseorrule({{case.owner}}), or anentitytoken without a type renders as""and is listed as unresolved. The step card shows a missing-context indicator. Saving the playbook is never blocked. - Names are case-sensitive.
{{entity.User}}is not{{entity.user}}. - You add the quotes. The resolver substitutes the bare value. Write
actor.user.name="{{entity.user}}", notactor.user.name={{entity.user}}.
Resolved step example
A query step in the library:
/query: last 7 days of sign-ins for this user
from: okta
window: 7d
npl: metadata.log_source="okta" class_uid=3002 user.name="{{entity.user}}"Attached to a case whose entities contain user: ["jsmith"], the run shows:
/query: last 7 days of sign-ins for this user
from: okta
window: 7d
npl: metadata.log_source="okta" class_uid=3002 user.name="jsmith"The stored playbook is never changed. Resolution runs each time the run is read, against the frozen run_context.
Why the snapshot is frozen
An investigation can last hours or days. New events join the case, the rule is edited, the alert is reclassified. If tokens resolved against live state, /action: disable {{entity.user}} could point at a different user from one moment to the next. The snapshot pins the run to the moment it started.
Attaching the same playbook again creates a new run with a fresh snapshot, which picks up any entities added since.
AI agents working a run
pivt reads the resolved form of each step: labels and parameters with the tokens substituted, plus the danger and approval settings on /action steps, which decide whether the agent proposes an action or leaves it to the analyst.
Troubleshoot
Need help with these checks? Contact support with the request ID and time with timezone.
An entity token resolves to an empty string
Check the entity type and case-sensitive token name. Use {{entity.ip}}, rather than an OCSF path such as {{entity.src_endpoint.ip}}.
A nested event token is empty without a warning
Event tokens read top-level keys only. Use entity tokens for nested OCSF entity values.
New case entities do not appear in the run
The run context is frozen at attachment. Attach the playbook again to create a run with a fresh snapshot.
What's next
- Authoring: the slash-command grammar and the visual builder.
- Library & lifecycle: statuses, approvals and access control.
- Entities & Entity Graph: how
entitiesis populated. - OCSF field reference: field paths for
npl:queries.