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

ScheduleId	Unique 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.
Name	Descriptive name intended for end user (free text field). Should be appropriate for the end user to select a schedule
Description	Descriptive text or comment (free text field)
Alias	Optional alias, which will be applied to all jobs being created from this schedule. No two schedules can have the same alias.
TemplateId	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).
JobDescription	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).
WorkerHost	Name of the host to process the jobs being created by this schedule.
ResumeInterruptedJob	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.
Disabled	Optional field. While set to true, the whole schedule is disabled, so no occurrences apply.
Standby	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.
TimePlan	Specification of times to create and run a job (see below)
Creator	Optional information about the client, which created (or updated) the schedule object (see below).

Fields of TimePlan

TimeZone	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.
FrameCondition	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.
FirstStart	Optional: date+time to limit the first occurrence
LastStart	Optional: date+time to limit the last occurrence
NumOccurrences	Optional: Count to limit the occurrences - This field is not yet implemented and is being ignored.
Recurrences	A list of definitions when to run a job. At least one recurrence must be provided, otherwise it won't occur.
Start	date+time as reference to pattern definitions; if pattern defines once, this is the occurrence time.
Duration	Duration of the scheduled job (in milliseconds). A value of zero means the job is not ended by scheduling.
KeepDuration	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
Pattern	Optional: Defines in which interval to run the job If pattern is missing, the job is run once.
Cycle	Define if to run the job Once, Daily, Weekly, Monthly or Yearly
Step	Repeat cycle step. 1 means every time the cycle applies, 2 means every second time, etc. 1 is default, if not specified.
Weekdays	Optional: Defines on which weekdays to run (not valid for daily pattern).
Weekday	One of the 7 weekdays
OffsetInMonth	Number 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.
TimeOffset	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 type	Format	Description
date+time	'YYYY'-'MM'-'DD'T'hh':'mm':'ss[.fff]['Z'] 'YYYY'-'MM'-'DD'T'hh':'mm':'ss[.fff]['Z'] 'YYYY'-'MM'	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"
num	Integer number (32 bit)	Example: 42
num64	Integer number (64 bit)	Example: -86400000
cycle	Enumeration of cycle types	One of: Once, Daily, Weekly, Monthly, Yearly
timeZoneId	Name 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.
weekday	Enumeration of week days	One of: Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday
hostName	Name 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.

Id	Identifier for the creating client, prefer a GUID which is fix in the client's source code.
Name	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.
Description	A descriptive text about this client which might be shown in a message to the user.
Version	Version string, which might be considered for decision about possible incompatibilities.

JSON Spec

This is the principal specification of the schedule JSON format.

Schedule JSON Spec

JS

{
    "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

JS

{
    "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"
        },
        "recurrences":[
            {
                "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"
	}
}