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.
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.
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
- To begin, go to PagerDuty → Configuration → Inbound Field Rules → New to open the form to create a new field rule. Ensure Active is checked, if you wish to make it active immediately.
- 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.
- 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.
- 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
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
event: the Webhook Type
incident: the incident object (see "Response Schema" in the Incidents API reference)
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.
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 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.
The first step is to define some incident priorities in your PagerDuty account, by going to Configuration → Incident Priorities.
Once that is complete, navigate in ServiceNow to PagerDuty → Configuration → Refresh PagerDuty Priorities. Once this is done, the priorities will populate into the table
x_pd_integration_pagerduty_priority, whose contents are displayed under Priorities.
Once you have imported your PagerDuty priorities, go in ServiceNow to PagerDuty → Configuration → Priorities. 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
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
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 PagerDuty → Configuration → Configuration Files → Script 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:
source(GlideRecord): the webhook import row. Note the property
source.payload, which contains a JSON string representing the payload of the webhook.
target(GlideRecord): the ServiceNow incident to be created or updated, depending on the action.
action(string): will be
insertif a new incident record in ServiceNow is being created, or
updateif an existing one is being updated.