ServiceNow v8 is a robust, highly-customizable enterprise integration that you can configure to meet your business’s needs. Below are some guidelines to customize your ServiceNow integration with advanced features.

📘

Support Notes

• This article illustrates ways you may choose to customize workflows in the ServiceNow integration. Please note, however, that any customizations which alter the integration’s out-of-the-box behavior are not supported by the PagerDuty Support team.
• For assistance with advanced ServiceNow configurations, please contact your account manager/sales representative, or reach out to PagerDuty Services.

📘

Looking for a Different Version?

Advanced ServiceNow Configuration for the v7 integration is also available.

Best Practices for Automation

Please ensure the following:

• Do not auto-populate or modify any fields that have dependencies – meaning that the integration uses data from the field elsewhere within the integration.
• Do not auto-populate or modify any fields that the integration uses to map objects between ServiceNow and PagerDuty.

For example, if you map Configuration Items to PagerDuty services in the integration, do not set the CI field in the inbound field rules. If you have enabled priority synchronization, do not define any rules that set the Urgency, Impact or Priority fields in ServiceNow incidents.

Keeping automation simple and non-overlapping will help you avoid unpredictable or unstable behavior.

📘

Availability

Premium features such as PagerDuty Custom Field synchronization and “Create a ServiceNow Incident” as an Incident Workflow Action are only available on the Enterprise Incident Management plan. Please contact our Sales Team for more information

Custom Field Mappings

🚧

Required User Permissions

• In ServiceNow: Only users with the x_pd_integration.admin role can view, create and delete Custom Field Mappings in ServiceNow.
• In PagerDuty: Only Global Admins and Account Owners can create, edit, and delete custom fields.

The Custom Field Mappings feature allows you to define field-level mapping between the ServiceNow integration and PagerDuty incident Custom Fields with the same data type. Once the fields are mapped, the field options (single and Multi Select) and values will sync bi-directionally.

Custom Field data from PagerDuty incidents syncs to the associated fields in the ServiceNow incident record, and those ServiceNow fields sync to the associated Custom Fields in the PagerDuty incident. The PagerDuty incident and ServiceNow incident must be linked for those fields to sync.

Custom Fields that are defined as part of the integration will count towards the account’s limits for custom fields. For more information, please see our Custom Fields on Incidents article.

Custom Field Mapping Update Behavior

The integration will immediately update PagerDuty Custom Fields options when you make changes to the mapped ServiceNow Incident Record Field:

• If you add an option to a mapped ServiceNow Incident Record Field, the integration will add the option to the dropdown on the PagerDuty incident detail page.
• If you delete an option from a mapped ServiceNow Incident Record Field, the integration will delete the option from the dropdown on the PagerDuty incident detail page.
• If you rename an option in the ServiceNow Incident Record Field, the integration will reflect the new name in the dropdown on the PagerDuty incident detail page.

These changes must be made from the Custom Field Mappings page within ServiceNow; these changes cannot be made from the PagerDuty custom field.

View Custom Field Mappings

To view your custom field mappings in ServiceNow, navigate to Custom Field Mappings.

Create Custom Field Mappings

🚧

Restrictions

• You cannot map multiple ServiceNow Incident Record Fields to one PagerDuty custom field, or multiple custom fields to one ServiceNow Incident Record Field.
• You cannot map a read-only ServiceNow Incident Record Field to a PagerDuty custom field.

1. Navigate to Custom Field Mappings.
2. Select New from the top right.
3. Select a ServiceNow field (Required): Select your preferred ServiceNow field from the dropdown. We will only fetch ServiceNow fields that match the approved field types.
4. Enter the following under Configure the new PagerDuty field:
   1. Display Name: Enter a display name for the PagerDuty incident UI.
   2. Field Name: Enter a field name.
   3. Description (Optional): Enter an optional description.
5. Review the mapping and then click Save.

Edit Custom Field Mappings

At this time, Custom Field Mappings cannot be edited. Once created, custom field mappings will need to be deleted and then re-created.

Delete Custom Field Mappings

1. Navigate to Custom Fields Mappings
2. Select the record you want to delete.
3. Click Delete.
4. A confirmation modal will appear. Click Delete again to confirm.

ServiceNow Fields Eligible for Mapping

Fields of the following data types are eligible for mapping

