Custom fields allow you to enrich PagerDuty incidents with critical and helpful metadata throughout the incident lifecycle. Flexibly define your preferred data, and standardize what information your incidents display. This feature also allows you to aggregate data from several existing systems and populate that information during incident response.

📘

Early Access

The custom fields feature is currently in Early Access, with features and documentation subject to change.

Custom Field Components

Custom fields are comprised of two main components:

• Fields
• Schemas

Fields

Fields are the data displayed on incidents. Fields have a data type, which helps with validation and standardizing input. A field can be an integer, string, boolean (true/false), and more.

For example, if you created six fields:

• Root Cause
• Contact Info
• Customer Impacting
• Data Region
• Due Date
• Salesforce ID

The Customer Impacting field would be a boolean (true/false) field, the Due Date would be a datetime field and the rest would be string fields.

You can also set fixed options for fields, which are great for fields where responders should pick from a premade list. For example, the Data Region string field above would work well with fixed options, as there may only be 4-5 different regions available. This further helps with validation and standardizing input.

Schemas

Schemas are groups that help organize fields. Taking the six fields from the example above, you can create schemas to group them into. For example:

• Default Schema
• Ticketing Schema
• Salesforce Schema

You would use these schemas to manage which fields appear on which incidents. For example, you could have a Default Schema for fields that you want to appear on most incidents, such as the Root Cause, Contact Info and Customer Impacting fields. Meanwhile, a separate Salesforce Schema could be best for incidents only related to customers, and for these incidents you might want to include fields such as the Salesforce ID. You can create the schemas you need, group the fields into these schemas, and then assign these schemas to services.

Configure Custom Fields

In order to create custom fields and apply them to incidents, you must perform the following:

1. Create a Custom Field
2. Create a Schema
3. Add Fields to a Schema
4. Associate Schemas with Services

Create a Custom Field

🚧

Required User Permissions

Admins and Account Owners can create, edit and delete fields.

1. Navigate to Incidents Custom Fields from the top navigation bar.
2. Click New Custom Field.
3. Enter the following:
   • Display Name: The name for the field when displayed in incidents.
   • Field Name: This field will automatically populate 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: Short description of the information this field displays in incidents.
4. Next, select the Data Type.
   • You may optionally select Allow Multiple Values to allow users to choose from one or more options.
   • You may optionally select Fixed Options to require users to choose from preset options. Once selected, click Add an option and input an option you would like users to choose from. Repeat the above as needed to continue adding up to 10 options.
5. Click Create. Repeat these steps for as many fields are needed.

Edit a Field

1. Navigate to Incidents Custom Fields.
2. Click the menu to the right of the field you would like to edit and select Configure.
3. Edit your preferred details and then click Save.

Delete a Field

🚧

Requirement

You can only delete fields that do not have any associated schemas. To remove a field from a schema, please see Edit Schemas.

1. Navigate to Incidents Custom Fields.
2. Click the menu to the right of the field you would like to delete and select Delete.
3. Click Delete again to confirm.

Create a Schema

🚧

Required User Permissions

Admins and Account Owners can create, edit and delete schemas.

1. Navigate to Incidents Custom Fields from the top navigation bar.
2. Select the Schemas tab.
3. Click New Schema.
4. Enter a Schema Name and Schema Description.
5. Click Save.

Add Fields to a Schema

1. Navigate to Incidents Custom Fields from the top navigation bar.
2. Select the Schemas tab and select the schema you would like to edit.
3. From the schema page, click Add a Field.
4. Search and select an available field from the list, or create a New Custom Field.
   • If the field should be required, you may optionally select , check Required Field and then enter the field’s Default value. See our Required Fields section to learn more.
   • Repeat steps 3-4 for as many fields are needed.
5. Click Save Changes.

Edit Schemas

1. Navigate to Incidents Custom Fields Schemas tab.
2. You may edit details in the following tabs:

Fields

To add more fields:

1. From the schema page, click Add a Field.
2. Search and select an available field from the list, or create a New Custom Field.
   • If the field should be required, you may optionally select , check Required Field and then enter the field’s Default value. See our Required Fields section to learn more.
3. Click Save Changes.

To delete fields:

1. Click the menu and select Remove from Schema.
2. Click Save Changes.

