Difference: MailerContrib (r6 vs. r5)

Mailer Contrib MailerContrib

Allows users to "subscribe" to regularly scheduled e-mails containing either:

  • A report on changes to all topics that have changed within a particular TWiki web.
  • A report on changes to a specific topic or set of topics the user can define flexibly.
  • The entire content of a specific topic or set of topics. This is referred to as "news mode."
  • The companion plugin (TWiki:Plugins.SubscribePlugin SubscribePlugin ) lets you trivially add a "Subscribe to changes" button to topics
WARNING: TWiki-4 only. If you want to use this extension with an earlier version of TWiki, please use revision 17 of the zip.
WARNING: TWiki-4 only. If you want to use this extension with an earlier version of TWiki, please use revision 17 of the zip.

tools/mailnotify

tools/mailnotify

The central component of MailerContrib is a script, tools/mailnotify, that generates and sends out the emails based on analysis of

  1. users' subcriptions listed in the WebNotify topic in each web, and
  2. changes within the respective webs.

This script is designed to be run from cron (or an equivalent off-line job scheduler), or from the command-line.

The script collates the changes emails so that each subscriber only receives one changes notification for all changes in all webs in the TWiki. Furthermore, users can elect to receive just summaries of changes, or the entire content of topics that have changed.

Each web can optionally contain a topic called WebNotify.

Users subscribe to email notifications using their WikiName or an alternative email address, and can specify the webs/topics they wish to track, WWhole groups of users can also be subscribed for notification.

The general format of a subscription is:

three spaces * subscriber [ : topics ]

Where subscriber can be a WikiName, an E-mail address, or a group name. If subscriber contains any characters that are not legal in an email address, then it must be enclosed in 'single' or "double" quotes.

topics is an optional space-separated list of topics:

  • ... without a Web. prefix
  • ...that exist in this web.

Users may further customize the specific content they will receive using the following controls:

  • You can use * in a topic name, where it is treated as a wildcard character. A * will match zero or more other characters - so, for example, Fred* will match all topic names starting with Fred, *Fred will match all topic names ending with Fred, and * will match all topic names.
  • Each topic may optionally be preceded by a '+' or '-' sign. The '+' sign means "subscribe to this topic". The '-' sign means "unsubscribe" or "don't send notifications regarding this particular topic". This allows users to elect to filter out certain topics. Topic filters ('-') take precedence over topic includes ('+') i.e. if you unsubscribe from a topic it will cancel out any subscriptions to that topic.
  • 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 immediately followed by an exclamation mark ! or a question mark ? with no intervening spaces, indicating that the topic (and children if there is a tree depth specifier as well) should be mailed out as complete topics instead of change summaries. ! causes the topic to be mailed every time even if there have been no changes, and ? will mail the topic only if there have been changes to it. This only makes sense for subscriptions, and is intended for mailshotting regular newletters.

For example: Subscribe Daisy to all changes to topics in this web.

   * daisy.cutter@flowers.com

Subscribe Daisy to all changes to topics that start with Web.

   * daisy.cutter@flowers.com : Web*

Subscribe Daisy to changes to topics starting with Petal, and their immediate children, WeedKillers and children to a depth of 3, and all topics that match start with Pretty and end with Flowers e.g. PrettyPinkFlowers

   * DaisyCutter: Petal* (1) WeedKillers (3) Pretty*Flowers

Subscribe StarTrekFan to changes to all topics that start with Star except those that end in Wars, sInTheirEyes or shipTroopers.

   * StarTrekFan: Star* - *Wars - *sInTheirEyes - *shipTroopers

Subscribe Daisy to the full content of NewsLetter whenever it has changed

   * daisy@flowers.com: NewsLetter?

Subscribe buttercup to NewsLetter and its immediate children, even if it hasn't changed.

   * buttercup@flowers.com: NewsLetter! (1)

Subscribe GardenGroup (which includes Petunia) to all changed topics under AllnewsLetters to a depth of 3. Then unsubscribe Petunia from the ManureNewsLetter, which she would normally get as a member of GardenGroup?:

   * GardenGroup: AllNewsLetters? (3)
   * petunia@flowers.com: - ManureNewsLetter

