ScheduledJob

From Ocean Framework Documentation Wiki
Jump to: navigation, search

ScheduledJobs are asynchronous jobs which run once, at a particular point in time. They have the same basic syntax and semantics as AsyncJobs (except they do not have a token attribute), but instead of a CRON control string they take a date and time string.

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

/v1/scheduled_jobs

The second public URL is:

/v1/scheduled_jobs/execute

Structure

name
(String) An optional name for this ScheduledJob.
description
(String) An optional description of this ScheduledJob.
enabled
(Boolean) Whether this ScheduledJob is enabled to run or not. Defaults to true.
run_at
(String) When to run this ScheduledJob. Should be UTC and in ISO format, e.g. "2015-12-01T18:40:00Z". The seconds are ignored; the granularity of the service is one minute.
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 ScheduledJob 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 ScheduledJob, 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 ScheduledJob turns poison. (read only)
created_at
(String) The datetime when this ScheduledJob was created. (read only)
updated_at
(String) The datetime when this ScheduledJob was last updated. (read only)
last_run_at
(String) The datetime when this ScheduledJob was last run. (read only)

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 ScheduledJob resource are:

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


GET self

Retrieves a ScheduledJob resource.

200
The operation was successful.

PUT self

Updates a ScheduledJob 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 ScheduledJob resource.

204
The delete operation was successful.

PUT run

Runs the ScheduledJob resource.

204
The operation was successful. No body was returned.

GET /v1/scheduled_jobs

Returns the collection of ScheduledJobs.

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

POST /v1/scheduled_jobs

Creates a new ScheduledJob resource.

  • Required attributes:
    • credentials
    • run_at
    • 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 ScheduledJob 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 ScheduledJob resource in the response body.

PUT /v1/scheduled_jobs/execute

Examines the collection of ScheduledJobs and runs any jobs due. (Called once a minute by an Ocean CronTask.)

204
The operation was successful. No body was returned.