Qorus Integration Engine® Enterprise Edition 6.1.0_prod
Loading...
Searching...
No Matches
Implementing Jobs

Back to the Developer's Guide Table of Contents

Implementing Qorus Jobs

All Qorus integration objects are described by YAML metadata produced by our IDE, which is available as a free (as in free of charge and also open source) extension to Microsoft Visual Studio Code, a multi-platform editor from Microsoft. The Qorus extension is called Qorus Developer Tools and can be installed directly from Visual Studio Code.

Jobs are simple tasks executed on a schedule, similar to a cron job. The information and status of processing is stored in the database and is reported through system APIs. An internal API is also provided to jobs; see Job API Reference for more information.

Jobs in the Qorus IDE
See also

Job Definition Files

Job definition files define job metadata including the job schedule and furthermore contain a link to the job class source code.

Job definition files are defined in YAML as described in this section.

Job definition files are used to create job definitions in the Qorus schema that will be run acording to their schedule.

Job YAML definition files are parsed by the oload program, which will create the jobs in the Qorus database according to the information in the file.

Jobs have the following properties:

Job Name

The name of the job; the name and version together are unique identifiers for the job and are used to derive the jobid (the single unique identifier for the job; it is generated from a database sequence when the job is loaded into the system via oload).

There can only be one job of a given name loaded in the system at any time, so the name of a job is also a unique identifier for the job.

Job Version

Version string for the job object; this version is informative; only one version of a job is stored in the database at a time.

Job Patch

A string "patch" label which can be used to show that a job was updated while not affecting the jobid.

Note
The patch value can be updated without affecting references to other objects; the unique ID for the object is not updated when the patch value is updated, however since job names are already unique, the patch attribute is not as useful as in other objects but is still included in jobs for consistency's sake.

Job Description

Description of the job; accepts markdown for formatted output.

Job Author

The "author" value indicates the author of the job and will be returned with the job metadata in the REST API and also is displayed in the system UI.

Job Remote Flag

The "remote" flag indicates if the job will run as an independent qjob process communicating with other elements of Qorus Integration Engine with a distributed queue protocol rather than internally in the qorus-core process.

When jobs run in separate qjob processes, it provides a higher level of stability and control to the integration platform as a whole, as a workflow with implementation problems cannot cause the integration platform to fail.

There is a performance cost to running in separate qjob processes; job startup and shutdown is slightly slower, and communication with qorus-core also suffers a performance hit as all communication must be serialized and transmitted over the network.

Furthermore memory usage is significantly higher for interfaces running in separate programs, as all the common infrastructure for each interface must be duplicated in each process.

The default for this option depends on the client option qorus-client.remote (if this client option is not set, then the default value is True).

The remote value can be changed at runtime by using the following REST API: PUT /api/latest/jobs/{id_or_name}?action=setRemote

Note
The remote flag is considered to be managed by operations, which means that once an interface has been loaded into Qorus, if its remote flag is updated with the API, then those API-driven changes are persistent and will not be overwritten by subsequent loads of the interface by oload.

Job Active Flag

A boolean value giving the active status of the job; if not present, the default is True.

An inactive job is only run on demand; its schedule is ignored.

Job Schedule

A cron specification, either this value or the duration attribute must be set, but not both.

Job schedules follow the format of a cron job time specification; it is made up of 5 fields separated by spaces as follows:

Field Values
minutes 0-59
hours 0-23
days of month 1-31
months 1-12 (or 3-letter English month abbreviations: Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec)
days of week 0-7 (0 and 7 are Sunday, or 3-letter English day abbreviations: Sun, Mon, Tue, Wed, Thu, Fri, Sat)

Case is ignored when giving month or day of week abbreviations. A field may be an asterisk (*), which stands for all possible values in that field.

Lists and ranges are allowed (also ranges and lists of abbreviated names are allowed); examples:

  • 1,2,5,9
  • 0-4,8-12,15
  • mon-wed,thu,sat

A skip/repeat specification can be appended with an asterisk (*) or a range in the format "/number", which means that the job should run every number units (ie minutes, hours, days, etc) in the range. For example:

  • */2: means every 2 minutes (or hours, days, etc, depending on the field)
  • 0-12/3: means every 3 hours from 0 to 12 (if given in an hour field)

Because fields are separated by spaces, no spaces are allowed within a field.

Note
The day of a command's execution can be specified by two fields, days of month, and days of week. If both fields are restricted (ie, aren't *), the command will be run when either field matches the current time. For example, "30 4 1,15 * fri" would cause a command to be run at 4:30 am on the 1st and 15th of every month, plus every Friday.

