> ## Documentation Index
> Fetch the complete documentation index at: https://docs.forest.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Run a workflow on data change

> Start a workflow on every record that enters a segment, and send only the exceptions to your team.

A workflow can start on its own each time a record enters a segment. Your team only steps in when a run needs a person.

For example, every document that enters the `Waiting for validation` segment starts a workflow that checks it and sets its status to `Validated`.

## How it works

The workflow uses two inboxes:

* **The automated inbox** lists every record of the segment. The workflow processes them, nobody takes them.
* **The fallback inbox** receives a task when a run needs a person: an error, a confirmation or a manual step. Operators work it like any [inbox](https://docs.forest.app/product/manage/inbox.md), and the run continues where it stopped.

A record is done when it leaves the segment. End your workflow with a step that changes what the segment filters on, for instance an **Update Data** step that sets the status to `Validated`. When a run ends and its record is still in the segment, the workflow doesn't start again on that record: fix the workflow or the data.

New records start within 5 minutes by default, up to 20 runs at a time per inbox. Your developers can change this interval in [Forest Runtime](https://docs.forest.app/product/process/workflows/forest-runtime.md#tuning).

## Before you start

To start a workflow on data change, you need:

* A segment on the workflow's collection.
* A **Fallback inbox** and the **On data change** trigger turned on, in the workflow's **Triggers** section. See [Workflow triggers](https://docs.forest.app/product/process/workflows/triggers.md#the-on-data-change-trigger).
* A service account in the inbox's team. The workflow runs with its permissions, so its role must be able to read the collections of the inbox and of the fallback inbox.
* A fallback inbox that people work from. An automated inbox can't be the fallback inbox.
* [Forest Runtime](https://docs.forest.app/product/process/workflows/forest-runtime.md) 1.34.0 or later running on your environment.

## Set it up

Only Admins and Process Owners can pick the service account in **Runs as**.

> [tab] From the workflow
>
> 1. In the workflow's **Triggers** section, under **On data change**, click **New automatic inbox**.
> 2. Pick the **Segment**, then name the inbox and pick its icon.
> 3. Pick the dispatch rule. The workflow starts the records in this order.
> 4. Pick the service account in **Runs as**.
> 5. Click **Confirm**.
>
> You can also create the inbox from the Customization Center: **Add new** → **Inbox**.

> [tab] From an existing inbox
>
> 1. Turn on **Layout Editor** mode and click the inbox in the left navbar.
> 2. In the **Process** section, set **How it starts** to **Automatically, as soon as a record enters**.
> 3. Pick the **Workflow** and the service account in **Runs as**, then click **Save**. Only workflows with the **On data change** trigger turned on are listed.

The workflow also starts on the records already in the segment. Forest shows how many before you confirm.

When you switch an existing inbox to automatic, Forest cancels the tasks operators hold in it and aborts their workflow runs. Forest asks you to confirm in a **Switch this inbox to automatic?** dialog, and the workflow then starts on those records.

## Follow the runs

The workflow's **On data change** row lists its automated inboxes, with their state and service account.

Admins open an automated inbox from the left navbar, where a bolt icon marks it. It opens on its **Backlog**:

| State | Meaning |
| - | - |
| **Doing** | The workflow is processing the record, or its run ended and the record is still in the segment. |
| **Escalated** | The run waits on a person in the fallback inbox. Click the fallback inbox name in the header to reach it. |
| **Completed** | The record left the segment. |
| **Canceled** | The run was aborted, or one of its steps was revised. |
| **Automatically Canceled** | Forest closed the task, for instance when the inbox was switched to automatic or back to manual. |

**Canceled** and **Automatically Canceled** tasks show through the Backlog filters. Click the refresh icon to update the list.

Operators can't take, assign or unassign the records of an automated inbox: the workflow holds them.

If more than 100 records are still in the segment after their run, the automation stops starting new runs until your workflow takes them out of the segment. The Backlog header then shows the automation as **Stopped**, with the reason.

## Pause or stop

To pause, open the inbox settings in **Layout Editor** mode and click **Pause** in the **Process** section. No new run starts, and the runs already going finish. Click **Resume** to start again. A pause applies to production right away.

To stop for one inbox, set **How it starts** to **Operators handle the records, no workflow** in its **Process** section and click **Save**. Operators work the inbox again. The runs already going finish, and records whose run ended while they stayed in the segment go back to operators.

To stop for every inbox, turn off **On data change** in the workflow's **Triggers** section. The inboxes stay linked to the workflow, and show as stopped.

A workflow's fallback inbox can't be deleted while the workflow has an automated trigger turned on. Turn off the triggers or pick another fallback inbox first.

## Related

> [card] [Workflow triggers](https://docs.forest.app/product/process/workflows/triggers.md)
>
> Manual, webhook, MCP and On data change.

> [card] [Inbox](https://docs.forest.app/product/manage/inbox.md)
>
> How operators process tasks in an inbox.


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