Subscribe IT:admins (a non-TWiki group defined by an alternate user mapping) to all changes to Web* topics.

   * 'IT:admins' : Web*

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 about changes that topic once (though they will still receive individual mails for news topics).

If a group is listed for notification, the group will be recursively expanded to the e-mail addresses of all members.

__ALERT! Warning: Because an email address is not linked to a user name, there is no way for TWiki to check access controls for email addresses. A user identified by an email address will only be sent change notifications if the topic they are asubscribed to is readable by guest users. You can limit what email addresses can be used in WebNotify, or even block use of emails altogther, using the {MailerContrib}{EmailFilterIn} setting in =configure.

TIP Tip: List names in alphabetical order to make it easier to find the names.

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 mailnotify script.

Note that when using the "news mode" ! or ? specifiers the entire topic text is mailed out as HTML. The newsletter template is used to generate the content in this mail, using whatever skin is selected in the topic being mailed.

In addition, the %STARTPUBLISH% and %STOPPUBLISH% markers used by TWiki:Plugins.PublishContrib to delimit the text to be published are respected in news mode.

TWiki/Contrib/MailerContrib code library

TWiki/Contrib/MailerContrib code library

The second part of the module is a code library that provides the services for other applications to modify the subscription topics through a clean, well documented API. This allows (for example) plugin developers to add (for example) a "Register me for this newsletter" button to their pages. Developers should refer to the POD documentation for the WebNotify class as their starting point.

Installation Instructions

Installation Instructions

You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server where TWiki is running.

Like many other TWiki extensions, this module is shipped with a fully automatic installer script written using the BuildContrib.

  • If you have TWiki 4.2 or later, you can install from the configure interface (Go to Plugins->Find More Extensions)
  • If you have any problems, then you can still install manually from the command-line:
    1. Download one of the .zip or .tgz archives
    2. Unpack the archive in the root directory of your TWiki installation.
    3. Run the installer script ( perl <module>_installer )
    4. Run configure and enable the module, if it is a plugin.
    5. Repeat for any missing dependencies.
  • If you are still having problems, then instead of running the installer script:
    1. Make sure that the file permissions allow the webserver user to access all files.
    2. Check in any installed files that have existing ,v files in your existing install (take care not to lock the files when you check in)
    3. Manually edit LocalSite.cfg to set any configuration variables.
  • To make sure the installation was successful, run the mailnotifyscript from the command line, with no parameters. In this case it will print out what it would have done to STDOUT. STDOUT.

Additional settings

  • You can change the regular expression that matches email addresses in WebNotify using the {MailerContrib}{EmailFilterIn} setting in =configure setting in configure. This allows you to limit the domains to which emails can be sent, or even block email addresses altogether.

Setting up your cron job(s)

Setting up your cron job(s)

You need to set up a cron (or equivalent) job to run the tools/mailnotify perl script.

The script is used as follows: perl -I bin mailnotify [-q] [-news] [ web1 web2 ... webN ]

bin path to the TWiki bin directory, so that the script can find the rest of TWiki.
-q Don't print progress information
-news Run in news mode (process NewsNotify instead of WebNotify)
web1 web2 ... webN List of webs to process, separated by spaces or commas. The default is to process all webs. Wildcards (*) are supported.

For example, assuming TWiki was installed at /usr/local/twiki, this cron entry:

0 0 * * * cd /usr/local/twiki && perl -I bin tools/mailnotify -q Public Private

will generate change notifications for the Public and Private webs every night at midnight. (Google for crontab for more information on what all the 0 0 * * * fields mean)

0 0 * * * cd /usr/local/twiki && perl -I bin tools/mailnotify -q -Sandbox

will generate change notifications for all webs, except the Sandbox web.

0 0 * * 0 cd /usr/local/twiki && perl -I bin tools/mailnotify -news

will generate newsletters from all webs every week on midnight Saturday.

Developer Notes

Developer Notes

The changes mails sent to users are based on a TWiki template called mailnotify. This template must contain the following definitions.

