The Custom Field Mappings feature allows you to map ServiceNow incident fields and PagerDuty Custom Fields that share the same data type. Once these fields are mapped, field values will sync bi-directionally. The PagerDuty incident and ServiceNow incident must be linked for those fields to sync.

Custom Fields created within ServiceNow will count towards your account's Custom Field limits. For more information, please see Custom Fields on Incidents.

🚧

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.

View Custom Field Mappings

Custom Field Mappings can only be viewed in ServiceNow. To view your Custom Field mappings, navigate to PagerDuty Custom Field Mappings.

When viewing Incident Types in PagerDuty, Custom Fields that have been mapped to a ServiceNow field will have ServiceNow ITSM in the Managed By column.

Create Custom Field Mappings

🚧

Restrictions

• Field mappings are one-to-one, i.e., a ServiceNow field can only be mapped to one Custom Field and a Custom Field can only be mapped to one ServiceNow field. Once a field has been mapped, it will not appear as an option when creating a new mapping.
• The PagerDuty Custom Field data type must match the data type expected by the ServiceNow field.
• You cannot map a read-only ServiceNow Incident Record Field to a PagerDuty Custom Field.
• A unique name is required for each Incident Type and Custom Field object.
• The default synchronization direction for new mappings is bidirectional, however you can optionally change it to unidirectional. See instructions below.

1. In ServiceNow, navigate to PagerDuty Field Mapping Custom Field Mappings.
2. Click New on the top right to create a new mapping.
3. Select a ServiceNow field: Select your desired ServiceNow field from the dropdown. We will only fetch ServiceNow fields that match the approved field types.
   1. If you choose to map a Choice field, you will be prompted to create a new PagerDuty Custom Field in the next step. This ensures consistent choice options across platforms.
4. In the Define Sync Direction section, select the desired synchronization option:
   1. Bidirectional (Default): Custom field values will sync bidirectionally between PagerDuty and ServiceNow.
   2. Sync from ServiceNow to PagerDuty: Custom field values will sync in one direction, from ServiceNow to PagerDuty.
   3. Sync from PagerDuty to ServiceNow: Custom field values will sync in one direction, from PagerDuty to ServiceNow.
5. Select one of the following options for PagerDuty Custom Field:

Use an existing Custom Field

• Select an existing field from the dropdown that appears. Only Custom Fields with the same data type as the ServiceNow field will appear. This option is not available when mapping a ServiceNow Choice field as a new Custom Field must be created to ensure consistent choice options across platforms.

Create a new Custom Field

• Configure the new PagerDuty Custom Field by entering the Custom Field Details:
  • Display Name: The name for the field when displayed in the PagerDuty incident UI.
  • Incident Type: The incident type that will use this Custom Field. The default selection will be Base Incident.
  • Field Name: This field automatically populates with the above display name. Refer to this field in the API by the Field Name. The field name can only contain letters, numbers, and underscores.
  • Description (optional): Short description of the information this field displays in incidents.
  • Field Type: This field automatically populates with the type that matches the chosen ServiceNow field and cannot be changed.

5. Review the mapping, then click Save. You should see a modal appear indicating the field mapping was created successfully.

Edit Custom Field Mappings

At this time, field mappings cannot be edited. Once created, custom field mappings will need to be deleted and then re-created in order to remap a field.

Delete Custom Field Mappings

You can delete the mapping between a ServiceNow field and PagerDuty Custom Field. This action does not affect any field values already set on existing incidents and this does not delete the fields. To delete a Custom Field in PagerDuty after removing a mapping, please refer to Custom Fields on Incidents for more information.

❗️

Warning

This action cannot be undone. Mappings can only be deleted from ServiceNow.

1. In ServiceNow, navigate to PagerDuty Field Mapping Custom Field Mappings.
2. Select the record you want to delete.
3. Click Delete.
4. 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 and due_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

Custom Fields Unidirectional Sync

Custom field synchronization allows administrators to control the flow of data between ServiceNow and PagerDuty. When configuring custom field mappings, administrators can select from multiple synchronization options: bidirectional custom field data flow across both platforms, or unidirectional synchronization that restricts custom field data movement to a single direction. This flexibility allows organizations to implement synchronization strategies that align with their specific workflow requirements and data governance policies.

Select the Synchronization Direction

🚧

The default synchronization direction for new mappings is bidirectional.

ServiceNow administrators can define the synchronization direction when creating a new custom field mapping in the ServiceNow integration. This allows them to control the flow of data between PagerDuty and ServiceNow:

• Bidirectional: Custom field values will sync bidirectionally between PagerDuty and ServiceNow.
• Sync from ServiceNow to PagerDuty: Custom field values will sync in one direction, from ServiceNow to PagerDuty.
• Sync from PagerDuty to ServiceNow: Custom field values will sync in one direction, from PagerDuty to ServiceNow.

Update the Custom Field Sync Direction

Currently, the integration does not support modifying the sync direction once a custom field mapping has been saved.

However, you can delete the custom field mapping, and then recreate the mapping with your preferred sync direction.

View the Custom Field Mapping Sync Direction

When configuring a custom field mapping, you can refer to the directional arrow in the Review Mapping section, which indicates how data will flow between the systems. Alternatively, you can navigate to the PagerDuty Custom Fields table and reference the Sync Direction column, which shows the sync direction for all of the custom field mappings in your ServiceNow environment.

Examples:

Supported ServiceNow Field Types & Mapping Restrictions

There are three ServiceNow field types that can unidirectionally sync to PagerDuty Custom Fields:

• Reference field type
• Read-only fields
• Choice fields with a dependent field

More information regarding the ServiceNow field types and their mapping restrictions:

Identify Read-Only Fields

