Sub-Workflow

Embed another workflow as a single node. Edit the inner workflow inline with breadcrumb navigation.

Overview

The Sub-Workflow node embeds another workflow inside the current one. From the outside it looks like any node – it has input/output ports and a status indicator. Click the Expand icon to edit the inner workflow inline; a breadcrumb appears at the top of the editor showing the nesting path ([Parent] -> [Child] -> ...). Execution is recursive with a maximum nesting depth of 5 levels, and cycle detection prevents infinite loops.

A workflow becomes callable as a sub-workflow when it contains at least one matched pair of Sub-Workflow Input + Sub-Workflow Output nodes sharing the same routeId. Each pair defines a “route” through the workflow; a single workflow can expose multiple routes.

How to add a sub-workflow

Two paths:

• Create empty (recommended for new work) – Click “Create empty sub-workflow” in the config panel. A fresh child workflow is created under the current parent with one input + one output node seeded automatically, and the editor opens for editing immediately. The child is hidden from the project workflow list (it’s not standalone – only reachable via this parent).
• Reference an existing workflow – Use the Workflow dropdown to pick any standalone workflow that has matched input/output boundary nodes. The picker hides child workflows owned by other containers (so you only see top-level, reusable workflows).

Configuration

Field	Type	Default	Description
Label	string	"Sub-Workflow"	Display name for this node instance.
Create empty sub-workflow	button	n/a	Creates and opens a fresh child workflow seeded with one input + one output node. Disabled until the parent has been saved.
Workflow	selector	none	Dropdown to pick an existing standalone workflow to reference. Hides child workflows of other containers.
All Projects	toggle	off	When enabled, shows workflows from all projects (not just the current one).
Route	selector	none	Select which input/output route to use if the referenced workflow exposes multiple routes.
Interface Preview	read-only	n/a	Displays the input and output port definitions of the selected route.
Refresh	button	n/a	Reloads the referenced workflow’s interface definition.
View mode	selector	Ports	How the node renders on the canvas. v1 ships the Ports view (input/output handles + status + preview). Storyboard / Video / Script views land in a later release as plug-ins.
Edit (expand icon on node)	button	n/a	Opens the referenced workflow for editing inline. A breadcrumb appears at the top of the editor showing the nesting path; click any crumb to jump to that level.
View Workflow	button	n/a	Opens the referenced workflow in a read-only viewer modal (does not navigate away).
Open Workflow	button	n/a	Same as the Edit (expand) button – opens the referenced workflow inline with breadcrumb nav.

Inputs & Outputs

Inputs: Dynamic handles based on the selected route’s input port definitions.

Outputs: Dynamic handles based on the selected route’s output port definitions.

Breadcrumb navigation

When you open a referenced workflow via Expand (or “Open Workflow”), a breadcrumb appears at the top of the editor: [Original Workflow] -> [Sub-workflow A] -> [Sub-workflow B]. Click any crumb to jump to that level. The breadcrumb auto-clears when you navigate back to the original workflow.

If you have unsaved changes when you click Expand, the editor prompts you to save or discard before navigating.

Validation

Workflows that contain sub-workflow-input or sub-workflow-output boundary nodes are validated at save time:

• Every input boundary node must have a matching output boundary node sharing the same routeId.
• Every output boundary node must have at least one declared output port.
• Two boundary nodes (input or output) must not share the same routeId.

Violations are rejected with 400 invalid_sub_workflow and a structured details array listing each error.

Best Practices

• Keep sub-workflow nesting shallow. The maximum depth is 5 levels; deeply nested workflows are harder to debug.
• Use the “Create empty” button for one-off encapsulation – it keeps the child workflow private to its parent.
• Use the Workflow reference dropdown for reusable building blocks – these stay top-level and can be picked from any parent.
• Use descriptive labels to clarify each Sub-Workflow node’s role in the parent.
• Refresh the interface after modifying the referenced workflow to pick up any port changes.
• Use the “All Projects” toggle sparingly – prefer workflows within the same project for organizational clarity.

Common Use Cases

• Reusing a standard video composition pipeline across multiple content workflows.
• Encapsulating complex processing chains (image -> upscale -> effects) into a single reusable node.
• Building template-like workflows that can be parameterized via input ports.
• Organizing large workflows into manageable, modular sub-components.
• Grouping a multi-node scene (i2i + animate + speech + lip-sync) into a single shot container.

Tips

• Cycle detection prevents a workflow from calling itself (directly or indirectly). Detection uses workflowId:routeId pairs, so the same workflow can still be called via different routes.
• Execution progress is tracked via subWorkflowProgress with currentNode, completed, and total counts.
• Only nodes reachable from the selected route’s input (via BFS traversal) are executed – not the entire referenced workflow.
• The route snapshot caches the interface definition. Use the Refresh button if the referenced workflow’s ports have been modified.
• Child workflows created via “Create empty” do not show up in the project’s main workflow list – they’re owned by their parent and reachable only via the Edit/Expand button.