---+ Enhanced notification system for TWiki

This page documents an enhanced notification system for TWiki.

%TOC%

---++ The previous system

The original notification system of TWiki is based on manual
registration of user on a specific topic. Registration is performed by
adding wiki user name on the WebNotify topic of the web to be
monitored. 
Just adding a line like the following example shows suffices to be registered :
<verbatim>
   * Main.JohnSmith
</verbatim>

Periodically, a daemon scans the web for changes on topics since the
last scan and sends an email to registered users summarizing the
modifications.

This system notifies users for changes on any topic of the web. The
whole topic set may represent a too big set for most users. The new
system provides a solution to this problem.

---++ Backward compatibility
#BackwardCompatibility

The new system is fully backward compatible with the previous system.
Users using the previous system should not see any difference after
the switch to the new system. They will still receive notifications
for all topics of the web.

---++ An extended syntax

Using the new syntax of registration in the WebNotify topic, users can
now specify which specific topics they want to monitor. The syntax has
been extended to accept a list of topics just after the wiki name (or
optionnaly after the user email address), as shown by the following
examples :

<verbatim>
   * Main.JohnSmith : FooBar, NextMeeting, FunnyStuff, WebHome
   * Main.BobWhite - bob.white@foo.com : TeamNews
</verbatim>

The topic list follows the user name on the same line. It is separated
from the user name by a colon character (=:=). Topic names are
separated by spaces commas or a mix of them.

Topic names may use wildcards characters to match multiple topics.

The =[NEW]= keyword may also be used in the topic list to be notified
on creation of topic even if its name doesn't match other items of the
topic list.

In the following example, the user will be notified on changes on all
topics whose name begins with "Foo" or ends with "Bar" or is exactly
"FunnyStuff" or any topic that has just been created (whatever its
name is).

<verbatim>
   * Main.JohnSmith : Foo*, *Bar, FunnyStuff, [NEW]
</verbatim>

The topic list is optionnal; by default a notification is sent for
changes on all topics (see [[#BackwardCompatibility][Backward
Compatibility]] section).

---++ A simpler user interface

This enhanced notification system is completed by another new feature
: the *Subscribe* feature.  A =Subscribe= button has been
added to the tool bar of each page (alongside the =edit=, =attach= or
=new= buttons).

This new button, when clicked, automatically registers this topic in
your notification settings for the current web. If you were already
notified for changes on this topic, no modification is made to your
settings, otherwise your settings are updated with this new topic
name.

To unregister for notification on a specific topic, users, as before,
must directly modify their settings in the WebNotify topic.

---++ Limitations and planned features

Clicking the =Subscribe= button while another user is editing the
WebNotify topic produces an error message suggesting to retry
later. This can be resolved by caching the users' requests and
automatically handle cached requests when the topic lock is release.

As with the original notification system, users' settings for the all
Wiki are dispersed on WebNotify topics of each webs. If this is a
problem for users, settings could be centralised in a unique page for
each user for the all Wiki (for example in the =Main.JohnSmith=
personnal page or a =Main.JohnSmithNotifConf= page).

Notification on a topic change could be extended to notification on
changes on this topic and all its child-topics.  Someone monitoring a
topic is certainly also interrested in monitoring topics created as
children of this topic.  This would provide a consistent way of
project monitoring with a unique notification request.

-- Main.NicolasDuboc - 09 Mar 2004

$Id: MailNotifyDoc.txt,v 1.2 2004/05/10 14:00:28 nduboc Exp $