Integrate with ServiceNow

What does the integration offer?

Compass has an application in the ServiceNow Store which allows bi-directional functionality between Compass and ServiceNow. Use the integration to send ServiceNow incident events to Compass with detailed information and to forward Compass alerts as incidents to ServiceNow.

Compass determines the right people to notify based on on-call schedules, notifies via email, text messages (SMS), phone calls, and iOS and Android push notifications, and escalates alerts until the alert is acknowledged or closed.

How does the integration work?

• When an incident is created in ServiceNow, an alert is created in Compass.

• When an incident is resolved/closed in ServiceNow, the alert is closed in Compass.

• When the incident is assigned to a group in ServiceNow, the corresponding team is added to the alert if the name of the group in ServiceNow and the name of the team in Compass match.

• When the incident is assigned to a user in ServiceNow, the alert in Compass is assigned to the corresponding user.

• User & Group synchronization (optional).

Alert action mapping

• If Send Alert Updates Back to ServiceNow selection is enabled, actions are executed in ServiceNow when the chosen action is executed in Compass for alerts which are created by the ServiceNow integration.

• If Create ServiceNow Incidents for Compass Alerts selection is enabled, actions are executed in ServiceNow when the chosen action is executed in Compass for alerts which have a source other than the ServiceNow integration.

The feature is explained in more detail later on this page.

Set up the integration

ServiceNow is a bidirectional integration. Setting it up involves the following steps:

• Add a ServiceNow integration in Compass

• Configure the integration in ServiceNow

Add a ServiceNow integration

To add a ServiceNow integration in Compass, complete the following steps:

1. Go to your team’s operations page.

2. On the left navigation panel, select Integrations and then Add integration.

3. Run a search and select “ServiceNow”.

4. On the next screen, enter a name for the integration.

5. Optional: Select a team in Assignee team if you want a specific team to receive alerts from the integration.

6. Select Continue.
   The integration is saved at this point.

7. Expand the Steps to configure the integration section and copy the API key.
   You will use this key while configuring the integration in ServiceNow later.

8. Select Turn on integration.
   The rules you create for the integration will work only if you turn on the integration.

Configure the integration in ServiceNow

1. Go to the ServiceNow Store and download the Compass application.

2. Go to System Applications > Applications > Downloads to finish the installation of the app.

3. Create/Update a user with roles x_86994_jsm.jsm_app_role, import_transformer, and import_set_loader in the instance. Assign a password to the user. This password can be permanent or temporary. After adding the Compass application to the instance, the Compass application is available for you in the navigator.

4. Under the Compass application menu, select Compass Configuration.

5. Paste the API key previously copied from Compass into Compass API Key.

6. Leave the Compass API URL field as-is, if not using Compass Sandbox.

7. Check Use Synchronization option to value, if synchronizing users & groups in ServiceNow with Compass is desired.

For more information, check out the "User & Group Synchronization (Optional)" section in this article.

8. Check Use Acknowledge Action in Compass Instead of Assigning the Alert When the Incident is Assigned to Somebody in ServiceNow option if it is preferred to acknowledge the alert instead of assigning it to a user in Compass when an incident is assigned to someone in ServiceNow. For more information, please check out the "Acknowledging the Alert in Compass When the Incident is Assigned in ServiceNow (Optional)" section below.

9. Save the configuration in ServiceNow.

10. Go back to ServiceNow integration page in Compass.

11. Populate the "ServiceNow Instance Subdomain" field with the subdomain of the ServiceNow instance.

12. Populate the "ServiceNow User ID" and "ServiceNow Password" fields with the user ID and the password of the user created/updated earlier.

Map action alerts

Compass allows customers to define action mappings between Compass actions and ServiceNow actions.

For alerts created by ServiceNow

• Use this section to map Compass actions to ServiceNow actions when the source of the alert is ServiceNow (i.e when the alert is created by ServiceNow integration.)

• Map different Compass actions to different ServiceNow actions. For example, add a note to a ServiceNow incident when the alert is acknowledged in Compass. In order to do this, define "If alert is acknowledged in Compass, add it as a work note to the incident in ServiceNow." mapping in "Send Alert Updates Back to ServiceNow” section.

