ServiceNow Integration Guide | PagerDuty

Configure the ServiceNow v8 Integration

ServiceNow + PagerDuty Integration Benefits

How it Works

Incident communication between ServiceNow and PagerDuty is bi-directional. This allows you to trigger, reassign, resolve, use Incident Workflows, post status updates and set impacted Business Services in either system. The following behavior is supported:

  • Third party monitoring tool integrations detect an issue and trigger an incident in PagerDuty. Responders receive PagerDuty incident notifications and they can acknowledge/resolve via PagerDuty. When a PagerDuty incident triggers, it opens a ServiceNow ticket and above actions are kept in sync for the lifecycle of the incident.
  • When a ServiceNow ticket is created, it automatically triggers a PagerDuty incident and notifies responders. A responder acknowledges the PagerDuty incident, and above actions from PagerDuty are kept in sync with the ServiceNow ticket.

Requirements

In ServiceNow:

  • A ServiceNow Administrator role is required for configuration.

In PagerDuty:

Quick Links

Version

This guide details configuration for the latest ServiceNow v8 integration.

👍

Upgrade to ServiceNow v8

Please see our Upgrade to ServiceNow v8 article for instructions to upgrade from another version.

📘

Looking for a Different Version?

The ServiceNow v7 integration is also available.

Integration Walkthrough

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 application navigator, search System Definition and select the Tables module. Search for and open the following records and perform the specified actions:

TablesInstructions
sys_user
sys_user_group
sys_user_grmember
Select the Application Access tab and ensure the following are checked:

- Can read
- Can create
- Can Update
-Allow configuration

Click Update in the upper right of each to save.
Sysauto_scriptNote: The permissions granted on the Scheduled Script Executions (sysauto_script) table are required to provision scheduled scripts to process PagerDuty webhooks.

Select the Application Access tab and ensure the following are checked:

- Can read
- Can create
- Can Update

Click Update in the upper right to save.

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, Configuration Item, 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. We recommend that you add the PagerDuty fields to the Group, Configuration Item, User and Incident views by clicking the in the upper right to customize the display of columns. This will make them visible in your list views only.
Click gear icon

Click gear icon

  1. The following are the available PagerDuty fields that you can add to the various list views or forms in ServiceNow:
List Views and FormsPagerDuty Fields
User list view and User form- PagerDuty ID
Group list view and individual Group form- PagerDuty default escalation
- PagerDuty error message
- PagerDuty schedule
- PagerDuty service
- PagerDuty team
- PagerDuty webhook
Applications list view and individual CI form- PagerDuty Change Event Token
- PagerDuty service
- PagerDuty webhook
Incident list view and Incident form- PagerDuty incident
  1. Select your preferred PagerDuty field(s) in the left-hand Available slush bucket, and then click to move it to the Selected slush bucket. Repeat as desired. If you would like to reposition their order, you can also use the or buttons. Click OK to save.
Add PagerDuty fields to views

Add PagerDuty fields to views

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 Create New API Key.
  3. In the dialog that appears, 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.

🚧

Provision a Default User: Behavior

The 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 Users and click Add Users.
  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, click Add and then 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. The ServiceNow user account allows 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 application navigator, search Organization Users and click New to create a new user account for PagerDuty application use.
  2. Perform the following:
    1. User ID: Enter any desired username for the User ID. This username must be all lower case.
    2. First/Last name: Enter any desired First and Last name for the user.
    3. Email: 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.
    4. Checkboxes: Ensure that the Password needs reset and Locked out checkboxes are unchecked. Ensure that Active is checked. If the Web service access only and Internal Integration User options are available, you can optionally select these checkboxes.

🚧

Checkboxes

  • Ensure that the Password needs reset and Locked out checkboxes are unchecked.
  • Ensure that Active is checked.
  • If the Web service access only and Internal Integration User options are available, you can optionally select these checkboxes.
Create a ServiceNow user account for webhook authentication

Create a ServiceNow user account for webhook authentication

  1. Click Submit and then search and select the user’s profile.
  2. Click Set Password. In the modal that appears, click Generate and then click Save Password. Once the password has been saved, copy the username and password and keep them in a safe place, as you will need to provide them in PagerDuty Settings (within the ServiceNow UI) in a later step. Click Close to proceed.
  3. Navigate to the Roles tab in the User form and click Edit. Assign the following roles:
    1. itil
    2. x_pd_integration.admin
  4. 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 and action upon Incidents in ServiceNow. 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.

  1. 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). Click Update.

To summarize what should be completed thus 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, you may now begin configuring the API and Webhook Connection in ServiceNow.

3.2: Configure the API and Webhook Connection in ServiceNow

🚧

Application Scope Warning

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 by providing your instance’s login credentials. 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 perform the following:

Integration Behavior

FieldInstructions
Choose ServiceNow to PagerDuty mappingSelect one of the following from the dropdown:

- Configuration Items and Assignment Groups map to PagerDuty (Recommended)
- Assignment Groups map to PagerDuty

To learn more, see Choose How ServiceNow Objects Map to PagerDuty Objects.

PagerDuty Settings

