Table of Contents |
---|
Scope
- JobScheduler offers supports PowerShell as a language for implementation of jobs, see
Jira server SOS JIRA columns key,summary,type,created,updated,due,assignee,reporter,priority,status,resolution serverId 6dc67751-9d67-34cd-985b-194a8cdc9602 key JS-1595 - 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 jobssupport 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 that will be supported as they are (jobs, 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 JobScheduler Master.
Feature Availability
Display feature availability | ||
---|---|---|
|
Examples
Example: PowerShell
...
Job
Example 1: A simple PowerShell job with some scripting similar to basic shell jobs might look like this:
Code Block |
---|
<?xml version="1.0" encoding="ISO-8859-1"?> <job process_class="my_Agent"> <script language="powershell"> <![CDATA[ echo "job is starting" # pausespause the job for 10 seconds sleepStart-Sleep -Seconds 10 # show thelist 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> |
...
Code Block |
---|
<?xml version="1.0" encoding="ISO-8859-1"?> <job process_class="my_Agent"> <script language="powershell"> <![CDATA[ # PowerShell function used for thein main job function get_files($directory)Get-Files( $directory ) { echo "entering function get_files" return getGet-childitemChildItem $directory } echo "job is starting" sleepStart-Sleep -Seconds 10 # the same structure as in the example 1 but using a PowerShell function $files = get_filesGet-Files "c:\tmp\my_directory" echo $files echo "job is finishing" ]]> </script> <run_time /> </job> |
Example: PowerShell API
...
Job
A basic API Job job might look like this:
Code Block |
---|
<?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$taskId = $spooler_task.id() # showdisplay the information about job and task echo "job $jobName with title $jobTitle is starting" echo "task ID is $taskID$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 contains a job with implements a pre-processing Monitor script (API job) that is executed before the job script (the shell job) is executed:
Code Block |
---|
<?xml version="1.0" encoding="ISO-8859-1"?> <job process_class="my_Agent"> <script language="powershell"> <![CDATA[ echo "job is starting" sleepStart-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 shows explains how to set use different outputs output channels for PowerShell such as:
Code Block | ||
---|---|---|
| ||
<?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 infor the logjob 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> |
Explanations
- Using PowerShell standard output
- 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 outputSetting PowerShell verbosity for a job
- The standard PowerShell verbosity setting is considered for log output
- Use
$VerbosePreference = "Continue"
followed by - Subsequently use the
Write-Verbose
cmdlet.
- Setting Using PowerShell debug messages for a job
- The Standard The PowerShell debug setting is considered for log output in jobs (through 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 example shows how to set this at lines 16-17
- The Standard The PowerShell debug setting is considered for log output in jobs (through by use of
- Setting Warning Messages can be done as in line 19
- Setting Error Messages can be done as in line 22
- This throws an error and ends effectively the job with an error
Write-Host
does not work for PowerShell jobs as such jobs are not running in a PowerShell host console, but in a PowerShell run-time process.- 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
Extras: PowerShell CLI for Powershell Jobs
...