v2 Runtime v2

The Runtime is Flowgear's compiled execution and design model for Workflows.

It combines a visual designer with a YAML code view, validates the Workflow against current Node Method contracts, and compiles the definition to binaries for execution. The Runtime also manages deferred data, nested execution scopes, Workflow state, logging, and cleanup.

Workflow design

A Workflow contains ordered Steps. Each Step invokes a Node Method or defines a control-flow container.

Workflow Parameters define the input contract. Workflow Returns define the output contract. Step Parameters can use literal values or Expressions that reference Workflow Parameters and earlier Step Returns.

The canvas and code view edit the same Workflow definition. You can move between them while you build, and the designer reports YAML, structure, type, mapping, and compilation problems against the affected part of the Workflow.

See Workflow YAML for the definition format.

Compiled execution

Before a Workflow runs, Flowgear binds its Steps to published Node Method contracts, validates the design, renders executable code, and compiles it.

Compilation catches problems such as incompatible types, invalid Expressions, missing Method inputs, unsupported mapping shapes, and invalid trigger arrangements before the published Workflow is activated.

The resulting artifact is a compiled Workflow assembly. If an embedded C# script requires additional runtime packages, Flowgear publishes a bundle containing the Workflow assembly and its required files.

Lazy evaluation and streaming

The Runtime can defer reading a Stream or asynchronous collection until a downstream Step consumes it. This reduces unnecessary buffering and allows the same Workflow structure to process large streams or numbers of records without requiring design changes.

See Lazy Evaluation and Streaming for the complete model and its limits.

Ways to run

A Workflow can be activated in several ways:

  • Run or debug it from the designer or a build tool.
  • Preview data and inferred schemas while designing.
  • Run it on a Daily, Weekly, Monthly, or Cron schedule.
  • Enable a listener that waits for an external event.
  • Publish it as an HTTP endpoint.
  • Publish it as a tool through the Workflow MCP Server.

Published triggers only activate a Workflow in an Environment where the Workflow is enabled. When Release Management is enabled, the revision published to that Environment is the revision that runs.

Environments and Clusters

A Workflow runs in an Environment. The Environment determines which published Workflow revision, Connection values, hostname, permissions, and related configuration apply.

By default, Workflows run on Flowgear's cloud Cluster. You can assign a Workflow to a Local Cluster when it must reach resources on a private network or local machine. All Steps in a Workflow run on the selected Cluster. This behaviour differs from the v1 Runtime, where DropPoints cause specific Steps in a Workflow to run locally.

Connections used by the Workflow must be available on a compatible Cluster.

Logs and diagnostics

The Runtime reports live and completed Step activity through Workflow logs. The Console can show status, duration, row or byte counters, Property previews, Returns, and errors while a Workflow runs.

Streams and asynchronous collections are wrapped for logging without changing the value consumed by the Workflow. Large values can be truncated in the visible preview and made available as downloads when the logging policy permits storage of the complete value.

You can enable Logging.Redact on a Workflow Property to remove its value from Workflow logs. Redaction does not change the value supplied to the Workflow, and it does not sanitize Debug results, exception messages, or diagnostics emitted directly by a Node.

Agent-assisted design

The Workflow designer includes an assistant that can discover Node Methods, propose Workflow YAML, help select Connections, run the Workflow, inspect failures, and refine the design. You review the proposed Workflow before applying it to the canvas.

The Builder MCP Server exposes the server-side build tools to compatible external coding agents. These tools can discover exact contracts, debug a Workflow under a persisted identity, inspect logs, and save the tested revision.

Coexistence with v1 Runtime Workflows

Workflows for the v1 and v2 Runtimes can coexist on the same Site. Shared objects such as Sites, Environments, API keys, and folders can appear across both runtimes, while the designer, Workflow definition, execution engine, trigger implementation, and local Cluster model differ.

Existing v1 Runtime Workflows do not need to be ported to the v2 Runtime. v1 Runtime remains supported, including Connector updates, and users can select either runtime when creating a Workflow.

See v1 Runtime and v2 Runtime for a detailed comparison, coexistence guidance, and a safe migration outline.

See also