E-mail Notification

Revision: $Id$


CPSSharedCalendar's email notifications uses CPS3s event and subscription system. In short, when a calendar event is modified, a notification event is sent via the event system. This is picked up by the subscription system that looks up which users are interested in getting an email for this event.

1   Quick start

After you have installed CPSSharedCalendar, log in as manager and go to the Root of Workspaces. Click on Notifications management. Select all the checkboxes for Calendar events for the Attendee manager and Owner roles, and Save Changes.

Also make sure that you have a valid mail server set up. Click on "Reconfigure portal" and enter a correct SMTP server, and a correct Administrator Email.

2   Implementation details

The notification events are created by the calendar tool. Currently only notification on the status changes of attendees is implemented, but notification for other event modifications will soon follow.

Every notification event has an object that the event concerns; it is the object that sends the events, so to speak. In CPSSharedCalendar, that object is always the Calendar object. So an event where the status of an attendee is changed will be sent from that attendee's personal or "home" calendar.

This enables people to subscribe to events for other calendars. For example, a secretary would be interested to know that the boss gets invited to meetings; a course manager would be interested to see that people book the class rooms; and so on.

The actual workflow of the notification is as follows:

  1. Somebody changes the participation status of an attendee on an event:

    event.setParticipationStatus(attendee, status)
  2. The event calls sends EventParticipationChangeEvent.

  3. The storage manager is a subscriber, and an event is sent:

    storage_manager.notifyOnStatusChange(event, old_status, status)
  4. The storage manager decides which event to send, and to which calendars to send it, and then sends the event:

    event_tool.notify(event_type, homecal, infos)
  5. The event tool propagates this event to every other tool that has asked to listen to it, including the subscriptions tool.

  6. The subscriptions tool looks up who are interested in this event. This can be specific users, specific email addresses, and most commonly, specific roles (like the one you set up in quick start, above). For the roles, it then looks up every user who has these roles on the object that is sending along with the event (which is some kind of calendar in our case). It then sends an email to all of the users that wanted notification.

3   Event types

The storage manager looks at the old status and the new status to determine which type of event to send when you have a status change. This fine grained split into different status changes makes it possible to select what type of changes you want a mail for. Maybe you only want if for invitations, or only when an accepted event gets moved.

There are at the seven different notification events that are sent: Invite, accept, decline, tentative, delegated, deleted and status change.

Invite is sent only when somebody's status goes from None (not in the meeting at all) to NEEDS-ACTION.

Accept, decline and tentative are sent when somebody that was invited changed his status. That is, when NEEDS-ACTION goes to ACCEPTED, DECLINED or TENTATIVE, respectively.

Delegated is sent when the new status is DELEGATED (no matter what the old status was). This should also be sent to the person to which the event is delegated, but there is no way to convey that information to the system yet.

Deleted is send when the status goes to None. This should only happen when the attendee is completely removed from the attendee-list.

Last is status change, which is the event that is called if none of the other matched.

The events are all sent to the attendee that has his status changed, and to the event organizer (Delegated will in the future also be sent to the delegatee). However, currently the attendee is not notified.

An example: Florent invites Martijn for a meeting. Since Florent is the organizer of the event, both his and Martijn's calendar gets selected for notifications. However, since Florent also is the current user, only Martijn's calendar gets notified. CPS is set up so that the Owners of calendars are subscribed to all calendar events, so Martijn receives an email. Kit has also subscribed to invite notifications for Martijn's calendar, so he gets an email as well.

Martijn accepts the meeting. Again both Martijn's and Florent's calendars get selected for notification, but since Martijn now is the current user only Florent's calendar is actually notified, and neither Kit not Martijn gets an email.