• Choice (Choice, String w/ Choice Set, Integer w/ Choice Set) without dependent values.
  • Note: Fields associated to Choice Sets of type “Suggestion” will be treated as being of their underlying data type (String, Integer, etc.), i.e. they will not be treated as choice fields.
• Date Time (glide_date_time and due_date)
• URL
• String
• Integer
• Decimal
• Boolean (True/False)

The following ServiceNow Incident Record Fields are eligible for mapping

Label	Columns	Data Type	Choice?
Active	active	boolean	No
Activity due	activity_due	due_date	No
Actual end	work_end	glide_date_time	No
Actual start	work_start	glide_date_time	No
Approval	approval	string	Yes
Approval set	approval_set	glide_date_time	No
Business impact	business_impact	string	No
Business resolve time	business_stc	integer	No
Category	category	string	Yes
Child Incidents	child_incidents	integer	No
Close code	close_code	string	Yes
Close notes	close_notes	string	No
Closed	closed_at	glide_date_time	No
Conference Bridge	x_pd_integration_conf_bridge	string	No
Contact type	contact_type	string	Yes
Correlation display	correlation_display	string	No
Correlation ID	correlation_id	string	No
Description	description	string	No
Due date	due_date	glide_date_time	No
Effective number	task_effective_number	string	No
Expected start	expected_start	glide_date_time	No
Follow up	follow_up	glide_date_time	No
Impact	impact	integer	Yes
Incident state	incident_state	integer	Yes
Knowledge	knowledge	boolean	No
Last reopened at	reopened_time	glide_date_time	No
Notify	notify	integer	Yes
Number	number	string	No
On hold reason	hold_reason	integer	Yes
Opened	opened_at	glide_date_time	No
Order	order	integer	No
Probable cause	cause	string	No
Reassignment count	reassignment_count	integer	No
Reopen count	reopen_count	integer	No
Resolve time	calendar_stc	integer	No
Resolved	resolved_at	glide_date_time	No
Severity	severity	integer	Yes
Short description	short_description	string	Yes — “Suggestion”
State	state	integer	Yes
Transfer reason	route_reason	integer	Yes
Upon approval	upon_approval	string	Yes
Upon reject	upon_reject	string	Yes
Urgency	urgency	integer	Yes

Post-mapping Behavior

Post-mapping Behavior in ServiceNow

• You can delete the mapping.
  • When this happens, future synchronization will stop. Any value on historical Integration records from this mapping will be preserved (i.e. no back-deleting values).
• You can’t delete the PagerDuty Custom Field created by the integration. You must delete PagerDuty Custom Fields in PagerDuty.
• You can’t edit the PagerDuty Custom Field Name or Description; it is effectively a read-only mapping.

Post-mapping Behavior in PagerDuty

• You can change the Custom Field Display Name and/or the Description.
• You can view the Custom Field in the PagerDuty UI.
• You can’t edit the Custom Field options (if it is a Single/Multi-select data type), but you can view the options.
• You can’t delete the Custom Field if it’s mapped to an integration. You must delete the Custom Field mapping in ServiceNow before deleting the Custom Field in PagerDuty.
• You can’t force-delete the Custom Field mapping from the PagerDuty UI.

🚧

You must delete the Custom Field mapping in ServiceNow before deleting the Custom Field in PagerDuty.

• If you are unable to remove a custom field mapping because it was not removed from ServiceNow first, please reach out to [email protected] for assistance.

How Custom Fields are Synced

Syncing Custom Fields From PagerDuty to ServiceNow

Syncing Custom Fields From ServiceNow to PagerDuty

Sync a Custom Field Mapping with a Default Value

When you create a ServiceNow Incident, the ServiceNow Incident Record Field should be populated with the default value of the mapped PagerDuty Custom Field. This is a fast-follow action after the record is created, because Custom Field default values are passed through via a v3 webhook event: incident.custom_field_values.updated.

How ServiceNow Incident fields Sync with PagerDuty Custom Fields Populated by Event Orchestration

1. Configuration: You can create the Custom Field mapping within ServiceNow. At this time, we do not have any features that allow you to map a new ServiceNow Incident Record Field to an existing PagerDuty Custom Field.
2. Usage: When the Event Orchestration populates the PagerDuty Custom Field, that value is immediately synced to the mapped ServiceNow Incident Record Field. When you change the value of the ServiceNow Incident Record Field, the value is synced back to the PagerDuty Custom Field. If the PagerDuty Custom Field is populated with an invalid value, which the integration does not recognize, then that value will not sync to the ServiceNow Incident Record Field.

