E-mail Notification
===================

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.

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 SMPT server, and a correct Administrator Email.

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.

All notification events 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 objects. 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 the status change hook on the attendee:

   attendee.on_status_change(self, old_status, status)

3. The attendee calls the notification method on the storage manager 
   (Does that make sense? The storage manager? Why did I put it there? /lre)
   
   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 who 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 adresses, 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 send 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.


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 send only when somebodys 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 delegee).
However, the current 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
calender gets notified. CPS is set up so that the Owners of calendars are 
subscribed to all calendar events, so Martijn receievs 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
Florents calendar is actually notified, and neither Kit not Martijn gets an 
email.

