PowerShell Jobs

Scope

• JobScheduler offers PowerShell as a language for implementation of jobs.
• The introduction of PowerShell as a language for JobScheduler has not only with API jobs to do, but can also be used a language for shell jobs.
• There are some differences between Shell and PowerShell Jobs that will be supported as they are (see PowerShell as a Shell).
• The decision to include PowerShell as a language for JobScheduler (among others) is in the same line with the development of Microsoft programming languages.
• PowerShell jobs are executed with Agents, not with a Master

Feature Availability

FEATURE AVAILABILITY STARTING FROM RELEASE 1.10.5

Examples

Example: PowerShell as a Shell

Example 1: A simple PowerShell job with some scripting similar to basic shell jobs might look like this:

<?xml version="1.0" encoding="ISO-8859-1"?>
<job process_class="my_Agent">
    <script language="powershell">

echo "job is starting"

# pauses the job for 10 seconds
sleep 10

# show the files in a directory
$files = dir *
echo $files
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">
	
	# PowerShell function used for the main job
	function get_files($directory){
		echo "entering function get_files"
		return get-childitem $directory
	}
	
	echo "job is starting"
	sleep 10
 
	# the same structure as in the example 1 but using a PowerShell function
	$files = get_files "my_directory"
	echo $files
	echo "job is finishing"
	
    </script>
    <run_time />
</job>

Example: PowerShell API Jobs 

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()
	
	# show 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 to false / for order jobs set to true
	return $false
}
        ]]>
    </script>
    <run_time />
</job>

Example: Combination of both (PowerShell Job with Monitor as a Pre-Processing job)

This PowerShell job contains a job with a  pre-processing Monitor script (API job) that is executed before the job script (the shell job) is executed:

<?xml version="1.0" encoding="ISO-8859-1"?>

<job  process_class="my_Agent">
    <script  language="powershell">

echo "job is starting"
sleep 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 outputs

The following job shows how to set different outputs 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[
# 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 in the log
Write-Warning "job: this is a warning"

# can be used to throw an error
# Write-Error "job: this is an error"

# This does not work: Use of Write-Host is not allowed
# Write-Host "job: this is some output"
        ]]>
    </script>

    <run_time />
</job>

Extras: PowerShell CLI for Powershell Jobs

The integration of the PowerShell CLI into PowerShell jobs is available as well. A basic job using the PowerShell CLI might look like this:

 <job process_class="my_Agent">
 <script language="powershell">
 <![CDATA[

Import-Module JobScheduler
show-status

 ]]>
 </script>
<run_time />

Compatibility between PowerShell and Shell

As mentioned before, PowerShell Jobs should be seen as a migration path for shell jobs. That means, every shell job should 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: for PowerShell instead of % 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 in 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 methods for $spooler_task.order():

# Example Shell: 
echo name1 = value2 >> %SCHEDULER_RETURN_VALUES%

# Example PowerShell: 
$spooler_task.order().params().set_value("name1","value2")