# Human-in-the-Loop Workflows

FlowDrop can pause a running workflow to ask a user for input — a confirmation, a choice, free-form text, or a structured form. This is called **Human-in-the-Loop** (HITL) and is useful for approval workflows, interactive data collection, and any process that needs human judgment.

!!! note "Modules Required"
    Enable the following modules:
    ```bash
    drush en flowdrop_interrupt flowdrop_stategraph
    ```
    For the interactive testing interface, also enable:
    ```bash
    drush en flowdrop_playground
    ```

## How It Works

1. The workflow reaches an **interrupt node** (e.g., ConfirmationNode).
2. The pipeline **pauses** and creates an interrupt request.
3. The user **responds** to the interrupt (via the Playground UI or API).
4. The pipeline **resumes** from where it left off, using the user's response as input.

!!! important
    Human-in-the-loop workflows require the **StateGraph** orchestrator, which supports pausing and resuming. The standard synchronous orchestrator cannot pause.

## Interrupt Node Types

| Node | What It Does | User Sees |
|------|-------------|-----------|
| **ConfirmationNode** | Asks a yes/no question | A confirmation prompt with Yes/No buttons |
| **ChoiceNode** | Presents a list of options | A list of choices (single or multi-select) |
| **TextInputNode** | Requests free-form text | A text input field |
| **FormInputNode** | Requests structured data | A form generated from a JSON Schema definition |

## Step-by-Step: Build an Approval Workflow

This example builds a workflow that asks for confirmation before logging a message.

### Step 1: Create the Workflow

1. Navigate to **Administration > FlowDrop > Workflows** and create a new workflow.
2. Open it in the visual editor.

### Step 2: Add the Nodes

Add three nodes to the canvas:

1. **Text Input** — The data to be approved.
2. **ConfirmationNode** — Found in the **Human-in-the-Loop** category. This will pause the workflow and ask the user to confirm.
3. **Logger** — To log the result after approval.

### Step 3: Configure the Confirmation Node

1. Click on the ConfirmationNode to open its configuration panel.
2. Set the **prompt** — the question the user will see (e.g., "Do you want to proceed with logging this message?").

### Step 4: Connect the Nodes

1. Connect **Text Input** output → **ConfirmationNode** input.
2. Connect **ConfirmationNode** output → **Logger** input.

### Step 5: Save the Workflow

Click **Save** in the editor toolbar.

### Step 6: Test in the Playground

The Playground is the easiest way to test interrupt workflows interactively.

1. From the workflow listing, click the dropdown and select **Playground**.
2. Send a message to start the workflow.
3. When the workflow reaches the ConfirmationNode, the Playground shows the confirmation prompt inline.
4. Click **Yes** or **No** to respond.
5. The workflow resumes and completes.

!!! tip "Playground Access"
    The Playground requires the `flowdrop_playground` module and the `execute playground workflow` permission.

## Using the Playground

The Playground provides a chat-like interface for testing workflows:

### Starting a Session

1. Navigate to **Administration > FlowDrop > Workflows**.
2. Click the dropdown on a workflow and select **Playground**.
3. Send a message to start the workflow execution.

### Responding to Interrupts

When the workflow pauses for user input, the Playground renders the appropriate UI inline:

- **Confirmation** — Yes/No buttons
- **Choice** — A list of selectable options
- **Text Input** — A text field with a submit button
- **Form Input** — A generated form with fields based on the JSON Schema

Click or fill in your response and submit. The workflow will resume.

### Managing Sessions

- Each Playground interaction is a **session** with its own message history.
- Create multiple sessions to test different scenarios.
- Reset a session to start over.
- Delete old sessions to clean up.

## Permissions

| Permission | What It Allows |
|------------|---------------|
| `resolve own flowdrop interrupts` | Respond to own interrupt requests |
| `resolve any flowdrop interrupts` | Respond to any interrupt request |
| `view own flowdrop interrupts` | View own pending interrupts |
| `view any flowdrop interrupts` | View any pending interrupt |
| `cancel own flowdrop interrupts` | Cancel own pending interrupts |
| `cancel any flowdrop interrupts` | Cancel any pending interrupt |
| `execute playground workflow` | Use the Playground interface |

For a complete permissions reference, see the [Permissions](permissions.md) page.

## Tips

- **Use the StateGraph orchestrator** — HITL workflows require it. The Playground uses StateGraph automatically.
- **Keep prompts clear** — Write confirmation prompts that clearly explain what will happen on Yes vs No.
- **Test in Playground first** — Before connecting triggers, validate your interrupt flow in the Playground.
- **Approval Gates** — For multi-step approval processes, use the **ApprovalGateNode** from the `flowdrop_stategraph` module. It works like a confirmation but is designed for formal approval workflows.

## Next Steps

- **[Execution Modes](execution-modes.md)** — Understand the StateGraph orchestrator
- **[Setting Up Triggers](triggers.md)** — Automate workflows that include HITL pauses
- **[Monitoring Workflows](monitoring-workflows.md)** — Track paused and interrupted pipelines
