{/* migration: slug: servicenow-integration-details */} {/* migration: section: integrations */} 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](doc: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](doc:servicenow-integration-details-v7) for the v7 integration are also available. # Integration Capabilities An infographic depicting ServiceNow integration capabilities

An infographic depicting ServiceNow integration capabilities

# Installation and Configuration - **Installation**: For installation instructions, refer to the [ServiceNow Integration Guide](doc:servicenow-integration-guide). - **Advanced Configuration**: For more in-depth information about customizing the ServiceNow integration, refer to [Advanced ServiceNow Configuration](doc: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 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](https://store.servicenow.com/store/app/82fa2be61b246a50a85b16db234bcb5c). 3. Navigate to **System Diagnostics** :fa-arrow-right: **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](doc:servicenow-integration-guide#11-servicenow-application-access-controls). 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** :fa-arrow-right: **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](doc:advanced-servicenow-configuration#check-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](doc:servicenow-integration-guide) or [upgraded](#upgrade-to-servicenow-v8), global integration settings can be found by navigating to **PagerDuty Settings**. A screenshot of the ServiceNow web app showing the PagerDuty app's settings

A screenshot of the ServiceNow web app showing the PagerDuty app's 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](doc: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](doc: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](doc: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](doc: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](doc: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](doc: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

PagerDuty Settings

You can gather some of these values by following the initial steps in the [ServiceNow Integration Guide](doc:servicenow-integration-guide). You may also edit them at a later date by following [steps 2–5](doc:servicenow-integration-guide#step-2-configuration-in-pagerduty) 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](doc: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 with the [Default PagerDuty User Account for ServiceNow](doc: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](doc:service-regions)**: Leave as the default, `https://api.pagerduty.com`. **If your account is hosted in the EU [service region](doc:service-regions)**: 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: A screenshot of the ServiceNow web app showing activity stream customization

A screenshot of the ServiceNow web app showing 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, for example `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. See [Advanced ServiceNow Configuration](doc:advanced-servicenow-configuration#use-a-mid-server) 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** :fa-arrow-right: **Configuration** :fa-arrow-right: **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. | 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 A flowchart depicting the integration health check

A flowchart depicting the 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. A screenshot displaying example output of the Integration Health Check

A screenshot displaying example output of the Integration Health Check

## 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](doc:servicenow-integration-guide) of the PagerDuty app in ServiceNow and when [upgrading the app to v8](#upgrade-to-servicenow-v8). # Webhooks Health Check A flowchart depicting the webhook health check

A flowchart depicting the webhook 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. A screenshot showing an example of the Webhooks Health Check output

A screenshot showing an example of the Webhooks Health Check output

A screenshot of the ServiceNow web app showing an overview of webhooks' 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** 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](doc:servicenow-integration-guide) of the PagerDuty app in ServiceNow and when [upgrading the app to v8](#upgrade-to-servicenow-v8). Additional Webhooks Health Checks can be run after installation or upgrade at the Admin's discretion. # Webhooks Migration A flowchart depicting the PagerDuty v3 webhook migration

A flowchart depicting the PagerDuty v3 webhook 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](#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](doc: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

An image depicting the communication flow from PagerDuty to ServiceNow

**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. | Variable | Description | | :---------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `source` | The import record. The field `source.message_type` is particularly important, as it will be one of the [webhook types](https://developer.pagerduty.com/docs/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

An image depicting the communication flow from ServiceNow 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 An image depicting an overview of ServiceNow and PagerDuty incident interaction

An image depicting an overview of ServiceNow and PagerDuty incident interaction