...

Job

• A job is the basic unit what to execute with that is executed by an Agent.
• Job implementations come with 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 calls 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 allow the use of scripting languages such as Perl, Ruby, Python, PowerShell etc. for which .. The use of these languages requires an interpreter is to be installed with the OS and that can be executed from the command line.
    • Consider that jobs executed by an Agent cannot successfully request interaction from a console or from a user. If the application, command, script or binary file that is executed tries to bring up a popup window for user interaction then this will fail as . This is because in scheduling mode there is no console window to display messages and to request that a user to confirm makes a confirmation in a popup window.
  • JVM Jobs can be 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.

...

• 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, JS7 - Retry Instruction and JS7 - If Instruction.

...

• Shell Jobs
  • The Agent provides JS7 - Job Environment Variables that are available for any shell jobs.
  • JS7 - Order Variables and job node arguments are exposed as environment variables from a mapping that is performed at job level, see below.
• JVM Jobs
  • Jobs running in a JVM provided by the Agent are forwarded a parametrization object that holds similar information as from the environment variables for shell jobs.

...

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

Required Job Properties

Any The 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 excludednot allowed. 
• 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 to have failed. For further details see the chapter below chapter on Error Handling.
• Executable Type: Allows to select the job implementation to be selected as 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.

...

Job Properties Tab

• Title: A title can be added to the job that will be displayed with in the respective viewsrelevant views can be added to a job.
• Job Class: 

  • Status
    colour Yellow title TODO

• Compatibility: For users of JobScheduler branch 1.x a compatibility mode is available.
  • For use of environment variables compatibility enables
    • to automatically create the automatic creation of environment variables for shell jobs from any available order variables and job arguments.
    • to the use of the prefix SCHEDULER_PARAM_ prefix 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 Environment variables for job scripts have to be specified by a mapping:
    
    
    
    
  • The mapping includes to specify specification of 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 is an expression that can be specified like this:
    • as a reference to a variable using the syntax $variableName syntax
      • consider that no leading or trailing spaces are allowed for references.
    • as a string which is a sequence of characters
      • enclosed with single quotes to allow literal use of any characters, including the $ character. The only character not allowed for a string is a single quote.
      • enclosed with double quotes to allow mixed use of characters and variables. A $ character is considered to as a prefix for a variable.
  • 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 of overwriting 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.

...

• Job options include the following configuration items:




• Task Limit: Should more than one order pass the workflow at the same time or should parallel child orders execute the same job then this setting determines the maximum number of tasks that are available for the job. This limits parallelism of tasks to the specified number. If more than the specified number of tasks is requested then orders have to wait until a task becomes free.
• Timeout / Grace Timeout: Specifies the maximum duration that a job should run.
  • If the timeout is exceeded then the Agent will send a SIGTERM signal to a shell job. This corresponds to executing the kill -15 command in Unix environments. The purpose of the SIGTERM signal is to let the job know that it should terminate and to leave it up to the job implementation to perform some cleanup tasks such as disconnecting from a database or removing temporary files.
  • After sending the SIGTERM signal the Agent will wait for the duration of the Grace Timeout to allow the task to complete. If the Grace Timeout is exceeded then the Agent will send a SIGKILL signal that will kill the task. This corresponds to executing the kill -9 command in Unix environments.
• Criticality: This option allows to select a level to be selected that can be used for monitoring purposes to prioritize alerts depending on a job's criticality.
• Log Level: The log level can be used by JVM jobs to adjust their log level. This option is not applicable for shell jobs.

...

• Node properties include the list of default arguments that are available from the respective job node:




• The use case for node arguments includes to use using the same job for a number of times in a given workflow with different parameter sets.
  • Assume that the job requires the same parameter names to be used.
  • However, for each occurrence of the job in a workflow different parameter values should be used.
• In this situation node arguments can be introduced that specify variables with the same name but with different values for each occurrence of a job in the workflow.
  • Names of node arguments should not interfere with order variables as otherwise the node argument values will be overwritten by order variable values.
  • For shell jobs node arguments have to be mapped to environment variables similarly to order variables. 
  • For JVM jobs node arguments are available from Java objects exposed to the job implementation.

...

By design the Job Instruction provides no capabilities to handle for handling job errors. The Job Instruction is limited to determine determining if the job's return code signals success or error.

...

• A job can be added to a JS7 - Try / Catch Instruction block to execute follow-up jobs from a Catch block in case of job failure.
• A job can be added to a JS7 - Retry Instruction block to retry execution of one or more jobs in case that a specific job fails.
• A job can be added to a JS7 - If Instruction to check the job's return code or return values and to decide about further processing such as failing or finishing the underlying order or continuing with a different set of jobs in the workflow. This particularly applies to in a situation when a job terminates with a non-zero return code that is not considered an error but e.g. an informational warning or in a situation when return codes are used to control workflow execution, e.g. indicating by specific return codes that successor jobs should be skipped. The If Instruction is the perfect means to handle this situation.

...