Skip to main content

Chain playbooks across cases

By the end of this tutorial you will have a rent charge that reads its rent from a lease, which reads it from a property: three playbooks whose cases are bound to each other, so the rent is filled once, a correction at the property marks everything downstream stale, and one refresh per case brings it up to date.

For one playbook filled by an agent in conversation, see Fill a case per client. This tutorial is about what that one does not cover: a case that reads another case.

Nine steps:

  1. Declare the property playbook.
  2. Declare the lease playbook.
  3. Declare the charge playbook.
  4. Open the property case.
  5. Bind the lease and the charge.
  6. Ask what is missing.
  7. Fill the chain.
  8. Raise the rent — everything downstream goes stale.
  9. Refresh the chain — the proof.

Every call is shown for all three clients. The ids in the responses are examples — copy the ids your own calls return.

Prerequisites​

export NATURALI_TOKEN=nat_sk_...
export PROJECT=proj_V1StGXR8Z5jdHi6B

Nothing here runs an agent, so the calls draw no tokens.

1. Declare the property playbook​

Every playbook names the policy_ids its cases run under. These three run no executor, so one policy allowing case reads serves all of them:

naturali create-policy \
--project-id "$PROJECT" \
--name lease-chain \
--description "What the property, lease and charge playbooks run under." \
--document "{
\"statement\": [
{ \"effect\": \"Allow\", \"action\": [\"playbooks:GetPlaybookCase\"], \"resource\": [\"srn:$PROJECT:*:*\"] }
]
}"
export POLICY=pol_Ln5bW8eT1yKc3VxD

One collect node: a person writes its three inputs, and a collect node's output is its inputs. Each input's schema refuses a bad value and its description is what step 6 asks for.

DEFINITION=$(cat <<'EOF'
{
"nodes": [
{ "id": "profile", "title": "Property profile", "kind": "collect", "final": true,
"inputs": [
{ "name": "address", "schema": { "type": "string", "minLength": 1 }, "required": true,
"source": "manual", "description": "Street address" },
{ "name": "owner", "schema": { "type": "string", "minLength": 1 }, "required": true,
"source": "manual", "description": "Owner name" },
{ "name": "rent_base", "schema": { "type": "number", "minimum": 0 }, "required": true,
"source": "manual", "description": "Monthly base rent" }
] }
]
}
EOF
)
naturali create-playbook \
--project-id "$PROJECT" \
--name property \
--policy-ids "$POLICY" \
--definition "$DEFINITION"
{
"id": "pbk_5xCYMsP012qQBmRu",
"name": "property",
"version": 1,
"policy_ids": ["pol_Ln5bW8eT1yKc3VxD"],
"definition": { "nodes": ["…"] }
}
export PROPERTY=pbk_5xCYMsP012qQBmRu

2. Declare the lease playbook​

The lease declares the property as an upstream under the name property, and holds two nodes:

  • prop is an upstream node: it takes no inputs and no executor, and outputs what the node profile holds in the case bound to property.
  • terms collects the lease's rent, read from prop with an ordinary { node_id, field } source, and the tenant, which a person writes.

An upstream node still carries an empty inputs array.

DEFINITION=$(cat <<EOF
{
"upstreams": [{ "name": "property", "playbook_id": "$PROPERTY" }],
"nodes": [
{ "id": "prop", "title": "Property", "kind": "upstream", "inputs": [],
"upstream": { "name": "property", "node_id": "profile" } },
{ "id": "terms", "title": "Lease terms", "kind": "collect", "final": true,
"inputs": [
{ "name": "rent_base", "schema": { "type": "number" }, "required": true,
"source": { "node_id": "prop", "field": "output.rent_base" } },
{ "name": "tenant", "schema": { "type": "string", "minLength": 1 }, "required": true,
"source": "manual", "description": "Tenant name" }
] }
]
}
EOF
)
naturali create-playbook \
--project-id "$PROJECT" \
--name lease \
--policy-ids "$POLICY" \
--definition "$DEFINITION"
{
"id": "pbk_z0my7x9XbXWffxeq",
"name": "lease",
"version": 1,
"policy_ids": ["pol_Ln5bW8eT1yKc3VxD"],
"definition": { "upstreams": ["…"], "nodes": ["…"] }
}
export LEASE=pbk_z0my7x9XbXWffxeq

The definition is checked as it is written: an upstream naming a playbook that does not exist is UNKNOWN_UPSTREAM, and one that reads the playbook back is UPSTREAM_CYCLE. POST /v1/projects/{project_id}/playbooks/validate reports both without writing.

3. Declare the charge playbook​

The same shape one level down: lease is the upstream, ctr pulls the lease's terms, and charge reads the rent from ctr. The charge never names the property — it reaches it through the lease.

