This module is an add-on to the TWiki kernel that supports e-mail notification of changes.

Summary of Contents

bin/mailnotify

The main part of the mailer module is a script, bin/mailnotify. This script is designed to be run from 'cron' (or an equivalent offline job scheduler), and processes the contents of the standard WebNotify 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.

Subscribers are listed WebNotify in "bullet lists" following one of the following formats:

three spaces * [ webname . ] wikiName - SMTP mail address
three spaces * [ webName . ] wikiName
three spaces * SMTP mail address
three spaces * SMTP mail address : topics
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:

   * daisy@flowers.com
   * daisy@flowers.com: Web*
   * DaisyCutter: Petal* (1) WeedKillers (3) Red*Phlox
   * StarTrekFan: * - *Wars - *sInTheirEyes - *shipTroopers

A user may be listed many times in the WebNotify topic. Where a user has several lines in WebNotify 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/mailnotify script.

Note mailnotify ignores permissions in webs. It is entirely possible for a user to get added to a WebNotify 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).

TWiki/Contrib/MailerContrib code library

The second part of the module is a code library that provides the services for other applications to modify WebNotify 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 WebNotify package described below.

bin/remove_obsolete_locks

The old mailnotify script had a side-effect; it would remove obsolete topic locks as it ran. This has not been implemented in mailnotify, as it is not required in the Dakar release of TWiki.

Installation Instructions

This Contrib is pre-installed as part of the TWiki release package, and should only have to be re-installed if an upgrade is required.

• Download the ZIP file from the Plugin web (see below)
• Unzip MailerContrib.zip in your twiki installation directory.
• Run the installer script MailContrib_intaller.pl or alternatively resolve all dependencies manually.
• To make sure the installation was successful, run the bin/mailnotify script from the command line, with no parameters. In this case it will print out what it would have done to STDOUT.

Setting up your cron job

You need to set up a cron (or equivalent) job to run bin/mailnotify.

Usage: bin/mailnotify [-q] [ web1 web2 ... webN ]

-q	Don't print progress information
web1 web2 ... webN	List of webs to process, separated by spaces or commas. Default is to process all legal TWiki webs. Wildcards (*) are supported.

The script can also be used 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; default is 0
webs	Space or comma-separated list of webs to process

Settings

• Name of the perl package
  • Set STUB = TWiki::Contrib::Mailer

Contrib Info

Author:	TWiki:Main/CrawfordCurrie (http://c-dot.co.uk)
Copyright ©:	2004, Wind River Systems
License:	GPL
Change History:
4 March 2005	1.010 Dakar release ready.
12 Oct 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 Oct 2004	1.003 Excluded _ webs from processing, added bin/remove_obsolete_locks for full reverse-compatibility
1 Oct 2004	1.002 PeterThoeny provided additional documentation
27 Sep 2004	1.001 runnable as CGI script, minor bugfixes, removed dependency on DBCacheContrib
8 Sep 2004	1.000 Initial version
Home:	TWiki:Plugins/MailerContrib
Feedback:	TWiki:Plugins/MailerContribDev

Related Topics: TWikiPreferences

-- TWiki:Main/CrawfordCurrie