ServiceNow Integration Guide | PagerDuty

Configuring and installing the core ServiceNow v6 integration

ServiceNow + PagerDuty Integration Benefits

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

How it Works

Communication between ServiceNow and PagerDuty is bi-directional, allowing incidents to be acknowledged, delegated (reassigned 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. Users receive notifications from PagerDuty and they 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.
  • A ticket is filed in ServiceNow, which automatically triggers an incident in PagerDuty and notifies the user. The user takes ownership via PagerDuty and information from PagerDuty is kept in sync with ServiceNow.

Requirements

  • In ServiceNow: A ServiceNow Administrator role is required to configure the integration. This article details installing the latest version 6 of our ServiceNow integration, which is certified for ServiceNow Kingston, London, and Madrid.
  • In PagerDuty:
    • The ServiceNow integration is only available to accounts on Business or Digital Operations plans. Please contact our Sales Team if you would like to upgrade to a plan featuring the ServiceNow integration.
    • An Admin, Global Admin or Account Owner base role is required for configuration. If you're not sure what role you have, or if you need your permissions adjusted, visit our sections on Checking Your User Role or Changing User Roles.

Looking for another version?

Quick Links

ServiceNow Requirements Prior to Install

Application Access Controls

In order for the PagerDuty integration to function, a ServiceNow administrator must make the following changes:

  1. In the left hand application navigator, search System Definition and select the Tables module. Search for and open the record for the User (sys_user) table.
  2. Select the Application Access tab and check the Allow configuration checkbox. This will allow you to provision PagerDuty users from a user form. Click Update to save.
  1. Next, return to the application navigator and select System DefinitionTables module. Open the record for the Group (sys_user_group) table.
  2. The following permissions are required so that the PagerDuty integration can map PagerDuty users to ServiceNow user records. In the Application Access tab, check the Can update checkbox so that the integration can store a PagerDuty User ID on the ServiceNow record when user provisioning is complete. Next, click the Allow configuration checkbox, which is required so that you can provision one or more Groups into PagerDuty from the List view. Click Update to save.
  1. Next, from the System DefinitionTables module, open the record for the Group Member (sys_user_grmember) table and check the Allow configuration option. This option is required so that PagerDuty can add an item into the bulk action menu when managing Group Members. Click Update to save.

Installation from the ServiceNow Store

1 . Click here to find the appropriate application.

  1. Select the option to purchase the application (there is no actual charge). Make sure to select the most recent version of the app available for your version of ServiceNow.
  2. Log in to your ServiceNow account as an admin.
  3. In Kingston and London, open the System ApplicationsApplications module and click the Downloads tab to view the PagerDuty Incident Resolution Platform application. In Madrid, open System ApplicationsAll Available ApplicationsAll.
  4. Click Install on the PagerDuty application.

Add PagerDuty Fields to Views

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.

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.

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

  • User list view and user form
    • PagerDuty ID
  • Group list view and individual Group form
    • PagerDuty service
    • PagerDuty escalation
    • PagerDuty webhook
    • PagerDuty team
    • PagerDuty schedule
  • CMDB CI Application list view and individual CI form
    • PagerDuty service
    • PagerDuty webhook
  • Incident list view and Incident form
    • PagerDuty ID

Configuration In the PagerDuty Web App

Create an API Key

  1. Log in to your PagerDuty account. Navigate to the Configuration menu and select API Access.
  2. On the API Access Keys page, click the Create New API Key button.
  1. 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.
  2. Next will see a dialog displaying your API key. Copy this key and save it in a secure place for later use when configuring the PagerDuty Settings page in ServiceNow. 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 your key.

Create a Default PagerDuty User Account for ServiceNow

The integration requires ServiceNow to have access 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.

  1. In your PagerDuty account, navigate to Configuration, select Users and click the green 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 Manager 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. 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.

Configuration in Your ServiceNow Instance

Create an Integration User Account For Webhook Authentication

The PagerDuty integration 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 OrganizationUsers and click New to create a new user account for PagerDuty application use.
  1. Enter a User ID, First/Last name and Password for the user. You can use any desired username and password. Copy the username and password and keep them in a safe place, as you will need to provide them in the PagerDuty Settings UI (within ServiceNow) in a later step. If the Web service access only and Internal Integration User options are available, you can optionally select these checkboxes.
  1. In the Email field, enter the same email that you entered for the new user in PagerDuty (step 2 of the Create a Default PagerDuty User Account for ServiceNow section, above) . This will result in requests being properly formatted with a PagerDuty-From header.
  2. 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.

This new user account requires the ability to make API requests, which 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.

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

To summarize what should be completed this far:

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

Configuring the PagerDuty Settings Page in ServiceNow

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

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 be editable.

  1. In your ServiceNow instance, navigate to PagerDutyConfigurationPagerDuty Settings in the application navigator.
  2. ServiceNow user for authentication and ServiceNow user password for authentication fields: Enter the user ID and password of the new ServiceNow user (generated in step 2 of Create an Integration User Account For Webhook Authentication, above).
  3. Default PagerDuty User ID to use: Enter the user ID of the default user you created in PagerDuty (the 7-character alphanumeric ID starting with P from step 3 of Create a Default PagerDuty User Account for ServiceNow, above). Note: 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 default role must be at least Manager or higher. This ensures that ServiceNow users who do not have a PagerDuty account can perform the provisioning of users/groups, etc. If not all of these 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 account. It may also impact the ability to provision users and groups from ServiceNow to PagerDuty.
  4. REST API endpoint URL: This should be left as the default, https://api.pagerduty.com.
  5. PagerDuty API access key: Enter the PagerDuty API key (generated in step 4 of Create an API Key, above).
  6. Once you have provided the necessary configuration on the PagerDuty Settings page, click Save.
  7. Validate that the integration works by clicking ConfigurationTest REST API Connection. You should get a Connection test successful (200) response if everything is working properly:
  1. Validate that the ServiceNow user account was successfully configured by clicking ConfigurationTest 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.

Adding 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 onto Additional Properties to Review.

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. Navigate to Configuration Services click the service name and click Create Extension.

  2. In the Extension Type field, search and select ServiceNow (v6.0) and enter a Name in the format servicenow-service-name (e.g., servicenow-shopping-cart). In the following fields, enter:

    • ServiceNow URL: Enter the URL in the following format: https://[INSTANCE-NAME].service-now.com/api/x_pd_integration/pagerduty2sn
    • ServiceNow User ID and ServiceNow Password: Enter the User ID and Password created in step 2 of the Create an Integration User Account For Webhook Authentication section, above.
    • Sync Options: Sync All Incidents will sync all new incidents to your ServiceNow instance. Manually Sync Incidents allows you to choose which incidents you want to sync, by adding the option to Sync with ServiceNow on the incident details page.
    • Incident Type: Incident will create Incidents in ServiceNow. Security Incident will generate a ServiceNow Security Incident.
  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 Configuration Services 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.

Additional Properties to Review

Once you’ve installed 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, and they 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. You can learn more about the differences below.
  • 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.
  • Enable Response Mobilizer: When enabled, you will be able to add one or more users as responders to an existing incident from the ServiceNow interface. Response Mobilizer features are part of the PagerDuty Modern Incident Response add-on product, which is purchased separately from the PagerDuty platform. Please read this article for more information.
  • Enable Conference Bridges: When enabled, you will be able to add conference bridge information to an incident from the ServiceNow interface. Conference Bridge features are part of the PagerDuty Modern Incident Response add-on product, which is purchased separately from the PagerDuty platform. Please read this article for more information.

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 → PagerDuty 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 Policies.
  • 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:

Provisioning Configuration Items to PagerDuty

Note

If you have selected Assignment Groups map to PagerDuty in the PagerDuty → Configuration → PagerDuty Settings page, 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 Configuration Item (CI) is mapped to PagerDuty.
  1. Select an application (or CI) that you would like to provision to PagerDuty. Then, under Related Links, click the Provision CI Into PagerDuty link to deploy it to your PagerDuty instance.
  1. 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.
  2. 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 PagerDuty → Configuration → PagerDuty 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. 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.
  1. 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.

  1. 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.
  2. 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. In a list of ServiceNow users, you can see directly which users have already been created in PagerDuty as their PagerDuty ID field will already be populated.
  2. In the below example, 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:
  1. 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.
  2. 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.
  3. 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 creating a new incident in ServiceNow and setting the Assignment Group field to a group that has been mapped to PagerDuty. 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 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.

Upgrading Your PagerDuty Integration

Before starting the upgrade process for your PagerDuty integration, there are some detailed action items listed under the Tips For Upgrading section in this Community Post. Specifically:

  • 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 v6.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.
  • Once you have successfully upgraded, determine what (if any) customizations need to be reapplied after the install. Be sure to capture these in an update set and store a copy for future reference.

ServiceNow Integration Guide | PagerDuty


Configuring and installing the core ServiceNow v6 integration

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.