<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head><meta http-equiv="content-type" content="text/html; charset=utf-8" />
<title>[14127] CalendarServer/trunk/doc/Extensions</title>
</head>
<body>
<style type="text/css"><!--
#msg dl.meta { border: 1px #006 solid; background: #369; padding: 6px; color: #fff; }
#msg dl.meta dt { float: left; width: 6em; font-weight: bold; }
#msg dt:after { content:':';}
#msg dl, #msg dt, #msg ul, #msg li, #header, #footer, #logmsg { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; }
#msg dl a { font-weight: bold}
#msg dl a:link { color:#fc3; }
#msg dl a:active { color:#ff0; }
#msg dl a:visited { color:#cc6; }
h3 { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; font-weight: bold; }
#msg pre { overflow: auto; background: #ffc; border: 1px #fa0 solid; padding: 6px; }
#logmsg { background: #ffc; border: 1px #fa0 solid; padding: 1em 1em 0 1em; }
#logmsg p, #logmsg pre, #logmsg blockquote { margin: 0 0 1em 0; }
#logmsg p, #logmsg li, #logmsg dt, #logmsg dd { line-height: 14pt; }
#logmsg h1, #logmsg h2, #logmsg h3, #logmsg h4, #logmsg h5, #logmsg h6 { margin: .5em 0; }
#logmsg h1:first-child, #logmsg h2:first-child, #logmsg h3:first-child, #logmsg h4:first-child, #logmsg h5:first-child, #logmsg h6:first-child { margin-top: 0; }
#logmsg ul, #logmsg ol { padding: 0; list-style-position: inside; margin: 0 0 0 1em; }
#logmsg ul { text-indent: -1em; padding-left: 1em; }#logmsg ol { text-indent: -1.5em; padding-left: 1.5em; }
#logmsg > ul, #logmsg > ol { margin: 0 0 1em 0; }
#logmsg pre { background: #eee; padding: 1em; }
#logmsg blockquote { border: 1px solid #fa0; border-left-width: 10px; padding: 1em 1em 0 1em; background: white;}
#logmsg dl { margin: 0; }
#logmsg dt { font-weight: bold; }
#logmsg dd { margin: 0; padding: 0 0 0.5em 0; }
#logmsg dd:before { content:'\00bb';}
#logmsg table { border-spacing: 0px; border-collapse: collapse; border-top: 4px solid #fa0; border-bottom: 1px solid #fa0; background: #fff; }
#logmsg table th { text-align: left; font-weight: normal; padding: 0.2em 0.5em; border-top: 1px dotted #fa0; }
#logmsg table td { text-align: right; border-top: 1px dotted #fa0; padding: 0.2em 0.5em; }
#logmsg table thead th { text-align: center; border-bottom: 1px solid #fa0; }
#logmsg table th.Corner { text-align: left; }
#logmsg hr { border: none 0; border-top: 2px dashed #fa0; height: 1px; }
#header, #footer { color: #fff; background: #636; border: 1px #300 solid; padding: 6px; }
#patch { width: 100%; }
#patch h4 {font-family: verdana,arial,helvetica,sans-serif;font-size:10pt;padding:8px;background:#369;color:#fff;margin:0;}
#patch .propset h4, #patch .binary h4 {margin:0;}
#patch pre {padding:0;line-height:1.2em;margin:0;}
#patch .diff {width:100%;background:#eee;padding: 0 0 10px 0;overflow:auto;}
#patch .propset .diff, #patch .binary .diff {padding:10px 0;}
#patch span {display:block;padding:0 10px;}
#patch .modfile, #patch .addfile, #patch .delfile, #patch .propset, #patch .binary, #patch .copfile {border:1px solid #ccc;margin:10px 0;}
#patch ins {background:#dfd;text-decoration:none;display:block;padding:0 10px;}
#patch del {background:#fdd;text-decoration:none;display:block;padding:0 10px;}
#patch .lines, .info {color:#888;background:#fff;}
--></style>
<div id="msg">
<dl class="meta">
<dt>Revision</dt> <dd><a href="http://trac.calendarserver.org//changeset/14127">14127</a></dd>
<dt>Author</dt> <dd>cdaboo@apple.com</dd>
<dt>Date</dt> <dd>2014-10-31 07:29:02 -0700 (Fri, 31 Oct 2014)</dd>
</dl>
<h3>Log Message</h3>
<pre>Updated spec.</pre>
<h3>Modified Paths</h3>
<ul>
<li><a href="#CalendarServertrunkdocExtensionscaldavrecursplittxt">CalendarServer/trunk/doc/Extensions/caldav-recursplit.txt</a></li>
<li><a href="#CalendarServertrunkdocExtensionscaldavrecursplitxml">CalendarServer/trunk/doc/Extensions/caldav-recursplit.xml</a></li>
</ul>
</div>
<div id="patch">
<h3>Diff</h3>
<a id="CalendarServertrunkdocExtensionscaldavrecursplittxt"></a>
<div class="modfile"><h4>Modified: CalendarServer/trunk/doc/Extensions/caldav-recursplit.txt (14126 => 14127)</h4>
<pre class="diff"><span>
<span class="info">--- CalendarServer/trunk/doc/Extensions/caldav-recursplit.txt 2014-10-31 02:08:53 UTC (rev 14126)
+++ CalendarServer/trunk/doc/Extensions/caldav-recursplit.txt 2014-10-31 14:29:02 UTC (rev 14127)
</span><span class="lines">@@ -1,12 +1,14 @@
</span><span class="cx">
</span><span class="cx">
</span><span class="cx">
</span><del>-Calendar Server Extension C. Daboo
</del><ins>+
+ C. Daboo
</ins><span class="cx"> Apple
</span><del>- January 10, 2014
</del><ins>+ October 30, 2014
</ins><span class="cx">
</span><span class="cx">
</span><span class="cx"> Smart Splitting of Recurring Events in CalDAV
</span><ins>+ caldav-recursplit-01
</ins><span class="cx">
</span><span class="cx"> Abstract
</span><span class="cx">
</span><span class="lines">@@ -15,48 +17,20 @@
</span><span class="cx"> preserve the original per-attendee data, such as alarms and
</span><span class="cx"> participation status.
</span><span class="cx">
</span><del>-
</del><span class="cx"> Table of Contents
</span><span class="cx">
</span><del>- 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2
- 2. Conventions Used in This Document . . . . . . . . . . . . . . . 3
- 3. New behavior . . . . . . . . . . . . . . . . . . . . . . . . . 3
- 3.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . . 6
- 4. Security Considerations . . . . . . . . . . . . . . . . . . . . 8
- 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 8
- 6. Normative References . . . . . . . . . . . . . . . . . . . . . 8
- Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 9
- Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 9
</del><ins>+ 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 1
+ 2. Conventions Used in This Document . . . . . . . . . . . . . . 2
+ 3. New behavior . . . . . . . . . . . . . . . . . . . . . . . . 3
+ 3.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . 5
+ 4. Server Initiated Splitting . . . . . . . . . . . . . . . . . 8
+ 5. Security Considerations . . . . . . . . . . . . . . . . . . . 8
+ 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8
+ 7. Normative References . . . . . . . . . . . . . . . . . . . . 8
+ Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 9
+ Appendix B. Change History . . . . . . . . . . . . . . . . . . . 9
+ Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 9
</ins><span class="cx">
</span><del>-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Daboo [Page 1]
-
- CalDAV Recurrence Splitting January 2014
-
-
</del><span class="cx"> 1. Introduction
</span><span class="cx">
</span><span class="cx"> Internet calendaring and scheduling standards are defined by
</span><span class="lines">@@ -76,6 +50,14 @@
</span><span class="cx"> (different UIDs and thus different calendar object resources stored
</span><span class="cx"> in a CalDAV calendar). One series contains all the instances up to
</span><span class="cx"> the point where the change is made, and the other contains all the
</span><ins>+
+
+
+Daboo Expires May 3, 2015 [Page 1]
+
+ CalDAV Recurrence Splitting October 2014
+
+
</ins><span class="cx"> instances from that point onwards. Typically this is done by
</span><span class="cx"> truncating the recurrence rule in the existing resource and creating
</span><span class="cx"> a new resource for the ongoing recurrence. However, when done that
</span><span class="lines">@@ -104,15 +86,6 @@
</span><span class="cx"> likely resulting in loss of per-attendee data. A future extension to
</span><span class="cx"> iTIP might be possible to address that, but is not covered here.
</span><span class="cx">
</span><del>-
-
-
-
-Daboo [Page 2]
-
- CalDAV Recurrence Splitting January 2014
-
-
</del><span class="cx"> 2. Conventions Used in This Document
</span><span class="cx">
</span><span class="cx"> The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
</span><span class="lines">@@ -134,6 +107,13 @@
</span><span class="cx"> parameters and enumerated values defined in this extension.
</span><span class="cx">
</span><span class="cx">
</span><ins>+
+
+Daboo Expires May 3, 2015 [Page 2]
+
+ CalDAV Recurrence Splitting October 2014
+
+
</ins><span class="cx"> 3. New behavior
</span><span class="cx">
</span><span class="cx"> A server supporting the features described in this specification MUST
</span><span class="lines">@@ -144,51 +124,62 @@
</span><span class="cx"> To split an existing calendar object resource containing a recurring
</span><span class="cx"> event, a client issues an HTTP POST resource with the request-uri set
</span><span class="cx"> to the URI of the calendar object resource. The client also includes
</span><del>- the following two URI query parameters:
</del><ins>+ the following two URI query parameters, and one optional one:
</ins><span class="cx">
</span><del>- 1. "action" set to the value "split"
</del><ins>+ 1. "action" set to the value "split" - REQUIRED
</ins><span class="cx">
</span><span class="cx"> 2. "rid" set to an iCalendar format DATE-TIME value in UTC
</span><del>- ("YYYYMMDDTHHMMSSZ" style format).
</del><ins>+ ("YYYYMMDDTHHMMSSZ" style format) - REQUIRED
</ins><span class="cx">
</span><ins>+ 3. "uid" set to an iCalendar UID property value - OPTIONAL
+
</ins><span class="cx"> The "action" parameter is used to distinguish this operation from
</span><span class="cx"> others that might be defined in the future for calendar object
</span><span class="cx"> resources. The "rid" parameter specified the UTC date-time where the
</span><span class="cx"> split is to occur. The actual split occurs at the next recurrence
</span><span class="cx"> instance on or after the "rid" parameter value - the "split point".
</span><ins>+ The optional "uid" parameter can be used by the client to specify the
+ iCalendar UID property value used in the new calendar object resource
+ created by the server. In the absence of the "uid" parameter, the
+ server will itself generate the UID value for the new calendar object
+ resource.
</ins><span class="cx">
</span><del>- Client MUST include both parameters in the POST request and MUST
- ensure a valid date-time value is used. The date-time value MUST NOT
- be earlier than the start time of the first instance of the
- recurrence set, and it MUST NOT be later than the start time of the
</del><ins>+ Clients MUST include both "action" and "rid" parameters in the POST
+ request and MUST ensure a valid date-time value is used. The date-
+ time value MUST NOT be earlier than the start time of the first
+ instance of the recurrence set, and it MUST NOT be later than the
+ start time of the last instance of the recurrence set. If the "rid"
+ parameter value is not of the correct format or missing, the server
+ MUST return a DAV:error response with the CALDAV:valid-rid-parameter
+ pre-condition code. If the "rid" parameter is valid, but outside of
+ the allowed range, or the targeted calendar object resource is not
+ recurring, then the server MUST return a DAV:error response with the
+ CS:invalid-split pre-condition code. The server MUST reject any
+ attempt by an attendee to split their copy of a scheduled calendar
+ object resource - only organizers are allowed to split events. If
+ the optional "uid" parameter is used by the client, and the server
+ determines that the specified value is invalid (e.g., too short or
+ too long as per reasonable requirements), then it MUST return a
+ DAV:error response with the CS:invalid-split pre-condition code.
</ins><span class="cx">
</span><span class="cx">
</span><span class="cx">
</span><del>-Daboo [Page 3]
</del><ins>+
+Daboo Expires May 3, 2015 [Page 3]
</ins><span class="cx">
</span><del>- CalDAV Recurrence Splitting January 2014
</del><ins>+ CalDAV Recurrence Splitting October 2014
</ins><span class="cx">
</span><span class="cx">
</span><del>- last instance of the recurrence set. If the "rid" parameter value is
- not of the correct format or missing, the server MUST return a DAV:
- error response with the CALDAV:valid-rid-parameter pre-condition
- code. If the "rid" parameter is valid, but outside of the allowed
- range, or the targeted calendar object resource is not recurring,
- then the server MUST return a DAV:error response with the CS:invalid-
- split pre-condition code. The server MUST reject any attempt by an
- attendee to split their copy of a scheduled calendar object resource
- - only organizers are allowed to split events.
-
</del><span class="cx"> Clients MAY include an HTTP "Prefer" request header including the
</span><del>- value "return=representation" (see [I-D.snell-http-prefer]). That
- instructs the server to return a WebDAV multistatus response
- containing two responses: one for the targeted resource and one for
- the new resource created as a result of the split. The multistatus
- response MUST include the DAV:getetag and CALDAV:calendar-data
- properties for each resource. In the absence of the "Prefer:
- return=representation" request header, the server MUST return an HTTP
- "Split-Component-URL" response header whose value is the URI of the
- new resource created as a result of the split.
</del><ins>+ value "return=representation" (see [RFC7240]). That instructs the
+ server to return a WebDAV multistatus response containing two
+ responses: one for the targeted resource and one for the new resource
+ created as a result of the split. The multistatus response MUST
+ include the DAV:getetag and CALDAV:calendar-data properties for each
+ resource. In the absence of the "Prefer:return=representation"
+ request header, the server MUST return an HTTP "Split-Component-URL"
+ response header whose value is the URI of the new resource created as
+ a result of the split.
</ins><span class="cx">
</span><span class="cx"> When a server receives a valid split request as described above, it
</span><span class="cx"> does the equivalent of the following:
</span><span class="lines">@@ -217,14 +208,6 @@
</span><span class="cx"> the split point, or, in the absence of an "RRULE", to the
</span><span class="cx"> first "RDATE" property value on or after the split point.
</span><span class="cx">
</span><del>-
-
-
-Daboo [Page 4]
-
- CalDAV Recurrence Splitting January 2014
-
-
</del><span class="cx"> 3. The calendar data in the new resource is modified as follows:
</span><span class="cx">
</span><span class="cx"> A. Any overridden components with a "RECURRENCE-ID" property
</span><span class="lines">@@ -236,6 +219,13 @@
</span><span class="cx"> C. Any "RRULE" property that only generates instances on or
</span><span class="cx"> after the split point is removed.
</span><span class="cx">
</span><ins>+
+
+Daboo Expires May 3, 2015 [Page 4]
+
+ CalDAV Recurrence Splitting October 2014
+
+
</ins><span class="cx"> D. Any remaining "RRULE" property has an "UNTIL" value applied,
</span><span class="cx"> with the until value being one second less than the split
</span><span class="cx"> point.
</span><span class="lines">@@ -245,12 +235,11 @@
</span><span class="cx">
</span><span class="cx"> F. Attendee participation status MUST NOT be changed.
</span><span class="cx">
</span><del>- 4. The server MUST add a "RELATED" property, with a "RELTYPE"
- parameter set to "X-CALENDARSERVER-RECURRENCE-SET", and with its
- value set to the "UID" property value of the new resource to all
- components of the existing and new resources, if the existing
- resource does not contain a "RELATED" property with a "RELTYPE"
- parameter value set to "X-CALENDARSERVER-RECURRENCE-SET".
</del><ins>+ 4. The server MUST add a "RELATED-TO" property, with a "RELTYPE"
+ parameter set to "X-CALENDARSERVER-RECURRENCE-SET", to all
+ components of the existing and new resources, if one does not
+ already exist. The new property value is set to a new auto-
+ generated "UID" value.
</ins><span class="cx">
</span><span class="cx"> When an organizer splits a scheduled event, the server performs the
</span><span class="cx"> following actions:
</span><span class="lines">@@ -273,14 +262,6 @@
</span><span class="cx"> Note that, since attendees can be invited to specific instances of a
</span><span class="cx"> recurring meeting (not necessarily the entire set), it is possible
</span><span class="cx"> that either the old or new calendar data no longer contains any valid
</span><del>-
-
-
-Daboo [Page 5]
-
- CalDAV Recurrence Splitting January 2014
-
-
</del><span class="cx"> components since the attendee was not invited to the corresponding
</span><span class="cx"> portions of the original split recurrence. In such cases, the server
</span><span class="cx"> MUST remove the original resource, or MUST NOT create the new
</span><span class="lines">@@ -290,6 +271,17 @@
</span><span class="cx">
</span><span class="cx"> Assume the following iCalendar data is stored in the resource with
</span><span class="cx"> URI "/event.ics":
</span><ins>+
+
+
+
+
+
+Daboo Expires May 3, 2015 [Page 5]
+
+ CalDAV Recurrence Splitting October 2014
+
+
</ins><span class="cx"> BEGIN:VCALENDAR
</span><span class="cx"> PRODID:-//Example Inc.//Example Calendar//EN
</span><span class="cx"> VERSION:2.0
</span><span class="lines">@@ -329,14 +321,6 @@
</span><span class="cx"> <propstat>
</span><span class="cx"> <prop>
</span><span class="cx"> <getetag>"5bc9a2b55081eba0a9cd34f742aa1c11"</getetag>
</span><del>-
-
-
-Daboo [Page 6]
-
- CalDAV Recurrence Splitting January 2014
-
-
</del><span class="cx"> <calendar-data xmlns='urn:ietf:params:xml:ns:caldav'
</span><span class="cx"> >BEGIN:VCALENDAR
</span><span class="cx"> VERSION:2.0
</span><span class="lines">@@ -346,8 +330,16 @@
</span><span class="cx"> DTSTART:20140110T120000Z
</span><span class="cx"> DURATION:PT1H
</span><span class="cx"> DTSTAMP:20140110T135358Z
</span><del>- RELATED-TO;RELTYPE=X-CALENDARSERVER-RECURRENCE-SET:E3B9D6D4-E19F-
- 47AA-9088-1A29A9A7030F
</del><ins>+
+
+
+Daboo Expires May 3, 2015 [Page 6]
+
+ CalDAV Recurrence Splitting October 2014
+
+
+ RELATED-TO;RELTYPE=X-CALENDARSERVER-RECURRENCE-SET:8DE45ECB-8145-
+ 4AEC-B3E1-11A9DB22A578
</ins><span class="cx"> RRULE:FREQ=DAILY;COUNT=11
</span><span class="cx"> SUMMARY:Example
</span><span class="cx"> END:VEVENT
</span><span class="lines">@@ -368,11 +360,11 @@
</span><span class="cx"> PRODID:-//Example Inc.//Example Calendar//EN
</span><span class="cx"> BEGIN:VEVENT
</span><span class="cx"> UID:E3B9D6D4-E19F-47AA-9088-1A29A9A7030F
</span><del>- DTSTART:20140101T120000Z
</del><ins>+ DTSTART:20140110T120000Z
</ins><span class="cx"> DURATION:PT1H
</span><span class="cx"> DTSTAMP:20140110T135358Z
</span><del>- RELATED-TO;RELTYPE=X-CALENDARSERVER-RECURRENCE-SET:E3B9D6D4-E19F-
- 47AA-9088-1A29A9A7030F
</del><ins>+ RELATED-TO;RELTYPE=X-CALENDARSERVER-RECURRENCE-SET:8DE45ECB-8145-
+ 4AEC-B3E1-11A9DB22A578
</ins><span class="cx"> RRULE:FREQ=DAILY;UNTIL=20140110T115959Z
</span><span class="cx"> SUMMARY:Example
</span><span class="cx"> END:VEVENT
</span><span class="lines">@@ -385,44 +377,48 @@
</span><span class="cx"> </multistatus>
</span><span class="cx">
</span><span class="cx"> The original resource is changed to have a start date-time value of
</span><del>-
-
-
-Daboo [Page 7]
-
- CalDAV Recurrence Splitting January 2014
-
-
</del><span class="cx"> "20140110T120000Z", and the "COUNT" component of the "RRULE" property
</span><span class="cx"> is adjusted to the value "11" (which represents the number of
</span><span class="cx"> remaining instances for that event, 9 early instances having been
</span><span class="cx"> removed). The new resource has the original start date-time value,
</span><span class="cx"> and its "RRULE" property has an "UNTIL" value one second prior to the
</span><del>- split point. Both resources have a "RELATED" property with a
</del><ins>+ split point. Both resources have a "RELATED-TO" property with a
</ins><span class="cx"> "RELTYPE" parameter set to "X-CALENDARSERVER-RECURRENCE-SET" and a
</span><del>- value set to the "UID" property value of the new resource.
</del><ins>+ value set to a new "UID" value.
</ins><span class="cx">
</span><span class="cx">
</span><del>-4. Security Considerations
</del><span class="cx">
</span><ins>+
+Daboo Expires May 3, 2015 [Page 7]
+
+ CalDAV Recurrence Splitting October 2014
+
+
+4. Server Initiated Splitting
+
+ Servers can automatically split events that have already been stored
+ by the client. The trigger for such splitting is up to the server
+ (e.g., it can split when a recurring event exceeds a certain size, or
+ when a certain number of instances are now in the past). When
+ splitting, the server MUST use the approach outlined above - namely
+ create a new calendar object resource for the past instances,
+ truncate the existing calendar data and use the "RELATED_TO" property
+ to link them. In other words, this will look exactly like a client-
+ initiated split.
+
+5. Security Considerations
+
</ins><span class="cx"> This specification does not introduce any more security
</span><span class="cx"> considerations beyond those already listed in iCalendar [RFC5545],
</span><span class="cx"> iTIP [RFC5546] and CalDAV Access [RFC4791] and CalDAV Scheduling
</span><span class="cx"> [RFC6638].
</span><span class="cx">
</span><ins>+6. IANA Considerations
</ins><span class="cx">
</span><del>-5. IANA Considerations
-
</del><span class="cx"> TBD: new HTTP request header registration.
</span><span class="cx">
</span><ins>+7. Normative References
</ins><span class="cx">
</span><del>-6. Normative References
-
- [I-D.snell-http-prefer]
- Snell, J., "Prefer Header for HTTP",
- draft-snell-http-prefer-18 (work in progress),
- January 2013.
-
</del><span class="cx"> [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
</span><span class="cx"> Requirement Levels", BCP 14, RFC 2119, March 1997.
</span><span class="cx">
</span><span class="lines">@@ -435,18 +431,23 @@
</span><span class="cx"> September 2009.
</span><span class="cx">
</span><span class="cx"> [RFC5546] Daboo, C., "iCalendar Transport-Independent
</span><del>- Interoperability Protocol (iTIP)", RFC 5546,
- December 2009.
</del><ins>+ Interoperability Protocol (iTIP)", RFC 5546, December
+ 2009.
</ins><span class="cx">
</span><span class="cx"> [RFC6638] Daboo, C. and B. Desruisseaux, "Scheduling Extensions to
</span><span class="cx"> CalDAV", RFC 6638, June 2012.
</span><span class="cx">
</span><ins>+ [RFC7240] Snell, J., "Prefer Header for HTTP", RFC 7240, June 2014.
</ins><span class="cx">
</span><span class="cx">
</span><span class="cx">
</span><del>-Daboo [Page 8]
</del><ins>+
+
+
+
+Daboo Expires May 3, 2015 [Page 8]
</ins><span class="cx">
</span><del>- CalDAV Recurrence Splitting January 2014
</del><ins>+ CalDAV Recurrence Splitting October 2014
</ins><span class="cx">
</span><span class="cx">
</span><span class="cx"> Appendix A. Acknowledgments
</span><span class="lines">@@ -454,7 +455,15 @@
</span><span class="cx"> This specification is the result of discussions between the Apple
</span><span class="cx"> calendar server and client teams.
</span><span class="cx">
</span><ins>+Appendix B. Change History
</ins><span class="cx">
</span><ins>+ Changes since -01
+
+ 1. Added "uid" query parameter to POST request
+
+ 2. New "RELATED-TO" is now a new UID value not the value of the new
+ resource
+
</ins><span class="cx"> Author's Address
</span><span class="cx">
</span><span class="cx"> Cyrus Daboo
</span><span class="lines">@@ -492,13 +501,4 @@
</span><span class="cx">
</span><span class="cx">
</span><span class="cx">
</span><del>-
-
-
-
-
-
-
-
-Daboo [Page 9]
-
</del><ins>+Daboo Expires May 3, 2015 [Page 9]
</ins></span></pre></div>
<a id="CalendarServertrunkdocExtensionscaldavrecursplitxml"></a>
<div class="modfile"><h4>Modified: CalendarServer/trunk/doc/Extensions/caldav-recursplit.xml (14126 => 14127)</h4>
<pre class="diff"><span>
<span class="info">--- CalendarServer/trunk/doc/Extensions/caldav-recursplit.xml 2014-10-31 02:08:53 UTC (rev 14126)
+++ CalendarServer/trunk/doc/Extensions/caldav-recursplit.xml 2014-10-31 14:29:02 UTC (rev 14127)
</span><span class="lines">@@ -6,7 +6,7 @@
</span><span class="cx"> <!ENTITY rfc5546 PUBLIC '' 'bibxml/reference.RFC.5546.xml'>
</span><span class="cx"> <!ENTITY rfc4791 PUBLIC '' 'bibxml/reference.RFC.4791.xml'>
</span><span class="cx"> <!ENTITY rfc6638 PUBLIC '' 'bibxml/reference.RFC.6638.xml'>
</span><del>-<!ENTITY idPreferHeader SYSTEM 'http://xml.resource.org/public/rfc/bibxml3/reference.I-D.snell-http-prefer.xml'>
</del><ins>+<!ENTITY rfc7240 PUBLIC '' 'bibxml/reference.RFC.7240.xml'>
</ins><span class="cx"> ]>
</span><span class="cx"> <?rfc toc="yes"?>
</span><span class="cx"> <?rfc tocdepth="4"?>
</span><span class="lines">@@ -18,7 +18,7 @@
</span><span class="cx"> <?rfc compact="yes"?>
</span><span class="cx"> <?rfc subcompact="no"?>
</span><span class="cx"> <?rfc private="Calendar Server Extension"?>
</span><del>-<rfc ipr="none" docName='caldav-recursplit-00'>
</del><ins>+<rfc ipr="none" docName='caldav-recursplit-01'>
</ins><span class="cx"> <front>
</span><span class="cx"> <title abbrev="CalDAV Recurrence Splitting">Smart Splitting of Recurring Events in CalDAV</title>
</span><span class="cx"> <author initials="C." surname="Daboo" fullname="Cyrus Daboo">
</span><span class="lines">@@ -76,17 +76,18 @@
</span><span class="cx">
</span><span class="cx"> <section title="New behavior">
</span><span class="cx"> <t>A server supporting the features described in this specification MUST include "calendarserver-recurrence-split" as a field in the DAV response header from an OPTIONS request on a calendar home collection.</t>
</span><del>- <t>To split an existing calendar object resource containing a recurring event, a client issues an HTTP POST resource with the request-uri set to the URI of the calendar object resource. The client also includes the following two URI query parameters:
</del><ins>+ <t>To split an existing calendar object resource containing a recurring event, a client issues an HTTP POST resource with the request-uri set to the URI of the calendar object resource. The client also includes the following two URI query parameters, and one optional one:
</ins><span class="cx"> <list style='numbers'>
</span><del>- <t>"action" set to the value "split"</t>
- <t>"rid" set to an iCalendar format DATE-TIME value in UTC ("YYYYMMDDTHHMMSSZ" style format).</t>
</del><ins>+ <t>"action" set to the value "split" - REQUIRED</t>
+ <t>"rid" set to an iCalendar format DATE-TIME value in UTC ("YYYYMMDDTHHMMSSZ" style format) - REQUIRED</t>
+ <t>"uid" set to an iCalendar UID property value - OPTIONAL</t>
</ins><span class="cx"> </list>
</span><del>- The "action" parameter is used to distinguish this operation from others that might be defined in the future for calendar object resources. The "rid" parameter specified the UTC date-time where the split is to occur. The actual split occurs at the next recurrence instance on or after the "rid" parameter value - the "split point".</t>
</del><ins>+ The "action" parameter is used to distinguish this operation from others that might be defined in the future for calendar object resources. The "rid" parameter specified the UTC date-time where the split is to occur. The actual split occurs at the next recurrence instance on or after the "rid" parameter value - the "split point". The optional "uid" parameter can be used by the client to specify the iCalendar UID property value used in the new calendar object resource created by the server. In the absence of the "uid" parameter, the server will itself generate the UID value for the new calendar object resource.</t>
</ins><span class="cx"> <t>
</span><del>- Client MUST include both parameters in the POST request and MUST ensure a valid date-time value is used. The date-time value MUST NOT be earlier than the start time of the first instance of the recurrence set, and it MUST NOT be later than the start time of the last instance of the recurrence set. If the "rid" parameter value is not of the correct format or missing, the server MUST return a DAV:error response with the CALDAV:valid-rid-parameter pre-condition code. If the "rid" parameter is valid, but outside of the allowed range, or the targeted calendar object resource is not recurring, then the server MUST return a DAV:error response with the CS:invalid-split pre-condition code. The server MUST reject any attempt by an attendee to split their copy of a scheduled calendar object resource - only organizers are allowed to split events.
</del><ins>+ Clients MUST include both "action" and "rid" parameters in the POST request and MUST ensure a valid date-time value is used. The date-time value MUST NOT be earlier than the start time of the first instance of the recurrence set, and it MUST NOT be later than the start time of the last instance of the recurrence set. If the "rid" parameter value is not of the correct format or missing, the server MUST return a DAV:error response with the CALDAV:valid-rid-parameter pre-condition code. If the "rid" parameter is valid, but outside of the allowed range, or the targeted calendar object resource is not recurring, then the server MUST return a DAV:error response with the CS:invalid-split pre-condition code. The server MUST reject any attempt by an attendee to split their copy of a scheduled calendar object resource - only organizers are allowed to split events. If the optional "uid" parameter is used by the cl
ient, and the server determines that the specified value is invalid (e.g., too short or too long as per reasonable requirements), then it MUST return a DAV:error response with the CS:invalid-split pre-condition code.
</ins><span class="cx"> </t>
</span><span class="cx"> <t>
</span><del>- Clients MAY include an HTTP "Prefer" request header including the value "return=representation" (see <xref target='I-D.snell-http-prefer'/>). That instructs the server to return a WebDAV multistatus response containing two responses: one for the targeted resource and one for the new resource created as a result of the split. The multistatus response MUST include the DAV:getetag and CALDAV:calendar-data properties for each resource. In the absence of the "Prefer:return=representation" request header, the server MUST return an HTTP "Split-Component-URL" response header whose value is the URI of the new resource created as a result of the split.
</del><ins>+ Clients MAY include an HTTP "Prefer" request header including the value "return=representation" (see <xref target='RFC7240'/>). That instructs the server to return a WebDAV multistatus response containing two responses: one for the targeted resource and one for the new resource created as a result of the split. The multistatus response MUST include the DAV:getetag and CALDAV:calendar-data properties for each resource. In the absence of the "Prefer:return=representation" request header, the server MUST return an HTTP "Split-Component-URL" response header whose value is the URI of the new resource created as a result of the split.
</ins><span class="cx"> </t>
</span><span class="cx"> <t>
</span><span class="cx"> When a server receives a valid split request as described above, it does the equivalent of the following:
</span><span class="lines">@@ -112,7 +113,7 @@
</span><span class="cx"> </list>
</span><span class="cx"> </t>
</span><span class="cx"> <t>
</span><del>- The server MUST add a "RELATED" property, with a "RELTYPE" parameter set to "X-CALENDARSERVER-RECURRENCE-SET", and with its value set to the "UID" property value of the new resource to all components of the existing and new resources, if the existing resource does not contain a "RELATED" property with a "RELTYPE" parameter value set to "X-CALENDARSERVER-RECURRENCE-SET".
</del><ins>+ The server MUST add a "RELATED-TO" property, with a "RELTYPE" parameter set to "X-CALENDARSERVER-RECURRENCE-SET", to all components of the existing and new resources, if one does not already exist. The new property value is set to a new auto-generated "UID" value.
</ins><span class="cx"> </t>
</span><span class="cx"> </list>
</span><span class="cx"> </t>
</span><span class="lines">@@ -182,8 +183,8 @@
</span><span class="cx"> DTSTART:20140110T120000Z
</span><span class="cx"> DURATION:PT1H
</span><span class="cx"> DTSTAMP:20140110T135358Z
</span><del>-RELATED-TO;RELTYPE=X-CALENDARSERVER-RECURRENCE-SET:E3B9D6D4-E19F-
- 47AA-9088-1A29A9A7030F
</del><ins>+RELATED-TO;RELTYPE=X-CALENDARSERVER-RECURRENCE-SET:8DE45ECB-8145-
+ 4AEC-B3E1-11A9DB22A578
</ins><span class="cx"> RRULE:FREQ=DAILY;COUNT=11
</span><span class="cx"> SUMMARY:Example
</span><span class="cx"> END:VEVENT
</span><span class="lines">@@ -204,11 +205,11 @@
</span><span class="cx"> PRODID:-//Example Inc.//Example Calendar//EN
</span><span class="cx"> BEGIN:VEVENT
</span><span class="cx"> UID:E3B9D6D4-E19F-47AA-9088-1A29A9A7030F
</span><del>-DTSTART:20140101T120000Z
</del><ins>+DTSTART:20140110T120000Z
</ins><span class="cx"> DURATION:PT1H
</span><span class="cx"> DTSTAMP:20140110T135358Z
</span><del>-RELATED-TO;RELTYPE=X-CALENDARSERVER-RECURRENCE-SET:E3B9D6D4-E19F-
- 47AA-9088-1A29A9A7030F
</del><ins>+RELATED-TO;RELTYPE=X-CALENDARSERVER-RECURRENCE-SET:8DE45ECB-8145-
+ 4AEC-B3E1-11A9DB22A578
</ins><span class="cx"> RRULE:FREQ=DAILY;UNTIL=20140110T115959Z
</span><span class="cx"> SUMMARY:Example
</span><span class="cx"> END:VEVENT
</span><span class="lines">@@ -222,11 +223,14 @@
</span><span class="cx"> ]]></artwork></figure>
</span><span class="cx"> </t>
</span><span class="cx"> <t>
</span><del>- The original resource is changed to have a start date-time value of "20140110T120000Z", and the "COUNT" component of the "RRULE" property is adjusted to the value "11" (which represents the number of remaining instances for that event, 9 early instances having been removed). The new resource has the original start date-time value, and its "RRULE" property has an "UNTIL" value one second prior to the split point. Both resources have a "RELATED" property with a "RELTYPE" parameter set to "X-CALENDARSERVER-RECURRENCE-SET" and a value set to the "UID" property value of the new resource.
</del><ins>+ The original resource is changed to have a start date-time value of "20140110T120000Z", and the "COUNT" component of the "RRULE" property is adjusted to the value "11" (which represents the number of remaining instances for that event, 9 early instances having been removed). The new resource has the original start date-time value, and its "RRULE" property has an "UNTIL" value one second prior to the split point. Both resources have a "RELATED-TO" property with a "RELTYPE" parameter set to "X-CALENDARSERVER-RECURRENCE-SET" and a value set to a new "UID" value.
</ins><span class="cx"> </t>
</span><span class="cx"> </section>
</span><span class="cx"> </section>
</span><span class="cx">
</span><ins>+ <section title='Server Initiated Splitting'>
+ <t>Servers can automatically split events that have already been stored by the client. The trigger for such splitting is up to the server (e.g., it can split when a recurring event exceeds a certain size, or when a certain number of instances are now in the past). When splitting, the server MUST use the approach outlined above - namely create a new calendar object resource for the past instances, truncate the existing calendar data and use the "RELATED_TO" property to link them. In other words, this will look exactly like a client-initiated split.</t>
+ </section>
</ins><span class="cx"> <section title='Security Considerations'>
</span><span class="cx"> <t>This specification does not introduce any more security considerations beyond those already listed in <xref target="RFC5545">iCalendar</xref>, <xref target="RFC5546">iTIP</xref> and <xref target="RFC4791">CalDAV Access</xref> and <xref target="RFC6638">CalDAV Scheduling</xref>.</t>
</span><span class="cx"> </section>
</span><span class="lines">@@ -243,7 +247,7 @@
</span><span class="cx"> &rfc5546;
</span><span class="cx"> &rfc4791;
</span><span class="cx"> &rfc6638;
</span><del>- &idPreferHeader;
</del><ins>+ &rfc7240;
</ins><span class="cx"> </references>
</span><span class="cx"> <!--
</span><span class="cx"> <references title='Informative References'>
</span><span class="lines">@@ -254,14 +258,13 @@
</span><span class="cx"> This specification is the result of discussions between the Apple calendar server and client teams.
</span><span class="cx"> </t>
</span><span class="cx"> </section>
</span><del>- <!--
</del><span class="cx"> <section title='Change History'>
</span><del>- <t>Changes since -00
</del><ins>+ <t>Changes since -01
</ins><span class="cx"> <list style='numbers'>
</span><del>- <t></t>
</del><ins>+ <t>Added "uid" query parameter to POST request</t>
+ <t>New "RELATED-TO" is now a new UID value not the value of the new resource</t>
</ins><span class="cx"> </list>
</span><span class="cx"> </t>
</span><span class="cx"> </section>
</span><del>- -->
</del><span class="cx"> </back>
</span><span class="cx"> </rfc>
</span></span></pre>
</div>
</div>
</body>
</html>