# FlowDrop Workflow Executor

> Execute workflows from within other workflows, enabling composition and reuse of workflow definitions.

## Overview

The `flowdrop_workflow_executor` module enables workflow composition — a node in one workflow can execute an entirely separate workflow and use its results. This supports both synchronous execution (wait for the sub-workflow to complete) and asynchronous execution (fire and forget or poll for results later).

Since 1.4.0 the recommended entry point is **`WorkflowNode`**, which is the FlowDropNodeProcessor plugin that exposes every published workflow as a callable building block in another workflow. The legacy `WorkflowExecutor` / `WorkflowResultsRetriever` pair is still shipped for backward compatibility.

## Dependencies

- [flowdrop](flowdrop.md)
- [flowdrop_workflow](flowdrop_workflow.md) (workflow definitions)
- [flowdrop_session](flowdrop_session.md) (session context for sub-workflows)

## Tips and Tricks

### Synchronous vs Asynchronous Sub-Workflows

- **Synchronous** — The parent workflow waits for the sub-workflow to complete before continuing. Use for short sub-workflows where you need the results immediately.
- **Asynchronous** — The parent workflow continues immediately. Use the `WorkflowResultsRetriever` node later to fetch results.

### Workflow Composition Patterns

- **Reusable building blocks** — Extract common logic (e.g., data enrichment, notification sending) into separate workflows and call them from multiple parent workflows.
- **Modular design** — Break complex workflows into smaller, testable sub-workflows that can be developed and tested independently in the [playground](flowdrop_playground.md).

### `WorkflowNode` and `flowdrop_workflow` derivatives (1.4.0+)

`WorkflowNode` is a single FlowDropNodeProcessor plugin with a derivative per published workflow — `flowdrop_workflow:<workflow_id>`. Each derivative behaves like a regular node with **typed input and output ports** drawn from the called workflow's schema snapshot (see [flowdrop_workflow](flowdrop_workflow.md)), so the parent editor renders it the same as any other processor.

Key semantics:

- **Parent session reuse** — the sub-workflow runs against the parent's session, so chat history, log messages, and the playground UI all see a single end-to-end conversation. Messages emitted from inside a sub-workflow carry the originating `workflow_id` in their metadata so the playground can attribute them.
- **Cancel cascade** — when the parent pipeline is cancelled or paused, `WorkflowNode` implements `CancellableNodeProcessorInterface` and drives the cascade scoped to the sub-pipeline id, so signals don't leak into sibling sub-workflows.
- **HITL resume** — when a HITL interrupt is raised inside a sub-workflow, `WorkflowNode` implements `ResumableNodeProcessorInterface` and continues the parent once the interrupt resolves. Failures and pauses surface on the parent rather than completing silently.
- **Async completion** — for fire-and-forget mode, completion is observed through a **linked interrupt** + `PipelineCompletionSentinelMessage`; the parent's `WorkflowNode` resumes when the sentinel is matched on the sub-pipeline id by `PipelineCompletionSubscriber`.

## Developer API

### Services

| Service ID | Class | Description |
|-----------|-------|-------------|
| `flowdrop_workflow_executor.service` | `WorkflowExecutionService` | Programmatic interface for executing workflows as sub-workflows |

### Node Processors

| Plugin | Description |
|--------|-------------|
| `flowdrop_workflow:<workflow_id>` (`WorkflowNode`) | Runs a published workflow as a sub-workflow with typed input/output ports. One derivative per published workflow. Recommended since 1.4.0. |
| `WorkflowExecutor` | Legacy: executes a referenced workflow with configurable execution mode (sync/async). |
| `WorkflowResultsRetriever` | Legacy: retrieves results from a previously executed sub-workflow. |

## References

- [flowdrop_workflow](flowdrop_workflow.md) — workflow definitions
- [flowdrop_session](flowdrop_session.md) — session context
- [flowdrop_runtime](flowdrop_runtime.md) — execution engine