DEFINITION=$(cat <<EOF
{
"upstreams": [{ "name": "lease", "playbook_id": "$LEASE" }],
"nodes": [
{ "id": "ctr", "title": "Lease", "kind": "upstream", "inputs": [],
"upstream": { "name": "lease", "node_id": "terms" } },
{ "id": "charge", "title": "Monthly charge", "kind": "collect", "final": true,
"inputs": [
{ "name": "rent_base", "schema": { "type": "number" }, "required": true,
"source": { "node_id": "ctr", "field": "output.rent_base" } },
{ "name": "month", "schema": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}\$" }, "required": true,
"source": "manual", "description": "Billing month, YYYY-MM" }
] }
]
}
EOF
)
naturali create-playbook \
--project-id "$PROJECT" \
--name charge \
--policy-ids "$POLICY" \
--definition "$DEFINITION"
{
"id": "pbk_YaPp3Kcm8o19SUlP",
"name": "charge",
"version": 1,
"policy_ids": ["pol_Ln5bW8eT1yKc3VxD"],
"definition": { "upstreams": ["…"], "nodes": ["…"] }
}
export CHARGE=pbk_YaPp3Kcm8o19SUlP

4. Open the property case​

A case is one subject filled against one version of a playbook. The property is the root of the chain, so it binds nothing.

naturali create-playbook-case \
--project-id "$PROJECT" \
--playbook-id "$PROPERTY" \
--subject "Rua das Flores 12"
{
"id": "pbk_case_BVb3joB9UCqllk5z",
"playbook_version": 1,
"subject": "Rua das Flores 12",
"actor_id": null,
"upstreams": {},
"revision": 0
}
export PROPERTY_CASE=pbk_case_BVb3joB9UCqllk5z

5. Bind the lease and the charge​

Each case names, in upstreams, the case it reads for every upstream its playbook declares. The binding is fixed for the life of the case, and many cases may share one upstream case: a second charge case for next month would bind this same lease.

naturali create-playbook-case \
--project-id "$PROJECT" \
--playbook-id "$LEASE" \
--subject "Rua das Flores 12, lease" \
--upstreams "{\"property\":\"$PROPERTY_CASE\"}"

export LEASE_CASE=pbk_case_WqRJNUziy0pGJOrX

naturali create-playbook-case \
--project-id "$PROJECT" \
--playbook-id "$CHARGE" \
--subject "Rua das Flores 12, 2026-11" \
--upstreams "{\"lease\":\"$LEASE_CASE\"}"

The CLI and curl tabs export the lease case's id between the two calls, from the first response.

The second response, trimmed to each node's state:

{
"id": "pbk_case_QrSViwcagFtApQe5",
"upstreams": { "lease": "pbk_case_WqRJNUziy0pGJOrX" },
"nodes": [
{ "id": "ctr", "state": "blocked", "blocked_by": ["terms"] },
{ "id": "charge", "state": "blocked", "blocked_by": ["ctr"] }
]
}
export CHARGE_CASE=pbk_case_QrSViwcagFtApQe5
A missing or wrong binding is refused

A case without a binding for a declared upstream, with one for a name the playbook does not declare, or bound to a case of another playbook (or of another actor) answers 400 PLAYBOOK_CASE_UPSTREAM_INVALID and creates nothing.

6. Ask what is missing​

GET /v1/projects/{project_id}/playbook-cases/{case_id}/missing answers, for one goal, every input still to be written — and it follows the bindings. Ask it about the charge:

naturali get-playbook-case-missing \
--project-id "$PROJECT" \
--case-id "$CHARGE_CASE" \
--node-id charge
{
"case_id": "pbk_case_QrSViwcagFtApQe5",
"node_id": "charge",
"waves": [
[
{
"case_id": "pbk_case_BVb3joB9UCqllk5z",
"node_id": "profile",
"input": "address",
"description": "Street address",
"required": true
},
{
"case_id": "pbk_case_BVb3joB9UCqllk5z",
"node_id": "profile",
"input": "owner",
"description": "Owner name",
"required": true
},
{
"case_id": "pbk_case_BVb3joB9UCqllk5z",
"node_id": "profile",
"input": "rent_base",
"description": "Monthly base rent",
"required": true
},
{
"case_id": "pbk_case_WqRJNUziy0pGJOrX",
"node_id": "terms",
"input": "tenant",
"description": "Tenant name",
"required": true
},
{
"case_id": "pbk_case_QrSViwcagFtApQe5",
"node_id": "charge",
"input": "month",
"description": "Billing month, YYYY-MM",
"required": true
}
]
]
}

One call, three cases: each entry carries the case_id to write it to (schema trimmed above). Whoever or whatever collects the data asks the charge once and learns everything the chain still needs.

7. Fill the chain​

Write the property first. POST /v1/projects/{project_id}/playbook-cases/{case_id}/inputs writes a batch, all or none; each value names the revision of the field it read in expected_revision, which is null for a field still unset. wait: true answers once every node the write started has settled.