Precedence

The latest value updated in either platform will always take precedence. These fields can be changed even after an incident is resolved, in case you want to update information only discovered during your Incident Review process.

Configure Escalation Policy Priority Mapping

The ServiceNow v8 integration allows Assignment Groups to have more than one escalation policy assigned to incidents based on incident priority in ServiceNow. For example, if you would like one escalation policy assigned to incidents with a priority of Moderate or below and another for priorities above Moderate, you could map escalation policies to this scheme. There are two ways to configure this feature: via the PagerDuty menu or on an individual Assignment Group.

To configure escalation policy priority mapping via the PagerDuty menu

1. Navigate to PagerDuty in the application navigator and select Map Priority to Escalation Policy.
2. Click New and select the Assignment Group, Escalation Policy and Priority you wish to map and check the Active checkbox.
3. Click Submit to save. If you would like to deactivate this mapping, return to the Map Priority to Escalation Policy screen, click the status in the Active column, uncheck the Active checkbox and click Update. You may repeat this process to map multiple escalation policies to different priorities.

To configure escalation policy priority mapping on an individual Assignment Group

1. Search and click into your preferred Assignment Group. Select the PagerDuty Escalation Policies tab and click New.
2. In the Escalation Policy field, search and select your preferred escalation policy. In the Priority field, search and select which priority should be mapped to that escalation policy. Check the Active checkbox to activate this setting and click Submit. You may repeat this process to map multiple escalation policies to different priorities.

Once configured, when an incident is assigned to that assignment group and the mapped priority, the mapped escalation policy will be assigned to that incident.

Create a ServiceNow Incident as a Workflow Action

Please read our Incident Workflows article for more information about creating a ServiceNow Incident Workflow action.

v3 Webhooks

Supported Event Types

• incident.triggered

• incident.acknowledged

• incident.unacknowledged

• incident.annotated

• incident.delegated

• incident.escalated

• incident.reassigned

• incident.resolved

The introduction of v3 webhooks adds support for the following event types:

• incident.priority_updated

• incident.responder.added

• incident.responder.replied

• incident.conference_bridge.updated

• incident.workflow.completed

• incident.workflow.started

New Event Types in v8

Responder Events

• incident.responder.added
• incident.responder.replied

The above PagerDuty responder updates sync to the ServiceNow Incident Work Notes and in the PagerDuty Response table in ServiceNow.

Priority Events

• incident.priority_updated

Responders no longer need to publish PagerDuty notes to force-sync priority changes to ServiceNow. When you update the priority of the incident in PagerDuty, the ServiceNow incident record is also updated to reflect the corresponding priority (as defined in the priority mappings).

Conference Bridge Events

• incident.conference_bridge.updated

New PagerDuty incidents triggered with conference bridges will have that reflected in the Conference Bridge field of the ServiceNow incident. Changing the conference bridge on an existing PagerDuty incident will update the field in ServiceNow.

Asynchronous Webhook Processing

Prior to the ServiceNow v8 release, webhooks were processed synchronously in ServiceNow with some known implications. One of these implications was the temporary disablement of webhooks when the processing time exceeded the 15 seconds timeout of v2 webhooks. Generic Webhooks (v3) expect a successful 2xx response within 5 seconds.

To mitigate timeout issues, ServiceNow v8 changes the default webhook processing mode from synchronous to asynchronous for both v2 and v3 webhooks. In asynchronous mode, the ServiceNow webhook processor will immediately send a 200 response to PagerDuty and queue the message for background processing.

Multiple Scheduled Script Execution jobs will be provisioned to de-queue and process the webhook events asynchronously. The logs for these jobs can be found in System Logs Events (x_pd_integration.process_webhook), which shows a record of the jobs and their state.

The process for checking webhook failures remains the same: look for error messages in the webhook import logs, and then verify if a new record was created in the Webhook Import Rows table.

Business Rules: ServiceNow to PagerDuty

A business rule is a server-side script that runs when a record is displayed, inserted, deleted, or when a table is queried. Business rules are used to automatically change values in form fields when the specified conditions are met.

