A replacement for the core 'mailnotify' functionality. This module brings a new level of flexibility and ease of use to notifications.

%TOC%

---+ Summary of Contents
---++ <code>bin/mailnotifier</code>
The main part of the mailer module is a script, =bin/mailnotifier=. This script is designed to be run from 'cron' (or an equivalent offline job scheduler), and processes the contents of the standard %NOTIFYTOPIC% topic. As well as providing the usual notification service, it also provides per-topic notification services. The script may be run from the command line, a cron job, or from the browser.

The "new" format of <nop>%NOTIFYTOPIC% is a natural extension of the existing format. In the old format, subscribers are listed in "bullet lists" following one of the following formats:

_three spaces_ * [ _webname_ . ] _wikiName_ - _SMTP mail address_ %BR%
_three spaces_ * [ _webName_ . ] _wikiName_

The second format uses the home topic of the user to recover their mail address. This format is extended to accept the following syntaxes:

_three spaces_ * _SMTP mail address_ %BR%
_three spaces_ * _SMTP mail address_ : _topics_ %BR%
_three spaces_ * [ _webname_ . ] _wikiName_ : _topics_

where _topics_ is a space-separated list of topic names.
	* Specify topics without a _Web._ prefix
	* Topics must exist in this web.
	* Topics may be specified using * wildcards
	* Each topic may optionally be followed by an integer in parentheses, indicating the depth of the tree of children below that topic. Changes in all these children will be detected and reported along with changes to the topic itself. _Note_ This uses the TWiki "Topic parent" feature.
	* Each topic may optionally be preceded by a '+' or '-' sign. The '+' sign means "subscribe to this topic" (the same as not putting anything). The '-' sign means "don't send notifications regarding this topic". This allows users to elect to filter out changes to certain topics (and their children, to an arbitrary depth). Topic filters ('-') take precedence over topic includes ('+').

For example:
<verbatim>
	* daisy@flowers.com
	* daisy@flowers.com: Web*
	* DaisyCutter: Petal* (1) WeedKillers (3) Red*Phlox
	 * StarTrekFan: * - *Wars - *sInTheirEyes - *shipTroopers
</verbatim>
A user may be listed many times in the <nop>%NOTIFYTOPIC% topic. Where a user has several lines in <nop>%NOTIFYTOPIC% that all match the same topic, they will only be notified of changes to that topic _once_.

If a _TWiki group_ is listed for notification, the group will be recursively expanded to the email addresses of all members.

In the future it is intended that individual users will be able to control the frequency with which they are notified of topic changes, by changing a schedule specification in their home topic. However at present, the notification schedule is controlled by the frequency of activation of the =cron= job that runs the =bin/mailnotifier= script.

%RED% __Note__ the =mailnotifier= ignores permissions in webs. It is entirely possible for a user to get added to a <nop>%NOTIFYTOPIC% topic in a web, when they are not authorised to view the topics in that web. This could result in them having limited access to sensitive information (the topic summaries). %ENDCOLOR%

---++ <code>TWiki/Contrib/MailerContrib</code> code library
The second part of the module is a code library that provides the services for other applications to modify <nop>%NOTIFYTOPIC% through a clean, well documented interface. This allows (for example) plugin developers to add a "Register me for notification" button to their pages. The main interface is the =Web<nop>Notify= package described below.

---++ <code>bin/remove_obsolete_locks</code>
The old =mailnotify= script had a side-effect; it would remove obsolete topic locks as it ran. This has not been implemented in =mailnotifier=. Instead, a separate side script is provided in this module that performs this function, called =bin/remove_obsolete_locks. For full compatibility with =mailnotify= this script should be run (from =bin=) on the same schedule as =mailnotifier=.

---+ Detailed Documentation
The =bin/mailnotifier= is used from the command line as follows:

<code>Usage: bin/mailnotifier [-q] [-m] [ <i>web1 web2 ... webN</i> ]</code>
| =-q= | Don't print progress information |
| =-m= | Send mail. Default behaviour is to print out plain text of mails that would be sent to STDOUT |
| <code><i>web1 web2 ... webN</i></code> | List of webs to process, separated by spaces or commas. Default is to process all legal TWiki webs. Wildcards (*) are supported. |

