Workflow YAML v2

A Workflow is stored as a YAML document.

The canvas and code view edit the same definition. Changes made in code are parsed and validated before the designer applies them to the Workflow.

Document structure

A Workflow definition contains three main sections:

  • Parameters defines values supplied when the Workflow starts.
  • Steps is the ordered list of work performed by the Workflow.
  • Returns defines values returned by the Workflow.

The following example shows the structure only. Replace every placeholder with a Node, version, Method, and Property contract obtained from the Console or Builder MCP before you run or save it.

Parameters:
  requestId:
    Type: string
    Sample: REQ-001

Steps:
  - Name: processRequest
    Description: Processes the supplied request.
    Node: <node-name>@<version>
    Method: <method-name>
    Parameters:
      RequestId:
        Type: string
        Expression: "{.requestId}"
    Returns:
      Result:
        Type: object
        Properties:
          status:
            Type: string

Returns:
  result:
    Type: object
    Expression: "{processRequest.Result}"
    Properties:
      status:
        Type: string
        Expression: "{processRequest.Result.status}"

Name: Process request
RuntimeVersion: 2

The Console and platform can also add identity and storage fields such as SiteKey, Key, FolderKey, ClusterKey, and FileHash. Preserve current values when you edit an existing Workflow. Builder MCP uses Key and FileHash to prevent an update from overwriting a newer revision.

Steps

Each item under Steps can contain:

Field Description
Name Unique camelCase name used by Expressions within the current scope.
Description Optional explanation of the Step's purpose.
Node Internal Node name and version in <name>@<version> form.
Method Exact Method name exposed by the selected Node.
TemplateKey Designer metadata identifying the template used to create the Step. It does not control runtime evaluation.
Parameters Values supplied to the Node Method.
Returns Output shape exposed by the Node Method.
Steps Child Steps owned by a container Step.

Ordinary Step Returns should preserve the output envelope defined by the selected Method. Do not rename or flatten them in the Step. Map the required fields when a downstream Parameter or Workflow Return consumes them.

Properties

Workflow Parameters, Workflow Returns, Step Parameters, and Step Returns use the same Property structure.

See Workflow Properties for valid shapes, short scalar form, complex values, arrays, Streams, Samples, and logging behavior. See Workflow Parameters and Returns and Steps for their complete contracts.

Field Description
Type Simplified Workflow type used for validation and mapping.
Description Guidance about the Property's purpose or contract.
Sample Representative design-time data used for preview and inference. It is not a runtime assignment.
Value Literal runtime value.
Expression Runtime mapping from a Workflow Parameter, an earlier Step Return, or a mapping function.
Logging Workflow log handling such as Redact.
Properties Nested fields for an object or array item.

A runtime-assigned leaf normally uses either Value or Expression, not both.

Types

Workflow YAML supports these authored types:

  • string
  • number
  • boolean
  • datetime
  • timespan
  • guid
  • enum
  • object
  • array
  • stream
  • connectionKey

The selected Node Method contract determines which type and shape a Property must use.

Values and Expressions

Use Value for a literal scalar or an array whose items are scalar values.

Use Expression for a value obtained at runtime:

  • {.requestId} refers to the Workflow Parameter named requestId.
  • {processRequest.Result} refers to the Result Return from the processRequest Step.
  • {processRequest.Result.status} refers to a nested field.

Function calls are not enclosed in braces. Braces identify references inside the function, for example:

CONCAT({getCustomer.Customer.firstName}, " ", {getCustomer.Customer.lastName})

A Step can only reference Workflow Parameters and Returns that are available earlier in its execution scope. It cannot reference a later Step.

Objects and arrays

Use Properties to declare an object's fields or an array item's shape.

When an array maps an upstream collection, put the collection Expression on the array Property and map each target field beneath Properties. The Runtime evaluates the mapping for each item.

Do not place a structured JSON or XML document directly in a complex Value. Pass the document to an appropriate parser Step and map the parsed object or array.

HTTP and MCP Workflows

HTTP and MCP Workflows normally begin with a receive Step and end with one root-level response Step. Map the response on that Step rather than adding ordinary Workflow Returns.

Validation

Flowgear validates YAML structure before it compiles the Workflow. Validation can report:

  • Unknown or duplicate Workflow, Step, or Property fields.
  • Missing or duplicate Step names.
  • Missing Node or Method names.
  • Unsupported or incompatible types.
  • Invalid Value and Expression combinations.
  • Unknown functions or malformed references.
  • Missing required Parameters or Returns.
  • Invalid Connection types, trigger arrangements, or container shapes.

Use the path shown in the Problems tab to locate the affected part of the definition. See Workflow Validation for the validation layers and diagnostic categories.