# Advanced ServiceNow v7 Configuration

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


> **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](https://www.pagerduty.com/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**

![Inbound Field Rules](/images/kb/7fc2682f538d18f66affeba785fa21c67f18b50ba0ca78d682435b276950ad8d-inbound_field_rules.webp)
*Inbound Field Rules*

### 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](https://developer.pagerduty.com/docs/ZG9jOjQ1MjA5ODc1-overview-v2-webhooks#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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Property_accessors#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.

![Inbound Field Rule definition form](/images/kb/86d44f4f706841356de63e7a1d977fb1a52d167078b588d7b528761e3153a1f7-inbound_field_rules2.webp)
*Inbound Field Rule definition form*

### 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](https://developer.pagerduty.com/api-reference/b3A6Mjc0ODE1NA-list-log-entries) 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](https://developer.pagerduty.com/docs/webhooks/v2-overview/#webhook-types)
- `incident`: the incident object (see "Response Schema" in the [Incidents API reference](https://developer.pagerduty.com/api-reference/b3A6Mjc0ODE0MQ-get-an-incident))

### 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 [Incident Priority](/incident-management/incidents/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](#import-pagerduty-priorities), in ServiceNow navigate to **PagerDuty**  →  **Configuration**  →  **Priorities**. Here you will find a predefined list of your PagerDuty [priorities](/incident-management/incidents/incident-priority), which can then be mapped to ServiceNow urgency and impact value pairs. The computed ServiceNow priority value will also be shown in the table.

![PagerDuty priorities in ServiceNow](/images/kb/7de1ac8bf4793974b737a784ebff09fdcf5f5de97deeb67e0732423823dd55a0-define_priority.webp)
*PagerDuty priorities in ServiceNow*

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.

![Priority mapping](/images/kb/a2ef7b1fd8b23bda1dc97866dea4be573a6a40614d98c5d123f0a2d74afbe939-define_priority2.webp)
*Priority mapping*

## 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](https://developer.servicenow.com/dev.do#!/learn/courses/sandiego/app_store_learnv2_scripting_sandiego_scripting_in_servicenow/app_store_learnv2_scripting_sandiego_server_side_scripting/app_store_learnv2_scripting_sandiego_gliderecord)): the webhook import row. Note the property `source.payload`, which contains a JSON string representing the webhook's payload.
2. `target` ([GlideRecord](https://developer.servicenow.com/dev.do#!/learn/courses/sandiego/app_store_learnv2_scripting_sandiego_scripting_in_servicenow/app_store_learnv2_scripting_sandiego_server_side_scripting/app_store_learnv2_scripting_sandiego_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.