Skip to main content

Using Blameless Runbooks

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 Landing Page

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: Allows 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

  1. Click on the + NEW RUNBOOK button in the top-right corner. You will be prompted with a side modal to complete basic runbook fields:

    • Name
    • Description
    • View Mode
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 runbook 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, the Runbook Summary information, as well as preview the current runbook steps.

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 shows 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 your step from the Title input.

Step title

Task types

You can select from different task types for each Step, as described in the following table

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

Text Blocks, Rich Text Blocks, and Code Snippets allow the use of supported variables.

Building Rich Text Blocks

Rich Text allows the Runbook user to create hyperlinked text and apply styles within the steps.

  1. Usera must select the text they want to hyperlink.
  2. A tooltip with a set of tools appears.
  3. Select the link option (link symbol). A empty text field appears.
  4. Enter a valid URL (e.g. https://www.google.com) and type "ENTER".

The selected text is now hyperlinked in both Runbook document editor and read modes.

Supported Variables

Blameless supports the following global variables:

${global.user.name}
${global.user.email}
${global.incident.id}
${global.incident.type}
${global.incident.severity}
${global.incident.channel.id}
${global.incident.channel.name}
${global.incident.channel.url}

Custom Form

The custom form allows you to add a step in a Runbook to require users to capture information when running this Runbook after it is attached to an incident.

UI Schema Sample

The UI schema is not a required field for the custom form, however, if it is not filled in, the Blameless default UI schema will be used.

The following is a sample UI Schema that you can copy and paste and update to your needs:

{
"firstName": {
"ui:autofocus": true,
"ui:emptyValue": "",
"ui:autocomplete": "family-name"
},
"lastName": {
"ui:emptyValue": "",
"ui:autocomplete": "given-name"
},
"age": {
"ui:widget": "updown",
"ui:title": "Age of person",
"ui:description": "(earthian year)"
},
"bio": {
"ui:widget": "textarea"
},
"password": {
"ui:widget": "password",
"ui:help": "Hint: Make it strong!"
},
"date": {
"ui:widget": "alt-datetime"
},
"link": {
"ui:widget":"LinkWidget",
"ui:hidden": false,
"ui:href":"http://blameless.com"
},
"telephone": {
"ui:options": {
"inputType": "tel"
}
}
}

JSON Schema Sample

The following is a sample JSON Schema that you can copy and paste and update to your needs:


{
"title": "A registration form",
"description": "A simple form example.",
"type": "object",
"required": [
"firstName",
"lastName"
],
"properties": {
"firstName": {
"type": "string",
"title": "First name",
"default": "Chuck"
},
"lastName": {
"type": "string",
"title": "Last name"
},
"telephone": {
"type": "string",
"title": "Telephone",
"minLength": 10
}
}
}

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).

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.