Scheduler Jobs

Overview

Jobs are the individual runs of the specified function from a scheduler. This article will outline the various parts of a Scheduler Job.

Properties

• name : Name of the job
• scheduler_id : ID of the scheduler that created the job. This may be empty as schedulers are not required to create jobs
• execute_time : Time when job is ready to be executed
• status : Status of the job
• resolution : Notes whether or not the job was successful
• message : Contains messages produced by the job, including errors
• target : Function or URL called by the job
• data : Data attached to the job
• requeue : Boolean to determine whether the job will be replaced in the queue upon failure
• retry_count : Determines how many times the system will retry the job before failure
• failure_count : The number f times the job has failed
• job_delay : The delay (in seconds) between each job run
• assigned_user_id : User ID of which the job will be executed as
• client : The name of the client owning the job
• percent_complete : For postponed jobs, this can be used to determine how much of the job has been completed

Creating a Job

To create job, you must first create an instance of SchedulesJobs class and use submitJob in SugarJobQueue. An example is shown below:

  <?php

$jq = new SugarJobQueue();
$job = new SchedulersJob();
$job->name = "My Job";
$job->target = "function::myjob";
$jobid = $jq->submitJob($job);

echo "Created job $jobid!";

Job Targets

Job target contains two components, type and name, separated by "::". Type can be:

• function : Name or static method name (using :: syntax). This function will be passed the job object as the first parameter and if data is not empty, it will be passed as the second parameter.
• url : External URL to call when running the job

Running the Job

The job is run via the runJob() function in SchedulersJob. This function will return a boolean success value according to the value returned by the target function. For URL targets, the HTTP error code being less than 400 will return success.

If the function updated the job status from 'running', the return value of a function is ignored. Currently, the postponing of a URL job is not supported.

Job status

Jobs can be in following statuses:

• queued : The job is waiting in the queue to be executed
• running : The job is currently being executed
• done : The job has executed and completed

Job Resolution

Job resolution is set when the job is finished and can be:

• queued : The job is still not finished
• success : The job has completed successfully
• failure : The job has failed
• partial : The job is partially done but needs to be completed

Job Logic Hooks

The scheduler jobs module has two additional logic hooks that can be used to monitor jobs. The additional hooks that can be used are shown below:

• job_failure_retry : Executed when a job fails but will be retried
• job_failure : Executed when the job fails for the final time

You can find more information on these hooks in the Job Queue Hooks section.