Plug-in Documentation

PowerShell

Overview

The PowerShell plug-in provides a step for running user-defined PowerShell scripts.

To add the PowerShell plug-in steps to processes, click Scripting > PowerShell in the step palette of the process editor.

Compatibility

The IBM UrbanCode Deploy automation plug-in for PowerShell works with PowerShell Version 4.0 and later.

This plug-in requires version 6.1.1 or later of IBM UrbanCode Deploy.

Installation

No special steps are required for installation. See Installing plug-ins in UrbanCode Deploy.

History

Version 9

  • Fixed APAR PH12966 Process fails when script doesn\t explicitly call \exit\.

Version 8

  • Fixed APAR PH01425 Exit command failing the plugin step.

Version 7

  • Updated copyright.

Version 6

  • Fixed APAR PI93408 Set-StepOutputProperties being overwritten by Groovy output properties.

Version 5

  • Fixed successful exit status to allow plugin step to succeed in post-processing.

Version 4.770502

Version 4 of the plug-in includes the following features:

  • Options and PowerShell Home properties are no longer hidden.
  • Improved help descriptions.
  • Added generic process example.

Version 3.756775

The initial non-beta release of the plug-in. If you are a beta tester, reinstall the plug-in.

  • Removed default verbose output for script. Use PowerShell preference variables in your script to control output.
  • Removed the tutorial.
  • Removed the argument fields.
  • Added Options field to set PowerShell command arguments at script start.
  • Set-StepOutputProperty command is now used as the de facto way to set an output property.

Version 2.741854

The following features are included in second beta release of the plug-in:

  • Default logging for scripts
  • Improved help descriptions
  • Tutorial uncommented and improved

Steps

Process steps in the Powershell Integration plug-in

Run PowerShell Script

Runs a PowerShell script. This step allows for bidirectional passing of script variables
and UrbanCode Deploy 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 plug-in 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 UrbanCode 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

Why does the plug-in 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 plug-in to interact with the command line.

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

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

Why is script output not displayed in the IBM UrbanCode Deploy log?

The IBM UrbanCode Deploy log stores all PowerShell output. You might need to change the PowerShell output preferences. To learn more, see the Microsoft documentation here: https://technet.microsoft.com/en-us/library/hh847796.aspx.

Usage

Download the plug-in 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.