Scope
- JobScheduler supports PowerShell for implementation of jobs, see - JS-1595Getting issue details... STATUS
- The support for PowerShell fills the gap between Shell jobs and API jobs:.
- PowerShell jobs can use any Windows commands or PowerShell cmdlets and functions.
- PowerShell jobs can use the objects and methods of the JobScheduler API for PowerShell.
- Some minor differences exist between classic Shell jobs and PowerShell jobs, see Compatibility between PowerShell and Shell.
- PowerShell jobs are executed with Agents, not with a JobScheduler Master.
Background
- From the early days of JobScheduler the distinction between Shell jobs and API jobs was introduced:
- Shell jobs include whatever can be executed from the command line of the respective shell (Unix or Windows)
- API jobs are coded in a programming/scripting language. JobScheduler exposes its API to supported languages.
- With PowerShell jobs such differences are leveled in a way that PowerShell jobs can include
- commands such as
- any calls to Windows commands and programs
- any PowerShell cmdlets
- any calls to .NET classes
- callback functions such as
spooler_init(), spooler_open(), spooler_process(), spooler_close(), spooler_exit() as known from API jobs:
- without a callback function being specified script code is automatically executed within the scope of a
spooler_process()
callback function.
- without a callback function being specified script code is automatically executed within the scope of a
- commands such as
- At the time of writing performance penalties are obseved for PowerShell jobs due to loading the .NET Framework for the PowerShell run-tme:
- the delay for PowerShell jobs starting compared to Shell job is about 1-2s. The effective delay depends on the users system performance.
- this delay corresponds more or less to the time required to execute
PowerShell.exe
from the command line.
Feature Availability
FEATURE AVAILABILITY STARTING FROM RELEASE 1.10.5
Examples
Example: PowerShell Job
Example: A simple PowerShell job with some scripting similar to shell jobs might look like this:
Example: A basic PowerShell job including the call to a function might look like this:
Example: PowerShell API Job
A basic API job might look like this:
Example: Combine both PowerShell Job and Monitor
This PowerShell job implements a pre-processing Monitor script that is executed before the job script is executed:
Explanations
- The monitor script is executed before a task is started for this job.
- Its purpose is to decide if the task should be started or not. This decision is taken from the existence of the file
/tmp/go.txt
. - The return code reflects the decision to start or not to start a task for the job.
Example: PowerShell Job with different output channels
The following job explains how to use output channels for PowerShell such as:
Explanations
- Using PowerShell standard output
- Use of the
Write-Output
andEcho
cmdlets is applicable. - Use of the
Write-Host
cmdlet is not applicable for PowerShell jobs as the cmdlet requires a PowerShell host console to be available (powershell.exe
), whereas JobScheduler runs PowerShell in a process without interaction.
- Use of the
- Using PowerShell verbose output
- The standard PowerShell verbosity setting is considered for log output
- Use
$VerbosePreference = "Continue"
- Subsequently use the
Write-Verbose
cmdlet.
- Using PowerShell debug messages
- The PowerShell debug setting is considered for log output in jobs by use of
$DebugPreference = "Continue"
- In addition, the current log level of the job has to be set, e.g. log level
debug1
will log debug messages.- With the JobScheduler log level being switched to
info
no debug output is written to the log file. - With the JobScheduler log level being switched to
debug1
,debug2
, ...,debug9
then debug output is added to the log.
- With the JobScheduler log level being switched to
- The PowerShell debug setting is considered for log output in jobs by use of
- Using PowerShell Warnings
- Warnings are created by use of the
Write-Warning
cmdlet. Such warnings create corresponding warnings in the JobScheduler Master that are visible from the log and that might trigger a notification by mail.
- Warnings are created by use of the
- Using PowerShell Error Messages
- Use of the
Write-Error
cmdlet will create a job error that is visible from the log and that triggers subsequent actions as e.g. notification by mail, stopping the job, suspending an order etc.
- Use of the
JobScheduler PowerShell CLI for Jobs
- The feature is only available in case your Agent is running on a machine with PowerShell available
- For more information about how to install and to use the JobScheduler PowerShell CLI module for an Agent see PowerShell Command Line Interface - Introduction
The JobScheduler PowerShell CLI module is available for PowerShell jobs. A basic job using the PowerShell CLI might look like this:
Explanations
- The PowerShell CLI is activated by the
Import-Module JobScheduler
command. - For a complete list of cmdlets available from the PowerShell CLI see PowerShell CLI - Cmdlets
Additional examples are available from the PowerShell CLI - Use Cases article.
Compatibility between PowerShell and Shell
PowerShell jobs can be considered as a migration path for shell jobs. This suggests that any shell job can possibly be converted (with a few changes) to a PowerShell job.
Please consider compatibility issues as explained below.
Reading Order parameters or Job parameters
Reading parameters works slightly different for PowerShell jobs than for shell jobs, using $env:VARIABLE
for PowerShell instead of %VARIABLE%
as for shell:
# Example Shell: environment variable for task/order parameter myscript.cmd %SCHEDULER_PARAM_NAME1% # Example PowerShell solution 1: environment variable for task/order parameter myscript.cmd $env:SCHEDULER_PARAM_NAME1 # Example PowerShell solution 2: shorthand notation for task/order parameter myscript.cmd $spooler_params.item( "name1" ) # Example PowerShell solution 3: access task parameter myscript.cmd $spooler_task.params().value( "name1" ) # Example PowerShell solution 4: access order parameter myscript.cmd $spooler_task.order().params().value( "name1" )
Returning a parameter and its value to an Order
Setting a parameter for an order (for instance parameter name1
with the initial value value1
) and modifying the value to value2
and returning the parameter to the order so that the next job chain node uses the new value. For PowerShell this works using the API method available from $spooler_task.order()
:
# Example Shell: echo name1 = value2 >> %SCHEDULER_RETURN_VALUES% # Example PowerShell: $spooler_task.order().params().set_value( "name1", "value2" )
Error Handling
PowerShell jobs offer a number of options to detect run-time errors.
Checking the last exit code of a Windows program or script
- If a native Windows program or script (.bat, .cmd) causes an error then this will assign the exit code to the
$LastExitCode
global variable. This behavior does not apply to cmdlets causing errors. - JobScheduler checks this variable and will set the job exit code accordingly. For exit codes != 0 an error is raised.
- This behavior is superior compared to shell jobs as errors from any line in the job script are detected. For shell scripts only the last line of a job script determines the execution result (Unix:
$?
, Windows:%errorlevel%
).
Checking error output
- Native Windows programs or scripts and cmdlets can cause errors that create some error output (stderr).
- PowerShell jobs can be configured to handle any output found in stderr to indicate an error. Not all output to stderr may indicate an error as a number of Windows native programs is reported to write to stderr instead of stdout. Therefore users can choose from the following configuration:
<job stderr_log_level="error"/>
- Indicates that any output found in stderr will result in a job error.
<job stderr_log_level="info"/>
- Indicates that output to stderr is logged but will not result in a job error (default).
- For details check - JS-1329Getting issue details... STATUS and - JS-1393Getting issue details... STATUS
Suppressing Exit Codes
- Users who wish to suppress exit codes of failed executions of native Windows programs or scripts can use
$LastExitCode = $null
- This will disable the above mentioned check of the last exit code.
Catching errors
- Users can use
try/catch
blocks to implement individual error handlingThis simple example prevents errors from being raised for non-accessible network shares:
try { $found = Test-Path \\some_share\some_directory\some_file -PathType Leaf } catch { $found = $false }
- From the above example an exception is raised and handled that does not result in a job error. In addition no output to stderr is created that would be detected by the above mentioned error output checking.
References
Reference Documentation
- For further information about how to write API Jobs in PowerShell please check the Reference Documentation. You will find the available objects and methods as well as some useful examples for API jobs
Change Management References