Flow - Execute

Type identifier: flow:execute Category: Flow Operations

Description

Runs another Flow, optionally scheduling it for a later run. Allows Flows to call other Flows, passing inputs and receiving results. Supports both synchronous (inline) and scheduled (background) run modes.

Input Handles

Input Handle Details

trigger

• Type: trigger
• Notes: Only present when the target Flow's trigger node has isDataOnly: false

scheduledAt

• Type: date

• Notes:

  • Only present when isScheduled is true
  • If the scheduled time is in the past, the Flow runs immediately

Dynamic Input Handles

Input handles are dynamically generated based on the target Flow's trigger node incomingData configuration. The handle ID follows the pattern {type}:{incomingDataId}.

Output Handles

Output Handle Details

flowExecutionId

• Type: string (CUID2 format)
• Notes: Only present when isScheduled is true. The ID can be used to track or cancel the scheduled run.

Dynamic Result Handles

When isScheduled is false, output handles are created for each flow:result node in the target Flow. The handle ID is the result node's nodeId, and the data type matches the result node's configured type.

Configuration Options

Configuration Details

flowId

• Type: string (CUID2 format, 25 characters)
• Validation: Must reference an existing Flow in the current Space
• Notes: Select from the Flow picker in the node configuration

triggerNodeId

• Type: string
• Validation: Must reference a flow:trigger node in the target Flow
• Notes: Automatically set when selecting a Flow with the Flow picker

isScheduled

• Type: boolean
• Default: false

• Notes:

  • When true, the Flow is queued to run in the background
  • When false, the Flow runs inline and results are available immediately

Behaviour

Execution Flow

1. Node receives trigger on the trigger input handle
2. Fetches the target Flow version and validates the trigger node
3. Resolves all input values from connected handles
4. Maps input values to the target Flow's incoming data Schema
5. Either schedules or runs the Flow based on isScheduled

Synchronous Run (isScheduled: false)

1. Runs the target Flow inline
2. Result node outputs are made available on output handles
3. UX nodes (ux:message, ux:action) automatically pass output to the parent Flow
4. Triggers success on completion or error on failure (see Child Flow Failure Propagation)

Scheduled Run (isScheduled: true)

1. Reads the scheduledAt input
2. If the scheduled time is in the past, runs immediately
3. Queues the Flow to run in the background
4. Outputs the flowExecutionId for tracking
5. Triggers success after scheduling

Child Flow Failure Propagation

A synchronous child Flow fails when one of its nodes fails with an error that the node does not handle itself, that is, the failing node has no connected error output. This includes data nodes (for example a data:expression that throws) whose failure would otherwise only resolve to null in a consumer that tolerates missing data, such as flow:result. Errors that are only written to the run log (for example Missing required property '…' in source schema while mapping inputs) do not fail the child Flow, and a failing node whose error output is connected is treated as handled.

When the child Flow fails:

• If this node's error output is connected, it triggers error and sets its error result to { message }, where the message names the failing child Flow node and its error. success is not triggered.
• If this node's error output is not connected, the failure is unhandled in the calling Flow as well: the node fails, and the failure keeps propagating to the next calling flow:execute node, up to the first one with a connected error output.
• When the target trigger is data-only and this node is resolved as data, its result outputs fail with the child Flow failure when they are read, so the failure still propagates to the calling Flow (even through consumers that tolerate missing data).

Input Mapping

For each incoming data item in the target trigger:

1. Resolves the corresponding input handle value
2. For entity types, applies the standard Record fields
3. Maps the value to the target Schema structure

Result Propagation

• ux:message and ux:action outputs are automatically passed to the parent Flow
• flow:result outputs are captured and available on the corresponding output handle

Edge Cases

Examples

Synchronous Run

{
  "type": "flow:execute",
  "data": {
    "label": "Execute Process Order",
    "flowId": "clx1234567890abcdefghij",
    "triggerNodeId": "node_abc123",
    "isScheduled": false
  }
}

Input Handles (assuming target trigger has orderId string input):

• trigger (trigger)
• string:orderId (string)

Output Handles (assuming target has one result node):

• success (trigger)
• error (trigger)
• node_result_xyz (matches result node type)

Scheduled Run

{
  "type": "flow:execute",
  "data": {
    "label": "Schedule Email Reminder",
    "flowId": "clx9876543210zyxwvutsrq",
    "triggerNodeId": "node_def456",
    "isScheduled": true
  }
}

Input Handles:

• trigger (trigger)
• scheduledAt (date)
• Dynamic inputs from target trigger

Output Handles:

• success (trigger)
• error (trigger)
• flowExecutionId (string)