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.

This article details installing version 5 of our ServiceNow integration, which is certified for ServiceNow Kingston, London and Madrid. This guide will walk you through the process of integrating your environment with PagerDuty.

📘

Looking for another version?

Versions v7.6(current), v6, and v4 of our ServiceNow Enterprise integration are also available.

Quick Links

• 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.

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.
2. Click on the Application Access tab and enable the Allow configuration option to support the action to provision PagerDuty users from a user form. Then click Update.

3. Back in the System Definition Tables module, open the record for the Group (sys_user_group) table.
4. In the Application Access tab, enable the Allow configuration option to support the action to provision PagerDuty service and policy from a group form.
5. Enable the Can create and Can update options as well to allow PagerDuty to write the group’s service and policy IDs to the group record. Then click Update.

6. From the System Definition Tables module, open the record for the Group Member (sys_user_grmember) table and enable the Allow configuration option. Then click Update.

Installation from the ServiceNow Store

• Click here to find the appropriate application
• 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.
• Log in to your ServiceNow Enterprise account as an admin.
• Open the System Applications Applications module and click the Downloads tab to view the PagerDuty Incident Resolution Platform application.
• 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
  • PagerDuty team
  • PagerDuty schedule
• CMDB CI Application (List and Individual CI form)
  • PagerDuty service
  • PagerDuty webhook
• Incident
  • PagerDuty ID

Configuration 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. In PagerDuty, navigate to Integrations API Access Keys.
2. On the API Access Keys 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, and choose an API version. 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.

Configuration in ServiceNow

Firstly, note, most of the basic application-wide settings for the integration are set on the page PagerDuty Configuration PagerDuty Settings 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. Under Organization Users, click New to 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 Settings UI when configuring the application.

2. Set a User ID, First name, Last name and Password for the user. If the Web service access only and Internal Integration User options are available, make sure that they are enabled.

3. Populate the email field on the integration user that was just created with an email address of a valid user in PagerDuty. This will result in requests being properly formatted with a PagerDuty-From header.
4. Under the Roles tab, select Edit and assign the following three roles to the user: itil, rest_service and x_pd_integration.admin.

🚧

Madrid and later ServiceNow versions

If you are installing the PagerDuty integration for the first time in the Madrid platform version, add the role snc_platform_rest_api_access in place of rest_service. If you installed the PagerDuty integration while on a version earlier than Madrid, you should not need to make any changes.

5. Go to PagerDuty Configuration PagerDuty Settings 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.
6. 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 PagerDuty Settings 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 the ID of a valid PagerDuty user ID. This will be used if the integration cannot identify a PagerDuty user account for the ServiceNow user performing the action. The value here should be the alphanumeric code beginning with P at the end of the user's profile URL in PagerDuty.
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.
4. Validate that the integration works by clicking on Configuration Test REST API Connection. You should get a Connection test successful (200) response if everything is working properly:

❗️

Setting the default user correctly is important

If you do not have auto-provisioning enabled, a default PagerDuty user ID is required. If a valid user ID is not set, many aspects of the integration will not work.

The default PagerDuty ID must be a PagerDuty user ID, not a ServiceNow user ID or email address. A PagerDuty user’s ID can be found at the end of the user's PagerDuty profile page URL. It is an alphanumeric code beginning with P, (for example, PXXXXXX).

Moreover, the PagerDuty user's default role must be at least "Responder".

Finally, if there is a user in ServiceNow who has that PagerDuty user ID in their PagerDuty ID field, that user's email address must exactly match the login email of the user in PagerDuty.

If all of these conditions are not met, the integration will be unable to reassign or resolve incidents in PagerDuty when they are reassigned or resolved by a user in ServiceNow who does not have a corresponding PagerDuty account.

Additional Properties to Review

Once you’ve downloaded and configured the integration, check out the Advanced Configuration article for more information on configuring Priority Sync, Inbound Field Rules and other optional configurations.

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

