


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


       <!ELEMENT schedule-changes
                 (dtstamp, action) >

       <!ELEMENT dtstamp CDATA>
       <!-- Date-time value in UTC -->

       <!ELEMENT action (create|update|cancel|reply)>
       <!-- Type of change that occurred -->

       <!ELEMENT create EMPTY>
       <!-- New calendar object was created -->

       <!ELEMENT update (recurrence+)>
       <!-- Calendar object was changed -->

       <!ELEMENT cancel (recurrence*)>
       <!-- Calendar object was cancelled -->

       <!ELEMENT reply (attendee, recurrence+)>
       <!-- Reply received from attendee -->

       <!ELEMENT recurrence
           ((master | recurrenceid), changes)>
       <!-- Which instances were affected by the change,
            and details on the per-instance changes -->

       <!ELEMENT master EMPTY>
       <!-- The "master" instance was affected -->

       <!ELEMENT recurrenceid CDATA>
       <!-- RECURRENCE-ID value for the affected instance -->

       <!ELEMENT changes changed-property*>
       <!-- Detailed changes in the iCalendar data -->

       <!ELEMENT changed-property changed-parameter*>
       <!ATTLIST changed-property name PCDATA>
       <!-- An iCalendar property changed -->

       <!ELEMENT changed-parameter EMPTY>
       <!ATTLIST changed-parameter name PCDATA>
       <!-- An iCalendar property parameter changed -->

       <!ELEMENT attendee CDATA>
       <!-- ATTENDEE iCalendar property value -->






Daboo                                                           [Page 4]

                   CalDAV Scheduling Change Indicators        April 2009


   Example:  This example indicates that a new calendar component was
      created.

   <CS:schedule-changes
        xmlns:CS="http://calendarserver.org/ns/">
     <CS:dtstamp>20080818T223423Z</CS:dtstamp>
     <CS:action>
       <CS:create/>
     </CS:action>
   </CS:schedule-changes>

   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.

   <CS:schedule-changes
        xmlns:CS="http://calendarserver.org/ns/">
     <CS:dtstamp>20080818T223423Z</CS:dtstamp>
     <CS:action>
       <CS:update>
         <CS:recurrence>
           <CS:master/>
           <CS:changes>
             <CS:changed-property name="SUMMARY"/>
           </CS:changes>
         <CS:recurrence/>
       </CS:update>
     </CS:action>
   </CS:schedule-changes>

   Example:  This example indicates that two recurrence instances were
      cancelled from a recurring component.

   <CS:schedule-changes
        xmlns:CS="http://calendarserver.org/ns/">
     <CS:dtstamp>20080818T223423Z</CS:dtstamp>
     <CS:action>
       <CS:cancel>
         <CS:recurrence>
           <CS:recurrence-id>20090101T010000Z</CS:recurrence-id>
         <CS:recurrence/>
         <CS:recurrence>
           <CS:recurrence-id>20090102T010000Z</CS:recurrence-id>
         <CS:recurrence/>
       </CS:update>
     </CS:action>
   </CS:schedule-changes>




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.

   <CS:schedule-changes
        xmlns:CS="http://calendarserver.org/ns/">
     <CS:dtstamp>20080818T223423Z</CS:dtstamp>
     <CS:action>
       <CS:reply>
         <CS:attendee>mailto:cyrus@example.com</CS:attendee>
         <CS:recurrence>
           <CS:recurrence-id>20090101T010000Z</CS:recurrence-id>
           <CS:changes>
             <CS:changed-property name="ATTENDEE">
               <CS:changed-parameter name="PARTSTAT"/>
             </CS:changed-property>
           </CS:changes>
         <CS:recurrence/>
       </CS:update>
     </CS:action>
   </CS:schedule-changes>

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]

