PowerShell Jobs

Scope

JobScheduler supports PowerShell for implementation of jobs, see JS-1595 - Getting 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
- callch as spooler_process() for
At the time of writing a performance penalty is obseved for PowerShell jobs due to loading the .NET Framework 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 1: A simple PowerShell job with some scripting similar to shell jobs might look like this:

<?xml version="1.0" encoding="ISO-8859-1"?>
<job process_class="my_Agent">
    <script language="powershell">
        <![CDATA[
echo "job is starting"

# pause the job for 10 seconds
Start-Sleep -Seconds 10

# list files in a directory
$files = dir *
echo $files
 
# execute some Windows command script
/tmp/some_batch_script.cmd
echo "job is finishing"
        ]]>
    </script>
    <run_time />
</job>

Example 2: A basic PowerShell job including the call to a function might look like this:

<?xml version="1.0" encoding="ISO-8859-1"?>
<job  process_class="my_Agent">
    <script  language="powershell">
        <![CDATA[
# PowerShell function used in main job
function Get-Files( $directory )
{
	echo "entering function get_files"
	return Get-ChildItem $directory
}
	
echo "job is starting"
Start-Sleep -Seconds 10
 
$files = Get-Files "c:\tmp\my_directory"
echo $files
echo "job is finishing"	
        ]]>
    </script>
    <run_time />
</job>

Example: PowerShell API Job

A basic API job might look like this:

<?xml version="1.0" encoding="ISO-8859-1"?>
<job  process_class="/tests/Agent" stop_on_error="no">
    <script  language="powershell">
        <![CDATA[
function spooler_process()
{		
	# set variables to store the information about job and task 	
	$jobName = $spooler_job.name()
	$jobTitle = $spooler_job.title()
	$taskId = $spooler_task.id()
	
	# display the information about job and task
	echo "job $jobName with title $jobTitle is starting"
	echo "task ID is $taskId"
		
	echo "job is finishing"
		
	# for standalone jobs set return code to false / for order jobs set to true in case of successful execution
	return $false
}
        ]]>
    </script>
    <run_time />
</job>

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:

<?xml version="1.0" encoding="ISO-8859-1"?>
<job  process_class="my_Agent">
    <script  language="powershell">
        <![CDATA[
echo "job is starting"
Start-Sleep -Seconds 10
echo "job is finishing"
        ]]>
    </script>

    <monitor  name="process_powershell" ordering="0">
        <script  language="powershell">
            <![CDATA[
function spooler_process_before()
{
	# check for a "go" file that is required to start the job
	$rc = ( Test-Path -Path "/tmp/go.txt" -PathType Leaf )
	echo ".. looking up go file: $rc"
	return $rc
}
            ]]>
        </script>
    </monitor>

    <run_time />
</job>

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:

<?xml version="1.0" encoding="ISO-8859-1"?>
<job  process_class="my_Agent" stop_on_error="no">
    <settings >
        <log_level ><![CDATA[debug1]]></log_level>
    </settings>

    <script  language="powershell">
        <![CDATA[
# Use Write-Output or Echo cmdlets to write to the JobScheduler log
Write-Output "job: this is some output"
echo "job: this is some output"

# This does not work: Use of Write-Host cmdlet is not applicable
# Write-Host "job: this is some output"

# Standard PowerShell verbose setting is considered for log output
$VerbosePreference = "Continue"
Write-Verbose "job: this is some verbose output"

# Standard PowerShell debug setting is considered for log output
$DebugPreference = "Continue"
# In addition the current log level of the job has to be set, e.g. log level "debug1" logs debug messages
Write-Debug "job: this is some debug output"

# creates a warning for the job
Write-Warning "job: this is a warning"

# can be used to throw an error
# Write-Error "job: this is an error"
        ]]>
    </script>

    <run_time />
</job>

Explanations

Using PowerShell standard output
- Use of the Write-Output and Echo 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.
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.
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.
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.

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:

<?xml version="1.0" encoding="ISO-8859-1"?>
<job process_class="my_Agent">
	<script language="powershell">
		<![CDATA[
Import-Module JobScheduler
 
# display summary information
Show-Status
 
# retrieve the number of available job chains
( Get-JobChain ).count

# get the number of current tasks
( Get-Task ).count
		]]>
	</script>
	<run_time />
</job>

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.

Calling Order parameters or Job parameters

Calling parameters works differently for PowerShell jobs than for shell jobs, using $env:VARIABLE for PowerShell instead of %VARIABLE% as for shell:

# Example Shell: 
myscript.cmd %SCHEDULER_PARAM_NAME1%

# Example PowerShell: 
myscript.cmd $env:SCHEDULER_PARAM_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-1329 - Getting issue details... STATUS and JS-1393 - Getting 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 handling
- This 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

T	Key	Linked Issues	Fix Version/s	Status	P	Summary	Updated

Loading...

Refresh

Space shortcuts

Page tree

Scope

Background

Feature Availability

Examples

Example: PowerShell Job

Example: PowerShell API Job

Example: Combine both PowerShell Job and Monitor

Example: PowerShell Job with different output channels

JobScheduler PowerShell CLI for Jobs

Compatibility between PowerShell and Shell

Calling Order parameters or Job parameters

Returning a parameter and its value to an Order

Error Handling

Checking the last exit code of a Windows program or script

Checking error output

Suppressing Exit Codes

Catching errors

References

Reference Documentation

Change Management References