ServiceNow + PagerDuty Integration Benefits

• Leverage ServiceNow’s workflow and ticketing capabilities with PagerDuty’s robust on-call scheduling, notifications and escalations.
• Run Response Plays, post status updates and set the impacted Business Service on a PagerDuty incident all from the ServiceNow interface.
• Perform Assignment Group and priority mapping to PagerDuty escalation policies.
• Provision Business and technical services from ServiceNow to PagerDuty along with their dependency relationships.
• Send ServiceNow change requests to PagerDuty as change events.
• Author custom code for outbound REST API calls.
• MID server support.

How it Works

Incident communication between ServiceNow and PagerDuty is bi-directional, allowing users to trigger, reassign, resolve, use response plays, post status updates and set impacted Business Services in either system. The following workflows are supported:

• Third party monitoring tool integrations detect an issue and trigger an incident in PagerDuty. Users receive notifications from PagerDuty and they can acknowledge/resolve via PagerDuty. A ServiceNow ticket is opened when a PagerDuty incident is triggered and above actions are kept in sync for the lifecycle of the incident.
• A ticket is filed in ServiceNow, which automatically triggers an incident in PagerDuty and notifies the user. The user takes ownership via PagerDuty, and above actions from PagerDuty are kept in sync with ServiceNow.

Requirements

In ServiceNow:

• A ServiceNow Administrator role is required for configuration.

In PagerDuty:

• The ServiceNow integration is only available to accounts on the following pricing plans: Business, Digital Operations (legacy) and Enterprise for Incident Management. Please contact our Sales Team if you would like to upgrade to a plan featuring the ServiceNow integration.
• A Global Admin or Account Owner base role is required for configuration.

Quick Links

• More information on How the integration works and Advanced Configuration
• Troubleshooting the ServiceNow integration
• Frequently Asked Questions

Version

This guide details configuration for the latest ServiceNow v7.9.1 integration.

📘

Looking for another version?

The ServiceNow v6 integration is also available.

Integration Walkthrough

🚧

Assignment Groups/Change Groups

Assignment Groups are now referred to as Change Groups in ServiceNow Quebec, and these terms are interchangeable in this guide.

Step 1: Complete ServiceNow Pre-Install Requirements

1.1 ServiceNow Application Access Controls

In order for the integration to function, a ServiceNow administrator must allow configuration access in the following ServiceNow tables. In the left hand application navigator, search System Definition and select the Tables module. Search for and open the following records and perform the specified actions:

1.2 Integration Installation

Install the PagerDuty integration from the ServiceNow Store.

1.3 Add PagerDuty Fields to Views (Optional)

If you wish to view the PagerDuty ID fields within ServiceNow, they will need to be manually added to the Group, User and Incident views. This will make it easier to see which ServiceNow objects are mapped to PagerDuty. Instructions are detailed in Show or hide fields on a form in ServiceNow’s documentation.

1. It is recommended that you add the PagerDuty fields to the User and Group list views by clicking the gear icon in the upper left corner of the grid to customize the display of columns. This will make them visible in your list views only.

2. The following is the list of available PagerDuty fields that you can add to the various list views or forms in ServiceNow:

Step 2: Configuration In PagerDuty

2.1 Create a PagerDuty API Access Key

1. Log in to your PagerDuty account in the web app. 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, 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. Click Create key to save.
4. Next you will see a dialog displaying your API key. 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. Click Close once you have successfully copied and saved your key.

2.2 Create a Default PagerDuty User Account for ServiceNow

This integration requires ServiceNow to have access to your PagerDuty account both by an API token and a PagerDuty user account. The PagerDuty user account is required so that non-PagerDuty users can take action in ServiceNow and the actions will be reflected in PagerDuty.

🚧

Important Note

This integration now has the option to provision a Default User from the ServiceNow UI, however this function has stipulations to consider:

• When provisioning the Default User, it will create a PagerDuty user based on the user who is logged in to ServiceNow and configuring this setting. If you are okay with being provisioned as the Default ServiceNow user, please follow directions in this section and then move on to Step 3: Configuration in Your ServiceNow Instance.
• If you do not want to be provisioned as the Default ServiceNow user in PagerDuty, please proceed with the steps below.