from the browser the following CGI parameters are supported:

| =verbose= | set to 0 to get the same effect as -q |
| =sendmail= | Set to 1 to actually send mail |
| =webs= | Space or comma-separated list of webs to process |

<table bgcolor="lightyellow"><tr><td>
%RED% The following POD documentation is provided for the use of developers only. %ENDCOLOR%%BR%Everyone else can just ignore it.

The main class is =TWiki::Contrib::MailContrib::WebNotify=, which allows you to load a notify topic and manipulate the entries. The other classes support this main class. =TWiki::Contrib::Mailer= is the implementation of =bin/mailnotifier=.

---
---++ package TWiki::Contrib::MailerContrib::WebNotify
Object that represents the contents of a %NOTIFYTOPIC% topic in a TWiki web

---+++ sub new($web)
Create a new object by parsing the content of the webnotify topic in the
given web. This is the normal way to load a %NOTIFYTOPIC% topic. If the
topic does not exist, it will create an empty object.

---+++ sub writeWebNotify()
Write the object to the %NOTIFYTOPIC% topic it was read from.
If there is a problem writing the topic (e.g. it is locked),
the method will return an error message. If everything is ok
it will return undef.

---+++ sub getSubscriber($name, $noAdd)
| =$name= | Name of subscriber (wikiname with no web or email address) |
| =$noAdd= | If false or undef, a new subscriber will be created for this name |
Get a subscriber from the list of subscribers, and return a reference
to the Subscriber object. If $noAdd is true, and the subscriber is not
found, undef will be returned. Otherwise a new Subscriber object will
be added if necessary.

---+++ sub getSubscribers()
Get a list of all subscriber names (unsorted)

---+++ sub subscribe($name, $topics, $depth)
| =$name= | Name of subscriber (wikiname with no web or email address) |
| =$topics= | wildcard expression giving topics to subscribe to |
| =$depth= | Child depth to scan (default 0) |
Add a subscription, adding the subscriber if necessary.

---+++ sub unsubscribe($name, $topics, $depth)
| =$name= | Name of subscriber (wikiname with no web or email address) |
| =$topics= | wildcard expression giving topics to subscribe to |
| =$depth= | Child depth to scan (default 0) |
Add an unsubscription, adding the subscriber if necessary. An unsubscription
is a specific request to ignore notifications for a topic for this
particular subscriber.

---+++ sub toString() -> string
Return a string representation of this object, in %NOTIFYTOPIC% format.

---+++ sub processChange($change, $db, $changeSet, $seenSet)
| =$change= | ref of a TWiki::Contrib::Mailer::Change |
| =$db= | TWiki::Contrib::MailerContrib::UpData database of parent references |
| =$changeSet= | ref of a hash mapping emails to sets of changes |
| =$seenSet= | ref of a hash recording indices of topics already seen |
Find all subscribers that are interested in the given change, and
add their email expansions to the changeset with pointers to the
change. Only the most recent change listed in the .changes file is
retained. This method does _not_ change this object.

---+++ sub isEmpty() -> boolean
Return true if there are no subscribers

---
---++ package TWiki::Contrib::MailerContrib::Subscriber
Object that represents a subscriber to notification. A subscriber is
a name (which may be a wikiName or an email address) and a list of
subscriptions which describe the topis subscribed to, and
unsubscriptions representing topics they are specifically not
interested in. The subscriber
name may also be a group, so it may expand to many email addresses.

---+++ sub new($name)
| =$name= | Wikiname, with no web, or email address, of user targeted for notification |
Create a new user.

---+++ sub getEmailAddresses() -> list
Get a list of email addresses for the user(s) represented by this
subscription

---+++ sub subscribe($subs)
| =$subs= | Subscription object |
Add a new subscription to this subscriber object.
The subscription will always be added, even if there is
a wildcard overlap with an existing subscription.

---+++ sub unsubscribe($subs)
| =$subs= | Subscription object |
Add a new unsubscription to this subscriber object.
The unsubscription will always be added, even if there is
a wildcard overlap with an existing subscription or unsubscription.

