# ServiceNow Integration Details

An overview of how the ServiceNow v8 integration works

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](/integrations/servicenow-integration-guide) integration, and will give you a deeper understanding of how it works at a fundamental level.

> **Looking for a Different Version?:** [ServiceNow Integration Details](https://support.pagerduty.com/main/docs/servicenow-integration-details-v7) for the v7 integration are also available.

## Integration Capabilities

![An infographic depicting ServiceNow integration capabilities](/images/kb/8c2d303be3b1acf5920ff53a3ccc28774adccb36557b6dc0c6d6d8796890720a-V8_New_Features_1.webp)

## Installation and Configuration

- **Installation**: For installation instructions, please refer to the [ServiceNow Integration Guide](/integrations/servicenow-integration-guide).
- **Advanced Configuration**: For more in-depth information about customizing ServiceNow integration, please refer to [Advanced ServiceNow Configuration](/integrations/servicenow-integration-guide/advanced-servicenow-configuration).

### Upgrade to ServiceNow v8

> **Required User Permissions:** You must have a ServiceNow Admin role to upgrade the integration.

1. [Revert customizations](https://docs.servicenow.com/bundle/vancouver-platform-administration/page/customer-support/task/revert-customization.html) 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](https://store.servicenow.com/store/app/82fa2be61b246a50a85b16db234bcb5c).
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.
   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 our integration guide](/integrations/servicenow-integration-guide#11-servicenow-application-access-controls).
6. 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.  
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](/integrations/servicenow-integration-guide/advanced-servicenow-configuration#check-inbound-field-rules) to extract data from the new v3 webhook payload.
10. **If you had customizations** (_Optional_):  
    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 (i.e., 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 incur breakage in the new version of the integration.

## Manage Integration Settings

Once the ServiceNow v8 integration has been [initially configured](/integrations/servicenow-integration-guide) or [upgraded](#upgrade-to-servicenow-v8) to, global integration settings can be found by navigating to **PagerDuty Settings**.

![A screenshot of the ServiceNow web app showing the PagerDuty app's settings](/images/kb/56642cbfdfa2c2b67ea1ec01471ccf55007e20aa2b561e6a3d9a9875ebabcf06-PagerDuty_settings.webp)
*PagerDuty Settings page in ServiceNow*

### 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](/integrations/servicenow-integration-guide/servicenow-provisioning#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](/account-admin/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](/incident-management/incidents/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](/incident-management/incidents/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](/ai-automation/automation/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](/incident-management/communicate/communicate-with-stakeholders#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

You can gather some of these values by following the initial steps in the [Integration Walkthrough](#integration-walkthrough). However, you may choose to edit them at a later date by following [steps 2-5](/integrations/servicenow-integration-guide#step-2-configuration-in-pagerduty) again.

| Setting                                                   | Values                                                                                                                                                                                                                                                                                                                                                     |
| :-------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| PagerDuty account URL (`https://subdomain.pagerduty.com`) | Your PagerDuty subdomain URL, e.g., `https://subdomain.pagerduty.com`                                                                                                                                                                                                                                                                                      |
| PagerDuty API access key                                  | Paste the [REST API key](/integrations/servicenow-integration-guide#21-create-a-pagerduty-api-access-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 to the [Default PagerDuty User Account for ServiceNow](/integrations/servicenow-integration-guide#22-create-a-default-pagerduty-user-account-for-servicenow) . |
| REST API Endpoint                                         | - **If your account is hosted in the US [service region](/get-started/service-regions)**: This should be left as the default, `https://api.pagerduty.com` - **If your account is hosted in the EU [service region](/get-started/service-regions)**: Enter `https://api.eu.pagerduty.com`                                                                                 |

### 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 (e.g. ServiceNow incident work notes stream). Check the options that you want to display in the incident activity stream:

![A screenshot of the ServiceNow web app showing activity stream customization](/images/kb/ade26f8170444efbd5616a2be64fc5f3454eeb564dac8468fdf1258df46d00de-snow-activity-stream-customization.webp)
*ServiceNow activity stream customization*

### PagerDuty API requests customization

#### HTTP headers

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

#### Use MID Server

The ServiceNow integration comes with optional [MID server](https://docs.servicenow.com/bundle/vancouver-servicenow-platform/page/product/mid-server/concept/mid-server-landing.html) support. Please see our [Advanced ServiceNow Configuration](/integrations/servicenow-integration-guide/advanced-servicenow-configuration#use-a-mid-server) article for more information.

### 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** 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**:

| Component | Description |
| --- | --- |
| **PagerDuty** | Functions for performing actions on incidents, including incident assignment, syncing work notes, and triggering incidents. |
| **PagerDutyInbound, PagerDutyInboundV3** | Functions that handle receipt and processing of webhooks from PagerDuty. |
| **PagerDutyProvisioning** | Handles the creation of objects in PagerDuty from ServiceNow. |
| **PagerDuty\_REST** | Core functions for making REST API requests. |
| **PagerDutyInboundWorkflowActions** | For Workflow actions, and manual sync of PagerDuty incidents to create a ticket in ServiceNow. |

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

![A flowchart depicting the integration health check](/images/kb/3b9d928f153646c30da24d0dacd12c2d838d553e7ed69bcaf2e0e69864ffbad3-snow-v8-details-integration-health-check.webp)
*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.

![A screenshot displaying example output of the Integration Health Check](/images/kb/eb743f4f4b194558310d395ade69b22aff9198bcb738e185a66b7f5185a12daa-snow-v8-integration-health-check-example.webp)
*Integration Health Check example*

### 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](/integrations/servicenow-integration-guide) of the PagerDuty app in ServiceNow, and also when [upgrading the app to v8](#upgrade-to-servicenow-v8). 

## Webhooks Health Check

![A flowchart depicting the webhook health check](/images/kb/0293ce85098e6c8534bd4cb16f9d102cfffe4ec557173e3ccec05a8cae7acd12-snow-v8-webhook-health-check.webp)
*Webhook health checks*

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

![A screenshot showing an example of the Webhooks Health Check output](/images/kb/df7a4be-snow-v8-webhooks-health-check-example.png)

![A screenshot of the ServiceNow web app showing an overview of webhooks' status](/images/kb/88050583d32b294961ad50ac014516a4292463c53ab9c9979a2340573a27001b-Webhook_Health_Check.webp)
*Webhook status*

### 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** to initiate the process. Review the results, and resolve any inconsistencies detected by the health check. Then re-run the health check again to confirm that the inconsistencies have been resolved.
- **When to Run a Webhook Health Check**: Run the Webhooks Health Check during [initial configuration](/integrations/servicenow-integration-guide) of the PagerDuty app in ServiceNow, and also when [upgrading the app to v8](#upgrade-to-servicenow-v8). You can execute additional Webhooks Health Checks after installation/upgrade at the Admin’s discretion.

## Webhooks Migration

![A flowchart depicting the PagerDuty v3 webhook migration](/images/kb/d4058acd772facf8bd54e830bfbdf7e9d8b45d857cf68c1eeefab639e1b3f63a-snow-v8-webhook-migration.webp)

### 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](#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](/integrations/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.

![An image depicting the communication flow from PagerDuty to ServiceNow](/images/kb/f28bdca9a9cbb140ad920297a8d80d626cfff8a755ac20954e4574b919d90970-pd-to-snow.webp)
*PagerDuty to ServiceNow communication flow*

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

| Variable | Description |
| --- | --- |
| `source` | The import record. The field `source.message_type` is particularly important, as it will be one of the [webhook types](/developer/webhooks-overview). |
| `action` | This will be `insert` or `update` depending on whether a new incident record is created or an existing incident is updated. |
| `assignOnAckOnly` | A boolean value (`true` or `false`), determined by the setting **Only assign based on an acknowledgment from PagerDuty user**. Its value determines whether the ServiceNow incident should be assigned based on acknowledgment from PagerDuty, or if the integration should synchronize incident assignment between ServiceNow and PagerDuty with each webhook update. |
| `target` | A GlideRecord object representing the incident in ServiceNow that will be created or updated. |

### 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

![An image depicting the communication flow from ServiceNow to PagerDuty](/images/kb/04b23ce6832b0879f02356706c3753fa1967c2036009e7ec93bdab052b809908-snow-to-pd.webp)
*ServiceNow to PagerDuty communication flow*

#### 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

![An image depicting an overview of ServiceNow and PagerDuty incident interaction](/images/kb/e474b46f5ebd6426b847b90a9450d0ed8e51f42a7b8d77a6f8410730b421c4db-snow-interaction-pd-incidents.webp)