> ## 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 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 follow-ups created from your incidents. That metadata then flows everywhere follow-ups go: the web UI, Slack, workflows, ticketing exports, dashboards, the API, and webhooks.

Use custom fields on follow-ups to:

* **Categorize follow-up work** by the dimensions your organization cares about (owning business unit, product area, affected cluster, etc.)
* **Report on follow-through** — filter and group follow-ups 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 follow-ups are exported to external project management tools

<Note>
  Custom fields apply to **follow-ups** (post-incident work), not tasks. Tasks are meant to be lightweight, in-the-moment work items and do not display custom fields. If you convert a task to a follow-up, custom fields become available on it.
</Note>

<Info>
  Custom fields for action items are rolling out progressively. If you don't see the **Incident Follow Up** form under **Configuration → Forms**, reach out to your Rootly customer success manager or **[support@rootly.com](mailto:support@rootly.com)** to have it enabled.
</Info>

***

### How It Works

Follow-ups use the same custom field library as incidents. A single field definition—say, *Business Unit Owner*—can be placed on your incident forms, your follow-up form, or both, so your reporting categories stay consistent: one name, one slug, one set of options. Each follow-up 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 Incident Follow Up form** — found under **Configuration → Forms**, this form controls which custom fields appear when a follow-up is created or edited. Like other forms, it 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 Follow-Up Form

<Steps>
  <Step title="Create your custom fields">
    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.
  </Step>

  <Step title="Open the Incident Follow Up form">
    Go to **Configuration → Forms** and select **Configure** on the **Incident Follow Up** form. This form is shown whenever a follow-up is added or edited.
  </Step>

  <Step title="Add fields to the form">
    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.

    <Tip>
      To keep data consistent, we recommend keeping the Web and Slack versions of the form in sync. A field placed only on the Web form won't appear in Slack dialogs (and vice versa).
    </Tip>
  </Step>

  <Step title="Set display and requirement rules">
    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).
  </Step>
</Steps>

<Note>
  The follow-up's standard fields (title, description, assignee, priority, status, due date) are always part of the form. The fields you can **add** to it are custom fields — built-in incident fields (severity, services, etc.) belong to the incident itself.
</Note>

If you use [Dynamic Forms](/configuration/dynamic-forms), the follow-up form respects your form sets—so different incident types or conditions can present different follow-up fields.

***

### Filling In Custom Field Values

#### In the Web UI

When creating or editing a follow-up—from the **Follow-ups** tab on an incident, or from the global **Follow-ups** view under Post-Incident—the form displays every custom field placed on the Web version of the Incident Follow Up form. Values can be added at creation or filled in later by editing the follow-up.

#### In Slack

Slack follow-up dialogs—opened via `/rootly followup`, `/rootly add action item`, `/rootly action items`, or the message **More actions** menu—display the custom fields placed on the Slack version of the form. Required and conditional rules are enforced in the dialog just as on the web.

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 follow-up is created, any custom field that is both **placed on the follow-up form** (the default form set's Web or Slack version) 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 however the follow-up is created—web, Slack, API, or workflows.

<Info>
  Pre-filling is a one-time convenience, not a sync. Once the follow-up is saved, its field values are fully independent of the incident's—changing one never changes the other.
</Info>

#### Converting Between Tasks and Follow-Ups

Since custom fields only display on follow-ups, converting a follow-up to a task hides its custom field values. Rootly warns you before the conversion (in both web and Slack) and lists the fields that will be hidden. The values are **preserved, not deleted**—if you convert the item back to a follow-up, they reappear.

***

### Filtering, Columns, and Reporting

**Follow-ups list.** The global Follow-ups view supports 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.

**Dashboards.** [Dashboard](/metrics/customized-dashboards) panels built on action item data can group and filter by custom field values, letting you chart follow-up 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:

* **Triggers** — each custom field adds a `[CustomField] <Field Name> Updated` trigger, so a workflow can fire the moment a field value is set or changed on a follow-up.
* **Conditions** — workflows can branch on a follow-up'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 a follow-up'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 follow-up.

<Info>
  **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 }}`
</Info>

***

### Referencing Values in Liquid

Follow-up 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](https://docs.rootly.com/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 follow-up includes a `custom_field_selections` array with its field values. See [Event Payloads](/configuration/event-payloads) for the payload structure.

***

### FAQ

<AccordionGroup>
  <Accordion title="Can I put custom fields on tasks?" icon="list-check">
    No. Custom fields display on **follow-ups** only. Tasks are designed as lightweight in-incident work items. Converting a task to a follow-up makes custom fields available on it.
  </Accordion>

  <Accordion title="Do follow-up field values stay in sync with the incident's values?" icon="rotate">
    No. Shared fields are **pre-filled** from the incident when the follow-up is created, but after that the values are independent. This is intentional—a follow-up's business unit, for example, may legitimately differ from the incident's.
  </Accordion>

  <Accordion title="Can I use different fields on the Web and Slack forms?" icon="table-columns">
    Yes. The Incident Follow Up form has separate Web and Slack versions. That flexibility can cause confusion (a follow-up created in Slack may show different fields when edited on web), so we recommend keeping them in sync unless you have a specific reason not to.
  </Accordion>

  <Accordion title="Can I make a custom field required?" icon="asterisk">
    Yes. Each field placed on the 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.
  </Accordion>

  <Accordion title="Why don't I see custom fields on my follow-up form?" icon="circle-question">
    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 version (Web vs. Slack) of the Incident Follow Up form, and (4) any conditional display rules on the placement are met.
  </Accordion>

  <Accordion title="Can I manage the follow-up form via Terraform?" icon="code">
    API support is available today via the form field placements endpoints. Terraform provider support for placing fields on the follow-up form is rolling out—check the <a href="https://registry.terraform.io/providers/rootlyhq/rootly/latest/docs">Rootly Terraform provider docs</a> for the latest.
  </Accordion>
</AccordionGroup>