HTML:before Section of a HTML mail before the changes
HTML:middle Repeated in a HTML mail for each change
HTML:after Section of a HTML mail after the changes
PLAIN:before Section of a plain text mail before the changes
PLAIN:middle Repeated in a plain text mail for each changes
PLAIN:after Section of a plain text mail after the changes
MailNotifyBody All the above are embedded in this. %HTML_TEXT% expands to the HTML obtained by expanding the HTML:* templates, and %PLAIN_TEXT% from the PLAIN:* templates.

The default template sends multipart mails containing both HTML and plaintext versions. You can easily provide a custom version of this template using a local skin.

Newsletters are sent after formatting using the standard view template, using whatever skin is selected in the topic being mailed.

Contrib Info

Contrib Info

Another great TWiki extension from the WikiRing - working together to improve your wiki experience!

Many thanks to the following sponsors for supporting this work:

Author: TWiki:Main/CrawfordCurrie (http://c-dot.co.uk)
Copyright ©: 2004, Wind River Systems; 2006, http://WikiRing.com
License: GPL
Version: 16078 (22 Jan 2008) 16071 (21 Dec 2007)
Change History:  
2 Nov 21 Dec 2007 Bugs:Item4818: added quotes to support non-alphabetic and other wierd group names Bugs:Item4887: corrected minor rendering error Bugs:Item4917: removed dependence on symbolic web names TWikibug:Item5155: added missing TopicContext?.pm
9 Sep 2 Nov 2007 Bugs:Item4326 workaround for possible error in WebNotify API in old releases, Should not affect most users. TWikibug:Item4818: added quotes to support non-alphabetic and other wierd group names TWikibug:Item4887: corrected minor rendering error TWikibug:Item4917: removed dependence on symbolic web names
6 9 Sep 2007 Bugs:Item4488 doc tweaks TWikibug:Item4326 workaround for possible error in WebNotify API in old releases, Should not affect most users.
14550 6 Sep 2007 Bugs:Item4461 - 'Changed' link now points to most recent changes, not the entire history TWikibug:Item4488 doc tweaks
22 14550 Jun 2007 Bugs:Item4284 - added access control checks and email filter TWikibug:Item4461 - 'Changed' link now points to most recent changes, not the entire history
21 May 22 Jun 2007 Bugs:Item3969 - 8bit email fix (TWikibug:Item4284TWiki:Main.WillNorris - added access control checks and email filter )
13623 21 May 2007 Bugs:Item4014 no changes was resetting the notify time to 0. Thanks to TWikibug:Item3969TWiki:Main.JeffCrawford - 8bit email fix ( for nailing this down. TWiki:Main.WillNorris)
12496 13623 Item3415 TWikibug:Item4014 mailnotify did not send notifications no changes was resetting the notify time to intranet users 0. Thanks because of wrong call to findUser. TWiki:Main.JeffCrawford for nailing this down.
11672 12496 Added newsletter support, after much harassment from TWikibug:Item3415TWiki:Main.LynnwoodBrown: mailnotify did not send notifications to intranet users because of wrong call to findUser.
11534 11672 Item2153 Added newsletter support, after much harassment from Clarified docs. TWiki:Main.LynnwoodBrownItem2698 Improved error reporting.
8808 11534 Item1654 TWikibug:Item2153 mailnotify must enter : Clarified docs. the command_line context TWikibug:Item2698: Improved error reporting.
8625 8808 Item1508 TWikibug:Item1654 Making : mailnotify must enter the dashes in command_line context the separatator clearer
8606 8625 Item1508 TWikibug:Item1508 : Making the dashes in the separatator clearer MailerContrib: Brushing up HTML mailnotify template
8602 8606 Item1508 TWikibug:Item1508 : MailerContrib: Cleaning Brushing up plaintext e-mail template, HTML mailnotify template removing TEXTAREA
8522 8602 Item1511 TWikibug:Item1508 arguments : to getScriptUrl in wrong order frownMailerContrib: Cleaning up plaintext e-mail template, removing TEXTAREA
8434 8522 Item1465 TWikibug:Item1511 Fix 'TWiki.' : arguments to '%TWIKIEB%.' getScriptUrl in wrong order frown
8398 8434 Item1460 TWikibug:Item1465 polished up the comment a : Fix 'TWiki.' to '%TWIKIEB%.' bit
8308 8398 Item1362 TWikibug:Item1460 moving mailnotify cron script : polished up the comment a bit
7848 8308 Item1167 TWikibug:Item1362 forced all mail operations to : moving mailnotify cron script generate absolute URLs
7568 7848 Item910 TWikibug:Item1167 use SCRIPTURL{view} instead of complex url expr : forced all mail operations to generate absolute URLs
6864 7568 Item624 TWikibug:Item910 mailer templates moved the the right places : use SCRIPTURL{view} instead of complex url expr
6861 6864 Item624 TWikibug:Item624 Added proper : mailer templates support for plain text mails moved the the right places
6809 6861 Item623 TWikibug:Item624 don't print anything if verbosity is switched off. : Added proper templates support for plain text mails
6659 6809 Item528 TWikibug:Item623 Updated : don't print anything if verbosity is switched off. MailerContrib. it's working and the sendmail parameter is used.
6474 6659 Item420 TWikibug:Item528 removed spurious : Updated remove_obsolete_locks from MailerContrib. it's working and the sendmail parameter is used.
5924 6474 Item153 TWikibug:Item420 fix mail URL-fixing scheme : removed spurious remove_obsolete_locks from MailerContrib
5269 5924 Minor doc fixes TWikibug:Item153: fix mail URL-fixing scheme
5266 5269 Doc tidy-ups, added Minor doc fixes filtering of _ webs, added obsolete lock script
5264 5266 Changed default to add web name to user name (I hope) Doc tidy-ups, added filtering of _ webs, added obsolete lock script
5263 5264 Minor doc tidyups Changed default to add web name to user name (I hope)
5261 5263 Documentation changes, and Minor doc tidyups fixed to scan all webs.
5253 5261 runnable as CGI script, minor bugfixes, removed dependency Documentation changes, and fixed to scan all webs. on DBCacheContrib
5234 5253 Minor doc changes runnable as CGI script, minor bugfixes, removed dependency on DBCacheContrib
5231 5234 Made a change Minor doc changes an object, added unit tests to CVS, lots of testing.
4 5231 March 2005 1.010 Dakar release ready. Made a change an object, added unit tests to CVS, lots of testing.
12 Oct 2004 4 March 2005 1.004 Added support for 1.010 Dakar release ready. 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 12 Oct 2004 1.003 Excluded _ webs 1.004 Added support for anti-subscriptions. Doc fixes from processing, added bin/remove_obsolete_locksTWiki:Main.PeterThoenyfor full reverse-compatibility . Bug fixes to permissions code. Back-off and retry if the mailer can't be reached (should really be in Net::sendEmail)
1 6 Oct 2004 1.002 PeterThoeny provided additional documentation 1.003 Excluded _ webs from processing, added bin/remove_obsolete_locks for full reverse-compatibility
27 Sep 1 Oct 2004 1.001 runnable as CGI script, 1.002 PeterThoeny provided additional documentation minor bugfixes, removed dependency on DBCacheContrib
8 27 Sep 2004 1.000 Initial version 1.001 runnable as CGI script, minor bugfixes, removed dependency on DBCacheContrib
Home: 8 Sep 2004 TWiki:Plugins/MailerContrib 1.000 Initial version
Feedback: Home: TWiki:Plugins/MailerContribDev TWiki:Plugins/MailerContrib
Appraisal: Feedback: http://TWiki.org/cgi-bin/view/Plugins/MailerContribAppraisal TWiki:Plugins/MailerContribDev
Appraisal: http://TWiki.org/cgi-bin/view/Plugins/MailerContribAppraisal
IAttachmentActionSizeDateWhoComment
logo.gifgiflogo.gifmanage 11.2 K 25 Apr 2008 - 13:03AdminUser Saved by install script
wikiringlogo20x20.pngpngwikiringlogo20x20.pngmanage 1.3 K 25 Apr 2008 - 13:03AdminUser Saved by install script

View topic | View difference side by side | History: r6 < r5 < r4 < r3 | More topic actions
 
This site is powered by FoswikiCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding Foswiki? Send feedback