An unsubscription is a statement of the subscribers desire _not_
to be notified of changes to this topic.

---+++ sub isSubscribedTo($topic) -> boolean
| =$topic= | Topic object we are checking |
| =$db= | TWiki::Contrib::MailerContrib::UpData database of parents |
Check if we have a subscription to the given topic.

---+++ sub isUnsubscribedFrom($topic) -> boolean
| =$topic= | Topic object we are checking |
| =$db= | TWiki::Contrib::MailerContrib::UpData database of parents |
Check if we have an unsubscription from the given topic.

---+++ sub toString() -> string
Return a string representation of this object, in Web<nop>Notify format.

---
---++ package TWiki::Contrib::MailerContrib::Subscription
Object that represents a single subscription of a user to
notification on a page. A subscription is expressed as a page
spec (which may contain wildcards) and a depth of children of
matching pages that the user is subscribed to.

---+++ sub new($pages, $childDepth)
| =$pages= | Wildcarded expression matching subscribed pages |
| =$childDepth= | Depth of children of $topic to notify changes for. Defaults to 0 |
Create a new subscription.

---+++ sub toString() -> string
Return a string representation of this object, in Web<nop>Notify format.

---+++ sub matches($topic, $db, $depth) -> boolean
| =$topic= | Topic object we are checking |
| =$db= | TWiki::Contrib::MailerContrib::UpData database of parent names |
| =$depth= | If non-zero, check if the parent of the given topic matches as well. undef = 0. |
Check if we match this topic. Recurses up the parenthood tree seeing if
this is a child of a parent that matches within the depth range.

---
---++ package TWiki::Contrib::MailerContrib::Change
Object that represents a change to a topic.

---+++ sub new($web)
| =$web= | Web name |
| =$topic= | Topic name |
| =$author= | String author of change |
| =$time= | String time of change |
| =$rev= | String revision identifier |
| =$summary= | String summary of the change |
Construct a new change object.

---+++ sub expandHTML($html) -> string
| =$html= | Template to expand keys within |
Expand an HTML template using the values in this change. The following
keys are expanded: %<nop>TOPICNAME%, %<nop>AUTHOR%, %<nop>TIME%,
%<nop>REVISION%, %<nop>TEXTHEAD%.

Returns the expanded template.

---+++ sub expandPlain() -> string
Generate a plaintext version of this change.

---++ package TWiki::Contrib::MailerContrib::UpData

Object that lazy-scans topics to extract
parent relationships.

---+++ sub new($web)
| =$web= | Web we are building parent relationships for |
Constructor for a web; initially empty, will lazy-load as topics
are referenced.

---+++ sub getParent($topic) -> string
Get the name of the parent topic of the given topic

SMELL: *Huge* assumption about topic files containing meta-data!! This
should really do a Search, but there is no published API.

---++ package TWiki::Contrib::Mailer

Package of support for extended Web<nop>Notify notification, supporting per-topic notification and notification of changes to children.

Also supported is a simple API that can be used to change the Web<nop>Notify topic from other code.

---+++ sub mailNotify($sendmail)
| $sendmail | If true, will send mails. If false, will print to STDOUT |

Process the Web<nop>Notify topics in each web and generate and issue
notification mails. Designed to be invoked from the command line; should
only be called by =mailnotify= scripts.


</table>

---+ Settings
	* Name of the perl package
		* Set STUB = TWiki::Contrib::Mailer

