Skip to main content

Event Schedule API

This API is based on the Device Configuration API framework. For guidance on how to use these APIs, please refer to Device Configuration APIs.

warning

This API is in BETA stage. The API is provided for testing purposes and is subject to backward-incompatible changes, including modifications to functionality, behavior, and availability. Please don't use in production environment.

Overview​

The Event Schedules API is used to manage scheduled events sent by the event system according to certain schedules.

There are two types of schedules: pulse schedules and interval schedules.

The schedule type is determined by the DTEND part of the schedule definition:

  • If DTEND is present, the schedule is of the interval type.
  • If DTEND is not present, the schedule is of the pulse type.

Schedules are defined using a format based on the iCalendar format specified by RFC 5545.

Pulse schedules​

Pulse schedules are stateless events with no current value that are sent with a certain frequency and represent a single instant in time.

Pulse schedules recur with a frequency specified by the RRULE part of the schedule property. Such schedules either don't include a DTEND or include a DTEND equal to DTSTART.

For example, a pulse that occurs every second is defined as follows:

DTSTART:19700101T000000\nRRULE:FREQ=SECONDLY;INTERVAL=1

While a pulse that occurs every five minutes is defined as follows:

DTSTART:19700101T000000\nRRULE:FREQ=MINUTELY;INTERVAL=5

Interval schedules​

Interval schedules are stateful events with a value that represents whether a schedule is valid at a given time. They have a certain field which is set to 1 if the schedule is within bounds and 0 if it is outside at any given time.

An interval schedule is defined using a combination of DTSTART, DTEND, and RRULE. Depending on the requirements, the responsibilities for defining the schedule can be distributed across these three parts in different ways.

  • DTSTART specifies the first instance of the interval.
  • DTEND specifies the date and time at which the first interval ends. Thus DTSTART and DTEND together define a duration starting from DTSTART.
  • RRULE specifies the recurrence of this interval.

Daily schedule

A daily schedule, for example, valid between 9.30 and 17.00 every Tuesday and Wednesday uses DTSTART and DTEND to define the times of day during which the schedule is active, while RRULE specifies the days on which it applies.

DTSTART:19700101T093000\nDTEND:19700101T170000\nRRULE:FREQ=WEEKLY;BYDAY=TU,WE

In this example, DTSTART and DTEND define an interval starting at 09.30 and lasting 7.5 hours, while RRULE specifies that this interval recurs weekly on Tuesdays and Wednesdays.

This means that DTSTART defines the start of the first occurrence as well as the pattern for subsequent occurrences, while the duration between DTSTART and DTEND is preserved in a way that makes the interval remains the same for each occurrence.

Weekly schedule

A weekly schedule, for example, running from Monday 08:00 to Friday 16:30 would have the following property value:

DTSTART:19700105T080000\nDTEND:19700109T163000\nRRULE:FREQ=WEEKLY

DTSTART specifies the first applicable Monday at 08.00, DTEND specifies the first applicable Friday at 16.30 while RRULE specifies that it should be repeated every week (FREQ=WEEKLY). Another way to read it can be: We define an interval which should recur every week, starting from the 5th of January 1970 at 08.00, for a duration equal to the interval from the first occurrence up to the 9th of January 1970 at 16.30.

Monthly and yearly schedules can be defined in the same way as weekly schedules: DTSTART specifies the first start time, DTEND specifies the first end time, while RRULE governs the repetition.

Use cases​

Get root entity​

Example:

curl --request GET \
  --anyauth \
  --user "<username>:<password>" \
  --http1.1 \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/scheduled-events/v2
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success",
    "data": {
        "schedules": [
            {
                "id": "Schedule1",
                "name": "MyPulseSchedule",
                "scheduleType": "PULSE",
                "schedule": "DTSTART:19700101T000000\nRRULE:FREQ=SECONDLY;INTERVAL=1"
            },
            {
                "id": "Schedule2",
                "name": "MyIntervalSchedule",
                "scheduleType": "INTERVAL",
                "schedule": "DTSTART:19700101T000000\nDTEND:19700102T000000\nRRULE:FREQ=WEEKLY;BYDAY=MO,TU"
            }
        ]
    }
}

Add a pulse schedule​

Add a pulse schedule with one pulse for every second.

Example:

curl --request POST \
  --anyauth \
  --user "<username>:<password>" \
  --http1.1 \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/scheduled-events/v2/schedules \
  --data '{
    "data": {
        "name": "OneSecondPulseSchedule",
        "schedule": "DTSTART:19700101T000000\nRRULE:FREQ=SECONDLY;INTERVAL=1"
    }
}'
HTTP/1.1 201 Created
Content-Type: application/json

{
    "status": "success",
    "data": {
        "id": "schedule1",
        "name": "OneSecondPulseSchedule",
        "scheduleType": "PULSE",
        "schedule": "DTSTART:19700101T000000\nRRULE:FREQ=SECONDLY;INTERVAL=1"
    }
}

Add an interval schedule​

Add an interval schedule valid for the whole day, every Monday and Tuesday.

Example:

curl --request POST \
  --anyauth \
  --user "<username>:<password>" \
  --http1.1 \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/scheduled-events/v2/schedules \
  --data '{
    "data": {
        "name": "Monday&Tuesday",
        "schedule": "DTSTART:19700101T000000\nDTEND:19700102T000000\nRRULE:FREQ=WEEKLY;BYDAY=MO,TU"
    }
}'
HTTP/1.1 201 Created
Content-Type: application/json

{
    "status": "success",
    "data": {
        "id": "schedule2",
        "name": "Monday&Tuesday",
        "scheduleType": "INTERVAL",
        "schedule": "DTSTART:19700101T000000\nDTEND:19700102T000000\nRRULE:FREQ=WEEKLY;BYDAY=MO,TU"
    }
}

Remove a schedule​

Remove a pulse schedule.

Example:

curl --request DELETE \
  --anyauth \
  --user "<username>:<password>" \
  --http1.1 \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/scheduled-events/v2/schedules/schedule1
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success"
}

Set a pulse schedule​

Update the name and schedule of a pulse schedule.

Example:

curl --request PATCH \
  --anyauth \
  --user "<username>:<password>" \
  --http1.1 \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/scheduled-events/v2/schedules/schedule1 \
  --data '{
    "data": {
        "name": "TwoSecondPulseSchedule",
        "schedule": "DTSTART:19700101T000000\nRRULE:FREQ=SECONDLY;INTERVAL=2"
    }
}'
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success"
}

Set an interval schedule​

Update the name and schedule of an interval schedule.

Example:

curl --request PATCH \
  --anyauth \
  --user "<username>:<password>" \
  --http1.1 \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/scheduled-events/v2/schedules/schedule2 \
  --data '{
    "data": {
        "name": "Monday&Tuesday&Wednesday",
        "schedule": "DTSTART:19700101T000000\nDTEND:19700102T000000\nRRULE:FREQ=WEEKLY;BYDAY=MO,TU,WE,TU"
    }
}'
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success"
}

API definition​

Structure​

event-schedules.v2 (Root Entity)
    ├── schedules (Entity Collection)
        ├── id (Property)
        ├── name (Property)
        ├── schedule (Property)
        ├── scheduleType (Property)

Entities​

event-schedules.v2​

  • Description: Manage scheduled events
  • Type: Singleton
  • Operations
    • Get
  • Attributes
    • Dynamic Support: No

event-schedules.v2.schedules​

  • Description: Schedules
  • Type: Collection (Key Property: id)
  • Operations
    • Get
    • Set
      • Properties: id, name, schedule, scheduleType
    • Add
      • Required properties: name, schedule
      • Optional properties: id
    • Remove
  • Attributes
    • Dynamic Support: No
Properties​
id​
  • Description: Unique identifier for a schedule. Automatically generated if not provided during add.
  • Datatype: string
  • Operations
    • Get (Permissions: admin, operator, viewer)
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No
name​
  • Description: Well-known name of the schedule.
  • Datatype: string
  • Operations
    • Get (Permissions: admin, operator, viewer)
    • Set (Permissions: admin)
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No
schedule​
  • Description: Schedule definition, based on the iCalendar format.
  • Datatype: string
  • Operations
    • Get (Permissions: admin, operator, viewer)
    • Set (Permissions: admin)
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No
scheduleType​
  • Description: Type of schedule, either 'Pulse' or 'Interval'.
  • Datatype: ScheduleVariant
  • Operations
    • Get (Permissions: admin, operator, viewer)
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No

Data types​

ScheduleVariant​

  • Description: Type of schedule
  • Type: string
  • Enum Values: "PULSE", "INTERVAL"
Last updated on