Export and import runbooks

Edit online

Export and import runbooks by sending requests to the HTTP API. You can use existing tools to send requests, for example cURL, Postman for Chrome, or RESTClient for Firefox.

Before you can send requests, you need to create an API key for authentication. See API Keys for instructions how to create an API key.

In addition, determine the host name part of your IBM® Netcool® Operations Insight® user interface URL. The base URL for sending API requests has the format https://<netcool-operations-insight-hostname>, for example, https://netcool.apps.mycluster.mycompany.com.

When creating a runbook, an ID is automatically assigned to it. The ID is used when you create an Impact trigger to link the runbook to events that match a specific filter pattern. When you plan to export the runbook and import it later on (for example, to restore a backup version of the runbook after the runbook is removed), you must set the keepId parameter. The keepId parameter includes the runbook ID during the export. Setting this parameter helps ensure that the integrity of the Impact trigger can be preserved when the runbook is imported later on.

Depending on your certificate configuration, you might need to add the -k or --insecure options for the example curl commands.

Export Runbooks

The following two calls create output, which can be imported again.
Use the following API to export all runbooks (including runbook IDs):
GET api/v1/rba/runbooks?exportFormat=keepId
When enabling the option exportFormat via the query parameter, the usual output of the command is replaced by an array of JSON objects. These JSON objects can be used to create the runbooks by using the import API endpoint. The following call is an example:
curl -u <APIKeyUsername>:<APIKeyPassword> https://netcool.apps.mycluster.mycompany.com/api/v1/rba/runbooks?exportFormat=keepId
Replace <APIKeyUsername> with your username and <APIKeyPassword> with your password.
Use the following API to export a single runbook:
GET api/v1/rba/runbooks/<RunbookId>?exportFormat=keepId
Replace <RunbookId> with the ID of the runbook. You can retrieve this ID, for example, from the Edit Runbook window. The following call is an example:
curl -u <APIKeyUsername>:<APIKeyPassword> https://netcool.apps.mycluster.mycompany.com/api/v1/rba/runbooks/<RunbookId>?exportFormat=keepId > exportedRunbook.json
Replace <APIKeyUsername> with your username and <APIKeyPassword> with your password. Replace <RunbookId> with the ID of the runbook.

Import Runbooks

Use the following API to import runbooks:
POST api/v1/rba/runbooks/import
The following call is an example:
curl -H "Expect:" -H "Content-Type: application/json" -u <APIKeyUsername>:<APIKeyPassword> -d@./exportedRunbooks.json https://netcool.apps.mycluster.mycompany.com/api/v1/rba/runbooks/import
Replace <APIKeyUsername> with your username and <APIKeyPassword> with your password. Note: ./exportedRunbooks.json is the output file that is created from the previous example.
Note: If you previously exported a lot of runbooks (or some very large runbooks), you might face the 10 MB upload limit of the Runbook API when trying to import them again. The runbook file must be split into multiple JSON files, and each of these chunks must be imported separately. The following examples assume that you have the jq tool installed.
  • Example: Split by maximum file size
    If your runbooks do not reference any automation actions, or if your automation actions are not shared between multiple runbooks, you can use the following command to split the file into chunks of a maximum of 10 MB each, named exportedRunbooks.json.aa, exportedRunbooks.json.ab, etc.:
    cat exportedRunbooks.json | jq .[] -c | split -C 10485760 --filter='jq . -cs > $FILE' - exportedRunbooks.json.
  • Example: Split by automation actions
    If exportedRunbooks.json is larger than 10 MB and if it contains multiple runbooks that reference the same automation action, then try to group all these runbooks into a single chunk file. This avoids creating multiple copies of the same automation action during the import. You can use the following command to split the original file into multiple JSON chunk files, named exportedRunbooks.json.aa, exportedRunbooks.json.ab, etc. Each of these files contains all the runbooks that reference the same set of automation actions:
    cat exportedRunbooks.json | jq 'group_by(.automations)'[] -c | split -l 1 - exportedRunbooks.json.

General Notes® on export and import

  • Exporting runbooks returns the data of referenced automations inline. These automations are created new when the runbook is imported.
  • Import actions do not overwrite existing runbooks, automations, or both.
  • Exporting multiple runbooks at once will consolidate automations that are referenced by more than one runbook and only create the minimum necessary number of new automations.
  • Imported runbooks are in draft state and do not retain any kind of version, execution, or approval history. The user performing the import action is visible as the runbook creator.
  • Exporting runbooks returns the data of referenced runbooks depending on the chosen export format mode.
  • In normal mode, nested runbooks are exported in the "flat" structure, where all runbook references are resolved and runbooks are exported as if they did not contain references to other runbooks.
  • In keepId export mode, nested runbooks are exported while retaining their referencing structure. Referenced runbooks are included in the data as additional runbooks. Runbooks that are referenced by their latest version keep their ID. Runbooks that are referenced by a fixed version create an additional entry with a placeholder ID, which is replaced by a new random ID upon importing the data set.
  • Importing a data set which includes nested runbooks fails to create any runbooks referencing other runbooks if the "publish" flag is not set. This occurs because referencing other runbooks is only allowed on published runbooks, not on drafts.
  • When exporting multiple runbooks, ones with invalid nested runbook references and invalid automation action references will not be exported. The export will include all other runbooks, and all errors are logged in the runbook service.

For more information about creating an API key, see API Keys.

For more information about the API, see the Runbook Automation - API Documentation child page under Runbooks API.