Building Reusable Windmill Flows: Inputs, Step Piping, and Return Values

Windmill models automation as composition: small, typed scripts are arranged into flows that execute as a single job. Flows are represented as directed acyclic graphs in which each step can be a script from the workspace or the Windmill Hub, inline code, a loop, or a branch. Building a first flow raises three concrete questions: what the flow accepts as input, how each step consumes the results of earlier steps, and what the flow returns when it finishes. Windmill's answers are a piped input model, expression-based bindings between steps, and a return rule defined by the last executed step. This guide covers those mechanics in the visual flow editor, the incremental testing workflow that supports them, and the code-first alternative that defines jobs and their dependencies in Python or TypeScript.

Flows as DAGs: The Data Model to Think In

Flows as DAGs: The Data Model to Think In

In Windmill a flow is a state machine expressed as a directed acyclic graph (DAG) that stitches scripts together into a single job — the foundation for all reusable automations and apps【2†url】. When you create a new flow the editor shows only two blocks: an Input step that declares the flow’s parameters and a Result step that collects the final output. You add intermediate steps with the + button, arranging them in any order that respects the DAG’s no‑cycle rule.

Script varieties

A step can host one of five script kinds, each selectable from the workspace, the public Windmill Hub, or written inline in the flow editor【0†url】:

Kind	Default role
Action	Standard executable script (default)
Trigger	Starts the flow based on external events
Approval	Pauses execution until a user approves
Error handler	Runs when a previous step fails
Preprocessor	Pre‑runs transformation before the main logic

Choosing a saved workspace or Hub script is encouraged when the step is likely to be reused, because it decouples the logic from the flow definition and enables versioning across projects.

Data movement

By default Windmill pipes results between steps: the JSON output of a step becomes a named variable that later steps can reference (e.g., step_3.result). The Result block automatically receives the output of the last executed step, making it straightforward to feed the flow’s output to another flow or an app UI【2†url】. This model works well for lightweight automation where payloads remain modest.

When dealing with large or non‑JSON data—common in heavy ETL pipelines—piping can become inefficient. Windmill therefore offers a shared directory (./shared) that steps can read from or write to, bypassing the result‑piping mechanism. Using the shared folder is recommended only for sizable payloads; otherwise keep steps small, reuse saved scripts, and let the DAG’s native piping handle data flow.

Design guidance

• Keep steps focused – each step should perform a single, well‑named operation.
• Prefer saved scripts – scripts stored in the workspace or Hub are instantly reusable in other flows.
• Reserve ./shared – use it only for large binary blobs or massive tabular data that would strain JSON piping.

Understanding this DAG‑centric data model is the first step toward building composable, maintainable Windmill automations.

Exposing Inputs: Turning a Flow into a Generic Component

Exposing Inputs: Turning a Flow into a Generic Component

Flows become reusable components when they expose their variable parts as flow inputs. The first step in productionising a flow is to define those inputs explicitly, rather than hard‑coding values inside script steps.

