You can configure integrations at a runbook level, meaning you can trigger these integrations at any time; you don’t require a runbook to have started or a specific task to have completed. An example of using this feature could be where a runbook level integration has been set up to create a Change Request in ServiceNow. The integration will link the Change Request and Runbook ID. When a change is made to the runbook edit panel, this will trigger the integration and update ServiceNow with the variables you are updating.
Note: Only custom integrations can be configured as runbook-level integrations. It is not possible to change an existing custom integration from task level to runbook level or vice versa. You will need to create a brand new integration specific for a runbook level or task level integration each time.
These integrations can be selected within a runbook and can be triggered in two ways:
Automatically when an update is made, in the UI or via an endpoint that utilises the Public API:
in the Runbook Details panel and/or
within the Pages tab (see after step three of Set up a runbook-level integration)
Manually by clicking on Run Integration under the integration’s listing in the Runbook Integrations side panel (see step four of Link and execute a runbook-level integration within a runbook).
Prerequisites
You should create a new integration and choose the trigger as On Runbook Update.
You will require the following permissions to create runbook-level integrations:
The Runbook Admin role to edit existing runbook-level integrations and link them to a runbook
Both the Custom fields admin and Integrations admin roles to configure new integrations
Set up a runbook-level integration
Follow these steps to configure a runbook-level integration:
Go to Settings > Integrations and click + to create a new custom integration.
When editing your new custom integration, click + NEW under Integration Actions.
In the General tab, ensure you select the On Runbook Update trigger when creating your action. You can read more about our Custom Integrations in our Developer Portal.
Warning: Please be advised that by choosing the On Runbook Update trigger, the integration will begin every time something is updated.
The On Runbook Update trigger automatically starts the integration whenever something is updated in either:
The Runbook Details panel
Or the runbook’s Pages tab
Each time any details are changed, the integration will fire and re-fire.
Note: You cannot enable/disable runbook-level integrations during a live or rehearsal run or in approved templates. However, you can use the Re-fire and Run integration button and view the Action Log. Runbook-level integration custom fields can also be added, edited and changes saved whilst in a live or rehearsal state.
Link and execute a runbook-level integration within a runbook
By default, runbook-level integrations aren’t linked to runbooks. Similar to task level integrations they need to be added to the runbook in order to get invoked. To link and execute them, follow these steps:
Note: The runbook integrations icon (mentioned in the second step) will only be available in a runbook's side panel if you have configured an integration with the On Runbook Update trigger.
Select an existing runbook, or create a new runbook.
Click the runbook integrations icon in the runbook’s side panel.
In the Runbook Integrations panel, enable an integration by toggling it on. This will enable you to configure custom fields that you require for this specific integration.
4. If you wish to manually execute an integration as opposed to letting it automatically execute, click Run Integration as shown in the image below.
Note: If you toggle the switch to off, it will no longer be linked to the runbook and won’t be able to be triggered automatically or manually.
Note: A runbook-level integration can be executed in all of the following runbook states:
During the planning stage
During a rehearsal run
During a live run
This feature can be configured for all runbook type templates. For approved templates, you will need to have the Integrations Admin role to modify runbook-level integrations.