Run PowerShell Script

Audience: Software Developers

Skill Prerequisites: Actions, Tokens, PowerShell

Runs PowerShell code that you type into the action, using Windows PowerShell on the server. Tokens in the code are replaced before it runs. What the script outputs can be saved in a token for the next actions.

note

This action requires the Scripting feature to be licensed.

Typical Use Cases

• Read information from the server, such as free disk space, a Windows service's status or the application pool's identity
• Do small file or folder jobs that the file actions don't cover
• Transform text or data with PowerShell, for example parsing or reformatting a value before saving it
• Try out a command quickly while building an application

Don't use it to

• Run a program or a batch file. Use Run Executable in an Automation job.
• Run SQL. Use Run SQL Query.
• Call a web service. Use Server Request.

Related Actions

Action Name	Description
Run Executable	Runs a program on the server (Automation jobs only).
Execute Javascript (Server)	Runs JavaScript on the server.
Execute Actions	Catches errors from the script with its On Error actions.

Input Parameter Reference

Parameter	Description	Supports Tokens	Default	Required
Script	The PowerShell code to run. For example, [System.Security.Principal.WindowsIdentity]::GetCurrent().Name returns the name of the account the application pool runs as. If it's empty, the action does nothing.	Yes	empty string	Yes

Output Parameters Reference

Parameter	Description
Output Token Name	The name of the token that stores the script's output. Enter it without brackets, for example DiskInfo, then use [DiskInfo] in the next actions.

What's captured

The token gets everything the script sends to its output: values returned by commands, values written with Write-Output, and plain values on their own line. It's converted to text the same way PowerShell displays it in a console (with Out-String), so objects appear as formatted tables or lists.

Other streams aren't captured. Text from Write-Host, Write-Information, Write-Warning, Write-Verbose and Write-Error doesn't end up in the token.

How errors are handled

• Errors that stop the script, such as throw or a syntax error, make the action fail. The actions after it don't run, unless it's inside an Execute Actions with On Error actions.
• Errors that don't stop the script, such as Write-Error or a command that fails for one item, are ignored. The script keeps running and the action succeeds.

To make a command's error stop the script, add -ErrorAction Stop to the command, or put $ErrorActionPreference = 'Stop' at the top of the script.

Considerations

• The script runs on the web server, inside the web server process and with the permissions of its account (usually the IIS application pool identity). It can read and change anything that account can reach. Only people you trust with the server should be able to edit this action.
• Never put user input straight into the script. Tokens are replaced before the script runs, so a token's value becomes part of the code. A value such as '; Remove-Item C:\Data -Recurse; ' could run as a command. Validate or escape values first.
• Square brackets are also PowerShell syntax. Type names like [string] or [System.IO.File] are used by PowerShell. Avoid giving your tokens names that match the type names in your script.
• The action waits for the script to finish. A slow script keeps the form, API call or workflow waiting. For long work, run it from an Automation job.
• Each run starts fresh. Variables and imported modules aren't kept between runs.
• Use absolute paths. The current folder is the web server's, not your site's root folder.

Examples

tip

To understand how to use the below examples, please see Running Examples.

1. Find out which account the application runs as

This action saves the Windows account of the application pool in the AppPoolIdentity token. It's useful when you need to grant that account access to a folder or a database.

{
    "Title": "Run PowerShell Script",
    "ActionType": "RunPowerShellScript",
    "Description": "Get the application pool identity",
    "Condition": null,
    "Parameters": {
        "Script": "[System.Security.Principal.WindowsIdentity]::GetCurrent().Name",
        "OutputTokenName": "AppPoolIdentity"
    }
}

2. Get the free space on the C: drive

This action saves the free space on drive C:, in gigabytes, in the FreeSpaceGB token. A later action can compare it with a limit and send an alert. -ErrorAction Stop makes the action fail if the drive can't be read.

{
    "Title": "Run PowerShell Script",
    "ActionType": "RunPowerShellScript",
    "Description": "Get free disk space",
    "Condition": null,
    "Parameters": {
        "Script": "$drive = Get-PSDrive -Name C -ErrorAction Stop\n($drive.Free / 1GB).ToString('0.0')",
        "OutputTokenName": "FreeSpaceGB"
    }
}

The output text ends with a line break. Trim it before comparing it or saving it, if needed.

Revised 09/26/2026