Product Knowledge Base

Space shortcuts

Page tree

Versions Compared

Old Version 39

changes.mady.by.user Andreas Püschel

Saved on

compared with

New Version 40

changes.mady.by.user Andreas Püschel

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

  • JobScheduler supports PowerShell for implementation of jobs, see 
    Jira
    serverSOS JIRA
    columnskey,summary,type,created,updated,due,assignee,reporter,priority,status,resolution
    serverId6dc67751-9d67-34cd-985b-194a8cdc9602
    keyJS-1595
  • The support for PowerShell includes fills the gap between Shell jobs and API jobs:.
    • PowerShell jobs can use any Windows commands or PowerShell cmdlets and functions.
    • PowerShell jobs can use the objects and methods of the JobScheduler API for PowerShell.
  • Some minor differences exist between classic Shell jobs and PowerShell jobs, see Compatibility between PowerShell and Shell.
  • PowerShell jobs are executed with Agents, not with a JobScheduler Masternot with a JobScheduler Master.

Background

  • From the early days of JobScheduler the distinction between Shell jobs and API jobs was introduced:
    • Shell jobs include whatever can be executed from the command line of the respective shell (Unix or Windows)
    • API jobs are coded in a programming/scripting language. JobScheduler exposes its API to supported languages.
  • With PowerShell jobs such differences are leveled in a way that PowerShell jobs can include 
    • any calls to Windows commands and programs
    • any PowerShell cmdlets
    • any calls to .NET classes
  • At the time of writing a performance penalty is obseved for PowerShell jobs due to loading the .NET Framework PowerShell run-tme. 
    • The delay for PowerShell jobs starting compared to Shell job is about 1-2s. The effective delay depends on the users system performance.
    • This delay corresponds more or less to the time required to execute PowerShell.exe from the command line.

Feature Availability

Display feature availability
StartingFromRelease1.10.5

...

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

Code Block
languagepowershell
collapsetrue
<?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:

Code Block
languagepowershell
collapsetrue
<?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>

...

A basic API job might look like this:

Code Block
languagepowershell
collapsetrue
<?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 return code to false / for order jobs set to true in case of successful execution
	return $false
}
        ]]>
    </script>
    <run_time />
</job>

...

This PowerShell job implements a  pre-processing Monitor script that is executed before the job script is executed:

Code Block
languagepowershell
collapsetrue
<?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>

...

The following job explains how to use output channels for PowerShell such as:

 

Code Block
languagepowershell
collapsetrue
<?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

  1. Using PowerShell standard output
    • Use of the Write-Output and Echo 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.
  2. Using PowerShell verbose output
    • The standard PowerShell verbosity setting is considered for log output
    • Use $VerbosePreference = "Continue" 
    • Subsequently use the Write-Verbose cmdlet.
  3. 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.
  4. 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.
  5. 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. 

...

The JobScheduler PowerShell CLI module is available for PowerShell jobs. A basic job using the PowerShell CLI might look like this:

Code Block
languagepowershell
collapsetrue
<?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

# get the number of current tasks
( Get-Task ).count
		]]>
	</script>
	<run_time />
</job>

...