Build a sub-workflow

Latest Dynatrace
How-to guide
6-min read
Published Aug 03, 2026

A sub-workflow is not a separate workflow type you configure at creation time — it's a role a workflow takes on when another workflow references it using the Run workflow action. Any live standard workflow can be used as a sub-workflow.

The workflow's input and result configuration defines the interface:

Workflow input: Specifies what data the calling workflow can pass in. Inside the sub-workflow, tasks access this data using the input() expression.
Workflow result: Specifies what the Run workflow task returns to the calling workflow as its result.

Simple workflows cannot act as sub-workflows. The Run workflow action only lists deployed, standard workflows.

When to use sub-workflows

Reusable workflow logic: Extract a set of tasks into a standalone workflow that multiple parent workflows can call. You maintain the logic in one place. Common examples are notification routing workflows or shared entity-lookup steps.

Long-running operations: Each action in Dynatrace runs in the serverless runtime, which enforces a 120-second execution limit per action. A sub-workflow runs as a separate workflow execution with its own task timeout, configurable up to 7 days. Use it for operations that take longer than that limit, such as polling an external API until an asynchronous task completes.

Prepare the sub-workflow input

Before building a sub-workflow, define what data it needs from the caller and what it should return.

Open or create the workflow you want to use as a sub-workflow.
In the workflow editor, open Options.
Under Workflow input, define the expected input as a JSON object. These are the defaults; the calling workflow can override or extend individual fields at call time.
Under Workflow result, define a Jinja expression that evaluates to a JSON object. This is what the Run workflow task returns as its result.
Deploy the workflow so it appears in the Run workflow action's selection list.

Call a workflow as a sub-workflow

In the calling workflow, add a task and select the Run workflow action.
In Run Workflow, select the target workflow from the drop-down list.
In Input, provide the JSON input to pass. This is merged with the sub-workflow's default input — you only need to supply fields you want to override or that have no defaults.

For the full reference on available options and restrictions, see Run workflow action.

Trigger-and-poll pattern

Some external APIs follow an asynchronous pattern; you submit a request to start an operation and then poll a status endpoint until the operation finishes. If polling runs for more than 120 seconds, this won't fit in a single action execution.

Encapsulate the entire operation—triggering it and polling until it completes–inside a single sub-workflow, instead. The calling workflow only needs to know the operation parameters; the two-phase protocol of the external API stays inside the sub-workflow.

Build the trigger-and-poll sub-workflow

Create a new standard workflow. Set its trigger to On demand—the main workflow starts it explicitly via the Run workflow action.
Under Workflow input, define the query or request body that describes what the async operation should do, for example:
```
{ "query": "" }
```

Add a first Run JavaScript task that submits the request to the external API. Use the SDK to read the query from the workflow input and return the job identifier for the polling task:

import { execution } from '@dynatrace-sdk/automation-utils';

const ex = await execution();
const { query } = await ex.input();
const job = await submitQuery(query);
return { jobId: job.id };

Add a second task that polls the results endpoint. Configure the polling task so that it results in error state when the results are not yet ready — this is what the retry mechanism hooks into. With a Run JavaScript task, use the @dynatrace-sdk/automation-utils SDK to read the job identifier from the previous task's result, then throw an error while the job is still running and return the result payload once it's complete:
```
import { execution } from '@dynatrace-sdk/automation-utils';

const ex = await execution();
const { jobId } = await ex.result('submit_query');
const job = await fetchJobResult(jobId);
if (job.status !== 'COMPLETED') throw new Error(`Job not ready: ${job.status}`);
return job.result;
```
In the polling task's Options, enable Retry on error with a retry count and delay that together cover your expected maximum operation duration. You can also enable Wait before to delay the very first poll attempt if the job needs time to start.
Under Workflow result, expose the result payload from the polling task so that callers receive the data directly:
```
{{ result("fetch_results") | to_json }}
```
Deploy the sub-workflow.

Wire up the main workflow

Add a Run workflow task and select the trigger-and-poll sub-workflow.
In Input, pass the query that defines the async operation:
```
{ "query": "fetch logs | filter ..." }
```
In the task's Options, open Adapt timeout and set a timeout that matches the maximum expected operation duration.
Downstream tasks receive the result payload directly via {{ result("task_name") }} (using the actual task name you set)—no status fields, just the data.

Monitoring

Sub-workflow executions are tracked as separate workflow executions and are linked to their parent from both directions. For details on navigating between parent and sub-workflow executions in the execution monitor and filtering the execution list, see Monitor sub-workflow executions.

See where a workflow is used as a sub-workflow

The editor displays a hint when a workflow is used as a sub-workflow in another workflow.

Select Used as sub-workflow > See all affected workflows to see the details. Only workflows that are available to you are displayed. Private ones aren't visible in the list.
If you delete a workflow that is used as a sub-workflow, you're presented with a list of the affected calling workflows to judge the impact of the deletion.