API usage scenario

Edit online

The following example demonstrates how the Runbook Automation API can be applied in a more complex workflow scenario. In this scenario, a user wants to integrate an external program with IBM® Runbook Automation. The external program should scan the runbook repository and add a new step to all runbooks where the runbook contains a tag with the content addstep. Additionally, the external program should only consider runbooks that have been published.

Get a list of all available runbooks
The application calls the API endpoint GET /api/v1/rba/runbooks to retrieve a list of all runbooks. Looking at the complete response model of the runbook, it becomes clear that the program must only evaluate the fields runbookId, steps and tags. Steps and tags are on the root level of the document, but runbookId is part of the readOnly section. As only published versions are relevant, the query parameter version is set to approved. The complete call, as provided by the Swagger UI, is:
```
curl -X GET --header 'Accept: application/json' 'https://netcool.apps.mycluster.mycompany.com/api/v1/rba/runbooks?version=approved&fields=readOnly%2Csteps%2Ctags'
```
The response is a JSON array with each entry containing the properties readOnly, steps and tags.
Output processing by external program
The user writes logic to the external program in order to filter the output. All entries of the JSON array where the tag array does not contain an entry with addstep are discarded. Of the remaining entries, the runbookIds are stored together with the steps in a data structure, as per the following JSON format:
```
[
  {
    "runbookId" : "$runbookId",
    "steps" : [ … ]
  },
  (…)
]
```
Within the steps section, the external program changes the content by adding a new step at the end that contains the static content required by the user. For example, an existing runbook with the following steps:
```
steps : [
  {
    "number" : 1,
    "description" : "Log in to the system and install the latest updates provided by the OS vendor."
  }
]
```
Would be extended to:
```
steps : [
  {
    "number" : 1,
    "description" : "Log in to the system and install the latest updates provided by the OS vendor."
  },
  {
    "number" : 2,
    "description" : "To conclude this runbook, reboot the system."
  }
]
```
Change the runbooks
The user creates a for-each loop in the external program that iterates over the data structure created in step 2. For each entry, the external program calls the API endpoint PATCH /api/v1/rba/runbooks/:runbookId (where :runbookId is the ID of the runbook from the data structure previously shown). The steps section of the prepared data is sent to the body. An example call for a runbook with the ID 7ef63332-5a3e-40f7-a923-af3ffb6795d3 and a steps section as previously described would look as follows:
```
curl -X PATCH --header 'Content-Type: application/json' --header 'Accept: application/json' -d ' \ steps : [ \ { \ "number" : 1, \ "description" : "Log in to the system and install the latest updates provided by the OS vendor." \ }, \ { \ "number" : 2, \ "description" : "To conclude this runbook, reboot the system." \ } \ ] \ ' 'https://netcool.apps.mycluster.mycompany.com/api/v1/rba/runbooks/7ef63332-5a3e-40f7-a923-af3ffb6795d3'
```

Summary

By using the Runbook Automation API in an external program, you can automatically and systematically change a large number of runbooks based on the data already present in the system.