RFC 

Network Working Group D.M. Royer 
INTERNET DRAFT INET-Consulting 
<draft-royer-cap-notify-02>  1 September 2003 
Category: Informational  
Expires: 1 March 2004  


iCalendar notification of upcoming VEVENTs, VTODOs, VALARMs or any changes.
draft-royer-cap-notify-02

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 1 March 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 iCalendar objects.

This memo has been updated to include non-CAP notificaitons.

This memo includes a new CAP command types of "REQUEST-NOTIFY", "NOTIFICATION", and "CANCEL-NOTIFY", a new property of "OBSERVER", a new iCalendar 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 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 these iCalendar objects and using them with 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.


1Introduction

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 OBSERVER or supplied mailto: URLs that VALARM TRIGGERs are ready to be processed. Or that something is new or has changed. 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 could 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 an ORGANIZER. 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:mailto:holiday-cal@Royer.com
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

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 ORGANIZER 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 ORGANIZER creates an ID that is unique 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 ORGANIZER.

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
OBSERVER;ALERT="TRIGGER,CHANGED,UPDATES":CUA
END:NOTIFICATION
END:VCALENDAR

If not all "OBSERVER" property values are accepted, then 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-organizer
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-organizer
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", 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-organizer
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

2OBSERVER property

Property Name: OBSERVER

Purpose: The value of the "OBSERVER" property is added to the list of interested observers if permissions 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 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].


3ALERT 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


4REQUEST-NOTIFY METHOD

A CUA makes notification requests to the organizers 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.


5CAN-NOTIFY CAP Capability

A CS may 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.


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
 

A.  Bibliography


[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-11.txt.


Full Copyright Statement

Acknowledgement