> ## 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.

# Creating Action Items via Automation & API

> Automate action item creation through workflows, incident roles, and direct API integration for scalable incident response processes.

## How Automation Creates Action Items

Action items—tasks and follow-ups—can be generated automatically through **Workflows**, **Incident Roles**, or the **Rootly API**. Automation ensures teams never miss a critical task, follow-up, or improvement opportunity during or after an incident.

Automation is especially powerful for:

* Enforcing consistent response processes
* Creating tasks or follow-ups automatically based on incident conditions
* Routing work to the correct owners
* Producing reliable audit trails
* Integrating with tools such as Jira, GitHub, and Slack

<Info>
  Automation reduces operational overhead and ensures every incident produces actionable, trackable work.
</Info>

***

## Action Items and Workflows

Workflows can both **create** and **react to** action items using a variety of triggers and conditions.

### Supported Workflow Triggers (Action Item Category)

Rootly supports the following action-item–related triggers:

* `incident_updated`
* `action_item_created`
* `action_item_updated`
* `assigned_user_updated`
* `summary_updated`
* `description_updated`
* `status_updated`
* `priority_updated`
* `due_date_updated`
* `teams_updated`
* `slack_command`

### Workflow Conditions

Workflows can filter based on:

* Action item type (Task / Follow-up)
* Status
* Priority
* Incident severity
* Visibility
* Incident kind
* Incident roles
* Other incident attributes (teams, services, etc.)

<Info>
  Conditions and triggers map directly to code-backed enums and workflow schemas, ensuring strict validation and predictable automation.
</Info>

***

### Example: Workflow **creates** a task when the Security team is added

<Info>
  **Trigger**

  * Teams added

  **Conditions**

  * Kind → Incident
  * Team → is one of → Security

  **Action**

  * Create a task to alert the Legal team
</Info>

***

### Example: Workflow **reacts to** a new action item

<Info>
  **Trigger**

  * Action item created

  **Conditions**

  * Type → Task
  * Priority → High

  **Action**

  * Create an external ticket (for example, Jira, GitHub, GitLab, Linear)
</Info>

<Info>
  Workflow tasks are grouped by integration. Jira actions, for example, appear under the Jira task group and require the Jira integration to be enabled.
</Info>

***

## Action Items and Incident Roles

Incident Roles can include predefined tasks that are automatically converted into incident action items when an incident is created.

These role-based tasks carry:

* Summary
* Priority
* Role assignment metadata
* Ordering/position

To configure:

<Steps>
  <Step title="Open Roles">
    Go to **Configuration → Roles**.
  </Step>

  <Step title="Select a Role">
    Select the role you want to add tasks to.
  </Step>

  <Step title="Open the Tasks Tab">
    Open the **Tasks** tab.
  </Step>

  <Step title="Add or Reorder Tasks">
    Add or reorder tasks as needed.
  </Step>
</Steps>

<Info>
  Role-based action items give each incident a predictable starting checklist and ensure operational discipline.
</Info>

Learn more about [Incident Roles](/configuration/incident-roles).

***

## Action Items and the API

The Rootly API allows programmatic creation, management, and retrieval of action items.

### Endpoints

* **List incident action items**\
  [/api-reference/incidentactionitems/list-incident-action-items](/api-reference/incidentactionitems/list-incident-action-items)

* **Create an incident action item**\
  [/api-reference/incidentactionitems/creates-an-incident-action-item](/api-reference/incidentactionitems/creates-an-incident-action-item)

* **Retrieve an incident action item**\
  [/api-reference/incidentactionitems/retrieves-an-incident-action-item](/api-reference/incidentactionitems/retrieves-an-incident-action-item)

* **Update an incident action item**\
  [/api-reference/incidentactionitems/update-an-incident-action-item](/api-reference/incidentactionitems/update-an-incident-action-item)

* **Delete an incident action item**\
  [/api-reference/incidentactionitems/delete-an-incident-action-item](/api-reference/incidentactionitems/delete-an-incident-action-item)

* **List all action items for an organization**\
  [/api-reference/incidentactionitems/list-all-action-items-for-an-organization](/api-reference/incidentactionitems/list-all-action-items-for-an-organization)

## Supported API Fields (Create/Update)

* `kind` (`task` or `follow_up`)
* `summary` (required)
* `description` (Markdown supported)
* `assigned_to_user_id`
* `assigned_to_group_ids`
* `priority` (`high`, `medium`, `low`)
* `status` (`open`, `in_progress`, `done`, `cancelled`)
* `due_date` (ISO 8601)
* `form_field_selections` ([custom field](/incidents/action-items/action-item-custom-fields) values — each entry takes a `form_field_id` plus a `value` or the relevant `selected_*_ids`)
* **Jira fields:**
  * `jira_issue_id`
  * `jira_issue_key`
  * `jira_issue_url`

## Response Fields Include

* Kind, priority, status
* Due date
* Assigned user & groups
* Custom field values via the `custom_field_selections` relationship (use `?include=custom_field_selections` to embed them)
* Integration URLs:
  * `jira_issue_url`
  * `github_issue_url`
  * `gitlab_issue_url`
  * `linear_issue_url`
* `url` and `short_url`
* Timestamps and metadata

<Info>
  The API follows the JSON:API spec and enforces the same validations as the Web UI and Slack.
</Info>

***

## Best Practices

* **Automate common tasks** to reduce manual work
* **Use role-based tasks** for consistent incident startup actions
* **Assign owners early** to prevent drift
* **Use priorities intentionally** to structure follow-up workflows
* **Integrate external systems** (Jira, GitHub, etc.) for centralized tracking
* **Review overdue follow-ups regularly** for reliability improvements

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="A workflow didn’t create an action item" icon="bolt">
    Confirm the trigger conditions matched the incident and that the user/action had permission to create action items.
  </Accordion>

  <Accordion title="A role task did not appear during incident creation" icon="user-tag">
    Ensure the role is enabled and the role tasks themselves are active. Disabled tasks are not copied over.
  </Accordion>

  <Accordion title="The API returned a validation error" icon="triangle-exclamation">
    Make sure `summary` is present and enum fields (priority, status, kind) match allowed values. Check Jira fields if provided.
  </Accordion>

  <Accordion title="A follow-up could not be created" icon="plus">
    Some organizations disable task/follow-up creation after an incident is resolved, cancelled, or closed.
  </Accordion>

  <Accordion title="API-created items aren’t appearing in Slack" icon="hashtag">
    Slack notifications fire only when:

    * The team has a Slack integration
    * The incident has a `slack_summary_timestamp`
    * Notifications aren’t suppressed

    These notifications are not workflow-dependent.
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.