Custom fields

Custom fields capture structured information about an incident beyond the standard fields incident.io provides. Use them to record things like:

• Which services or systems are affected
• Which teams are involved
• Which customers are impacted
• Whether personal data is involved
• How many customers are affected
• Links to relevant documents or resources

That information is then available throughout the incident, in Workflows and other automation, and when you filter and report on incidents later.

​

Create a custom field

1. Go to Settings → Custom fields
2. Click Add custom field
3. Give the field a short, explicit Name, and a Description explaining what it represents. The description shows as help text wherever responders see the field
4. Choose a Field type
5. For Single-select and Multi-select fields, choose where the options come from
6. Click Save

Creating a field doesn’t decide where responders see it. Use Settings → Forms to add it to your incident forms and control whether it’s optional or required. Advanced settings includes After this field has been set, don’t allow a user to unset it. Turn this on for a select field whose value shouldn’t be cleared once somebody has provided it.

​

Choose a field type

Pick the field type based on the information you want responders to provide, and how you plan to use it later. Single-select Responders choose one value from a list of options. For example, an Affected region field with the options US, EMEA, and APAC. Use Single-select when there should be one structured answer. Multi-select Responders choose one or more values from a list. For example, an Affected services field containing API, Web app, and Payments, with several services selected on the same incident. Text Responders enter free-form text. Use Text when there’s no predefined set of answers, such as an external reference or a short piece of extra context. Link Responders enter a URL. Use Link for a resource associated with the incident, such as a dashboard, document, or ticket. When filtering incidents, you can filter on whether a Link field is set or blank. Number Responders enter a number. For example, a Customers affected field. Filters on a Number field can compare values with operators like greater than, less than, or equal to.

​

Manage options for select fields

Single-select and Multi-select fields draw their options from your Catalog by default. Pick either type and we’ll ask Which catalog type will the values come from?, so all you need to do is select a type. To set the options yourself instead, click Manage options manually underneath that dropdown. That reveals How should options be managed?, where you can switch between all three approaches. From a catalog type (recommended) Keep the field backed by a Catalog type when the values already exist as objects in your Catalog, such as Services, Teams, Customers, or Regions. The field’s options come directly from the entries in that Catalog type, so you don’t maintain a second copy of the list in custom field settings. If you have a Service Catalog type containing Payments API, Checkout, and Authentication, an Affected service field backed by that type offers exactly those entries. Changes to the Catalog flow through to the field:

• Renaming an entry changes how the value appears on incidents, including historical ones
• Archiving an entry stops it being selected on new incidents, and incidents that already use it keep the value

Use Group by catalog attribute to group the options responders see by an attribute in your Catalog. Catalog-backed fields also unlock automatically setting a field from a Catalog relationship, and filtering one field’s options based on another. A fixed list Choose A fixed list when you know the possible values up front and want an Admin or Owner to control them. An Environment field with the options Production, Staging, and Development is a good fit: a stable list that doesn’t need to exist as objects in your Catalog. Set the options here or through the API. Drag them to set the order they appear in, and use Add new group to organize a long list. A list anyone can add to Choose A list anyone can add to when responders should be able to create new options mid-incident. A Customer field is a common example, where a responder needs to add a customer that hasn’t come up before. New options can be added during an incident from Slack / Microsoft Teams or the dashboard. That’s more flexible, but the set of values is less tightly controlled than a fixed list or a Catalog-backed field.

​

Filter options based on another field

A Catalog-backed field can hold a lot of entries. An Affected teams field pointing at a Team Catalog type might offer hundreds of teams, which is a long way to scroll mid-incident. If your Catalog records the Division each Team belongs to, you can narrow that list: responders pick a Division first, and Affected teams only offers the teams in it. Edit the field you want to narrow, then set Filter options based on the value of another custom field to the field it should depend on. The dropdown names the relationship it will follow, so Division (Team → Division) filters Teams by their Division attribute. Both fields need to be backed by Catalog types, and the type you’re filtering needs an attribute pointing at the other one. This pairs well with form conditions: show Affected teams only once Division is set, and responders get a short, relevant list instead of a long one. See adding custom fields to incident forms.

​

Add custom fields to incident forms

Configure where each field appears under Settings → Forms. Custom fields can be added to the Declare, Accept, Update, Resolve, Retrospective, and Custom fields forms. For each placement, choose to Show this field always or only when the incident matches conditions, and to Require this field never, always, or when the incident matches conditions. So you could:

• Always show Affected service when declaring an incident
• Only show Data classification for incidents that meet particular conditions
• Require Root cause category before an incident can be resolved
• Make the same field optional on one form and required on another

This lets you collect information at the point in the incident where it’s most useful, rather than asking for everything upfront. For everything you can configure on a form, including default values and placeholder text, see Incident forms.

​

Set a custom field automatically

Custom fields don’t always need to be filled in by hand. Set a Catalog-backed field with an expression and we’ll derive its value from something you already know about the incident, saving your responders a dropdown. Say your Catalog holds Services and the Team that owns each Service. A responder selects Payments API as the affected service, and we set Affected team to Payments for them. To set a field automatically:

1. When creating or editing a Catalog-backed field, select Set automatically, then Add an expression
2. Use the expression builder to navigate through your Catalog to the value you want, starting from another custom field on the incident
3. Choose whether users can override the calculated value

For the Services and Teams example, the expression starts from the Affected services field and follows the Catalog relationship to the owning Team. Whether users can override the value determines how strictly the relationship holds:

• Users can override: the expression acts as a sensible default. Use this where the relationship is usually right, but a responder may occasionally need something different, as with Affected team
• Users can’t override: the field is controlled entirely by the expression. Use this for values that always follow the same relationship, like deriving Affected function from Affected team. A field nobody can override doesn’t need to appear on a form at all

Automatic fields also make reporting easier. You might have hundreds of Teams but only a handful of Functions: responders pick the affected Team, a second field derives its Function, and you can report by Function without asking anyone for both. When you create an automatically set field or change its expression, we’ll ask whether you want to backfill it on existing incidents. Choose Yes to calculate the value for existing incidents as well as new ones, or No to apply the expression only going forwards. If a responder overrides the value by hand, we won’t overwrite their choice the next time the expression runs. To go back to the calculated value, reset the field on the incident.

​

Use custom fields in automation

Custom fields are available in Workflow triggers and conditions, so you can run different automation depending on what’s been captured on an incident. For example:

• Escalate to a particular team when one of their services is affected
• Notify customer support when a high-value customer is affected
• Send different comms based on the affected region
• Trigger additional processes when an incident involves sensitive data

Every field type can be referenced in Workflow conditions and message templates. To derive a value inside a Workflow, see How to use Workflow Expressions.

​

Use custom fields for reporting

Custom fields add dimensions and filters to your incident data, so you can answer questions like:

• Which services are involved in the most incidents?
• Which customers are affected most often?
• Which teams respond fastest?
• How many incidents involved personal data?
• Which incidents affected more than 100 customers?

In Insights, most panels can use custom fields as filters or split data by them. Custom fields are also available when filtering the Incidents list, and are included when you export incidents to CSV.

​

FAQs

​

Related