Some examples:

  • run ten minutes after midnight, every day
    "10 0 * * *"
  • run at 2:35pm on the first of every month
    "35 14 1 * *"
  • run at 11 pm on weekdays
    "0 23 * * mon-fri"
  • run 34 minutes after the hour, every other hour, every day
    "34 */2 * * *"
  • run at 5 after 4am every Sunday
    "5 4 * * sun"
Note
The job's schedule value is considered to be managed by operations, which means that once a job has been loaded into Qorus, if its schedule is updated with the API, then those API-driven changes are persistent and will not be overwritten by subsequent loads of the job by oload.
Since
Qorus 2.7.0.p2 added support for the skip/repeat specification ("/number")

Job Run Skipped Flag

A boolean value telling the system if the job should be run immediately if the last scheduled run was missed due to system downtime or the job being disabled; if not present, the default is True

Job Expiry Date

An optional expiration date; the job will not be run (and will be automatically set to inactive) when the expiration date is reached.

Job Class Name

Indicates the class name of the job's class; this allows the job to have names that are not valid identifiers in the source language.

Job Language

The programming language used for the job implementation.

Job Source Code

The implementation of the job must be made in the programming language given by Job Language; the main job class must inherit one of the following classes depending on the source language:

The job's logic will be executed by calling the run() method for the job, unless a run trigger for a finite state machine or class connection has been defined; in that case the job's source code is ignored.

Example Python Job Definition: example-job-v1.0.qjob:
class PythonSimpleTest(job.QorusJob):
def run(self):
UserApi.logInfo("job info: %y", getInfo())
Example Java Classpath Tag Value
classpath: $OMQ_DIR/user/jar/my-jar-1.jar:$OMQ_DIR/user/jar/my-jar-2.jar 
Example Java Job Definition: MyJavaExampleJob.java
package com.qoretechnologies.qorus.example;
import qore.OMQ.UserApi.Job.QorusJob;
class MyJavaExampleJob extends QorusJob {
// the run method implments the job's logic
public void run() throws Throwable {
logInfo("test job info: %y", getInfo());
}
}
Note
  • The classpath tag can be used to add entries to the classpath for Java classes; $OMQ_DIR can be used in classpath entries as in the above example and will be resolved to the Qorus directory; see Java Classpath Handling in Qorus for more information
Example Qore Job Definition: example-job-v1.0.qjob:
%new-style
%require-types
%strict-args
%enable-all-warnings
class MyExampleJob inherits QorusJob {
# the run() method implements the job's logic
run() {
logInfo("job info: %y", getInfo());
}
}
Note
  • Job logic defined in the run() method of a job class can be implemented by Finite State Machines / Flow Designer instead; in case a Finite State Machine has the run trigger in a job, the run() method logic defined in the job class will never be executed, and the method body should remain empty.
  • The run method can also be implemented by a class connection using the run trigger

Job Library

Jobs support library objects that provide additional code for the job.

See also
Library Objects for more information

Job Mappers

An optional list of mappers that are used in the job.

See also

Job Value Maps

An optional list of value maps that are used in the job.

See also

Job Groups

An optional list of interface groups that the job is a member of.

Note that the job will be disabled if any of the interface groups is disabled; additionally, interface groups provide the ability to restrict users from accessing unauthorized configuration or data.

See also
Interface Groups for more information

Job Modules

This attribute provides a list of Qore-language modules that are loaded in the job's logic container that can provide base classes for the job class as well as other functionality for the job.

See also
Qore-Language Job Extension Modules for more information.

Job Constructors and Static Initialization

Job classes can have a constructor and classes can have static initialization, but a job constructor cannot require any arguments.

Job Configuration Items

Jobs can declare configuration items as metadata to allow the behavior of the job to be modified by users at runtime using the operational web UI or the REST API.

Job configuration items are:

  1. Created by oload when loading the job
  2. Read at runtime with job APIs to affect the functionality of the job
  3. Updated using the web UI using the REST API with PUT /api/latest/jobs/{id_or_name}/config/{name}

Job configuration items are designed to allow users to affect the execution of a job so that changes can be made by authorized users in the UI without requiring a change to development.

Note
All configuration item values are considered to be managed by operations by design, which means that once a configuration item has been loaded into Qorus, any changes to its value with the API are persistent and will not be overwritten by subsequent loads of the configuration item by oload.

Strictly Local Job Config Item

If the strictly_local flag is True, then the job configuration item is local and the value for the configuration item cannot be set on the global level.

If the strictly_local flag on a job configuration item is False (the default), then the job configuration item is not local and the value can also be set on the global level.

Note
All configuration item values are considered to be managed by operations by design, which means that once a configuration item has been loaded into Qorus, any changes to its value with the API are persistent and will not be overwritten by subsequent loads of the configuration item by oload.
See also
Config Items: Code to No-Code Runtime Configuration for Your Code