Advanced ServiceNow Configuration

How to leverage the full power and versatility of the ServiceNow and PagerDuty integration.

ServiceNow is a complex enterprise integration that allows for versatile configurations with your PagerDuty account to meet the specific criteria of your unique business. Below are some guidelines for customizing your ServiceNow integration with advanced configurations.

Best Practices for Automation

It is strongly recommended that between inbound field rules, priority synchronization, webhook import customization and the basic behavior of the integration (i.e. mapping between configuration items / assignment groups and PagerDuty services / escalation policies), there is no overlap in terms of automated modification to records in ServiceNow (such as Assignment Rules).

Make sure that in any given automation, you do not modify any fields that are already set automatically by some other feature of the integration, or used by the integration in the mapping of objects between ServiceNow and PagerDuty.

For example, if you map configuration items to PagerDuty services in the integration, do not set the CI field of an incident automatically in the inbound field rules. Especially 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.

Inbound Field Rules

You can define rules for automatically setting values for fields in the ServiceNow incident based on fields in the data of the webhook from PagerDuty. Required fields can be set when creating or modifying incidents automatically through the integration. Additionally, custom JavaScript code can be run in the process of importing incident lifecycle data into ServiceNow.

Two example rules, which are disabled by default but available for reference and adaptation, are available with the base installation of the app:

  • Configuration item - set from payload on trigger
  • Configuration Item - set default on trigger*
The Inbound Field Rules menu

The Inbound Field Rules menu

Basic Setup

  1. To begin, go to PagerDutyConfigurationInbound Field RulesNew to open the form to create a new field rule. Ensure Active is checked, if you wish to make it active immediately.
  2. Select the PagerDuty Webhook Type to specify which incident lifecycle event the rule should be applied at. For a list of webhook types, see Webhooks Overview: Webhook Types.
  3. Select the ServiceNow Incident field to be populated, and define how the field should be set:
  4. Set Default Value: use a fixed value to populate the field.
  5. Set From PagerDuty Webhook Payload: Using dot notation, specify the namespace path to the property of the PagerDuty webhook to be used.
  6. When setting a default value, a freeform text field will appear in which you can specify the value to set for the field.
Inbound Field Rule definition form

Inbound Field Rule definition form

Setting Based on the Payload

When setting from 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 properties that are available, you can look in Webhook Import Rows; sample JSON-encoded objects should be saved in the Payload column.

A few examples of fields in the PagerDuty webhook payload one could specify:

  • log_entries: the log entry object associated with the incident lifecycle event. See Log Entries API for the expected schema of such objects.
    • log_entries.channel: if the event is incident.trigger, this will be the original data received by PagerDuty that triggered the incident. This could be useful if the incident originated from an upstream monitoring tool.
    • log_entries.service: The service on which the incident was triggered / to which it corresponds.
    • log_entries.teams: An array of TeamReference objects
  • event: the Webhook Type
  • incident: the incident object (see "Response Schema" in the Incidents API reference)

Running a Lookup Script

By enabling this option, you can run custom JavaScript to perform additional actions in lieu of each field rule to obtain additional data, and define the final value to be applied to the ServiceNow incident field. A text area box will appear when checking the “Run lookup script”.

Within the scope of the script, there will be variable named value defined, whose value will be that of the property 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.

Testing Your New Inbound Field Rule

If you are setting a field from PagerDuty webhook, you can test the rule you created by pressing the Test Set From PagerDuty Webhook Payload button. This will allow you to specify the Webhook Payload Field name (such as log_entries.channel), provide a sample payload (copied from one of your Webhook Import Rows table), then verify the returned value.

Priority Synchronization

Priority levels set for incidents in PagerDuty can automatically set the priority levels on the linked incident in ServiceNow, and vice versa.

When the priority is modified on the incident in ServiceNow, it is updated in real-time in PagerDuty. Similarly, the incident priority is set when initially triggering the incident in PagerDuty.

When changing the priority on a PagerDuty incident, the change will be reflected in ServiceNow after the next webhook event is sent to ServiceNow for the incident.

Importing PagerDuty Priorities

The first step is to define some incident priorities in your PagerDuty account, by going to ConfigurationIncident Priorities.

Once that is complete, navigate in ServiceNow to PagerDutyConfigurationRefresh PagerDuty Priorities. Once this is done, the priorities will populate into the table x_pd_integration_pagerduty_priority, whose contents are displayed under Priorities.

Defining the Priority Mapping

Once you have imported your PagerDuty priorities, go in ServiceNow to PagerDutyConfigurationPriorities. You will find there a predefined list of your PagerDuty Priorities, which can then be mapped to ServiceNow Urgency and Impact value pairs. The computed ServiceNow priority value will also be shown in the table.

The Priority Data Lookup list

The Priority Data Lookup list

To edit how incident priorities in PagerDuty map to priorities in ServiceNow, click on the PagerDuty priority field in the mapping in question to edit the record and set a value for its corresponding ServiceNow Impact and ServiceNow Urgency. On save, the ServiceNow Priority will be computed and shown in the table.

The priority mapping form

The priority mapping form

Customized Automation

If you need further automation to be taken in the webhook import process (when data and events from PagerDuty are synchronized to ServiceNow) beyond inbound field rules, the preferred way is to edit the PagerDutyInboundCustomScript Script Include. This script include will not be modified in future releases, and so any local modifications to the source code can be safely made without concern for incorporating changes from software updates.

The script is found in ServiceNow under PagerDutyConfigurationConfiguration FilesScript Includes.

Within the source code of that script include, you will find a function customPostTransformActivity defined in the prototype declaration of the PagerDutyInboundCustomScript include. This is the function where you will define code to run in lieu of all the other actions taken when webhook data from PagerDuty, corresponding to the PagerDuty incident, is translated into incident data in ServiceNow. This function will be executed during the Webhook Import process (see under *How the Integration Works for further details on this).

Within the scope of that function, the three parameters available as local variables are as follows:

  1. source (GlideRecord): the webhook import row. Note the property source.payload, which contains a JSON string representing the payload of the webhook.
  2. target (GlideRecord): the ServiceNow incident to be created or updated, depending on the action.
  3. action (string): will be insert if a new incident record in ServiceNow is being created, or update if an existing one is being updated.

Advanced ServiceNow Configuration


How to leverage the full power and versatility of the ServiceNow and PagerDuty integration.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.