Settings

Edit the Schema Name and/or Schema Description and then click Save.

Associated Services

To associate more services:

1. Click Associate Service, search and select your preferred service, click Associate and then click Confirm. Repeat this step if you would like to add more services.
2. Click Save Changes.

To remove a service association:

To remove a service association, you must associate the service with a different schema by following our instructions in Associate Schemas with Services.

Delete Schemas

🚧

Requirement

You can only delete schemas that do not have any associated services. To remove a schema association from a service, associate a different schema with the service.

1. Navigate to Incidents Custom Fields Schemas tab.
2. Click the menu to the right of the schema you would like to delete and select Delete.
3. Click Delete again to confirm.

Associate Schemas with Services

Schemas are associated with services to determine which fields should appear on that service’s incidents. For example, if you had a Salesforce Schema and only wanted those fields to appear on incidents on a Customer Support service, you would associate the schema with that service.

🚧

Required User Permissions

In order to associate a schema with a service, you must have permission to edit that service.

📘

One Schema Per Service

Only one schema can be assigned to a given service at any point in time. Assigning a different schema to a service will automatically remove a current assignment, if one is in place.

1. Navigate to Incidents Custom Fields Schemas tab and select your preferred schema.
2. Select the Associated Services tab.
3. Click Associate Service, search and select your preferred service, click Associate and then click Confirm. Repeat this step if you would like to add more services.
4. Click Save Changes.

Field Data Types

You can specify the field data type when you add a field. Data types help standardize and validate field data, preventing users from entering incorrect data types into a field. There are six field types:

🚧

Field Restrictions

• String values have a maximum of 200 characters.
• URL values have a maximum of 200 characters. Only absolute URLs are allowed, and they must use one of these schemes: http, https, tel.
• Datetime values must conform to either full-date or date-time RFC3339, section 5.6. Examples of supported values: 2022-03-14, 2019-08-28T10:43:05Z.

Required Fields

📘

Default Behavior

All fields are optional by default. It is not currently possible to set a field as required and then set it back to optional, as this may compromise data on existing incidents.

Fields can be defined as required at the schema level. This allows a field to be required in one schema but not another. When a field is defined as required, a default value must also be provided. This is used as the value when the field values are initialized (typically at the time of incident creation).

The default value must match the data type and options of the field. E.g., if a field is defined as multi-valued, then the default value must be a list of values even if that list has only a single element.

Using Custom Fields on Incidents

🚧

Required User Permissions

Users with permission to edit an incident can edit custom fields for that incident.

When a schema with fields is associated with a service, incidents on that service will show these fields. A new Custom Fields section is included on any incident with an associated schema:

Responders can click into the Custom Fields section to interact with and edit fields. Fields with default values will be prefilled, but many fields will be empty and intended for the responder to fill out during incident response.

🚧

Required Fields and Incident Resolution

If a field is set as required, responders must populate it with a valid value before resolving the incident.

FAQ

How do required fields work in schemas?

Expand

A required field is one that must have a value before an incident can be resolved. All fields are optional by default. It is not currently possible to set a field as required and then set it back to optional, as this may compromise data on existing incidents.

Can I assign multiple schemas to a service?

Expand

At this time, services can only have one schema assigned each. To have more granular control over which fields appear on a service, you can assign the same field to multiple schemas. You can mix and match fields across schemas, and you can create as many schemas as needed.

What happens to active incidents if I change fields in their schema?

Expand

When an incident’s field values are initialized, a frozen copy of the schema is created at that specific point in time. As a result, adding or removing fields to/from the schema, or even changing the schema assigned to the incident's service does not change the field values for already-initialized incidents.

Field metadata, however, is not part of this frozen copy. Most significantly, what this means is that if field options are changed or added to a field, those options are immediately available to all incidents that use that field. For example, let’s say that you have a field to store the AWS Region and initially define options for that field as US East (Virginia), US West (Oregon), and Singapore. Then later you add another option, Mumbai. Upon addition of that option, Mumbai is now a valid value for any incident that has that field. Removing a field option does not change any existing field values. E.g., in that same scenario if Singapore was removed, any incident with a field value set to Singapore would remain as-is; however any new attempt to set a field value to Singapore would fail.