PagerDuty Integration Business Rules can be found in ServiceNow under PagerDuty Configuration Configuration Files select the Business Rules tab.

All aspects of the integration that concern any flow of data from ServiceNow to PagerDuty are handled by business rules. If the conditions of a business rule are met, the rule and its associated script are run, which invokes a transaction with the PagerDuty API to perform the necessary actions in PagerDuty.

Most processes that send updates from ServiceNow to PagerDuty will follow the flow of: Business Rule Event Queue Script Action Script Includes.

Notable Fields

• Table: The table to be updated.

• Active: Whether the rule is active or inactive.

• When to run (tab): Shows the conditions under which the Business Rule will execute.

  • Order: Stacks priority of rule execution.
  • When: After, before, async (in relation to the action that is taking place on the table, i.e. after an insert happens on table x, do y).
  • Insert/Update/Delete/Query: The action that takes place on the table e.g. a record is created, updated, deleted, queries.

• Actions (tab): Specifies fields in ServiceNow to update upon the business rule executing.

• Advanced (tab): Will oftentimes contain a script to initiate additional logic. This is typically where an event for the business rule is created and added to the event queue. This code can reference other scripts and script actions within ServiceNow.

Inbound Field Rules

You can define rules to automatically set fields in a ServiceNow incident based on the field values in PagerDuty webhooks. The integration can automatically set required fields when incidents are created or modified. Additionally, you can run custom JavaScript code when incident lifecycle data is imported into ServiceNow.

With the introduction of v3 webhooks, some changes have been made to the payload data compared to v2 webhooks. As a result, the existing Inbound Field Rules that are configured to process v2-webhook-specific data will not function properly with v3 webhooks. You will have to manually update their existing v2-based Inbound Field Rules to point to the appropriate v3 webhook payload fields post-upgrade.

Configure Inbound Field Rules

1. In ServiceNow, go to PagerDuty Configuration Inbound Field Rules New to open the form to create a new field rule.
   1. If you wish to make the rule active immediately, check Active.
2. Select the PagerDuty Webhook Type to specify which event the rule should be applied to.
   1. For a list of webhook types, see Webhooks Overview: Webhook Types.
   2. The Trigger event type applies to manually-triggered incidents created through the new Create a ServiceNow Incident Workflow action.
3. Select the ServiceNow incident field to be populated, and define how the field should be set:
   1. Set Default Value: Use a fixed value to populate the field.
   2. Set From PagerDuty Webhook Payload: Using dot notation, specify the namespace path to the property of the PagerDuty webhook to be used.
4. A free form text field will appear, in which you can specify the default value for the field.

Set Values Based on the Webhook Payload

1. Confirm the properties that are available from the webhook payload.
   1. When setting values based on the webhook payload, a field named PagerDuty webhook payload field will appear, in which you can enter the property of the webhook to reference.
   2. To see available properties, you can look in Webhook Import Rows; sample JSON-encoded objects should be saved in the Payload column.
2. Navigate to the inbound field rule to test setting this field.
   1. If you are setting a field from PagerDuty webhooks, you can test the inbound rule by selecting Test Set From PagerDuty Webhook Payload. This will allow you to specify the Webhook Payload Field name, provide a sample payload (copied from one of your Webhook Import Rows table), then verify the returned value.

Run a Lookup Script

1. Enable this option to run custom JavaScript that performs additional actions and define the final value applied to a ServiceNow incident field. This can be used instead of defining field rules to obtain the additional data.
2. A text box will appear when you check Run lookup script. Within the script’s body there is a variable named value, whose value will be retrieved from the webhook payload specified in the PagerDuty webhook payload field.
3. By the end of the script, define a value for the variable result, and that value will be used to populate the field. It is not necessary to commit or save the record at the end of the script.

Update Inbound Field Rules to Reference the v3 Webhook Payload

Check Inbound Field Rules

