The PowerShell plug-in provides a step for running user-defined PowerShell scripts. The following features are included in the initial release: PowerShell script text box Bidirectional passing of script variables and HCL Launch parameters Custom exit status handling User-specified session parameters
The PowerShell plugin provides a step for running user-defined PowerShell scripts.
This plugin includes one or more steps, click Steps for step details and properties.
This plugin works with PowerShell Version 4.0 and later.
See Installing plugins in HCL Launch for installing and removing plugins.
The following table describes the changes made in each plugin version.
| Version | Description |
|---|---|
| 9 | Fixed APAR PH12966. Process fails when script doesn\t explicitly call \exit\. |
Download the plugin and extract the .zip file. A tutorial is available in the form of an example process in the imports/process/PowerShell+Example.json file. To see the tutorial content, import the example process.
To access this plugin in the palette, click Scripting > PowerShell.
The following process steps are available in the Powshell plugin.
Runs a PowerShell script. This step allows for bidirectional passing of script variables and HCL Launch properties.
| Name | Type | Description | Required |
|---|---|---|---|
| Command Line Options | String | Command-line options for the PowerShell session. Changing command-line arguments can affect plugin functionality. The -File parameter is reserved. The -Command parameter is reserved if the value is a string. See Microsoft documentation for further details. | No |
| PowerShell Home | String | If the PowerShell command is in the system path, specify the PowerShell command name. Otherwise, specify the full path to the PowerShell command. | Yes |
| PowerShell Script | String | Accepts any PowerShell syntax. The prefix _IBMUCD is reserved for internal use; all methods and variables with this prefix are subject to change. Use dot source notation to call a script from a file. For example: . C:/HelloWorld.ps1. Use the standard notation for input properties. For example: $YourVar=${p?:deployProperty}. Use the command Set-StepOutputProperty to set an output property. For Example: Set-StepOutputProperty OutputPropName OutputPropValue. | Yes |
FullyQualifiedErrorId : MethodInvocationNotSupportedInConstrainedLanguage
This issue is caused by a new policy update to the Windows defender application control (WDAC) Windows GPO. It resulted in PowerShell on the agent servers to run in ConstrainedLanguage mode, causing the error. To enable full language support, refer to the following link: https://stackoverflow.com/questions/57032747/how-to-change-powershell-mode-to-fulllanguage-mode-from-constrained-mode
PowerShell script execution failed. Error Message: Windows PowerShell is in Non-Interactive mode. Read and Prompt functionality is not available.
When scripts are run in non-interactive mode, Stop-Process requires the -Force option to make it non-interactive even if -Confirm:$false is set. Change the line of your script to: Stop-Process -Name $process -Force
For additional assistance on this issue, refer to the following links:
PowerShell exits with exit code 1 rather than returning $LASTEXITCODE when last process exit code is >0.
This is a bug in MS PowerShell and a PS v7.0.0 error. Details and workarounds are found at the following links:
System.Management.Automation.ExitException: System error.
This is a PS script error. Solutions are found at the following link: https://stackoverflow.com/questions/42481761/system-management-automation-exitexception-system-error-in-powershell-studio
System error" from invoke command: System.Management.Automation.StopUpstreamCommandsException
This is a MS PowerShell error and caused because Script is wrapped in the Invoke-Command. This is a PS v6.1.3 error and resolved in a later version. This issue was resolved in #10840 and released as the version 7.0.0 and previewed at the following link: https://github.com/PowerShell/PowerShell/pull/10840.
Details and workarounds are found at the following links:
Why does the plugin step succeed when the PowerShell script exits with a -128 error status?
The plug-in is configured by default to accept a -128 status as success. By default, PowerShell exits with a 0 error status even if the script fails, so using 0 results in false positives. If the -128 status overlaps with a custom error status that is used in your script, change the error status in the hidden properties.
How can I pass the -file parameter?
Use one of the following options:
Summary
Usage
Steps
Troubleshooting
PowerShell -non-interactive -Additional_Parameters_HereHow can I run the script in a multi-threaded apartment model?
Perform the following:
Why is script output not displayed in the HCL Launch log?
The HCL Launch log stores all PowerShell output. You may need to change the PowerShell output preferences. To learn more, refer to the Microsoft documentation here: https://technet.microsoft.com/en-us/library/hh847796.aspx.
