Scope
- JobScheduler supports PowerShell as a language for implementation of jobs, see - JS-1595Getting 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>
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 PowerShell CLI module for an Agent see PowerShell Command Line Interface - Introduction
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