---+ Installation Instructions

	* Download the ZIP file from the Plugin web (see below)
	* Unzip ==%TOPIC%.zip== in your twiki installation directory. Content:
	| *File:* | *Description:* |
		| ==lib/TWiki/Contrib/MailerContrib/WebNotify.pm== |  |
	| ==lib/TWiki/Contrib/MailerContrib/Subscriber.pm== |  |
	| ==lib/TWiki/Contrib/MailerContrib/Subscription.pm== |  |
	| ==lib/TWiki/Contrib/MailerContrib/Change.pm== |  |
	| ==lib/TWiki/Contrib/MailerContrib/UpData.pm== |  |
	| ==lib/TWiki/Contrib/MailerContrib/build.pl== |  |
	| ==lib/TWiki/Contrib/Mailer.pm== |  |
	| ==data/TWiki/MailerContrib.txt== |  |
	| ==bin/mailnotifier== |  |
	| ==bin/remove_obsolete_locks== |  |
	| ==MailerContrib_installer.pl== |  |

	* Run the installer script =MailContrib_intaller.pl= or alternatively resolve all dependencies manually.
	* To make sure the installation was successful, run the
	=bin/mailnotifier= script from the command
	line, with no parameters. In this case it will print out what it
	would have done to STDOUT.
	* Set up cron (or equivalent) jobs to run =mailnotifier= and =remove_obsolete_locks=.
	 * Manually modify your %TWIKIWEB%.WebChangesAlert topic: Replace the part between the STARTINCLUDE and the STOPINCLUDE with the following help text:
<blockquote>
<form action="">
<textarea name="rawtext" disabled="disabled" rows="10" cols="78" style="width: 99%">
<nop>__Format:__ TWiki handles entries in bullet list (<nop>=&amp;lt;space&amp;gt;&amp;lt;space&amp;gt;&amp;lt;space&amp;gt;*=) format containing the %<nop>TWIKIWEB%.WikiName of a user; a !<nop>WikiName with e-mail address; an e-mail address only; or a [<nop>[%<nop>MAINWEB%.TWikiGroups][TWikiGroup]]. Each of these may be followed by a colon and a comma separated list of topics, indicating what to subscribe to. Examples with explanation:
<nop>
<nop>	* <nop>=%<nop>MAINWEB%.FredBloggs								--&amp;gt;= send to e-mail address specified in user's home page
<nop>	* <nop>=not.user@work.com							 --&amp;gt;= send to user not registered in TWiki
<nop>	* <nop>=%<nop>MAINWEB%.EngineeringGroup						--&amp;gt;= send to all members of a group
<nop>	* <nop>=%<nop>MAINWEB%.FredBloggs - !<nop>secondary@home.com	--&amp;gt;= send to an alternative e-mail address
<nop>	* <nop>=%<nop>MAINWEB%.FredBloggs: !<nop>InterestingStuff, !<nop>MeetingMinutes*, !<nop>IssueTracker (2)= %<nop>BR% <nop>=--&amp;gt;= get notified of changes to specific topics only. Wildcards * may be used. The integer in parenthesis indicates the depth of the tree of children below that topic; changes in all these children will be detected and reported along with changes to the topic itself. Only children based on the topic parent feature are considered.
</textarea>
</form>
</blockquote

---+ Contrib Info

|  Author: | TWiki:Main/CrawfordCurrie (http://c-dot.co.uk) |
|  Copyright &copy;: | 2004, Wind River Systems |
|  License: | GPL |
|  Dependencies: | None |
|  Version: | 1.004 |
|  Change History: | <!-- versions below in reverse order -->&nbsp; |
| 12 October 2004 | 1.004 Added support for anti-subscriptions. Doc fixes from TWiki:Main.PeterThoeny. Bug fixes to permissions code. Back-off and retry if the mailer can't be reached (should really be in Net::sendEmail) |
| 6 October 2004 | 1.003 Excluded _ webs from processing, added =bin/remove_obsolete_locks= for full reverse-compatibility |
| 1 October 2004 | 1.002 Peter<nop>Thoeny provided additional documentation |
|  27 September 2004 | 1.001 runnable as CGI script, minor bugfixes, removed dependency on DB<nop>CacheContrib |
|  8 September 2004 | 1.000 Initial version |
|  Home: | TWiki:Plugins/%TOPIC% |
|  Feedback: | TWiki:Plugins/%TOPIC%Dev |

__Related Topics:__ %TWIKIWEB%.TWikiPreferences

-- TWiki:Main/CrawfordCurrie - 12:25:00 12 October 2004
<!-- Do _not_ attempt to edit this topic; it is auto-generated. Please add comments/questions/remarks to the Dev topic instead. -->
