PowerShell Core Script (Execute)

Use the Task Execute PowerShell Core Script (versions 2020.3 and newer) to execute Microsoft PowerShell Core scripts on Agents. This effectively allows you to create your own, custom Tasks in Ivanti Automation. Microsoft PowerShell Core 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 PowerShell Core 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 .NET Core Desktop Runtime 3.1 or newer must be installed on Agents.
  • The Automation agent includes the Microsoft PowerShell Core components it uses, so PowerShell Core does not need to be installed separately on Agents.
  • The PowerShell Core 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 PowerShell Core scripts needs to have "Log on locally" rights.
  • Ivanti Automation 2021.1 adds Linux Agent support for Microsoft PowerShell Core 7 script execution on these platforms:

    • Ubuntu 20.04 x86_64

    • Ubuntu 18.04 x86_64

    • Ubuntu 16.04 x86_64

    • CentOS 8 x86_64

    • CentOS 7 x86_64

    • Red Hat Enterprise Linux (RHEL) 8 x86_64

    • Red Hat Enterprise Linux (RHEL) 7 x86_64

    • SUSE 15 x86_64

    • SUSE 12 x86_64

    • MacOS (support added in 2021.2, also requires .Net Core 3.1 or newer)

Configuration

Settings tab

  • 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.
  • By default, the PowerShell Core 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 Core execution policy to "Unrestricted" and use unsigned PowerShell Core scripts. After execution of the Task, the PowerShell Core 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 Core 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 PowerShell Core 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 PowerShell Core Console output to obtain wider or narrower columns.
  • In the field Set width of PowerShell Core console output at, you can specify the width of the PowerShell Core console (the default is 256 bytes). This is useful to prevent data from becoming unreadable. You can use parameters, functions and variables.
  • In the field Timeout PowerShell Core 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 PowerShell Core 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 PowerShell Core 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 PowerShell Core 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 PowerShell Core Script (Execute) Task, and you have another Task that installs certain software. By using the option Set parameter with exit code in the PowerShell Core 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 PowerShell Core, type the following, and press ENTER: Get-Help About_Signing.

Multiple returns in PowerShell Core scripts

You can define multiple parameters for the module containing the PowerShell Core 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 Core 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 Core 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 Core command returns an object. The serialized object should be placed into the parameter and in the following PowerShell Core 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 Core methods).