Download
The PowerShell Command Line Interface is available
- from GitHub at https://github.com/sos-berlin/scheduler-cli-powershell
from PowerShell Gallery at https://www.powershellgallery.com/packages/JobScheduler/1.2.0
PowerShell GalleryFind-Module -Name JobScheduler Install-Module -Name JobScheduler
Description
The JobScheduler Command Line Interface (CLI) can be used to control JobScheduler instances (start, stop, status) and job-related objects such as jobs, job chains, orders, tasks.
The CLI module supports Windows PowerShell FullCLR 5.1 and PowerShell CoreCLR 6.x and 7.x for Windows, Linux and MacOS environments. It can be used with JobScheduler releases 1.12 and 1.13. The CLI module is used for the following areas of operation:
- provide bulk operations:
- select jobs, job chains, orders and tasks
- manage orders with operations for start, stop and removal
- suspend and resume jobs, job chains and orders
- terminate tasks
- schedule jobs and orders:
- add orders to job chains
- start jobs and orders
- manage Agents
- retrieve Agent clusters
- check Agent status
- retrieve Agent job execution reports
- work as a replacement for existing Windows command scripts
- JobScheduler start script
.\bin\jobscheduler.cmd
:- provide operations for installing and removing the JobScheduler Windows service
- starting and stopping JobScheduler instances including active and passive clusters
- JobScheduler Event script
.\bin\jobscheduler_event.cmd
- JobScheduler start script
Getting Started
Prerequisites
Check Execution Policy
PS > Get-ExecutionPolicy
- shows the current execution policy, see e.g. Microsoft Technet about_Execution_Policies
- The required PowerShell execution policy for the JobScheduler CLI module is RemoteSigned or Unrestricted
PS > Set-ExecutionPolicy RemoteSigned
- Modifying the execution policy might require administrative privileges
Check Module Location
- PowerShell provides a number of locations for modules, see $env:PSModulePath for predefined module locations.
- Download/unzip the JobScheduler CLI module
- either to a user's module location, e.g. for Windows
C:\Users\<user-name>\Documents\WindowsPowerShell\Modules\
or/home/<user-name>/.local/share/powershell/Modules
for a Linux environment - or to a location that is available for all users, e.g.
C:\Windows\system32\WindowsPowerShell\v1.0\Modules\
- or to an arbitrary location that later on is specified when importing the module.
- either to a user's module location, e.g. for Windows
- Directory names might differ according to PowerShell versions.
- The required JobScheduler CLI module folder name is JobScheduler. If you download the module it is wrapped in a folder that specifies the current branch, e.g. scheduler-cli-powershell-1.2.0. Manually create the JobScheduler folder in the module location and add the contents of the scheduler-cli-powershell-1.2.0 folder from the archive.
Import Module
PS > Import-Module JobScheduler
- loads the module from a location that is available with the PowerShell module path,
- see
$env:PSModulePath
for predefined module locations.
PS > Import-Module C:\some_module_location\JobScheduler
- loads the module from a specific location, absolute and relative paths can be used on all platforms.
Hint: You can add the command Import-Module JobScheduler
to your PowerShell profile to have the module loaded on start of a PowerShell session, see PowerShell CLI 1.1 - Use Cases - Credentials Management
Connect to Web Service
As a first operation after importing the module it is required to execute the Connect-JS
cmdlet.
PS > Connect-JS -Url <Url> -AskForCredentials
- specifies the URL for which the JOC Cockpit REST Web Service is available and asks interactively for credentials. The default account is
root
with the passwordroot
.
- specifies the URL for which the JOC Cockpit REST Web Service is available and asks interactively for credentials. The default account is
PS > Connect-JS <Url> <Credentials> <JobSchedulerId>
orPS > Connect-JS -Url <Url> -Credentials <Credentials> -Id <JobSchedulerId>
- specifies the URL of JOC Cockpit which is the same URL that you use when opening the JOC Cockpit GUI in your browser, e.g.
http://localhost:4446
. When omitting the protocol (HTTP/HTTPS) for the URL then HTTP is used. - specifies the credentials (user account and password) that are used to connect to the Web Service.
- A credential object can be created by keyboard input like this:
Set-JSCredentials -AskForCredentials
- A credential object can be created like this:
$credentials = ( New-Object -typename System.Management.Automation.PSCredential -ArgumentList 'root', ( 'root' | ConvertTo-SecureString -AsPlainText -Force) )
- The example makes use of the default account
root
and passwordroot
. - A possible location for the above code is a user's PowerShell Profile that would be executed for a PowerShell session.
- Credentials can be forwarded with the Url parameter like this:
Connect-JS -Url http://root:root@localhost:4446
- Specifying account and password with a URL is considered insecure.
- A credential object can be created by keyboard input like this:
- specifies the JobScheduler ID that the Master has been installed with. As JOC Cockpit can manage a number of Master instances the
-Id
parameter can be used to select the respective Master. - allows to execute cmdlets for the specified Master independently from the server and operating system that the JobScheduler Master is operated for, i.e. you can use PowerShell cmdlets on Windows to manage a JobScheduler Master running on a Linux box and vice versa. As an exception to this rule you cannot start a remote JobScheduler Master and you cannot start a remote JobScheduler Windows service, however, you can restart, terminate, abort, suspend and resume any JobScheduler Master instance on any platform.
- specifies the URL of JOC Cockpit which is the same URL that you use when opening the JOC Cockpit GUI in your browser, e.g.
Run Commands
The JobScheduler CLI provides a number of cmdlets, see PowerShell CLI - Cmdlets. Return values of cmdlets generally correspond to the JOC Cockpit REST Web Service.
- The complete list of cmdlets is available with the command:
PS > Get-Command -Module JobScheduler
- Cmdlets come with a full name that includes the term
JobScheduler
:PS > Get-JobSchedulerStatus
- The term
JobScheduler
can be abbreviated toJS
:PS > Get-JSStatus
The term JobScheduler
can further be omitted if the resulting alias does not conflict with existing cmdlets:PS > Get-Status
- Should conflicts occur with existing cmdlets from other modules then no conflicting aliases will be created. This includes aliases for cmdlets from the PowerShell Core as e.g.
Get-Job, Start-Job, Stop-Job
.
It is recommended to use the abbreviated formGet-JSJob, Start-JSJob
etc. - Help information for a given cmdlet is available with:
PS > Get-Help Get-JSStatus -detailed
Examples
Find some typical use cases for the JobScheduler CLI.
PS > Get-JSStatus -Display
- shows the summary information for a JobScheduler Master.
PS > (Get-JSJobChain).count
- shows the number of job chains that are available.
PS > (Get-JSJob).count
- shows the number of jobs that are available.
PS > (Get-JSTask).count
- shows the number of tasks that are currently running.
PS > Get-JSJob -Directory /sos -Running | Stop-JSTask
- stops all running tasks from the specified folder.
PS > Get-JSTask | Stop-JSTask
- performs an emergency stop and terminates all running tasks.
PS > Get-JSJob -Running -Enqueued | Stop-JSTask
- performs an emergency stop and terminates all running and enqueued tasks.
PS > Get-JSTask -Enqueued
- retrieves the list of enqueued tasks, i.e. tasks that are scheduled for later start.
PS > $orders = (Get-JSOrder -Directory /my_jobs -Recursive -Temporary | Suspend-JSOrder)
- retrieves temporary ad hoc orders from the my_jobs directory and any sub-folders with orders found being suspended. The list of affected orders is returned.
PS > $orders | Remove-JSOrder
- remove orders based on a list that has previously been retrieved.
Manage Log Output
JobScheduler Cmdlets consider verbosity and debug settings.
PS > $VerbosePreference = "Continue"
- This will cause verbose output to be created from cmdlets.
PS > $VerbosePreference = "SilentlyContinue"
- The verbosity level is reset.
PS > $DebugPreference = "Continue"
- This will cause debug output to be created from cmdlets.
PS > $DebugPreference = "SilentlyContinue"
- The debug level is reset.
Manage JobScheduler Master Instance for Windows
Specifically for Windows the Master installation can be managed.
PS > Use-JSMaster -InstallPath <InstallationPath>
- specifies the full installation path, e.g.
C:\Program Files\sos-berlin.com\jobscheduler\scheduler1.10
, for a locally available JobScheduler Master.
- specifies the full installation path, e.g.
PS > Use-JSMaster -InstallPath $env:SCHEDULER_HOME
- You can use the environment variable
SCHEDULER_HOME
that points to the installation path. - The JobScheduler CLI module on import checks availability of this environment variable.
- You can use the environment variable
PS > Use-JSMaster -Url <Url> -Id <JobSchedulerID>
- specify both URL and JobScheduler ID (recommended).
- determines if the Master with the specified JobSchedulerID is locally available.
- Hints
- If your JobScheduler Master is configured to require HTTP authentication then please consider that
- by default the Windows credentials of the current user are forwarded for web requests.
- individual credentials can be added by use of the following cmdlet
Set-JobSchedulerCredentials
. - For details and examples see PowerShell CLI 1.1 - Use Cases - Credentials Management
- If your JobScheduler Master is configured to require HTTP authentication then please consider that
Find some use cases for JobScheduler Master management:
- Start the JobScheduler Master:
Start-JSMaster -Service
- Starts the Windows service of a JobScheduler Master
- Start the JobScheduler Master in paused mode:
Start-JSMaster -Service -Pause
- The Windows service is started and is immediately paused to prevent any tasks from starting.
- Restart the JobScheduler Master:
Restart-JSMaster -Timeout 120
- Restarts the Master having left any running tasks up to 120 seconds to complete.
- Stop the JobScheduler Master immediately:
Stop-JSMaster -Action kill
- This will kill all running tasks immediately and terminate the JobScheduler Master.
- Stop the JobScheduler Master cluster:
Stop-JSMaster -Cluster -Action abort
- Install the JobScheduler Master Windows service:
Install-JSService -Start -PauseAfterFailure
- Installs and starts the Windows service. Should a previous JobScheduler run have been terminated with failure then the JobScheduler Master will switch to paused mode.
- This allows e.g. to check for enqueued tasks before starting operations.
- A previously installed Windows service with the same name will be removed.
- Install the JobScheduler Master Windows service for a specific account:
Install-JSService -Start -UseCredentials
- This will install the Windows service and ask for the name of the account and password that the service is operated for. The account name typically includes the domain and user, e.g.
.\some_user
forsome_user
in the current domain.
- Remove the JobScheduler Master Windows service:
Remove-JSService
- This will remove the Windows service. Should any tasks be running with the JobScheduler Master then the removal will be delayed.
- Consider to use
Stop-JSMaster -Action abort
if immediate termination of the Windows service is required.
Change Management References
JobScheduler Cmdlets in Detail
Pages
- PowerShell CLI 1.2 - Cmdlets
- PowerShell CLI 1.2 - Cmdlets - Job Management
- PowerShell CLI 1.2 - Cmdlets - Job Chain Management
- PowerShell CLI 1.2 - Cmdlets - Job Stream Management
- PowerShell CLI 1.2 - Cmdlets - Calendar Management
- PowerShell CLI 1.2 - Cmdlets - Master Management
- PowerShell CLI 1.2 - Cmdlets - Agent Management
- PowerShell CLI 1.2 - Cmdlets - Event Management
- PowerShell CLI 1.2 - Cmdlets - Inventory Management
- PowerShell CLI 1.2 - Cmdlets - Windows Utilities and Service Management
- PowerShell CLI 1.2 - Cmdlets - Migration Management
- PowerShell CLI 1.2 - Use Cases
- PowerShell CLI 1.2 - Use Cases - Credentials Management
- PowerShell CLI 1.2 - Use Cases - Kill a number of tasks
- PowerShell CLI 1.2 - Use Cases - Logs
- PowerShell CLI 1.2 - Use Cases - Manage Events
- PowerShell CLI 1.2 - Use Cases - Manage JobScheduler when the GUI becomes unresponsive
- PowerShell CLI 1.2 - Use Cases - Manage Masters
- PowerShell CLI 1.2 - Use Cases - Manage temporary orders
- PowerShell CLI 1.2 - Use Cases - Reporting
- PowerShell CLI 1.2 - Use Cases - Synchronous Processing
- PowerShell CLI 1.2 - Use Cases - Use with a Proxy
Navigation