Notifications

Notifications are used by the system to inform users of changes, either to calendar data or to the structure of the system, or to inform them of upcoming events, such as a meeting.

There is a proprietary Apple standard for notifications, associated with their sharing specification. This is implemented by bedework. New non-proprietary standards are being developed which will be implemented.

These standards deal almost exclusively with private and group calendaring. We (bedework) are extending them into the public events space.

A side note: system mailer

There has been for some time a system mailer which allows emailing of messages. This is used to inform public events submitters that there events have been accepted or rejected. This will be replaced by using the notification processes described below.

In the meantime this service is configured by

• go to the jmx panel org.bedework.bwengine->service=system and set the MailerClass attribute. To disable mailing it is set to "org.bedework.mail.DummyMailer" which is a class which just discards messages. The class "org.bedework.mail.SimpleMailer" will send an email message.
• go to the jmx panel org.bedework.bwengine->service=Mailer and configure appropriately for your mail service

The notifications process

Notifications get sent currently for the following major reasons:

1. Sharing changes (subscribe, unsubscribe etc)
2. Changes to content in shared collections

The first category of changes largely involves invitations to share or responses.

The second category allows users to see, for example, that an event they share has changed in some way - e.g. the start time changed. Shared events can be used to schedule meetings or social events without the overhead of true iTip scheduling.

Within bedework change notifications are driven by system events. These are JMS messages that log user activity. Change events are processed by the change notifier to determine if anybody needs to be notified of the event.

Notifications collection

Each user of the system has a notifications collection which is used to store all notifications to that user. CalDAV clients and the bedework personal web client, will display the contents of that collection and allow users to dismiss the notifications or act upon them.

Action Items

1. Can't dismiss all notifications
2. Change notifications don't link to anything and don't go away

Notifications for private and group calendaring.

For the standard implementation, a sharee is added to the collection that is shared. When a change takes place that list is examined. If absent, no notifications are sent. If it is present and contains active sharees then each sharee will receive a notification in their notifications collection.

Notifications for public events.

This allows a user to subscribe to an event and then receive notifications when that event changes. This and the following section have a related problem in that the user doesn't want notifications for all events - only those they are subscribed to.

Event Registration system

This is a subsystem which manages the state of events for which people can register. In essence there are a certain number of tickets, some may be reserved by the system and there may be limits on how many a single individual may have. When the event is fully booked there is the provision for a waiting list. The desire is for registered users to receive notifications when changes take place that effect them. These changes include:

• Being allocated tickets after being on waiting list.
• Event cancellations
• Event date/time changes

Users who wish to receive notifications are subscribed to the notification system for emails. The system will then add notifications to their collection when changes take place that effect them. As calendar users they may already be subscribed or they may not wish to receive all notifications. We need to be careful to only enable the appropriate subset of notifications.

Currently the class EventActionBase sends a message to the event registration system when an event changes. This should probably be moved down into the service layer.

Notifications for systems administrators.

In  common with some of the implementations above, the user to be notified will not be subscribed directly to the collection holding the events. The user has a filtered view of the collection and only wants notifications for events that match that filter. The problem is to

• Identify all the aliases pointing to a collection
• Identify the subset that allow the event to be seen

An alternative might be to build a special alias only for notifications. This would typically have a simpler filter - most aliases have filters that involve ownership and categorization whereas the common condition is generally events owned by the group.

The notification engine

Notifications are generated by bedework and stored in notification collections in the users home. These collections are defined by the standards and may be accessed by clients to inform the user of changes or invitations or responses. Some users may wish to have notifications delivered to them by some external process such as email or sms. The notification engine is an outboard service that will deliver the notification via some service then, optionally, remove it from the collection.

The notification engine is part client and part push notification gateway. We'll try to implement parts of the draft push notification protocol as we go along.

There are potentially very many users wishing for some sort of unsolicited notification. To avoid building large tables in the calendar engine, that system will inform the notification engine every time a notification is added to a collection. These may be bundled together when possible. It is up to the notification engine to accept or discard the message. The message is posted to the notification engine web service and is domething like

    {
       "system": "localBedework",

       "token": "abcdef",

                  "hrefs": [ "/principals/users/fred", "/principals/users/jim" ]

    }

Note that the hrefs are principal hrefs. It's up to the notification engine to use standard protocols to locate the notification collection for the principal.

Subscriptions to the notification engine

To receive notifications via the service, users need to subscribe or be subscribed. A subscription has the following information:

• Source - at the moment they all come from the calendar system
• Delivery methods. Email, sms etc. Each element is a structure with information for the method - e.g. email address
• Types - user may want only certain types of notification

Formatting outbound messages

Flow of messages

Most notifications will be handled in a similar manner. When a notification collection is updated a message will be sent to the notification engine informing it which principal was affected. It is up to the notification engine to discover, via CalDAV, what was actually added.

Endpoints:

There are a number of web service endpoints which are called to pass messages between the system components.

• Calendar engine:

• Notification engine: web service to accept messages indicating a principal has received a new notification

• notify web service - based on caldav support. Accepts notification related messages

• CalWS - SOAP service used by event registration system to retrieve events.

• Event registration service: web service to allow calendar engine to indicate events have changed.

The following sections describe the flow of messages when certain actions take place

Sharing:

• User A invites user B

• Notification placed in user B notifications collection

• Notify handler in calendar engine sends message to notify engine indicating user B has notification

• Notify engine does a sync report on the notify collection via CalDAV and gets new notification(s)

• Formats and sends notification.

Event registration - event canceled:

• Public event admin cancels an event - sets the status.

• Message sent to event registration system (ERS) telling it event has changed (href is supplied).

• ERS retrieves the event. Determines status is cancelled.

• ERS retrieves all registrations for the event and builds a message listing the principals.

• ERS sends message to the calendar engine notify web service endpoint

• Calendar engine adds notifications to principals notification collection(s)

• Calendar engine sends message to notification system informing it that principals need to be checked

• Notify engine does sync report(s) and send notification message(s).

Adding a new notification type

A none trivial exercise depending on what needs to be done. At least these steps:

• Define a class or classes: caldav util is the home for many.

• Define or extend a parser: same home.

• Ensure parser is registered with the standard parser class: that is in the static section of those parsers

• In CalSvc add a call to create an instance of the parser - forces registration early on.

• Do the same in BedeworkConnectorInstance in the notification engine

• In the client/appcommon package add any code needed to process the notification for navigation to NotifyResource.