Skip to main content
Skip table of contents

Schedule Data

About Schedules

Schedules serve to prepare a job to run at a later time or recurrently following a time pattern.

The description of the job to be created at the point in time when the schedule hits is specified either by a template being referred by the schedule or by a JobDescription inside the schedule. For every time the schedule hits, a new job will be created from this template (template data is documented in Templates Data). Further explanations can be found in Understanding ROAD Schedules.

For general understanding of ROAD data types and especially ROAD jobs, see Jobs Data.

Schedules are supported only in an installation with database.

Data Fields

Fields directly in schedule

ScheduleIdUnique ID of this schedule. Is exclusively created by the ROAD Service's schedules/POST command and is required for all later access to this schedule object.
NameDescriptive name intended for end user (free text field). Should be appropriate for the end user to select a schedule
DescriptionDescriptive text or comment (free text field)
AliasOptional alias, which will be applied to all jobs being created from this schedule. No two schedules can have the same alias.

ID of a job template, which is to be used for creating a job at times of occurrence. Requirements to such template are described in Specifying the Scheduled Jobs.

Alternatively the job to be created can be described inside the schedule by providing the field JobDescription (see below).


Describes the job to be created at times of occurrence. See Specifying the Scheduled Jobs and Job Description Data.

Alternatively the job to be created can be described by providing the ID of a job template in field TemplateId (see above).


Name of the host to process the jobs being created by this schedule.


false or true value, which defines if to resume a job, which was created by this schedule, but didn't run to its planned end time. (default = false)

See Prematurely Ending and Possible Resuming of the Job for more information.

DisabledOptional field. While set to true, the whole schedule is disabled, so no occurrences apply.

Optional field. If set to true, the schedule is meant to run a job always. This is intended for usage with external control or with control via Easy REST interface to have always a job prepared and waiting for signals to run.

For a standby job the whole timePlan is completely ignored.

Note a standby job should normally never stop, so instead of sending a finish request to it, there should be used a pause or pause with outputSwitch. In case the job nevertheless stops, it will get restarted when the ROAD ScheduleRunner component runs the next time by its usual cycle.

TimePlanSpecification of times to create and run a job (see below)
CreatorOptional information about the client, which created (or updated) the schedule object (see below).

Fields of TimePlan


Optional: Id of the time zone to be applied on all recurrences.

If this field is missing, the local time zone of the host processing this schedule is applied.


Optional: Specify a time frame in which the schedule can occur and/or an amount of occurrences (see below)

The frame condition is considered before planning the next scheduling time. It does not define when to run a job.

        FirstStartOptional: date+time to limit the first occurrence
        LastStartOptional: date+time to limit the last occurrence
        NumOccurrencesOptional: Count to limit the occurrences - (warning) This field is not yet implemented and is being ignored.
RecurrencesA list of definitions when to run a job. At least one recurrence must be provided, otherwise it won't occur.


date+time as reference to pattern definitions; if pattern defines once, this is the occurrence time.
        DurationDuration of the scheduled job (in milliseconds). A value of zero means the job is not ended by scheduling.

Defines for the case that a job is started too late, if to end it at calculated time or keep the duration. This may occur if a job was interrupted or if the Service was down while the schedule should have started.

true: The duration counts from actual start time of the job
false: The calculated end time (Start + Duration) is applied

Default is false


Optional: Defines in which interval to run the job
If pattern is missing, the job is run once.

                CycleDefine if to run the job Once, Daily, Weekly, Monthly or Yearly
                StepRepeat cycle step. 1 means every time the cycle applies, 2 means every second time, etc.
1 is default, if not specified.
        WeekdaysOptional: Defines on which weekdays to run (not valid for daily pattern).
                WeekdayOne of the 7 weekdays
                OffsetInMonthNumber of matching weekday inside month (0 = each, 1 = 1st, 2 = 2nd, -1 = last, -2 = second last, etc.).
Allowed values are in range -4 until 4.
0 is default, if not specified.

Optional: Time offset to be added to the time resulting from the former calculation. Is required e.g. to define a time of day after an occurrence day was selected by weekday specification.

An integer number specifying a number of milliseconds, can be negative.

Field Types

Field typeFormatDescription




Date + time in ISO 8601 formet. Note the suffix is always appended to values returned by the Service, indicating which UTC offset it relates to ("Z" means UTC). Values being sent to the Service don't need the suffix as they are always interpreted as local for the relevant time zone. If a UTC offset is specified, this only affects calculation of the time itself, but the specified time zone is not affected.

