PowerShell

The PowerShell steps support running a PowerShell script and formatting PowerShell objects that are displayed in the Job log file.

PowerShell – Execute PowerShell Script

This job step allows you to execute a PowerShell script. This job step differs greatly from using the PowerShell facilities through the command-line program in that you can pass objects to your script. In addition, your script can pass PowerShell objects downstream to other PowerShell scripts without the limitation of ‘string’ arguments.

Platforms Supported

Windows.

Software Prerequisites

Design and Windows: PowerShell 3.0 (or later)

Job Step Properties

Machine – This property represents the machine(s) you want to run the PowerShell script on. Multiple machines can be specified through comma separation. By default, the script will run on the same machine as the Execution Queue’s machine.

Note: This property is ignored unless the Implicit Remote property is set to true. In addition, you must specify the additional properties in the “Imported Command” collection. In particular, the “Commands to Import” and “Allow Clobber”. If the additional properties are not specified then the contents of this property are ignored and the commands will be executed on the local execution machine. In addition, you may need to enable RemoteSigned Execution Policy for both the execution and target machine(s) as well as enabling PowerShell Remoting (enable-psremoting –force) and the WinRM service.

Script – This property represents the contents of the PowerShell script itself.

If you wish that the entire script action is executed on the remote machine, use the script below as an example:

$s = New-PSSession -ComputerName "SERVER.DOMAIN"

Invoke-Command -Session $s -ScriptBlock {Invoke-Expression "Set-Location D:\FilePath;D:\FilePath\Test.exe"}

Implicit Remote = False

InputObject – This property represents an object that you would like to pass to the PowerShell script. The object can be a single object or contain a collection of objects.

InputObjects – This collection of properties represents any objects that you would like to pass to the script. Simply use the “Add” button to add one or more objects that you want to pass as an input collection to the script.

Implicit Remote – This Boolean property indicates whether you want to enable Implicit Remoting and the Machine property. If enabled, you must also specify what Commands to Import as well as any other applicable properties.

Imported Command Properties – This collection of properties represents the desired attributes when Implicit Remote is enabled and importing commands.

Commands to Import represents one or more commands that should be imported from the remote machine(s). Multiple commands are comma delimited and wildcards are supported.

Imported Command Prefix, if specified, appends a prefix to each command that is being retrieved. This avoids clobbering existing commands.

Allow Clobber is a Boolean property that if enabled allows the same named commands that exist on this machine to be overwritten by the implicit remote commands. If false, the commands are not retrieved.

Powershell Console File – This property, if specified, represents a path to a Powershell console file that contains custom Powershell snap-ins.

Format Output Objects – This Boolean property indicates whether any output objects should be formatted. If ‘True’ the objects are formatted and the data will appear in the job’s log file. If ‘False’ the objects are not formatted.

No profile – This Boolean property controls whether a user’s Powershell profile will be executed prior to the Powershell script itself. A value of true indicates that the user profile script should not be executed. A value of false indicates that the user’s profile (if one exists) should be executed. Please note that this property may be overridden by the Powershell Machine Execution Policy that is in effect.

Display Objects Immediately – This Boolean property indicates whether any returned objects should be displayed in the Job’s Log file. If True, they are; if False (default), they aren’t.

Return Value Type – This dropdown indicates the type of object returned as part of the Return Value. By default, the BaseObject is returned. You can select PsObject which includes the BaseObject as well as other information normally returned by Powershell.

Return Step Value

If your script returns any output objects they will be accessible through step-name.ReturnValue.

The above job step "Step2", in conjunction with the earlier "Step1" image, shows how objects can be passed from one script to another. Note $input is piped to the cmdlet “Format-Table”. The actual objects are retrieved through the execution variable “Step1.ReturnValue” (note that no string substitution syntax is used; we want the objects themselves). Finally the “Format Output Objects” property is set to True so the objects are formatted for display.

This job step utilizes PSObject as the return value type instead. PSObject is normally returned by Powershell. To complement the example using $input the equivalent for PSObject is $input[0].Status.

Note: InputObject and InputObjects are related in that both properties represent an input to the Powershell script. InputObject is the more flexible of the two. InputObject can represent a single object or a collection of objects. InputObjects can only represent a collection of objects. Depending on your usage you may find one of these “inputs” more useful than the other. Please note that only one can be specified. If both are specified, InputObject will be used.

Note: PowerShell supports the concept of terminating and non-terminating errors. This means that a script may “fail” but if the error is non-terminating the exit code will be of success. PowerShell does provide a mechanism for treating non-terminating errors as terminating, for example, -ErrorAction Stop.

Spotted a typo or can’t find help on a certain subject? Reach out to the Documentation team at docsupport@redwood.com.