1. In your PagerDuty account, navigate to People, select Users and click the Add Users button.
2. Enter ServiceNow User in the Name field and enter any valid email address in the Email field. Copy this email and save it in a safe place for later steps when you will be entering it into ServiceNow. Once you have saved this email, select Global Admin as the Base Role and click Add and Send Invitations to save.
3. You will now see the ServiceNow User in your PagerDuty Users list. Click the user name and take note of the 7-character alphanumeric user ID in the URL of this page. E.g., If your URL reads https://your-subdomain.pagerduty.com/users/PXXXXXX the user ID would be PXXXXXX. Copy this user ID and keep it, along with this users’ email, in a safe place. In later steps, you will also be entering this user ID into ServiceNow.

Step 3: Configuration in Your ServiceNow Instance

3.1 Create a ServiceNow User Account For Webhook Authentication

The PagerDuty integration also requires a ServiceNow user account to operate under. This enables PagerDuty to sync actions back to ServiceNow via webhooks. This design serves as a security feature, and allows you to control the integration’s permissions and roles within ServiceNow.

1. Log in to your ServiceNow instance. In the ServiceNow application navigator, search Organization Users and click New to create a new user account for PagerDuty application use.
2. Enter a User ID, First/Last name and Password for the user. You can use any desired username. Set a password for the user and copy it. Save the username and password and keep them in a safe place, as you will need to provide them in the PagerDuty Settings (within the ServiceNow UI) in a later step. If the Web service access only and Internal Integration User options are available, you can optionally select these checkboxes.

3. In the Email field, enter the same email that you entered for the new user in PagerDuty (step 2 of the Create a Default User Account for ServiceNow section, above). This will result in requests being properly formatted with a PagerDuty-From header. Click Submit and then search and click into the user profile.
4. Under the Roles tab, select Edit and assign to the user the following three roles: itil, rest_service, and x_pd_integration.admin. Click Save to be returned to the User form.

The new user account that you created requires the ability to make API requests. This allows PagerDuty to create incidents in ServiceNow and action existing Incidents (such as changing assignment). If your ServiceNow instance allows all users to perform REST API calls, providing the itil and the x_pd_integration.admin role should be sufficient. If REST API access is restricted by role, provide the necessary role to the user account. In many cases, this is either the snc_platform_rest_api_access or the rest_service role.

5. In the PagerDuty ID field, enter the 7 character user ID of the default PagerDuty user account (generated in step 3 of Create a Default PagerDuty User Account for ServiceNow, above).

To summarize what should be completed this far:

• A default PagerDuty user account has been created for ServiceNow to use.
• An API Key has been created in PagerDuty.
• A ServiceNow user account has been created for the PagerDuty integration to use.
• The above user accounts have been mapped to each other via their shared email address and the PagerDuty User ID.

If all of these prerequisites have been fulfilled, Update the user record in ServiceNow. You may now begin configuring the PagerDuty Settings page in ServiceNow.

3.2: Configure PagerDuty Settings in ServiceNow

Please note that most of the settings for the integration can be set by navigating to the PagerDuty application Configuration PagerDuty Settings, accessed through the application navigator of your ServiceNow instance:

You may see a warning at the top of the page indicating that you need to switch into the PagerDuty application scope. Proceed with this step if you are prompted. Once done, the PagerDuty Settings page should become editable.

1. In your ServiceNow instance, navigate to PagerDuty Configuration PagerDuty Settings in the application navigator, and enter the user ID and password of the new ServiceNow user into the ServiceNow user for authentication and ServiceNow user password for authentication fields. Note: The value input for ServiceNow user for authentication must be all lower case in order to match the ServiceNow user ID.

2. Input information in the following fields:

Once you have provided the necessary configuration on the PagerDuty Settings page, click Save.

3. Validate that the integration works by clicking Actions Test REST API Connection. You should get a Connection test successful (200) response if everything is working properly.

4. Validate that the ServiceNow user account was successfully configured by clicking Actions Test ServiceNow User Authentication. You should get a ServiceNow user authentication test successful (200) response if everything is working properly. Upon successful completion of the two tests, initial configuration is now complete.

5. Validate that the Default User settings were properly configured. To do this, click Test Default User Settings. You should see a series of success messages. If you do not receive a success message, you will be informed if there are any changes required.

3.3 Add the ServiceNow Extension to an Existing PagerDuty Service

