Description

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

Quick Info

Product
HCL Launch
Type
plugin
Compatibility
Created by
HCL Software
Website
Version Name Action

9.1025820

launch-powershell-integration-9.1025820.zip

launch-powershell-integration-9.1025820.zip

9.1025820


Summary

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.

Compatibility

This plugin works with PowerShell Version 4.0 and later.

Installation

See Installing plugins in HCL Launch for installing and removing plugins.

History

The following table describes the changes made in each plugin version.

Plugin history details
Version Description
9 Fixed APAR PH12966. Process fails when script doesn\t explicitly call \exit\.

Usage

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.

Step palette

To access this plugin in the palette, click Scripting > PowerShell.

Steps

The following process steps are available in the Powshell plugin.

Run PowerShell Script

Runs a PowerShell script. This step allows for bidirectional passing of script variables and HCL Launch properties.

Input properties for the Run PowerShell Script step
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

Troubleshooting

Errors and solutions

ERROR

FullyQualifiedErrorId : MethodInvocationNotSupportedInConstrainedLanguage

SOLUTION

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

ERROR

PowerShell script execution failed. Error Message: Windows PowerShell is in Non-Interactive mode. Read and Prompt functionality is not available.

SOLUTION

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:

ERROR

PowerShell exits with exit code 1 rather than returning $LASTEXITCODE when last process exit code is >0.

SOLUTION

This is a bug in MS PowerShell and a PS v7.0.0 error. Details and workarounds are found at the following links:

ERROR

System.Management.Automation.ExitException: System error.

SOLUTION

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

ERROR

System error" from invoke command: System.Management.Automation.StopUpstreamCommandsException

SOLUTION

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:

Questions and Answers

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:

  • Insert PowerShell -non-interactive -Additional_Parameters_Here
  • Use the Shell plugin to interact with the command line.

How can I run the script in a multi-threaded apartment model?

Perform the following:

  • Navigate to the hidden properties.
  • Add -MTA to one of the argument properties.

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.