ServiceNow is a powerful platform-as-a-service, which 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, please refer to the ServiceNow Integration Guide.
• Advanced Configuration: For more in-depth information about customizing how the ServiceNow integration behaves, please 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/modified files. Be sure to 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. Then, 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 for some reason or another. Important misses will be marked Priority 1 or Priority 2; if there are any high-priority skipped files in that list (Priority 1 or 2), 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 upgrade and will force-upgrade the file to the version of the PagerDuty app you’ve just installed. Lower priority skipped files should be left 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 this is 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 in order to provision a connection.
5. On the PagerDuty Settings page:
   1. Select a Sync option and Task type in the new Webhook Configuration management section.
   2. Add Custom Field entries information to the Activity Stream, as necessary.

Post-Upgrade Process

1. Navigate to Integration Health Check. The integration health check will run automatically, to ensure initial connection is intact and verify that the workflow connection has been enabled.
2. Navigate to Webhooks Health Check Run health check, to determine if there are any inconsistencies prior to migration.
   1. The Webhook Health Check is important to:
      1. Maintain a snapshot of all existing webhooks (v2 and/or v3) and their configuration (e.g. auto/manual).
      2. Identify webhook inconsistencies and provide remedial guidance for any findings.
3. Navigate to Webhooks Migration to migrate webhooks to v3, and convert all ServiceNow extensions to the latest version.
4. If you have customizations (Optional): Re-apply any customizations at this point.
5. Navigate to PagerDuty Inbound Field Rules to update existing Inbound Field Rules to extract data from the new v3 webhook payload.
6. Activate new features:
   1. Assignment Group/CI records display the PagerDuty webhook configuration options:
      1. For the Assignment Group (Users table): The webhook configuration options will be displayed automatically.
      2. For Configuration Items:
         1. Open the record of the Configuration Item in question
         2. Navigate to Configure Related lists.
         3. Move PagerDuty Webhook from the Available slush bucket to the Selected slush bucket and click Save.
      3. Navigate to Custom Field Mappings to set up bi-directional sync mappings.

Manage Integration Settings

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

Integration Behavior

Expand

Setting	Values
Choose ServiceNow to PagerDuty mapping	Select 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 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. If this value is customized, please be sure to select the appropriate value here.
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 - Global Admin
Checkboxes	Check to enable or Uncheck to disable the following settings: - Resolve PagerDuty incident if ServiceNow incident is assigned to a group that doesn't exist in PagerDuty: Choose whether or not a PagerDuty incident 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 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 the Group is provisioned to PagerDuty. - Create PagerDuty Schedule when provisioning Assignment Groups: Automatically create a new schedule when you provision an Assignment Group to 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. Teams are available on the following pricing plans: Business, Digital Operations (legacy) and Enterprise for Incident Management. - Create PagerDuty Team when provisioning Assignment Groups (Must select Use PagerDuty teams first): Automatically create a PagerDuty Team when you provision an Assignment Group to PagerDuty. - Enable Response Mobilizer feature: Add one or more users as responders to an existing incident from the ServiceNow interface. The Add Responders feature is available on the following pricing plans: Business, Digital Operations (legacy) and Enterprise for Incident Management. - Enable Conference Bridge feature: Add conference bridge information to an incident from the ServiceNow interface. The Conference Bridge feature is available on the following pricing plans: Business, Digital Operations (legacy) and Enterprise for Incident Management. - Enable Incident Workflows feature: Run Incident Workflows from the ServiceNow interface. Incident Workflows are available on the following pricing plans: Business, Digital Operations (legacy) and Enterprise for Incident Management. - Enable Status Update feature: Send incident status updates from the ServiceNow interface. Status Updates are available with the following pricing plans: Business, Digital Operations (legacy) and Enterprise for Incident Management.
Customize PagerDuty Incident Body	Customize the PagerDuty incident body when an incident is created from ServiceNow. Use braces to input variables from columns in the incident table and {workNote} to include a work note.

PagerDuty Settings

Expand

These values should have already been entered during the Integration Walkthrough. However, you may choose to 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, e.g., https://subdomain.pagerduty.com
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 service ID	You 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 service URL and paste it into this field.
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. You may either create a Default User in PagerDuty (recommended) or provision one from this field in ServiceNow. Please note that if you choose to provision from ServiceNow, you will be provisioned as the Default User in PagerDuty. Omitting this field could result in incidents not being created in PagerDuty, if they are created by ServiceNow users that have not been provisioned to PagerDuty.
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

Expand

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 to the aforementioned ServiceNow user.
Sync option	You may select the incident sync method from the dropdown: - Auto: When a PagerDuty incident triggers, it automatically creates a ServiceNow Incident. The same logic applies in the ServiceNow Incident to PagerDuty Incident direction. - Manual: When a PagerDuty incident triggers, it will not automatically create a ServiceNow Incident. Instead, you will see a Sync to ServiceNow button on the PagerDuty incident’s details page. The same logic applies in the ServiceNow Incident to PagerDuty incident direction.
Task type	At this time, only Incident task types are available.
ServiceNow REST endpoint for webhook	Optionally modify the path that PagerDuty uses to send webhooks. It is recommended that you leave this value as is.
Workflow Connection	The connection used to create ServiceNow Incidents based on PagerDuty Incident Workflows.

Activity Stream Customization

Expand

Configuration options to control what PagerDuty information is shown in the ServiceNow incident activity stream. Check an option to enable and Uncheck to disable the following information:

• Incident triggering
• Incident assignment
• Incident reassignment and escalation
• Status updates
• Added responders
• Responder responses
• Incident workflows
• Conference bridge addition
• Custom Fields updates
• Custom Fields errors

PagerDuty API requests customization

Expand

HTTP headers

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

Use MID Server

The ServiceNow v8 integration comes with optional MID server support. Please see our Advanced ServiceNow Configuration article for more information.

Legacy Settings

Expand

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.

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:

It is possible to modify these components. However, please note that any customizations to these core components, which 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: The Health Check validates if the integration is able to successfully make requests to the PagerDuty REST API. You should get a Connection test successful (200) response if the request was successful.
• Test ServiceNow User Authentication: The Health Check validates the username and password for the integration user in ServiceNow. Specifically, the ServiceNow integration user on the PagerDuty Settings page. You should get a ServiceNow user authentication test successful (200) response if the validation was successful.
• Test Default User Settings: The Health Check validates the UserID 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 if there are any changes required.
• Test Workflow Connection: The Health Check validates if 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 the health check is complete, the results will be displayed on this page.
• When to run the Integration Health Check: We recommend running Integration Health Checks during the initial configuration of the PagerDuty app in ServiceNow, and also 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 the concept of asynchronous job execution to fetch all required data from PagerDuty and ServiceNow, and then it 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. Then click Run health check or Re-run health check to initiate the process.
• When to Run a Webhook Health Check: Run the Webhooks Health Check during initial configuration of the PagerDuty app in ServiceNow, and also when upgrading the app to v8. Additional Webhooks Health Checks can be executed after installation/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, please 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. Next, navigate to Webhooks Health Check.
3. Click Run health check.
4. If there are any inconsistencies, we recommend resolving them prior to migrating webhooks to v3.
5. Next, select All and search and select Webhooks Migration and Migrate your webhooks.
6. You should see a confirmation modal indicating 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/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. However, 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 script for v3 webhooks – contains the logic for all default operations taken when updating or inserting an incident (e.g., 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