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:

Success ResultDescription

(see below)

OK = 200
JSON formatted results list

Get data for all existing schedules (completely or specific fields).

<uri>/api/schedules?fields=name,, job.transitions&skip=0&limit=20

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
JSON formatted result

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).


Created = 201
{ "templateId" : "5c8fd7aa8775951f98d11c9d" }

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.




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:

  • PUT: In case that jobs are running which are caused by this schedule, they might need updates. This means those jobs will immediately be finished. Independent from the former state jobs will be (re-) started if the updated schedule specifies so. This includes occurrences in the past, if the schedule's field ResumeInterruptedJob is set and the duration is lasting or indefinite (Duration field is zero).
  • DELETE: Related jobs are finished immediately.

GET: Supported Parameters for schedules

Optional Query Parameters (for all GET requests)



(see below)

Limit the response to specified fields

(warning) fields in combination with parameter pending is not (yet) supported

fields=scheduleId, name


Search filter. See Query Expressions for a detailed description. See below for fields which are supported by this interface.

(warning) filter in combination with parameter pending currently only supoprts field workerHost

filter=name=="Test Schedule"


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 in results list (default: 0)

offset and skip are synonymic

limitLimit the result list size (default: 100)limit=100


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 }



(see below)

Query pending occurrences of all or of a specific schedule.

A time range to be considered can be passed.



(see below)

Specify a time zone for the returned pending times of a pending query.

(warning) clientTimeZone is only supported in combination with parameter pending

clientTimeZone=W. Europe Standard Time


(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.

(warning) refTime is only supported in combination with field nextOccurrence

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.


  • 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 ((warning) is one month our default (question))
  • schedules?pending=now: Queries for all occurrences of all schedules from now until one month from now ((warning) is one month our default (question))

The result of this query is a list of schedule specifications with these fields:

Field NameDescription

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)

scheduleIdUnique id of a schedule
nameName 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 NameDescription
scheduleIdUnique id of a schedule as created by the Service for a POST request
nameTitle of a schedule
templateIdId as reference to a template

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.

timePlanDescription of time frame, start time and recurrences for running a job from the referenced template

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

  • a date+time: the time of the next occurrence after now or the refTime. This date is always in UTC, independent from the time zone being specified for the schedule.
  • "running": If a job caused by this schedule is currently running (independent from the actual planned occurrences)
  • "continuous": If a job was planned for the past and there is no planned end of this job or the planned duration is to finish in the future. This might mean a job was started in the past and ended already - this may be expected or erroneous.
  • "none": In case no occurrence is there in future.

Note this field is supported for fields parameter only - not for filter or sort.,

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.

creatorInformation 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 ( 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.