Using the Start a Workflow Node

Overview

The Start Workflow Execution node launches another workflow from inside a running workflow. In this article, we'll be covering what the node does, how to configure it, and how to choose between its two execution modes.

This node is the primary tool for building modular workflow systems — where one orchestrating workflow triggers other focused workflows that each handle a specific task.

Understand how the node works

When the Start Workflow Execution node runs, it starts a new execution of the workflow you select. By default, the parent workflow pauses and waits for the child workflow to complete before moving on to the next node. If the child execution fails or is cancelled, the parent node fails accordingly.

You can change this behavior using the Fire and forget option, described below.

On retry, the node re-uses the existing child execution by default rather than starting a new one. You can override this with the Start new workflow execution on retry option.

Add the node to your workflow

1. In the Graph View, click the + icon where you want to add the node.
2. In the node picker, open the Workflows tab.
3. Select Start workflow execution.
4. In the node's side panel, configure the inputs described below.

Configure the node inputs

Workflow (required)

Select the workflow to start. The dropdown lists all workflows in your account. The selected workflow must be enabled when the node runs, or the node will fail with a WORKFLOW_DISABLED error.

The target workflow's trigger type does not have to be Manual. However, the object type must be compatible with any Object ID value you pass.

Input (optional)

Data to pass to the child workflow as its trigger input. The value must satisfy the child workflow's trigger input schema, if one is defined. You can reference values from the current workflow's state using a State input or a Function input.

Object ID (optional)

The Global ID of the gaiia record to associate with the child execution — for example, an account or inventory item. When supplied, the child execution appears on that record's Workflows tab, just like a manually launched execution.

Fire and forget (optional)

Controls whether the parent workflow waits for the child execution to finish.

• Disabled (default): the parent workflow pauses until the child execution completes. If the child fails or is cancelled, the parent node fails.
• Enabled: the parent workflow continues immediately after starting the child execution, without waiting for it to complete. The node outputs the child execution's ID so you can reference it downstream.

Use fire and forget when the child workflow runs independently and its outcome does not affect the parent's logic — for example, sending a notification or logging an event in parallel.

Start new workflow execution on retry (optional)

Controls what happens when the parent node is retried.

• Disabled (default): on retry, the node resumes the existing child execution rather than starting a new one. This prevents duplicate executions when retrying transient failures.
• Enabled: on retry, the node always starts a fresh child execution. Use this only when the child workflow is safe to run more than once for the same parent node.

Access the node output

When Fire and forget is enabled, the node outputs the started execution's ID:

• state.steps['your-node-slug'].output.workflowExecutionId — the ID of the child execution that was started.

When Fire and forget is disabled, the node waits for the child execution to complete. The child workflow's output (as defined by its End node output mapper) becomes available via:

• state.steps['your-node-slug'].output

If the child workflow does not define a workflow-level output mapper on its End node, the output will be empty. See Using Output Mappers for how to configure a workflow output.

Understand error codes

The node can fail with the following error codes:

• WORKFLOW_NOT_FOUND — the selected workflow no longer exists.
• INVALID_WORKFLOW_ID — the workflow ID is malformed or could not be resolved.
• STARTED_WORKFLOW_EXECUTION_FAILED — the child execution failed. Only applies when Fire and forget is disabled.
• STARTED_WORKFLOW_EXECUTION_CANCELLED — the child execution was cancelled. Only applies when Fire and forget is disabled.

You can attach error links to this node to handle specific error codes gracefully. For example, draw an error link for STARTED_WORKFLOW_EXECUTION_FAILED to route failures to a recovery path without failing the parent workflow. See Handling Node Failures: Retry Strategies, Timeouts, and Error Links for details.

Common patterns

Reusable sub-workflows

Build a library of focused workflows — one for provisioning, one for sending notifications, one for updating records — and call them from a single orchestrating workflow using this node. This keeps each workflow small, testable, and reusable across multiple parent workflows.

Passing object context

When your child workflow performs actions on a specific gaiia record, pass that record's Global ID using the Object ID field. The child execution will appear on that object's Workflows tab, giving your team full visibility into what ran and when.

Launching parallel tasks

Combine this node with a Parallel Loop node to start multiple child executions concurrently — for example, provisioning services across a list of accounts at the same time.