• Integration Behavior
  • Choose ServiceNow to PagerDuty mapping: Select whether or not Assignment Groups should map to PagerDuty or if Configuration Items and Assignment Groups should map to PagerDuty.
  • Incident state value to use when PagerDuty resolves an incident: Select the integer value associated with the “Resolved” state in your ServiceNow instance. If this value is customized please be sure to select the appropriate value here.
  • Resolve PagerDuty incident if ServiceNow incident is assigned to a group that doesn’t exist in PagerDuty: Choose whether or not an incident in PagerDuty should be resolved if it is assigned to a group that doesn’t exist (has been mapped to) PagerDuty. This is useful if not all ServiceNow Groups are mapped to PagerDuty escalation policies.
  • Create a new PagerDuty user if one is not found with the ServiceNow user’s email: Optionally auto provision users involved in ServiceNow into PagerDuty when they are assigned or manage an incident in ServiceNow. This may impact billing on your account.
  • Do not assign the ServiceNow incident until a PagerDuty user has acknowledged the incident
  • Provision current Assignment Group members into PagerDuty when provisioning Assignment Groups: Optionally auto provision all users who are part of an Assignment Group when the Assignment Group is provisioned into PagerDuty
  • Create PagerDuty Schedule when provisioning Assignment Groups: Automatically create a new schedule for Assignment Groups that are provisioned by ServiceNow into PagerDuty. When a schedule is created, the Manager for the Assignment Group will be added to the schedule. The schedule then needs to be populated with other users in PagerDuty.
  • Use PagerDuty teams: Make use of the PagerDuty teams functionality along with assignment groups in ServiceNow.
  • Create PagerDuty Team when provisioning Assignment Groups: when enabled, a PagerDuty team will be created when you provision an Assignment Group from ServiceNow to PagerDuty
• PagerDuty Settings
  • PagerDuty instance URL: the URL to your PagerDuty instance.
  • PagerDuty API access key: The API key that was generated as part of the configuration process, used to authenticate with the PagerDuty REST API.
  • Default User ID: This PagerDuty account will be used to make API requests (from ServiceNow to PagerDuty) if the user performing an action in ServiceNow does not exist in PagerDuty.Omitting this field could result in incidents not being created in PagerDuty if created by a ServiceNow users that is not provisioned in PagerDuty.
  • REST API Endpoint: This field should not need to be changed.
• ServiceNow Settings
  • ServiceNow user for authentication: The username that PagerDuty should use to authenticate with ServiceNow for webhook delivery.
  • ServiceNow user password for authentication: The corresponding password to the aforementioned user.
  • ServiceNow REST endpoint for webhook callback: Optionally modify the path that PagerDuty uses to send webhooks to. It is recommended that you leave this value as is.
• Legacy Settings
  • Logging verbosity level: Modify the amount of information contained in the logs for the PagerDuty integration. Default value is info, consider changing to debug if you need to troubleshoot.

Choose How ServiceNow objects map to PagerDuty objects

The option Choose ServiceNow to PagerDuty mapping on the PagerDuty Configuration Settings page allows the following two options for the correspondence between systems:

• ServiceNow Configuration Items and Assignment Groups map to PagerDuty
  • Configuration Items map to PagerDuty services
  • Assignment Groups map to PagerDuty escalation policy
• ServiceNow Assignment Groups map to PagerDuty
  • Assignment Groups will map to both a PagerDuty service and a PagerDuty escalation policy

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

Provision 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 Configuration Item 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, select Provision CI Into PagerDuty 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 correspond to a PagerDuty escalation policy. You can optionally enable settings to automatically create a PagerDuty schedule and team when a group is provisioned from ServiceNow.

Depending on which mapping you choose on the Settings 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 policy, service, and webhook ID. Optionally, each assignment group will also have a PagerDuty schedule and Team ID.
• If you choose Configuration Items and Assignment Groups map to PagerDuty, each assignment group will only have a PagerDuty escalation ID (optionally, assignment groups will also have a corresponding PagerDuty schedule and Team ID). The PagerDuty service and webhook ID is mapped to your Configuration Items in ServiceNow.

Note: The user provisioning assignment groups from ServiceNow 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, select Provision Group into PagerDuty 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.

The assignment group will also have a corresponding schedule ID and Team ID if these were enabled in the PagerDuty Settings UI.

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 Provision Group into PagerDuty from the dropdown on the Groups list view.

Provision 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.

Upgrade Your PagerDuty Integration

Before starting the upgrade process for your PagerDuty integration, please make sure you’ve addressed the following items:

• Revert customizations prior to upgrading from the store, as the upgrade path will not patch customized/modified files.
• Prior to running the "MIGRATE WEBHOOKS TO v5.0" script, update the PagerDuty Settings page, and run both the Test REST API Connection and the Test ServiceNow User Authentication scripts to ensure a success (200) status code.