


Calendar Server Extension                                       C. Daboo
                                                                   Apple
                                                       February 28, 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 . . . . . . . . . . . . 5
         4.1.2.1.  CS:dtstamp XML Element  . . . . . . . . . . . . . . 5
         4.1.2.2.  CS:action XML Element . . . . . . . . . . . . . . . 5
         4.1.2.3.  CS:changes XML Element  . . . . . . . . . . . . . . 6
         4.1.2.4.  CS:recurrences XML Element  . . . . . . . . . . . . 7
   5.  Security Considerations . . . . . . . . . . . . . . . . . . . . 7
   6.  IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 7
   7.  Normative References  . . . . . . . . . . . . . . . . . . . . . 7
   Appendix A.  Acknowledgments  . . . . . . . . . . . . . . . . . . . 8
   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . . . 8

















Daboo                                                           [Page 1]

                   CalDAV Scheduling Change Indicators     February 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     February 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     February 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 (changes, recurrences?)>
       <!-- Calendar object was changed -->

       <!ELEMENT cancel (recurrences?)>
       <!-- Calendar object or instances were cancelled -->

       <!ELEMENT reply (attendee, partstat?, private-comment?,
                        recurrences?)>
       <!-- Reply received from attendee -->

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

       <!ELEMENT partstat EMPTY>
       <!-- ATTENDEE PARTSTAT property parameter value changed -->

       <!ELEMENT private-comment EMPTY>
       <!-- X-CALENDARSERVER-PRIVATE-COMMENT property value
            changed -->

       <!ELEMENT changes changed-property*>
       <!ATTLIST changed-property name PCDATA>

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

       <!ELEMENT recurrences (master?, recurrenceid*)>
       <!-- Which instances were affected by the change -->

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

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





Daboo                                                           [Page 4]

                   CalDAV Scheduling Change Indicators     February 2009


   Example:

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

   Example:

   <CS:schedule-changes
        xmlns:CS="http://calendarserver.org/ns/">
     <CS:dtstamp>20080818T223423Z</CS:dtstamp>
     <CS:action>
       <CS:update>
         <CS:changes>
           <CS:changed-property name="SUMMARY"/>
         </CS:changes>
         <CS:recurrences/>
       </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 four child elements that can appear, and each is
   described next.

4.1.2.1.  CS:dtstamp XML Element

   This elements 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 5]

                   CalDAV Scheduling Change Indicators     February 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.    |
   |           | The CS:changes and CS:recurrences child elements      |
   |           | indicate what the changes were and which instances    |
   |           | were affected.  If the calendar object is not         |
   |           | recurring, CS:recurrences MUST NOT be present.  If    |
   |           | all or any individual instances of a recurring        |
   |           | calendar object were affected, then CS:recurrences    |
   |           | MUST be present and indicate which instances were     |
   |           | affected.                                             |
   |           |                                                       |
   | CS:cancel | A cancellation scheduling message was processed.  If  |
   |           | the calendar object is not recurring or all instances |
   |           | are being removed, then CS:recurrences MUST NOT be    |
   |           | present.  If any individual instances of a recurring  |
   |           | calendar object were affected, then CS:recurrences    |
   |           | MUST be present and indicate which instances were     |
   |           | affected.                                             |
   |           |                                                       |
   | CS:reply  | An Attendee's reply was processed.  The CS:attendee,  |
   |           | CS:partstat and CS:private-comment elements indicate  |
   |           | which Attendee replied, whether their "PARTSTAT"      |
   |           | changed, and whether any private comment was changed. |
   |           | The CS:partstat and CS:private-comment child elements |
   |           | MUST only be present if the relevant properties or    |
   |           | parameters were changed.  If the calendar object is   |
   |           | not recurring, CS:recurrences MUST NOT be present.    |
   |           | If all or any individual instances of a recurring     |
   |           | calendar object were affected, then CS:recurrences    |
   |           | MUST be present and indicate which instances were     |
   |           | affected..                                            |
   +-----------+-------------------------------------------------------+

4.1.2.3.  CS:changes XML Element

   This element indicates the key changes that took place.  The child
   element CS:changed-property lists all the properties in all instances
   that changed, with the name attribute on each element indicating
   which iCalendar property changed.  There MUST only be one CD: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.



Daboo                                                           [Page 6]

                   CalDAV Scheduling Change Indicators     February 2009


   For each CD:changed-property element, if any parameters were changed
   on the corresponding properties, then those should be includes as
   child elements CD:changed-parameter, with the name attribute on those
   elements containing the name of the parameter changed.  As with CS:
   changed-proeprties, there MUST only be one CS:changed-parameter
   element for each iCalendar parameter that changed.

4.1.2.4.  CS:recurrences 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.                            |
   |                 |                                                 |
   | CS:recurrenceid | The instance with the specified "RECURRENCE-ID" |
   |                 | value was changed.                              |
   +-----------------+-------------------------------------------------+

   If no child elements were specified, then all instances were 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.

   [RFC2445]  Dawson, F. and Stenerson, D., "Internet Calendaring and
              Scheduling Core Object Specification (iCalendar)",
              RFC 2445, November 1998.




Daboo                                                           [Page 7]

                   CalDAV Scheduling Change Indicators     February 2009


   [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.


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 8]

