Runbook Documents

Runbooks allows users to document the optimal and consistent way to respond to events. Users are guided through a series of predefined steps to accomplish a specific outcome via manual steps.

Getting Started

Navigate over to the Blameless UI, and from the main navigation menu click on Runbook Documents.

Runbooks section

Runbooks List

Here you can view all created Runbooks at a glance and perform custom filtering and sorting. From this view you can also create new Runbooks and interact with existing Runbooks.

Filtering

Using the filter input, you can filter Runbooks by Name, Description and Steps Count fields.

Runbooks filter

Sorting

You can sort Runbooks by Name, Description, Steps, Created and Updated fields

Runbooks sort
note

By default it will sort by Created field, in Descending ↓ direction.

List

Existing Runbooks will be listed here.

Runbook list items

Each Runbook listed here will have a color and an icon to identify the status of the last used Runbook Document.

Runbook list item

Hovering over the status icon will present additional information for the runbook status if applicable.

State hover

Clicking on the more actions menu in the top-right corner of a runbook item opens a context menu with different options:

  • Edit: Alows the user to edit runbook properties
  • Runbook Steps: Allows the user to edit runbook steps
  • Remove: Removes the runbook
Runbook item context menu

Creating a Runbook Document

You can create a new runbook by clicking the + NEW RUNBOOK button in the top-right corner.

Create runbook button

You will be prompted with a side modal to complete basic runbook fields.

Create new runbook
FieldDescriptionDefaultRequired
NameRunbook nameTrue
DescriptionRunbook descriptionFalse
View Mode- Default: Show each step within a box so you can easily differentiate between steps.
- Compact: Show steps without any wrapper so that the runbooks appears like one long document.
DefaultTrue

Runbook Details Page

Once you create a new runbook, you'll be redirected to its details page.

Details page

Summary Sidebar

Here you can find general information pertaining to the current runbook:

Summary sidebar
  • Actions: Available actions for the current runbook (runner actions are only visible in runner view)
  • Created by: Show the user who created the runbook.
  • Updated by: Show the user who last updated the runbook.
  • Description: Runbook description.
  • Created: Runbook created date.
  • Updated: Runbook last updated date.
  • Last Used: Show the datetime when the runbook document was last used.
  • Resource Name: Show resource associated to the runbook, if applicable (i.e Incident).
  • Resource Id: Show resource ID, if applicable (i.e Incident ID).
  • History: Show the historical usage, if applicable.

Editing a Runbook

In the top-right corner, there is an EDIT RUNBOOK button, clicking that button allows you to edit basic runbook properties such as Name, Description and VIEW MODE.

Edit runbook modal

Steps Tab

From the steps tab, you can easily view the steps in your runbook or create new ones. After creating a new runbook, this will initially be empty, so you'll be prompted with a message and a button to start building steps.

Empty step tab

Clicking the BUILD STEPS button or the Pencil Icon in the actions section, you can start building your runbook steps.

Build steps

Usage History Tab

From the Usage History tab, you can view the historical usage of the runbook document, as well as preview current runbook steps.

Runner running

Building Steps

From the steps builder UI, you can start creating steps for your runbook by clicking the CREATE STEP button.

In the left panel you can see all the steps you've created, and clicking on a step show the details in the right panel.

Steps builder

Step Title

By default, steps will be named New Step (n), you can change that and add a custom name to you step from the Title input.

Step title

Requiring Feedback

If the task type allows it, you can prompt the user for explicit feedback after the task is completed in the runner.

Require feedback

When Need Feedback is enabled and the task is completed, the user can add additional feedback.

Feedback task

You can create different tasks. The following table describes them:

NameDescriptionExample
Text BlockLog and print any message to the screen. Supports the use of state and global variables.Text Block
Rich Text BlockSimilar to Text Block with rich text capabilities. Supports the use of state and global variables.Rich Text Block
Code SnippetDisplay a code editor that allows you to select between more than 50 languages with syntax highlighting. Supports the use of state and global variables.Code Snippet
Custom FormUse this task to create you own form with JSONSchema.custom form

Ordering Steps

If you need to change the order of steps, you can easily drag and drop them.

Sort steps

Cloning Steps

If you've created a step that you'd like to reuse across multiple runbooks or even in your current runbook, you can click the Duplicate step to runbook button for the step you want to clone and then select a runbook as a destination.

Clone step

Attaching Runbooks to Incidents

If you want to attach one or multiple Runbooks to an existing Incident, you can do that from the Runbooks Tab on an Incident details page.

Attach runbook to an incident

Usage History

The usage history tab shows the historical usage of your runbooks, the runbook metadata and its associated resources (e.g. incidents).

Delay runner

Runbook History

When a runbook is attached to a resource (e.g. an incident), it will create and associate an instance of that runbook to the resource. Creating an instance of the runbook allows us to create a snapshot of the runbook at a given time. This is useful for historical usage tracking, especially as Runbook contents continue to evolve.

Runbook Instance Status

You can see the current instance status in the Usage History Tab and also in the Runbooks List for each runbook.

There are many different statuses for a given runbook instance:

StatusColorIconDescription
COMPLETEDstatus completedRunning instance has been completed successfully.
RUNNINGstatus runningRunbook instance is running.
INTERACTIONstatus interactionA step requires user interaction.
PAUSEDstatus pausedRunbook instance has been paused.
FAILEDstatus failedRunbook instance failed in a step.
CANCELEDstatus canceledRunbook instance canceled by the user.

Instance History

If you're in the Usage History Tab, you can see all previous and current instances of the runbook at the bottom of the Summary Sidebar under the History section.

If you click one of the previous instances, you'll see a snapshot of the instances at that given time.

Instance history