FieldInstructions
PagerDuty account URL (https://subdomain.pagerduty.com)Enter your PagerDuty subdomain URL, e.g., https://subdomain.pagerduty.com
PagerDuty API access keyEnter the PagerDuty API key generated in the steps above.
Default User ID

(Note: Must be performed first before Default Service ID)
There are two options for this field depending on how you’ve chosen to assign the Default PagerDuty User in step 2.2, above:

- If you have already created a Default User in PagerDuty (Recommended): Enter the user ID of the default user you created in PagerDuty (the 7-character alphanumeric ID starting with P from step 3 of the Create a Default User Account for ServiceNow section above). Setting the default PagerDuty user, and doing so correctly, is important. The default PagerDuty ID must be a PagerDuty user ID, not a ServiceNow user ID or email address. Moreover, the PagerDuty user's base role must be at least Manager, and we recommend Global Admin, as less than an Admin role will in some situations result in a failure to update the PagerDuty incident record as expected. A sufficiently high role ensures that ServiceNow users who do not have a PagerDuty account can have their work on ServiceNow incidents reflected in the corresponding PagerDuty incident. If not all of the above conditions are 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 any corresponding PagerDuty user account. It may also impact the ability to provision users and groups from ServiceNow to PagerDuty.

- If you would like to provision a Default User to PagerDuty: Please note that this will provision a PagerDuty user based on whomever is clicking this button. If you do not want to be the default user, you must create one in PagerDuty by following these instructions. If you do want to be provisioned as the default user, click Provision default user and the User ID will auto-populate.
Default Service IDYou have the option to provision a paging service by clicking Provision default service. If you do not want to provision and already have a service in mind, you may copy the 7-character ID starting with P at the end of the URL of that service and paste it into this field.
REST API Endpoint- If your account is hosted in the US service region: This should be left as the default, https://api.pagerduty.com
- If your account is hosted in the EU service region: Enter https://api.eu.pagerduty.com

Webhook Configuration

FieldInstructions
ServiceNow user IDEnter the User ID of the user that you just created in ServiceNow.

Note: The value input for ServiceNow user for authentication must be all lower case in order to match the ServiceNow user ID.
ServiceNow user passwordEnter the Password of the user that you just created in ServiceNow.

Once you have provided the above information, click Save at the bottom of the page.

  1. Next, you will validate that the integration works. Navigate to Integration Health Check. The health check will run automatically, and you should get a Connection test successful (200) response with check marks on all tests if everything is working properly. If the test is not successful, there will be marks next to the items that need to be addressed.

3.3 Provision a PagerDuty Service

In this step you will provision a Configuration Item or an Assignment group as an initial PagerDuty service. This will create a corresponding webhook in PagerDuty and complete ServiceNow to PagerDuty mapping. Please see our article on ServiceNow Provisioning for more information about provisioning further services.

  1. Depending on the PagerDuty Settings option you selected in step 3.2 for how ServiceNow records will map to PagerDuty objects, perform the following:
  • If you are mapping Configuration Items and Assignments Groups to PagerDuty (Recommended): Navigate to the Configuration Item that you want to provision as a PagerDuty service.
  • If you are only mapping Assignment Groups: Navigate to the Assignment Group that you want to provision as a PagerDuty service.
  1. Open the Configuration Item or Assignment Group in ServiceNow. In the Related Links section, you should now see an option to Provision CI into PagerDuty or Provision Group into PagerDuty. Selecting one of these options will create the corresponding webhook in PagerDuty and complete the mapping for you.

3.4 Priority Synchronization

The priority level on a newly triggered PagerDuty incident can automatically set the priority level on a linked ServiceNow incident, and vice versa. Priority is also synced when you edit the priority of an incident in either direction. To enable this functionality, you must import PagerDuty priorities and define priority mapping in ServiceNow.

👍

Leave a Note When Changing Priority

If you need to change an incident’s priority, we recommend leaving a text note to keep relevant stakeholders informed.

3.4.1 Import PagerDuty Priorities

  1. First, define incident priorities in your PagerDuty account by going to User Icon Account Settings Incident Priorities. For more information, please see our Incident Priority article.
  2. Next, in ServiceNow, navigate to PagerDuty Actions Refresh PagerDuty Priorities and click OK when prompted. After this, priorities will populate in the table x_pd_integration_pagerduty_priority, whose contents are displayed under PagerDuty priority.

3.4.2 Define the Priority Mapping

Once you have imported PagerDuty priorities, you may define priority mapping in the same table (located at PagerDuty Field Mapping PagerDuty Priorities). The predefined list of your PagerDuty priorities, can be mapped to ServiceNow urgency and impact value pairs. The computed ServiceNow priority value will also be shown in the table.

To define how PagerDuty incident priorities map to ServiceNow priorities:

  1. Select the PagerDuty priority in the desired mapping to edit the record.
  2. Set a value for its corresponding ServiceNow Impact and Urgency.
Select ServiceNow Impact and Urgency value pairs to map to the PagerDuty Priority record

Select ServiceNow Impact and Urgency value pairs to map to the PagerDuty Priority record

  1. Click Update.
  2. After updating, the ServiceNow priority will be computed and shown in the table.
PagerDuty Priorities table in ServiceNow with mapped priorities

PagerDuty Priorities table in ServiceNow with mapped priorities

Step 4: Test the Integration

To verify that PagerDuty and ServiceNow are communicating, trigger a PagerDuty incident on the provisioned service and check to see that a ServiceNow Incident has been triggered. Once you resolve the PagerDuty​​ incident, the ServiceNow incident will also be resolved, and vice versa. ServiceNow also maintains a log of the incident activities that have taken place within PagerDuty.

👍

Index Service Columns

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.

Manage Integration Settings

For more information on managing the integration’s settings, please see our ServiceNow Integration Details article.

ServiceNow Provisioning

For more information on provisioning Configuration Items, Assignment Groups and Users from ServiceNow to PagerDuty, please see our ServiceNow Provisioning article.

Upgrade the ServiceNow Integration

To upgrade your ServiceNow integration to the latest version, please see our Upgrade to ServiceNow v8 article.