Playbook Cookbook

What is a playbook?

A playbook is one versioned JSON file that describes a business domain for AnythingGraph. Think of it as an installable package: it tells the platform which record types exist, how they connect in a graph, what sample rows to seed for demos, and optionally who may read or write which rows.

Playbooks appear in the dashboard Playbooks gallery. When you install a pack, the backend creates entities (tables), relationship types, and—if provided—example_data rows and links. The same file is read by rdf-cache for graph queries and, when configured, for relationship-based access control (ReBAC) at query time.

File location: dashboard/backend/src/playbook/playbooks/<id>.json where id matches the JSON id field (e.g. hr-relationship-access.json).

What a playbook can do

Not every playbook uses every block. The HR example uses schema, graph, demo data, and ReBAC; a simple starter pack might only define entities and relationships.

How a playbook JSON is structured

A playbook file is one JSON object. Author in this logical order: identity and catalog text first, then schema (entities and relationship types), then policy, then instance demo data.

Schema is stable: entity names and relationship types define the graph shape for every tenant. example_data is optional sample content. ReBAC references schema names and walks instance links stored after install (or ingest).

Names are snake_case internally (employee, member_of_department). The platform exports camelCase property IRIs to Turtle/RDF (memberOfDepartment).

HR relationship access — example playbook

hr-relationship-access models a small HR domain: departments, employees, HR users (managers and HR business partners), and compensation rows. It demonstrates graph-shaped org data and relationship-based visibility—not only “who installed the playbook.”

Schema relationships

Sample cast (example_data)

Alice and Bob are department managers; Carol is an HR BP for Engineering. Jane and John are in Engineering; Sara is in Sales. One compensation row (COMP-9001) links to Jane.

Access subjects use hr_user.user_id as subject_id in MCP (e.g. alice.mgr, carol.hr). Section 6 walks through who may see which rows; section 8 shows MCP checks.

JSON reference (brief)

Condensed field guide for the HR file. Open the full JSON for every rule and row: dashboard/backend/src/playbook/playbooks/hr-relationship-access.json

Top-level skeleton

{
  "id": "hr-relationship-access",
  "name": "HR relationship access",
  "description": "...",
  "category": "operations",
  "instructions": "...",
  "entities": [ { "name": "hr_user", "display_name": "...", "fields": [ ... ] } ],
  "entity_relationships": [ { "relationship_name": "...", "subject_entity_name": "...", "object_entity_name": "..." } ],
  "relationship_access_rules": { "subject_entity_name": "hr_user", "rules": [ ... ], "deny_by_default": true },
  "example_data": { "rows": [ ... ], "relationships": [ ... ] }
}

Catalog fields

entities[] and fields

entity_relationships[]

example_data

{
  "entity_name": "hr_user",
  "values": { "user_id": "alice.mgr", "full_name": "Alice Manager", ... }
}

{
  "relationship_name": "manager_manages_department",
  "subject_row_ref": "hr_user::alice.mgr",
  "object_row_ref": "department::ENG"
}

Example links use entity_name::identifier for subject_row_ref / object_row_ref (derived from each row’s identifier field). relationship_name must match a schema relationship, and the row refs must match that relationship’s subject/object entities.

relationship_access_rules (summary)

Rule authoring detail, scenarios, and direction pitfalls are in Setting access rules.

Setting access rules — scenarios and walkthrough

Optional relationship_access_rules describe row-level read/write policy using the instance graph. The HR pack uses hr_user as the subject; callers pass subject_id equal to user_id (e.g. alice.mgr).

HR scenarios in plain language

1. Self employee profile — A user may read an employee row when its email matches their hr_user.email (no graph hop).
2. Manager department team — Users whose role_title is a manager type may read employees in departments they manages_department (walk: employee → department → managing hr_user).
3. HR BP department — HR Business Partners may read employees in departments they hr_representative_for.
4. Compensation via visible employee — HR BP / HR Director / Department Manager roles may read a compensation_record only when it links to an employee they could already read (walk: compensation → employee, then check prior employee access).

Engineering Manager is in the manager rule but not in the compensation role list — so Alice sees Jane and John but not COMP-9001.

Who sees what

Demo rows and links (example_data)

Rule mechanics (path, match, prior access)

Each entry in rules[] targets one resource_entity_name with effect: allow (or deny).

Manager path (Alice → Engineering employees)

{
  "path": [
    { "relationship_name": "member_of_department", "direction": "forward",
      "from_entity_name": "employee", "to_entity_name": "department" },
    { "relationship_name": "manages_department", "direction": "reverse",
      "from_entity_name": "department", "to_entity_name": "hr_user" }
  ]
}

Plain language: start on an employee → their department → find an hr_user who manages that department → is it the requester?

Self access (match)

{
  "match": {
    "type": "field_equals_subject",
    "resource_field": "email",
    "subject_field": "email"
  }
}

Compensation (path + prior access)

{
  "resource_entity_name": "compensation_record",
  "path": [
    { "relationship_name": "compensation_for", "direction": "forward",
      "from_entity_name": "compensation_record", "to_entity_name": "employee" }
  ],
  "requires_prior_access_to": "employee"
}

direction: forward vs reverse

The most common authoring mistake. Direction refers to stored link orientation in entity_relationships, not informal English.

How to create your own playbook

Copy an existing pack (e.g. HR) as a template, rename id and filename, then edit schema, relationships, optional example_data, and optional relationship_access_rules.

Where files live

Ship playbook JSON under: dashboard/backend/src/playbook/playbooks/<id>.json

The dashboard catalog loader picks up all *.json files in that folder. Restart the dashboard backend if playbooks do not hot-reload. rdf-cache reads the same directory via PLAYBOOKS_DIR — restart rdf-cache after rule changes.

Author checklist

1. Identity — choose id, name, category; filename must match id.
2. Entities and fields — snake_case names; is_identifier on business keys; pick one subject entity if using ReBAC.
3. Relationships — declare subject → object consistently; document direction in instructions.
4. Example data — enough rows and links to exercise every relationship and rule path in Graph View and MCP.
5. Access rules (optional) — start with deny_by_default: true; add allow rules; verify each hop’s direction against stored links.
6. Implementation status — use catalog_only while drafting; set enforced when ready for MCP/data-layer filtering.
7. Install and sync — install from Playbooks UI; confirm Data Capsule / graph export.
8. Validate — use MCP list_allowed_rows and SPARQL with subject_id (see next section).

How to test via MCP

Prerequisites: install playbook, sync Data Capsule, rdf-cache + MCP running.

1. list_data_capsules — confirm hr-relationship-access cached.
2. list_allowed_rows with playbook_id: hr-relationship-access, subject_id: alice.mgr, entity_name: employee — expect two row ids.
3. Repeat for bob.mgr (one employee) and carol.hr + compensation_record (one row).
4. run_sparql with subject_id and SELECT ?row ?fullName ... — always include ?row when ReBAC is on.

See Documentation for MCP setup and environment variables.