The StatusDashboard ServiceNow integration facilitates communication between a ServiceNow account (via a ServiceNow business rule), and a StatusDashboard account (via inbound webhooks) for the purpose of automatically updating one or more status dashboards (and sending notifications) whenever incidents are created or updated in ServiceNow.
How it works
There are three steps required to enable the ServiceNow integration:
- Enable inbound webhooks in your StatusDashboard account. To enable inbound webhooks, navigate to Admin > Integrations > Webhook (Inbound) in the StatusDashboard administration portal. From here, enable the Webhook Endpoint, the Webhook Secret, and the External Service Ids.
- Map relevant services/applications from your ServiceNow account to StatusDashboard services. To perform this mapping, navigate to the StatusDashboard global services list Admin > Services. From here, edit any service and scroll down to the "Webhook (Inbound)" field and input the sys_id of the relevant ServiceNow service into the "External Service ID" field. Any StatusDashboard services that will be updated via ServiceNow will require a mapping. To locate ServiceNow services, perform the following:
-
- Type "cmdb_ci.list" in the ServiceNow navigation filter
- Search for the service in question
- Click on the name of the service
- Click on the three horizontal lines in the upper left of the screen next to the service name, and select "Copy sys_id"
-
- Create a ServiceNow business rule that triggers whenever updates are made to the ServiceNow incident table. This business rule will create, sign and send a webhook to StatusDashboard with all relevant information on the event. To create the business rule, perform the following:
-
- Navigate to System Definition > Business Rules in ServiceNow.
- Create a new Business Rule with the following attributes:
- Name: StatusDashboard Webhook
- Table: Incident [incident]
- Advanced Checkbox: Checked
- When to run tab:
- When: after
- Insert & Update checkboxes: checked
- Advanced tab: Include the StatusDashboard integration script in the script field. The script can be found in the StatusDashboard GitHub repository.
-
Business Rule Script Options
The StatusDashboard / ServiceNow business rule script has the following options which can be set at the top of the script:
Option | Description |
Debug boolean |
Set to true if you are having trouble getting the business rule script to work and you want to enable debug logging in the ServiceNow system log. |
endpoint string |
This is the custom endpoint that is unique to each StatusDashboard customer. The endpoint can be acquired by navigating to Admin > Integrations > Webhook (Inbound) in the StatusDashboard administration portal. |
secret string |
The secret used for signing webhooks. When webhook signing is configured in your StatusDashboard inbound webhooks configuration, any webhooks received by StatusDashboard that are not signed are discarded. You are highly encouraged to sign webhooks. If no secret value is provided, webhooks will not be signed by the ServiceNow business rule script. |
statusMapping dict |
This is a mapping dictionary between the ServiceNow 'state' and the StatusDashboard 'status'. Incidents created/updated in StatusDashboard must have one of the following statuses: investigating, identified, monitoring, resolved. This mapping dictionary uses the ServiceNow state to set the desired status for incidents. For example, in the default mapping dictionary, if a ServiceNow incident has a state of "New", then the event will be created/updated in StatusDashboard with a status of "Investigating". |
severity_include boolean |
Whether or not to include the event severity when the incident is created/updated in StatusDashboard. When false, severity will not be included in the event, and the severity_mapping dictionary is ignored. |
severity_hide boolean |
Whether or not to set the severity hidden attribute on incident in StatusDashboard. Some customers may wish to set severity and track it internally, but hide it from their status dashboards and notifications to customers. |
severity_mapping dict |
This is a mapping dictionary between the ServiceNow 'impact' and the StatusDashboard 'severity'. Incidents created/updated in StatusDashboard can have either a standard severity (major_performance, minor_performance, major_outage, minor_outage) or a custom defined severity in their event configuration. This mapping dictionary uses the ServiceNow impact to set the desired severity for incidents. For example, in the default mapping dictionary, if a ServiceNow incident has a state of "1 - High", then the event will be created/updated in StatusDashboard with a severity of "Major Outage". Customers who wish to have their StatusDashboard configuration exactly match the ServiceNow configuration for severities may do so by customizing their StatusDashboard severity event configuration. |
include_long_description boolean |
When set to true, the ServiceNow short description and long description will be concatenated and set as the event description in StatusDashboard. When set to false, only the short description will be set. |
suppress_str string |
Customers may wish to periodically suppress StatusDashboard from triggering notifications to subscribed customers when incidents are created or updated in ServiceNow. To temporarily stop triggering notifications for a particular incident whenever it is updated in ServiceNow, include the suppress_str anywhere in the short description.
|
Triggering the Business Rule
Actions that typically trigger the business rule in ServiceNow to send a webhook to Statusdashboard:
- Editing the incident and updating the short/long description or any of the other attributes of the event like state or impact.
- Posting a customer visible comment to the incident. If you are adding a customer visible comment and also updating the description or changing other attributes of the incident, it is best to add the customer visible comment but not post it (and update the event as one action). Failing to do this could trigger multiple updates to the StatusDashboard event, with notifications.
When a customer visible comment is added to an incident in ServiceNow, it will be added to StatusDashboard as part of the incident timeline as an update, with the text of the customer visible comment and a timestamp.