Calendar Server Extension C. Daboo Apple April 26, 2009 Change Indicators for Processed CalDAV Scheduling Messages Abstract This document defines an extension to CalDAV Scheduling that adds a change summary for scheduling messages automatically processed by the server. It can be used by clients to provide a detailed indication to a calendar user of how a calendar object was changed by auto- processing of a scheduling message. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2 2. Conventions Used in This Document . . . . . . . . . . . . . . . 2 3. New behavior . . . . . . . . . . . . . . . . . . . . . . . . . 2 4. New features . . . . . . . . . . . . . . . . . . . . . . . . . 3 4.1. CalDAV Changes . . . . . . . . . . . . . . . . . . . . . . 3 4.1.1. Change Indicator WebDAV Property . . . . . . . . . . . 3 4.1.2. CS:schedule-changes XML element . . . . . . . . . . . . 6 4.1.2.1. CS:dtstamp XML Element . . . . . . . . . . . . . . 6 4.1.2.2. CS:action XML Element . . . . . . . . . . . . . . . 6 4.1.2.3. CS:recurrence XML Element . . . . . . . . . . . . . 7 4.1.2.4. CS:changes XML Element . . . . . . . . . . . . . . 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 Daboo [Page 1] CalDAV Scheduling Change Indicators April 2009 1. Introduction Internet calendaring and scheduling standards are defined by iCalendar [RFC2445] and iTIP [RFC2446]. The CalDAV Access [RFC4791] standard defines a way to access calendar data stored on a server, and the CalDAV Scheduling [I-D.desruisseaux-caldav-sched] draft defines how scheduling occurs between users of a CalDAV server. In CalDAV Scheduling, scheduling messages sent between calendar users can be automatically processed by the CalDAV server. Often clients need to provide an indication to the user of what changed when such auto-processing occurs (e.g. to inform the user that an event was re- scheduling or cancelled). Sometimes the client does not have the old copy of the automatically updated calendar object to hand, so as a result it can't determine changes itself. This specification defines a new WebDAV property on scheduling messages stored in a calendar user's scheduling Inbox collection. This property is automatically generated by the server and contains XML data representing the changes made by the server when it auto- processed the scheduling message. Clients can use the data in this property to provide an indication to a calendar user as to what changed. 2. Conventions Used in This Document The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. When XML element types in the namespaces "DAV:" and "urn:ietf:params:xml:ns:caldav" are referenced in this document outside of the context of an XML fragment, the string "DAV:" and "CALDAV:" will be prefixed to the element type names respectively. The namespace "http://calendarserver.org/ns/" is used for XML elements defined in this specification. When XML element types in this namespace are referenced in this document outside of the context of an XML fragment, the string "CS:" will be prefixed to the element type names respectively. 3. New behavior When a CalDAV scheduling server automatically processes a scheduling message in a scheduling inbox collection, it SHOULD determine what changes were applied to the matching scheduling object resource and Daboo [Page 2] CalDAV Scheduling Change Indicators April 2009 create an XML data value (as described next) and store that in the CS:schedule-changes property on the scheduling message resource. When a client checks the scheduling inbox collection to look for scheduling messages that need to be acknowledged by a calendar user, the client MAY check for the presence of the CS:schedule-changes and retrieve its value via a PROPFIND or CALDAV:multiget REPORT request. The XML data value can then be parsed and useful information extracted and presented to the user in whatever way is appropriate for the client. 4. New features 4.1. CalDAV Changes 4.1.1. Change Indicator WebDAV Property Name: schedule-changes Namespace: http://calendarserver.org/ns/ Purpose: Indicates what changed when a scheduling message was automatically processed by a server. Protected: This property MUST be protected and SHOULD NOT be returned by a PROPFIND allprop request (as defined in Section 14.2 of [RFC4918]). COPY/MOVE behavior: This property value SHOULD be kept during a MOVE operation, but is normally re-initialized when a resource is created with a COPY. It should not be set in a COPY. Description: This property SHOULD be defined on all scheduling messages that have been automatically processed by the server. If present, it contains a single CS:calendar-changes XML element. Definition: Daboo [Page 3] CalDAV Scheduling Change Indicators April 2009 Daboo [Page 4] CalDAV Scheduling Change Indicators April 2009 Example: This example indicates that a new calendar component was created. 20080818T223423Z Example: This example indicates that a non-recurring component, or the master component in a recurring component, was changed and that the change was to the "SUMMARY" iCalendar property. 20080818T223423Z Example: This example indicates that two recurrence instances were cancelled from a recurring component. 20080818T223423Z 20090101T010000Z 20090102T010000Z Daboo [Page 5] CalDAV Scheduling Change Indicators April 2009 Example: This example indicates that the Attendee with calendar user address "mailto:cyrus@example.com" replied to the Organizer and changed their "PARTSTAT" iCalendar property parameter on one recurrence instance. 20080818T223423Z mailto:cyrus@example.com 20090101T010000Z 4.1.2. CS:schedule-changes XML element The CS:schedule-changes XML element is used to indicate what changes were made when the server automatically processed a scheduling message. There are two child elements that can appear, and each is described next. 4.1.2.1. CS:dtstamp XML Element This element contains a text value in the form of an iCalendar Date- Time value in UTC. This value is the time at which the automatic processing took place. 4.1.2.2. CS:action XML Element This element indicates the nature of the changes that took place: Daboo [Page 6] CalDAV Scheduling Change Indicators April 2009 +-----------+-------------------------------------------------------+ | Child | Description | | Element | | +-----------+-------------------------------------------------------+ | CS:create | A new calendar object was created in the default | | | calendar of the recipient. | | | | | CS:update | An update to an existing calendar object occurred. A | | | CS:recurrence element is included for each recurrence | | | instance changed. Each CS:recurrence element | | | indicates the specific instance that was changes as | | | well as details on which properties or parameters | | | changed. | | | | | CS:cancel | A cancellation scheduling message was processed. If | | | the calendar object is not recurring or all instances | | | are being removed, then there MUST NOT be any | | | CS:recurrence element present. If any individual | | | instances of a recurring calendar object were | | | affected, then a CS:recurrence element MUST be | | | present and indicate which instances were affected. | | | | | CS:reply | An Attendee's reply was processed. The CS:attendee, | | | element indicates which Attendee replied. The | | | CS:recurrence element indicates which recurrence | | | instance was changed and whether the change was to | | | the Attendee's PARTSTAT parameter or | | | X-CALENDARSERVER-PRIVATE-COMMENT property. | +-----------+-------------------------------------------------------+ 4.1.2.3. CS:recurrence XML Element This element indicates which instances were affected by a change: +-----------------+-------------------------------------------------+ | Child Element | Description | +-----------------+-------------------------------------------------+ | CS:master | The "master" component defining the recurrence | | | pattern was changed, or a non-recurring | | | component was changed. | | | | | CS:recurrenceid | The instance with the specified "RECURRENCE-ID" | | | value was changed. | | | | | CS:changes | Detailed changes - see next section. This | | | element is not present when processing a | | | "CANCEL". | +-----------------+-------------------------------------------------+ Daboo [Page 7] CalDAV Scheduling Change Indicators April 2009 4.1.2.4. CS:changes XML Element This element indicates the key changes that took place. +---------------------+---------------------------------------------+ | Child Element | Description | +---------------------+---------------------------------------------+ | CS:changed-property | Indicates which iCalendar property changed. | | | The "name" attribute on the XML element is | | | the name of the iCalendar property that | | | changed. There MUST only be one | | | CS:changed-property element for a specific | | | name attribute value, i.e. if multiple | | | properties of the same name changed, only | | | one CS:changed-property will appear. For | | | each CS:changed-property element, if any | | | property parameters were changed on the | | | corresponding properties, then those should | | | be included as CS:changed-parameter child | | | elements, with the "name" attribute on | | | those elements containing the name of the | | | iCalendar property parameter changed. As | | | with CS:changed-property, there MUST only | | | be one CS:changed-parameter element for | | | each iCalendar property parameter that | | | changed. | +---------------------+---------------------------------------------+ 5. Security Considerations TODO: 6. IANA Considerations This document does not require any actions on the part of IANA. 7. Normative References [I-D.desruisseaux-caldav-sched] Daboo, C. and B. Desruisseaux, "CalDAV Scheduling Extensions to WebDAV", draft-desruisseaux-caldav-sched-06 (work in progress), November 2008. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. Daboo [Page 8] CalDAV Scheduling Change Indicators April 2009 [RFC2445] Dawson, F. and Stenerson, D., "Internet Calendaring and Scheduling Core Object Specification (iCalendar)", RFC 2445, November 1998. [RFC2446] Silverberg, S., Mansour, S., Dawson, F., and R. Hopson, "iCalendar Transport-Independent Interoperability Protocol (iTIP) Scheduling Events, BusyTime, To-dos and Journal Entries", RFC 2446, November 1998. [RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault, "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791, March 2007. [RFC4918] Dusseault, L., "HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV)", RFC 4918, June 2007. Appendix A. Acknowledgments This specification is the result of discussions between the Apple calendar server and client teams. Appendix B. Change History Changes in -03 1. Re-worked XML schema to allow for per-instance changes to be indicated. Changes in -02 1. CS:changes element changed to use CS:changed-property child elements for more detailed information. Author's Address Cyrus Daboo Apple Inc. 1 Infinite Loop Cupertino, CA 95014 USA Email: cyrus@daboo.name URI: http://www.apple.com/ Daboo [Page 9]