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
This integration is being decommissioned along with our v1 REST API. Please plan to upgrade to the latest version of our ServiceNow integration.
Note: This guide is for the ServiceNow v3.2.1 integration and earlier. If you’re on v3.5 or a later version of the integration, you will want to use the current Integration Guide.
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.
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:
- User uses PagerDuty for notifications only. Once notified, they use ServiceNow to assign, investigate, resolve the incident.
- User gets a notification from PagerDuty and takes incident ownership via PagerDuty (by acknowledging) then uses ServiceNow for investigation and resolution.
- 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 Istanbul, Helsinki, Geneva and Fuji, and will walk you through the process of integrating your environment with PagerDuty. There is different integration guide available for ServiceNow Express.
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.
- From the System Definition → Tables module, open the record for the User (
- Enable the Allow configuration option to support the action to provision PagerDuty users from a user form.
- From the System Definition → Tables module, open the record for the Group (
- Enable the Allow configuration option to support the action to provision PagerDuty service and policy from a group form.
- Enable the Can create and Can update options to allow PagerDuty to write the group’s service and policy IDs to the group record.
- Log into the ServiceNow Store and search for the PagerDuty Incident Resolution Platform 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 new application.
- Click Install on the PagerDuty application.
Add PagerDuty Fields to Views
If you wish to view the PagerDuty ID fields, they will manually need to be added. 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.
- PagerDuty service
- PagerDuty escalation
Create a REST API Key
- From the Apps & Add-Ons menu, select API Access.
- On the API Access page, click the Create New API Key button.
- 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; leaving this box unchecked will create a full access key.A note about versioning: API v2.0 is designed to make it easier for new integrations to communicate with PagerDuty. Most existing PagerDuty integrations will require an API v1.0 key.
- Once you have filled in your options, click Create Key.
- Once you click Create Key, you will see a dialog displaying your key and confirming the options you filled in on the previous step. Make sure to copy this key into any application that needs it now, 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 your key.
Configure the PagerDuty App
- Go to PagerDuty → Configuration → Properties.
- Enter your PagerDuty account URLs as per the example and paste in your API Key from the previous steps. It is also suggested that you change the security key to a long unique string. This key is required for all webhook URLs.
- Validate that the integration works by clicking on Configuration → Test API Connection. You should get a
Connection test successful (200) response if everything is working properly:
Additional Properties to Review
- 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
- Incident state value to use when PagerDuty resolves an incident: If you have modified the default ServiceNow incident states, enter the value of you want incidents set to when PagerDuty resolves the related incident
- Resolve PagerDuty incident if ServiceNow incident is assigned to a group that doesn’t exist in PagerDuty: If a ServiceNow incident is linked to a PagerDuty incident and the ServiceNow incident is re-assigned to a group that does not have a PagerDuty service, should the PagerDuty incident be set to resolved and unlinked from ServiceNow
- 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
- 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
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.
- Below is a list of all assignment groups within our ServiceNow instance. You will notice that the “PagerDuty service” and “PagerDuty escalation policy” fields are empty for the listed groups.
- We then select an assignment group that we would like to provision to PagerDuty. In this case, it”s the CAB Approval group. We then click on the “Provision PagerDuty Service” link to deploy this group to PagerDuty:
- 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 policy” fields are populated:
- Lastly, you can see that the corresponding service and escalation policy have been created. The service also has the webhook automatically created, which powers the bi-directional sync between PagerDuty and ServiceNow. The webhook also contains the shared secret in the URL, enhancing the security of the communications.
Provisioning Users to PagerDuty
- The integration also allows for the provisioning of users from ServiceNow to PagerDuty.
- 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.
- You then see a notice that the user is being provisioned. Upon completion, the “PagerDuty ID” field is automatically populated.The user will also shows up within PagerDuty.
- If the user has their “Business phone” or “Mobile phone” fields populated, these settings will also be automatically provisioned as Contact Methods and Notification Rules in PagerDuty.
- 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 they are communicating by assigning an incident to the group in ServiceNow. Below is an incident that was assigned to the Field Services group which is tied to a PagerDuty service. It was then reassigned to the CAVUCode 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.
Can a PagerDuty incident create a ServiceNow incident?
Yes. This is done on a service-by-service on the PagerDuty side by modifying the webhook URL. For each PagerDuty service you want to create ServiceNow tickets from, you’d have to add
&group=Database to the end of the URL. This specifies which assignment group to assign the newly-created ServiceNow ticket to. As with URLs in your browser, you will need to define special characters in your webhook URL using percent-encoded values. For example, if your group name has a space, be sure to replace the space with
%20. Please note that this will not automatically resolve ServiceNow tickets created from any email-based PagerDuty services.
Can I migrate from the PagerDuty update set for ServiceNow Eureka to the new app integration?
Yes, a migration can be performed by a ServiceNow user with the
security_admin role after installing and configuring the new PagerDuty app.
You can escalate to the
security_admin role by clicking on the lock in the banner next to the user’s name. Once escalated, this script can be run via the Scripts – Background module. The script will perform the following actions:
- Migrate all PagerDuty integrated incidents to the new fields used by the Fuji or Geneva application
- Migrate all PagerDuty integrated groups to the new fields
- Disable the old PagerDuty Business Rules
- Disable the old inbound webhook processor
- Hide the old PagerDuty application menu
- Disable the old incident fields and group fields
After the script has completed, an admin will need to modify the incident and group form layout. The layouts simply need to be saved to remove the disabled fields. No other changes should be necessary.
What’s new in the latest version of the app?
Version 3.2.1 – Supporting Istanbul, Helsinki & Geneva
- This version is now compatible with and certified for ServiceNow Istanbul.
Version 3.1 – Supporting Helsinki and Geneva
- This version is now compatible with and certified for ServiceNow Helsinki.
- The inbound HTTP processors have been converted to scripted REST APIs to obtain Helsinki certification. PagerDuty webhook URLs will need to be updated as a result of this change. Clicking PagerDuty → MIGRATE WEBHOOKS will automatically update your PagerDuty webhooks where needed, including ones that were manually configured, as long as the ServiceNow assignment group is mapped to a PagerDuty service.
- We’ve added support for incident resolution from ServiceNow for incidents that were created by a third-party PagerDuty service integration.
- We’ve migrated incident resolve logic to use the
incident/resolve REST API instead of the events API.
Why are PagerDuty notes not showing up in the ServiceNow Activity Stream after upgrading the PagerDuty app to version 3.1?
This is due to changes in newer releases to ServiceNow which require you to manually enable execution of business rules for the Notes Import Service’s transform map. To do enable execution of the necessary business rule:
- Go to PagerDuty → Imports → Notes Import Service, then click PagerDuty Note Import.
- Check Run business rules and click Update.
Note: Version 3.2.1 of the app has this option enabled automatically.
Can I manually create PagerDuty services that are tied to ServiceNow?
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:
- Go to your service and click on the Integrations tab, from there click Add or manage extensions.
- For the Extension Type select Generic Webhook, then enter a name, then enter the webhook URL for the PagerDuty connector public page, which varies depending on the app version you use.For app version 3.1 and later:
https://<subdomain>.service-now.com/api/x_pd_integration/pagerduty2sn?webhook_key=<your secret key>
For app version 3.0 and earlier:
https://<subdomain>.service-now.com/x_pd_integration_pagerduty2sn.do?webhook_key=<your secret key>
Remember to replace
<your secret key> with your ServiceNow subdomain and secret key from the PagerDuty Properties page in ServiceNow.
- Click the Save button.