Nested Workflow Execution

Relevant source files

• apps/docs/content/docs/en/blocks/condition.mdx
• apps/sim/app/api/schedules/execute/route.test.ts
• apps/sim/app/api/schedules/execute/route.ts
• apps/sim/app/api/webhooks/trigger/[path]/route.test.ts
• apps/sim/app/api/webhooks/trigger/[path]/route.ts
• apps/sim/app/api/workflows/[id]/execute/route.ts
• apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/terminal/utils.ts
• apps/sim/app/workspace/[workspaceId]/w/[workflowId]/hooks/index.ts
• apps/sim/app/workspace/[workspaceId]/w/[workflowId]/hooks/use-node-utilities.ts
• apps/sim/app/workspace/[workspaceId]/w/[workflowId]/hooks/use-workflow-execution.ts
• apps/sim/app/workspace/[workspaceId]/w/[workflowId]/utils/workflow-canvas-helpers.ts
• apps/sim/app/workspace/[workspaceId]/w/[workflowId]/utils/workflow-execution-utils.ts
• apps/sim/app/workspace/[workspaceId]/w/components/preview/components/preview-workflow/components/subflow/subflow.tsx
• apps/sim/app/workspace/[workspaceId]/w/components/preview/components/preview-workflow/preview-workflow.tsx
• apps/sim/background/schedule-execution.ts
• apps/sim/background/webhook-execution.ts
• apps/sim/background/workflow-execution.ts
• apps/sim/blocks/blocks/workflow.ts
• apps/sim/blocks/blocks/workflow_input.ts
• apps/sim/executor/dag/builder.test.ts
• apps/sim/executor/dag/builder.ts
• apps/sim/executor/dag/construction/edges.test.ts
• apps/sim/executor/dag/construction/edges.ts
• apps/sim/executor/dag/construction/loops.ts
• apps/sim/executor/dag/construction/nodes.ts
• apps/sim/executor/dag/construction/parallels.ts
• apps/sim/executor/dag/types.ts
• apps/sim/executor/execution/block-executor.ts
• apps/sim/executor/execution/edge-manager.test.ts
• apps/sim/executor/execution/edge-manager.ts
• apps/sim/executor/execution/engine.test.ts
• apps/sim/executor/execution/engine.ts
• apps/sim/executor/execution/executor.ts
• apps/sim/executor/execution/state.ts
• apps/sim/executor/execution/types.ts
• apps/sim/executor/handlers/condition/condition-handler.test.ts
• apps/sim/executor/handlers/condition/condition-handler.ts
• apps/sim/executor/handlers/workflow/workflow-handler.test.ts
• apps/sim/executor/handlers/workflow/workflow-handler.ts
• apps/sim/executor/index.ts
• apps/sim/executor/orchestrators/loop.ts
• apps/sim/executor/orchestrators/node.ts
• apps/sim/executor/orchestrators/parallel.ts
• apps/sim/executor/types.ts
• apps/sim/executor/utils/block-data.ts
• apps/sim/executor/utils/parallel-expansion.ts
• apps/sim/executor/utils/subflow-utils.ts
• apps/sim/hooks/use-execution-stream.ts
• apps/sim/lib/logs/execution/trace-spans/trace-spans.test.ts
• apps/sim/lib/logs/execution/trace-spans/trace-spans.ts
• apps/sim/lib/webhooks/processor.ts
• apps/sim/lib/workflows/blocks/block-dimensions.ts
• apps/sim/lib/workflows/executor/execution-core.ts
• apps/sim/lib/workflows/executor/execution-events.ts
• apps/sim/lib/workflows/executor/human-in-the-loop-manager.ts
• apps/sim/stores/terminal/console/store.ts
• apps/sim/stores/terminal/console/types.ts
• helm/sim/templates/cronjobs.yaml

Purpose and Scope

This document explains how workflows execute other workflows inline through the Workflow block (BlockType.WORKFLOW and BlockType.WORKFLOW_INPUT). It covers implementation details of the WorkflowBlockHandler, call chain validation for cycle detection, depth limits for resource management, trace span aggregation, and the instance-based correlation mechanism that allows the UI to render nested executions.

For information about loop and parallel subflow execution, see 3.5 Loop & Parallel Execution For human-in-the-loop pause/resume mechanics, see 3.14 Human-in-the-Loop & Paused Executions

---

Workflow Block Handler

The WorkflowBlockHandler is the core engine for nested execution. It creates a sub-executor with an isolated ExecutionContext while maintaining a link to the parent.

Sources: apps/sim/executor/handlers/workflow/workflow-handler.ts38-40

Handler Logic Flow

Diagram: Nested Workflow Handler Execution Flow

The handler implements executeWithNode to support execution within loops or parallel branches, passing nodeMetadata to preserve iteration context apps/sim/executor/handlers/workflow/workflow-handler.ts54-61

