Hello Zimbra Friends,
This blog is brought to you by David Bingham, Technical Product Manager at Synacor, and describes how Zimbra stores and communicates calendar events over its various APIs. This is technical information, suited for developers of software intended to interop with Zimbra … but it is also for anyone curious about Zimbra Tech Skillz.
Interoperability of scheduling information
To support interoperability with a wide variety of calendaring and scheduling systems and applications, Zimbra supports several calendar data formats, as summarized in the table below.
iCal format
In this section, we’ll look at some specific details of the iCalendar format to support further explanations about event recurrence. If you want to know more, there is a good overview of the iCalendar format available from Wikipedia.
In Example 1 – Simple Event, we see the iCal description of an appointment from a Zimbra calendar.
- Indenting has been added for ease of interpretation.
- iCalendar format is VCALENDAR v 2.0
- Property blocks have BEGIN and END labels. This block provides the details about the Timezone used for the event.
- The VEVENT block contains the properties of the event itself.
Now, look at Example 2 – Zoom into single event and the callouts for some properties of the event.
- Each event has a unique identifier.
- The start and end Date/Time values for the event.
- Properties beginning with X are experimental. In this case, the property specifies the busy status that the meeting organizer intends the attendee’s copy of the meeting to have. [MS-OXCICAL]
- TRANSP (Transparency) indicates how to treat the event’s period when reporting Free/Busy information. OPAQUE events will be blocked out, while TRANSPARENT events will appear free.
Recurrence rules
The details about how an event repeats appear in the form of a recurrence rule. We saw an example of this earlier in Example 1 – Simple Event, with the recurrence of the timezone’s Daylight Savings Time change in iCalendar data format.
In Example 3 – DST Recurrence Rule we see that DST begins every year on the second Sunday in March, where weeks start on a Monday. Let’s break that down.
- The RRULE consists of a set of properties, beginning with a required frequency, FREQ, set to “YEARLY”, so this event repeats on some relative annual cycle. Other common values are “DAILY”, “WEEKLY”, “MONTHLY”, or “YEARLY”.
- All other properties are optional, and the order of appearance is unimportant.
- This event will repeat forever because there is no end specified. We can specify an end with “UNTIL” and an end date/time or “COUNT” and some number of occurrences.
- The INTERVAL property is a positive single-digit integer that combines with FREQ to express how often the event repeats, thus every “1” year. (The default is 1, so the property in this example is redundant.)
- The BYMONTH property specifies a comma-separated list of months of the year (1 – 12) in which the event repeats. In our example, the value 3 corresponds with March.
- Similarly, the BYDAY property tells us which day or days in the month or months the event repeats on. We could give a list of comma-separated text values (MO..SU) or numeric values (1- 31), or, as in this example, we can specify more complex constructs like “the second Sunday” by concatenating an ordinal integer and a day, as in “2SU”.
- For this rule, we’ve specified the start-of-week using WKST set to MO (Monday). This ensures that the BYDAY property is unambiguous. (The default is MO, so the property in this example is redundant.)
There are many more options available than we’ve seen in this simple example, with only a few properties. Numerous RRULE examples have been provided in [RFC-2455], section 4.8.5.4 Recurrence Rule. A quick review of those should provide you with a good understanding of the variety of ways to express an event’s recurrence. == Recurring events
Now let’s take a look at the iCalendar data for a recurring event series from a Zimbra user’s calendar, in Example 4 – Simple Recurring Event. We’ll call this simple because all the occurrences of the series follow the recurrence rules, with no exceptions. We’ll consider exceptions later.
In addition to the RRULE with its properties, the combination of start date/time (DTSTART) and end date/time (DTEND) fully express the recurrence of the event.
• The first instance of this event is on February 27, 2020, starting at 5:30 pm and ending at 6:00 pm, Eastern Time.
• Further occurrences happen daily, every day, for a total of 5 days.
- The Recurrence Rule for the event appears in the VEVENT block. Combining that with DTSTART and DTEND, we have the full description of the event’s recurrence.
- The organizer is usually the calendar owner. In a shared calendar, events that have been created or modified by other users will also have a “SENT-BY” property here.
Exceptions in recurring events
An Exception is an instance of an event series that differs from the series definition. For this article, we’re most interested in exceptions that depart from the recurrence rules for the series; however, an exception could follow the recurrence rules but differ in its SUMMARY, DESCRIPTION, STATUS, or other optional property.
Example 5 – Exception to a Recurring Event illustrates an exception with a different start time than the original series specified.
- The instance scheduled to start on February 27, 2020, at 5:30 pm now starts at 4:00 pm and ends at 4:30 pm.
- That exception has a DESCRIPTION that is different than the series.
- When rescheduling an instance of a series, Zimbra applications will always modify it to create an exception within the series. They will never detach an instance from the series.
- The Zimbra Connector for Outlook (ZCO) is unique among Zimbra applications because Outlook is responsible for how the calendar is managed in the application, while ZCO’s role is to synchronize changes between Outlook and the Zimbra server. Fortunately, Outlook treats recurring events just as the Zimbra Web Client does; rescheduled instances of recurring meetings remain as exceptions within the original series.
- The series VEVENT block has a UID but no RECURRENCE-ID.
- The exception VEVENT block has the same UID as the series, but a unique RECURRENCE-ID with a value equal to the DTSTART of the instance according to the event Recurrence Rule.
- The exception has updated DTSTART and DTEND values.
- The SEQUENCE property counts revisions of the component or block it appears in.
We see a different type of exception in Example 6 – Deleted occurence from a Recurring Event, when canceling one instance in the series.
• The instance scheduled to start on February 28, 2020, at 5:30 pm is an “EXDATE” (exception date) within a VEVENT related to the series.
- EXDATE lists the canceled instances using the DTSTART of the instance according to the event Recurrence Rule.
Summary
In this article, we’ve used the iCalendar data format to examine how Zimbra expresses calendar events, recurrence, and exceptions. In particular, we’ve compared a simple recurring event with two types of exceptions; a rescheduled instance and a canceled instance.
Zimbra provides multiple protocols that support calendar data interoperability with a wide variety of systems and applications, all working with the same consistent set of data.
Thank you,
David Bingham
References
[ZSOAP] Synacor Inc., “Zimbra SOAP API Reference”, 8.8.15, July 2019 https://wiki.zimbra.com/wiki/SOAP_API_Reference_Material_Beginning_with_ZCS_8.
[RFC-5545] Desruisseaux, B., Ed., “Internet Calendaring and Scheduling Core Object Specification (iCalendar)”, RFC 5545, DOI 10.17487/RFC5545, September 2009, http://www.rfc-editor.org/info/ rfc5545.
[MS-ASCAL] Microsoft Corporation, “Exchange ActiveSync: Calendar Class Protocol”, v20181001, October 1, 2018, https://docs.microsoft.com/en-us/openspecs/exchange_server_protocols/ms-ascal.
[MS-OXCICAL] Microsoft Corporation, “iCalendar to Appointment Object Conversion Algorithm”, February 14, 2019, https://docs.microsoft.com/en-us/openspecs/exchange_server_protocols/ms-oxcical.
Comments are closed.