CronJob

From Ocean Framework Documentation Wiki
Jump to: navigation, search

CronJobs are asynchronous jobs which run periodically. They have the same basic syntax and semantics as AsyncJobs (except they do not have a token attribute), but they also have a Unix CRON compatible control string to specify when they are to run. The full Unix CRON syntax is supported. A small number of CronJobs are set up by default in the system to perform cleanup and maintenance tasks automatically.

The CronJob resource has one public URL. (For information about the difference between Public and Internal URLs and HATEOAS conventions, please see API Structure and Conventions.)

/v1/cron_jobs

Structure

name
(String) An optional name for this CronJob.
description
(String) An optional description of this CronJob.
enabled
(Boolean) Whether this CronJob is enabled to run or not. Defaults to true.
cron
(String) When to run this CronJob. The syntax of this string is described below and is in standard CRON format. All standard CRON features are supported.
steps
(Array) An array of job steps. The syntax and semantics are exactly the same as for AsyncJobs.
default_step_time
(Integer) The maximum time a job step is assumed to take by default (this can be overridden for each separate job step). Default 30 seconds. If the job should fail for any reason, this is the amount of time it will take before the job is considered again.
default_poison_limit
(Integer) The number of job step restarts after which the whole job is to be regarded as poison and removed from the queue (the creator will be notified). Default: 5. The limit can be overridden per job step, and the count is cleared before each step starts.
max_seconds_in_queue
(Integer) The maximum number of seconds this CronJob may exist in the queue. Default: 1 day (86400 seconds).
credentials
(String) The username and password (Base64 encoded, cf. POST to Authentications) to use in re-authentication. This attribute is required when creating a CronJob, but will never appear in any external resource representation.
poison_email
(String) This email address, if present, will receive email notification when an AsyncJob executing this CronJob turns poison. (read only)
created_at
(String) The datetime when this CronJob was created. (read only)
updated_at
(String) The datetime when this CronJob was last updated. (read only)
last_run_at
(String) The datetime when this CronJob was last run. (read only)

CRON expression

The cron attribute must contain a CRON expression string to control when the CronJob is to run. A CRON expression is a string comprising five fields separated by whitespace.

Format

Field name Mandatory? Allowed values Allowed special characters
Minutes Yes 0-59 * / , -
Hours Yes 0-23 * / , -
Day of month Yes 1-31 * / , -
Month Yes 1-12 or JAN-DEC * / , -
Day of week Yes 0-6 or SUN-SAT * / , -

Special characters

Asterisk ( * )
The asterisk indicates that the cron expression matches for all values of the field. E.g., using an asterisk in the 4th field (month) indicates every month.
Slash ( / )
Slashes describe increments of ranges. For example 3-59/15 in the 1st field (minutes) indicate the third minute of the hour and every 15 minutes thereafter. The form */... is equivalent to the form "first-last/...", that is, an increment over the largest possible range of the field.
Comma ( , )
Commas are used to separate items of a list. For example, using MON,WED,FRI in the 5th field (day of week) means Mondays, Wednesdays and Fridays.
Hyphen ( - )
Hyphens define ranges. For example, 2-12 in the fourth field indicates every month between February and December, inclusive.

Predefined scheduling definitions

Several special predefined values can be used as shorthand values for the cron attribute.

Entry Description Equivalent to
@yearly (or @annually) Run once a year at midnight on the morning of January 1 0 0 1 1 *
@monthly Run once a month at midnight on the morning of the first day of the month 0 0 1 * *
@weekly Run once a week at midnight on Sunday morning 0 0 * * 0
@daily Run once a day at midnight 0 0 * * *
@hourly Run once an hour at the beginning of the hour 0 * * * *
# * * * * *
# ┬ ┬ ┬ ┬ ┬
# │ │ │ │ │
# │ │ │ │ │
# │ │ │ │ └───── day of week (0 - 6) (0 to 6 are Sunday to Saturday, or use names)
# │ │ │ └────────── month (1 - 12)
# │ │ └─────────────── day of month (1 - 31)
# │ └──────────────────── hour (0 - 23)
# └───────────────────────── min (0 - 59)

Examples

The following specifies that the CronJob is to run at one minute past midnight (00:01) of every day of the month, of every day of the week:

1 0 * * *

This example runs the CronJob at 20:00 every day:

0 20 * * *

The following cron value runs the CronJob every two hours, at midnight, 02:00, 04:00, 06:00, 08:00 and so on:

0 */2 * * *

This example runs the CronJob every six minutes during the first 30 minutes of each hour, but only during office hours on Mondays, Wednesdays, and Fridays:

0-29/6 9-17 * * MON,WED,FRI

The following runs the CronJob on midnight on the morning of the first day of every month:

@monthly

This runs a spooky CronJob at midnight on Friday the 13th:

0 0 13 * FRI

Hyperlinks

The following hyperlink names are used in the following subsections. To retrieve the URL and Content-Type to use, use the _links hash. Note that the URI may change, and thus you should make no inference on how to construct similar URIs from any previous URI. For more information, refer to Hyperlink URIs are Opaque. You may store hyperlink URIs in permanent storage for later use.

The hyperlinks for an CronJob resource are:

self
as always, the self hyperlink can be used to perform CRUD actions on the AsyncJob resource.
creator
the ApiUser who created this CronJob.
updater
the ApiUser who last updated this CronJob.
last_async_job
the AsyncJob used to handle the last run of this CronJob.


GET self

Retrieves a CronJob resource.

200
The operation was successful.

PUT self

Updates a CronJob resource.

PUT requests, according to the RFC standard, require all resource attributes to be updated simultaneously. However, in Ocean PUT requests have the same semantics as PATCH requests in that it's possible to set individual attributes. The API will reject requests with missing essential attributes. If you receive unknown properties, you must preserve them and pass them back unchanged in PUT and PATCH requests. Other than that, you should ignore them. This enables the API to be upgraded transparently.

200
The operation was successful.

DELETE self

Deletes a CronJob resource.

204
The delete operation was successful.

PUT run

Runs the CronJob resource.

204
The operation was successful. No body was returned.

GET /v1/cron_jobs

Returns the collection of CronJobs.

200
The operation was successful. The collection is returned as a JSON array in the response body.

POST /v1/cron_jobs

Creates a new CronJob resource.

  • Required attributes:
    • credentials
    • cron
    • steps
  • Optional attributes:
    • token
    • name
    • description
    • enabled
    • default_step_time
    • default_poison_limit
    • max_seconds_in_queue
    • poison_email
201
The operation was successful and a new CronJob resource has been created. The response headers will, as is customary, include a standard Location header giving the URI of the newly created resource. To save you the extra request Ocean also returns the new CronJob resource in the response body.