summaryrefslogtreecommitdiff
path: root/KEP-0003.txt
blob: f029785da9e4236f565fb724cf3aebfc279435f7 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
{{kep
 |number=3
 |ticketnumber=
 |title=Introduction of 'subevent' sub-tag for 'exclusion' from 'recurrence'
 |author=Georg Greve
 |author_email=greve@kolabsys.com
 |status=approved
 |type=design
 |creation_date=2010-11-16
 |obsoleted_by=
 |related=
}}


== Abstract ==

The Kolab storage format models allows recurrence to have 'non-occurence' exceptions already, but it does not allow to have 'modification' exceptions, e.g. change of time or location. The way this has been handled is to create a 'non-occurence' exception, and then create a separate event for that day with the default values of the recurring event.

This has been understood as a suboptimal solution for a long time because the clients cannot easily connect that new event with the recurring event for future modifications, while the user logically sees them as connected.

The solution is to introduce a hierarchically nested 'subevent' sub-tag for an exception, which takes all default values from the recurring event itself, and only contains the differences to these default values <ref name="fix-recurrances-xml-1.1">Martin Konold, Event XML 1.1 (fix recurrances), http://kolab.org/pipermail/kolab-format/2008-December/000876.html</ref>.

== Update to the XML Format ==

The following changes for recurrence storage in Kolab XML are part of the changeset applied against version 1.0 of the 'event' and 'task' object types of Kolab Format 2.0:

* Clients '''MUST''' treat the date of the 'exclusion' as the Recurrence ID<ref name="rfc5545">[[RFC:5545 | RFC5545: Internet Calendaring and Scheduling Core Object Specification, 3.8.4.4 Recurrence ID]]</ref> where applicable, in particular iTIP<ref name="rfc5546">[[RFC:5546 | RFC5546: iCalendar Transport-Independent Interoperability Protocol (iTIP)]]</ref> handling;
* A 'subevent' XML tag '''MAY''' be added hierarchically nested within an 'exclusion' to a 'recurrence' of an 'event' object;
* There '''MAY''' be only one 'subevent' per 'exclusion';
* All event values of the 'subevent' default to the 'event' within which it is nested. Values within 'subevent' change these values for this 'exception' from the 'recurrence' only;
* Fields for 'event' that 'subevent' '''MUST NOT''' specify are: 'uid' and 'recurrence';
* Fields that 'subevent' '''MUST''' define are: 'creation-date' and 'last-modification-date'

=== Example ===

Moving one instance of a recurring event from date1, a normal date in the recurrence cycle, to new-date1 with a recurrence exception created at 21:15:12 UTC on 1st of May 2011 and last modified at 23:12:51 UTC on 2nd of May 2011 would express itself as follows:

 <event>
 ...
   <recurrence>
   ...
     <exclusion>date1
       <subevent>
         <start-date>new-date1</start-date>
         <creation-date>2011-05-01T21:15:12Z</creation-date>
         <last-modification-date>2011-05-02T23:12:51Z</last-modification-date>
       </subevent>
     </exclusion>
   </recurrence>
 </event>


== Upgrade Path ==

New clients that correspond to 'event' and 'task' objects of the Kolab Format after application of this KEP will be fully compatible with older data sets.

Older clients can continue to behave as before at their own choice, and will remain consistent with the version 1.0 of the 'event' and 'task' object types in Kolab Format 2.0 and no data will be lost or corrupted. So whilst this is important, it is not urgent. 

Older clients that do not implement the Kolab Format after application of this KEP will however not be able to display recurrence exceptions of newer clients properly, so it is '''STRONGLY''' recommended to move to the newer format as soon as possible.

== References ==

{{Reflist}}

== Copyright ==

This document has been placed in the public domain.