PowerShell Jobs

Scope

• JobScheduler supports PowerShell as a language for implementation of jobs, see  JS-1595 - Getting issue details... STATUS
• The support for PowerShell includes API jobs and shell jobs.
  • PowerShell jobs can use any Windows commands or PowerShell commands.
  • PowerShell jobs can use the JobScheduler API.
• There are some minor differences between Shell jobs and PowerShell jobs, see PowerShell as a Shell.
• PowerShell jobs are executed with Agents, not with a JobScheduler Master.

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

Example: Combine both PowerShell Job and Monitor

This PowerShell job implements a  pre-processing Monitor script (API job) 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 different 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>

JobScheduler PowerShell CLI for Jobs

The JobScheduler PowerShell CLI 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
		]]>
	</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

Compatibility between PowerShell and Shell

PowerShell jobs can be considered as a migration path for shell jobs. This suggests that every 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: 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 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" )

References

Reference Documentation

• For further information about how to write API Jobs in PowerShell please check http://www.sos-berlin.com/doc/en/scheduler.doc/api/api-powershell.xml. You will find the available methods as well as some useful examples for your API jobs

Change Management References