Create and run a Playbook
Playbooks are reusable, executable workflows. You author a branching graph of steps once, publish it, and Hub runs a controlled instance of it each time a qualifying event occurs. They live in **Settings → Building blocks**, alongside Pipelines. ## When to use a Playbook Use a Playbook when a process needs to: - Follow a defined sequence of human tasks and decisions. - Branch based on a condition or an AI assessment. - Take automatic record actions at specific points. - Run consistently every time it is triggered, with a full execution history. Typical examples include enquiry triage, onboarding checklists, approval flows and issue escalation. ## Before you begin - You must be a workspace owner or administrator. - Decide the record type the Playbook will run against. - Create a task-enabled collection for Hub tasks linked to the Playbook (see *Create and sync tasks with Notion*). The task collection must have at least one open status. - Identify your triggers: one or more **form submissions**, **pipeline stage entries**, or **manual starts** from a record. - Assign at least one workspace member as the fallback assignee for human steps. ## Create a Playbook 1. Open **Settings → Building blocks**. 2. Select the **Playbooks** tab. 3. Select **New playbook**. 4. Give the Playbook a clear name. 5. Choose the **record types** it applies to. 6. Choose the **task collection** that will hold Hub tasks for human steps. 7. Set the **fallback assignee** — the member tasks are assigned to when a step has no specific assignee. 8. Design the graph (see below). 9. Add at least one trigger under **Starts**. 10. Save and publish the Playbook. 11. Enable it to allow new runs to start. ## Design the graph Playbooks are designed in **Outline** or **Canvas** view. Each Playbook is a directed graph of connected steps. ### Step types | Step type | What it does | |---|---| | **Guidance** | Provides instructions to the assignee. No decision required; continues automatically. | | **Human task** | Creates a Hub task for a team member. The run waits until the task is completed. | | **Human decision** | Creates a Hub task and presents named outcome choices. The assignee selects an outcome to advance the run. | | **Rule condition** | Evaluates a field value on the record and branches automatically (Yes or No). | | **AI assessment** | Asks Hub's AI to assess the record and recommend an outcome. The assignee confirms or overrides the recommendation. | | **Action** | Applies an automatic record action (assign, tag, set field, set status, create task, create record, notify, send email, send Slack message, or call a webhook). | | **Wait** | Pauses the run for a configured number of seconds before continuing. | | **Finish** | Ends the run. | ### Connecting steps - In Outline view, select a step and use the inspector to connect it to the next step. - In Canvas view, drag a connection from a step's exit handle to the next step. - Decision, assessment and condition steps have multiple named exits. Connect each exit to the appropriate next step. - Steps can converge on a shared continuation — for example, all decision branches meeting at a single **Action** or **Finish** step. ### AI assessment steps AI assessment steps use Hub's AI to classify the record using the inputs you choose. The AI provides a recommended outcome and an explanation, along with references to the input values it used. The assigned member can accept the recommendation or choose a different outcome. Assessment steps default to requiring **human confirmation** — the AI cannot advance the run on its own without the assignee's review. ## Preview a Playbook Before publishing, select **Preview** to simulate running the Playbook without any effects. Preview shows how the graph would execute for a representative record and confirms that connections and conditions are valid. ## Publish and enable Publishing captures an immutable snapshot of the Playbook definition. Each run uses the version that was published when it started — edits to the draft do not affect running instances. After publishing: 1. Toggle the Playbook to **Enabled**. 2. Confirm that your configured triggers are active (form published, pipeline stage active, or records available for manual start). ## Triggers A Playbook can be started from three sources. Configure them under **Starts** in the editor. | Trigger | How it works | |---|---| | **Form submission** | Hub starts a run automatically when a response is submitted to a selected form. The form must be published. Only persisted responses from the form service start Playbook runs. | | **Pipeline stage entry** | Hub starts a run when a record enters a selected stage of a selected pipeline. The run is checked against the current stage at the moment it begins. | | **Record (manual start)** | A team member opens a matching record and selects **Start** in the **Playbooks** panel on the record's detail page. | ## Run lifecycle Once started, a run moves through your graph step by step. Each run has one of these statuses: | Status | Meaning | |---|---| | **Running** | The run is advancing through automatic steps. | | **Waiting** | The run is paused at a Wait step. | | **Awaiting task completion** | A Human task step is waiting for its Hub task to be completed. | | **Awaiting review** | A Human decision or AI assessment step is waiting for a team member to choose an outcome. | | **Completed** | The run reached a Finish step. | | **Failed** | An error prevented the run from continuing. | | **Cancelled** | A team member or administrator cancelled the run. | ### Task completion When a Human task step is reached, Hub creates a linked task in the configured task collection. The task is assigned to the step's assignee (or the fallback assignee). Completing the task advances the run. > **Playbook tasks are controlled by the run.** Status and completion changes on a Playbook-linked task are managed by the Playbook, not by direct record edits. Choose an explicit outcome in the **Playbooks** panel to complete a decision step. ### Retry and cancellation Failed runs can be retried from the **Playbooks** panel on the record detail page. Administrators can cancel a run from the same panel. A cancellation reason is recorded in the run log. ## View run history and progress Open a record to see its **Playbooks** panel. The panel shows: - Active and recent runs for that record. - The current step and its status. - The full run log: each completed step, its outcome, and when it completed. - For AI assessment steps: the recommended outcome, explanation and supporting inputs. - Controls to resolve pending decisions, retry failed steps or cancel the run. Administrators can also see all runs across all records from the Playbook editor. ## Bind a Playbook to a form or pipeline stage To attach a Playbook to a form or pipeline stage without opening the Playbook editor: 1. Open the form or pipeline stage settings. 2. Find the **Executable playbooks** disclosure. 3. Check the Playbook you want to attach. The change is saved to the Playbook's draft. Publish and enable the Playbook to activate it. ## Execution guarantees - Published definitions are snapshotted at run start. Draft changes do not affect running instances. - Form and pipeline triggers deduplicate: the same event cannot start the same Playbook twice on the same record. - Record actions applied by Action steps are tracked as Playbook transitions in the record's history. - Decisions and task completions are transactional — the run state and the record update happen together or not at all. - Controlled retry resumes from the last committed step, not from the start. ## Limitations - A Playbook can only run against record types listed in its configuration. - Assignees must have current record edit access at publish time. Reassign steps before publishing if a member's role has changed. - The task collection must not have required fields beyond the ones a Playbook can supply (subject, linked record, due date). - Stage-triggered runs are checked at the moment they start. If the record has already moved to a different stage, the run is skipped.