1. Add an input step – In the left‑hand panel of the flow editor, click the Input node and press Add variable. Typical examples are a spreadsheet_id and a worksheet_name for a gsheets/getValues flow.
2. Choose the correct type – New variables default to string. Using the right‑hand properties panel you can switch the schema to object, number, or other JSON‑schema types, matching the downstream script’s expectations.
3. Provide defaults – Supplying default values (e.g., a known spreadsheet ID) speeds up ad‑hoc testing and pre‑populates the auto‑generated UI that end users see when they run the flow [Windmill Docs – Flow Inputs][https://www.windmill.dev/docs/getting_started/flows_quickstart].

The defined inputs drive the auto‑generated UI for the flow’s run dialog, so callers can fill out a form without writing any front‑end code. Windmill also supports richer input schemas:

• oneOf – Allows a single input to present a selectable list of distinct object schemas, rendering a drop‑down that lets the user pick the desired shape [Windmill Changelog – oneOf support][https://www.windmill.dev/changelog].
• Dynamic select fields – Options for a select input can be recomputed at runtime based on other input arguments. Both TypeScript and Python scripts can expose a helper that returns the filtered list, enabling conditional filtering or sorting [Windmill Changelog – dynamic select][https://www.windmill.dev/changelog].

Version‑sensitivity – The exact behavior of oneOf and dynamic selects depends on the installed Windmill version; the features were introduced in specific releases documented in the changelog. Verify the runtime version in your deployment before relying on these UI patterns.

Best‑practice checklist

• Parameterize every value that may change between executions before wiring steps together.
• Keep input names short, self‑explanatory, and consistent with the metadata guidelines (e.g., spreadsheet_id, not id1) [Windmill Docs – Metadata recommendations][https://www.windmill.dev/docs/getting_started/flows_quickstart].
• Set sensible defaults to reduce friction for downstream callers.

By following this sequence, a flow is transformed into a generic, composable component that can be invoked from other flows, the Hub UI, or programmatic APIs while preserving type safety and a clean, auto‑generated user experience.

Three Ways to Bind a Step's Input: Static, Flow Env, and Previous Results

Three Ways to Bind a Step's Input: Static, Flow Env, and Previous Results

Windmill flows accept inputs through a piped model that lets each step pull values from three distinct sources.

1. Static values

A static binding is a literal entered directly into the step’s input field. It can be a string, number, or JSON fragment and remains unchanged for every execution of the flow. Because the value is baked into the step definition, static bindings are ideal for true constants such as fixed URLs or hard‑coded thresholds【0†content】.

2. Flow env variables

Flow‑level constants are exposed via flow_env.VARIABLE_NAME. They may hold strings, JSON objects, or resources (e.g., database connections). Workspace variables can be linked to a flow env string through the $ button, allowing secrets or external references to be injected at run time【0†content】【1†content】. Use this mechanism when the value varies per‑deployment but should be available to every step—common cases include API keys, file paths, or shared configuration objects.

3. Dynamic links to previous results

When a step needs data computed earlier in the DAG, bind its input to the result of another step. You can reference a prior step by its identifier (e.g., step_5) or, more interactively, click the plug logo next to the target variable. After the flow or the upstream step has been tested, the UI presents a list of reachable outputs; selecting one creates an expression like step_5.result【0†content】. For scripts that produce large payloads, store the data in ./shared and pass only a reference to avoid bloating JSON results.

Wiring inputs in the editor

1. Select the script step.
2. Click the plug icon beside each variable you wish to bind.
3. Choose the corresponding flow‑input variable, a flow env entry, or a previous step’s output from the panel.

If you prefer a code‑first approach, type the expression directly, e.g., flow_input.my_param or flow_env.API_KEY, into the input field【4†content】.

Guidance on choosing a binding

Binding type	When to use	Performance tip
Static	Values that never change (constants, flags)	No runtime lookup
Flow env	Secrets, resources, per‑run configuration	Keeps sensitive data out of step JSON
Dynamic	Data derived upstream (API responses, computed aggregates)	For large blobs, write to ./shared instead of passing through JSON

Note: Some community tutorials show placeholder syntax such as ${previous_step.result}. Windmill’s official syntax is expression‑based, using step IDs, flow_input, and flow_env. Treat the placeholder form as a paraphrase, not the canonical binding language.

What a Flow Returns: The Last Step's Result and Its Two Exceptions

What a Flow Returns: The Last Step’s Result and Its Two Exceptions

In Windmill a flow’s Result block is simply the output of the step that finishes last. The platform treats the flow as a pipeline, so whatever value – JSON object, scalar, or stream – the final step returns becomes the flow’s return value that callers (other flows, UI widgets, APIs) consume【2†url】.

Two situations where the rule does not apply

1. Error before the final step – If any preceding step returns an error and the step’s error‑handling policy is the default Stop on error and propagate error up, the flow aborts. No normal result is emitted; Windmill’s error handling surface takes over【2†url】.
2. Early return enabled – A step can be marked with Early return. When the step succeeds, execution halts immediately and its output is returned, bypassing any subsequent steps【2†url】.

Because the return contract is that simple, arranging steps deliberately is essential. The step you intend to expose as the public payload should be placed last (or be the early‑return step). Treat any incidental step that happens to run last as a designated return step to avoid accidental payload changes.

Shaping the result after an error

Windmill lets you tune per‑step error behavior in the Advanced tab:

• Retry policy – specify a delay and a maximum number of attempts; the step will be retried automatically on failure【3†url】.
• Continue on error – when enabled, the flow proceeds to the next step after all retries, allowing you to handle the error downstream (e.g., in a branch‑one)【1†url】.
• Continue on disapproval – for Approval steps, this toggle lets the flow continue even when a disapproval or timeout occurs; the resume payload contains an error field that downstream steps can inspect to distinguish the different outcomes【1†url】.

Streaming as a return value (version‑sensitive)

Starting with the 2025.3 release, the last step may return a stream (any AsyncGenerator or iterator‑compatible object). While the job remains in the queue, Windmill streams results via Server‑Sent Events; once the job finishes, the full stream becomes the flow’s final result, or it is attached as wm_stream if a non‑stream result already exists【6†url】. This capability is useful for large LLM responses or progressive data feeds, but it is only available in recent releases, so check your platform version before relying on it.

Practical checklist

• Place the intended payload‑producing step last (or enable Early return).
• Configure retry and error handling per step to match the desired flow resilience.
• Use Continue on error / disapproval when you need post‑error branching.
• If streaming is required, ensure the final step returns a stream and that your Windmill instance runs a version that supports result streaming.

Following these guidelines makes a flow’s return contract explicit, predictable, and aligned with the consuming components’ expectations.

Control Flow That Preserves Reuse: Loops, Branches, and Inner Flows

Control Flow That Preserves Reuse: Loops, Branches, and Inner Flows

Windmill’s visual flow editor lets you enrich a DAG without sacrificing the ability to reuse steps. The three main control‑flow primitives—loops, branches, and inner flows—are each a distinct step type that can be combined with the platform’s error policy.

Loops

• For‑loop step – Takes an iterator expression that evaluates to a list. Each iteration creates a temporary variable (by default item) that feeds every step inside the loop. The loop runs once per element and automatically wires the item variable to downstream expressions 【source】(https://www.windmill.dev/docs/getting_started/flows_quickstart)​.
• While‑loop step – Executes a sequence of steps indefinitely until one of the following occurs: the user cancels the run, an Early stop step is reached, or the loop is halted by an explicit failure. A skip‑failure mode lets the loop ignore non‑critical errors and continue with the next iteration 【source】(https://www.windmill.dev/changelog)​.

Branches

• Branch‑one – Adds a conditional branch that runs only if a Boolean condition evaluates to true. This is ideal for routing logic such as “process only when status == 'ready'”.
• Branch‑all – Executes every defined branch in parallel, treating each as an independent mini‑flow. Use it for fan‑out patterns (e.g., sending notifications to multiple channels simultaneously) 【source】(https://www.windmill.dev/docs/getting_started/flows_quickstart)​.

Inner Flows (Sub‑flows)

A flow can invoke another flow as a step. The called flow runs in isolation, and its final output becomes the ordinary result of the calling step. This encourages a library of reusable sub‑flows: when a group of steps repeats in several places, extract it to a separate flow and reference it instead of duplicating the graph 【source】(https://www.windmill.dev/docs/triggers)​.

Error Policy & Continuations

• Default – A step stops on error and propagates the error upward.
• Continue‑on‑error – When enabled, the flow proceeds to the next step after all retries, allowing a subsequent branch‑one to examine the error field and perform custom handling 【source】(https://www.windmill.dev/changelog)​.
• Continue‑on‑disapproval – Works the same way for approval steps; a disapproval or timeout yields a resume payload containing an error field, which downstream conditions can test without extra bookkeeping 【source】(https://www.windmill.dev/changelog)​.

Practical Guidance

• Use branch‑one for exclusive conditional routes; pair it with continue‑on‑error if you need to react to failures inside the same branch.
• Deploy branch‑all when you need parallel fan‑out; each branch can be an inner flow for maximal reuse.
• Consolidate duplicated step groups into a dedicated sub‑flow and call it via an inner‑flow step—this reduces maintenance overhead and keeps the parent DAG shallow.
• Remember that disapproval or timeout payloads always carry an error field, so you can distinguish success, failure, and human‑driven outcomes directly in branch conditions.

Test as You Build: Step-Level Testing and Run Inspection

Incremental verification in the editor

Windmill treats every step as a testable unit. After configuring a step you can click the Test button to run the flow up to that point, letting you see the intermediate output before later steps exist. The Test up to x action (available from the step’s context menu) executes the DAG from the flow input through the selected node, returning the exact values that downstream steps would receive. This pattern lets you catch wiring mistakes early, without having to run the whole job.

Trigger testing and schema capture

Triggers can be exercised in test mode, which records the incoming webhook payload without invoking the production handler. The captured payload can then be reused as a concrete example for the flow’s input schema. Windmill even lets you update the flow’s JSON schema directly from this test data, automatically inferring argument types such as numbers or strings 【5†source】. This makes the schema‑driven validation step repeatable and version‑controlled.

Inspecting a completed run

When a flow finishes, the Logs tab opens a log explorer that presents a tree view of every step. Each node shows a live status indicator and expands to reveal the exact input passed to the step and the result it returned. The flow status viewer adds a high‑level overview: branches (branchall, branchone), while‑loops, and for‑loops expose their current branch or iteration status in the top node. For‑loop detail pages list every iteration’s outcome without pre‑loading the entire list, allowing you to jump to any iteration on demand 【2†source】.

Tests‑as‑scripts

A changelog entry introduced a tests‑as‑scripts mechanism. Adding a comment of the form

// test: path/to/target

to any script converts it into an automated test for the specified target script or flow. These tests run automatically on every deployment of the target, and their pass/fail/running status appears on the target’s detail page 【4†source】. Built‑in templates for TypeScript and Python simplify writing such tests, and CI badges can be displayed on workspace comparison pages.

Finishing the flow

Once all steps pass local testing and the run inspection looks correct, the editor offers four deployment options:

1. Deploy – make the flow the latest production version.
2. Schedule – create a recurring execution schedule (cron‑like).
3. Create an app – generate an auto‑UI that exposes the flow’s inputs as a web form.
4. Publish to the Windmill Hub – share the flow with the community, optionally adding documentation and version tags.

These actions complete the iterative workflow: design → step‑level test → run inspection → automated test integration → production rollout.

Workflows as Code: Authoring Flows Without the Visual Editor

Workflows as Code (WAC)

Windmill’s Workflows as Code lets you author orchestrations directly in Python or TypeScript, bypassing the visual flow editor. The approach is a single script that defines jobs and their dependencies using a small set of primitives. Because the definition lives in code, it can be generated, templated, or conditionally assembled at runtime—capabilities that are awkward in a static graph UI.

Core primitives (WAC v2)

• workflow() – entry point that registers the orchestration.
• task() – launches a child job; each task gets its own log and timeline.
• taskScript() / taskFlow() – invoke existing Windmill scripts or flows by path, preserving reuse.
• step() – records a lightweight inline result (e.g., a timestamp or random ID) that is replay‑deterministic.
• sleep() – server‑side delay that fully releases the worker slot.
• waitForApproval() – pauses execution until a human approves; the worker is released during the wait.
• parallel() – runs a collection of tasks concurrently, optionally bounded by a concurrency limit.

These primitives were introduced in WAC v2, which switched to checkpoint‑based orchestration. After each primitive, the workflow suspends, releases its worker, and stores a checkpoint. This design eliminates worker waste during sleeps, approvals, or child‑task execution, prevents deadlocks, and allows unlimited parallelism across any number of workers【1†url】.

Limitations

WAC is currently an on‑demand trigger mechanism that applies only to scripts (not to visual flows). The workflow must be invoked explicitly—e.g., via an API call or a schedule—rather than through a flow‑type trigger such as a webhook attached to a visual pipeline. This restriction is documented in the product changelog and should be considered when choosing an orchestration style.

Approval handling

Both the TypeScript and Python SDKs expose a flag to control approver identity:

• TypeScript: selfApproval (default true).
• Python: self_approval (default True).

Setting the flag to false forces the approval step to require someone other than the workflow triggerer, matching the visual editor’s “require external approver” toggle【2†url】.

When to prefer code over the visual editor

Scenario	Recommended approach
Fixed, simple pipelines that benefit from visual inspection	Visual flow editor
Dynamically generated pipelines, conditional branches, or programmatic reuse of sub‑flows	Workflows as Code
Need for fine‑grained control over parallelism, checkpointing, or zero‑waste sleeping	Workflows as Code
Teams that already maintain Python/TypeScript tooling and want to keep orchestration versioned alongside application code	Workflows as Code

In practice, developers often start with the visual editor for rapid prototyping, then migrate to WAC once the pipeline stabilises or when the orchestration logic becomes too complex to represent cleanly on a canvas.

Example (TypeScript)

import { workflow, task, sleep, waitForApproval, parallel } from "windmill";

workflow(async () => {
  const data = await taskScript("scripts/fetch_data");
  await sleep(30);                     // releases the worker for 30 seconds
  const approvals = await waitForApproval({
    selfApproval: false,               // require external approver
    message: "Approve data processing?"
  });
  if (!approvals.approved) return;

  await parallel([
    task(() => taskScript("scripts/transform_a", { data })),
    task(() => taskScript("scripts/transform_b", { data }))
  ]);

  const result = await step(() => ({
    timestamp: Date.now(),
    id: crypto.randomUUID()
  }));

  return result;
});

The snippet demonstrates checkpoint suspension (sleep, waitForApproval), child‑job dispatch (taskScript), deterministic inline results (step), and parallel execution (parallel). Because each primitive creates a checkpoint, the workflow can resume after any interruption without re‑executing completed steps. This model provides deterministic, resource‑efficient orchestration that scales automatically with the available worker pool.

A Reusable-Flow Checklist

Reusable‑Flow Checklist

1. Create the required Input and Result steps

   • Fact: Every flow begins with an Input step that defines the variables the flow accepts, and a Result step that captures the final output — the result of the last executed step, unless an earlier error occurs or Early return is set【{"id":2,"cursor":0}】.
   • Recommendation: Keep the Result step as a clear contract for downstream consumers; rename it to reflect the payload (e.g., final_report).

2. Declare input variables

   • Fact: New input variables default to the string type; they can be re‑typed (e.g., number, JSON) and given default values in the UI【{"id":1,"cursor":1}】.
   • Recommendation: Parameterize all values that may change between environments (API keys, IDs) before moving to production.

3. Bind step inputs

   • Fact: Step inputs may be bound to:
     • Static values entered directly,
     • Flow‑level constants accessed as flow_env.VARIABLE_NAME (including resource references), or
     • Dynamic links to prior step results using the step’s ID and the plug‑logo selector【{"id":0,"cursor":0}】.
   • Fact: The shortcut flow_input.{variable_name} can be typed manually to link a step input to a flow input without using the UI【{"id":2,"cursor":1}】.
   • Recommendation: Wire each binding only after the source step has been successfully tested.

4. Configure control structures

   • Fact:
     • For loops iterate over an iterator expression (e.g., an array)【{"id":5,"cursor":0}】.
     • Branch‑one executes a sub‑flow when a condition evaluates to true【{"id":6,"cursor":0}】.
     • Branch‑all runs all branches in parallel, treating each as an independent flow【{"id":6,"cursor":0}】.
     • Inner flows allow nesting a complete flow inside another flow’s step【{"id":4,"cursor":0}】.
   • Recommendation: Use inner flows to encapsulate frequently reused step groups, making the top‑level flow easier to read.

5. Manage large payloads

   • Recommendation: Store heavy data (e.g., large CSVs, binaries) in the ./shared directory and reference them instead of returning the full payload in JSON results.

6. Set retry policies

   • Fact: Each step’s Advanced tab lets you define a retry count, delay, and maximum attempts; retries are triggered automatically on step failure【{"id":2,"cursor":0}】.
   • Recommendation: Apply retries only to idempotent or transient‑error‑prone operations to avoid unintended side effects.

7. Document metadata

   • Fact: The Metadata tab allows setting a Name, Summary, and Description; Windmill advises keeping these succinct yet explicit【{"id":3,"cursor":1}】.
   • Recommendation: Fill all three fields consistently; include version notes if the flow’s contract changes.

8. Validate against changelog‑driven features

   • Recommendation: If you rely on recent additions such as dynamic select, captured trigger inputs, streaming returns, or WAC v2 primitives, verify their presence in the deployed Windmill version (see the official changelog).

9. Choose a finishing route

   • Recommendation: After the flow passes all tests, decide how to expose it:
     1. Deploy as a production job,
     2. Schedule periodic runs,
     3. Create an app using the autogenerated UI, or
     4. Publish to the Hub for reuse by other teams.

Methodology and sources

• Reviewed: October 15, 2026.
• Method: Documentation-led analysis using the primary sources listed below. Validate versions and environment-specific claims before production use.
• Windmill Docs — Flows Quickstart
• Windmill Docs — Script and Flow Triggers
• Windmill Docs — Introduction (dependency and input management)
• Windmill Changelog (WAC v2, error/approval toggles, input features)
• Bold Tech — Building a CRUD Application with Windmill and Google Sheets (flow input parameterization walkthrough)
• Cubepath — Windmill Script and Flow Automation Platform (step types and data-passing examples)