ServiceNow Express Integration Guide

This integration requires use of our v1 REST API which is currently in a decommissioning period, please contact support to gain access to a v1 REST API key to configure this integration.

For more information about the v1 REST API deprecation, take a look at our FAQ here: https://v2.developer.pagerduty.com/v2/docs/v1-rest-api-decommissioning-faq

ServiceNow Express is a platform-as-a-service which offers advanced automation and process workflow for small and medium businesses. 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.

Communication between ServiceNow Express 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:

  1. User uses PagerDuty for notifications only. Once notified, they use ServiceNow to assign, investigate, resolve the incident.

  2. User gets a notification from PagerDuty and takes incident ownership via PagerDuty (by acknowledging) then uses ServiceNow for investigation and resolution.

  3. User uses PagerDuty to get a notification, then takes incident ownership (by acknowledging), and resolves the incident.

You can see a visual representation of these workflows here:

This guide is certified for ServiceNow Express and will walk you through the process of integrating your environment with PagerDuty. There is a different integration method available for ServiceNow Enterprise.

In ServiceNow

Install the PagerDuty Application

  1. Log in to the ServiceNow Store and search for the PagerDuty Incident Resolution Platform for Express application.

  2. Click Get to make the application available for installation.

  3. Log in to your ServiceNow Express account as an admin.

  4. Go to Application Configuration → Store Applications and click the Downloads tab to see the new application.

  5. Click Install on the PagerDuty application.

Create a PagerDuty User

The application requires a ServiceNow user account to process webhooks from PagerDuty. We recommend creating a service account for PagerDuty, rather than using an existing user account for this purpose.

  1. Go to User Administration → Users and click New.

  2. Enter a User ID, such as pagerduty.webhook, enter a password, and assign the roles admin and x_pd_integration_xadmin to this user.

Add PagerDuty Fields to Views

If you wish to view the PagerDuty ID fields, they will need to be added manually, as ServiceNow applications are unable to automatically modify form layouts. 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
    • PagerDuty ID
  • Group
    • PagerDuty service
    • PagerDuty escalation
  • Incident
    • PagerDuty ID

In PagerDuty

Log in to PagerDuty as an admin or the account owner.

Create a REST API Key

  1. Go to Configuration → API Access and click Create New API Key.

    Note: You will not see API Access if you are not logged in to PagerDuty as an admin or the account owner, or if your account’s pricing plan does not include API access.

  2. Enter a Description for your new key, such as ServiceNow Express, and set the API version for this key to v1 Legacy, then click Create Key.

    Note: Choosing v2 Current will not work for ServiceNow Express at this time.

  3. Once you click Create Key, you will see a dialog displaying your key and confirming the options you filled in on the previous step.

    Copy this key before closing the dialog, as you will not have access to view the key again. 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.

In ServiceNow

Configure the PagerDuty App

  1. Go to PagerDuty for Express → Configuration → Properties.

  2. Enter your PagerDuty account URLs in the PagerDuty instance URL and REST API endpoint URL fields, paste in your API access key from PagerDuty, and enter the ServiceNow user account and password you created for processing PagerDuty webhooks.

  3. Validate that the integration works by going to PagerDuty for Express → Test REST API Connection. You will see Connection test successful (200) if everything is working properly:

Additional Properties to Review

  • What is the lowest priority incident that will trigger a PagerDuty incident: Enter the lowest priority for a ServiceNow incident that will trigger a PagerDuty incident

  • 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

  • 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

  • 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

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.

  1. Below is a list of all assignment groups within our ServiceNow instance. You will notice that the PagerDuty service and PagerDuty escalation fields are empty for the listed groups.

  2. We then select an assignment group that we would like to provision to PagerDuty. In this case, it’s the Service Desk group. We then click on the Provision PagerDuty Service link to deploy this group to PagerDuty:

  3. The user is then notified that the assignment group will be created. Once it’s complete, you will see that the PagerDuty service and PagerDuty escalation fields are populated:

  4. Lastly, you can see 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 also contains the pagerduty.webhook user credentials that were configured earlier.

Provisioning Users to PagerDuty

The integration also allows for the provisioning of users from ServiceNow to PagerDuty. The only requirement for provisioning is that users must have an email address set in ServiceNow in order to be provisioned in PagerDuty.

Additionally, if the user has a Business phone or Mobile phone set in their ServiceNow profile, these numbers will be provisioned as Contact Methods and Notification Rules in their new PagerDuty account.

Below is the list of ServiceNow users. You can quickly see which users have already been created in PagerDuty as the PagerDuty ID field has been populated:

Provision a Single User

  1. 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:

  2. You then see a notice that the user is being provisioned. Upon completion, the PagerDuty ID field is automatically populated:

Provision Multiple Users at Once

You can also provision multiple users at once by selecting them and selecting the Provision PagerDuty User option from the dropdown menu on the Users page:

Verify that ServiceNow and PagerDuty are Communicating

You can verify that they are communicating by assigning an incident to a PagerDuty-enabled group in ServiceNow. Below is an incident that was assigned to the Service Desk group which is tied to a PagerDuty service. It was then acknowledged within PagerDuty, and a note added by the assigned user in PagerDuty was imported to ServiceNow.

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.

FAQ

Can I manually create PagerDuty services that are tied to ServiceNow Express?

Yes, you can do so by creating a new service in PagerDuty and selecting ServiceNow as the first integration type, or by adding a new ServiceNow integration to an existing service. You will then need to enter the PagerDuty Service ID and Escalation Policy ID into ServiceNow group’s PagerDuty service and PagerDuty escalation fields to tie the PagerDuty service and ServiceNow group together. Afterward, add a ServiceNow webhook to your PagerDuty service as follows:

  1. Go to your service and click on the Integrations tab, from there click Add an extension.

  2. For the Extension Type select ServiceNow Express, enter a Name for the extension, then enter the webhook URL for the PagerDuty app:

    https://<subdomain>.service-now.com/api/x_pd_integration_x/pagerduty_webhook

    Your will also need to enter the User name and Password for the ServiceNow user account you created for PagerDuty.

  3. Click Save.