Network Working Group C. Daboo Internet-Draft Apple Intended status: Standards Track July 6, 2009 Expires: January 7, 2010 VALARM Extensions for iCalendar draft-daboo-valarm-extensions-00 Status of this Memo This Internet-Draft is submitted to IETF in full conformance with the provisions of BCP 78 and BCP 79. 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 January 7, 2010. Copyright Notice Copyright (c) 2009 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents in effect on the date of publication of this document (http://trustee.ietf.org/license-info). Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Abstract This document defines a set of extensions to the iCalendar VALARM component to enhance use of alarms and improve interoperability between clients and servers. Daboo Expires January 7, 2010 [Page 1] Internet-Draft VALARM Extensions July 2009 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Conventions Used in This Document . . . . . . . . . . . . . . 3 3. Extensible syntax for VALARM . . . . . . . . . . . . . . . . . 3 4. VALARM Unique Identifier . . . . . . . . . . . . . . . . . . . 5 5. VALARM URI Action . . . . . . . . . . . . . . . . . . . . . . 6 6. VALARM Agent Property . . . . . . . . . . . . . . . . . . . . 7 6.1. Alarm Agent Property . . . . . . . . . . . . . . . . . . . 7 6.2. URI Property Parameter . . . . . . . . . . . . . . . . . . 8 7. VALARM Status Property . . . . . . . . . . . . . . . . . . . . 9 7.1. Last Triggered Property . . . . . . . . . . . . . . . . . 10 7.2. Snooze Until Property . . . . . . . . . . . . . . . . . . 11 8. VALARM Included by Reference . . . . . . . . . . . . . . . . . 12 8.1. Unique Identifier Reference Property . . . . . . . . . . . 13 9. Default Alarms in CalDAV . . . . . . . . . . . . . . . . . . . 13 10. Security Considerations . . . . . . . . . . . . . . . . . . . 13 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14 12. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 14 13. References . . . . . . . . . . . . . . . . . . . . . . . . . . 14 13.1. Normative References . . . . . . . . . . . . . . . . . . . 14 13.2. Informative References . . . . . . . . . . . . . . . . . . 14 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 14 Daboo Expires January 7, 2010 [Page 2] Internet-Draft VALARM Extensions July 2009 1. Introduction The iCalendar [I-D.ietf-calsify-rfc2445bis] specification defines a set of components used to describe calendar data. One of those is the "VALARM" component which appears as a sub-component of "VEVENT" and "VTODO" components. The "VALARM" component is used to specify a reminder for an event or to-do. Different alarm actions are possible as are different ways to specify how the alarm is triggered. As iCalendar has become more widely used and as client-server protocols such as CalDAV [RFC4791] have become more popular, several issues with "VALARM" components have arisen. Most of these relate to the need to extend the existing "VALARM" component with new properties and behaviors to allow clients and servers to accomplish specific tasks in an interoperable manner. For example, clients typically need a way to specify that an alarm has been dismissed by a calendar user, or has been "snoozed" by a set amount of time. To date, this has been done through the use of custom "X-" properties specific to each client implementation, leading to poor interoperability. This specification defines a set of extensions to "VALARM" components to cover common requirements for alarms not currently addressed in iCalendar. Each extension is defined in a separate section below. For the most part, each extension can be supported independently of the others, though in some cases one extension will require another. 2. Conventions Used in This Document The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "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. 3. Extensible syntax for VALARM Section 3.6.6 of [I-D.ietf-calsify-rfc2445bis] defines the syntax for "VALARM" components and properties within them. However, as written, it is hard to extend this by adding, e.g., a new property common to all types of alarm. Since many of the extensions defined in this document need to extend the base syntax, an alternative form for the Daboo Expires January 7, 2010 [Page 3] Internet-Draft VALARM Extensions July 2009 base syntax is defined here, with the goal of simplifying specification of the extensions. A "VALARM" calendar component is re-defined by the following notation: alarmcext = "BEGIN" ":" "VALARM" CRLF alarmprop "END" ":" "VALARM" CRLF alarmprop = *( ; the following are REQUIRED, ; but MUST NOT occur more than once action / trigger / ; one set of action properties MUST be ; present and MUST match the action specified ; in the ACTION property actionprops / ; the following is OPTIONAL, ; and MAY occur more than once x-prop / iana-prop ) actionprops = audiopropext / disppropext / emailpropext audiopropext = *( ; 'duration' and 'repeat' are both OPTIONAL, ; and MUST NOT occur more than once each, ; but if one occurs, so MUST the other duration / repeat / ; the following is OPTIONAL, ; but MUST NOT occur more than once attach ) disppropext = *( Daboo Expires January 7, 2010 [Page 4] Internet-Draft VALARM Extensions July 2009 ; the following are REQUIRED, ; but MUST NOT occur more than once description / ; 'duration' and 'repeat' are both OPTIONAL, ; and MUST NOT occur more than once each, ; but if one occurs, so MUST the other duration / repeat ) emailpropext = *( ; the following are all REQUIRED, ; but MUST NOT occur more than once description / summary / ; the following is REQUIRED, ; and MAY occur more than once attendee / ; 'duration' and 'repeat' are both OPTIONAL, ; and MUST NOT occur more than once each, ; but if one occurs, so MUST the other duration / repeat ) 4. VALARM Unique Identifier Several of the other extensions in this specification require identifying a specific instance of a "VALARM" component in an iCalendar stream. To aid that, this extension adds a "UID" property to "VALARM" components to allow a unique identifier to specified. The value of this unique identifier can then be used to refer uniquely to the "VALARM" component. The "UID" property defined here follows the definition in Section 3.8.4.7 of [I-D.ietf-calsify-rfc2445bis]. In particular it MUST be a globally unique identifier. Daboo Expires January 7, 2010 [Page 5] Internet-Draft VALARM Extensions July 2009 The "VALARM" component defined in Section 3 is extended here as: alarmprop /= *( ; the following is OPTIONAL, ; but MUST NOT occur more than once uid ) 5. VALARM URI Action Currently "VALARM" components have actions for audio, display and email. New types of action are of interest, e.g., SMS, instant messaging, etc. Rather then specify separate actions for these, an alternative is to define a "URI" action that allows any URI scheme to be used as an action, where it makes sense. Thus URI schemes for IM [RFC3860], SIP [RFC3261], TEL [RFC3966] etc could be used. This extension defines a new "URI" property value for use with the "ACTION" property in "VALARM" components. A new set of action properties is defined for "VALARM" components based on this new action as defined by the syntax below. actionvalue /= "URI" ; Adds a new action for a "VALARM" actionprop /= uriprop ; Re-defines the "VALARM" component to include ; "uriprop" as a new set of action properties uriprop = *( ; the following are REQUIRED, ; but MUST NOT occur more than once description / uri / ; 'duration' and 'repeat' are both OPTIONAL, ; and MUST NOT occur more than once each, ; but if one occurs, so MUST the other duration / repeat ) Daboo Expires January 7, 2010 [Page 6] Internet-Draft VALARM Extensions July 2009 6. VALARM Agent Property With the advent of a standard client/server protocol for calendaring and scheduling data ([RFC4791]) there is a need to specify which client or server should handle the presentation of an alarm when it is triggered. For example, calendar users want to be able to receive alarms at all times, even when their desktop client might be unavailable. Since the server is "always on", a service running on the server could monitor alarm status and when appropriate trigger those alarms. In addition it may be important for only the server or the client to be set to handle an alarm - and in some cases only specific servers or clients. To address this need, this specification defines an "ALARM-AGENT" iCalendar property that can be added to any "VALARM" component. This property specifies whether a client or server or both should be responsible for processing the alarm when it triggers. In addition, a "URI" property parameter can be added to uniquely identify the client or server that should process the alarm. This is defined by the syntax below. alarmprop /= *( ; the following is OPTIONAL, ; and MAY occur more than once alarm-agent ) 6.1. Alarm Agent Property Property Name: ALARM-AGENT Purpose: This property specifies whether a client, server, both or none gets to process an alarm when it is triggered. Value Type: TEXT Property Parameters: IANA, non-standard, and URI property parameters can be specified on this property. Conformance: This property can be specified within "VALARM" calendar components. Daboo Expires January 7, 2010 [Page 7] Internet-Draft VALARM Extensions July 2009 Description: This property is used to specify who is responsible for processing an alarm when it is triggered. When the value "SERVER" is specified, only a server that has a copy of the event is responsible. When the value "CLIENT" is specified, only a client that has a copy of the event is responsible. When the value "BOTH" is specified, either a client or server is responsible. When the value "NONE" is specified, neither a client nor server is responsible (i.e. the alarm action is never carried out when it triggers). If the "URI" property parameter is specified for "SERVER" or "CLIENT" values, then only the client or server identified by the "URI" value is responsible. Clients or servers that are not responsible for the alarm SHOULD NOT process the alarm action when it is triggered. Format Definition: This property is defined by the following notation: alarm-agent = "ALARM-AGENT" alarmagentparam ":" alarmagentvalue CRLF alarmagentparam = *( ; the following is OPTIONAL, ; but MUST NOT occur more than once (";" uriparam) / ; the following is OPTIONAL, ; and MAY occur more than once (";" other-param) ) alarmagentvalue = "SERVER" / "CLIENT" / "BOTH" / "NONE" / iana-token / x-name Example: The following is an example of this property: ALARM-AGENT:SERVER 6.2. URI Property Parameter Property Name: URI Daboo Expires January 7, 2010 [Page 8] Internet-Draft VALARM Extensions July 2009 Purpose: This property parameter specifies a URI that is related to the property it is applied to. Format Definition: This property is defined by the following notation: uriparam = "URI" "=" DQUOTE uri DQUOTE Description: This property parameter is used to specify a URI that is associated with the property it is applied to. Each property that allows this parameter to be specified MUST indicate what the value of the URI represents. Example: The following is an example of this property: ALARM-AGENT;URI="http://calendar.example.com":SERVER 7. VALARM Status Property There is currently no way for a "VALARM" component to indicate the status of the alarm (e.g., whether it has been triggered or not). With the advent of a standard client/server protocol for calendaring and scheduling data ([RFC4791]) it is quite possible for an event with an alarm to exist on multiple clients in addition to the server. If each of those is responsible for performing the action when an alarm triggers then multiple "alerts" are generated by different devices. In a such a situation a calendar user would like to be able to "dismiss" the alarm on one device and have it dismissed on the others too. In addition, calendar user agents often provide a way for calendar users to "snooze" an alarm (temporarily dismiss it but have it re- scheduled to trigger again a short while later). However, there is no way for a "VALARM" component to indicate that it has been snoozed and for how long. Finally, with recurring events that have alarms, it is important to know when the last alarm in the recurring set was triggered, so that the client can determine whether any and how many past alarms have been missed. To address these needs, this specification adds the following: o a "STATUS" property to "VALARM" components with values to indicate wether an alarm is active, inactive, completed (dismissed) or snoozed. Daboo Expires January 7, 2010 [Page 9] Internet-Draft VALARM Extensions July 2009 o a "LAST-TRIGGERED" property to "VALARM" components to indicate when the alarm was last triggered. o a "SNOOZE-UNTIL" property to "VALARM" components to indicate when to trigger an alarm after it has been "snoozed". This is defined by the syntax below. alarmprop /= *( ; the following are OPTIONAL, ; but MUST NOT occur more than once status / last-triggered / snooze-until ) statvalue /= statvalue-alarm statvalue-alarm = "ACTIVE" ; Indicates alarm is active and ; waiting to be triggered. / "CANCELLED" ; Indicates alarm is inactive ; and won't be triggered. / "COMPLETED" ; Indicates alarm has triggered ; and been dismissed. / "SNOOZED" ; Indicates alarm has triggered ; and been snoozed. ; Status values for a "VALARM" 7.1. Last Triggered Property Property Name: LAST-TRIGGERED Purpose: This property specifies the UTC date and time at which the corresponding alarm was last triggered. Value Type: DATE-TIME Property Parameters: IANA and non-standard property parameters can be specified on this property. Conformance: This property can be specified within "VALARM" calendar components. Daboo Expires January 7, 2010 [Page 10] Internet-Draft VALARM Extensions July 2009 Description: This property is used to specify when an alarm was last triggered. This allows clients to track repeating alarms or alarms on recurring events or to-dos to ensure that the right number of missed alarms can be tracked. Format Definition: This property is defined by the following notation: last-triggered = "LAST-TRIGGERED" lasttrigparam ":" datetime CRLF lasttrigparam = *( ; the following is OPTIONAL, ; and MAY occur more than once (";" other-param) ) Example: The following is an example of this property: LAST-TRIGGERED:20090604T084500Z 7.2. Snooze Until Property Property Name: SNOOZE-UNTIL Purpose: This property specifies the UTC date and time at which the corresponding alarm is to be re-triggered after being "snoozed". Value Type: DATE-TIME Property Parameters: IANA and non-standard property parameters can be specified on this property. Conformance: This property can be specified within "VALARM" calendar components. Description: This property is used to specify when an alarm is expected to be re-triggered following a "snooze" operation by a calendar user. Format Definition: This property is defined by the following notation: Daboo Expires January 7, 2010 [Page 11] Internet-Draft VALARM Extensions July 2009 snooze-until = "SNOOZE-UNTIL" snoozeuntilparam ":" datetime CRLF snoozeuntilparam = *( ; the following is OPTIONAL, ; and MAY occur more than once (";" other-param) ) Example: The following is an example of this property: SNOOZE-UNTIL:20090604T085000Z 8. VALARM Included by Reference In some situations a calendar user might wish to define an alarm to be used on multiple events or to-dos. This would allow a change to one alarm to effect the alarms for multiple events or to-dos without having to modify each "VALARM" component in each event or to-do. One use for this is for setting up a "default" alarm for a calendar user - one that gets applied to all new events or to-dos added to the user's calendar. TODO: need more text on how properties are "inherited" and "overridden". This extension defines a "UID-REFERENCE" property for use with "VALARM" components. The value of this property is the unique identifier ("UID" property value) of another "VALARM" component. The "UID-REFERENCE" property is used in place of normal "VALARM" action properties as defined by the syntax below. alarmprop /= *( ; the following is OPTIONAL, ; but MUST NOT occur more than once uid-ref ) Daboo Expires January 7, 2010 [Page 12] Internet-Draft VALARM Extensions July 2009 8.1. Unique Identifier Reference Property Property Name: UID-REFERENCE Purpose: This property specifies a reference to another component. Value Type: TEXT Property Parameters: Non-standard property parameters can be specified on this property. Conformance: This property can be specified within "VALARM" calendar components. Format Definition: This property is defined by the following notation: uid-ref = "UID-REFERENCE" uidrefparam ":" text CRLF uidrefparam = *(";" other-param) Description: This property is used to specify a reference to an iCalendar "VALARM" component. Its value is equal to the value of the "UID" property in the component being referenced. When present in a "VALARM" component, all the properties from the referenced "VALARM" are applied to the referring component, except for those that have counter-parts in the referring component. For example, a "SUMMARY" property defined in a referenced component can be overridden by a "SUMMARY" in the referring component. Also, per-instance copies of some properties are required, such as "LAST-TRIGGERED" and "SNOOZE-UNTIL". Example: The following is an example of this property: UID-REFERENCE:19960401T080045Z-4000F192713-0052@example.com 9. Default Alarms in CalDAV TODO: specify how default alarms for different types of component and for timed/all-day can be set in WebDAV properties and then referenced in calendar data, and automatically applied by the server to new events and new invites. 10. Security Considerations TODO:talk about importance of stripping VALARMs from incoming iTIP. Daboo Expires January 7, 2010 [Page 13] Internet-Draft VALARM Extensions July 2009 Talk about VALARMs being used to "spam" - particularly nasty if the server handles it. 11. IANA Considerations TODO: tables registering new properties, parameters and values. 12. Acknowledgments This specification came about via discussions at the Calendaring and Scheduling Consortium. 13. References 13.1. Normative References [I-D.ietf-calsify-rfc2445bis] Desruisseaux, B., "Internet Calendaring and Scheduling Core Object Specification (iCalendar)", draft-ietf-calsify-rfc2445bis-10 (work in progress), April 2009. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault, "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791, March 2007. 13.2. Informative References [RFC3261] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, A., Peterson, J., Sparks, R., Handley, M., and E. Schooler, "SIP: Session Initiation Protocol", RFC 3261, June 2002. [RFC3860] Peterson, J., "Common Profile for Instant Messaging (CPIM)", RFC 3860, August 2004. [RFC3966] Schulzrinne, H., "The tel URI for Telephone Numbers", RFC 3966, December 2004. Daboo Expires January 7, 2010 [Page 14] Internet-Draft VALARM Extensions July 2009 Author's Address Cyrus Daboo Apple Inc. 1 Infinite Loop Cupertino, CA 95014 USA Email: cyrus@daboo.name URI: http://www.apple.com/ Daboo Expires January 7, 2010 [Page 15]