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

# Managing workflows

> Create, manage, and configure workflows in Ingestly.

The **Workflows** page is your starting point in Ingestly. It shows all workflows in the currently selected [workspace](/admin/workspaces), organized by workflow group. Switch workspaces using the sidebar dropdown to see workflows in a different workspace.

## Filtering the list

The **Workflows** entry in the sidebar carries saved views that filter the list for you:

| View              | Shows                                                                                  |
| ----------------- | -------------------------------------------------------------------------------------- |
| **All Workflows** | Every workflow in the workspace                                                        |
| **Active**        | Workflows currently accepting documents                                                |
| **Paused**        | Workflows that are paused                                                              |
| **Standalone**    | Workflows no other workflow can call                                                   |
| **Sections**      | [Reusable sections](/guides/reusable-sections), the workflows other workflows can call |

Each view sets the list's own filters, so you can adjust or clear them from the **Filter** control once you land there. A workflow that has both a sub-workflow trigger and a trigger of its own is a section, so it appears under **Sections** and not under **Standalone**.

## Creating a workflow

1. Click **New Workflow**
2. Enter a name for your workflow
3. Optionally add a description
4. Optionally assign the workflow to an existing workflow group
5. Click **Create Workflow**

Your new workflow opens to the detail page where you can configure it in the editor and start uploading documents.

## Workflow groups

Workflow groups help you organize related workflows. Each group has a name and a color that appears next to its workflows on the Workflows page.

### Creating a group

1. Click **New Group** on the Workflows page
2. Enter a name
3. Pick a color
4. Click **Create Group**

### Organizing workflows

* **Move a workflow:** open the workflow's context menu and choose **Move to group**, then pick the destination group
* **Reorder groups:** drag a group header to change its position on the page
* **Edit or delete:** open the group menu to rename it, change its color, or delete it. Deleting a group leaves its workflows in place; they move back to the ungrouped section

Workflow groups are scoped to the current workspace. Switching workspaces shows a different set of groups.

## Duplicating a workflow

Use **Duplicate** from a workflow's context menu to create a copy with the same configuration. The new workflow starts **deactivated** so you can adjust it before it accepts live documents. If the source workflow belongs to a group, the duplicate joins the same group.

## Workflow detail page

Click any workflow to open its detail page. The main content area shows the **documents list**, all documents uploaded to this workflow with their processing status.

The documents table includes the following columns:

| Column            | Description                            |
| ----------------- | -------------------------------------- |
| **Document Name** | Original name of the uploaded document |
| **Size**          | Document size                          |
| **Pages**         | Number of pages in the document        |
| **Status**        | Current processing status              |
| **Created**       | Upload timestamp                       |

Above the documents table you'll find **Sort** and **Filter** controls and a **⋯** menu with **Refresh**, which reloads the list on demand, and **Columns**, which shows or hides columns.

### Action buttons

The [workflow editor](/workflows/editor) header carries the workflow-level actions on every tab: **Upload** opens the upload dialog to add documents to this workflow (unavailable while the workflow is paused, with the reason shown), and **Activate** (**Deactivate** once it is running) starts or stops processing. The rest sit in the **More actions** overflow menu:

* **Workflow versions**: browse and restore the workflow's saved versions
* **Workflow settings**: edit the description, retention, reference strictness, and group
* **Enable self-learning**: turn [self-learning](/workflows/self-learning) on for this workflow and open its **Learning** tab. Shown while learning is off, for organizations that have self-learning
* **Save as Template**: save the current configuration as a reusable template
* **Export to file**: download the workflow as a JSON file
* **Import from file**: replace the current draft from an exported file
* **Copy to Production** or **Copy to Development**: copy the saved workflow to the other [environment](/workflows/stages)
* **Validate workflow**: check the configuration and list any errors

## Self-learning

Self-learning is an opt-in, per-workflow feature that turns approved reviews of Extract nodes into examples for later extractions. It is granted per organization rather than by plan. See [Self-learning](/workflows/self-learning) for how it works, the **Learning** tab, and the settings.

## Error handler

An error handler is another workflow that Ingestly runs when a run of this workflow fails. Use it to post the failure to an external system with an [HTTP action](/nodes/http-action), notify a channel, or route the document into a fallback workflow.

An error handler fires once per failed run. This is what separates it from [alert rules](/admin/alert-rules), which watch failure rates across a workflow over a rolling window and notify you by email or in-app. Use an alert rule to learn that failures are spiking. Use an error handler to act on a single failure.

### Choosing a handler

Open the [workflow editor](/workflows/editor)'s **More actions** menu, choose **Workflow settings**, then pick a workflow under **Error Handler**. Clear the field to remove the handler.

The workflow you pick must:

* Start with a [Forward trigger](/nodes/forward-trigger) that accepts a data contract
* Be in the same environment as the workflow it handles
* Accept a contract whose required fields the failure context below supplies
* Not be the workflow itself, and not lead back to it through another workflow's error handler

The picker lists paused workflows with a **(Paused)** label. You can select one, but a paused handler is skipped when a failure actually happens.

<Note>
  Duplicating a workflow, or copying it to another environment, does not carry the error handler over. Set it again on the copy.
</Note>

### Failure context

The handler receives a fixed set of fields. You cannot add to it or map it: write the handler's contract against these names.

| Field           | Type   | Description                             |
| --------------- | ------ | --------------------------------------- |
| `workflowId`    | string | The workflow whose run failed           |
| `workflowName`  | string | Its name                                |
| `runId`         | string | The failed run                          |
| `documentId`    | string | The document that was being processed   |
| `documentName`  | string | Its original file name                  |
| `error`         | string | The failure message                     |
| `failedNodeIds` | array  | The nodes that failed in that run       |
| `environment`   | string | The environment the run belonged to     |
| `failedAt`      | string | When the run failed, as a UTC timestamp |

The handler also receives the original document, so it can parse it, attach it, or forward it on.

A handler run is an ordinary run. It appears in the handler workflow's run history and consumes credits like any other.

### When it does not fire

* The failure was handled inside the workflow. A node whose failure edge is connected does not fail the run
* The run was a test run or a dry run
* The run was a child of another run. Child runs settle through their parent, which fires the handler once
* The failed run was itself an error-handler run. A handler that fails does not call its own handler, so a broken handler cannot loop
* The handler is paused, sits in a different environment, or no longer starts with a valid trigger

## Debug badge

A workflow with at least one [breakpoint](/workflows/editor#breakpoints) set shows a **Debug** badge on its detail page header and next to its name in the workflows table, so anyone browsing the list can see that its runs are parking at breakpoints. Copying a workflow to another [environment](/workflows/stages) or duplicating it never carries its breakpoints to the new workflow: the copy always starts with no breakpoints set, regardless of the source workflow.

## Workflow actions

From the workflows list or detail page, you can:

* **Activate:** enable the workflow to accept documents and run
* **Pause:** pause the workflow without deleting it. Paused workflows do not accept new documents or trigger runs
* **Delete:** permanently remove the workflow and all its data