PowerShell Command Line Interface - Introduction

TOPIC

about_JobScheduler

DOWNLOAD

The PowerShell Command Line Interface is available from GitHub at https://github.com/sos-berlin/scheduler-cli-powershell

SHORT DESCRIPTION

The JobScheduler Command Line Interface (JCLI) can be used to control
JobScheduler instances (start, stop, status) and job-related objects
such as jobs, job chains, orders, tasks.

The JobScheduler CLI module supports Windows PowerShell 2.0 and newer.

LONG DESCRIPTION

The JobScheduler Command Line Interface (JCLI) is used for the following
areas of operation:

• work as a replacement for the command script .\bin\jobscheduler.cmd:
  • provide operations for installing and removing the JobScheduler Windows service
  • starting and stopping JobScheduler instances including active and passive clusters
• provide bulk operations:
  • select jobs, job chains, orders and tasks
  • manage orders with operations for start, stop and removal
  • terminate tasks
• schedule jobs and orders:
  • add orders to job chains
  • start jobs and orders

The JobScheduler CLI provides a number of cmdlets, see PowerShell CLI - Cmdlets

• The complete list of cmdlets is available with the command:
  • PS C:\> Get-Command -Module JobScheduler
• Cmdlets come with a full name and a short alias:
  • The full name includes the term JobScheduler and can be omitted as e.g. in:
  • PS C:\> Use-JobSchedulerMaster
  • PS C:\> Use-Master
• Should conflicts occur with existing modules then the aliases can be removed
  • PS C:\> Remove-Item alias:Use-Master

Cmdlets consider verbosity and debug settings.

• This will cause verbose output to be created from cmdlets:
  • PS C:\> $VerbosePreference = "Continue"
• The verbosity level is reset with:
  • PS C:\> $VerbosePreference = "SilentlyContinue"
• This will cause debug output to be created from cmdlets:
  • PS C:\> $DebugPreference = "Continue"
• The debug level is reset with:
  • PS C:\> $DebugPreference = "SilentlyContinue"

The responses from a JobScheduler Master can include large XML answers.
Such answers are stored in temporary files, the debug message indicates the location of the file.
The threshold for creating temporary files is 1000 byte by default.
Consider use of the Set-Option -DebugMaxOutputSize cmdlet to change this value.

The JobScheduler CLI is provided with  JS-1630 - Getting issue details... STATUS

HOW TO GET STARTED WITH THE JobScheduler CLI?

The JobScheduler CLI is used for JobScheduler instances that are installed
locally or on remote computers and is initialized by the following commands:

• Import Module
  • PS C:\> 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 C:\> Import-Module C:\some_module_location\JobScheduler
    • loads the module from a specific location, absolute and relative paths can be used.
  • Hints
    • The JCLI module will automatically connect to a Master on import of the module if one of the following environment variables is present:
      • SCHEDULER_URL specifies the URL for which the Master is operated.
      • SCHEDULER_ID specifies the unique identification of a Master.
      • SCHEDULER_HOME specifies the installation path of a locally available Master.
    • 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 - Use Cases - Credentials Management
• Use JobScheduler Master Instance
  • As a first operation after importing the module it is required to execute the Use-Master cmdlet.

  • PS C:\> Use-Master <Url>   or   PS C:\> Use-Master -Url <Url> 
    • specifies the URL for which the JobScheduler Master is available. This is the same URL that you would use when opening the JOC GUI in your browser, e.g. http://localhost:4444. Do not omit the protocol (http/https) for the URL.
    • 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 to manage a JobScheduler Master running on a Linux box.
    • specifying the URL is not sufficient to manage the Windows Service of the respective Master, see below.
  • PS C:\> PS C:\> Use-Master -Id <JobSchedulerID>
    
    • references the JobScheduler ID that has been assigned during installation of a Master.
    • adds the JobScheduler ID to the assumed installation base path.
      
      • A typical base bath would be C:\Program Files\sos-berlin.com\jobscheduler
      • The path is added the subdirectory with the name of the JobScheduler ID
  • PS C:\> Use-Master -InstallPath <InstallationPath>
    • specifies the full installation path, e.g. C:\Program Files\sos-berlin.com\jobscheduler\scheduler1.10, for a locally available JobScheduler Master.
  • PS C:\> Use-Master -InstallPath $env:SCHEDULER_HOME
    • You can use an environment variable SCHEDULER_HOME that points to the installation path.
    • The JobScheduler CLI module on import checks availability of this environment variable
    • The Use-Master cmdlet is executed automatically if SCHEDULER_HOME is present.
  • PS C:\> Use-Master <Url> <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 command:
        • Set-Credentials -AskForCredentials prompts for user input of an account and password.
        • Set-Credentials -Credentials $credentials accepts a predefined credentials object that can be created e.g. by
          • $credentials = ( New-Object -typename System.Management.Automation.PSCredential -ArgumentList 'account', ( 'password' | ConvertTo-SecureString -AsPlainText -Force) )
          • Technically this allows to store the account and password in a script which is not recommended for compliance reasons.
        • Set-Credentials without parameters removes an existing credentials object from being forwarded for web requests.
      • You can add the command Set-Credentials to your PowerShell profile to have credentials applied on start of a PowerShell session.
