<master>

# Notifications Package

## The Idea

The Zawinski's Law:

> Every program attempts to expand until it can read mail. Those programs which cannot so expand are replaced by ones which can.

The OpenACS Corollary to Zawinski's Law:

> Every web-based application attempts to expand until it can send mail. Those applications which cannot so expand are replaced by ones which can.

At some point, your web application - your OpenACS package, that is - needs to send email to your users. The usual way to do this is to:

- add a bunch of `acs_mail_lite::send` calls to your code
- suddenly realize that the users are getting too much email: find a way to batch up the emails using a sweeper proc
- suddenly note that different alerts have different priorities: add user preferences for immediate notifications or batched alerts
- slap your forehead when you note that you've reimplemented bboard notifications.

The goal of the Notifications package is to provide the following functionality:

- a generalized means of creating notification types (e.g. "bboard notifications")
- a generalized means of subscribing to notification types (e.g. "subscribe to OpenACS Design Forum")
- a generalized means for a user to control his notifications: frequency, format (HTML, text), delivery method (email, IM, etc..).
- a generalized and simple means for an application to add to the notification queue for a given notification type (e.g. "notify all interested parties that a new message has been added to the OpenACS Design Forum").

## Use Cases

There are two main actors of the notifications package:

- OpenACS end-users
- OpenACS packages that want to notify users

Success for this package will be gauged by how many packages choose to use it instead of going the `acs_mail_lite::send/iteration` route.

### Web Application End-User

A web application end-user can:

- view all of his notifications, organized by category
- edit frequency and format of notifications
- remove notification requests
- suspend notifications for a while (i.e. vacation)

### Sample Package: Forums

The Forums package will need to use notifications, specifically as follows:

- set up notifications for a user who is subscribed to a forum or thread
- easily add a message to the notification queue for a forum or thread

## Data Types

### Notification Type

A notification type is a category of notifications that fit a certain application. "Forum Notifications" is one example. It is conceivable that one application would have more than one notification type if it performs very different types of notifications.

A notification type may store additional data about the notification itself. Thus, a "notification type" is also characterized by the specific data it must keep track of.

### Notification Request

Given a certain notification type (e.g. "Forum Notificaton"), a notification request is an association of a party, a notification type, and an object for which this notification type applies.

An example would be "Ben Adida requests a Forum Notification on OpenACS Design":

- The Party ID: Ben Adida
- The Notification Type: Forum Notification
- The Object ID: The OpenACS Design Forum

### Notification Preferences

A user or party may request certain preferences on their notification requests. Some of these preferences will be on a per request basis. Others will be on a party-wide basis:

- frequency of notifications
- format of notification (HTML or text)
- destination of notification (which email address, or which IM)

### Notification

The notification is the actual message that goes out and summarizes information that needs to be communicated. A notification is the result of processing all the messages for a particular notification type, and sending them to all the parties who have requested this notification type, using the preferences indicated.

## Under The Hood: OpenACS Constructs

The Notification package declares an initial `notification_request` OpenACS object type. This is the base type for all notification requests. Creating a new notification type involves subtyping `notification_request`. For ease of programming, an additional table `notification_types` is kept which mirrors that `acs_object_types` table for all subtypes of `notification_request`.

Notification messages are queued as individual OpenACS objects. A mapping table of which notification messages have been sent to which users is kept. Whenever the pending list of users for a particular notification is emptied, the notification object and its associated mapping table rows are removed. There is no need to keep a history of these notifications (not now).

The process for delivering a notification is implemented as a service contract in order to enable other means of notification (IM, SMS, snail mail - who knows!). Instead of attempting to make the notifications package too smart, we expect packages to come up with different notification types (i.e. short vs. long) that will fit the type of delivery in question. A long notification sent to SMS is probably not a good idea. But we can't expect the Notification package to be super smart about "summarizing" information down to a smaller message.

Email delivery is implemented using `acs-mail-lite` for reliability.

## Supplemental discussions

There are some additional docs and discussions on the forums in the following threads:

- Notifications tutorial
- How do I use notifications?

© 2002 OpenForce, Inc.