Purpose

• Instructions to execute jobs are basic to workflow automation.
• Any number of jobs can be executed in a workflow.

Job

• A job is the basic unit what to execute with an Agent.
• Job implementations come in the following flavors:
  • Shell Jobs are executed with the operating system shell, e.g. the Windows Shell or one of the Unix Shells such as /bin/sh, /bin/bash etc.
    • Shell jobs include to call any shell commands, scripts and executable files.
    • Such jobs behave similarly to individual commands being executed in the command line of the operating system.
    • Shell jobs include to use scripting languages such as Perl, Ruby, Python, PowerShell etc. for which an interpreter is installed with the OS that can be executed from the command line.
  • JVM Jobs are implemented in a number of supported languages that can be operated for a Java Virtual Machine and for which the Agent exposes JS7 - Order Variables and job node arguments. Job implementation languages include
    • Java: such jobs are executed in the JVM provided by the Agent.
    • JavaScript, Ruby, Python etc.: such jobs require use of a GraalVM® Java Virtual Machine that provides the compiler for the respective scripting language.

Relationships

• A workflow can include any number of jobs.
• A job is assigned an Agent that executes the job.
  • Within a workflow jobs can be executed by different Agents (cross-platform scheduling)
• A workflow can include additional instructions
  • to manage job dependencies, e.g. by use of the JS7 - Fork / Join Instruction, 
  • to manage job resources, e.g. by use of the JS7 - Lock Instruction
  • to manage error handling, e.g. by use of the JS7 - Try / Catch Instruction and JS7 - Retry Instruction

Configuration

Jobs are managed from the JOC Cockpit Configuration -> Inventory View.

The tree panel offers the Workflows category to select and display a workflow with the JS7 - Workflow Editor.

• Jobs can be added from the Instruction Panel by dragging and dropping from the  icon.
• When a job is selected then this causes the Job Property Editor to be displayed.

Required Job Properties

Any required job properties are available with the Job Properties tab of the Workflow Editor.

• Name: A job name is required. No spaces are allowed and a number of characters are excluded. 
• Label: A label assigns a name to the workflow node that is assigned the job.
  • The same job can be re-used in the same workflow, however, the job label is unique.
• Agent: Assignment to an Agent is required.
• Return Code: The meaning of the job's return code has to be specified. 
  • Return Codes
    • For shell jobs the OS exit code determines the return code. By default an exit code 0 signals success, any other exit codes signal failure.
    • For JVM jobs the return code is specified by the job implementation.
  • Values
    • Return Codes are integer values within the range from 0 to 9999.
    • A number of return codes can be specified separated by a comma. 
  • On Success / On Error
    • Either successful return codes can be specified or return codes signaling failure.
    • If a job terminates with a return code that is not indicated with the successful return codes or that is stated with return codes signaling failure then the job is considered being failed. For further details see the below chapter on Error Handling.
• Executable Type: Allows to select the job implementation to be a shell job or a JVM job.
  • For shell jobs the Job Property Editor displays the Script subtab and Environment Variables sub-tab.
  • For JVM jobs the Job Property Editor displays the Java subtab.
• Script Subtab
  
  • This tab holds the input field for the job script. 
    
    
  • The right upper corner of this tab offers a pencil icon to invoke the script editor should more than a few commands be added to the job script
    
    
    
    
  • The script editor offers syntax highlighting, capabilities for search & replace, undo & redo etc. Closing the script editor by use of the Submit button will add the script content to the script subtab.

• Java Subtab
  
  • TODO

Optional Job Properties

Job Properties Tab

• Title: A title can be added to the job that will be displayed with the respective views.
• Job Class: 
  • TODO
• Compatibility: For users of JobScheduler branch 1.x a compatibility mode is available.
  • For use of environment variables compatibility enables
    • to automatically create environment variables for shell jobs from any available order variables and job arguments.
    • to use the prefix SCHEDULER_PARAM_ for any environment variable created.
  • For use of job arguments the compatibility mode offers a corresponding tab.
• For Shell Jobs: Environment Variables Subtab
  • Any environment variables for job scripts have to be specified by a mapping:
    
    
    
    
  • The mapping includes to specify a name for the environment variable that has to comply with OS requirements. Names are automatically converted to uppercase. The GUI offers the list of order variable names for the mapping to environment variables.
  • The value of an environment variable can be specified like this:
    • as a string which is a sequence of characters
      • excluding the $ character that prefixes variables.
      • or being enclosed with single quotes to allow literal use of the $ character.
    • as a reference to a variable using the syntax $variableName.
  • The advantage of the above mapping is the fact that
    • you publish environment variables only that are required by a job instead of creating an arbitrary number of environment variables from any order variables and job arguments,
    • you limit the risk to overwrite existing shell environment variables, e.g. when passing an order variable with the name "PATH" then this would overwrite a shell environment variable with the same name.

Node Properties Tab

Error Handling