Calendaring and Scheduling D. Royer Internet-Draft INET-Consulting Expires: March 1, 2004 September 1, 2003 CAP notification of upcoming VEVENTs, VTODOs, VALARMs or any changes. draft-royer-cap-notify-01 Status of this Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http:// www.ietf.org/ietf/1id-abstracts.txt. The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. This Internet-Draft will expire on March 1, 2004. Copyright Notice Copyright (C) The Internet Society (2003). All Rights Reserved. Abstract This memo describes a method used to ask for and receive notifications. These notifications will be the direct result of a stored components and the notifications or changes to components or the store and are represented in iCalendar format. This is an extensions to CAP. This memo includes a new CAP command types of "REQUEST-NOTIFY", "NOTIFICATION", and "CANCEL-NOTIFY", a new property of "OBSERVER", a new component "NOTIFICATION", CAP capabilities of "CAN-NOTIFY", "NOTIFY-UPDATES", and "ALLOW-NOTIFY-BOT". A "REQUEST-NOTIFY" command is a request to add an observer to an component in the "TARGET" calendar. In addition the "REQUEST-NOTIFY" command can alert the CUA of changes to specific components or in the calendar or calendar Royer Expires March 1, 2004 [Page 1] Internet-Draft CAP-Notify September 2003 store. Everything is subject to VCAR restrictions. These are asynchronous notifications must be advertised by the CS and requested by the CUA. This memo discusses how to transport them using CAP. In addition if the CS and CUA support the "NOTIFY-UPDATES" capability, then the CS will send "NOTIFICATION" components to the CUA describing the UIDs or TARGETS that have changed since the currently authenticated CU was last connected allowing for easier synchronization. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. OBSERVER property . . . . . . . . . . . . . . . . . . . . . . 6 3. ALERT Parameter . . . . . . . . . . . . . . . . . . . . . . . 7 4. REQUEST-NOTIFY METHOD . . . . . . . . . . . . . . . . . . . . 8 5. Restriction tables . . . . . . . . . . . . . . . . . . . . . . 8 6. CAN-NOTIFY CAP Capability . . . . . . . . . . . . . . . . . . 8 7. Component, Property and Parameter details . . . . . . . . . . 8 Author's Address . . . . . . . . . . . . . . . . . . . . . . . 9 A. Bibliography . . . . . . . . . . . . . . . . . . . . . . . . . 9 Intellectual Property and Copyright Statements . . . . . . . . 10 Royer Expires March 1, 2004 [Page 2] Internet-Draft CAP-Notify September 2003 1. Introduction iCalendar specifies that a component may include a VALARM component. iTIP describes how to perform scheduling, CAP describes how to store and fetch those components. Notifications as used here are asynchronous messages that inform a registered CUA (the OBSERVER) or supplied mailto: URLs that VALARM TRIGGERs are ready to be processed. Or that something is new or has changed. When CAP was being developed it was decided that notifications would be deferred until a later time. This memo describe notifications and how they are delivered to the observers. These observers may or might not be an ATTENDEE or ORGANIZER. They simply need permissions to become an observer. A CUA-BOT is defined here to mean a CUA that automatically performs operations on behalf of a CU. The CUA-BOT is separate from the CS, however an implementation could provide them in the same application binary program as a CS. A NOTIFY-BOT is a CUA-BOT that performs these notification operations on behalf of a CU. The components would be stored in a CS and the NOTIFY-BOT would have access to the component for the purpose of sending object to the registered observers. A CUA informs a CAL-ADDRESS that it wishes to receive notifications by sending a "REQUEST-NOTIFY" command object to a CS. This request includes the specific TARGET or component UIDs where the CUA wishes to become an OBSERVER. In addition any CUA may be listed as an observer meaning that if the currently authenticated CUA supports notifications they will happen as requested. Here is an example of a request to be notified: BEGIN:VCALENDAR VERSION:2.0 CMD:REQUEST-NOTIFY TARGET:cap://cal.Royer.com/holiday-list BEGIN:NOTIFY UID:uid-of-interested-component 1 UID:uid-of-interested-component 2 OBSERVER;ALERT="TRIGGER":mailto:Doug+ical-notify@Royer.com OBSERVER;ALERT="TRIGGER":mailto:SomeoneElse@example.com OBSERVER;ALERT="TRIGGER,CHANGED,UPDATES":CUA END:NOTIFY END:VCALENDAR Royer Expires March 1, 2004 [Page 3] Internet-Draft CAP-Notify September 2003 If the "UID" property is not supplied, then changes as defined in the "ALERT" parameter value the to the "OBSERVER" property will be reported when anything changes to the supplied "TARGET" property value. Exactly what is done or sent will depend on the "VALARM" property values, if the CU is currently in an active session from a CUA, and as defined in this memo. The "NOTIFICATION" components will be sent at the "VALARM" component "TRIGGER" value times specified in the "VALARM" component to all registered observers for the listed UIDs when the "ALERT" parameter has a value of "TRIGGER" in the "OBSERVER" property. The inclusion of the "TRIGGER" value in the "ALERT" parameter is the means by which the CUA requests the CS to process or send alarms stored on behalf of the CUA. If the "ALERT" parameter value contains "CHANGED", then whenever something changes the CS will attempt to deliver a "NOTIFICATION" component to the named observer. If the "ALERT" parameter value contains "UPDATES" and the CUA has supplied "NOTIFY-UPDATES" in its "GET-CAPABILITY" command reply, and there have been changes to any target or component where the observer is set to "CUA", then the CS will automatically send "NOTIFICATIONS" components to the CUA for all of those previously registered for changes. The "UPDATES" parameter value can only be used when the "OBSERVER" property value is set to "CUA". The reply from the CS is a "NOTIFICATION" component back to the OBSERVER that contains only the REQUEST-NOTIFY, TARGETs, any UIDs and a REQUEST-STATUS back to the CUA. If all "OBSERVER" property values are accepted, then one "NOTIFICATION" component is sent back. The CS creates an ID that is unique to the CS and supplies that ID back to the CUA in the "NOTIFYID" property. The "NOTIFYID" property is not supplied if all observers are rejected by the CS. BEGIN:VCALENDAR VERSION:2.0 TARGET:cap://cal.Royer.com/holiday-list CMD:REQUEST-NOTIFY BEGIN:NOTIFICATION REQUEST-STATUS:2.0 NOTIFYID:unique-id UID:uid-of-interested-component 1 UID:uid-of-interested-component 2 OBSERVER;ALERT="TRIGGER":mailto:Doug+ical-notify@Royer.com OBSERVER;ALERT="TRIGGER":mailto:SomeoneElse@example.com Royer Expires March 1, 2004 [Page 4] Internet-Draft CAP-Notify September 2003 OBSERVER;ALERT="TRIGGER,CHANGED,UPDATES":CUA END:NOTIFICATION END:VCALENDAR If not all "OBSERVER" property values are accepted, then one multiple "NOTIFICATION" components may be sent back in order to specifically determine what failed. Below 'mailto:SomeoneElse@example.com' was not allowed to observe 'UID:uid-of-interested-component 2' and was allowed to observe the other components. BEGIN:VCALENDAR VERSION:2.0 TARGET:cap://cal.Royer.com/holiday-list CMD:REPLY BEGIN:NOTIFICATION REQUEST-STATUS:2.0 NOTIFYID:a-unique-id-set-by-the-cs UID:uid-of-interested-component 1 UID:uid-of-interested-component 2 OBSERVER;ALERT="TRIGGER":mailto:Doug+ical-notify@Royer.com OBSERVER;ALERT="TRIGGER,CHANGED,UPDATES":CUA END:NOTIFICATION BEGIN:NOTIFICATION REQUEST-STATUS:2.0 NOTIFYID:a-unique-id-set-by-the-cs UID:uid-of-interested-component 1 OBSERVER;ALERT="TRIGGER":mailto:SomeoneElse@example.com NOTIFYID:unique-id END:NOTIFICATION BEGIN:NOTIFICATION REQUEST-STATUS:x.y -- permission denied! UID:uid-of-interested-component 2 OBSERVER;ALERT="TRIGGER":mailto:SomeoneElse@example.com END:NOTIFICATION END:VCALENDAR "NOTIFICATIONS" components may be removed or modified with the CAP "DELETE" and "MODIFY" commands. The property "NOTIFYID" parameter value can aid in the identification of "NOTIFICATION" components stored in the CS. When a CS removes a "NOTIFICATION" component and the "OBSERVER" has registered for "CHANGES", then the CS MAY send the observer a "NOTIFICATION" component. The "CMD" value set to "CANCEL-NOTIFY", Royer Expires March 1, 2004 [Page 5] Internet-Draft CAP-Notify September 2003 supplying the "NOTIFYID" property and and an optional "COMMENT" and "UID" properties. No "OBSERVER" properties are supplied if all observers are to be removed. If one or more "OBSERVER" properties are removed, then the removed observers are supplied. BEGIN:VCALENDAR VERSION:2.0 CMD:CANCEL-NOTIFY TARGET:cap://cal.Royer.com/holiday-list NOTIFYID:a-unique-id-set-by-the-cs UID:uid-of-interested-component 2 COMMENT:We no longer provide notification services for non local OBSERVERS. OBSERVER:mailto:SomeoneElse@example.com END:VCALENDAR For observers registered for "TRIGGER" alerts, the "UID" property and "VALARM" "SEQUENCE" property are sent in the "NOTIFICATION" component. The observer knows that it is a "TRIGGER" alert because it has the "SEQUENCE" property from the "VALARM" component. BEGIN:VCALENDAR VERSION:2.0 CMD:NOTIFICATION TARGET:cap://cal.Royer.com/holiday-list UID:uid-of-interested-component 2 SEQUENCE:3 END:VCALENDAR 2. OBSERVER property Property Name: OBSERVER Purpose: The value of the "OBSERVER" property is added to the list of interested observers if VCARs permit. Value Type: TEXT Property Parameters: Non-standard property parameters can be specified on this property. Conformance: The property can be specified in components as specified in this memo. Description: The "OBSERVER" property allows a value type of 'cal-address'. So it may be an mailto, CAP uri or any IANA registered cal-address type or the string "CUA". The "OBSERVER" property value Royer Expires March 1, 2004 [Page 6] Internet-Draft CAP-Notify September 2003 is the destination address for sending any VALARM at TRIGGER time. The "OBSERVER" property value may or might not be the same value as the "ATTENDEE" property value in the component or a contained "VALARM" component. Formal Definition: The property is defined by the following notation: observerprop = "OBSERVER" observer-params ":" observer-list CRLF observer-params = alert-param other-params other-params ; As defined in [CAP]. observer-list = observer-value *( "," observer-value) observer-value = (cal-address / "CUA") cal-address ; As definded in [CAP]. 3. ALERT Parameter Parameter Name: ALERT Purpose: Describes the kinds of alerts requested by the CUA. Value Type: TEXT Conformance: This parameter can be specified in the "OBSERVER" property. Description: Formal Definition: The property is defined by the following notation: ; Each unique ALERT value can only be included once. ; alert-param = "ALERT" "=" 1*( "TRIGGER" / "CHANGED" / "UPDATES" ) Example: The following is an example of this parameter: OBSERVER;ALERT="TRIGGER,CHANGED,UPDATES":CUA Royer Expires March 1, 2004 [Page 7] Internet-Draft CAP-Notify September 2003 4. REQUEST-NOTIFY METHOD A CUA makes notification requests to the observers calendar by sending a CMD:REQUEST-NOTIFY that contains the UID(s) where the notification is requested, and a VALARM component that contains the request action. 5. Restriction tables To be written ... 6. CAN-NOTIFY CAP Capability A CS can support notifications at three levels: (1) It can act as a NOTIFY-BOT. This is done by setting "CAN-NOTIFY" in the "GET-CAPABILITY" reply from the CS. This mode is activated if the CUA supplies "CAN-NOTIFY" in the CUAs "GET-CAPABILITY" reply to the CS. (2) Allowing CUAs to register as a NOTIFY-BOT. This is done by setting the 'ALLOW-NOTIFY-BOT" capability in the "GET-CAPABILITIES" reply form the CS. This mode is activated if the CUA supplies "ALLOW-NOTIFY-BOT" in the CUAs "GET-CAPABILITY" reply to the CS. For a CS that also supports mode (1) the CS ignores "OBSERVER" properties that have a "CUA" property value for the current session. And it ignores all "OBSERVER" properties where the value equals the currently authenticated UPN for the current session. These are ignored because the CUA has registered as the notification handler. (3) Allowing each CUA to act as its own notification handler. This is compatibility mode for a CS or CUAs that do not support notifications. This mode is activated when nether of the above two modes are activated at "GET-CAPABILITY" reply time. Each CUA can only activate one of the above modes. 7. Component, Property and Parameter details TODO Royer Expires March 1, 2004 [Page 8] Internet-Draft CAP-Notify September 2003 Author's Address Doug Royer INET-Consulting.com 1795 W. Broadway #266 Idaho Falls, Idaho 83402 US Phone: 208-520-4044 Fax: 866-594-8574 EMail: Doug@Royer.com URI: http://Royer.com/People/Doug Appendix A. Bibliography [BEEP] Rose, M., "The Block Extensible Exchange Protocol Core", RFC 3080, March 2001 ftp://ftp.isi.edu/in-notes/rfc3080.txt [BEEPTCP] Rose, M., "Mapping the BEEP Core onto TCP", RFC 3081, March 2001 ftp://ftp.isi.edu/in-notes/rfc3081.txt [iCAL] Dawson, F. and Stenerson, D., "Internet Calendaring and Scheduling Core Object Specification (iCalendar)", RFC 2445, November 1998 ftp://ftp.isi.edu/in-notes/rfc2445.txt [iTIP] Silverberg, S., Mansour, S., Dawson, F. and Hopson, R., "iCalendar Transport-Independent Interoperability Protocol (iTIP) Events, BusyTime, To-dos and Journal Entries", RFC 2446, November 1998 ftp://ftp.isi.edu/in-notes/rfc2446.txt [iMIP] Dawson, F., Mansour, S. and Silverberg, "iCalendar Message-Based Interoperability Protocol (iMIP)", RFC 2447, November 1998 ftp://ftp.isi.edu/in-notes/rfc2447.txt [CAP] Royer, D., Babics, G., Hill, P. Mansour, S. "Calendar Access Protocol (CAP)", work in progress, draft-ietf-calsch-cap-12.txt. Royer Expires March 1, 2004 [Page 9] Internet-Draft CAP-Notify September 2003 Intellectual Property Statement The IETF takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on the IETF's procedures with respect to rights in standards-track and standards-related documentation can be found in BCP-11. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementors or users of this specification can be obtained from the IETF Secretariat. The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights which may cover technology that may be required to practice this standard. Please address the information to the IETF Executive Director. Full Copyright Statement Copyright (C) The Internet Society (2003). All Rights Reserved. This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English. The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assignees. This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION Royer Expires March 1, 2004 [Page 10] Internet-Draft CAP-Notify September 2003 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Acknowledgment Funding for the RFC Editor function is currently provided by the Internet Society. Royer Expires March 1, 2004 [Page 11]