[Docs] [txt|pdf|xml|html] [Tracker] [Email] [Nits]

Versions: 00 01 03 04 05

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]


Html markup produced by rfcmarkup 1.129c, available from https://tools.ietf.org/tools/rfcmarkup/