For other Compass alerts

• Use this section to map Compass actions to ServiceNow actions when the source of the alert is NOT ServiceNow (i.e When the alert is created by another integration.)

• For this purpose, use Create ServiceNow Incidents for Compass Alerts section. In order to use this functionality, map one Compass action to "create an incident" ServiceNow action. The Compass action doesn't have to be "alert is created", it can be other actions as well.

• "a tag is added to the alert" and a "custom action is executed on alert" actions differ from other actions. When one of these actions is selected, an extra field is available to enter for which tags or for which custom action this mapping works.

• Enter multiple tags by separating the tags with a comma. If multiple tags are entered, the mapping works if the alert has one or more of the specified tags. Leave the tags field empty for the mapping to work for any tag.

• If a Compass action is mapped to multiple ServiceNow actions, an error occurs except for the "a tag is added to the alert" and "a custom action is executed on alert" actions. Save multiple mappings for these actions, because they differ by the given tags and the given custom action names.

Acknowledge the alert in Compass when the incident is assigned in ServiceNow (optional)

1. Currently, when an incident is assigned to someone in ServiceNow, the alert is assigned to the same user in Compass.

2. Assigning an alert to a user in Compass does not stop the notification flow.

3. Instead, the notification flow is stopped when the incident is assigned to someone in ServiceNow. There is an option for this behavior in our latest Compass application in ServiceNow.

4. It is not enabled by default. Check the option to value in order to acknowledge the alert instead of assigning it to the user in Compass.

Send payload to a custom-scripted REST API source endpoint in ServiceNow (optional)

1. Our integration with ServiceNow supports sending a payload from an alert action to a custom endpoint in ServiceNow.

2. Map any alert action to the "send to custom endpoint" ServiceNow action, and when those alert actions take place, a payload is sent to the endpoint specified.

3. The payload we send for this "send to custom endpoint" ServiceNow action is similar to the payload of our Webhook integration except it does not include the "integrationName" and "integrationId" fields. Check out this document to get more information about the payload.

4. We've already created a Scripted REST API Resource for our latest Compass application in ServiceNow called "sample".

5. We've developed a script to make an HTTP request to our Alert API and get the alert data from our Alert API and log it to the application logs as an example for this "sample" Scripted REST API Resource.

6. Map a custom Compass action called "sample" to the "send to custom endpoint" ServiceNow action and enter "sample" as the custom endpoint to test the feature.

7. This way, when the "sample" custom action is executed on an alert in Compass, it is forwarded to the "sample" endpoint in ServiceNow.

User and group synchronization (optional)

1. Our integration with ServiceNow supports synchronizing users and groups in ServiceNow with Compass.

2. Note that the synchronization is performed for the users and groups added to ServiceNow after the synchronization feature is enabled. We create a user in Compass for each such user in ServiceNow and we create a team in Compass for each such group in ServiceNow.

3. When a user is created, updated, or deleted, or a group is created or deleted in ServiceNow, the changes are applied to the Compass account if the "Use Synchronization" option is checked in the "Compass Configuration" form in ServiceNow.

4. In Compass-ServiceNow integration page, UNCHECK "Restrict Access to Configuration" option, if it is checked.

5. We get email, full name, business phone, mobile phone, and timezone fields of a user from ServiceNow and use those fields in Compass when creating a user.

6. The role of a user created in Compass will be "User" regardless of his/her role in ServiceNow.

7. When one or more of the full name, business phone, mobile phone, and timezone fields of a user change in ServiceNow, those fields are changed in Compass, too.

8. Compass does NOT allow special characters or spaces in team names, but ServiceNow does. So, we replace disallowed characters and spaces before creating a team in Compass when a group is created in ServiceNow with those characters in the name.

9. Updating group name or group description in ServiceNow will NOT update team name and team description in Compass.

10. When a user is added to or removed from a group in ServiceNow, the user is added to/removed from the team in Compass.