Windows PowerShell Script (Execute)

Use the Task Execute Windows PowerShell Script to execute Microsoft Windows PowerShell scripts on Agents. This effectively allows you to create your own, custom Tasks in Ivanti Automation. Microsoft Windows PowerShell is a command line shell and task-based scripting technology for the automation of a wide range of system administration tasks.

Using Ivanti Automation to handle your Windows PowerShell scripts makes it easy to execute and schedule scripts on many computers (Agents). The same version of the script is executed in the same manner across the entire set of Agents, ensuring consistent results. If the script is run on several Agents, Ivanti Automation presents the outputs in a single Result.

Prerequisites

  • Microsoft Windows PowerShell must be installed on the target computer. It is available as a free download on the Microsoft Download Center.
  • The script is executed with the user profile of the user name provided at Security Context for this Task. The account that is used to execute scripts needs to have "Log on locally" rights. Version 2021.4 adds a Run with elevated privileges option. If the provided credentials are not allowed to run elevated, the tasks will report an impersonation error.

Configuration

Settings tab

  • By default, the PowerShell scripts that you can run using this Task need to be digitally signed. Select Override execution policy for this Task to temporarily lower the PowerShell execution policy to "Unrestricted" and use unsigned PowerShell scripts. After execution of the Task, the PowerShell security will be reverted to the previous security level. This can be useful for example when running the VI Toolkit cmdlet.
  • If you use PowerShell snap-ins, for example to manage your Microsoft Exchange Server 2010 servers, store the console file that identifies the snap-ins (.psc1) as a Resource. Refer to this Resource in the Task, at Use Windows PowerShell Console File under Advanced Settings.
  • In the optional field Grab log file, you can select a text file to be collected from the target machine. This file will be shown as an extra tab in the Job results named Grabbed Log.
  • Depending on the amount of information presented in the output, columns may be very far apart, which makes for awkward reading; or too narrow, so that the information is truncated. Under Advanced Settings, adjust the total width of the Windows PowerShell Console output to obtain wider or narrower columns.
  • In the field Set width of Windows PowerShell console output at, you can specify the width of the Windows PowerShell console (as of 2020.1, the default is 256 bytes, in older versions the default is 16386 bytes). This is useful to prevent data from becoming unreadable. You can use parameters, functions and variables.
  • In the field Timeout Windows PowerShell execution after:, you can specify a maximum number of 9999 minutes (about 166 hours and 40 minutes). You can use parameters, functions and variables.
    • In certain situations, Agents can continue to execute the remaining commands in the script when the timeout expired. You can prevent situations like these by selecting Terminate Windows PowerShell when timeout expires. This exits any active process when the timeout expires.
    • If the use of parameters, functions and/or variables in the fields Set width of Windows PowerShell console output at and Timeout command execution after result in non-numeric values (text) when the Task is executed, the width and timeout will use a fall back value:
      • Set width of Windows PowerShell console output at: Fall back value is 256 bytes.
      • Timeout command execution after: Fall back value is 1 minute.
  • The option Set parameter with exit code allows you place an exit code into a parameter for use in another Task in the Module. For example, suppose you have configured a Module with a Windows PowerShell Script (Execute) Task, and you have another Task that installs certain software. By using the option Set parameter with exit code in the Windows PowerShell Script (Execute) Task, you can use this parameter in a condition in the software installation Task to determine whether the software installation Task should be executed.
  • The option Set parameter with standard output allows you to place the standard output into a parameter, for use in another Task in the Module (e.g. a Query).
  • The options under Task fails/succeeds if the script returns the following exit code allow you to specify numeric exit codes that indicate whether the task fails or succeeds.

Script tab

  • Scripts can be typed in directly. You can use Ivanti Automation functions, Ivanti Automation parameters and environment Variables in scripts. These Variables, functions and parameters will be parsed when the Task is executed.
    • To prevent code injection when using parameters from an untrusted source, use the Get-ResParam Cmdlet to safely pass the data from these parameters.
      Example for the parameter 'MyPassword':
      • For trusted sources, use: $[MyPassword]
      • For untrusted sources, use: Get-ResParam -Name MyPassword
  • Use the File extension of script field to specify the file extension that Ivanti Automation should use. This extension is used to save the script as a script file in the specified format when the Task is executed. Ivanti Automation will save this file in the temporary folder on the Agent that executes the Task.
  • Use the Open in editor button to open an external editor that is associated with the specified file extension in the File extension of script field. This makes it easier to create complex scripts and troubleshoot existing ones. After creating or editing the script, it will be copied from the external editor to the Script tab. If no associated editor can be found, the script will be opened in Notepad. For more information on how to configure file associations, see http://msdn.microsoft.com/en-us/library/windows/desktop/cc144175%28v=vs.85%29.aspx.
    • The Script tab has a limit of 64KB. If you use an external editor to edit a script, Ivanti Automation will disregard any characters that exceed this limit.
  • Any script output is shown in the detailed results per Agent, on a separate tab Console Output. The default output format is format-table.
  • When executing this Task, log files will be generated and included in the detailed Job history. Before the Agent uploads these output log, error log or grabbed log files to the Dispatcher and make them available, the Agent will first compress the file if it has a size less than 100 MB.
    • In the following situations, the compression of that file will not take place. As a result, the file will not be uploaded:
      • The file size cannot be determined
      • The file is empty
      • The file is larger than 100 MB
    • The Job history will report if a file could not be uploaded because the file size could not be determined, or if the file size was larger than 100 MB. Empty files will not be reported. If a file cannot be uploaded, the outcome of the Task is not affected: the Task will still complete successfully, but the log file(s) that were not uploaded are not available in the Console.

To find out more about signing scripts, open Windows PowerShell, type the following, and press ENTER: Get-Help About_Signing.

Multiple returns in PowerShell scripts

Ivanti Automation supports multiple returns when using the “Execute Windows PowerShell Script” task.

You can define multiple parameters for the module containing the PowerShell task and reference them as “$global:<param_name>= <something>”. This allows you to get values for multiple parameters within the same task.

For example:

$global:param1=(get-service | where Name -eq "WinRM").Name

$global:param2=(get-service | where Name -eq "WinRM").Status

The above script places the name of a service and its status into two different parameters (param1 and param2).

After that, the next PowerShell task within the module can do something like the following, providing more options and flexibility:

write-host $[param1]

write-host $[param2]

Keep this mind when using multiple returns:

  • Ivanti Automation applies the ToString method to the parameter and if the value of the PowerShell command returns only one attribute, the parameter will return the attribute value. If the command returns an object (an array or other object), we will return the representation of the object. For example, in the above script if no filtering was applied ("$global:param1=(get-service).Name"), we would return “System.Object[]” in param1.
  • Serialization and deserialization can be used to avoid situations when the PowerShell command returns an object. The serialized object should be placed into the parameter and in the following PowerShell task, the serialized string can be deserialized to get the initial object for further actions (for example, using the “ConvertTo-Json” or “ConvertFrom-Json” PowerShell methods).