Integrate Approval Workflows into your Runbooks

Introduction

Sometimes a workflow needs to have an explicit approval by a person to make a decision. Often this decision needs to be correctly stored and retrieved for audit purposes.

Luckily the Runbooks feature from IBM Watson AIOps can easily provide this in separate ways, so you can directly add those approvals into your Runbooks and allow them to feature this capability.

In this post, I am going to share two ways of doing such an approval and provide the skeletons of two example runbooks as an easy starting point for you to write your own runbook containing an approval step.

Approval via Parameter

The first way to implement an explicit approval into a runbook is using the parameter feature. With the introduction of parameter types this becomes much more elegant, as you can leverage a parameter of type "boolean" to model a yes-no-decision.

Concept

The concept consists of the following steps:

1. Create a boolean parameter representing the approval decision. Choose type "boolean" and default value "false".
2. Author your runbook. Create a step for the approval decision. Add all the information necessary to make that decision into it and inform the operator, that the decision will be final, once the "Next Step" button is clicked. The decision is made, by setting the value of the parameter.
3. The remaining steps of the runbook take the value of the parameter into account.

Example Skeleton Runbook

Skeleton Runbook on Public Runbook Share Repository

The Skeleton Runbook implements the "Approval via Parameter" workflow. The parameter is named "approval". You can create this runbook in your environment by using the Runbook Automation API and send the content of this JSON file to the API endpoint POST /api/v1/rba/runbooks.

Track and Audit

Runbook Automation safely and indefinitely stores the information who set the parameter and when that parameter was set. This information can be retrieved with the Runbook Automation API endpoints GET /api/v1/rba/runbookinstance and GET /api/v1/rba/runbookinstance/${runbookInstanceId}. The former is used to retrieve multiple execution records at once, while the second retrieves exactly execution record.

In any case, every Runbook Instance contains a history section, which tracks all actions and which parameters are set. For our Runbook this section contains the relevant data in Step 2, as this is the step where the approval decision is made:

"history": [
  {
    "action": "complete",
    "step": 1,
    "processedAt": 1620284225171,
    "processedBy": "johndoe@ibm.com",
    "parameters": {
      "approved" : false
    }
  },
  {
    "action": "complete",
    "step": 2,
    "processedAt": 1620284299999,
    "processedBy": "johndoe@ibm.com",
    "parameters": {
      "approved" : true
    }
  },
  {
    "action": "complete",
    "step": 3,
    "processedAt": 1620284311111,
    "processedBy": "johndoe@ibm.com",
    "parameters": {
      "approved" : true
    }
  }
]​

Here we can see, that johndoe@ibm.com did complete the step 2 at 1620284299999 (which is a Unix timestamp and means 2021-05-06 06:58 UTC) and set the parameter "approved" to true. Thereby creating a record of the approval action.

Approval via GoTo

The second way to implement an explicit approval into a runbook is using the GoTo element. You can efficiently use the GoTo feature to skip any number of steps or even the whole remaining runbook. If certain actions depend on an approval skip them, if the approval is rejected.

Concept

The concept consists of the following steps:

1. Author your runbook. Create a step for the approval decision. Add all the information necessary to make that decision into it and inform the operator, that the decision will be final, once either the "Next Step" button is clicked or the GoTo element is clicked. Clicking "Next Step" means approval. Clicking "GoTo" means rejection.
2. The following steps of the Runbook contain the actions only to be done, if an approval was made.

Example Skeleton Runbook

Skeleton Runbook on Public Runbook Share Repository

The Skeleton Runbook implements the "Approval via GoTo" workflow. The decision for approve or reject is made in Step 2 of the Runbook. You can create this runbook in your environment by using the Runbooks API and send the content of this JSON file to the API endpoint POST /api/v1/rba/runbooks`.

Track and Audit

Runbook Automation safely and indefinitely stores the information which steps were completed normally and which steps were left by using a GoTo action. This information can be retrieved with the Runbook Automation API endpoints GET /api/v1/rba/runbookinstance and GET /api/v1/rba/runbookinstance/${runbookInstanceId}. The former is used to retrieve multiple execution records at once, while the second retrieves exactly execution record.

In any case, every Runbook Instance contains a history section, which tracks all actions including how steps are processed. For our Runbook this section contains the relevant data in the second action, as this is the action taken in step 2, where the approval decision is made:

"history": [
  {
    "action": "complete",
    "step": 1,
    "processedAt": 1620284225171,
    "processedBy": "johndoe@ibm.com",
    "parameters": { }
  },
  {
    "action": "goTo",
    "step": 4,
    "processedAt": 1620284299999,
    "processedBy": "johndoe@ibm.com",
    "parameters": { }
  }
]​

Here we can see, that johndoe@ibm.com did complete the step 1 and then (in Step 2) used a goTo action to jump to step 4 at 1620284299999 (which is a Unix timestamp and means 2021-05-06 06:58 UTC). Thereby creating a record, that the approval has been rejected. For all full documentation of the Runbook Automation API refer to the official IBM Documentation.
#AIOps
#cp4waiops
#runbook
#Automation
#WorkflowAutomation
#workflow
#Featured-area-2
#Featured-area-2-home