Note: Unless the optional post-comma part supports more digits, ROAD's resolution is restricted to milliseconds, so three post-comma digits.

Examples: "2019-10-20T08:00:00", "2019-10-20T08:00:00+02", "2019-10-20T06:00:00Z"

numInteger number (32 bit)Example: 42
num64Integer number (64 bit)Example: -86400000
cycleEnumeration of cycle typesOne of: Once, Daily, Weekly, Monthly, Yearly
timeZoneIdName of the time zone in Windows format

Example: "W. Europe Standard Time"

A complete list of supported time zone ids can be provided by the ROAD service via a specific REST API, which is not yet supported. See api/schedules for a list of time zone ids.

weekdayEnumeration of week days

One of: Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday

hostNameName of a computer to run jobs

Either the network name of the computer or an alias as it can be configured in the Service's config.

Name is normalized to an appropriate format.

Fields of Creator

The Creator information is intended to allow a client which opens, modifies and stores back a schedule to decide if there might be data inside a schedule, which it is aware of. For example when a schedule is being opened for editing, which was not created with this scheduling UI, it may contain a job description which not supported by this UI. When saving this schedule back, its configuration will be lost.

By information about the client which created (or updated) the schedule object a client can decide if to open it for editing or posting a confirmation message to the user, etc.

IdIdentifier for the creating client, prefer a GUID which is fix in the client's source code.

A user-friendly name of the application. This name is to be displayed to the user when they get a warning about possible incompatibility.

Should be unique for every type of client.

DescriptionA descriptive text about this client which might be shown in a message to the user.
VersionVersion string, which might be considered for decision about possible incompatibilities.


This is the principal specification of the schedule JSON format.

Schedule JSON Spec

    "ScheduleId": "5da886348775955c8c0d1025", // not to be passed in POST or PUT requests
    "Name": "Complete ROAD schedule",
    "Description": "This is a sample ROAD schedule",
    "TemplateId": "000000000000000000000000",
    "WorkerHost": "<hostName>",
	"TimePlan": {
        "TimeZone": "<timeZoneId>", // optional
		"FrameCondition": { // optional
			"FirstStart": <date+time>, // optional
			"LastStart": <date+time> // optional
		"Recurrences": [
				"Start": <date+time>,
                "Duration": 3600000, // 1 hour
                "KeepDuration": <false or true>,
				"Pattern": {
					"Cycle": "<cycle>", // <cycle> is one of: Yearly, Monthly, Weekly, Daily, Once
					"Step": <num> // repeat cycle step (1 = every time, 2 = every second time, etc.)
				"Weekdays": [ // optional - not supported for Daily Pattern
						"Weekday" : "<weekday>", // one weekday (Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday)
						"OffsetInMonth" : <num> // number inside month (0 = each, 1 = 1st, 2 = 2nd, -1 = last)
			"TimeOffset": <num64> // optional - time duration after resolving the pattern in milliseconds
    "creator": {
        "id": "<creating client id>",
        "name": "<creating client name>",
        "description": "<free text>",
        "version": "<version>"

Example JSON

This is a real example of a schedule JSON. Note the ScheduleId field must not be passed as part of the JSON to POST or PUT requests, but will be returned by queries.

Recurrence JSON

    "scheduleId": "5da886348775955c8c0d1025",
    "name": "Complete ROAD schedule",
    "description": "This is a sample ROAD schedule",
    "templateId": "000000000000000000000000",
    "workerHost": "workstation-v",
    "timePlan": {
        "TimeZone": "W. Europe Standard Time",
        "frameCondition": {
            "firstStart": "2019-10-20T08:00:00Z",
            "lastStart": "2020-10-15T08:00:00Z"
                "start": "2019-10-15T08:00:00Z",
                "duration": 3600000, // 1 hour
                "keepDuration": true,
                "pattern": {
                    "cycle": "Yearly",
                    "step": 1
                "weekdays": [
                        "weekday": "Saturday",
                        "offsetInMonth": 2
                "timeOffset": -86400000
    "creator": {
        "id": "35B57AC0-3BFF-42B6-AB59-1125AA177ABE",
        "name": "DAVID scheduling client",
        "description": "Standard client to maintain schedules either specifying a job description or referring to a job template",
        "version": "1.2.345.0"
JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.