Sources: apps/sim/executor/handlers/workflow/workflow-handler.ts63-258 apps/sim/executor/handlers/workflow/workflow-handler.ts84-93

---

Call Chain & Depth Validation

To prevent infinite recursion and manage system resources, the platform enforces hard limits on nesting.

Call Chain Tracking

The system tracks the sequence of workflow IDs in the current execution path using a "Call Chain".

1. Header Propagation: In API-based executions, the chain is passed via the X-Sim-Via header (SIM_VIA_HEADER) apps/sim/lib/execution/call-chain.ts27-29
2. Validation: The validateCallChain function checks if the chain length exceeds MAX_CALL_CHAIN_DEPTH (25) apps/sim/lib/execution/call-chain.ts11-14
3. Cycle Detection: While the depth limit is the primary safeguard, the chain allows for future logic to detect repeating patterns of workflow IDs.

SSE Propagation Limits

While execution can go 25 levels deep, real-time UI updates (via Server-Sent Events) are limited to a shallower depth to prevent browser performance degradation.

Constant	Value	Description
MAX_CALL_CHAIN_DEPTH	25	Maximum allowed nesting for workflow execution apps/sim/lib/execution/call-chain.ts11
MAX_SSE_CHILD_DEPTH	3	Maximum depth for propagating onBlockStart/Complete callbacks apps/sim/executor/constants.ts162

Sources: apps/sim/lib/execution/call-chain.ts38-51 apps/sim/executor/handlers/workflow/workflow-handler.ts86-93 apps/sim/executor/handlers/workflow/workflow-handler.ts148-156

---

Instance Correlation & UI Aggregation

A critical challenge in nested execution is attributing child block events (e.g., "LLM Block started") to the correct parent "Workflow Block", especially when that parent is inside a loop.

The Instance ID Mechanism

1. Generation: The WorkflowBlockHandler generates a unique instanceId (UUID) for every single invocation of a workflow block apps/sim/executor/handlers/workflow/workflow-handler.ts84
2. Registration: It calls onChildWorkflowInstanceReady, passing the instanceId and the parent's iterationContext apps/sim/executor/handlers/workflow/workflow-handler.ts163-168
3. Execution Event Tagging: Every SSE event generated by the child workflow (and its children) includes this childWorkflowInstanceId apps/sim/lib/workflows/executor/execution-events.ts184-186

Trace Span Aggregation

When a child workflow finishes, its internal block logs are converted into TraceSpan objects and attached to the parent block's output.

Diagram: Child Trace Span Aggregation

The transformSpanForChildWorkflow function ensures that spans coming from a child are clearly marked with isFromChildWorkflow: true and the childWorkflowName for clear debugging in the logs apps/sim/executor/handlers/workflow/workflow-handler.ts497-518

Sources: apps/sim/executor/handlers/workflow/workflow-handler.ts464-495 apps/sim/executor/handlers/workflow/workflow-handler.ts520-543 apps/sim/lib/logs/execution/trace-spans/trace-spans.ts1-6

---

Data Flow & Input Mapping

Child workflows receive data through two primary mechanisms:

1. Direct Input: A single object passed to the child's start trigger.
2. Input Mapping: A key-value map where parent variables are assigned to specific child input variables.

The lazyCleanupInputMapping utility is used to ensure that the mapping is sanitized against the child's current block structure before execution apps/sim/executor/handlers/workflow/workflow-handler.ts127-132

Deployed vs. Draft Context

The handler respects the environment of the parent:

• If the parent is a Deployed execution, it calls checkChildDeployment to ensure the child is also deployed apps/sim/executor/handlers/workflow/workflow-handler.ts98-104
• It then uses loadChildWorkflowDeployed to fetch the immutable versioned state apps/sim/executor/handlers/workflow/workflow-handler.ts107
• If in Draft (Editor) mode, it loads the current working state apps/sim/executor/handlers/workflow/workflow-handler.ts108

Sources: apps/sim/executor/handlers/workflow/workflow-handler.ts121-140 apps/sim/executor/handlers/workflow/workflow-handler.ts326-381 apps/sim/executor/handlers/workflow/workflow-handler.ts383-400

---

Error Handling & Cancellation

Nested workflows share the parent's abortSignal. If a parent execution is cancelled, the signal propagates to the child's subExecutor, ensuring resources are freed immediately apps/sim/executor/handlers/workflow/workflow-handler.ts183

Errors in child workflows are caught and wrapped in a ChildWorkflowError apps/sim/executor/errors/child-workflow-error.ts1-19 This error includes the child's name and ID, allowing the useWorkflowExecution hook to provide a "breadcrumb" style error message to the user apps/sim/app/workspace/[workspaceId]/w/[workflowId]/hooks/use-workflow-execution.ts:78-102.

Sources: apps/sim/executor/handlers/workflow/workflow-handler.ts208-220 apps/sim/executor/handlers/workflow/workflow-handler.ts183