| paul@933 | 1 | = Event Recurrences = |
| paul@933 | 2 | |
| paul@934 | 3 | Events defined by iCalendar objects may recur when |
| paul@934 | 4 | [[http://tools.ietf.org/html/rfc5545#section-3.8.5|recurrence component properties]] |
| paul@934 | 5 | such as `RDATE` and `RRULE` are employed. Each recurrence of an event may then |
| paul@934 | 6 | be referenced using |
| paul@934 | 7 | [[http://tools.ietf.org/html/rfc5545#section-3.8.4.4|recurrence identifiers]], |
| paul@934 | 8 | and such identifiers indicate the originally-specified start point of a |
| paul@934 | 9 | particular recurrence (either implicitly specified by `RRULE` properties or |
| paul@934 | 10 | explicitly specified by `RDATE` properties). |
| paul@933 | 11 | |
| paul@933 | 12 | == Recurrence Identifier Stability == |
| paul@933 | 13 | |
| paul@934 | 14 | A recurrence retains the same identifier throughout its lifetime. Even if a |
| paul@934 | 15 | recurrence's start date or time changes, it will still retain the same |
| paul@934 | 16 | identifier in its `RECURRENCE-ID` property which will no longer reflect the |
| paul@934 | 17 | currently-specified start point of the recurrence. Such identifier stability |
| paul@934 | 18 | is intended to provide a means of identifying the original recurrence so that |
| paul@934 | 19 | it can be hidden from any calendar or event descriptions and replaced with the |
| paul@934 | 20 | modified version. |
| paul@933 | 21 | |
| paul@933 | 22 | == Recurrences and Time Zones == |
| paul@933 | 23 | |
| paul@934 | 24 | Since recurrence identifiers may be defined using time zone information, |
| paul@934 | 25 | imip-agent normalises the specified recurrence identifiers to UTC-based |
| paul@934 | 26 | datetimes to minimise ambiguity. For example: |
| paul@934 | 27 | |
| paul@934 | 28 | || '''iCalendar Property''' || '''Normalised Value''' || '''UTC Datetime?''' || |
| paul@934 | 29 | || `RECURRENCE-ID:20141114` || `20141114` || No || |
| paul@934 | 30 | || `RECURRENCE-ID:20141114T000000` || `20141114T000000` || No || |
| paul@934 | 31 | || `RECURRENCE-ID;TZID=Europe/Oslo:20141114` || `20141113T230000Z` || Yes || |
| paul@934 | 32 | || `RECURRENCE-ID;TZID=Europe/Oslo:20141114T000000` || `20141113T230000Z` || Yes || |
| paul@934 | 33 | || `RECURRENCE-ID:20141114T000000Z` || `20141114T000000Z` || Yes || |
| paul@933 | 34 | |
| paul@934 | 35 | Identifiers without time zone information are not in themselves sufficient to |
| paul@934 | 36 | unambiguously define points in time, and thus additional time zone information |
| paul@934 | 37 | must be provided to obtain such time periods for such purposes as detecting |
| paul@934 | 38 | conflicts with other events. In the above examples, those normalised values |
| paul@934 | 39 | not providing a UTC datetime representation need further conversion to be |
| paul@934 | 40 | usable for period comparisons. Such further conversion would be done by |
| paul@934 | 41 | nominating a disambiguating time zone, such as the user's configured time |
| paul@934 | 42 | zone. |
| paul@933 | 43 | |
| paul@934 | 44 | By normalising identifiers using any object-resident time zone information, |
| paul@934 | 45 | imip-agent can use the resulting values without needing to consult the object |
| paul@934 | 46 | providing any redefined recurrence, knowing that any time zone information has |
| paul@934 | 47 | already been taken into consideration. Thus, all UTC-based datetimes used as |
| paul@934 | 48 | recurrence identifiers are readily usable for comparison purposes, whereas any |
| paul@934 | 49 | floating date or datetime values used as recurrence identifiers must need |
| paul@934 | 50 | additional conversion using the user's time zone to be usable. |
| paul@933 | 51 | |
| paul@934 | 52 | It might be thought that there would be correspondence between a recurrence |
| paul@934 | 53 | identifier and the time zone details employed by the original object |
| paul@934 | 54 | describing the redefined recurrence (such as the `TZID` attribute specified on |
| paul@934 | 55 | an object's `DTSTART` property), and so any unqualified recurrence identifier |
| paul@934 | 56 | might be converted to a UTC-based datetime using such time zone details. |
| paul@934 | 57 | However, an assumption could equally be made that the recurrence identifier |
| paul@934 | 58 | should inherit time zone details from the redefined recurrence instead. The |
| paul@934 | 59 | only reasonable choice to be made when confronted with such ambiguity is to |
| paul@934 | 60 | treat any unqualified identifier as a genuine floating date or datetime, and |
| paul@934 | 61 | the normalisation process facilitates this strategy. |
| paul@933 | 62 | |
| paul@933 | 63 | == Recurrences and Free/Busy Information == |
| paul@933 | 64 | |
| paul@934 | 65 | Events employing recurrences on fixed occasions can be readily recorded in the |
| paul@934 | 66 | free/busy information for a calendar user. However, iCalendar also permits |
| paul@934 | 67 | recurrences that may potentially continue forever, and yet providing free/busy |
| paul@934 | 68 | information for arbitrary periods in the future may either result in |
| paul@934 | 69 | substantial computation or substantial demands on storage resources. |
| paul@934 | 70 | Consequently, free/busy information may only be generated for a period ending |
| paul@934 | 71 | at a certain point in the future defined in terms of days from the present. |
| paul@934 | 72 | Within this period scheduling would make sense, and attempts to schedule |
| paul@934 | 73 | events outside this period would succeed at the participant's own risk. |
| paul@933 | 74 | |
| paul@934 | 75 | Such a period where participant availability is known must be necessarily |
| paul@934 | 76 | expanded as time progresses. One-off events, once recorded in the free/busy |
| paul@934 | 77 | records, will not contribute further to expansions of those records. Recurring |
| paul@934 | 78 | events, however, may provide additional periods of interest as the |
| paul@934 | 79 | availability window moves forward in time. |
| paul@933 | 80 | |
| paul@934 | 81 | To determine which events contribute recurrences, a list of objects (initially |
| paul@934 | 82 | all objects known to a user that have not been cancelled) is consulted and |
| paul@934 | 83 | their recurrence properties inspected. With such knowledge of recurring |
| paul@934 | 84 | events, upon expanding the availability window, only these "known recurring" |
| paul@934 | 85 | events need to be inspected for further contributions to the free/busy |
| paul@934 | 86 | records, and those no longer contributing after a given point can be discarded |
| paul@934 | 87 | from the list for future expansion of the window. Meanwhile, new events would |
| paul@934 | 88 | need to be added to the list, at least if they were defined as providing |
| paul@934 | 89 | recurrences that may occur in future availability periods. |
| paul@933 | 90 | |
| paul@933 | 91 | === Updating Free/Busy Records === |
| paul@933 | 92 | |
| paul@934 | 93 | To update and thus expand availability information, it is suggested that a |
| paul@934 | 94 | regularly scheduled task be used to consult the events known (or thought) to |
| paul@934 | 95 | provide additional free/busy periods and to record such additional periods for |
| paul@934 | 96 | each user. This can be done using a system's `cron` daemon and a suitable |
| paul@955 | 97 | script in `/etc/cron.daily` or equivalent. Such a script is |
| paul@955 | 98 | [[../CronIntegration|provided]] in the imip-agent distribution along with a |
| paul@955 | 99 | program that can expand availability information for all known recipients of |
| paul@955 | 100 | calendar information. |
