Peler

: / opt / cpanel-ccs / doc / Extensions /
Filename : caldav-schedulingchanges.xml
back
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE rfc SYSTEM 'rfc2629.dtd' [
<!ENTITY rfc2119 PUBLIC '' 'bibxml/reference.RFC.2119.xml'>
<!ENTITY rfc2445 PUBLIC '' 'bibxml/reference.RFC.2445.xml'>
<!ENTITY rfc2446 PUBLIC '' 'bibxml/reference.RFC.2446.xml'>
<!ENTITY rfc4791 PUBLIC '' 'bibxml/reference.RFC.4791.xml'>
<!ENTITY rfc4918 PUBLIC '' 'bibxml/reference.RFC.4918.xml'>
<!ENTITY I-D.desruisseaux-caldav-sched PUBLIC '' 'bibxml3/reference.I-D.desruisseaux-caldav-sched.xml'>
]> 
<?rfc toc="yes"?>
<?rfc tocdepth="4"?>
<?rfc strict="yes"?>
<?rfc comments="yes"?>
<?rfc inline="yes"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes"?>
<?rfc compact="yes"?>
<?rfc subcompact="no"?>
<?rfc private="Calendar Server Extension"?>
<rfc ipr="none" docName='caldav-schedulingchanges-03'>
    <front>
        <title abbrev="CalDAV Scheduling Change Indicators">Change Indicators for Processed CalDAV Scheduling Messages</title> 
        <author initials="C." surname="Daboo" fullname="Cyrus Daboo">
            <organization abbrev="Apple">
                Apple Inc.
            </organization>
            <address>
                <postal>
                    <street>1 Infinite Loop</street>
                    <city>Cupertino</city>
                    <region>CA</region>
                    <code>95014</code> 
                    <country>USA</country>
                </postal>
                <email>cyrus@daboo.name</email>
                <uri>http://www.apple.com/</uri>
            </address>
        </author>
        <date/>
        <abstract>
            <t>
                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.
            </t>
        </abstract>
    </front>
    <middle>
        <section title='Introduction'>
            <t>
                Internet calendaring and scheduling standards are defined by <xref target="RFC2445">iCalendar</xref> and <xref target="RFC2446">iTIP</xref>. The <xref target="RFC4791">CalDAV Access</xref> standard defines a way to access calendar data stored on a server, and the <xref target="I-D.desruisseaux-caldav-sched">CalDAV Scheduling</xref> draft defines how scheduling occurs between users of a CalDAV server.
            </t>
            <t>
                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.
            </t>
            <t>
                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.
            </t>
        </section>
        <section title='Conventions Used in This Document'>
            <t>
                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 <xref target='RFC2119' />. 
            </t>
            <t>
                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. 
            </t>
            <t>
                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. 
            </t>
        </section>
        
        <!--
        <section title="Open Issues">
            <t>
                <list style="numbers">
                    <t>
                        None right now.
                    </t>
                </list>
            </t>
        </section>
        -->
        
        <section title="New behavior">
            <t>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 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.</t>
        </section>
        <section title='New features'>
            <section title="CalDAV Changes">
                <section title="Change Indicator WebDAV Property">
                <t>
<?rfc compact="no" ?>
                    <list style="hanging">
                        <t hangText="Name:">schedule-changes</t>
                        <t hangText="Namespace:">http://calendarserver.org/ns/</t>
                        <t hangText="Purpose:">Indicates what changed when a scheduling message was automatically processed by a server.</t>
                        <t hangText="Protected:">This property MUST be protected and SHOULD NOT be returned by a PROPFIND allprop request (as defined in Section 14.2 of <xref target="RFC4918"/>).</t>
                        <t hangText="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.</t>
                        <t hangText="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.</t>
                        <t hangText="Definition:">
                            <figure>
                                <artwork><![CDATA[
    <!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 -->

                   ]]></artwork>
                            </figure>
                        </t>
                        <t hangText="Example:">
                           This example indicates that a new calendar component was created.
                            <figure>
                                <artwork><![CDATA[
<CS:schedule-changes
     xmlns:CS="http://calendarserver.org/ns/">
  <CS:dtstamp>20080818T223423Z</CS:dtstamp>
  <CS:action>
    <CS:create/>
  </CS:action>
</CS:schedule-changes>
                   ]]></artwork>
                            </figure>
                        </t>
                        <t hangText="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.
                            <figure>
                                <artwork><![CDATA[
<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>
                   ]]></artwork>
                            </figure>
                        </t>
                        <t hangText="Example:">
                          This example indicates that two recurrence instances were cancelled from a recurring component.
                            <figure>
                                <artwork><![CDATA[
<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>
                   ]]></artwork>
                            </figure>
                        </t>
                        <t hangText="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.
                            <figure>
                                <artwork><![CDATA[
<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>
                   ]]></artwork>
                            </figure>
                        </t>
                    </list>
