api/schedules
Contents
About Schedules
Schedules serve to prepare a job to run at a later time or recurrently following a time pattern.
A schedule contains a scheduling of a job template with optional recurrences. For every time the schedule hits, a new job will be created from this template (template data is documented in Templates Data) or a specific job description. Further explanations can be found in Understanding ROAD Schedules.
For general understanding of ROAD data types and especially ROAD jobs, see Jobs Data.
Schedule Data
A schedule contains some describing information, a reference to a job template and time plan, which specifies when to run a job from the template. Schedule data is documented in Schedule Data.
Schedules are supported only in an installation with database.
Use Cases
- Plan a job to run once at a specific date and time in the future.
- Plan a job sequence to run in future (e.g. daily at the same time or every last Sunday in October)
- Get a specific schedule, display it in a GUI and allow the user to see (and edit) it.
- Search for schedules
- Get or update a single schedule (optionally restarting a running job)
- Create a new schedule
- Delete a schedule
Interface Usage
REST philosophy is a bit different from function-centric thinking. So to fulfill best practices, we use resource-centric interfaces:
| URI | Verb | Parameters (optional) | Success Result | Description |
|---|---|---|---|---|
| schedules | GET | (see below) | OK = 200 | Get data for all existing schedules (completely or specific fields). Examples: Note: If no matching schedule is found, the result value is not 404 (not found) - instead an empty results list will be returned. |
| schedules/{scheduleId} | GET | (see below) | OK = 200 | Get an existing schedule's data (completely or specific fields). Example: <uri>/api/schedules/5c8fd7aa8775951f98d11c9d?fields=name, timePlan.recurrences.pattern.cycle Note: If the schedule is not found, the result value is 404 (not found). |
| schedules | POST | Created = 201 | Creates a new template object, returning its ScheduleId. BODY must contain a json-formatted schedule which contains at least the field "Name". All other fields are optional to enable preparing incomplete schedules. | |
| schedules/{scheduleId} | PUT | (ResetOccurrences) | OK = 200 | Updates an existing schedule object by replacing it with the new BODY's json-formatted schedule. Notes: If the schedule is not found, the result value is 404 (not found). If the schedule is not changed, the result value is 304 (not modified). |
| schedules/{scheduleId} | DELETE | (ResetOccurrences) | OK = 200 | Deletes a schedule Note: If the schedule is not found, the result value is 404 (not found). |
PUT, DELETE: Supported Parameters for schedules
There is one optional parameter for a PUT and DELETE schedules request.
| Parameter | Description | Example |
|---|---|---|
ResetOccurrences (default=false) | If this parameter is false or missing, running jobs for this schedule are not affected by changes. The usual cycle of checking for pending schedules remains untouched then. If this parameter is provided, this means:
| ResetOccurrences=true |
GET: Supported Parameters for schedules
Optional Query Parameters (for all GET requests)
| Parameter | Description | Example |
|---|---|---|
fields (see below) | Limit the response to specified fields
| fields=scheduleId, name |
filter | Search filter. See Query Expressions for a detailed description. See below for fields which are supported by this interface.
| filter=name=="Test Schedule" |
sort | Sort order. Comma-separated list of sort fields. An optional "asc" or "desc" can be added after each field name (separated by space). | sort=name, description desc |
offset skip | Offset in results list (default: 0) offset and skip are synonymic | offset=100 |
| limit | Limit the result list size (default: 100) | limit=100 |
count | Only evaluate the count of matching jobs. Only pass the parameter name count without any value. Filters are considered, but fields, sort, skip and limit are ignored. Returns a count object like { "count": 42 } | count |
pending (see below) | Query pending occurrences of all or of a specific schedule. A time range to be considered can be passed. | pending=now,2019-12-31 |
clientTimeZone (see below) | Specify a time zone for the returned pending times of a pending query.
| clientTimeZone=W. Europe Standard Time |
refTime (see below) | Specify a date+time which counts instead of now for a calculating nextOccurrence time. This time is always expected to be in UTC.
|
pending Parameter
The (optional) pending parameter directs the ROAD Service to find all occurrences of schedules pending in a time range. It can be combined with a scheduleId to query only this one instead of all. Further filtering is currently not supported.
To specify a time range the start and end time can be provided to this parameter like this: pending=<start>, <end>
The times being passed for this range are considered to be either in the host's local time zone or in one specified by parameter clientTimeZone (see below).
If there is any schedule detected to be invalid while processing this request, this schedule is completely ignored in the pending query. Then no error is returned to sustain the whole request for pending schedules. But if the pending request is referring to one specific schedule (by providing a scheduleId), then an error is returned in this case.
Examples:
- schedules/5db97a72877595155cc55c43?pending=2019-11-11, 2019-12-31T13:33:00: Queries for all occurrences of the specified schedule from 11-November-2019 at 0:00:00 until 31-December-2019 at 13:33:00
- schedules?pending: Queries for all occurrences of all schedules from now until one month from now (
is one month our default 
) - schedules?pending=now: Queries for all occurrences of all schedules from now until one month from now ( is one month our default )
The result of this query is a list of schedule specifications with these fields:
| Field Name | Description |
|---|---|
| pendingTime | Time of one pending occurrence, converted to the requested client time zone and containing the resp. UTC offset. (Example: "2021-06-04T18:00:00+02:00", meaning 20:00:00 for CEST) |
| scheduleId | Unique id of a schedule |
| name | Name of the schedule |
clientTimeZone Parameter
The clientTimeZone parameter can optionally be specified as addition to the pending parameter. It specifies the time zone in which the resulting schedules' hit times are expressed. The supported time zone ids result from the Windows time zone specifications, which can be queried via the api/timezones interface. The ones supported by Dec 2019 are listed below.
If this parameter is not provided, the ROAD Service's local time zone is applied.
List of All Time Zones Supported by Dec 2019
fields Parameter
The (optional) fields parameter can contain one or several comma-separated column titles (case-insensitive). If this parameter is not used, the results' data will be provided completely. All job's field names can be passed in PascalCase or in camelCase.
Fields not existing in general or in a specific schedule will lead into not providing these fields in the result.
Fields of sub-objects are specified by the dot syntax (see in table).
For a complete list of schedule fields see Confluence page Schedule Data. Here only some of the most important fields:
| Field Name | Description |
|---|---|
| scheduleId | Unique id of a schedule as created by the Service for a POST request |
| name | Title of a schedule |
| templateId | Id as reference to a template |
| workerHost | Name of the host to process the jobs being created by this schedule. As part of a filter specification "localhost" can be passed to specify the addressed Service host. |
| timePlan | Description of time frame, start time and recurrences for running a job from the referenced template |
| nextOccurrence | Returns information about the next (planned) occurrence of this schedule. By default it uses the current time as the reference unless the additional parameter refTime is provided. This field can only be retrieved by explicitly requesting it, because it is rarely of interest for a client and quite costly in performance regards. Results may be
Note this field is supported for fields parameter only - not for filter or sort. |
template.name, | Direct access to fields inside the referenced template; only available if there is a valid template specified by field templateId. Note these fields are supported for fields and sort parameters only - not for filter. |
| creator | Information about the client, which created (or updated) the schedule object. |
sort Parameter
The (optional) sort parameter can contain one or several comma-separated sort criteria. Sort criteria are applied in their order, i.e. the second criteria is applied only where found entries' first field is identical. Each criteria can get an additional sort direction (ascending/asc or descending/desc), where ascending is default.
Example: sort=name, createdTime desc
Supported fields for sorting are all schedule fields (see Schedule Data). Not supported are the special field NextOccurrence and sub-fields inside a template (template.name etc.).
Schedule Data as REST Body
Where schedule data is transferred with a REST request to ROAD Service or response from ROAD Service, it is formatted as a JSON. This JSON's structure corresponds to the data structure as described in Confluence page Schedule Data.
The provided fields may be incomplete.
- A schedule creation request (HTTP POST) contains the fields to be set initially, where only "Name" is mandatory.
- A schedule update request (HTTP PUT) will replace the template with the new one provided. The field ScheduleId must not be provided.