1. Check your Inbound Field Rules to confirm which rules are setting ServiceNow incident fields based on the PagerDuty webhook payloads.
2. The log_entries parameter in v2 webhooks, has been modified to first_trigger_log_entry for v3 webhooks. To make that additional API call to retrieve the first_trigger_log_entry information, a new flag fetch_first_trigger_log_entry (System Property) has been introduced in ServiceNow V8. If you have any Inbound Field Rules referencing the log_entries parameter in v2 webhooks, this additional API call will be required in order to retrieve information from the new first_trigger_log_entry field. Please follow these steps to enable the flag:
   1. Navigate to the ServiceNow instance and log in with appropriate credentials.
   2. Open the System Properties module ( in the menu type sys_properties.list ).
   3. Search for the new property *fetch_first_trigger_log_entry that controls the additional API call for first_trigger_log_entry data.
   4. Set the property value to true if you want the system to include first_trigger_log_entry information in the payload of v3 webhooks. Set it to false if you do not want the additional call to be made.
   5. After the flag is enabled, you can update the inbound field rule to reference the first_trigger_log_entry field: data.first_trigger_log_entry.

Update the Inbound Field Rule

3. Repeat the following steps for each Inbound Field Rule identified in Step 1 of Check Inbound Field Rules above.
   1. Find an example v3 webhook payload:
      1. Navigate to Pagerduty Import Rows Webhook Import Rows.
      2. Find an example v3 webhook, matching the PagerDuty webhook type of your inbound find rule.
      3. Copy the example v3 webhook payload.
4. Navigate back to the inbound field rule and check the PagerDuty webhook payload field.
   1. Reference the example v3 webhook payload to confirm if the field needs to be updated to align with the new v3 payload structure.
   2. Update the PagerDuty webhook payload field as necessary.
5. Test the inbound rule by selecting Test Set From PagerDuty Webhook Payload. This will allow you to specify the Webhook Payload Field name, provide a sample payload (the example webhook payload copied from the Webhook Import Rows), then verify the returned value.

Clone Data Preserver

🚧

Required User Permissions

In order to use the Clone Data Preserver feature, your ServiceNow role must include clone_admin or admin.

In some cases, you may want to clone your ServiceNow production data to a developer instance. The Clone Data Preserver is a ServiceNow feature that defines what data should not be replaced when cloning one environment into another.

• Clone results based on Exclusion and Preserver configuration

To clone the PagerDuty integration in a way that it remains functional, you can use the Clone Data Preserver to preserve specified PagerDuty fields. Following the process below, you will make Clone Data Preservers for the four following tables:

System Property Table

To begin, we'll address PagerDuty fields in the System Property table (sys_properties):

1. Navigate to System Clone Preserve Data, and select New.
2. Create a new record for the Clone Data Preserver and select the table System Property [sys_properties].
3. Create OR conditions for the following Names.

• Name Is x_pd_integration.default_user OR

• Name Is x_pd_integration.instance_url OR

• Name Is x_pd_integration.sn2pd_mapping OR

• Name Is x_pd_integration.default_service OR

• Name Is x_pd_integration.api_key `OR

• Name Is x_pd_integration.webhook_restapi OR

• Name Is x_pd_integration.sn_auth_user OR

• Name Is x_pd_integration.sn_auth_userpwd

• Name Is x_pd_integration.connection_id

4. Click Submit.

User Table

Next, create a Clone Data Preserver for the sys_user table:

1. Navigate to System Clone Preserve Data, and select New.
2. Create a new record for the Clone Data Preserver and select the table User [sys_user].
3. Create a filter with the following condition:
   1. PagerDuty ID is not empty.
4. Click Submit.

Group Table

Thirdly, create a Clone Data Preserver for the sys_user_group table:

1. Navigate to System Clone Preserve Data, and select New.
2. Create a new record for the Clone Data Preserver and select the Group [sys_user_group] table.
3. Create filters with the following conditions:
   • PagerDuty escalation is not empty OR
   • PagerDuty schedule is not empty OR
   • PagerDuty service is not empty OR
   • PagerDuty team is not empty OR
   • PagerDuty webhook is not empty
4. Click Submit.

Configuration Item Table

Lastly, create a Clone Data Preserver for the cmdb_ci table.

1. Navigate to System Clone Preserve Data, and select New.
2. Create a new record for the Clone Data Preserver and select the Configuration Item [cmdb_ci] table.
3. Create filters with the following conditions:

• PagerDuty service is not empty OR
• PagerDuty webhook is not empty

4. Click Submit.

Use a MID Server

1. To enable, navigate to PagerDuty Settings in the application navigator and scroll to the Activity Stream Customization section.
2. Check the Use MID Server checkbox.
3. The Set MID Server field will have the default MID server auto-populated. Enter your parameters in the ECC parameters field.
4. Click Save.