Jobs

Jobs are actions that a module can do, which are either done periodically or are triggered upon a certain outside event.

Scheduled Tasks

Jobs that are performed periodically are called scheduled tasks.

Modules can create scheduled tasks on a site with the Scheduled Task Manager Module running.

Any module that registers a scheduled task will be called upon periodically to perform an action (the frequency can be controlled by the administrator who enables the scheduled task, but you can specify a default frequency).

Incoming Email Handlers

Jobs that are performed when an email is received by the CMS are called incoming email handlers.

Modules can create incoming email handlers on a site with the Incoming Email Manager Module running.

Any module that registers an incoming email handler will be called upon whenever an email is received to process that email.

Writing a Job

From a Module developer's point of view jobs are a lot like signals, in that you need to create a static function to perform a job, which the manager module will then call when it wants to run the job.

However the key difference is that signals are sent upon a specific event inside the CMS and are usually called in the context of a visitor visiting a site, whereas jobs are called either periodically or due to an outside event such as an incoming email.

Logging Output from a Job

Each time a job is run, any output you echo will be logged.

Depending on how the Admin configures the job, this output will either be ignored, logged in a record in the database, or sent to a support address via email.

The Status of your Job

Each time your handler runs, it needs indicate one of three statuses: Action Taken, No Action Taken, or Error.

Action Taken

This means that your job ran successfully, and it did something.

Your function can record a status of Action Taken by returning true.

No Action Taken

This means that while your job ran successfully, there was not an action for it to take.

Your function can record a status of Action Taken by returning true.

Error

This means that something went wrong.

You can record a status of Error by echoing an error message, then calling exit in PHP rather than returning.

Reference for jobs: