ProPeler
Home
Console
Upload
information
Create File
Create Folder
About
Tools
:
/
opt
/
cpanel-ccs
/
doc
/
Extensions
/
Filename :
caldav-privatecomments.txt
back
Copy
Calendar Server Extension C. Daboo Apple August 14, 2008 Private Attendee Comments in CalDAV Scheduling Abstract This document defines an extension to CalDAV Scheduling that enables Attendees to communicate private comments back to an Organizer, and for the Organizer to see each Attendees' comments. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2 2. Conventions Used in This Document . . . . . . . . . . . . . . 2 3. New behavior . . . . . . . . . . . . . . . . . . . . . . . . . 2 3.1. Attendee . . . . . . . . . . . . . . . . . . . . . . . . . 3 3.2. Organizer . . . . . . . . . . . . . . . . . . . . . . . . 3 4. New features . . . . . . . . . . . . . . . . . . . . . . . . . 5 4.1. iCalendar Changes . . . . . . . . . . . . . . . . . . . . 5 4.1.1. Changes to VEVENT Component . . . . . . . . . . . . . 5 4.1.2. Changes to VTODO Component . . . . . . . . . . . . . . 5 4.1.3. Changes to VJOURNAL Component . . . . . . . . . . . . 6 4.1.4. Private Comment Property . . . . . . . . . . . . . . . 6 4.1.5. Attendee Comment Property . . . . . . . . . . . . . . 7 4.1.6. Date-time Stamp Property Parameter . . . . . . . . . . 8 4.1.7. Attendee Reference Property Parameter . . . . . . . . 9 4.2. CalDAV Changes . . . . . . . . . . . . . . . . . . . . . . 9 4.2.1. OPTIONS Request . . . . . . . . . . . . . . . . . . . 9 4.2.1.1. Example: Using OPTIONS for the Discovery of Private Attendee Comments Support . . . . . . . . 10 4.2.2. Handling clients that do not preserve X- properties . 10 4.2.3. New pre-conditions for PUT . . . . . . . . . . . . . . 10 5. Security Considerations . . . . . . . . . . . . . . . . . . . 10 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 7. Normative References . . . . . . . . . . . . . . . . . . . . . 11 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 11 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 11 Daboo [Page 1] CalDAV Private Attendee Comments August 2008 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. It is often the case that an Attendee of an event wants to communicate information back to an Organizer when they respond to a meeting invitation. Sometimes this is to tell the Organizer the reason why an invite was declined, sometimes to add addition information to an acceptance. Typically these communications are expected to be private as they may contain comments about other Attendees. This specification defines new iCalendar properties and parameters that are used by clients to pass private comments between Attendees and Organizers of events being scheduling via CalDAV scheduling. It also defines an extension to CalDAV scheduling that defines how a server automatically processes the comments to ensure they are communicated properly between the Attendee and Organizer. 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. The prefix X-CALENDARSERVER- is used for all iCalendar properties and parameters defined in this extension. 3. New behavior Daboo [Page 2] CalDAV Private Attendee Comments August 2008 3.1. Attendee When an Attendee wants to send a private comment to an Organizer, the Attendee's calendar user agent adds or updates an "X-CALENDARSERVER- PRIVATE-COMMENT" property in each calendar component of a scheduling object resource to which the comment applies. The value of the comment is the actual message the Attendee is sending. The addition or update of any "X-CALENDARSERVER-PRIVATE-COMMENT" property causes the server to send a scheduling message to the Organizer as an iTIP "REPLY", and that MUST include the "X-CALENDARSERVER-PRIVATE-COMMENT" properties in addition to the normal properties sent as part of that scheduling message. 3.2. Organizer When a scheduling message from an Attendee is processed by the server, the server will check for the presence of a "X-CALENDARSERVER-PRIVATE-COMMENT" property in each component of the scheduling message and compare this with the scheduling object resource corresponding to the scheduling message currently stored on a live calendar belonging to the Organizer. For each component in the scheduling message, the server will identify the corresponding component in the scheduling object resource (possibly creating a new overridden component instance if needed) and do the following: +---------+---------------------------------------------------------+ | State | Description | +---------+---------------------------------------------------------+ | State 1 | Does the scheduling message contain a | | | "X-CALENDARSERVER-PRIVATE-COMMENT" property | | | | | State 2 | Does the scheduling object resource contain a | | | "X-CALENDARSERVER-ATTENDEE-COMMENT" property with an | | | "X-CALENDARSERVER-ATTENDEE-REF" parameter value that | | | matches the "ATTENDEE" value in the scheduling message | +---------+---------------------------------------------------------+ Daboo [Page 3] CalDAV Private Attendee Comments August 2008 +---------+---------+------------------------------------+ | State 1 | State 2 | Server Action | +---------+---------+------------------------------------+ | No | No | No additional processing required. | | | | | | No | Yes | Note 1. | | | | | | Yes | No | Note 2. | | | | | | Yes | Yes | Note 3. | +---------+---------+------------------------------------+ Note 1: The server MUST update the "X-CALENDARSERVER-DTSTAMP" parameter value on the "X-CALENDARSERVER-ATTENDEE-COMMENT" property, and it MUST set the value of that property to an empty string. It MUST remove all property parameters other than "X-CALENDARSERVER-DTSTAMP" and "X-CALENDARSERVER-ATTENDEE-REF". Note 2: The server MUST create an "X-CALENDARSERVER-ATTENDEE- COMMENT" and MUST set the "X-CALENDARSERVER-DTSTAMP" and "X-CALENDARSERVER-ATTENDEE-REF" parameter values, and MUST set the value of the new property to the value of the "X-CALENDARSERVER- PRIVATE-COMMENT" property. Other parameter values on the "X-CALENDARSERVER-PRIVATE-COMMENT" property MAY be copied to the "X-CALENDARSERVER-ATTENDEE-COMMENT" property if supported. Note 3: The server MUST update the "X-CALENDARSERVER-DTSTAMP" parameter value on the "X-CALENDARSERVER-ATTENDEE-COMMENT" property, and MUST set the value of the new property to the value of the "X-CALENDARSERVER-PRIVATE-COMMENT" property. It MUST remove all property parameters other than "X-CALENDARSERVER- DTSTAMP" and "X-CALENDARSERVER-ATTENDEE-REF", and other parameter values on the "X-CALENDARSERVER-PRIVATE-COMMENT" property MAY be copied to the "X-CALENDARSERVER-ATTENDEE-COMMENT" property if supported. When creating or updating the "X-CALENDARSERVER-DTSTAMP" property parameter value, the server MUST set it to the date-time UTC value when the processing of the scheduling message took place. When creating the "X-CALENDARSERVER-ATTENDEE-REF" property parameter value, the server MUST set it to the "ATTENDEE" property value in the scheduling message being processed. As the scheduling message is an iTIP "REPLY" only one "ATTENDEE" property will be present in each component, and the value corresponds to the Attendee sending the reply. Servers MUST remove an "X-CALENDARSERVER-ATTENDEE-COMMENT" property Daboo [Page 4] CalDAV Private Attendee Comments August 2008 if the corresponding "ATTENDEE" property is removed by the Organizer. Servers MUST NOT include "X-CALENDARSERVER-ATTENDEE-COMMENT" properties in scheduling messages sent to Attendees triggered by changes to an Organizer's scheduling object resource. Clients SHOULD ensure that "X-CALENDARSERVER-ATTENDEE-COMMENT" properties are not included in any iCalendar data "exported" to other calendar systems or sent as scheduling messages by the client. 4. New features 4.1. iCalendar Changes This specification introduces a new iCalendar properties "X-CALENDARSERVER-PRIVATE-COMMENT" and "X-CALENDARSERVER-ATTENDEE- COMMENT" for use in iCalendar components. 4.1.1. Changes to VEVENT Component The definition of the properties allowed in a "VEVENT" component is extended as follows: eventprop /= ; 'privatecomment' is optional, ; but MUST NOT occur more than once privatecomment / ; 'attendeecomment' is optional, ; and MAY occur more than once attendeecomment 4.1.2. Changes to VTODO Component The definition of the properties allowed in a "VTODO" component is extended as follows: Daboo [Page 5] CalDAV Private Attendee Comments August 2008 todoprop /= ; 'privatecomment' is optional, ; but MUST NOT occur more than once privatecomment / ; 'attendeecomment' is optional, ; and MAY occur more than once attendeecomment 4.1.3. Changes to VJOURNAL Component The definition of the properties allowed in a "VJOURNAL" component is extended as follows: jourprop /= ; 'privatecomment' is optional, ; but MUST NOT occur more than once privatecomment / ; 'attendeecomment' is optional, ; and MAY occur more than once attendeecomment 4.1.4. Private Comment Property Property Name: X-CALENDARSERVER-PRIVATE-COMMENT Purpose: A private comment that an Attendee adds to their copy of an event and that gets communicated to the Organizer by the server. Value Type: TEXT Property Parameters: IANA, non-standard, alternate text representation and language property parameters can be specified on this property. Conformance: This property can be specified once in "VEVENT", "VTODO", and "VJOURNAL" calendar components. Daboo [Page 6] CalDAV Private Attendee Comments August 2008 Description: This property can be added by an Attendee to their copy of a calendar component in a scheduling object resource. See Section 3.1. Format Definition: This property is defined by the following notation: privatecomment = "X-CALENDARSERVER-PRIVATE-COMMENT" privatecommentparam ":" text CRLF privatecommentparam = *( ; the following are OPTIONAL, ; but MUST NOT occur more than once (";" altrepparam) / (";" languageparam) / ; the following is OPTIONAL, ; and MAY occur more than once (";" other-param) ) Example: X-CALENDARSERVER-PRIVATE-COMMENT:Sorry I cannot attend the mee ting at the specified time. I am free one hour later though. 4.1.5. Attendee Comment Property Property Name: X-CALENDARSERVER-ATTENDEE-COMMENT Purpose: A private Attendee comment from an Attendee to the Organizer, as recorded by the server. Value Type: TEXT Property Parameters: IANA, non-standard, alternate text representation, language, timestamp and attendee property parameters can be specified on this property. Conformance: This property can be specified multiple times in "VEVENT", "VTODO", and "VJOURNAL" calendar components. However, it MUST only occur once in each component with the same "X-CALENDARSERVER-ATTENDEE-REF" parameter value. Daboo [Page 7] CalDAV Private Attendee Comments August 2008 Description: This property is added or updated by the server as a result of receiving a scheduling message from an Attendee. See Section 3.2. Format Definition: This property is defined by the following notation: attendeecomment = "X-CALENDARSERVER-ATTENDEE-COMMENT" attendeecommentparam ":" text CRLF attendeecommentparam = *( ; the following are REQUIRED, ; but MUST occur only once (";" dtstampparam) / (";" attendeerefparam) / ; the following are OPTIONAL, ; but MUST NOT occur more than once (";" altrepparam) / (";" languageparam) / ; the following is OPTIONAL, ; and MAY occur more than once (";" other-param) ) Example: X-CALENDARSERVER-ATTENDEE-COMMENT;X-CALENDARSERVER-DTSTAMP=20080814T 114816Z;X-CALENDARSERVER-ATTENDEE-REF="mailto:cyrus@example.com":So rry I cannot attend the meeting at the specified time. I am free on e hour later though. 4.1.6. Date-time Stamp Property Parameter Parameter Name: X-CALENDARSERVER-DTSTAMP Purpose: Indicates when an iCalendar property was updated by the server. Format Definition: This property parameter is defined by the following notation: dtstampparam = "X-CALENDARSERVER-DTSTAMP" "=" date-time ; MUST be a date-time in UTC Daboo [Page 8] CalDAV Private Attendee Comments August 2008 Description: This parameter indicates when specific iCalendar properties were added or changed as the result of the server automatically updating a scheduling object resource. Example: X-CALENDARSERVER-ATTENDEE-COMMENT;X-CALENDARSERVER-DTSTAMP=20080814T 114816Z;X-CALENDARSERVER-ATTENDEE-REF="mailto:cyrus@example.com":So rry I cannot attend the meeting at the specified time. I am free on e hour later though. 4.1.7. Attendee Reference Property Parameter Parameter Name: X-CALENDARSERVER-ATTENDEE-REF Purpose: Relates an iCalendar property to a particular "ATTENDEE" property in the same calendar component. Format Definition: This property parameter is defined by the following notation: attendeerefparam = "X-CALENDARSERVER-ATTENDEE-REF" "=" DQUOTE cal-address DQUOTE Description: This parameter relates a particular property to a specific "ATTENDEE" property in the same calendar component. It is used to tie Attendee comments back to the actual Attendee who made them. Example: X-CALENDARSERVER-ATTENDEE-COMMENT;X-CALENDARSERVER-DTSTAMP=20080814T 114816Z;X-CALENDARSERVER-ATTENDEE-REF="mailto:cyrus@example.com":So rry I cannot attend the meeting at the specified time. I am free on e hour later though. 4.2. CalDAV Changes 4.2.1. OPTIONS Request A server supporting the features described in this document MUST include "calendarserver-private-comments" as a field in the DAV response header from an OPTIONS request on all calendar resources. A value of "calendarserver-private-comments" in the DAV response header MUST indicate that the server supports all MUST level requirements specified in this document. Daboo [Page 9] CalDAV Private Attendee Comments August 2008 4.2.1.1. Example: Using OPTIONS for the Discovery of Private Attendee Comments Support >> Request << OPTIONS /home/cyrus/calendars/ HTTP/1.1 Host: cal.example.com >> Response << HTTP/1.1 200 OK Allow: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE Allow: PROPFIND, PROPPATCH, LOCK, UNLOCK, REPORT, ACL DAV: 1, 2, access-control, calendar-access DAV: calendarserver-private-comments Date: Sat, 11 Nov 2006 09:32:12 GMT Content-Length: 0 In this example, the OPTIONS method returns the value "calendarserver-private-comments" in the DAV response header to indicate that the collection "/home/cyrus/calendars/" supports the behavior defined in this specification. 4.2.2. Handling clients that do not preserve X- properties TODO: 4.2.3. New pre-conditions for PUT The following pre-conditions for a PUT request against a calendar resource are defined: (CS:valid-attendee-comment-change):Only the server is allowed to the value and parameters on an "X-CALENDARSERVER-ATTENDEE-COMMENT" property. If these pre-conditions are violated the server MUST return a DAV: error response with the appropriate XML element indicating the pre- condition being violated in the response to the PUT request. 5. Security Considerations TODO: Daboo [Page 10] CalDAV Private Attendee Comments August 2008 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., Desruisseaux, B., and L. Dusseault, "CalDAV Scheduling Extensions to WebDAV", draft-desruisseaux-caldav-sched-04 (work in progress), November 2007. [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. [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. 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 11]