Advanced ServiceNow Configuration
How to leverage the full power and versatility of the ServiceNow integration.
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.
- Navigate to Custom Field Mappings.
- Select New from the top right.
- 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.
- Enter the following under Configure the new PagerDuty field:
- Display Name: Enter a display name for the PagerDuty incident UI.
- Field Name: Enter a field name.
- Description (Optional): Enter an optional description.
- 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
- Navigate to Custom Fields Mappings
- Select the record you want to delete.
- Click Delete.
- 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
anddue_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
- 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.
- 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
- Navigate to PagerDuty in the application navigator and select Map Priority to Escalation Policy.
- Click New and select the Assignment Group, Escalation Policy and Priority you wish to map and check the Active checkbox.
- 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
- Search and click into your preferred Assignment Group. Select the PagerDuty Escalation Policies tab and click New.
- 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
- In ServiceNow, go to PagerDuty Configuration Inbound Field Rules New to open the form to create a new field rule.
- If you wish to make the rule active immediately, check Active.
- Select the PagerDuty Webhook Type to specify which event the rule should be applied to.
- For a list of webhook types, see Webhooks Overview: Webhook Types.
- The Trigger event type applies to manually-triggered incidents created through the new Create a ServiceNow Incident Workflow action.
- Select the ServiceNow incident field to be populated, and define how the field should be set:
- Set Default Value: Use a fixed value to populate the field.
- Set From PagerDuty Webhook Payload: Using dot notation, specify the namespace path to the property of the PagerDuty webhook to be used.
- 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
- Confirm the properties that are available from the webhook payload.
- 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.
- To see available properties, you can look in Webhook Import Rows; sample JSON-encoded objects should be saved in the Payload column.
- Navigate to the inbound field rule to test setting this field.
- 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
- 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.
- 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. - 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
- Check your Inbound Field Rules to confirm which rules are setting ServiceNow incident fields based on the PagerDuty webhook payloads.
- The
log_entries
parameter in v2 webhooks, has been modified tofirst_trigger_log_entry
for v3 webhooks. To make that additional API call to retrieve thefirst_trigger_log_entry
information, a new flagfetch_first_trigger_log_entry
(System Property) has been introduced in ServiceNow V8. If you have any Inbound Field Rules referencing thelog_entries
parameter in v2 webhooks, this additional API call will be required in order to retrieve information from the newfirst_trigger_log_entry
field. Please follow these steps to enable the flag:- Navigate to the ServiceNow instance and log in with appropriate credentials.
- Open the System Properties module ( in the menu type
sys_properties.list
). - Search for the new property
*fetch_first_trigger_log_entry
that controls the additional API call forfirst_trigger_log_entry
data. - 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. - 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
- Repeat the following steps for each Inbound Field Rule identified in Step 1 of Check Inbound Field Rules above.
- Find an example v3 webhook payload:
- Navigate to Pagerduty Import Rows Webhook Import Rows.
- Find an example v3 webhook, matching the PagerDuty webhook type of your inbound find rule.
- Copy the example v3 webhook payload.
- Find an example v3 webhook payload:
- Navigate back to the inbound field rule and check the PagerDuty webhook payload field.
- Reference the example v3 webhook payload to confirm if the field needs to be updated to align with the new v3 payload structure.
- Update the PagerDuty webhook payload field as necessary.
- 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
oradmin
.
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.
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
):
- Navigate to System Clone Preserve Data, and select New.
- Create a new record for the Clone Data Preserver and select the table System Property [sys_properties].
- 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
- Click Submit.
User Table
Next, create a Clone Data Preserver for the sys_user
table:
- Navigate to System Clone Preserve Data, and select New.
- Create a new record for the Clone Data Preserver and select the table User [sys_user].
- Create a filter with the following condition:
- PagerDuty ID is not
empty
.
- PagerDuty ID is not
- Click Submit.
Group Table
Thirdly, create a Clone Data Preserver for the sys_user_group
table:
- Navigate to System Clone Preserve Data, and select New.
- Create a new record for the Clone Data Preserver and select the Group [sys_user_group] table.
- 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
- PagerDuty escalation
- Click Submit.
Configuration Item Table
Lastly, create a Clone Data Preserver for the cmdb_ci
table.
- Navigate to System Clone Preserve Data, and select New.
- Create a new record for the Clone Data Preserver and select the Configuration Item [cmdb_ci] table.
- Create filters with the following conditions:
- PagerDuty service
is not empty
OR
- PagerDuty webhook
is not empty
- Click Submit.
Use a MID Server
- To enable, navigate to PagerDuty Settings in the application navigator and scroll to the Activity Stream Customization section.
- Check the Use MID Server checkbox.
- The Set MID Server field will have the default MID server auto-populated. Enter your parameters in the ECC parameters field.
- Click Save.
Updated 25 days ago