ServiceNow is a powerful platform-as-a-service that offers advanced automation and process workflows for the enterprise environment. This article is an overview of the components and concepts that drive the ServiceNow v8 integration, and will give you a deeper understanding of how it works at a fundamental level.

📘

Looking for a Different Version?

ServiceNow Integration Details for the v7 integration are also available.

Integration Capabilities

Installation and Configuration

• Installation: For installation instructions, refer to the ServiceNow Integration Guide.
• Advanced Configuration: For more in-depth information about customizing the ServiceNow integration, refer to Advanced ServiceNow Configuration.

Upgrade to ServiceNow v8

📘

Required User Permissions

You must have a ServiceNow Admin role to upgrade the integration.

1. Revert customizations prior to upgrading from the store, as the upgrade path will not patch customized or modified files. 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. Navigate to System Diagnostics Upgrade History and select the upgrade of the PagerDuty app that you just ran. In the Skipped Changes to Review tab, you may see a list of records that did not upgrade successfully. Important misses will be marked Priority 1 or Priority 2. If there are any high-priority skipped files in that list, go through each in turn by clicking their File name. On the following details page, click Revert to Base System — this will override the customizations that prevented the upgrade and force-upgrade the file to the version of the PagerDuty app you just installed. Leave lower-priority skipped files as-is.
4. Navigate to the PagerDuty Settings page to update the new fields in this form. A new workflow connection will be automatically provisioned upon clicking Save at the bottom of the screen. This will enable ServiceNow as a Workflow Action. Once complete, manual sync is immediately restored.
   1. If there is a ServiceNow user ID or ServiceNow user password change, the integration will force a connection update.
   2. A valid PagerDuty configuration (PagerDuty account URL, PagerDuty API access key, REST API Endpoint) is required to provision a connection.
   3. Select a Sync option in the new Webhook Configuration management section.
   4. In the Activity Stream section, confirm that there are check marks next to the event types that you want to sync to your ServiceNow activity stream.
5. Ensure that application access is granted for the sysauto_script table for read, create, and update operations, as indicated in this step of the integration guide.
6. Navigate to Integration Health Check. The integration health check will run automatically to ensure the initial connection is intact and verify that the workflow connection has been enabled.
7. Navigate to Webhooks Health Check Run health check, and resolve any inconsistencies prior to migration.
8. Navigate to Webhooks Migration to migrate webhooks to v3 and convert all ServiceNow extensions to the latest version.
9. Navigate to PagerDuty Inbound Field Rules to update existing Inbound Field Rules to extract data from the new v3 webhook payload.
10. (Optional) If you had customizations:
    1. Determine whether historical customizations are still necessary — new integration versions introduce new functionality and fixes such that the cause for a previous customization may no longer exist.
    2. Manually implement each required customization on the new version of the file. Do not revert any files to their pre-upgrade versions or import old versions of files. Test after each addition to ensure that the customization does not cause breakage in the new version of the integration.

Manage Integration Settings

Once the ServiceNow v8 integration has been initially configured or upgraded, global integration settings can be found by navigating to PagerDuty Settings.

Integration Behavior

Integration Behavior

Setting	Values
Choose ServiceNow to PagerDuty mapping	Select one of the following from the dropdown: Configuration Items and Assignment Groups map to PagerDuty (Recommended) or Assignment Groups map to PagerDuty. To learn more, see How ServiceNow Objects Map to PagerDuty Objects.
Incident state value to use when PagerDuty resolves an incident	Select the integer value associated with the Resolved state in your ServiceNow instance.
Default role that should be used when provisioning users from ServiceNow into PagerDuty	Select your preferred default role for provisioned users from the dropdown: Observer, Responder, Manager, or Global Admin.
PagerDuty functionalities available to display in ServiceNow	Check the features you want enabled in your ServiceNow instance: PagerDuty Teams — make use of PagerDuty Teams functionality along with assignment groups in ServiceNow (available on Business, Digital Operations (legacy), and Enterprise for Incident Management plans); Response Mobilizer — add one or more users as responders to an existing incident from the ServiceNow interface (Add Responders, available on Business, Digital Operations (legacy), and Enterprise for Incident Management plans); Conference Bridge — add conference bridge information to an incident from the ServiceNow interface (Conference Bridge, available on Business, Digital Operations (legacy), and Enterprise for Incident Management plans); Incident Workflows — run Incident Workflows from the ServiceNow interface (Incident Workflows, available on Business, Digital Operations (legacy), and Enterprise for Incident Management plans); Status Update — send incident status updates from the ServiceNow interface (Status Updates, available on Business, Digital Operations (legacy), and Enterprise for Incident Management plans); Incident Types — associate incidents with a specific incident type and its custom fields so that responders only see the custom fields relevant to the incident context.
PagerDuty action configurations	Resolve PagerDuty incident if ServiceNow incident is assigned to a group that doesn't exist in PagerDuty: Choose whether a PagerDuty incident should resolve if it is assigned to a group that has not been mapped to PagerDuty. This is useful if not all ServiceNow groups are mapped to PagerDuty escalation policies. Create a new PagerDuty user if the Assigned To user on the incident is not in PagerDuty: Optionally auto-provision ServiceNow users to PagerDuty when they are assigned to or manage a ServiceNow incident. 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 you provision the group to PagerDuty. Create PagerDuty Schedule when provisioning Assignment Groups: Automatically create a new schedule when you provision an Assignment Group to PagerDuty. When you create a schedule, it will automatically add the Manager for the Assignment Group to the schedule. You will then need to populate the schedule with other users in PagerDuty.
Customize PagerDuty Incident Body	Customize the PagerDuty incident body when you create an incident from ServiceNow. Use braces to input variables from columns in the incident table and {workNote} to include a work note.