If you would like to add the ServiceNow extension to an existing PagerDuty service, as opposed to creating a new one, use the following instructions. If you wish to create a new service, please skip this section and move on to Step 3.4: Review PagerDuty Settings in ServiceNow.

Option 1: Manually Configure the Extension in PagerDuty

This option requires that you have access to the username and password of the ServiceNow account that PagerDuty uses.

1. In your PagerDuty account, navigate to Services Service Directory click the service name select the Integrations tab Add or manage extensions New Extension.
2. In the Extension Type field, search and select ServiceNow (v7) and enter a Name in the format servicenow-service-name (e.g., servicenow-shopping-cart). In the following fields, enter:

3. Click Save.

Option 2: Use the ServiceNow Integration to Provision the PagerDuty Extension

This method does not require access to the username and password of the ServiceNow account that PagerDuty uses. Instead, access to the x_pd_integration.admin role in ServiceNow is required so that you can provision a new PagerDuty Extension using the integration.

1. Identify how ServiceNow maps to PagerDuty. ServiceNow can map Configuration Groups and Assignment Groups to PagerDuty, or just Assignment Groups. This is configured on the PagerDuty Settings page within ServiceNow.

   • If you are only mapping Assignment Groups, navigate to the Assignment Group that you want to map to PagerDuty.
   • If you map Configuration Items to PagerDuty, navigate to the Configuration Item that you want to map to PagerDuty.

2. Open the record in ServiceNow. You should see a number of PagerDuty fields that are blank. You will be populating the PagerDuty Service field.

📘

Note

If the PagerDuty Service ID is not blank, it means that the object is already mapped to PagerDuty.

3. In PagerDuty, using your web browser, navigate to Services Service Directory and select the existing service that is configured. In the URL bar, you will find the 7-character Service ID starting with the letter P. Copy the Service ID to your clipboard.
4. In ServiceNow, paste the Service ID in the PagerDuty Service field.
5. Click Save. If you are redirected back to the list view in ServiceNow, open the record again.
6. In the Related Links section, you should now see an option to Provision Webhook. Selecting this option will create the corresponding extension in PagerDuty and complete the mapping for you.

3.4 Review PagerDuty Settings in ServiceNow

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. Depending on your preferences, you may choose to use the following settings:

3.5 Choose How ServiceNow Objects Map to PagerDuty Objects

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

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

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

Step 4: Provisioning from ServiceNow to PagerDuty

In order to create a bi-directional sync between PagerDuty and ServiceNow, you must provision an Assignment Group into PagerDuty. Assignment Groups provisioned will create PagerDuty services and associated escalation policies where ServiceNow incidents will be triggered.

You may also optionally choose to provision Configuration Items, Services, Users and Priority from ServiceNow to PagerDuty.

4.1 Provision Assignment Group(s) to PagerDuty (Required)

With the PagerDuty integration, each ServiceNow assignment group will correspond to a PagerDuty escalation policy to ensure that incidents will be assigned correctly in PagerDuty. In this latest version, assignment groups provisioned to PagerDuty as services will have a default escalation policy and you will have the option to add additional escalation policies mapped to ServiceNow incident priorities. You can also 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, 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. Navigate to User Administration and click Groups. Select an assignment group that you would like to provision to PagerDuty. Then, click on the Provision Group into PagerDuty 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 within the Assignment Group.
   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 on the Provision Group into PagerDuty option from the dropdown menu on the Groups list view.

Please follow documentation here to add additional priority-mapped escalation policies to your Assignment Group.

5. Lastly, you will need to review the Sync Group Members with PagerDuty setting for your provisioned Assignment Groups. Enabling this option allows the integration to check if newly added Assignment Group members have a PagerDuty account. If they do not have an account, it will then provision them and add the user to the PagerDuty team associated with the group.

4.2 Provision Configuration Items and Users to PagerDuty (Optional)

📘

Note

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

See our Advanced ServiceNow Configuration guide for more instructions on how to provision CIs and users from ServiceNow to PagerDuty.

Step 5: Test the Integration

To verify that PagerDuty and ServiceNow are communicating:

1. Search and select PagerDuty Incidents in the application navigator. Click New to create a new incident.
2. In the Caller field, enter the ServiceNow user mapped to your PagerDuty account. Enter a Short description which will become the incident Title. In the Assignment Group field, search and select the Assignment Group mapped to PagerDuty. Enter any other preferred information on this page and click Submit in the upper right.
3. You should now see an incident in your PagerDuty account on the service that was mapped with your Assignment Group.