<?rfc compact="yes" ?>
                </t>
                </section>
                <section title="CS:schedule-changes XML element">
                  <t>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.</t>
                  <section title="CS:dtstamp XML Element">
                    <t>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.</t>
                  </section>
                  <section title="CS:action XML Element">
                    <t>This element indicates the nature of the changes that took place:</t>
                    <texttable>
                        <ttcol>Child Element</ttcol>
                        <ttcol>Description</ttcol>
                        
                        <c>CS:create</c>
                        <c>A new calendar object was created in the default calendar of the recipient.</c>
                        
                        <c>&nbsp;</c>
                        <c>&nbsp;</c>

                        <c>CS:update</c>
                        <c>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.</c>
                        
                        <c>&nbsp;</c>
                        <c>&nbsp;</c>
                        
                        <c>CS:cancel</c>
                        <c>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.</c>
                        
                        <c>&nbsp;</c>
                        <c>&nbsp;</c>
                        
                        <c>CS:reply</c>
                        <c>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.</c>
                    </texttable>
                  </section>
                  <section title="CS:recurrence XML Element">
                    <t>This element indicates which instances were affected by a change:</t>
                    <texttable>
                        <ttcol>Child Element</ttcol>
                        <ttcol>Description</ttcol>
                        
                        <c>CS:master</c>
                        <c>The "master" component defining the recurrence pattern was changed, or a non-recurring component was changed.</c>
                        
                        <c>&nbsp;</c>
                        <c>&nbsp;</c>

                        <c>CS:recurrenceid</c>
                        <c>The instance with the specified "RECURRENCE-ID" value was changed.</c>
                        
                        <c>&nbsp;</c>
                        <c>&nbsp;</c>

                        <c>CS:changes</c>
                        <c>Detailed changes - see next section. This element is not present when processing a "CANCEL".</c>
                    </texttable>
                  </section>
                  <section title="CS:changes XML Element">
                    <t>This element indicates the key changes that took place.</t>
                    <texttable>
                        <ttcol>Child Element</ttcol>
                        <ttcol>Description</ttcol>
                        
                        <c>CS:changed-property</c>
                        <c>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.</c>
                    </texttable>
                  </section>
                </section>
            </section>
        </section>

        <section title='Security Considerations'>
            <t>TODO:</t>
        </section>
        <section title='IANA Considerations'>
            <t>
                This document does not require any actions on the part of IANA.
            </t>
        </section>
    </middle>
    <back>
        <references title='Normative References'>
            &rfc2119;
            &rfc2445;
            &rfc2446;
            &rfc4791;
            &rfc4918;
            &I-D.desruisseaux-caldav-sched;
        </references>
<!--
<references title='Informative References'>
</references>
-->
        <section title='Acknowledgments'>
            <t>
                This specification is the result of discussions between the Apple calendar server and client teams.
            </t>
        </section>
        <section title='Change History'>
          <t>Changes in -03
            <list style='numbers'>
              <t>Re-worked XML schema to allow for per-instance changes to be indicated.</t>
            </list>
          </t>
          <t>Changes in -02
            <list style='numbers'>
              <t>CS:changes element changed to use CS:changed-property child elements for more detailed information.</t>
            </list>
          </t>
        </section>
    </back>
</rfc>