❗️

Integration Customizations

The following 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.

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

Best Practices for Automation

It is strongly recommended that you do not configure any overlap, in terms of automated modifications to ServiceNow records (e.g., Assignment Rules), between inbound field rules, priority synchronization, webhook import customization, and the basic behavior of the integration (i.e., mapping between Configuration Items, assignment groups, PagerDuty services and escalation policies, etc.).

In other words, please ensure that your automations do not modify any fields that another feature of the integration acts upon, or 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 of an incident 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 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.

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

Basic Setup

1. 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.
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:

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

4. When setting a default value, 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

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.

A few examples of fields in the PagerDuty webhook payload you might 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)

Run a Lookup Script

Enable this option to run custom JavaScript that performs additional actions and define the final value to be applied to a ServiceNow incident field, 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.

Test Your Inbound Field Rule

If you are setting a field from PagerDuty webhooks, you can test the rule by selecting Test Set From PagerDuty Webhook Payload. 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 it receives the next webhook event for the incident.

👍

Tip

If you need to change an incident’s priority, we recommend leaving a text note to keep relevant stakeholders informed.

Import PagerDuty Priorities

First, define incident priorities in your PagerDuty account by going to User Icon Account Settings Incident Priorities. For more information, please see Enable Incident Priority.

Next, in ServiceNow navigate to PagerDuty Actions Refresh PagerDuty Priorities. After this, priorities will populate in the table x_pd_integration_pagerduty_priority, whose contents are displayed under Priorities.

Define the Priority Mapping

Once you have imported PagerDuty priorities, in ServiceNow navigate to PagerDuty Configuration Priorities. Here you will find 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.

To edit how incident priorities in PagerDuty map to priorities in ServiceNow, select PagerDuty priority in the desired mapping to edit the record and set a value for its corresponding ServiceNow impact and urgency. After saving, the ServiceNow priority will be computed and shown in the table.

Customized Automation

If you need to customize the webhook import process (when data and events from PagerDuty are synchronized to ServiceNow) beyond what inbound field rules offer, we recommend using the PagerDutyInboundCustomScript Script Include. This script include will not be modified in future releases, so you can safely modify its source code without concern for incorporating changes from software updates.

You can find this script include in ServiceNow under PagerDuty Configuration Configuration Files Script Includes.

Within this script include’s source code, you will find a function customPostTransformActivity defined in the prototype declaration. This is the function where you can define what code to run in place of all other actions that are taken when webhook data from PagerDuty is translated into incident data in ServiceNow. This function will be executed during the Webhook Import process.

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

1. source (GlideRecord): the webhook import row. Note the property source.payload, which contains a JSON string representing the webhook’s payload.
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.