Below is an incident that was assigned to the Database group which is mapped to PagerDuty. It was then reassigned to the CAB Approval group, as shown in the Activity log.

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 highly recommended that you index the following columns in ServiceNow:

• incident.x_pd_integration_incident
• sys_user_group.x_pd_integration_pagerduty_escalation
• sys_user.x_pd_integration_pagerduty_id
• cmdb_ci.x_pd_integration_pagerduty_service

This will ensure optimal performance when the PagerDuty application is querying the incidents, group, user and CMDB tables.

👍

ServiceNow User Guide

Once initial configuration is complete, please read our ServiceNow User Guide for instructions on how to use the integration.

Configure the ServiceNow Change Events Integration

Once you have set up the ServiceNow integration (instructions above), you can configure it to send change events by following our instructions here.

Configure Escalation Policy Priority Mapping

The ServiceNow v7 integration allows Assignment Groups to have more than one escalation policy assigned to incidents based on incident priority in ServiceNow. For example, if you would like one escalation policy assigned to incidents with a priority of Moderate or below and another for priorities above Moderate, you could map escalation policies to this scheme. There are two ways to configure this feature: via the PagerDuty menu or on an individual Assignment Group.

To configure escalation policy priority mapping via the PagerDuty menu:

1. Navigate to PagerDuty in the application navigator and select Map Priority to Escalation Policy.
2. Click New and select the Assignment Group, Escalation Policy and Priority you wish to map and check the Active checkbox.
3. Click Submit to save. If you would like to deactivate this mapping, return to the Map Priority to Escalation Policy screen, click the status in the Active column, uncheck the Active checkbox and click Update. You may repeat this process to map multiple escalation policies to different priorities.

To configure escalation policy priority mapping on an individual Assignment Group:

1. Search and click into your preferred Assignment Group. Select the PagerDuty Escalation Policies tab and click New.
2. In the Escalation Policy field, search and select your preferred escalation policy. In the Priority field, search and select which priority should be mapped to that escalation policy. Check the Active checkbox to activate this setting and click Submit. You may repeat this process to map multiple escalation policies to different priorities.

Once configured, when an incident is assigned to that assignment group and the mapped priority, the mapped escalation policy will be assigned to that incident.

Author Custom Code for Outbound API Calls

1. Navigate to PagerDuty Settings in the application navigator and scroll to the PagerDuty API requests customization section.
2. Enter your custom headers, one per line without quotes (e.g., name: value).
3. Click Save.

You may also author custom code when configuring a MID server, below.

Configure a MID Server

The ServiceNow v7 integration comes with optional MID server support.

To configure a MID server:

1. Navigate to PagerDuty in the application navigator and select PagerDuty Settings. Under PagerDuty API requests customization check the Use MID Server checkbox.
2. The Set MID Server field will have the default MID server auto-populated. Enter your parameters in the ECC parameters field.
3. Click Save.

Upgrade Your PagerDuty Integration

Use the following process to upgrade your integration:

1. Revert customizations prior to upgrading from the store, as the upgrade path will not patch customized/modified files. Be sure to capture these customizations in an update set and store a copy for future reference before reverting to the out-of-the-box versions.
2. After reverting all app files, upgrade the PagerDuty app to the newest version in the ServiceNow Store.
3. Then, Navigate to System Diagnostics Upgrade History, then select the upgrade of the PagerDuty app that you just ran. You should see in the tab Skipped Changes to Review a list of records that did not upgrade successfully for some reason or another. Important misses will be marked Priority 2 or Priority 1; if there are any high-priority skipped files in that list (Priority 1 or 2), go through each in turn by clicking on their File name. On the following details page click the button Revert to Base System – this will override the customizations that prevented upgrade and will force-upgrade the file to the version of the PagerDuty app you’ve just installed. Lower priority skipped files should be left as is.
4. 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.
5. Then, run the Migrate Webhooks to v7 script.
6. Next, run the MIGRATE Escalation Policies to… script. This will ensure that the existing escalation policy to assignment group mapping is also added to the new table with the priority value empty to denote the default escalation policy.
7. Once you have successfully upgraded, determine what (if any) customizations need to be reapplied after the install.