Working with PowerShell Script Step Output

Last Updated: 03/28/2018 Introduced in Version:

Overview

When you include a PowerShell Script Step to a Flow in Decisions, the way that the script operates has a large impact on how to handle its output, and what path the flow takes after that Step.

Note: this document refers to features that are available in Decisions v4.0.4 and later.

 

Scripts that Output PowerShell Objects

Some PowerShell Scripts return lists of PowerShell objects, from which Decisions can select the properties you are interested in. An example of this is the Get Process List with Specified Output Properties Script Step that is avilable in the PowerShell Sample Scripts sample. That step retrieves a list of processes running on the Decisions server, and the script definition tells Decisions to select the ID and Process Name properties from the objects that the script returns. Each of these properties appear in the Outputs area of the Step as an array of values. The PowerShell Module Basics page provides details on this sample script.

 

Scripts that Output Text

Other PowerShell scripts return results as text. A simple example of this is the following PowerShell Script:

$Variable = "This is an example of string output."
Return $Variable

Because this PowerShell script does not return an object with properties, there are no properties for Decisions to select, and therefore no need to specify anything in the Outputs area of the Script. When this PowerShell Script is added as a Flow Step, you can access the output of the script in the Edit Input Mappings using the Script Raw Output. It is a single text string containing all of the lines of output that the script generated.

 

Non-terminating Errors

Some commands in PowerShell scripts do not halt script execution when they encounter a problem. They write error messages to a special error stream instead. This output can be mapped from a PowerShell Script Step using the Non-terminating Errors output of the step. This is a separate output stream from the Script Raw Output, and contains all of the errors that any portion of the script wrote. An example script that writes to this output stream is:

$Error_Message = "This is a non-terminating error"
Write-Error $Error_Message
Return

The script above does not return any objects or any Script Raw Output. If a Flow Step is created using it, the Step’s Non-terminating Errors property will contain the error message text when the Flow is run. Because more than one error message can be written, Decisions provides the Non-terminating Errors as an array of strings.

 

PowerShell Script Step Paths

Because PowerShell scripts can run to completion but still generate error messages, Decisions provides multiple paths out of a PowerShell Script Step:

Path Taken When
Done the PowerShell script ran successfully
Done With Errors the PowerShell script completed, and errors were written to the Non-terminating Errors property.
Failed the PowerShell script encountered an error that halted its execution. Instead of any normal output or non-terminating errors, an Exception Details property is provided.

Both the “Done With Errors” and “Failed” paths can be hidden using the Hide Done With Errors Path and Hide Failed Path checkboxes. If the Done With Errors path is hidden, the Done path will be taken instead and the Non-terminating Errors property will contain any errors. If the Failed path is hidden, then the Done path will be taken instead and the Exception Details information is placed in the Script Raw Output property.

Additional Resources