# Runbooks

Write and publish your own runbooks, run them against a real job with a record of each step, group parts under a main process, and keep the runbooks your modules bring.

When a job must be done the same way every time, a written procedure and a record of who did it help. At Harbor Point Logistics, the IT lead writes "Set up a new PC for an employee" once, and each technician runs it against the new hire's name.

[Add it from the Marketplace](/tenant/?open=settings/marketplace)

## What it does

**Runbooks** is your company's how-to library. Each runbook is one job as ordered steps: who does each step, what to do, what you see when it worked, and why it matters. The **Workflow** diagram draws the steps in lanes, one per role, and a red **Stop** box marks a step that must not be skipped.

A **run** is one time someone does the job for real, with a record of each step. The library also holds the runbooks your other modules ship.

## Set it up

1. Add **Runbooks** from the Marketplace. See [Marketplace: add or remove a module](article:5bf25be1-f0e9-40e4-9ef9-70ac8532cd9b).
2. Open its Module Settings from the **⋮** on the module's sidebar row. Set the default category for new runbooks and the model **✦ Assist** uses. See [Module settings and versions](article:fb7c92e4-6dcc-4ef4-80bc-1b6e7482e540).
3. Give **Read runbooks** to everyone who follows procedures, **Run a runbook** to people who carry them out, and **Write and edit runbooks** to the people who own them. See [Users and roles: roles and permissions](article:888a2a90-7990-4ea5-a58e-af06f56b1bfd).
4. Have someone with **Write and edit runbooks** open **Runbooks** once, so the runbooks your modules ship come into the library.

## Find and read a runbook

1. Click **Runbooks** in the sidebar. The tiles count your runbooks, the published ones and the runs in progress.
2. Type the task, system or equipment in **Search — task, system, equipment**. The search also looks inside the steps, and shows the step that matched under the title.
3. Narrow a long list with **All categories** or **Any status** (Published, Draft, Archived).
4. Click a runbook's row. It opens in a panel beside the list.
5. Read **Who takes part** and the **Workflow**. Click a box on the workflow to jump to that step. **Open full size** shows it large, with **−**, **+**, **Fit** and **100%**; **Close** or Esc returns.
6. Read **Before you start**, then each step's instructions, **Why** and **Done when**.

## Write and publish a runbook

1. Click **New Runbook**. Type the title as someone would ask for the job and click OK. The new runbook opens in the editor as a draft. To change an existing one, open it and click **Edit**.
2. Fill in **Title**, **Category**, **Applies to**, **Tags**, **Minutes**, **Owner**, **Purpose — what this does and when to use it** and **Before you start**. Click **Save Runbook**.
3. Click **Add Step** for each step; it adds a step called "New step" at the end straight away. Or click **Paste rough notes…**, paste your notes, click **✦ Assist**, check the numbered list, then click **Create steps from list** and confirm.
4. For each step, fill in its title, **Who does it** (a role title, never a person's name), **Instructions**, **Expected result** and **Why this step matters**. Click **Save Step**.
5. Optionally add a **Marker on the workflow** for a milestone, a **Warning** that shows as a **STOP POINT**, or a screenshot with **+ Add picture** (up to 15 MB) and its **Caption**.
6. Use the up and down arrows to put the steps in order.
7. Set **Status** to published and click **Save Runbook**. Click **Done** to see the runbook as others will.

Keep each runbook to one job, about 3 to 12 steps. **✦ Assist** on a field tidies the wording you wrote; it does not add steps or details. Pictures, new steps and the arrows save at once; other changes to a step need **Save Step**, and changes to the details need **Save Runbook**. To retire a runbook, set **Status** to archived. **Delete Runbook** removes it for good but keeps its run history.

## Track runs and fix what blocked people

1. Open a runbook and click **Start Run**. Type what the run is for: a job, customer, person, truck or machine.
2. Mark each step **Done**, **Skip** or **Blocked**. Skip asks why; Blocked asks what happened.
3. The run completes when every step is done or skipped. **Abandon** stops a run and keeps its record.
4. **Active runs** lists runs with the runbook, who they are for, who ran them, when they started and their status. Click one to carry on. **Back to library** returns to the list.

As the owner, read the notes on blocked steps and fix the runbook so the next person isn't stopped there. Edits never change past runs.

For how an ordinary user finds and follows a runbook, see [Find and follow a runbook](article:4b62ad1f-577a-4998-8bce-f00226376522).

## Main processes and module runbooks

**Main processes.** When a job is too long for one runbook, write a main-process runbook with one short step per part, and each part as its own runbook. A linked part shows **Part of the main process**; click it to go back up. The main process lists **The processes in this runbook**; click one to open it. The editor has no place for links yet: they come with runbooks loaded from a file, such as those a module ships.

**Module runbooks.** Your modules' runbooks come into the library, already published, when someone who can write runbooks opens it. On its page, a module's runbook names its module and says it is updated when the module is. They refresh when the module updates; one the module drops is archived. Don't edit them in place, because the next update replaces your changes. Click **Make a copy** instead: the copy opens in the editor as a draft named "(our copy)", and updates never touch it. Edit it and publish it.

## Who can do what

Each action in the module needs a permission. A Workspace Admin gives permissions to roles; see [Users and roles: create and edit roles](article:88d4e232-d5b8-4909-b452-cfe96d3d550f). **Out of the box** shows the module's starting roles that have it.

| Permission | What it lets someone do | Out of the box |
|---|---|---|
| **Read runbooks** | Search and read runbooks and see past runs. | Admin, Operator, Viewer |
| **Run a runbook** | Start a run and check off, skip or block its steps, and abandon runs. | Admin, Operator |
| **Write and edit runbooks** | Create, edit, publish, archive and delete runbooks and their steps and pictures, and use Assist. **Give with care.** | Admin, Operator |

## Ask its agent

The **Runbook Guide** finds the right runbook, walks you through it one step at a time, and records the run as you report back. Try:

- "What runbooks do we have for equipment configuration?"
- "Walk me through setting up a PC for a new floor employee."
- "Start a run of the new-hire PC setup for the new warehouse clerk."

It only tells you what the runbook says. See [Agent chat](article:073c6465-d85c-4364-8768-acf42a3a6a48).

## Good to know

- **Publish only after someone who does the job has read it.** People and the AI treat a published runbook as the way it is done.
- **Print a runbook** with the printer button at its top, next to **Edit** and **Start Run**. It prints the runbook alone.
- **Archiving a module's runbook doesn't last.** The next time someone who can write runbooks opens the library, the module's runbook comes back published. Keep your copy and leave the original alone.

## More help

Open **Help** in the module for its runbooks on each of these jobs. The Knowledge Base module can link articles to your published runbooks. See [Module help and Show me](article:53508199-cd90-4a4c-a453-f6e5c68bdd8e).


Source: https://datavisions.ai/docs/module-guides/runbooks
