Workflow Parameters and Returns v2

Workflow Parameters and Returns define the external contract of a Workflow.

Parameters are values supplied when the Workflow starts. Returns are values produced when it finishes. Sub-Workflows, Debug runs, Builder tools, and generated interfaces use these declarations to understand the Workflow boundary.

Workflow Parameters

In Code view, declare input names beneath the root Parameters map:

Parameters:
  customerId:
    Type: string
    Description: Customer identifier to retrieve.
    Sample: CUST-001

Reference a Workflow Parameter with a leading dot:

{.customerId}

The leading dot means the value comes from the Workflow input contract rather than a Step.

Workflow Parameters cannot define Expression, including on nested child Properties. They declare data supplied by the caller. Use Sample for representative design-time data and Value only when a literal default or authored input value is appropriate to the current invocation contract.

For structured inputs, declare Type: object or Type: array and use nested Properties to define the known shape. Do not use a complex literal Value as an untyped parallel schema.

Workflow Returns

Declare outputs beneath the root Returns map and map them from available Workflow Parameters or Step Returns:

Returns:
  customer:
    Type: object
    Expression: "{getCustomer.Customer}"
    Properties:
      id:
        Type: string
        Expression: "{getCustomer.Customer.id}"
      name:
        Type: string
        Expression: "{getCustomer.Customer.name}"

Return names and shapes are part of the reusable Workflow contract. Prefer focused business outputs over exposing an entire provider response without need.

For ordinary and Sub-Workflow execution, define at least one meaningful Return when the caller needs a result. This also makes Debug and Builder MCP output useful.

HTTP and MCP responses

An HTTP or MCP Workflow uses a matched receive/respond trigger pair. The root-level respond Step defines the transport response, and the runtime injects that response into the invocation result.

Do not duplicate that response under ordinary Workflow Returns. Keep the respond Step at root level and map the body, status, headers, or tool result according to its discovered Method contract.

Step Returns versus Workflow Returns

A Step Returns map describes the output envelope published by its exact Node Method. Preserve the discovered names and nested shape on the Step.

Map from that envelope at the consumer:

• A later Step Parameter consumes the field it needs.
• A Workflow Return selects or reshapes the final output.
• A respond Step constructs an HTTP or MCP transport response.

Availability and scope

An Expression can refer to a Workflow Parameter or a Step Return that is available in its current execution scope. A Step cannot refer to a later Step.

Nested control-flow scopes further limit what is available. A collection container can establish per-item scope for its child mappings. When a reference is not valid, the Problems tab reports the path and, when known, valid Returns or child Properties.

Streams

A Stream is a single opaque output. Do not map the same direct Stream source into more than one top-level Workflow Return. If a caller needs multiple interpretations, parse or transform the Stream inside the Workflow and return the resulting values.

Contract changes

Treat renamed, removed, retyped, or reshaped Parameters and Returns as interface changes. Before saving or releasing them, review:

• Sub-Workflow callers.
• HTTP or MCP schemas and generated OpenAPI definitions.
• Apps and external clients.
• Test payloads and agent prompts that use the old contract.

Use relationships and source search to identify dependants, then release caller and callee changes in a compatible order.