INTERET-DRAFT T. Moran Document: draft-moran-sipping-filter-arch-01.txt S. Addagatla Expires: April 2003 Nokia October 2002 Architecture for Event Notification Filters 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. Abstract This document defines an extendible architecture whereby an event subscriber (client) may specify the rules for SIP event notification from the notifier (server). Specific solution(s) meeting the architecture specification are provided in the annexes. Requirements for event filtering are described in [1]. Table of Contents 1 Introduction....................................................2 2 Conventions used in this document...............................3 3 Definitions.....................................................3 4 Defining Rules..................................................4 4.1 Pre-defined Attributes.....................................4 4.1.1 Current time..........................................4 4.1.2 Package-ID............................................4 4.1.3 Attribute-ID..........................................5 4.1.4 Error.................................................5 Moran, Addagatla Expires - April 2003 [Page 1] INTERNET-DRAFT Event Filtering Architetcure October 2002 4.2 Package Defined Attributes.................................5 4.3 Operators..................................................5 4.3.1 Mathematical Operators................................6 4.3.2 Comparison and Logical Operators......................6 4.3.3 Time-based Logical Operators..........................6 4.3.4 Filter Operators......................................7 4.4 Application Defined Operators..............................7 5 Client Operation................................................7 5.1 Normal.....................................................7 5.2 Abnormal...................................................8 6 Server Operation................................................8 6.1 Normal.....................................................9 6.2 Abnormal...................................................9 7 Security Considerations.........................................9 8 Guidelines for Creating Package Specific Filters...............10 8.1 Package ID................................................10 8.2 Language support..........................................10 8.3 Tranport mechanism........................................10 8.4 Attribute Support.........................................10 8.5 Operators.................................................10 8.6 Client Operation..........................................10 8.7 Server Operation..........................................11 8.8 IANA Considerations.......................................11 9 IANA Considerations............................................11 10 Acknowledgements..............................................11 11 References....................................................11 12 Author's Addresses............................................12 Annex A. Example Presence Filtering Applications.................12 Annex B. XML Schema Implementation (Normative)...................13 1 Introduction SIP event notification is described in [2]. It defines a general framework for subscriptions and notifications for events in SIP systems. It defines the SIP extensions for events, and introduces the concept of event packages, which are concrete applications of the general event framework to a specific group of events. Some event packages have been defined so far, e.g., user presence [3], watcher information [4], and message waiting indications [5]. As the inherent complexity of event packages grows, both the frequency and size of event notifications are bound to increase. In general, the client needs some mechanisms for controlling the frequency and content of event notifications. These mechanisms are expected to be particularly valuable to users of mobile wireless access devices. The characteristics of these devices typically include high latency, low bandwidth, low data processing Moran, Addagatla Expires - April 2003 [Page 2] INTERNET-DRAFT Event Filtering Architetcure October 2002 capabilities, small display, and limited battery power. Such devices can benefit from the ability to filter the amount of information generated at the source of the event notification. However, it is expected that the control mechanisms for event notifications add value for all users irrespective of their network access characteristics. This draft proposes a reusable and extendible architecture whereby an event client (e.g. a presence client) may specify the rules for when a notification should be sent to it and what the contents should contain. Syntactical constructs are identified which include common attributes and operations as well as mechanisms for extending the set of operations. Normal and abnormal operation of the subscriber, notifier, and proxy are defined. Guidelines for specifying package specific filtering (i.e. an instantiation of the architecture) are identified. Finally, an XML implementation of the architecture is provided Annex B for this release. The requirements for this architecture/framework are defined in [1]. 2 Conventions used in this document 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 RFC-2119 [1]. 3 Definitions Event notification filtering - the capability/ functionality for controlling the frequency and content of event notifications. That is, when notifications should be sent and restrictions as to what the conent should be. Filter criteria / filter - a set of rules for event notification filtering; may contain rules for notification triggering and/or limiting notification content. Notification criteria / trigger - that part of the filter criteria for controlling the frequency of the event notification. Content criteria / filter - that part of the filter criteria for specifying and identifying the information delived in the notification. Moran, Addagatla Expires - April 2003 [Page 3] INTERNET-DRAFT Event Filtering Architetcure October 2002 4 Defining Rules The event client (e.g. a presence client) specifies rules in the form of logical expressions wherein the server is informed of the appropriate conditions for notification (triggers) as well as the specific content to be delivered (filters). These rules consist of a defined set of operations applied to pre-defined attributes (see below) and/or attributes as defined in the event package. The evaluation of the rules restricts the frequency and content of the notifications. In other words, the rules specify the when and what criteria for notification. This section identifies the required attributes and operations for specifying event notification rules. Annex A provides example applications where client based filtering could be used. Annex B provides the XML schema implementation of the architecture. 4.1 Pre-defined Attributes In addition to the package-defined attributes, a common set of attributes is needed to trigger when a notification is sent and to filter what is sent. This section defines those attributes needed to define client-based rules for event notification and filtering. Also included is the definition of a common error handling attribute. 4.1.1 Current time Sending notifications based on absolute time or changes to a specific absolute time require the current time attribute. This attribute represents the current time relative to a time zone. Current time is specified as follows: * Year (0-9999) * Month (1-12) * Day of month (1-31) * Hour (hr: 0-23) * Minute (0-59) * Second (0-23) * Millisecond * Time Zone (EST, PST, etc.) Support of this attribute is optional. 4.1.2 Package-ID Moran, Addagatla Expires - April 2003 [Page 4] INTERNET-DRAFT Event Filtering Architetcure October 2002 The Package-ID attribute establishes a reference to the source that defines the application specific events (attributes). Server software utilizes this attribute to identify the application space (scope) for which the rules apply. This is especially useful for servers supporting multiple applications. Support of this attribute is required. 4.1.3 Attribute-ID This attribute acts as a pointer to a package specific attribute. It enables the client to specify what package attribute(s)should be evaluated before triggering the sending of a notification. The contents of this attribute are: * Package Attribute Name * Package Attribute Value * Package Attribute Instance The instance componentis needed for applications wherein multiple occurances of an attribute with the same name exist. Support of this attribute is optional. 4.1.4 Error In the event server does not understand the rule or cannot honor the request, the error attribute contains the server response that includes: * Error Code, * Error String * Error Details * Error Source Support of this attribute is required for the Code, and String parameters. All other parameters are optional. Error codes and strings are relevant to the package or service and not defined here. 4.2 Package Defined Attributes A package-defined attribute is referenced in a rule using the pre- defined attribute, Attribute-ID. Any attribute of any package may be referenced in a rule. Prior to referencing an attribute of a package, the package itself must be referenced as described in section 4.1.2 4.3 Operators Moran, Addagatla Expires - April 2003 [Page 5] INTERNET-DRAFT Event Filtering Architetcure October 2002 The following identifies the operations/constructs used to trigger notification and filter the notification content. The client is not required to specify a trigger and may only specify a filter as described in section 4.3.4. 4.3.1 Mathematical Operators These operators are used to manipulate attribute values relevant to their type as understood in the defining package. * Add - addition * Sub - subtraction * Mul - multiply * Div - divide * Mod - modulo 4.3.2 Comparison and Logical Operators These operators are used to compare attribute values relevant to their type as understood in the defining package. Lt - less than Le - less than or equal to Gt - greater than Ge - greater than or equal to Eq - equal to Ne - not equal to Not - Boolean not And - Boolean and Or - Boolean or Has-changed - this operation yields TRUE whenever the indicated attribute has changed. Has-changed-by - this operation yields TRUE whenever the indicated attribute has at least changed by the amount specified by . In - this operation compares the value of the attribute to members of list. The expression yields TRUE if a match is found, otherwise FALSE. 4.3.3 Time-based Logical Operators Every - this operation yields TRUE whenever period amount of time has lapsed since the subscription was received or since the last notification. Period is specified in hours, minutes, and seconds. Moran, Addagatla Expires - April 2003 [Page 6] INTERNET-DRAFT Event Filtering Architetcure October 2002 If repeat-n is specified, notification is repeated up to that many times unless the subscription is cancelled or the rule is replaced by a subsequent rule. If it is not specified (absent), then a single notification is generated. 4.3.4 Filter Operators Default - if no filter operator is specified or the explicit Default operator is used, then notifications will include those package attributes as defined by the package itself. This may include, for example, all attributes or only those that have changed. All - specifies that all package attribute values be reported when a notification is sent. All Changed - requires the server to report all attributes whose value has changed since the subscription or last notification. Triggering - indicates that the server is to report all attributes whose value change caused the notification rule to trigger. Only - only those attributes identified in ôlistö are to be sent in the notification. None - the server is to send a notification with no attributes. 4.4 Application Defined Operators Applications may extend the above base set of operators. However, the base set of operations should be used whenever possible. 5 Client Operation The normal and abnormal operation of the client (subscriber) is described below. 5.1 Normal The client creates a rule adhering to the above rule architecture. Required in the rule is a reference to the event package (i.e. inclusion of Package-ID) for which the rules apply and at least one triggering or filtering rule. Multiple triggering rules may be specified using the logical operators. If no triggering rules are specified, then the triggering rules as defined in the event package are used. If no, filtering rules are specified, then the filtering rules of the event package apply. Moran, Addagatla Expires - April 2003 [Page 7] INTERNET-DRAFT Event Filtering Architetcure October 2002 If the current_time attribute is specified in a rule, the time is understood to be that at the server. Since the client may not know the time zone at the server, the client includes the time zone parameter to which the time applies. The server will adjust the trigger relative to the difference between its own time zone and that specified by the client. For example, if the time zone of the server is EST and the client requests that notification be sent at 5:00 P.M. CST, then the server will set the trigger for 4:00 P.M. EST. The client (subscriber) may use multiple methods to establish the notification and filtering rule(s) in the server (notifier). However, whatever method is used, the rules for notification must be established either before or during subscription. Otherwise, the default notification rules of the package may override those desired by the client. The normative text of this draft does not specify how the rules are transferred to the server. Certainly, one option is to use the SUBSCRIBE request. This document does describe how the rules are to be specified using XML (See Annex B). A client may modify a rule by issuing a new set of rules to the server (e.g. re-subscribe). All prior rules are removed. That is they do not stick and must be restated if desired. If the initial response from the server does not indicate an error as described in section 4.1.4 or a transport error, then the client considers the rule as activated in the server. For example, if the client receives a 200 OK in response to a SUBSCRIBE request and there is no body or there is no described ERROR in the body of the response, then the client considers the rule as active. 5.2 Abnormal The client considers the rule as inactive if there is a transport error indicating the message was not accepted or was not confirmed (when confirmation is required). The client also considers the rule as inactive when the server responds with an error as described above. The status of a rule (set of rules) as specified by the client, is either active or inactive. No provision for partial activation is specified or required. Recovery mechanisms are beyond the scope of this draft. 6 Server Operation Moran, Addagatla Expires - April 2003 [Page 8] INTERNET-DRAFT Event Filtering Architetcure October 2002 The normal and abnormal operation of the server (notifier) is described below. 6.1 Normal When the server receives a rule specification it must associate the rule with the subscription or service instance. The rule must also be interpreted and a decision made as to whether the server will support the request in full or reject it. If supported, the server responds to the client as per the requirements of the transport (e.g. 200 OK). If no response is required, then no explicit response indicating activation of the rule is needed. 6.2 Abnormal If a server does not or cannot support a rule, then it must explicitly reject it. This is done by sending a response to the client which indicates the failure to accept the rule and why. Reasons may include errors in syntax, parameter values not supported, filtering not supported, etc. The more information provided by the server, the better able the client is to correct the problem and reissue an acceptable request. For example, if the rule specified an ôEveryö parameter value of 15 seconds, but the server only supported a granularity of minutes, then an error indication such as ôEvery value < 1 minuteö would enable the client to either use the server default rules or modify the request to 1 minute. The method for explicitly rejecting the rules is not within the scope of this document. However, as an example, the sever might send a 4XX response to a SUBSCRIBE request. The body of the response would contain the error indication as described in section 4.1.4. 7 Security Considerations The security considerations of the Subscribe method itself and the parent package (e.g. presence), apply here. Of special consideration is the integrity of the Subscribe content, namely the rules themselves. Tampering with the rules by an interceptor could result in undesirable results such as no notifications or too many. The later is of special concern since it can contribute to a denial of service for other subscribers. That is, a request to be notified every minute if the status changes could be changed to notify every second regardless of status changes. Abnormal charges to a mobile subscriber is another concern. Moran, Addagatla Expires - April 2003 [Page 9] INTERNET-DRAFT Event Filtering Architetcure October 2002 8 Guidelines for Creating Package Specific Filters This section describes the steps (descriptions) needed to provide a filter specification relevant to a given package (application). Generally, the filter specification should follow the outline of this document but with specific details as to the implementation needed for the given package. This includes support for operations, semantics of operations, error reporting, element value constraints, etc., etc. 8.1 Package ID The specification MUST identify the package (packages) to which the rules are applicable. 8.2 Language support The specification MUST identify what language is to be used to describe the rules. For example, XML schema as defined herein. 8.3 Tranport mechanism The specificaion MUST identify the means of transporting the rules to the server. For example, as part of a SIP SUBSCRIBRE message. 8.4 Attribute Support The specifiction SHOULD identify what attributes are supported for use in rules. This includes triggering as well as content limiting and predefined attributes as well as package attributes. Any additional semantics of the attributes as related to filtering should be described. 8.5 Operators The specification SHOULD identify what operators are relevant and their specific usage. For example, what does equality mean when comparing attribute X to some value. What, if any, are the value limitations. This includes triggering operations as well as filtering constructs. If there are extenstions to the architeture, they MUST be defined. It is recommended that examples be provided. 8.6 Client Operation Moran, Addagatla Expires - April 2003 [Page 10] INTERNET-DRAFT Event Filtering Architetcure October 2002 Normal and abnormal client operation MUST be described. Of particular importance is behavior in the event the server returns an error. 8.7 Server Operation Normal and abnormal server operation MUST be described. Of particular importance is behavior in the event the server does not recognize the content type, the content type is malformed, or the rules, while well formed, can not be supported. Error definitions MUST be provided. 8.8 IANA Considerations Filtering applications (packages) may want to identify specific content types relevant to filtering within the application domain. 9 IANA Considerations A new application type is required. The type registered with IANA is: application/eventfilter+XML. NOTE! IANA approval has not been requested. A specific type needs to be agreed upon and submitted. This is merely a placehodler. 10 Acknowledgements The authors would like to thank Eva-Maria Leppanen, Hisham Khartabil, Mikko Lonnfors, Jose Costa Requena, Aki Niemi, and Pekka Pessi for their valuable input. 11 References [1] Moran, T., "Requirements for Event Notification Filters", draft- moran-sipping-filter-reqs-01.txt, October 2002 [2] Roach, A., "SIP-Specific Event Notification", Internet Draft, November 2001, Work in progress [3] Rosenberg, J., et al, "SIP Extensions for Presence", Internet Draft, September 2001, Work in progress [4] Rosenberg, J., et al, "A SIP Event Sub.Package for Watcher Information", Internet Draft, July 2001, Work in progress [5] Mahy, R., Slain, I., "SIP Event Package for Message Waiting Indication", internet Draft, July 2001, Work in progress [6] RFC 2119 Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997 Moran, Addagatla Expires - April 2003 [Page 11] INTERNET-DRAFT Event Filtering Architetcure October 2002 [7] Moran, T., et. al., "Event Notification Filters", draft-moran- sipping-filter-00.txt, November, 2001 [8] XML 1.0: W3C Recommendation, "http://www.w3.org/TR/2000/REC-xml- 20001006" [9] SOAP version 1.2: W3C Working drafts from "http://www.w3.org/2002/ws/" 12 Author's Addresses Tim Moran Nokia Inc. 6000 Connection Drive Irving, Texas 75039 Tel: Sreenivas Addagatla Nokia Inc. 6000 Connection Drive Irving, Texas 75039 Tel: Annex A. Example Presence Filtering Applications Location based services for applications such as fleet management, driving directions, and tracking an E911 caller is one area wherein simple notification based on state change may be inadequate. These types of services will warrant notification based on changes such as the presentities location or simply periodic. Specifying a default rule in the event package is difficult (if not impossible) since each of these applications has different quality of service needs. Too frequent (too costly) or too few notifications may be sent. Too much or too little information may be sent as required by the user and/or the service. Group messaging is yet another application wherein the default rules may prove insufficient. A participant may not wish to know every single user that has joined a large conference. Instead, a periodic indication of how many may suffice. Other participants may only want to know when the primary participants have joined. Participants of a small chat session may wish to know all users in the session the moment they join. Moran, Addagatla Expires - April 2003 [Page 12] INTERNET-DRAFT Event Filtering Architetcure October 2002 The following are a few concrete examples where the subscriber and/or service is best equipped to define the rules for notification: This set of examples should match with Annex C. * A Conference leader only wants to be notified when a certain number of attendees (defined as a quorum) have subscribed (or registered) for the 9:00 a.m. group conference. * A Subscriber only wants to be notified when the presentityÆs location is Dallas or FortWorth. The notification should include the vehicle license, driver name, and city. * A Basic location tracking service requires notification when the presentities cell id changes. The notification should include the cell id. * An E911/Premium Location Service requires notification when the geo-location changes more than 25 meters. The geographical location and confidence factor are required. * A Push Data Service requires notification whenever the presentities GPRS state (attached/detached) changes. The GPRS state, contact address, and home/roam status are required in the notification. * The Economical Wireless Presence Service requires notification no more than every 15 minutes if the state of a buddy has changed. * The Premium Wireless Presence Service requires notification within 5 seconds if the state of a buddy has changed. Annex B. XML Schema Implementation (Normative) The following XML schema definitions are to be used when specifying filtering rules for packages with XML content. XML Schema Definition for SIP Event Filtering. Copyright 2002. Nokia. All rights reserved. Moran, Addagatla Expires - April 2003 [Page 13] INTERNET-DRAFT Event Filtering Architetcure October 2002 Moran, Addagatla Expires - April 2003 [Page 14] INTERNET-DRAFT Event Filtering Architetcure October 2002 Moran, Addagatla Expires - April 2003 [Page 15] INTERNET-DRAFT Event Filtering Architetcure October 2002 Moran, Addagatla Expires - April 2003 [Page 16] INTERNET-DRAFT Event Filtering Architetcure October 2002 Moran, Addagatla Expires - April 2003 [Page 17] INTERNET-DRAFT Event Filtering Architetcure October 2002 Moran, Addagatla Expires - April 2003 [Page 18]