> For the complete documentation index, see [llms.txt](https://docs.devolutions.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.devolutions.net/powershell-universal/automation/workflows.md).

# Workflows

Chain scripts and AI prompts into multi-step PowerShell Universal workflows using the Workflow and PSUItem variables to pass data between activities.

> This feature requires a [license](/powershell-universal/licensing.md).

PowerShell Universal workflows chain scripts and AI prompts into a single automation flow. Use workflows to pass data between steps, route execution based on a result, run independent work concurrently, and schedule the resulting process. Workflow runs create jobs that you can monitor in the standard job history.

## Create a workflow

1. Go to **Build > Workflows** and select **Create Workflow**.
2. Enter a name and optional description.
3. Add workflow parameters when callers must supply values such as an environment, approval target, or retention period.
4. Save the workflow, then open it to use the **Workflow Designer**.

Parameters have a name, default value, required setting, and help text. They are prompted for when the workflow is run manually and are available to workflow expressions.

## Build the workflow

The designer has an activity palette, a sequence canvas, and a properties pane.

1. Add an activity by dragging it from the palette to a canvas drop zone, or select the **plus** button beside the activity to append it to the sequence.
2. Select an activity to configure its properties in the right-hand pane.
3. Drag activities in the sequence to reorder them.
4. Select **Save Workflow** after making changes.

Script activities expose the PowerShell parameters defined on their target script. Provide a literal value or select **PowerShell** for an expression that is evaluated at runtime. AI prompt activities let you select an AI agent and provide the prompt to run.

## Decision branches

Use a **Decision** activity to create a True and False branch. This is useful for approval flows, validation checks, and handling a prior job result.

1. Add **Decision** from the activity palette.
2. Enter a PowerShell condition that returns `$true` or `$false`. If you leave it empty, the decision evaluates the first output item from the previous activity.
3. Use **Add activity** in each True or False lane to define the work for that outcome.
4. Add any subsequent activities after the Decision; each completed branch continues to the next activity in the main workflow.

For example, a script can return whether a deployment is approved. The Decision can use the default previous-output condition, or use an explicit expression such as:

```powershell
$Workflow.Environment -eq 'Production' -and $PreviousActivity.Status -eq 'Completed'
```

`$PreviousActivity` contains the prior activity's ID, type, name, job ID, status, start and end times, and pipeline output. Use it when the branch condition needs job metadata as well as its output.

## Run activities in parallel

Use a **Parallel** activity when independent script or AI prompt activities can run at the same time.

1. Add **Parallel** from the activity palette.
2. Select **Add activity** in the Parallel activity and add each child activity that can run independently.
3. Configure each child activity as usual.
4. Continue the main workflow after the Parallel activity completes.

PowerShell Universal starts the eligible child jobs concurrently and waits for them all to finish. If an AI prompt fails, or a script child is configured to fail on script error and finishes in a failed, error, or timed-out state, the Parallel activity fails.

## Pass data between activities

Workflow expressions are evaluated at runtime and can use these variables:

| Variable            | Use                                                                                                                                        |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `$Workflow`         | Workflow parameter values supplied when the run starts.                                                                                    |
| `$PSUItem`          | The raw pipeline output from the previous activity. A target script receives it automatically only when it declares a `PSUItem` parameter. |
| `$Output`           | Named values produced by a previous script that returned one hashtable.                                                                    |
| `$PreviousActivity` | Metadata and output for the immediately preceding activity.                                                                                |

For example, pass a workflow parameter to a script activity property:

```powershell
$Workflow.Environment
```

To deconstruct output, have a script return exactly one hashtable:

```powershell
@{
    Server = 'web01'
    Port = 443
}
```

With **Deconstruct Hashtable Output** enabled (the default), downstream PowerShell expressions can use the named values:

```powershell
$Output.Server
```

If the script returns multiple objects, or the single object is not a hashtable, use `$PSUItem` to work with the previous activity output instead.

## Run and schedule workflows

Select the **Play** icon in **Build > Workflows** to run a workflow on demand. PowerShell Universal prompts for any configured parameters, then opens the resulting workflow job.

Create a workflow schedule from the workflow's **Schedules** tab or from **Run > Schedules**. Workflows support simple, cron, continuous, and one-time schedules. Set the same run options available for scheduled automation, including execution environment, credential, and computer settings.

Use `Invoke-PSUWorkflow` to start a workflow from PowerShell or other PowerShell Universal automation. You can provide parameter values when invoking it.

## Manage workflows as configuration

When workflows are maintained in a configuration repository, use the configuration file explorer's **Refresh Configuration > Workflows** action to synchronize updated workflow definitions without restarting PowerShell Universal.

The Universal module also provides `Get-PSUWorkflow`, `New-PSUWorkflow`, `Set-PSUWorkflow`, `Remove-PSUWorkflow`, `New-PSUWorkflowParameter`, `New-PSUWorkflowActivity`, and `Invoke-PSUWorkflow` for configuration and automation scenarios.

## Monitor and troubleshoot runs

Open the workflow job from **Build > Workflows** to review its status, streams, pipeline output, and errors. Child script and AI jobs are associated with the workflow run, which makes it easier to identify the activity that failed.

When troubleshooting, verify that script parameter names match the target script metadata, use an expression rather than a literal for values that must be evaluated at runtime, and remember that the first activity has no previous output.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.devolutions.net/powershell-universal/automation/workflows.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.