Schedule service

Schedule service guide

The Schedule service manages schedules for use by other services. Schedules can be used to allow or deny access to a resource, or used as triggers for actions.

Setting a schedule

Schedules are created using the axsch:SetSchedule API call. A basic example:

{
  "axsch:SetSchedule": {
    "Schedule": [ {
      "ExceptionScheduleDefinition": null,
      "Attribute": [],
      "ScheduleDefinition":
        "BEGIN:VCALENDAR\nBEGIN:VEVENT\nDTSTART:20120312T080000\n
        DTEND:20120312T170000\nRRULE:FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR\n
        END:VEVENT\nEND:VCALENDAR\n",
      "token": "",
      "Description": "Desc1",
      "Name": "Name1"
    } ]
  }
}

<axsch:SetSchedule>
  <axsch:Schedule token="">
    <axsch:Attribute type="" Name="" Value=""></axsch:Attribute>
    <axsch:Description>Desc1</axsch:Description>
    <axsch:ExceptionScheduleDefinition></axsch:ExceptionScheduleDefinition>
    <axsch:Name>Name1</axsch:Name>
    <axsch:ScheduleDefinition>BEGIN:VCALENDAR&#xD;&#xA;
BEGIN:VEVENT&#xD;&#xA;
DTSTART:20120312T080000&#xD;&#xA;
DTEND:20120312T170000&#xA;
RRULE:FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR&#xD;&#xA;
END:VEVENT&#xD;&#xA;
END:VCALENDAR&#xD;&#xA;
</axsch:ScheduleDefinition>
  </axsch:Schedule>
</axsch:SetSchedule>

See section The RFC5545 syntax flavor for information about the schedule syntax.

There are default schedules in the system, which can be removed if desired. Use axsch:GetScheduleList to retrieve the list of available schedules.

Pulse and interval schedules

A schedule can be an interval schedule or a pulse schedule. Interval and pulse schedules are set using the same API call but they generate different events.

Interval schedules have a start time and an end time, that is, the schedule will be active during a defined time interval. Interval schedules are used to define rules for when resources can be accessed, for example "work hours", "weekends" or "holidays". Events are generated when the schedule state changes between active and inactive.
Pulse schedules only have a start time. Pulse schedules are used to trigger actions that should run at a specific time, or that should run repeatedly according to a recurrence rule, for example everyWednesday at 11 pm. Events are generated when the schedule becomes active.

Interval and pulse schedules are both created using axsch:Schedule. An interval schedule is created if the DTEND field exists in the VEVENT. If DTEND does not exist, a pulse schedule is created. For information about the schedule syntax, see The RFC5545 syntax flavor.

Exception schedules

Exception schedules use the same syntax as ordinary schedules, but are specified in the ExceptionScheduleDefinition instead of the ScheduleDefinition. Exceptions are subtracted from the ScheduleDefinition, that is, exception schedules override schedules, as can be seen in the table below.

Active Schedule Overview
ScheduleDefinition active	ExceptionScheduleDefinition active	Active
No	No	No
Yes	No	Yes
No	Yes	No
Yes	Yes	No

When multiple schedules and exception schedules are attached to a resource, this same table will apply. If any of the schedules are active, the outcome will be active, but if any of the schedules are in exception state, the total outcome will be inactive. This is useful to create a single schedule with only exceptions, such as a holiday schedule. This can then be reused on all resources where the same holidays should apply.

Note: It is always enough to look at the Active field to determine whether a schedule is currently active. If both the ScheduleDefinition and the ExceptionScheduleDefinition are active, the entire Schedule will be inactive. A Schedule will thus never be active if it is in an exception state.

Checking schedule status

There are two API calls that can be used to check the status of schedules: axsch:ScheduleActive and axsch:ScheduleStatusReport. The check if one or more specific schedules are active, use axsch:ScheduleActive. When checking multiple schedules, they are aggregated according to the following rule:

IF (Any schedule is active) AND NOT (Any exception schedule is active)

Examples:

Request

{
  "axsch:ScheduleActive": {
    "Token": [
      "standard_office_hours",
      "standard_weekends"
    ],
    "UtcTime": null,
    "LocalTime": null
  }
}

Request

<axsch:ScheduleActive>
<axsch:LocalTime>2013-11-01T10:17:17Z</axsch:LocalTime>
<axsch:Token>standard_office_hours</axsch:Token>
<axsch:Token>standard_weekends</axsch:Token>
<axsch:UtcTime>2013-11-01T10:17:17Z</axsch:UtcTime>
</axsch:ScheduleActive>

Response

{
  "Active": true,
  "Exception": false
}

Response

<axsch:Active>true</axsch:Active>
<axsch:Exception>false</axsch:Exception>

To get a simultaneous report for all schedules in the system, use axsch:ScheduleStatusReport:

Request

{
  "axsch:ScheduleStatusReport": {}
}

Request

<axsch:ScheduleStatusReport></axsch:ScheduleStatusReport>

Response

{
  "Status": [
    {
      "Token": "standard_weekends",
      "Active": false,
      "Exception": false
    },
    {
      "Token": "standard_office_hours",
      "Active": true,
      "Exception": false
    },
    {
      "Token": "standard_always",
      "Active": true,
      "Exception": false
    }
  ]
}

