ServiceNow Enterprise Integration Guide

This guide covers how to set up version 4 of the PagerDuty app for ServiceNow. To view the instructions for the latest version, please refer to our New ServiceNow Integration Guide.

ServiceNow Enterprise is a powerful platform-as-a-service, which offers advanced automation and process workflow for the enterprise environment. With this integration, you will be able to leverage ServiceNow’s workflow and ticketing capabilities with PagerDuty’s robust on-call scheduling, notifications and escalations.

Our ServiceNow application is certified for ServiceNow Helsinki, Istanbul, Jakarta (patch 6 and later) and Kingston. This guide will walk you through the process of integrating your environment with PagerDuty.

Check out our Knowledge Base to find out more about:

• What’s New in ServiceNow v4.0
• More information on How the integration works and Advanced Configuration
• Troubleshooting the ServiceNow integration
• Frequently asked questions

Communication between ServiceNow Enterprise and PagerDuty is supported in both directions allowing incidents to be acknowledged, delegated (assigned to another group) and resolved in either system. The following workflows are supported:

• Third party monitoring tool integrations detect an issue and trigger an incident in PagerDuty. User receives a notification from PagerDuty and the user can acknowledge/resolve via PagerDuty. A ServiceNow ticket is opened when a PagerDuty incident is triggered and kept in sync for the lifecycle of the incident.
• Ticket is filed in ServiceNow. An incident is automatically opened in PagerDuty and notifies the user. Via PagerDuty, user takes ownership via PagerDuty. Information from PagerDuty is kept in sync with ServiceNow.

You can see a visual representation of these workflows here:

ServiceNow Requirements Prior to Install

Application Access Controls

In order for the PagerDuty integration to function, the following changes are required in ServiceNow prior to installation. This work should be performed by a ServiceNow administrator.

1. From the System Definition → Tables module, open the record for the User (sys_user) table and enable the Allow configuration option to support the action to provision PagerDuty users from a user form.
2. From the System Definition → Tables module, open the record for the Group (sys_user_group) table, and:
   • Enable the Allow configuration option to support the action to provision PagerDuty service and policy from a group form.
   • Enable the Can create and Can update options to allow PagerDuty to write the group’s service and policy IDs to the group record.
3. From the System Definition → Tables module, open the record for the Group Member (sys_user_grmember) table and enable the Allow configuration option.

In ServiceNow

1. Log into the ServiceNow Store and search for the PagerDuty Incident Resolution Platform application.
2. Select the option to purchase the application. There is no charge for this application. Make sure to select the most recent version of the app available for your version of ServiceNow.
3. Log in to your ServiceNow Enterprise account as an admin.
4. Open the System Applications → Applications module and click the Downloads tab to view the new application.
5. Click Install on the PagerDuty application.

Add PagerDuty Fields to Views

If you wish to view the PagerDuty ID fields within ServiceNow, they will manually need to be added to views. How to do this is detailed in Show or hide fields on a form in the ServiceNow documentation.

It is also recommended that you add the fields to the list view, by clicking on the gear icon in the upper left corner of the grid, to customize the display of columns. For example, in the Groups view:

The following is the list of available fields. Adding these fields on the form views will also allow you to use the quick link to the related PagerDuty record.

• User (List and individual user form)
  • PagerDuty ID
• Group (List and individual group form)
  • PagerDuty service
  • PagerDuty escalation
  • PagerDuty webhook
• CMDB CI Application (List and Individual CI form)
  • PagerDuty service
  • PagerDuty webhook
• Incident
  • PagerDuty ID

In PagerDuty

Create a REST API Key

This API key will be used by ServiceNow to communicate with PagerDuty. The below steps only need to be performed once during initial install.

1. From the Integrations menu in PagerDuty, select API Access Keys.
2. On the API Access page, click the Create New API Key button.
3. In the dialog that pops up, you’ll be prompted to enter a Description for your key. You will also have the option to create the key as Read-only; leave this box unchecked as a full API key is required.
4. Once you have filled in your options, click Create Key.
5. Once you click Create Key, you will see a dialog displaying your key and confirming the options you filled in on the previous step.
6. Important: Make sure to copy this key and save it in a secure place, as you will not have access to the key after this step. If you lose a key that you created previously and need access to it again, you should remove the key and create a new one.
7. Click Close once you have successfully copied your key.

In ServiceNow

Firstly, note, most of the basic application-wide settings for the integration are set on the page PagerDuty → Configuration → Properties accessed through the system menu:

Create an integration user account for webhook authentication

The integration requires a ServiceNow user account under which to operate when performing actions initiated by webhooks from PagerDuty. This design serves as a security feature, and enables you to control the permissions and roles that the integration has.

1. Create a new service account in ServiceNow for the PagerDuty application to use. You will need to provide the username and password in the PagerDuty Properties UI when configuring the application.
2. Ensure that the Web service access only option is enabled.
3. Under the Roles tab, select Edit and assign to the user the following three roles: itil, rest_service, and x_pd_integration.admin.
4. Go to PagerDuty → Configuration → Properties in the ServiceNow system menu, and enter the user ID and password of the new user into the ServiceNow user for authentication and ServiceNow user password for authentication fields.
5. Validate that basic authentication is working by clicking on Test ServiceNow User Authentication. You should get a ServiceNow user authentication test successful (200) response if everything is working properly:

Configure the PagerDuty API connection

Go to PagerDuty → Configuration → Properties in the ServiceNow system menu, and configure the API connection by entering the following properties:

1. Default PagerDuty User ID to use if auto-provisioning is disabled: Enter a valid PagerDuty user ID to be used if the integration cannot identify a PagerDuty account for the ServiceNow user performing the action. Note, this must be a PagerDuty user ID, not a ServiceNow user ID or email address. A PagerDuty user’s ID can be found by copying the last part of their PagerDuty profile page, which is an alphanumeric code beginning with P.
2. REST API endpoint URL: this should be left as the default, https://api.pagerduty.com.
3. PagerDuty API access key: enter into this field the API key generated in the steps above. API key from the previous steps.
4. Validate that the integration works by clicking on Configuration → Test API Connection. You should get a Connection test successful (200) response if everything is working properly:

Additional Properties to Review

Once you’ve downloaded and configured the integration, check out our Knowledge Base for more information on configuring Priority Sync, Inbound Field Rules, and other advanced configuration options.

Other global settings for the PagerDuty integration can be found in the same PagerDuty → Configuration → Properties page as used above to configure the API connection and include:

• PagerDuty instance URL: the URL to your PagerDuty site.
• Default PagerDuty Service ID to use if the selected Configuration Item does not map to a PagerDuty Service (optional): In this case, if a ticket is opened against an unmapped Configuration Item, but the Assignment Group is mapped to PagerDuty, a PagerDuty incident will still be created on this PagerDuty Service.
• Incident state value to use when PagerDuty resolves an incident: If you have modified the default ServiceNow incident states, enter the value of you want incidents set to when PagerDuty resolves the related incident.
• Resolve PagerDuty incident if ServiceNow incident is assigned to a group that doesn’t exist in PagerDuty: If a ServiceNow incident is linked to a PagerDuty incident and the ServiceNow incident is re-assigned to a group that does not have a PagerDuty service, should the PagerDuty incident be set to resolved and unlinked from ServiceNow
• Automatically create a PagerDuty user if one is not found matching the user’s email: If a user cannot be found in PagerDuty, should the integration automatically provision a user based on the user’s email address from ServiceNow.
• Only assign based on an acknowledgment from PagerDuty user: If enabled, PagerDuty assignments will only be updated in ServiceNow when the incident is acknowledged in PagerDuty

Choose How ServiceNow objects map to PagerDuty objects

The option Choose ServiceNow to PagerDuty mapping on the PagerDuty → Configuration → Properties page allows the following two options for the correspondane between systems:

• ServiceNow Configuration Items & Assignment Groups map to PagerDuty
  • Configuration Items map to PagerDuty Services
  • Assignment Groups map to PagerDuty Escalation Policies
• ServiceNow Assignment Groups map to PagerDuty
  • Assignment Groups will map to a PagerDuty Service and a PagerDuty Escalation Policy

The following diagram represents the mapping between objects in both systems when Configuation Items and Assignment Groups map to PagerDuty:

Provisioning Configuration Items to PagerDuty

Note: If you have selected Assignment Groups map to PagerDuty in the PagerDuty Properties UI, you can skip this step. You will not need to provision Configuration Items into PagerDuty.

Before provisioning your Configuration Items into PagerDuty, it is recommended that you set the corresponding Assignment Group for each of the Configuration Items you will be provisioning. This simplifies the provisioning process: when you provision a single Configuration Item, it will verify that the Assignment Group exists in PagerDuty (as an Escalation Policy). If not, it will also provision the corresponding Assignment Group as a PagerDuty Escalation Policy.