PagerDuty Settings

PagerDuty Settings

You can gather some of these values by following the initial steps in the ServiceNow Integration Guide. You may also edit them at a later date by following steps 2–5 again.

Setting	Values
PagerDuty account URL (https://subdomain.pagerduty.com)	Your PagerDuty subdomain URL, for example https://subdomain.pagerduty.com.
PagerDuty API access key	Paste the REST API key that you generated in PagerDuty.
Default service ID (Optional)	You can provision a default PagerDuty service by clicking Provision default service. If you have an existing PagerDuty service that you want to use as the default service, copy the 7-character ID starting with P at the end of the service's URL and paste it into this field.
Default user ID	This is the integration user — sometimes also referred to as the service user or application user — that you created in PagerDuty. Paste the user ID associated with the Default PagerDuty User Account for ServiceNow.
REST API Endpoint	If your account is hosted in the US service region: Leave 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

Webhook Configuration

Setting	Values
ServiceNow user ID	The ServiceNow user ID that PagerDuty should use to authenticate with ServiceNow for webhook delivery.
ServiceNow user password	The corresponding password for the ServiceNow user above.
Sync option	This setting only applies to how PagerDuty creates ServiceNow incidents. Select the incident sync method from the dropdown: Auto — when a PagerDuty incident triggers, it automatically creates a ServiceNow incident; Manual — when a PagerDuty incident triggers, it will not automatically create a ServiceNow incident. Instead, a Sync with ServiceNow button will appear on the PagerDuty incident's details page.
Task type	At this time, only Incident task types are available.
ServiceNow REST endpoint for webhook	It is recommended that you leave this value as-is.
Workflow Connection	The connection used to create ServiceNow incidents based on PagerDuty Incident Workflows. After saving the PagerDuty Settings page, navigate back to this field to verify that a workflow connection has generated successfully.

Activity Stream Customization

Configuration options to control what PagerDuty information is shown in the ServiceNow incident activity stream, such as ServiceNow incident work notes. Check the options that you want to display in the incident activity stream:

PagerDuty API Requests Customization

HTTP Headers

Add custom headers for PagerDuty API requests. In the field, add one on each line without quotes, for example name:value.

Use MID Server

The ServiceNow integration comes with optional MID server support. See Advanced ServiceNow Configuration for more information.

Legacy Settings

Logging Verbosity Level

Modify the amount of information contained in the logs for the PagerDuty integration. The default value is info. Consider changing to debug for troubleshooting.

Core Components

All of the source code that performs the actions underpinning the integration can be accessed by going to PagerDuty Configuration Configuration files.

Most of the tasks performed to synchronize data between PagerDuty and ServiceNow are executed in the following application files, under Script Includes:

You can modify these components. Any customizations to these core components that alter the integration's out-of-the-box behavior are not supported by the PagerDuty Support Team.

Integration Health Check

What Happens During an Integration Health Check

• Test REST API Connection: Validates whether the integration can successfully make requests to the PagerDuty REST API. A Connection test successful (200) response indicates success.
• Test ServiceNow User Authentication: Validates the username and password for the integration user in ServiceNow — specifically, the ServiceNow integration user on the PagerDuty Settings page. A ServiceNow user authentication test successful (200) response indicates success.
• Test Default User Settings: Validates the user ID and email for the PagerDuty integration user — specifically, for the PagerDuty user corresponding to the Default user ID on the PagerDuty Settings page. You should see a series of success messages. If you do not receive a success message, you will be informed of any changes required.
• Test Workflow Connection: Validates whether a Workflow Connection has been established.

How and When to Run the Integration Health Check

📘

Required User Permissions

You must have the x_pd_integration.admin role in ServiceNow to run the Integration Health Check.

• How to run the Integration Health Check: In ServiceNow, navigate to Integration Health Check. The health check will run automatically. Once complete, the results will be displayed on this page.
• When to run the Integration Health Check: Run Integration Health Checks during the initial configuration of the PagerDuty app in ServiceNow and when upgrading the app to v8.

Webhooks Health Check

What Happens During a Webhooks Health Check

The Webhooks Health Check scans the existing system-wide webhook configurations connecting PagerDuty and ServiceNow, highlighting any errors or inconsistencies. The Webhooks Health Check also provides remediation guidance, such as bulk re-enabling disabled webhooks.

This feature uses asynchronous job execution to fetch all required data from PagerDuty and ServiceNow, then builds a snapshot of the status and configuration of your webhooks.

How and When to Run a Webhooks Health Check

📘

Required User Permissions

You must have the x_pd_integration.admin role in ServiceNow to run the Webhooks Health Check.

• How to run a Webhooks Health Check: Navigate to Webhooks Health Check and click Run health check to initiate the process. Review the results and resolve any inconsistencies detected. Re-run the health check to confirm that the inconsistencies have been resolved.
• When to run a Webhooks Health Check: Run the Webhooks Health Check during initial configuration of the PagerDuty app in ServiceNow and when upgrading the app to v8. Additional Webhooks Health Checks can be run after installation or upgrade at the Admin's discretion.

Webhooks Migration

Introduction to the Webhooks Migration Module

The Webhooks Migration module converts existing v2 ServiceNow extensions into generic v3 webhooks. We highly recommend running the Webhooks Health Check prior to migration, since this is the process that identifies v2 webhooks. To access the Webhooks Migration module in ServiceNow, navigate to Webhooks Migration.

Migrate Webhooks to v3

1. Before migrating your webhooks to v3, confirm that the workflow connection has been enabled. This can be verified by navigating to Integration Health Check, which will run automatically. Do not migrate webhooks or continue using the integration until you have completed this check.
2. Navigate to Webhooks Health Check.
3. Click Run health check.
4. If there are any inconsistencies, resolve them prior to migrating webhooks to v3.
5. Select All and search for and select Webhooks Migration, then click Migrate.
6. A confirmation modal will indicate that migration was successful.

Additional Notes Regarding Webhook Migration

• When managing v3 webhooks, refrain from re-configuring webhooks via the PagerDuty web UI. Instead, navigate to the Assignment Group or CI record in ServiceNow to make changes to webhook configuration.
• Installations upgraded to v8 will keep their existing v2 webhooks until the webhook migration is performed. Any new webhooks created after the upgrade will be v3.

Data from PagerDuty to ServiceNow

How PagerDuty Communicates to ServiceNow

Real-time incident updates in PagerDuty are communicated to ServiceNow through extensions on each PagerDuty service that correspond to a provisioned Assignment Group in ServiceNow. When you initially provision a group, it creates an extension on the service. In version 3.5 and later, a service extension will be provisioned automatically — if one does not already exist — whenever a new incident is created.

The extensions, also known as webhooks, specify URLs in your ServiceNow instance to which JSON-encoded data is sent via HTTPS POST requests.

The following variables dictate the actions that will be taken on the target record for each webhook import:

The PdWebhookTransform script — PdWebhookTransformV3 for v3 webhooks — contains the logic for all default operations taken when updating or inserting an incident, including additional fields to populate and workflow logic. Within the local scope, the following variables dictate the actions that will be taken on the target record for each webhook import.

By the time the script completes, the incident's properties will be stored in the target variable. Changes will be saved after the script exits.

Syncing PagerDuty Incident Notes to ServiceNow

Starting in version 5, the integration uses the annotate webhook event type to keep incident notes synchronized between PagerDuty and ServiceNow. When you add a PagerDuty incident note, the webhook transform will recognize the event and add the note as a work note with the suffix (PagerDuty: PAGERDUTY_USER_NAME on TIMESTAMP).

In earlier versions (v7.6 and below), the process that ran in the opposite direction was initiated by a business rule — in addition to the user-initiated UI action Refresh PagerDuty Notes — which appeared as an action in the context menu for any given linked incident. The business rule PD Update Worknotes from PagerDuty Notes polls for updates and raises the event x_pd_integration.import_notes (handled by the Import Notes from PagerDuty incident script action). In both cases, the functions PagerDuty.getIncidentNotes and PagerDuty.createNoteImports are used to import and save notes from PagerDuty. ServiceNow incident work notes will appear in PagerDuty with the prefix (from ServiceNow:SERVICENOW_USER_NAME).

Data from ServiceNow to PagerDuty

How ServiceNow Communicates to PagerDuty

Syncing ServiceNow Work Notes to PagerDuty

Work notes are copied from ServiceNow to PagerDuty through the PD Copy worknote to PagerDuty incident business rule, which triggers the x_pd_integration.post_worknote event, which then invokes the PagerDuty.postIncidentNote function. This runs any time a work note changes on a linked incident.

How ServiceNow Interacts with PagerDuty Incidents