> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rootly.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Custom Fields on Action Items
> Add custom fields to tasks and follow-ups to capture organization-specific metadata, drive reporting, power workflow automation, and enrich ticketing exports.
## Overview
Custom fields let you attach organization-specific metadata—like product area, business unit, cluster, or infrastructure provider—to the tasks and follow-ups created from your incidents. That metadata then flows everywhere action items go: the web UI, Slack, workflows, ticketing exports, dashboards, the API, and webhooks.
Use custom fields on action items to:
* **Categorize action item work** by the dimensions your organization cares about (owning business unit, product area, affected cluster, etc.)
* **Report on follow-through** — filter and group action items by field values in lists and dashboards
* **Automate with workflows** — trigger on field changes, branch on field values, and write values into Jira, Linear, GitHub, and other ticketing tools
* **Keep exports complete** — include required metadata when action items are exported to external project management tools
Custom fields apply to both kinds of action item: **tasks** (lightweight, in-incident work) and **follow-ups** (post-incident work). Each kind has its own form, so you can surface different fields on tasks than on follow-ups. Only custom fields can be added to these forms—an action item's standard fields (title, description, assignee, priority, status, due date) are always present.
Custom fields for action items are rolling out progressively. If you don't see the **Incident Follow Up** or **Incident Task** forms under **Configuration → Forms**, reach out to your Rootly customer success manager or **[support@rootly.com](mailto:support@rootly.com)** to have it enabled.
***
## How It Works
Action items use the same custom field library as incidents. A single field definition—say, *Business Unit Owner*—can be placed on your incident forms, your action item forms, or both, so your reporting categories stay consistent: one name, one slug, one set of options. Each action item stores its **own value** for the field—seeded from the parent incident at creation where fields are shared, but fully independent after that (see [Pre-Filled from the Parent Incident](#pre-filled-from-the-parent-incident)).
There are three moving parts:
1. **Fields** — created and managed under **Configuration → Fields**, exactly like [custom incident fields](/configuration/custom-fields). All custom field types are supported: text, textarea, rich text, number, checkbox, date, datetime, select, and multiple select—including select fields backed by Teams, Users, Services, Functionalities, Environments, Causes, Incident Types, or [Catalogs](/catalogs).
2. **The action item forms** — the **Incident Follow Up** and **Incident Task** forms, both under **Configuration → Forms**, control which custom fields appear on follow-ups and tasks respectively. Each has separate **Web** and **Slack** versions you can configure independently.
3. **Values** — set by responders in the web UI or Slack, pre-filled from the parent incident where fields are shared, or written automatically by workflows and the API.
***
## Configuring the Task and Follow-Up Forms
Go to **Configuration → Fields** and create the fields you need, or reuse fields that already exist for your incidents. See [Custom Fields](/configuration/custom-fields) for field types, options, and best practices.
Go to **Configuration → Forms** and select **Configure** on the **Incident Follow Up** form (shown whenever a follow-up is added or edited) or the **Incident Task** form (shown whenever a task is added or edited).
Click **Add Fields** and select the custom fields to display. Drag and drop to reorder them. Use the tabs to configure the **Web** and **Slack** versions of the form separately.
To keep data consistent, Rootly recommends keeping the Web and Slack versions of a form in sync. A field placed only on the Web form won't appear in Slack dialogs (and vice versa).
Edit each field on the form to control whether it is **required**, and whether it is displayed or required **conditionally** based on the value of another field above it—the same conditional logic available on [built-in forms](/configuration/built-in-forms).
The **Incident Task** and **Incident Follow Up** forms are independent, and the Task form starts **empty**—placing a field on the follow-up form does not add it to tasks (or vice versa). Add fields to each form explicitly. Only custom fields can be placed on these forms; an action item's standard fields (title, description, assignee, priority, status, due date) are always present, and built-in incident fields (severity, services, etc.) belong to the incident itself.
If you use [Dynamic Forms](/configuration/dynamic-forms), the action item forms respect your form sets, so different incident types or conditions can present different fields.
***
## Filling In Custom Field Values
## In the Web UI
When creating or editing an action item on an incident, the form displays every custom field placed on the Web version of the matching form (**Incident Task** or **Incident Follow Up**). Values can be added at creation or filled in later by editing the action item. The global **Follow-ups** view under Post-Incident also exposes follow-up custom fields.
## In Slack
Slack action item dialogs display the custom fields placed on the Slack version of the matching form. Required and conditional rules are enforced in the dialog just as on the web.
* **Tasks** — created with `/rootly task` (or `/rootly add action item`); view and manage yours with `/rootly todo` or `/rootly tasks`.
* **Follow-ups** — created with `/rootly followup` (or `/rootly add action item`); manage via `/rootly action items` or the message **More actions** menu.
Follow-ups created instantly from emoji reactions skip the dialog, so their custom fields start empty—fill them in afterward by editing the follow-up from `/rootly action items` or the web UI. Fields shared with the incident are still pre-filled automatically (see below).
Slack notifications sent when a follow-up is assigned also display its custom field values (up to 10 fields) beneath the summary, so assignees get full context without leaving Slack.
## Pre-Filled from the Parent Incident
When a new action item is created, any custom field that is both **placed on the matching action item form** and **already set on the parent incident** is pre-filled with the incident's value. You can edit or clear the pre-filled value before saving. Pre-filling applies to both tasks and follow-ups, however the action item is created—web, Slack, API, or workflows.
Pre-filling is a one-time convenience, not a sync. Once the action item is saved, its field values are fully independent of the incident's—changing one never changes the other.
## Converting Between Tasks and Follow-Ups
Tasks and follow-ups can carry different custom fields, since each has its own form. When you convert an action item from one kind to the other, any field that is on the **source** form but **not** on the **destination** form is hidden—its value is **preserved, not deleted**, and reappears if you convert back. Fields present on both forms stay visible and keep their values. Rootly warns you before converting (in both web and Slack) and lists the fields that will be hidden, but only when the conversion would actually hide something.
***
## Filtering, Columns, and Reporting
**Follow-ups list.** The global Follow-ups view supports follow-up custom fields as table columns and filters:
* Use **Configure View** to add custom field columns to the table. Fields with **Display this field in the incident details** turned off are hidden from the column picker.
* Filter follow-ups by custom field values—including select, user, team, service, functionality, and catalog-backed fields.
* Custom field values are searchable, so follow-ups can be found by the values set on them.
This view lists follow-ups only; task custom fields don't appear here. Use Dashboards for reporting across tasks.
**Dashboards.** [Dashboard](/metrics/customized-dashboards) panels built on action item data can group and filter by custom field values from **both** the task and follow-up forms, letting you chart action item volume and completion by product area, business unit, or any other dimension you track.
***
## Automating with Workflows
[Action item workflows](/workflows/action-item-workflows) get full custom field support for both tasks and follow-ups:
* **Triggers** — each custom field adds a `[CustomField] Updated` trigger, so a workflow can fire the moment a field value is set or changed on an action item.
* **Conditions** — workflows can branch on an action item's custom field values (is, is not, is one of, is set, is unset, plus contains any / all / none of for multi-value fields).
* **Actions** — the **Update Action Item** action can set custom field values, including with Liquid templating (for example, populating a field from `{{ incident.severity }}`).
* **Ticketing exports** — ticketing actions (Jira, Linear, GitHub, Asana, and more) support custom field mappings, so you can write an action item's field values into the external ticket using [Liquid variables](/liquid/action-item-variables).
Example: keep a Jira ticket's *Business Unit* field in sync with the action item.
**Trigger**
* `[CustomField] Business Unit Owner Updated`
**Action**
* **Update Jira Issue**, with a custom field mapping that sets the Jira field to
`{{ action_item.custom_fields_by_slug.business-unit-owner }}`
***
## Referencing Values in Liquid
Action item custom field values are available in Liquid wherever action item variables are supported:
```liquid theme={null}
# Simplest access — by field slug (multi-value fields return an array)
{{ action_item.custom_fields_by_slug.your-field-slug }}
{{ action_item.custom_fields_by_slug.your-multi-select-slug | join: ', ' }}
```
See [Action Item Variables](/liquid/action-item-variables#custom-fields) for the full structure, including the `action_item.custom_fields` array for advanced use.
***
## API and Webhooks
The [incident action items API](/api-reference/incidentactionitems/creates-an-incident-action-item) accepts custom field values through the `form_field_selections` attribute and returns them as `custom_field_selections`:
* **Create/update** — pass a `form_field_selections` array under `data.attributes`, with each entry containing a `form_field_id` and either a `value` (text-like fields) or the relevant `selected_*_ids` (option, user, group, service, functionality, catalog entity, environment, cause, or incident type fields).
* **Read** — responses include the `custom_field_selections` relationship; use `?include=custom_field_selections` to embed full values.
* **Webhooks** — incident [webhook](/configuration/webhooks) event payloads (such as `incident.updated`) embed the incident's action items in an `action_items` array; each embedded action item includes a `custom_field_selections` array with its field values. See [Event Payloads](/configuration/event-payloads) for the payload structure.
***
## FAQ
Yes. Custom fields apply to both tasks and follow-ups. Place the fields you want on tasks on the **Incident Task** form under **Configuration → Forms**—it's separate from the Incident Follow Up form and starts empty, so add fields to it explicitly.
No. Shared fields are **pre-filled** from the incident when the action item is created, but after that the values are independent. This is intentional—an action item's business unit, for example, may legitimately differ from the incident's.
Yes. Each action item form (Incident Follow Up and Incident Task) has separate Web and Slack versions. That flexibility can cause confusion (an item created in Slack may show different fields when edited on web), so Rootly recommends keeping them in sync unless you have a specific reason not to.
Yes. Each field placed on a form can be required always or conditionally, based on the values of fields above it. Required rules are enforced in both the web form and Slack dialogs.
Check that: (1) the feature is enabled for your organization, (2) the fields are **enabled** under Configuration → Fields, (3) the fields are placed on the correct form (Incident Task vs. Incident Follow Up) and the correct version (Web vs. Slack), and (4) any conditional display rules on the placement are met.
API support is available today via the form field placements endpoints. Terraform provider support for placing fields on the action item forms is rolling out—check the Rootly Terraform provider docs for the latest.