When configuring a custom field mapping, the Select a ServiceNow field section clearly identifies read-only fields with the label Field type: (Read Only). After selecting a read-only field, the Define the Sync Direction section will display an information message indicating that read-only fields can only be synced one-way, from ServiceNow to PagerDuty.

Example:

Identify Choice Fields with a Dependent Field

When configuring a custom field mapping, choice fields with a dependent field are identified as follows: Field type: Choice (Dependent on ). In the Define the Sync Direction section, you will see an information message indicating that the dependent field type can only be synced unidirectionally, from ServiceNow to PagerDuty.

Post-mapping Behavior

The integration will automatically post Custom Field updates to the PagerDuty incident timeline. If you have Custom Fields updates enabled in your incident activity stream, the integration will also add these updates to the ServiceNow incident work notes.

You can edit the Custom Field Display Name and/or the Description within PagerDuty, however these changes are not immediately synced. Instead, the synchronization of Custom Field metadata—including the display name, description, and default value—is managed by the PagerDuty Custom Fields Support Script Include. This script runs automatically every hour. After the script executes, the Custom Field mapping list will reflect the new display name and/or description.

Specific actions available in ServiceNow and explanations of how they function within the integration are outlined below.

Choice Field Updates

🚧

Restriction

Choice field options can only be updated within the ServiceNow Custom Field Mappings page; these changes cannot be made within PagerDuty.

When a ServiceNow Choice field's options are changed, the integration will immediately update the mapped PagerDuty Custom Field's options. If you add, delete, or rename an option for the mapped ServiceNow Field, the integration will reflect this change in the Custom Field's options in PagerDuty.

Data Type Updates

Editing the ServiceNow field data type may cause syncing issues, since the data type sent from the PagerDuty custom field will no longer match the data type expected by the ServiceNow field.

To avoid syncing issues, we recommend following the process below:

1. Edit the ServiceNow field data type.
2. Disable the Custom Field in PagerDuty.
3. Create a new Custom Field in PagerDuty, matching the new data type.
4. Navigate to the PagerDuty Custom Field Mappings table in ServiceNow.
5. Delete the mapping associated with the previous data type.
6. Create a new mapping from the new PagerDuty Custom Field to the ServiceNow field with the updated data type.

ServiceNow Field Label Updates

The integration does not sync field label updates to the Custom Fields Mapping table in ServiceNow. However, this does not impact the integration behavior - the integration will continue to sync custom field values to that ServiceNow field despite using the original display name.

To resolve this, you can delete and re-create the field mapping.

Deleted ServiceNow Field

Deleting a ServiceNow Field will remove the field from all of your ServiceNow incident records, along with its existing field values.

The deleted field is no longer available to new ServiceNow incidents, and the PagerDuty integration will not sync Custom Field values to a deleted ServiceNow field.

Deleting the ServiceNow field does not automatically remove the Custom Field mapping. The mapping must be manually deleted from the Custom Field Mapping table within ServiceNow.

How Custom Fields Sync

Custom Fields Sync From PagerDuty to ServiceNow

Custom Fields Sync From ServiceNow to PagerDuty

Sync a Custom Field Mapping with a Default Value

ServiceNow fields can be configured with a default value within the dictionary entry. However, these default values are not automatically synced to PagerDuty. To ensure consistency, you must manually set the same default value in the corresponding PagerDuty Custom Field.

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

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

TroubleShooting Custom Fields

If the error results from an incident.custom_field_values.updated webhook sent to ServiceNow, it will appear in the incident work notes, provided that the Custom Fields errors option is enabled in your incident activity stream. This error will also reflect in the custom field mapping record within ServiceNow.

If the error stems from the PagerDuty Custom Fields Support Script Include metadata synchronization job, it will only appear in the custom field mapping record within ServiceNow and not in the incident work notes.

Examples:

FAQ

How do I create a new mapping if the “Custom Field limit in PagerDuty has been reached”?

Since you have reached the amount of custom fields available in your PagerDuty pricing plan, you will need to delete an existing PagerDuty Custom Field in order to free up a new creation. The mapping experience today provisions a new PagerDuty Custom Field based on the ServiceNow Incident record field chosen.

Can I edit/modify the PagerDuty Custom Field in ServiceNow?

To ensure configuration consistency, we are enforcing that PagerDuty Custom Fields are only editable in PagerDuty. Please see our Custom Fields article for more information on how to edit an existing PagerDuty Custom Field.

Why can’t I edit the PagerDuty Custom Fields options for the Single Select or Multiple Select data type when it’s mapped to ServiceNow?

For the Single Select and Multiple Select data type, we are enforcing that the ServiceNow Incident record field is the source of truth for the options. Option edits and deletions in ServiceNow will be immediately reflected in the PagerDuty UI. Newly-added options in ServiceNow will also sync back to PagerDuty until the maximum number of options for the PagerDuty Custom Field is reached. However, if a ServiceNow field has more options available than PagerDuty’s, options beyond that PagerDuty limit will not sync to the PagerDuty UI and the last selected option will display instead.

Can an admin disable or temporarily pause custom field syncing?

At this time, we do not have any features that would allow admins to temporarily pause custom field syncing.

Are duplicate custom field mappings allowed?

Field mappings are one-to-one. I.e., a ServiceNow field can only be mapped to one Custom Field, and a Custom Field can only be mapped to one ServiceNow field. Once a field has been mapped, it will not appear as an option when creating a new mapping.

What is the expected behavior if multiple ServiceNow tickets are linked to the incident, or vice versa?

If there are multiple ServiceNow tickets linked to one PagerDuty incident, or multiple PagerDuty incidents linked to one ServiceNow ticket, the custom field value should remain synced with the value of the more recent record.