Jobs Guide

The server-side Jobs API and service allows you to run code periodically in the background for a variety of use cases. A number of different Job types can be scheduled.

By their nature, Jobs are imperfect due to the fact that the can only run when there are free cycles during the execution tasks the server is currently handling, like client requests.

For the most part Jobs run as close to their intervals as possible, with a variance of about 10 seconds in the worst case scenarios.

Management

All Job management is done using the Coronium Core Webmin in the Jobs Service section.

Viewing Jobs

To view all current Jobs, navigate to the Jobs Service section. You will be presented with a list of Jobs, including information such as the current status, last run time, and other information.

Creating Jobs

To create a new Job, navigate to the Jobs Service section and click the New Job button. Enter the requested information in the Job creation form. There is ample help and validation feedback directly on the form.

When you are done inputing your Job information, click the Create button. You will then be redirected to the Job code editor to create your Job code. See Writing Jobs.

Run Once

When creating a Job, you have the option of setting it to Run Once. This marks the Job so that it will only run one time on the booting of the Coronium Core server (after its initial interval). These can be useful for Jobs that only need to run once during the lifetime of the Coronium Core service. They will not run again on a service reload.

Editing Jobs

To edit an existing Job, navigate to the Jobs Service section. On the Job listing, click any Job name to edit the Job using the form presented.

When you are done editing your Job, click the Update button. See also Reloading Jobs.

To edit your Job code see Editing Job Code.

Removing Jobs

To remove a Job from the service, enter the Job editing mode (see Editing Jobs above). Click the Delete button, and then confirm the Job removal.

This is a destructive action, and cannot be undone.

Reloading Jobs

After adding or editing Job details, you will need to reload the Job service. In the Jobs Service section, click the Reload button to start the reload process.

You may need to wait for up to 60 seconds for the Job service to reload. While you're waiting, the service status will change to "Reloading". Once the reload process is complete, the status will return to "Running".

Jobs that have aleady been running will not have their interval reset. For example, let's assume a Job is set to run every 120 seconds, and a reload is issued at 60 seconds in. On reload, that Job will retain its remaining run time, in this case 60 seconds.

Job Status

In the Jobs Service section, you will see various status icons in the Job listing depending on how the Job was returned (see Job Returns below).

The following table describes the various status icons, and the return that initiates them. In the Jobs listing, you can hover your mouse over any icon to see more information.

Status Icon	Status Description	Return Type
	Is active and recurring or active and waiting to run.	job.OK
	Is active and will run again 24 hours after its last run.	job.SLEEP
	Is active but will not run again until a reload event is issued.	job.STOP
	Is not active, and will not run until reactivated manually.	job.EXIT
	This Job has been marked as Run Once but has not run yet.	See Run Once
	This Job has Run Once and will not run until a service reboot.	See Run Once

Job Errors

If any critical errors occur, or the Job file cannot be found when a Job is run, it will automatically be set to a deactivated state and will not run again until manually reactivated and a reload is issued.

Writing Jobs

Once you've created a Job (see Creating Jobs) you will be taken to the Job code editor to add your Job code.

All core modules are available for use in Job files. It is not possible to return responses to clients from Jobs (see Lifecycle/Context).

Creating Job Code

Once you have created your Job, you will be taken to the code editor and presented with a Job template.

Job Template

local job = core.job()

function job.run()
  --== Place your job code here

  return job.OK
end

return job

All of your Job code must be placed in the job.run() method to be run. When your Job work code is finished you must then return a valid Job status type (see below).

Failure to return a valid Job status will deactivate the Job when run.

Job Returns

Job returns determine how your Job will operate on its next run. The most common return is job.OK which keeps a job running in a recurring fashion.

To understand what each return type does, see the Return section of the Jobs API.

Job Helpers

Helpers are a group of methods that return the current minute, hour, day, etc. to help fine tune when your Job runs. To learn more about each helper see the Helpers section of the Jobs API.

Helper Example

local job = core.job()

function job.run()

  if job.day() == "Fri" then
    core.log("Do some Friday work")
  end

  return job.SLEEP

end

return job

In the example above we use the job.SLEEP return since we only need to check for a day on a daily basis.

Because Job intervals are imperfect, some helper types work better with certain return types. For instance, you may have unpredictable results when using the job.minute or job.hour helper with the job.SLEEP return.

Instead create a recurring Job that runs at least every 30 seconds to check for minute resolutions, or a Job every 30 minutes to check an hour resolution. You would want to use the job.OK return in these situations.

Editing Job Code

To edit existing Job code, navigate to the Jobs Service section, and click any of the links in the File Path column. This will take you to the Job code editor with the requested Job code loaded into the editor.

Once you've edited your code be sure to save it. While not required, you should issue a reload when finished.

Example Code

After creating your Job (see Creating Jobs) you can regulate them by the return status in your code.

Recurring

This Job will keep running at its set interval by returning job.OK

local job = core.job()

function job.run()

  --check stock
  local bikes, err, code = core.mysql.selectOne("products", {
    tbl = "toys",
    columns = { "stock" },
    where = { type = "Red Bikes" }
  })

  --update status
  if bikes.stock == 0 then
    local res, err, code = core.mysql.update("products", {
      tbl = "toys",
      values = { out_of_stock = true },
      where = { id = bikes.id }
    })
  end

  return job.OK
end

return job

Sleep Job

This Job will stop special sales on Sundays. Checks the day every 24 hours using job.SLEEP.

local job = core.job()

function job.run()

  if job.day() == "Sun" then
    local res, err, code = core.mysql.update("shop", {
      tbl = "status",
      values = { no_specials = true },
      where = { no_specials = false }
    })
  end

  return job.SLEEP
end

return job

Stop Job

This Job will send daily sales reports during January. And return job.STOP otherwise.

local job = core.job()

function job.run()

  local res, err, code = core.mysql.selectOne("shop", {
    tbl = "status",
    columns = { sales_total },
    where = { month = "Jan" }
  })

  if job.month() == "Jan" then
    local msg = core.email.new()
    msg:to("boss@work.com")
    msg:from("job@work.com")
    msg:subject("January Daily")
    msg:body("Sales today were: $"..res.sales_total)
    msg:send()

    return job.SLEEP
  else
    return job.STOP
  end
end

return job

Exit Job

This Job will deactivate returning job.EXIT if an error occurs with the query.

local job = core.job()

function job.run()

  local res, err, code = core.mysql.selectOne("products", {
    tbl = "toys",
    where = { type = "blender" }
  })

  if not res then
    core.log(err)
    return job.EXIT
  else
    return job.OK
  end

end

return job

Run Once Job

This Job will run once. The proper return type is job.OK for Run Once jobs.

local job = core.job()

function job.run()

  local config_tbl, err = core.network.getJson("https://some.json-config.com")

  local config, err = core.data('config')

  local id, err = config:save(config_tbl)

  return job.OK
end

return job