PowerShell Jobs

Scope

• JobScheduler offers Powershell as a language for implementation of Jobs
• Powershell Jobs have to been seen as the analogy for the Shell Jobs, even though there are some differences between Shell and Powershell Jobs
• 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 can only be run on Agents and not on the Master

Feature Availability

FEATURE AVAILABILITY STARTING FROM RELEASE 1.10.5

Powershell as a Shell

As mentioned before, Powershell Jobs should be seen as the analogy for Shell Jobs in the future. That means, every Shell job should be able to be (with any or few changes) converted into a Powershell job. 

Nevertheless, there are some compatibility issues described below.

Calling Order parameters or Job parameters

Example Shell: 
myscript.cmd %SCHEDULER_PARAM_NAME1%

Example Powershell: 
myscript.cmd $env:SCHEDULER_PARAM_NAME1

Returning a parameter an its value to an Order

Example Shell: 
echo NAME1 = VALUE1 >> %SCHEDULER_RETURN_VALUES%

Example Powershell: 
echo "NAME1 = VALUE1" >> $env:SCHEDULER_RETURN_VALUES%

Exit Code Handling

The following example throws no error in Shell but it breaks at line 2 and ends in an error for Powershell:

echo "job is starting"
abcde
echo "job is finishing"

The same example would be working in Powershell the following way:

echo "job is starting"
try{abcde}
catch{Break}
echo "job is finishing"

Examples

Example: Powershell as a Shell

Example 1: A simple job with some scripting analogue 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"
sleep 10
$files = dir *
echo $files
echo "job is finishing"
    </script>
    <run_time />
</job>

Example 2: A basic PowerShell job including that calls a function might look like this:

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


	function get_files($directory){
		echo "entering function get_files"
		return get-childitem $directory
	}
	
	echo "job is starting"
	sleep 10
	$files = get_files "*"
	echo $files
	echo "job is finishing"
	
    </script>
    <run_time />
</job>

Example: Powershell API Jobs

A basic API Job, analogue to Javascript jobs for instance, might look like this:

<?xml version="1.0" encoding="ISO-8859-1"?>
<job  process_class="my_Agent">
    <script  language="powershell">
	function spooler_process()
		{
		$spooler_log.info("job is starting")
		$files = get-childitem dir *
		echo $files 
		$spooler_log.info("job is finishing")
		return $false
		}
	
    </script>
    <run_time />
</job>

Example: Combination of both (Shell Job with Monitors as a Pre-Processing job)

This job contains a pre-processing job (API job) which is executed before the main 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()
		{
		$files = get-childitem *
		echo $files
		$spooler_log.info("hallo")
		return $true
		}
            ]]>
        </script>
    </monitor>
    <run_time />
</job>

Example: PowerShell Job with Debug output

The following job shows how to set different outputs for PowerShell such as:

1. Setting PowerShell verbose for a job
   1. The standard PowerShell verbose setting is considered for jobs
   2. The example shows how to set this at lines 11-12
2. Setting Debug messages for a job
   1. The standard PowerShell debug setting is ignored for jobs
   2. Instead, the current log level of the job is applied, e.g. log level "debug1" will log debug messages
   3. The example shows how to set this at lines 16-17
3. Setting Warning Messages can be done as in line 19
4. Setting Error Messages can be done as in line 22
   1. This throws an error and ends effectively the job with an error 
5. Write-Host does not work for PowerShell jobs as specified in lines 24-25

<?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 jobs:
$VerbosePreference = "continue"
Write-Verbose "job: this is some verbose output"

# Standard PowerShell debug setting is ignored for jobs:
# Instead the current log level of the job is applied, e.g. log level "debug1" logs debug messages
$DebugPreference = "continue"
Write-Debug "job: this is some debug output"

Write-Warning "job: this is a warning"

# This 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: CLI for Powershell Jobs

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

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

Import-Module JobScheduler
show-status

 ]]>
 </script>
<run_time />