Response

<axsch:Status>
  <axsch:Token>standard_weekends</axsch:Token>
  <axsch:Active>false</axsch:Active>
  <axsch:Exception>false</axsch:Exception>
</axsch:Status>
<axsch:Status>
  <axsch:Token>standard_office_hours</axsch:Token>
  <axsch:Active>true</axsch:Active>
  <axsch:Exception>false</axsch:Exception>
</axsch:Status>
<axsch:Status>
  <axsch:Token>standard_always</axsch:Token>
  <axsch:Active>true</axsch:Active>
  <axsch:Exception>false</axsch:Exception>
</axsch:Status>

The RFC5545 syntax flavor

The schedule syntax is based on RFC5545 (iCalendar), the syntax used by calendaring applications such as Google Calendar^TM and Microsoft Outlook^R. The RFC5545 specification is quite extensive and only the subset that is relevant for access control applications is supported by the access control API:

Only local time is used.
No support for UTC time
No support for VTIMEZONE
No support for VALARM
DTSTART;VALUE=DATE is converted to a 24h interval event
Overlapping RDATE /RRULE instances within a single VEVENT are undefined
The following RRULE parameters are supported:
1. HOURLY, MINUTELY, SECONDLY
2. DAILY
3. WEEKLY, WEEKLY;BYDAY
4. MONTHLY, MONTHLY;BYMONTHDAY
5. YEARLY, YEARLY;BYMONTH

Example schedules

Office hours:

BEGIN:VCALENDAR
BEGIN:VEVENT
SUMMARY:Office Hours
DTSTART:19700101T090000
DTEND:19700101T170000
RRULE:FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR
END:VEVENT
END:VCALENDAR

Weekends (starting with Friday evening):

BEGIN:VCALENDAR

BEGIN:VEVENT
DTSTART:19700104T000000
DTEND:19700105T000000
RRULE:FREQ=WEEKLY;BYDAY=SA,SU
END:VEVENT

BEGIN:VEVENT
DTSTART:19700102T170000
DTEND:19700103T000000
RRULE:FREQ=WEEKLY;BYDAY=FR
END:VEVENT

END:VCALENDAR

Oneshot Interval:

BEGIN:VCALENDAR
BEGIN:VEVENT
DTSTART:20120213T100000
DTEND:20120213T130000
END:VEVENT
END:VCALENDAR

Oneshot Pulse:

BEGIN:VCALENDAR
BEGIN:VEVENT
DTSTART:20120213T110000
END:VEVENT
END:VCALENDAR;

RDATE;VALUE=DATE:

BEGIN:VCALENDAR
BEGIN:VEVENT
SUMMARY:Some birthdays during 2012
DTEND:20120508T160000
RDATE;VALUE=DATE:20120508,20120604,20120608,20120810,20121130
DTSTART:20120508T140000
END:VEVENT
END:VCALENDAR;

Mixed RDATE/RRULE Interval:

BEGIN:VCALENDAR
BEGIN:VEVENT
DTSTART:20120201T000000
RRULE:FREQ=WEEKLY;BYDAY=WE,TH,FR
RDATE;VALUE=DATE-TIME: 20120131T153000,20120201T000000,20120203T153000
END:VEVENT
END:VCALENDAR;

COUNT and INTERVAL:

BEGIN:VCALENDAR
BEGIN:VEVENT
DTSTART:20120101T131313
RRULE:FREQ=DAILY;INTERVAL=4;COUNT=3
END:VEVENT
END:VCALENDAR;

UNTIL and INTERVAL:

BEGIN:VCALENDAR
BEGIN:VEVENT
DTSTART:20000101T120000
RRULE:FREQ=SECONDLY;INTERVAL=15;UNTIL=20000101T120045
END:VEVENT
END:VCALENDAR;

Schedule service API specification

axsch = http://www.axis.com/vapix/ws/schedule

The Schedule service provides an API to configure and check schedules.

It is used by the PACS AccessControl / A2E service.

Schedule definitions is in iCalendar syntax according to RFC 5545, but only a subset of RFC 5545 is required to be supported.

The following iCalendar components, properties and parameters MUST be supported:

VCALENDAR: starts and ends the definition.
UID and VERSION: since the RFC says they are required.
VEVENT: Provide a grouping of component properties that describe an event.
DTSTAMP, DTSTART, DTEND SUMMARY, DESCRIPTION: may be used by user interface, not interpreted.
TZID - if VTIMEZONE: supported.
RRULE and RDATE: to specify recurrances:
RDATE: allows you to specify a list of date, periods or date-times.
RDATE: with DATE-TIME, DATE and PERIOD VALUE types, e.g.
RRULE: allows you to specify recurring events on a minutely, hourly, daily, weekly, montly and yearly basis etc.

The following is optional:

VTIMEZONE: if not supported, all times not in UTC time is assumed to be in the device local timezone as specified in the Device service.
VALARM, VTODO, VJOURNAL, VFREEBUSY: typically not applicable.