KEP-0008.txt

[Jeroen van Meeuwen]

 KEP-0008.txt |  137 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 137 insertions(+)

New commits:
commit ed63bfca728e675656f10288715135171a73a363
Author: Jeroen van Meeuwen (Kolab Systems) <vanmeeuwen at kolabsys.com>
Date:   Sat Jun 25 13:51:39 2011 +0100

    Add KEP-0008 by Georg Greve <greve at kolabsys.com>

diff --git a/KEP-0008.txt b/KEP-0008.txt
new file mode 100644
index 0000000..4499a78
--- /dev/null
+++ b/KEP-0008.txt
@@ -0,0 +1,137 @@
+{{kep
+ |number=8
+ |ticketnumber=
+ |title=Priority for events, matching iCalendar priority range
+ |author=Georg Greve
+ |author_email=greve at kolabsys.com
+ |status=draft
+ |type=design
+ |creation_date=2011-06-25
+ |obsoleted_by=
+ |related=
+}}
+
+
+== Abstract ==
+
+Kolab XML version 1.0 of Kolab Format 2.0 allows requires storage of a
+mandatory 'priority' field with a numeric value of 1-5 for objects of
+type 'task' only. It did not define 'priority' for the 'event' object type.
+
+This Kolab Enhancement Proposal (KEP) <ref name"kep">[[KEP:1]]</ref>
+defines part of a changeset applied against version 1.0 of the 'event'
+and 'task' object types in Kolab Format 2.0, making 'priority' an
+optional, common field for both object types with numeric values of
+0-9 similar to the approach taken in RFC 5545<ref
+name="rfc5545">[[RFC:5545 | RFC5545: Internet Calendaring and
+Scheduling Core Object Specification, 3.8.1.9 Priority]]</ref> and RFC
+5546<ref name="rfc5546">[[RFC:5546 | RFC5546: iCalendar
+Transport-Independent Interoperability Protocol (iTIP)]]</ref>.
+
+As a result the Kolab Format will be more easily interoperable with
+iCalendar and iTip based groupware solutions, will better support
+clients that expect capabilities to define 'priority' for events, and
+will through explicit conversion rules towards other formats ensure
+that all such third party clients that do '''not''' follow the
+iCalendar approach will behave more consistently in a Kolab Groupware
+Environment.
+
+== Update to the XML Format ==
+
+The following changes for the 'priority' field in Kolab XML are part
+of the changeset applied against version 1.0 of the 'event' and 'task'
+object types in Kolab Format 2.0:
+
+* 'priority' is defined as an optional common field for objects of type 'task' and 'event' that '''MAY''' occur exactly zero or one times per object;
+* Values for 'priority' '''MUST''' be numbers between 0-9 corresponding to definitions in RFC 5545<ref name="rfc5545">[[RFC:5545 | RFC5545: Internet Calendaring and Scheduling Core Object Specification, 3.8.1.9 Priority]]</ref> and RFC 5546<ref name="rfc5546">[[RFC:5546 | RFC5546: iCalendar Transport-Independent Interoperability Protocol (iTIP)]]</ref> with 0 representing no/undefined priority, 1 representing the highest priority and 9 representing the lowest priority;
+* Clients '''MUST''' interpret objects without 'priority' field as having the 'priority' value of '0'.
+
+=== Example ===
+
+An event of the highest priority would look like this:
+
+ <event>
+ ...
+   <priority>1</priority>
+ </event>
+
+An undefined priority is the same as a priority that is set to '0' explicitly, so
+
+ <event>
+ ...
+   <priority>0</priority>
+ </event>
+
+and
+
+ <event>
+ ...
+ </event>
+
+are identical.
+
+== Client Behaviour ==
+
+Clients that need to translate between the priority stored in the Kolab Format and a third-party application, such as plugins for Microsoft Outlook shall use the following mapping:
+
+=== Mapping with Microsoft Exchange/Outlook ===
+
+Microsoft Exchange/Outlook have a priority system with values -1, 0, +1 whereby '1' = 'urgent', '0' = 'normal', '-1' = 'non-urgent'. 
+
+Conversion from Kolab XML to this priority system shall be done according to the following table:
+{| border="0" align="center" style="text-align:center;padding:2;"
+| Kolab XML Priority || mapped to || Microsoft Outlook Priority
+|-
+| 0 || -> || 0
+|-
+| 1-3 || -> || 1
+|-
+| 4-6 || -> || 0
+|-
+| 7-9 || -> ||-1
+|}
+
+Clients '''MUST''' retain the original value of the 'priority' field for storage and '''MAY''' only change the value of 'priority' based upon user interaction. 
+
+In such a case priorities '''MUST''' be translated according to the following table:
+{| border="0" align="center" style="text-align:center;padding:2;"
+| Microsoft Outlook Priority || mapped to || Kolab XML Priority 
+|-
+| -1 || -> || 9
+|-
+| 0 || -> || 5
+|-
+| 1 || -> || 1
+|}
+
+== Upgrade Path ==
+
+Kolab XML Version 1.0 of Kolab Format 2.0 only knows a 'priority' field for objects of the 'task' object type, but not the 'event' object type, and only with numeric values between 1 and 5. Task objects written to the old specification will continue to be understood by clients implementing the format after application of this changeset. Although the mapping for lower-priority tasks won't be perfect, the internal relatonship of priorities between tasks will be retained.
+
+Data written according to the Kolab Format after application of this changeset will typically not be understood correctly as the values 0, 6-9 were previously illegal, and the 'event' object type previously did not permit a 'priority' field. 
+
+It is therefore '''STRONGLY''' advised to not have older and newer clients work on the same dataset and recommended to move to the newer format as soon as possible.
+
+== Rationale ==
+
+Kolab XML should support priority for the 'event' object type in order to better handle RFC 5546<ref name="rfc5546">[[RFC:5546 | RFC5546: iCalendar Transport-Independent Interoperability Protocol (iTIP)]]</ref> (iTip) invitations, be more compatible with RFC 5545<ref name="rfc5545">[[RFC:5545 | RFC5545: Internet Calendaring and Scheduling Core Object Specification, 3.8.1.9 Priority]]</ref> (iCalendar) based groupware systems, and enable third party Kolab clients that provide this functionality in other setups (e.g. Microsoft Exchange/Outlook).
+
+The minimal change necessary would have been to move the 'priority' field from the definition of the 'task' object type to the 'Common In Tasks And Events' section of the specification, resulting in the 'priority' field being applicable to both 'task' and 'event' objects. 
+
+There were several reasons why also changing the range of values seemed sensible and not prohibitively expensive:
+* The task system is rarely used;
+* Where they exist older data sets will remain internally consistent, and merely see a shift towards being valued as more important;
+* Switching to RFC 5545<ref name="rfc5545">[[RFC:5545 | RFC5545: Internet Calendaring and Scheduling Core Object Specification, 3.8.1.9 Priority]]</ref> / RFC 5546<ref name="rfc5546">[[RFC:5546 | RFC5546: iCalendar Transport-Independent Interoperability Protocol (iTIP)]]</ref> compatibility eliminates one translation step and thus keeps things simpler;
+* If retaining the old Kolab approach, all events would have to be assigned an arbitrary priority even if the invitation did not specify a priority, or explicitly stated the event had no priority assigned, so;
+** Being able to store 'no priority assigned' explicitly allows to preserve more of the original invitation data;
+** Having the field optional as an implicit 'no priority assigned' allows to use old data event data sets in a consistent way that reflects user intent.
+
+None of these is strong enough individually to require the adoption of RFC 55455<ref name="rfc5545">[[RFC:5545 | RFC5545: Internet Calendaring and Scheduling Core Object Specification, 3.8.1.9 Priority]]</ref> / RFC 5546<ref name="rfc5546">[[RFC:5546 | RFC5546: iCalendar Transport-Independent Interoperability Protocol (iTIP)]]</ref> compatible ranges for priority, but taken together they made it a very sensible and slightly preferred choice.
+
+== References ==
+
+{{Reflist}}
+
+== Copyright ==
+
+This document has been placed in the public domain.