naturali write-playbook-case-inputs \
--project-id "$PROJECT" \
--case-id "$PROPERTY_CASE" \
--inputs '[
{ "node_id": "profile", "name": "address", "value": "Rua das Flores 12", "expected_revision": null },
{ "node_id": "profile", "name": "owner", "value": "Ana Lima", "expected_revision": null },
{ "node_id": "profile", "name": "rent_base", "value": 2000, "expected_revision": null }
]' \
--wait true

naturali write-playbook-case-inputs \
--project-id "$PROJECT" \
--case-id "$LEASE_CASE" \
--inputs '[{ "node_id": "terms", "name": "tenant", "value": "Bruno Reis", "expected_revision": null }]' \
--wait true

naturali write-playbook-case-inputs \
--project-id "$PROJECT" \
--case-id "$CHARGE_CASE" \
--inputs '[{ "node_id": "charge", "name": "month", "value": "2026-11", "expected_revision": null }]' \
--wait true

Nobody pulled anything: once the property was done, prop pulled it into the lease, and when the lease's terms was done, ctr pulled that into the charge through both levels. The last response, trimmed to each node's output:

{
"id": "pbk_case_QrSViwcagFtApQe5",
"nodes": [
{
"id": "ctr",
"state": "done",
"output": {
"value": { "rent_base": 2000, "tenant": "Bruno Reis" },
"revision": 1
}
},
{
"id": "charge",
"state": "done",
"output": {
"value": { "rent_base": 2000, "month": "2026-11" },
"revision": 3
}
}
]
}

Asking step 6 again now answers waves: []: nothing is left to write.

8. Raise the rent​

The owner raises the rent to 2500. Write it to the property case, naming the revision rent_base holds — 3, in the inputs of GET /v1/projects/{project_id}/playbook-cases/{case_id} on the property case.

naturali write-playbook-case-inputs \
--project-id "$PROJECT" \
--case-id "$PROPERTY_CASE" \
--inputs '[{ "node_id": "profile", "name": "rent_base", "value": 2500, "expected_revision": 3 }]' \
--wait true

The property is done at 2500. Read the lease case and the charge case: every node that reads it, at any depth, is stale and still holds the old value.

{
"id": "pbk_case_QrSViwcagFtApQe5",
"nodes": [
{
"id": "ctr",
"state": "stale",
"output": { "value": { "rent_base": 2000, "tenant": "Bruno Reis" } }
},
{
"id": "charge",
"state": "stale",
"output": { "value": { "rent_base": 2000, "month": "2026-11" } }
}
]
}

A charge issued now would bill 2000. That is the point of stale: the old value stays readable, marked as no longer current, until a refresh.

9. Refresh the chain​

An upstream node pulls again when it is run. POST /v1/projects/{project_id}/playbook-cases/{case_id}/nodes/{node}/run on prop re-reads the property into the lease, and on ctr re-reads the lease into the charge — in that order, one level at a time.

naturali run-playbook-case-node \
--project-id "$PROJECT" \
--case-id "$LEASE_CASE" \
--node prop \
--wait true

naturali run-playbook-case-node \
--project-id "$PROJECT" \
--case-id "$CHARGE_CASE" \
--node ctr \
--wait true

Each answers the execution that pulled the value:

{
"node_id": "ctr",
"status": "completed",
"result": "current",
"output": { "rent_base": 2500, "tenant": "Bruno Reis" },
"output_revision": 4
}

Read the charge case:

naturali get-playbook-case \
--project-id "$PROJECT" \
--case-id "$CHARGE_CASE"
{
"id": "pbk_case_QrSViwcagFtApQe5",
"nodes": [
{ "id": "ctr", "state": "done" },
{
"id": "charge",
"state": "done",
"output": {
"value": { "rent_base": 2500, "month": "2026-11" },
"revision": 5
}
}
]
}

That is the chain, proven: the rent was written once, at the property, and the charge for November bills 2500.

The chain protects what reads it
  • Deleting a case another case is bound to is 409 PLAYBOOK_CASE_HAS_DEPENDENTS — try it on the property case. Delete from the charge up.
  • Deleting a playbook with cases is 409 PLAYBOOK_HAS_CASES, and, once the cases are gone, a playbook another playbook declares as an upstream is 409 PLAYBOOK_HAS_DEPENDENTS. Delete the charge playbook before the lease, and the lease before the property.
  • A write a node's work makes to its own case or to a case reading it as an upstream at any depth is 403 PLAYBOOK_SELF_WRITE. Nodes feed their case through their output only.

To remove what this tutorial created, delete bottom-up with delete-playbook-case on the charge, lease and property cases, then delete-playbook on the charge, lease and property playbooks.

What's next​

  • Tie the chain to an end user — create-playbook-case takes --actor-id, and a case may bind only upstream cases of the same actor. See A case belongs to an actor.
  • Let an agent fill it — Fill a case per client gives an agent the tool that asks what is missing and writes the answers, and runs an agent as a node.
  • Change a chain safely — a playbook that gains an upstream needs the binding at upgrade; see Upgrading a case.