Skip to main content
The Run Workflow task executes another workflow as a sub-run of the current workflow. The parent workflow blocks until the child workflow reaches a terminal state, then branches on the outcome. Use Run Workflow to compose workflows out of smaller workflows. To run a single dataflow as a step, use the Run Package task instead.

Overview

  • Runs another workflow as a sub-run attached beneath the parent.
  • The parent workflow waits until the child workflow finishes (succeeds, fails, or is stopped) before continuing.
  • The child sub-run runs on the same cluster as the parent.
  • Stopping the parent run cascades and stops any child sub-runs.
  • The child workflow’s outcome drives the parent’s success, failure, and completion branches.

Configuration

1
Add a Run Workflow task to the workflow canvas.
2
Select the workflow you want to run. The selector only lists workflows, and you cannot reference the workflow the task lives in.
3
Optionally set variable overrides to pass into the child workflow.
4
Connect the outgoing edges to define what runs on success, failure, or completion of the child workflow.

Nesting limit

A workflow can run other workflows, but those child workflows cannot themselves contain a Run Workflow task. Nesting is limited to one level. Integrate.io checks this rule when you save the workflow and again when you start a run. If a workflow violates the limit, the validation error is:
A Workflow that is run by another Workflow cannot itself run a Workflow (nesting is limited to one level)
A workflow also cannot reference itself, directly or through another workflow. Integrate.io blocks cycles at save time and at run launch.

Validation

When you validate the parent workflow, Integrate.io also validates the child workflow this task runs. If the child workflow has errors, the task reports its name and error count, for example:
“Load customers” is not valid (6 errors). Open that package, fix it, then validate this one again.
Open the child workflow, fix its errors, then validate the parent workflow again. See Validating a package.

Variables and secrets

Every Run Workflow sub-run resolves its variables in this order, highest priority first:
  1. Per-task variable overrides you set on the Run Workflow task.
  2. Inherited variables from the parent run, meaning the resolved values the parent workflow is running with.
  3. The child workflow’s own stored variables.
An override is any value you set on the task that differs from the child workflow’s current default for that key. Values you leave at the child’s default are treated as inherited and fall through to the parent run’s value. A variable defined on the parent workflow reaches the sub-run without being redeclared on the task. The delta is re-evaluated on every run against the child workflow’s current variables, so renaming, adding, or removing a variable on the child updates the sub-run without re-saving the parent. Inherited public variables cross workspace boundaries. A parent run’s public variables reach the sub-run even when the child workflow lives in a different workspace and are readable by a user scoped only to the child. Parent secrets are not inherited. Secrets declared by the parent workflow are removed from the inherited variables before the sub-run starts, so they never reach the sub-run. The sub-run uses the child workflow’s own secrets. Per-task secret overrides are not supported. Secrets always come from the child workflow.

Referencing a parent variable

To use a parent workflow variable inside the child, reference it with the same ${name} syntax you would use anywhere else and leave the Run Workflow task’s override for that key blank. Typing ${ingest_run_id} as the task’s override value stores that literal string as the override and blocks inheritance.
Child workflow variable value
If the parent workflow declares ingest_run_id, the sub-run resolves it from the parent run’s value. Clear the corresponding row on the Run Workflow task to let the inherited value through.

Run tree and monitoring

The child workflow appears as a sub-run beneath the parent run in the job history. You can open it to see its own tasks, logs, and status. Stopping the parent run also stops the child sub-run.

Use cases

  • Reuse an existing workflow as a step inside a larger orchestration.
  • Split a long workflow into smaller workflows that can also run on their own.
  • Branch the parent workflow based on whether a child workflow succeeds or fails.
Last modified on October 27, 2026