With the PagerDuty integration, each ServiceNow configuration item can have a corresponding PagerDuty Service. This integration offers an easy way to quickly generate a new PagerDuty service and webhook (which is necessary to send information back to ServiceNow). It will also populate the associated fields within ServiceNow.

Any configuration item that extends the base cmdb_ci table can be mapped to PagerDuty because it inherits the same field that contains the PagerDuty service ID. This makes it easy to map any type of configuration item to services in PagerDuty, although provisioning only Business Services, Technical Services and/or Applications is recommended. For each configuration item type, the form view for it will need to be modified to show the PagerDuty object ID.

1. In the list of Applications within your ServiceNow instance, you will notice that the PagerDuty service, and PagerDuty webhook fields are all empty for the listed groups except when the CI is mapped to PagerDuty.
2. Select an application (or CI) that you would like to provision to PagerDuty. Then, under click on the Provision CI Into PagerDuty link under Related Links to deploy it to your PagerDuty instance.
3. You should see a notification that the configuration item will be created. Once it’s complete, the PagerDuty service and PagerDuty webhook fields will be populated with the PagerDuty IDs.
4. Lastly, you will find that the corresponding service and escalation policy have been created in PagerDuty. The service also has the webhook automatically created, which powers the bi-directional sync between PagerDuty and ServiceNow.

Provisioning Assignment Groups to PagerDuty

ServiceNow has the concept of assignment groups. With the PagerDuty integration, each assignment group will have a corresponding PagerDuty service and escalation policy. This integration offers an easy way to quickly generate a new PagerDuty service and escalation policy. It will also populate the associated fields within ServiceNow.

Depending on which mapping you choose on the Properties page, some PagerDuty attributes will not be set on Assignment Groups.

• If you choose Assignment Groups map to PagerDuty, each Assignment Group will have a corresponding PagerDuty escalation, service, and webhook ID.
• If you choose Configuration Items and Assignment Groups map to PagerDuty, each Assignment Group will only have a PagerDuty escalation ID. The PagerDuty service and webhook ID is mapped to your Configuration Items.

Note: The user provisioning assignment groups to PagerDuty must have a PagerDuty user ID attached to their account in ServiceNow

1. Select an assignment group that you would like to provision to PagerDuty. Then, click on the Provision PagerDuty Service link to deploy this group to your PagerDuty instance.
2. You should see a notification that the assignment group will be created. Once it’s complete, the PagerDuty service, PagerDuty escalation, and PagerDuty webhook fields will be populated.
3. Lastly, you will find that the corresponding service and escalation policy have been created in PagerDuty. The service also has the webhook automatically created, which powers the bi-directional sync between PagerDuty and ServiceNow. The webhook contains the shared secret in the URL, enhancing the security of the communications.
4. You can also provision multiple groups at once by selecting them and clicking on the Provision Group into PagerDuty option from the dropdown menu on the Groups list view.

Provisioning Users to PagerDuty

1. The integration also allows for the provisioning of users from ServiceNow to PagerDuty. Below is the list of ServiceNow users. You can see directly which users have already been created in PagerDuty as their PagerDuty ID field has already been populated.
2. We’ll select a user that has not already been provisioned to PagerDuty. We can then click on the Provision PagerDuty User link to add them to our PagerDuty account:
3. You then see a notice that the user is being provisioned. Upon completion, the PagerDuty ID field is automatically populated. The user also shows up within PagerDuty, with the same name and email address.
4. If the user has their Business phone or Mobile phone fields populated in ServiceNow, these settings will also be automatically provisioned as Contact Methods and Notification Rules in PagerDuty.
5. You can also provision multiple users at once by selecting them and clicking on the Provision PagerDuty User option from the dropdown menu on the Users screen.

Verify that ServiceNow and PagerDuty are Communicating

You can verify that PagerDuty and ServiceNow are communicating by assigning an incident to the group in ServiceNow. Below is an incident that was assigned to the Database group which is tied to a PagerDuty service. It was then reassigned to the CAB Approval escalation policy within PagerDuty.

Once the incident is resolved in PagerDuty, it will be resolved in ServiceNow and vice-versa. ServiceNow also maintains a log of what activities have taken place within PagerDuty.

Note: Once you have successfully installed and configured the PagerDuty application in your ServiceNow instance, it is recommended that you index the incident.x_pd_integration_incident column on your incident table. This will ensure optimal performance when the PagerDuty application is querying the incidents table.