Introduction

• PowerShell is a frequently used scripting language available for Linux, MacOS, Windows and other platforms.
• JS7 offers the JS7 - PowerShell Module for simplified access to the JS7 - REST Web Service API
• This article explains some common ways of handling run-time errors in PowerShell job scripts.

Scenario

• The examples below use a common scenario to raise a run-time error:
  • a workflow is assigned a lookup_path variable that specifies a directory which is tested in a later job to see whether or not it exists.
  • the PowerShelll Test-Path cmdlet is used to test for the existence of the directory. The functioning of the cmdlet is that:
    • it returns $True if the directory exists and $False if it does not exist,
    • it raises an exception if the cmdlet parameter for the directory includes a $Null value.
• In a perfect world script developers would check if a variable holds a null value before even using it. However, this world is far from being perfect. In addition, the script code required to perfectly check variables for null values would exceed by far the amount of code required for the effective processing of business logic. As a result, hardly anybody implements such checks.
• The examples below can be executed by adding an order, for example from the JOC Cockpit Workflows view in two variants:
  • add the order without modification of the lookup_path variable: the example will run without error,
  • add the order and modify the value of the lookup_path variable to an empty string: an error will be raised:
    
    x

PowerShell Profiles

PowerShell profiles can be used to modify defaults available with PowerShell.

• A PowerShell profile will be used if available from one of the locations provided by the platform (Windows, Linux, MacOS etc., please check applicability of profiles for your platform).
• You can examine the global $PROFILE variable to verify applicable profile locations:
  • PS C:\> $PROFILE | Get-Member

  • Profile locations typically are applied from the following properties in descending order. This means that all profiles from aall locations are applied if available.

    • $PROFILE.AllUsersAllHosts
    • $PROFILE.AllUsersCurrentHost
    • $PROFILE.CurrentUserAllHosts
    • $PROFILE.CurrentUserCurrentHost
• By default JS7 does not make use of a specific PowerShell profile, instead the above order of available profiles applies.

No Error Handling

This situation boils down to defaults available with PowerShell.

• Built-in defaults of PowerShell apply.
• Defaults that are modified by a PowerShell profile.

Continue Processing in case of Errors

The global $ErrorActionPreference variable makes use of the default value continue. As a result:

• the job script reports error messages to the stderr channel,
• the job script continues to run after being hit by an error.

This is the most undesirable scenario as it implies that the PowerShell script:

• continues and might perform very bad things, for example if a cmdlet such as Remove-Item -Path /$env:LOOKUP_PATH -Recurse would be used with $env:LOOKUP_PATH evaluating to null.
• completes with an exit code 0 signaling success if the last cmdlet executed with the script was successful. JS7 cannot know that an error occurred and users will not be notified.

Download the example below  (.json upload): pdErrorPowerShell_01_No_Handling_Continue.json

#!/usr/bin/env pwsh

$lookupPath = $env:LOOKUP_PATH
if ( !$lookupPath )
{
  $lookupPath = $null
}

If ( Test-Path -Path $lookupPath -PathType container )
{
	Write-Host "path found: $env:LOOKUP_PATH"
} else {
	Write-Host "path not found: $env:LOOKUP_PATH"
}

Stop Processing in case of Errors

The global $ErrorActionPreference variable in this example is set to the value stop. As a result:

• the job script reports error messages to the stderr channel,
• the job script stops immediately after being hit by an error.

This is a somewhat acceptable scenario as it prevents the PowerShell script from continuing and it raises an exception that is recognized by JS7 and which will fail the job.

Download the example below  (.json upload): pdErrorPowerShell_01_No_Handling_Stop.json

#!/usr/bin/env pwsh

# global setting: stop execution in case of errors
$ErrorActionPreference = "stop"

$lookupPath = $env:LOOKUP_PATH
if ( !$lookupPath )
{
  $lookupPath = $null
}

If ( Test-Path -Path $lookupPath -PathType container )
{
	Write-Host "path found: $env:LOOKUP_PATH"
} else {
	Write-Host "path not found: $env:LOOKUP_PATH"
}

Error Handling

This situation boils down to defaults available with PowerShell and to the handling of errors with jobs.

• Built-in defaults of PowerShell apply.
• Defaults that are modified by a PowerShell profile.
• Error detection by JS7, returning exit codes and controlling exceptions.

Use Error Detection by JS7

The global $ErrorActionPreference variable can have any value. For reasons explained above it is recommended that the variable is set to the value stop.

In addition, JS7 error detection is activated: any output to the stderr channel is considered to signal that the job has failed. This is achieved by using the relevant setting in the "Job Options" tab of the property editor in the JOC Cockpit Workflows view:

As a result:

• the job script can report errors by using the Write-Error cmdlet,

• the global $ErrorActionPreference variable determines if processing is to be stopped or continued,
• errors are reported and notified by JS7.

Download the example below (.json upload): pdErrorPowerShell_02_WriteError.json

#!/usr/bin/env pwsh

# use of Write-Error cmdlet
# consider the job options to fail if output to stderr is detected

$lookupPath = $env:LOOKUP_PATH
if ( !$lookupPath )
{
  Write-Error "empty lookup path not accepted"
}

if ( Test-Path -Path $lookupPath -PathType container -ErrorAction stop )
{
	Write-Host "path found: $env:LOOKUP_PATH"
} else {
	Write-Host "path not found: $env:LOOKUP_PATH"
}

Set Exit Code

Setting a non-zero exit code in a PowerShell script performs two operations:

• it stops processing of the script,
• it forwards the exit code to JS7.

This works independently of:

• setting the global $ErrorActionPreference variable to a specific value and
• error detection from the stderr channel by JS7.

Download the example below  (.json upload): pdErrorPowerShell_03_Exit.json

#!/usr/bin/env pwsh

# use of Write-Error cmdlet
# exit script with an exit code 

$lookupPath = $env:LOOKUP_PATH
if ( !$lookupPath )
{
  Write-Host "empty lookup path not accepted"
  Exit(12)
}

if ( Test-Path -Path $lookupPath -PathType container -ErrorAction stop )
{
	Write-Host "path found: $env:LOOKUP_PATH"
} else {
	Write-Host "path not found: $env:LOOKUP_PATH"
}

Control Exceptions with Try/Catch

Use of the PowerShell Try/Catch instructions offers full control of error handling in case of errors:

• it stops processing of commands in the Try block,
• it allows handling of errors in the Catch block that should not prevent further execution of the script,
• it allows handling of errors in the Catch block which prevent further execution of the script, e.g. by use of the Write-Error cmdlet that raises an exception which is forwarded to JS7.

This works independently of:

• setting the $ErrorActionPreference variable to a specific value and
• error detection from the stderr channel by JS7.

Download the example below  (.json upload): pdErrorPowerShell_04_Try_Catch.json

#!/usr/bin/env pwsh

$lookupPath = $env:LOOKUP_PATH
if ( !$lookupPath )
{
  $lookupPath = $null
}

try {
	If ( Test-Path -Path $lookupPath -PathType container )
	{
		Write-Host "path found: $env:LOOKUP_PATH"
	} else {
		Write-Host "path not found: $env:LOOKUP_PATH"
	}
} catch {
    $message = $_.Exception | Format-List -Force | Out-String
    Write-Error "error occurred: $message"
}

Further Resources

• JS7 - How to run PowerShell scripts from jobs