Export and import runbooks

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 and navigate to section Get authentication by using Zen API Key for instructions on how to create and encode an API key (ZenApiKey).

In addition, determine the host name part of your IBM Cloud Pak for AIOps user interface URL. The base URL for sending API requests has the format https://<waiops-hostname>, for example, https://cpd-cp4waiops.apps.mycluster.mycompany.com.

Runbooks are identified by an ID that gets generated when you create the runbook. For example, this ID is used when you create a runbook policy to link the runbook to alerts that match a specific filter pattern. When you plan to export the runbook and import it again at a later time (for example, to restore a backup version of the runbook after the runbook has been removed), you must use the "keepId" parameter to include the runbook ID during the export. This is so the integrity of the runbook policy is preserved when the runbook is imported later on.

Depending on your certificate configuration, you might need to add the "-k" or the "--insecure" option for the sample curl commands listed below.

The export call returns an encryption token in the "x-rba-encryption-token" header. This encryption token is used to encrypt sensitive data in the exported runbooks including fixed value mappings for password parameters and authentication credentials for HTTP automation actions. The encryption token is required on import to decrypt the encrypted sensitive data. The encryption token can be passed to the import call by using the "encryption" query parameter. Alternatively, you can drop encrypted data by setting the "ignoreEncryptedData" query parameter to "true".

When using curl, you can use the "-D header.txt" argument to write the response headers of the export call, which includes the encryption token, to a file named header.txt.

Important: Store the encryption token separately from the exported runbooks and in a secure place as it can be used to decrypt the encrypted sensitive data.

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 --header "Authorization: ZenApiKey <ZenApiKey>" -D header.txt https://cpd-cp4waiops.apps.mycluster.mycompany.com/aiops/api/story-manager/rba/v1/runbooks?exportFormat=keepId

Replace <ZenApiKey> with the encoded Platform UI (Zen) API key token that you created before.

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 --header "Authorization: ZenApiKey <ZenApiKey>" -D header.txt https://cpd-cp4waiops.apps.mycluster.mycompany.com/aiops/api/story-manager/rba/v1/runbooks/<RunbookId>?exportFormat=keepId > exportedRunbook.json

Replace <ZenApiKey> with the encoded Zen API key token that you created before. 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" --header "Authorization: ZenApiKey <ZenApiKey>" -d@./exportedRunbooks.json https://cpd-cp4waiops.apps.mycluster.mycompany.com/aiops/api/story-manager/rba/v1/runbooks/import?encryption=<EncryptionToken>

Replace <ZenApiKey> with the encoded Zen API key token that you created before. Note: ./exportedRunbooks.json is the output file that is created from the previous example.

Replace <EncryptionToken> with the value of the x-rba-encryption-token response header received during export. If you do not have the matching encryption token or do not want to import encrypted sensitive data you can specify "ignoreEncryptedData=true" instead of "encryption=<EncryptionToken" to import everything but the encrypted sensitive data.

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 Automation (runbook) API.