• Manage JobScheduler Objects
  • PS C:\> Show-Status
    • shows the summary information for a JobScheduler Master
  • PS C:\> Get-Order
PS C:\> Get-JobChain
PS C:\> Get-Job
PS C:\> Get-Task
    • retrieves the list of avaiable objects
  • see complete list of cmdlets with the cmdlet: Get-Command -Module JobScheduler

HOW TO RUN JobScheduler COMMANDS

JobScheduler commands are Windows PowerShell scripts (.ps1 files), so you can run
them at the command line, or in any editor.

• Makes the JobScheduler Master with the specified Url available for use with cmdlets.
  • PS C:\> Use-Master http://localhost:4444
• Shows the summary information of a JobScheduler Master.
  • PS C:\> Show-Status
• Shows the number of tasks that are currently running.
  • PS C:\> (Get-Task).count
• Stops all running tasks (emergency stop).
  • PS C:\> Get-Task | Stop-Task
• Collects the list of orders from a directory and stores it in a variable.
  • PS C:\> $orders = Get-Order /sos

For more information about JobScheduler cmdlets, type: Get-Help Use-Master -detailed, Get-Help Show-Status -detailed etc.

EXAMPLES

Find some typical use cases for the JobScheduler CLI.

• Perform an emergency stop:
  • Get-Task | Stop-Task -Action kill
  • This will terminate all running and enqueued tasks immediately.
• Find enqueued tasks, i.e. tasks that are scheduled for a later start:
  • Get-Task -NoRunningTasks
  • Retrieves the list of scheduled tasks.
• Suspend any temporary orders that are e.g. created by job scripts:
  • $orders = ( Get-Order /my_jobs -NoPermanent | Suspend-Order )
  • This will retrieve temporary ad hoc orders from the /my_jobs directory and any subfolders.
  • All temporary orders are suspended and the list of order objects is stored in a variable.
• Remove orders based on a list that has previously been retrieved:
  • $orders | Remove-Order
  • This will remove the orders available from the list.

MANAGING THE JobScheduler MASTER

Find some use cases for JobScheduler Master management.

• Start the JobScheduler Master:
  • Start-Master -Service
  • Starts the Windows service of a JobScheduler Master
• Start the JobScheduler Master in paused mode:
  • Start-Master -Service -Pause
  • The Windows service is started and is immediately paused to prevent any tasks from starting.
• Restart the JobScheduler Master:
  • Restart-Master -Timeout 120
  • Restarts the Master having left any running tasks up to 120 seconds to complete.
• Stop the JobScheduler Master immediately:
  • Stop-Master -Action kill
  • This will kill all running tasks immediately and terminate the JobScheduler Master.
• Stop the JobScheduler Master cluster:
  • Stop-Master -Cluster -Action abort
• Install the JobScheduler Master Windows service:
  • Install-Service -Start -PauseAfterFailure
  • Installs and starts the Windows service. Should a previous JobScheduler run have been terminated with failure then JobScheduler Master will switch to pause 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-Service -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 for some_user in the current domain.
• Remove the JobScheduler Master Windows service:
  • Remove-Service
  • 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-Master -Action abort if immediate removal of the Windows service is required.

SEE ALSO

• Full list of JobScheduler cmdlets: PowerShell CLI - Cmdlets
• Below list of aliases for JobScheduler cmdlets.

Master Managment

• Get-Calendar
  
• Get-Status
• Get-SystemCredentials
• Get-Version

• Restart-Master
• Resume-Master

• Send-Command
• Set-Credentials 
• Set-Option

• Show-Calendar

• Show-Status
• Start-Master

• Stop-Master
  
• Suspend-Master
• Use-Master

Job Chain Management

• Add-Order
• Get-JobChain
• Get-Order
• Get-SingleOrder
• Remove-Order
• Reset-Order
• Resume-Order

• Start-Order
• Suspend-Order
• Update-Order

Job Management

• Get-Job
• Get-Task
• Start-Job
• Stop-Job
• Stop-Task
• Update-Job

Windows Service Management

• Install-Service

• Remove-Service

Change Management References