/
Jobs

Jobs

The job extension is being phased out in favor of the task ext. See also Jobs and tasks.

Overview

The job extension is used to schedule and manage long running computing tasks in the background. The job extension may be used in two ways:

  1. any axon expression may be scheduled as a background task using the jobRun() function

  2. jobs may be permanently configured and scheduled to run periodically using the job, jobExpr, and jobSchedule tags; the Jobs app allows to do so through an easy user interface

Using Jobs

To use the Jobs app, click on the App Launcher and then select Jobs under the Advanced Apps section.

Jobs properties

 Once inside the Jobs app, at the upper section of the menu, the user can see the following options:

  • Create New

  • Debug

  • Log

  • Refresh

  • Backup

  • Restore

Create New

The Create New section, allows the user to create a new job. By clicking on it, the Create New Job window will pop up and the user must fill the following fields:

  1. Name : user must enter a name for the job,

  2. Function: In this field the user must enter the function that they want the job to run,

  3. Schedule: from this droplist, the user will select and configure how often the function is going to be automatically run.

 

Debug

The Debug section is that part of the Jobs app, that allows the user to see some information useful in the debug process of the job.

Log

The Log menu is the section that displays all the log messages. This part of the app is useful to check errors and debug issues that prevent the jobs working as they are expected.

Backup

This tool allows the user to create backups of their jobs, that can be saved on their local environment. Click on the following link for detailed information about Download

Restore

This tool allows the user to restore any of previously saved jobs into the current database project.  Click on the following link for detailed information about Upload

Jobs

In this section, the user can see a list of all the enabled/disabled jobs in the current project, followed by jobs last status value

Job editing

In order to edit an existing job, the user must select a job from the right side menu, under the Jobs section and click on it. After entering the job, the user will notice that the  menu is divided in two sections:

  • Actions

  • Job edit section

Actions

This section allows the user to do the following actions:

  • Run: manually run the job

  • Duplicate: duplicate the job

  • Trash: delete the job

  • Disable: the job will no longer be automatically resumed 

Job edit section

This section allows the user to edit the following job attributes:

  • Name: user can change the name of the job

  • Func: user can change/modify the job function

  • Schedule: user can edit the job schedule

  • Run time:view how long it took to run the job last

  • Last Status: view the status of the last attempted run cycle

  • Time: the actual time the last time the job ran

Advanced topics

Job Functions

The following Axon functions are used to create background tasks:

  • jobRun(): kick off an expression in the background

  • jobIsRunning(): check if your code is evaluating in context of job

  • jobProgress(): used to advance job's progress bar and update users what your job is currently doing

When the jobRun function is called it creates a background job and assigns it an opaque handle string. This handle may be used with functions such as jobStatus and jobLog() to monitor the status of the job.

Typically a function is written to be run in the context of a job. Here is a simple example:

() => do echo("TestJob start...") 10.times(i => do jobProgress(i*10, echo("TestJob " + i + "...")) jobSleep(1sec) end) echo("TestJob done!") end

To test it out create this function and give it a name like myTestJob and then run this expression in the Axon tool:

jobRun(myTestJob)

The function will be scheduled to run, and assuming you don't have other jobs running it should immediately execute on a background thread. The job extension tool will show your job and indicate the progress. The example code above will print messages to stdout every second for ten iterations.

Scheduled Jobs

You can configure scheduled jobs in the job extension tool. Scheduled jobs are recs with these three tags:

  • job: marker tag

  • jobExpr: the Axon expression to run (typically function name)

  • jobSchedule: when to run the job

The job scheduling tag uses a special string format we call a schedule rule:

  • one-shot jobs are scheduled to run once at a given date time:

    • onetime 2010-07-04T12:00:00-04:00 New_York

  • every jobs are scheduled to run periodically with a given interval:

    • every 15min: run every 15 minutes

    • every 2hr: run every 2 hours

  • at jobs are scheduled to run at one or more times of day:

    • at 00:00: run at midnight every day

    • at 9:00,18:00: run at 9am and 6pm every day

  • on jobs are scheduled to run only on given days at a given time:

    • on sun at 2:00: run every Sunday at 2am

    • on 1,15 at 12:00: run on the 1st and 15th of each month at noon

Jobs report their status from their last run using the following tags:

  • jobLastRuntime: duration of last run

  • jobLastStatus: status last run: doneCancel, doneErr, doneOk

  • jobLastTime: timestamp when job finished (success or failure)

Job scheduling is based off the jobLastTime tag. If this tag cannot be updated properly, then the job cannot be correctly scheduled. For this reason jobs are not scheduled if the database is not in read-write mode.

Jobs which run every hour or more frequently are called high frequency jobs. High frequency jobs only update their status transiently. This avoids writing job status to disk which is a costly operation. However it means that high frequency jobs will be re-run immediately after every reboot.

If the disabled marker tag is applied to a scheduled job, then it will not automatically run. However it can still be run manually using the jobRun() function.

Tuning

By default, the job extension will run up to 10 concurrent jobs. You can tune this by editing the job ext record and setting maxRunning the desired value.

// set maxRunning to 5 diff(read(ext=="job"), {maxRunning: 5}).commit

The job extension will keep the logs from the previous 20 jobs available in-memory. For jobs that do extensive logging, this can quickly consume heap. You can tune how many job logs are kept in memory by editing the job ext record and setting maxFinished to the desired value.

// set maxFinished to 10 diff(read(ext=="job"), {maxFinished: 10}).commit

Security

Jobs are executed in an axon context using the local user with the username "job". Use the userAllow function to grant specific superuser functions to your jobs. The job user account must not be configured with the "su" role or it will not be used.

If no user is defined by the username "job", then an inferred synthetic user with the "admin" role is used for all evaluations. The synthetic user has its projAccessFilter set to restrict access to the local project only. XQuery to other projects is not available.

Remember that by default all admin users can create/edit jobs. So it is important restrict what can be performed by jobs using the user database.

If testing changes to the job user account, you can call jobRefreshUser() to force an immediate cache refresh.