# Execution Modes

FlowDrop supports multiple execution modes (called **orchestrators**) that control how your workflow runs. Choosing the right orchestrator depends on how fast your workflow needs to complete, how many nodes it has, and whether it requires user interaction.

## Executing a Workflow

To manually execute a workflow:

1. Navigate to **Administration > FlowDrop > Execute** (`/admin/flowdrop/execute`).
2. Click **Execute Workflow**.
3. Select the workflow from the dropdown.
4. Choose an orchestrator (see below).
5. Click **Execute**.

!!! note
    You can also execute workflows automatically using [Triggers](triggers.md) — no manual action required.

## Choosing an Orchestrator

| Orchestrator | Speed | Best For | Requires Queue? |
|-------------|-------|----------|-----------------|
| **Synchronous** | Instant | Simple workflows (< 10 nodes), testing, form processing | No |
| **Synchronous Pipeline** | Instant | Same as synchronous, but with per-node tracking in the admin UI | No |
| **Asynchronous** | Background | Long-running workflows, many nodes, external API calls | **Yes** |
| **StateGraph** | Background | Loops, human-in-the-loop, chat workflows, approval gates | **Yes** |

### Synchronous

Runs all nodes in a single HTTP request. The page waits until execution finishes and then shows results immediately.

**Use when:**

- Testing a new workflow
- The workflow has a small number of nodes
- You need an immediate result (e.g., processing a form submission)

**Limitations:**

- Bound by PHP execution time limits
- The browser waits until the workflow finishes
- Not suitable for workflows that call slow external APIs

### Synchronous Pipeline

Same as synchronous, but creates a **Pipeline** entity with individual **Job** records for each node. This gives you per-node tracking and status visibility in the admin UI.

**Use when:**

- You want synchronous execution but also want to inspect per-node results afterward
- Debugging workflows to see exactly what each node produced

### Asynchronous

Queues the workflow for background processing. The page returns immediately while the workflow runs in the background via Drupal's queue system.

**Use when:**

- The workflow takes more than a few seconds to complete
- The workflow calls external APIs or services
- You are processing large amounts of data
- The workflow is triggered automatically (triggers default to async)

!!! warning "Queue Processing Required"
    Asynchronous workflows depend on Drupal's queue system. You **must** ensure queues are being processed, otherwise workflows will remain stuck in "pending" status. See [Setting Up Queue Processing](#setting-up-queue-processing) below.

### StateGraph

A stateful orchestrator that maintains execution state across steps. Supports loops, conditional routing, human-in-the-loop pauses, and checkpoint-based resumption.

**Use when:**

- The workflow contains loops (ForEach, iterator nodes)
- The workflow pauses for user input (confirmation, choice, text input nodes)
- You are building chat-based interactive workflows
- The workflow needs approval gates

!!! tip
    The [Playground](../modules/flowdrop_playground.md) always uses the StateGraph orchestrator. If your workflow works in the playground, it will work with StateGraph.

**Requires:** Enable the `flowdrop_stategraph` module:
```bash
drush en flowdrop_stategraph
```

## Setting Up Queue Processing

Asynchronous and StateGraph orchestrators require Drupal's queues to be processed. FlowDrop uses two queues:

| Queue | Purpose |
|-------|---------|
| `flowdrop_runtime_pipeline_execution` | Processes pipeline-level execution requests |
| `flowdrop_runtime_job_execution` | Processes individual node execution requests |

### Option 1: Drupal Cron (Simplest)

Drupal's built-in cron processes queues automatically. Ensure cron is configured and running at a reasonable frequency (every 1-5 minutes for responsive workflows).

Verify cron is running:
```bash
drush cron
```

### Option 2: Dedicated Queue Workers (Recommended for Production)

For faster, more reliable processing, run dedicated queue workers:

```bash
# Process pipeline execution queue
drush queue:run flowdrop_runtime_pipeline_execution

# Process job execution queue
drush queue:run flowdrop_runtime_job_execution
```

You can run these commands via a process manager (e.g., Supervisor) or as periodic cron jobs running every minute.

### Verifying Queue Status

Check if there are items waiting in the queue:

```bash
drush queue:list
```

If you see items accumulating in the FlowDrop queues but they are not being processed, verify that cron is running or start the queue workers manually.

## Monitoring Execution

After executing a workflow, you can monitor its progress:

1. Navigate to **Administration > FlowDrop > Pipelines** (`/admin/flowdrop/pipelines`).
2. Find your pipeline in the list (most recent first).
3. Click on the pipeline to see per-node job statuses.
4. Click on individual jobs to see their input/output data and any error messages.

For more details, see the [Monitoring Workflows](monitoring-workflows.md) guide.

## Next Steps

- **[Monitoring Workflows](monitoring-workflows.md)** — Track and debug workflow execution
- **[Setting Up Triggers](triggers.md)** — Automate workflow execution with event-driven triggers
- **[Troubleshooting](troubleshooting.md)** — Common issues and solutions
