summaryrefslogtreecommitdiff
path: root/KEP-0008.txt
blob: 1c997d1c48927bbf2bcd7c2cdbea9d3ed57efdbb (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
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
{{kep
 |number=8
 |ticketnumber=
 |title=Priority for events, matching iCalendar priority range
 |author=Georg Greve
 |author_email=greve@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 specifies a mandatory
'priority' field for objects of type 'task' only, using a numeric
value of 1-5. 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.