Difference: MailerContrib (1 vs. 19)

Revision 192018-07-10 - TWikiContributor

 

Mailer Contrib

<--
   Contributions to this TWiki extension are appreciated. Please update the page at
   http://twiki.org/cgi-bin/view/Plugins/MailerContrib or provide feedback at
   http://twiki.org/cgi-bin/view/Plugins/MailerContribDev.
   If you are a TWiki contributor please update the extension in the SVN repository.
-->
Send e-mail notification of changes to topics in TWiki webs

Introduction

The Mailer Contrib 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) lets you trivially add a "Subscribe to changes" button to topics

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.

<-- Included by WebChangesAlert -->

Users subscribe to email notifications using their WikiName or an alternative email address, and can specify the webs/topics they wish to track, Whole 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. Please note that the guest user TWikiGuest does not have an email address mapped to it, and will never receive email regardless of the configuration of that user.

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:
  • Using wild-card character in topic names - 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.
  • Unsubscribing to specific topics - 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.
  • Including child-topics in subscription - 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.
  • Subscribing to entire topic ("news mode") - Each topic may optionally be immediately followed by an exclamation mark ! and/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 full topic to be mailed every time even if there have been no changes, and ? will mail the full topic only if there have been changes. One can limit the content of the subscribed topic to send out by inserting %STARTPUBLISH% and %STOPPUBLISH% markers within the topic. Note that "news mode" subscriptions require a corresponding cron job that includes the "-news" option (see details).

Examples: 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 a custom user mapping) to all changes to Web* topics.
   * 'IT:admins' : Web*
In addition to single quotes ('), double quotes (") do the same job for a non-TWiki group.

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 subscribers identified by email addresses. A subscriber identified by an email address alone will only be sent change notifications if the topic they are subscribed to is readable by guest users. You can limit what email addresses can be used in WebNotify, or even block use of emails altogether, 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

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

This module is pre-installed. TWiki administrators can upgrade it as needed on the TWiki server.

<--/twistyPlugin twikiMakeVisibleInline-->

  • For an automated installation, run the configure script and follow "Find More Extensions" in the in the Extensions section.

  • Or, follow these manual installation steps:
    • Download the ZIP file from the extension home on twiki.org (see below).
    • Unzip MailerContrib.zip in your twiki installation directory.
    • Set the ownership of the extracted directories and files to the webserver user.
    • Install the dependencies (if any).

  • To make sure the installation was successful, run the mailnotify script from the command line, with no parameters. In this case it will print out what it would have done to STDOUT.

Additional settings

Restricting email addresses

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

Custom user/group notations without quotes

As mentioned in the 'IT:admins' example above, you can use custom user/group notations in WebNotify by surrounding them with single quotes (') or double quotes ("). But surrounding them in quotes is inconvenient especially because quotes are not needed for access control.

So you can set {MailerContrib}{CustomUserGroupNotations} to a regular expression matching the custom notations in configure. If you do that, you don't need to put those into quotes.

Email sending retries

If an error occurs with email sending, it reties. By default, 5 tries happen before it gives up. You can specify the max number of tries by setting {MailerContrib}{SendEmailTries}.

<--/twistyPlugin-->

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 subscriptions that include "!" or "?" following the topic)
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.

ALERT! Note: Multiple instances of mailnotify script are not allowed to be executed simultaneously. If you need to run the script multiple times with different options, make sure the cron jobs are scheduled so a previous run has finished before the next starts. You can also write a small script that runs mailnotify in sequence as described in TWiki:Support.DuplicateNotificationsFromMailerCon.

<-- 
  • Set STUB = TWiki::Contrib::Mailer
  • Set SHORTDESCRIPTION = Send e-mail notification of changes to topics in TWiki webs
-->

Developer Notes

The changes mails sent to subscribers 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

Many thanks to the following sponsors for supporting this work:

Author: TWiki:Main.CrawfordCurrie (http://c-dot.co.uk)
Changed:
<
<
Copyright: © 2004, Wind River Systems;
© 2008, wikiring.com
© 2004-2015 TWiki:TWiki.TWikiContributor
>
>
Copyright: © 2004, Wind River Systems;
© 2008, wikiring.com
© 2004-2018 TWiki:TWiki.TWikiContributor
 
License: GPL (GNU General Public License)
Changed:
<
<
Version: 2015-05-27
>
>
Version: 2018-07-10
 
<--/twistyPlugin twikiMakeVisibleInline-->
Added:
>
>
2018-07-10: TWikibug:Item7841: Copyright update to 2018
2017-12-21: TWikibug:Item7830: Fixed link to page author in notification template
2016-01-09: TWikibug:Item7708: Copyright update to 2016
 
2015-05-27: TWikibug:Item7604: Switch from GPL v2 to v3
2014-10-01: TWikibug:Item7559: mailnotify showing subscribers of a web wrong -- fixed
2013-05-02: TWikibug:Item7248: TWiki::Contrib::MailerContrib::_processWeb() to set $twiki->{webName}
2013-04-26: TWikibug:Item7245: Allowing a custom user/group notation in WebNotify without quotes
2013-02-15: TWikibug:Item7123: Use TWISTY in installation instructions and change history
2012-12-08: TWikibug:Item6962: Configure change: Move contrib settings from top level section to Extensions section -- TWiki:Main.PeterThoeny
2012-01-13: TWikibug:Item6796: Fixing copyright year to 2012
2011-11-07: TWikibug:Item6799: Doc & typo fixes
2011-07-08: TWikibug:Item6725: Change global package variables from "use vars" to "our" -- TWiki:Main.PeterThoeny
2010-07-09: TWikibug:Item6518: Fix for notification e-mail showing %MAKETEXT{"Web"} in subject
2010-06-12: TWikibug:Item6489: Separate WIKITOOLNAME from WEB name; escape WEB name to avoid auto-linking in case web is WikiWord
2010-05-26: TWikibug:Item6474: Fix for mailnotify failing due to non-existing _alert method
2010-05-21: TWikibug:Item6433: More doc fixes
2010-04-25: TWikibug:Item6433: Doc fixes, no code changes
15 Oct 2008 TWikibug:Item: generalised code to enable TWiki:Codev.SubscribePlugin to delegate parsing to MailerContrib - TWiki:Main.SvenDowideit
14 Oct 2008 TWikibug:Item6066: fixed issue for user mappings where cuid = login - TWiki:Main.SvenDowideit
27 Aug 2008 TWikibug:Item5949: fixed problem with unsubscribe that should result in an empty subscription
03 Aug 2008 TWiki 4.2.1 release version
27 Jul 2008 TWikibug:Item5776: TWiki:Main.KennethLavrsen added note to warn against running multiple instances of mailnotify at the same time.
15 May 2008 TWikibug:Item5232: TWiki:Main.CrawfordCurrie added support for non-ascii alphanumerics in topic names to WebNotify. TWikibug:Item5630: TWiki:Main.SvenDowideit fixed some spelling errors
25 Jan 2008 TWikibug:Item4812: added TWiki:Main.BobGoldstein's noexpand patch for groups
2 Nov 2007 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
9 Sep 2007 TWikibug:Item4326 workaround for possible error in WebNotify API in old releases, Should not affect most users.
6 Sep 2007 TWikibug:Item4488 doc tweaks
14550 TWikibug:Item4461 - 'Changed' link now points to most recent changes, not the entire history
22 Jun 2007 TWikibug:Item4284 - added access control checks and email filter
21 May 2007 TWikibug:Item3969 - 8bit email fix (TWiki:Main.WillNorris)
13623 TWikibug:Item4014 no changes was resetting the notify time to 0. Thanks to TWiki:Main.JeffCrawford for nailing this down.
12496 TWikibug:Item3415 mailnotify did not send notifications to intranet users because of wrong call to findUser.
11672 Added newsletter support, after much harassment from TWiki:Main.LynnwoodBrown
11534 TWikibug:Item2153 Clarified docs. TWikibug:Item2698 Improved error reporting.
8808 TWikibug:Item1654 mailnotify must enter the command_line context
8625 TWikibug:Item1508 Making the dashes in the separatator clearer
8606 TWikibug:Item1508 MailerContrib: Brushing up HTML mailnotify template
8602 TWikibug:Item1508 MailerContrib: Cleaning up plaintext e-mail template, removing TEXTAREA
8522 TWikibug:Item1511 arguments to getScriptUrl in wrong order frown
8434 TWikibug:Item1465 Fix 'TWiki.' to '%TWIKIEB%.'
8398 TWikibug:Item1460 polished up the comment a bit
8308 TWikibug:Item1362 moving mailnotify cron script
7848 TWikibug:Item1167 forced all mail operations to generate absolute URLs
7568 TWikibug:tem910 use SCRIPTURL{view} instead of complex url expr
6864 TWikibug:tem624 mailer templates moved the the right places
6861 TWikibug:tem624 Added proper templates support for plain text mails
6809 TWikibug:tem623 don't print anything if verbosity is switched off.
6659 TWikibug:tem528 Updated MailerContrib. it's working and the sendmail parameter is used.
6474 TWikibug:tem420 removed spurious remove_obsolete_locks from MailerContrib
5924 TWikibug:tem153 fix mail URL-fixing scheme
5269 Minor doc fixes
5266 Doc tidy-ups, added filtering of _ webs, added obsolete lock script
5264 Changed default to add web name to user name (I hope)
5263 Minor doc tidyups
5261 Documentation changes, and fixed to scan all webs.
5253 runnable as CGI script, minor bugfixes, removed dependency on DBCacheContrib
5234 Minor doc changes
5231 Made a change an object, added unit tests to CVS, lots of testing.
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
<--/twistyPlugin-->
Home: http://TWiki.org/cgi-bin/view/Plugins/MailerContrib
Feedback: http://TWiki.org/cgi-bin/view/Plugins/MailerContribDev
Appraisal: http://TWiki.org/cgi-bin/view/Plugins/MailerContribAppraisal

Related Topics: TWikiPreferences, CustomUserGroupNotations

Revision 182015-05-28 - TWikiContributor

 

Mailer Contrib

<--
   Contributions to this TWiki extension are appreciated. Please update the page at
   http://twiki.org/cgi-bin/view/Plugins/MailerContrib or provide feedback at
   http://twiki.org/cgi-bin/view/Plugins/MailerContribDev.
   If you are a TWiki contributor please update the extension in the SVN repository.
-->
Changed:
<
<
>
>
Added:
>
>
 
Added:
>
>
 Send e-mail notification of changes to topics in TWiki webs

Introduction

The Mailer Contrib 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) lets you trivially add a "Subscribe to changes" button to topics

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.

<-- Included by WebChangesAlert -->

Users subscribe to email notifications using their WikiName or an alternative email address, and can specify the webs/topics they wish to track, Whole 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. Please note that the guest user TWikiGuest does not have an email address mapped to it, and will never receive email regardless of the configuration of that user.

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:
  • Using wild-card character in topic names - 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.
  • Unsubscribing to specific topics - 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.
  • Including child-topics in subscription - 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.
  • Subscribing to entire topic ("news mode") - Each topic may optionally be immediately followed by an exclamation mark ! and/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 full topic to be mailed every time even if there have been no changes, and ? will mail the full topic only if there have been changes. One can limit the content of the subscribed topic to send out by inserting %STARTPUBLISH% and %STOPPUBLISH% markers within the topic. Note that "news mode" subscriptions require a corresponding cron job that includes the "-news" option (see details).

Examples: 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 a custom user mapping) to all changes to Web* topics.
   * 'IT:admins' : Web*
In addition to single quotes ('), double quotes (") do the same job for a non-TWiki group.

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 subscribers identified by email addresses. A subscriber identified by an email address alone will only be sent change notifications if the topic they are subscribed to is readable by guest users. You can limit what email addresses can be used in WebNotify, or even block use of emails altogether, 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

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

This module is pre-installed. TWiki administrators can upgrade it as needed on the TWiki server.

<--/twistyPlugin twikiMakeVisibleInline-->

  • For an automated installation, run the configure script and follow "Find More Extensions" in the in the Extensions section.

  • Or, follow these manual installation steps:
    • Download the ZIP file from the extension home on twiki.org (see below).
    • Unzip MailerContrib.zip in your twiki installation directory.
    • Set the ownership of the extracted directories and files to the webserver user.
    • Install the dependencies (if any).

  • To make sure the installation was successful, run the mailnotify script from the command line, with no parameters. In this case it will print out what it would have done to STDOUT.

Additional settings

Restricting email addresses

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

Custom user/group notations without quotes

As mentioned in the 'IT:admins' example above, you can use custom user/group notations in WebNotify by surrounding them with single quotes (') or double quotes ("). But surrounding them in quotes is inconvenient especially because quotes are not needed for access control.

So you can set {MailerContrib}{CustomUserGroupNotations} to a regular expression matching the custom notations in configure. If you do that, you don't need to put those into quotes.

Added:
>
>

Email sending retries

If an error occurs with email sending, it reties. By default, 5 tries happen before it gives up. You can specify the max number of tries by setting {MailerContrib}{SendEmailTries}.

 
<--/twistyPlugin-->

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 subscriptions that include "!" or "?" following the topic)
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.

ALERT! Note: Multiple instances of mailnotify script are not allowed to be executed simultaneously. If you need to run the script multiple times with different options, make sure the cron jobs are scheduled so a previous run has finished before the next starts. You can also write a small script that runs mailnotify in sequence as described in TWiki:Support.DuplicateNotificationsFromMailerCon.

<-- 
  • Set STUB = TWiki::Contrib::Mailer
  • Set SHORTDESCRIPTION = Send e-mail notification of changes to topics in TWiki webs
-->

Developer Notes

The changes mails sent to subscribers 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

Many thanks to the following sponsors for supporting this work:

Author: TWiki:Main.CrawfordCurrie (http://c-dot.co.uk)
Changed:
<
<
Copyright: © 2004, Wind River Systems;
© 2008, wikiring.com
© 2004-2013 TWiki:TWiki.TWikiContributor
>
>
Copyright: © 2004, Wind River Systems;
© 2008, wikiring.com
© 2004-2015 TWiki:TWiki.TWikiContributor
 
License: GPL (GNU General Public License)
Changed:
<
<
Version: 2014-10-01
>
>
Version: 2015-05-27
 
<--/twistyPlugin twikiMakeVisibleInline-->
Added:
>
>
2015-05-27: TWikibug:Item7604: Switch from GPL v2 to v3
 
2014-10-01: TWikibug:Item7559: mailnotify showing subscribers of a web wrong -- fixed
2013-05-02: TWikibug:Item7248: TWiki::Contrib::MailerContrib::_processWeb() to set $twiki->{webName}
2013-04-26: TWikibug:Item7245: Allowing a custom user/group notation in WebNotify without quotes
2013-02-15: TWikibug:Item7123: Use TWISTY in installation instructions and change history
2012-12-08: TWikibug:Item6962: Configure change: Move contrib settings from top level section to Extensions section -- TWiki:Main.PeterThoeny
2012-01-13: TWikibug:Item6796: Fixing copyright year to 2012
2011-11-07: TWikibug:Item6799: Doc & typo fixes
2011-07-08: TWikibug:Item6725: Change global package variables from "use vars" to "our" -- TWiki:Main.PeterThoeny
2010-07-09: TWikibug:Item6518: Fix for notification e-mail showing %MAKETEXT{"Web"} in subject
2010-06-12: TWikibug:Item6489: Separate WIKITOOLNAME from WEB name; escape WEB name to avoid auto-linking in case web is WikiWord
2010-05-26: TWikibug:Item6474: Fix for mailnotify failing due to non-existing _alert method
2010-05-21: TWikibug:Item6433: More doc fixes
2010-04-25: TWikibug:Item6433: Doc fixes, no code changes
15 Oct 2008 TWikibug:Item: generalised code to enable TWiki:Codev.SubscribePlugin to delegate parsing to MailerContrib - TWiki:Main.SvenDowideit
14 Oct 2008 TWikibug:Item6066: fixed issue for user mappings where cuid = login - TWiki:Main.SvenDowideit
27 Aug 2008 TWikibug:Item5949: fixed problem with unsubscribe that should result in an empty subscription
03 Aug 2008 TWiki 4.2.1 release version
27 Jul 2008 TWikibug:Item5776: TWiki:Main.KennethLavrsen added note to warn against running multiple instances of mailnotify at the same time.
15 May 2008 TWikibug:Item5232: TWiki:Main.CrawfordCurrie added support for non-ascii alphanumerics in topic names to WebNotify. TWikibug:Item5630: TWiki:Main.SvenDowideit fixed some spelling errors
25 Jan 2008 TWikibug:Item4812: added TWiki:Main.BobGoldstein's noexpand patch for groups
2 Nov 2007 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
9 Sep 2007 TWikibug:Item4326 workaround for possible error in WebNotify API in old releases, Should not affect most users.
6 Sep 2007 TWikibug:Item4488 doc tweaks
14550 TWikibug:Item4461 - 'Changed' link now points to most recent changes, not the entire history
22 Jun 2007 TWikibug:Item4284 - added access control checks and email filter
21 May 2007 TWikibug:Item3969 - 8bit email fix (TWiki:Main.WillNorris)
13623 TWikibug:Item4014 no changes was resetting the notify time to 0. Thanks to TWiki:Main.JeffCrawford for nailing this down.
12496 TWikibug:Item3415 mailnotify did not send notifications to intranet users because of wrong call to findUser.
11672 Added newsletter support, after much harassment from TWiki:Main.LynnwoodBrown
11534 TWikibug:Item2153 Clarified docs. TWikibug:Item2698 Improved error reporting.
8808 TWikibug:Item1654 mailnotify must enter the command_line context
8625 TWikibug:Item1508 Making the dashes in the separatator clearer
8606 TWikibug:Item1508 MailerContrib: Brushing up HTML mailnotify template
8602 TWikibug:Item1508 MailerContrib: Cleaning up plaintext e-mail template, removing TEXTAREA
8522 TWikibug:Item1511 arguments to getScriptUrl in wrong order frown
8434 TWikibug:Item1465 Fix 'TWiki.' to '%TWIKIEB%.'
8398 TWikibug:Item1460 polished up the comment a bit
8308 TWikibug:Item1362 moving mailnotify cron script
7848 TWikibug:Item1167 forced all mail operations to generate absolute URLs
7568 TWikibug:tem910 use SCRIPTURL{view} instead of complex url expr
6864 TWikibug:tem624 mailer templates moved the the right places
6861 TWikibug:tem624 Added proper templates support for plain text mails
6809 TWikibug:tem623 don't print anything if verbosity is switched off.
6659 TWikibug:tem528 Updated MailerContrib. it's working and the sendmail parameter is used.
6474 TWikibug:tem420 removed spurious remove_obsolete_locks from MailerContrib
5924 TWikibug:tem153 fix mail URL-fixing scheme
5269 Minor doc fixes
5266 Doc tidy-ups, added filtering of _ webs, added obsolete lock script
5264 Changed default to add web name to user name (I hope)
5263 Minor doc tidyups
5261 Documentation changes, and fixed to scan all webs.
5253 runnable as CGI script, minor bugfixes, removed dependency on DBCacheContrib
5234 Minor doc changes
5231 Made a change an object, added unit tests to CVS, lots of testing.
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
<--/twistyPlugin-->
Home: http://TWiki.org/cgi-bin/view/Plugins/MailerContrib
Feedback: http://TWiki.org/cgi-bin/view/Plugins/MailerContribDev
Appraisal: http://TWiki.org/cgi-bin/view/Plugins/MailerContribAppraisal

Related Topics: TWikiPreferences, CustomUserGroupNotations

Revision 172014-10-03 - TWikiContributor

 

Mailer Contrib

<--
   Contributions to this TWiki extension are appreciated. Please update the page at
   http://twiki.org/cgi-bin/view/Plugins/MailerContrib or provide feedback at
   http://twiki.org/cgi-bin/view/Plugins/MailerContribDev.
   If you are a TWiki contributor please update the extension in the SVN repository.
-->
Send e-mail notification of changes to topics in TWiki webs

Introduction

The Mailer Contrib 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) lets you trivially add a "Subscribe to changes" button to topics

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.

<-- Included by WebChangesAlert -->

Users subscribe to email notifications using their WikiName or an alternative email address, and can specify the webs/topics they wish to track, Whole 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. Please note that the guest user TWikiGuest does not have an email address mapped to it, and will never receive email regardless of the configuration of that user.

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:
  • Using wild-card character in topic names - 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.
  • Unsubscribing to specific topics - 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.
  • Including child-topics in subscription - 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.
  • Subscribing to entire topic ("news mode") - Each topic may optionally be immediately followed by an exclamation mark ! and/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 full topic to be mailed every time even if there have been no changes, and ? will mail the full topic only if there have been changes. One can limit the content of the subscribed topic to send out by inserting %STARTPUBLISH% and %STOPPUBLISH% markers within the topic. Note that "news mode" subscriptions require a corresponding cron job that includes the "-news" option (see details).

Examples: 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 a custom user mapping) to all changes to Web* topics.
   * 'IT:admins' : Web*
In addition to single quotes ('), double quotes (") do the same job for a non-TWiki group.

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 subscribers identified by email addresses. A subscriber identified by an email address alone will only be sent change notifications if the topic they are subscribed to is readable by guest users. You can limit what email addresses can be used in WebNotify, or even block use of emails altogether, 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

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

This module is pre-installed. TWiki administrators can upgrade it as needed on the TWiki server.

<--/twistyPlugin twikiMakeVisibleInline-->

  • For an automated installation, run the configure script and follow "Find More Extensions" in the in the Extensions section.

  • Or, follow these manual installation steps:
    • Download the ZIP file from the extension home on twiki.org (see below).
    • Unzip MailerContrib.zip in your twiki installation directory.
    • Set the ownership of the extracted directories and files to the webserver user.
    • Install the dependencies (if any).

  • To make sure the installation was successful, run the mailnotify script from the command line, with no parameters. In this case it will print out what it would have done to STDOUT.

Additional settings

Restricting email addresses

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

Custom user/group notations without quotes

As mentioned in the 'IT:admins' example above, you can use custom user/group notations in WebNotify by surrounding them with single quotes (') or double quotes ("). But surrounding them in quotes is inconvenient especially because quotes are not needed for access control.

So you can set {MailerContrib}{CustomUserGroupNotations} to a regular expression matching the custom notations in configure. If you do that, you don't need to put those into quotes.

<--/twistyPlugin-->

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 subscriptions that include "!" or "?" following the topic)
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.

ALERT! Note: Multiple instances of mailnotify script are not allowed to be executed simultaneously. If you need to run the script multiple times with different options, make sure the cron jobs are scheduled so a previous run has finished before the next starts. You can also write a small script that runs mailnotify in sequence as described in TWiki:Support.DuplicateNotificationsFromMailerCon.

<-- 
  • Set STUB = TWiki::Contrib::Mailer
  • Set SHORTDESCRIPTION = Send e-mail notification of changes to topics in TWiki webs
-->

Developer Notes

The changes mails sent to subscribers 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

Many thanks to the following sponsors for supporting this work:

Author: TWiki:Main.CrawfordCurrie (http://c-dot.co.uk)
Copyright: © 2004, Wind River Systems;
© 2008, wikiring.com
© 2004-2013 TWiki:TWiki.TWikiContributor
License: GPL (GNU General Public License)
Changed:
<
<
Version: 2013-05-02
>
>
Version: 2014-10-01
 
<--/twistyPlugin twikiMakeVisibleInline-->
Added:
>
>
2014-10-01: TWikibug:Item7559: mailnotify showing subscribers of a web wrong -- fixed
 
2013-05-02: TWikibug:Item7248: TWiki::Contrib::MailerContrib::_processWeb() to set $twiki->{webName}
2013-04-26: TWikibug:Item7245: Allowing a custom user/group notation in WebNotify without quotes
2013-02-15: TWikibug:Item7123: Use TWISTY in installation instructions and change history
2012-12-08: TWikibug:Item6962: Configure change: Move contrib settings from top level section to Extensions section -- TWiki:Main.PeterThoeny
2012-01-13: TWikibug:Item6796: Fixing copyright year to 2012
2011-11-07: TWikibug:Item6799: Doc & typo fixes
2011-07-08: TWikibug:Item6725: Change global package variables from "use vars" to "our" -- TWiki:Main.PeterThoeny
2010-07-09: TWikibug:Item6518: Fix for notification e-mail showing %MAKETEXT{"Web"} in subject
2010-06-12: TWikibug:Item6489: Separate WIKITOOLNAME from WEB name; escape WEB name to avoid auto-linking in case web is WikiWord
2010-05-26: TWikibug:Item6474: Fix for mailnotify failing due to non-existing _alert method
2010-05-21: TWikibug:Item6433: More doc fixes
2010-04-25: TWikibug:Item6433: Doc fixes, no code changes
15 Oct 2008 TWikibug:Item: generalised code to enable TWiki:Codev.SubscribePlugin to delegate parsing to MailerContrib - TWiki:Main.SvenDowideit
14 Oct 2008 TWikibug:Item6066: fixed issue for user mappings where cuid = login - TWiki:Main.SvenDowideit
27 Aug 2008 TWikibug:Item5949: fixed problem with unsubscribe that should result in an empty subscription
03 Aug 2008 TWiki 4.2.1 release version
27 Jul 2008 TWikibug:Item5776: TWiki:Main.KennethLavrsen added note to warn against running multiple instances of mailnotify at the same time.
15 May 2008 TWikibug:Item5232: TWiki:Main.CrawfordCurrie added support for non-ascii alphanumerics in topic names to WebNotify. TWikibug:Item5630: TWiki:Main.SvenDowideit fixed some spelling errors
25 Jan 2008 TWikibug:Item4812: added TWiki:Main.BobGoldstein's noexpand patch for groups
2 Nov 2007 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
9 Sep 2007 TWikibug:Item4326 workaround for possible error in WebNotify API in old releases, Should not affect most users.
6 Sep 2007 TWikibug:Item4488 doc tweaks
14550 TWikibug:Item4461 - 'Changed' link now points to most recent changes, not the entire history
22 Jun 2007 TWikibug:Item4284 - added access control checks and email filter
21 May 2007 TWikibug:Item3969 - 8bit email fix (TWiki:Main.WillNorris)
13623 TWikibug:Item4014 no changes was resetting the notify time to 0. Thanks to TWiki:Main.JeffCrawford for nailing this down.
12496 TWikibug:Item3415 mailnotify did not send notifications to intranet users because of wrong call to findUser.
11672 Added newsletter support, after much harassment from TWiki:Main.LynnwoodBrown
11534 TWikibug:Item2153 Clarified docs. TWikibug:Item2698 Improved error reporting.
8808 TWikibug:Item1654 mailnotify must enter the command_line context
8625 TWikibug:Item1508 Making the dashes in the separatator clearer
8606 TWikibug:Item1508 MailerContrib: Brushing up HTML mailnotify template
8602 TWikibug:Item1508 MailerContrib: Cleaning up plaintext e-mail template, removing TEXTAREA
8522 TWikibug:Item1511 arguments to getScriptUrl in wrong order frown
8434 TWikibug:Item1465 Fix 'TWiki.' to '%TWIKIEB%.'
8398 TWikibug:Item1460 polished up the comment a bit
8308 TWikibug:Item1362 moving mailnotify cron script
7848 TWikibug:Item1167 forced all mail operations to generate absolute URLs
7568 TWikibug:tem910 use SCRIPTURL{view} instead of complex url expr
6864 TWikibug:tem624 mailer templates moved the the right places
6861 TWikibug:tem624 Added proper templates support for plain text mails
6809 TWikibug:tem623 don't print anything if verbosity is switched off.
6659 TWikibug:tem528 Updated MailerContrib. it's working and the sendmail parameter is used.
6474 TWikibug:tem420 removed spurious remove_obsolete_locks from MailerContrib
5924 TWikibug:tem153 fix mail URL-fixing scheme
5269 Minor doc fixes
5266 Doc tidy-ups, added filtering of _ webs, added obsolete lock script
5264 Changed default to add web name to user name (I hope)
5263 Minor doc tidyups
5261 Documentation changes, and fixed to scan all webs.
5253 runnable as CGI script, minor bugfixes, removed dependency on DBCacheContrib
5234 Minor doc changes
5231 Made a change an object, added unit tests to CVS, lots of testing.
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
<--/twistyPlugin-->
Home: http://TWiki.org/cgi-bin/view/Plugins/MailerContrib
Feedback: http://TWiki.org/cgi-bin/view/Plugins/MailerContribDev
Appraisal: http://TWiki.org/cgi-bin/view/Plugins/MailerContribAppraisal

Related Topics: TWikiPreferences, CustomUserGroupNotations

Revision 162013-05-02 - TWikiContributor

 

Mailer Contrib

<--
   Contributions to this TWiki extension are appreciated. Please update the page at
   http://twiki.org/cgi-bin/view/Plugins/MailerContrib or provide feedback at
   http://twiki.org/cgi-bin/view/Plugins/MailerContribDev.
   If you are a TWiki contributor please update the extension in the SVN repository.
-->
Send e-mail notification of changes to topics in TWiki webs

Introduction

The Mailer Contrib 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) lets you trivially add a "Subscribe to changes" button to topics

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.

<-- Included by WebChangesAlert -->

Users subscribe to email notifications using their WikiName or an alternative email address, and can specify the webs/topics they wish to track, Whole 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. Please note that the guest user TWikiGuest does not have an email address mapped to it, and will never receive email regardless of the configuration of that user.

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:
  • Using wild-card character in topic names - 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.
  • Unsubscribing to specific topics - 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.
  • Including child-topics in subscription - 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.
  • Subscribing to entire topic ("news mode") - Each topic may optionally be immediately followed by an exclamation mark ! and/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 full topic to be mailed every time even if there have been no changes, and ? will mail the full topic only if there have been changes. One can limit the content of the subscribed topic to send out by inserting %STARTPUBLISH% and %STOPPUBLISH% markers within the topic. Note that "news mode" subscriptions require a corresponding cron job that includes the "-news" option (see details).

Examples: 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
Changed:
<
<
Subscribe IT:admins (a non-TWiki group defined by an alternate user mapping) to all changes to Web* topics.
>
>
Subscribe IT:admins (a non-TWiki group defined by a custom user mapping) to all changes to Web* topics.
 
   * 'IT:admins' : Web*
Added:
>
>
In addition to single quotes ('), double quotes (") do the same job for a non-TWiki group.
  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.

Changed:
<
<
ALERT! Warning: Because an email address is not linked to a user name, there is no way for TWiki to check access controls for subscribers identified by email addresses. A subscriber identified by an email address alone will only be sent change notifications if the topic they are subscribed to is readable by guest users. You can limit what email addresses can be used in %NOTIFYTOPIC%, or even block use of emails altogether, using the {MailerContrib}{EmailFilterIn} setting in =configure.
>
>
ALERT! Warning: Because an email address is not linked to a user name, there is no way for TWiki to check access controls for subscribers identified by email addresses. A subscriber identified by an email address alone will only be sent change notifications if the topic they are subscribed to is readable by guest users. You can limit what email addresses can be used in WebNotify, or even block use of emails altogether, 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

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

This module is pre-installed. TWiki administrators can upgrade it as needed on the TWiki server.

<--/twistyPlugin twikiMakeVisibleInline-->

  • For an automated installation, run the configure script and follow "Find More Extensions" in the in the Extensions section.

  • Or, follow these manual installation steps:
    • Download the ZIP file from the extension home on twiki.org (see below).
    • Unzip MailerContrib.zip in your twiki installation directory.
    • Set the ownership of the extracted directories and files to the webserver user.
    • Install the dependencies (if any).

  • To make sure the installation was successful, run the mailnotify script from the command line, with no parameters. In this case it will print out what it would have done to STDOUT.
Deleted:
<
<
Additional settings
  • You can change the regular expression that matches email addresses in WebNotify using the {MailerContrib}{EmailFilterIn} setting in =configure. This allows you to limit the domains to which emails can be sent, or even block email addresses altogether.
 
Added:
>
>

Additional settings

Restricting email addresses

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

Custom user/group notations without quotes

As mentioned in the 'IT:admins' example above, you can use custom user/group notations in WebNotify by surrounding them with single quotes (') or double quotes ("). But surrounding them in quotes is inconvenient especially because quotes are not needed for access control.

So you can set {MailerContrib}{CustomUserGroupNotations} to a regular expression matching the custom notations in configure. If you do that, you don't need to put those into quotes.

 
<--/twistyPlugin-->

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 subscriptions that include "!" or "?" following the topic)
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.

ALERT! Note: Multiple instances of mailnotify script are not allowed to be executed simultaneously. If you need to run the script multiple times with different options, make sure the cron jobs are scheduled so a previous run has finished before the next starts. You can also write a small script that runs mailnotify in sequence as described in TWiki:Support.DuplicateNotificationsFromMailerCon.

<-- 
  • Set STUB = TWiki::Contrib::Mailer
  • Set SHORTDESCRIPTION = Send e-mail notification of changes to topics in TWiki webs
-->

Developer Notes

The changes mails sent to subscribers 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

Many thanks to the following sponsors for supporting this work:

Author: TWiki:Main.CrawfordCurrie (http://c-dot.co.uk)
Copyright: © 2004, Wind River Systems;
© 2008, wikiring.com
© 2004-2013 TWiki:TWiki.TWikiContributor
License: GPL (GNU General Public License)
Changed:
<
<
Version: 2013-02-15
>
>
Version: 2013-05-02
 
<--/twistyPlugin twikiMakeVisibleInline-->
Added:
>
>
2013-05-02: TWikibug:Item7248: TWiki::Contrib::MailerContrib::_processWeb() to set $twiki->{webName}
2013-04-26: TWikibug:Item7245: Allowing a custom user/group notation in WebNotify without quotes
 
2013-02-15: TWikibug:Item7123: Use TWISTY in installation instructions and change history
2012-12-08: TWikibug:Item6962: Configure change: Move contrib settings from top level section to Extensions section -- TWiki:Main.PeterThoeny
2012-01-13: TWikibug:Item6796: Fixing copyright year to 2012
2011-11-07: TWikibug:Item6799: Doc & typo fixes
2011-07-08: TWikibug:Item6725: Change global package variables from "use vars" to "our" -- TWiki:Main.PeterThoeny
2010-07-09: TWikibug:Item6518: Fix for notification e-mail showing %MAKETEXT{"Web"} in subject
2010-06-12: TWikibug:Item6489: Separate WIKITOOLNAME from WEB name; escape WEB name to avoid auto-linking in case web is WikiWord
2010-05-26: TWikibug:Item6474: Fix for mailnotify failing due to non-existing _alert method
2010-05-21: TWikibug:Item6433: More doc fixes
2010-04-25: TWikibug:Item6433: Doc fixes, no code changes
15 Oct 2008 TWikibug:Item: generalised code to enable TWiki:Codev.SubscribePlugin to delegate parsing to MailerContrib - TWiki:Main.SvenDowideit
14 Oct 2008 TWikibug:Item6066: fixed issue for user mappings where cuid = login - TWiki:Main.SvenDowideit
27 Aug 2008 TWikibug:Item5949: fixed problem with unsubscribe that should result in an empty subscription
03 Aug 2008 TWiki 4.2.1 release version
27 Jul 2008 TWikibug:Item5776: TWiki:Main.KennethLavrsen added note to warn against running multiple instances of mailnotify at the same time.
15 May 2008 TWikibug:Item5232: TWiki:Main.CrawfordCurrie added support for non-ascii alphanumerics in topic names to WebNotify. TWikibug:Item5630: TWiki:Main.SvenDowideit fixed some spelling errors
25 Jan 2008 TWikibug:Item4812: added TWiki:Main.BobGoldstein's noexpand patch for groups
2 Nov 2007 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
9 Sep 2007 TWikibug:Item4326 workaround for possible error in WebNotify API in old releases, Should not affect most users.
6 Sep 2007 TWikibug:Item4488 doc tweaks
14550 TWikibug:Item4461 - 'Changed' link now points to most recent changes, not the entire history
22 Jun 2007 TWikibug:Item4284 - added access control checks and email filter
21 May 2007 TWikibug:Item3969 - 8bit email fix (TWiki:Main.WillNorris)
13623 TWikibug:Item4014 no changes was resetting the notify time to 0. Thanks to TWiki:Main.JeffCrawford for nailing this down.
12496 TWikibug:Item3415 mailnotify did not send notifications to intranet users because of wrong call to findUser.
11672 Added newsletter support, after much harassment from TWiki:Main.LynnwoodBrown
11534 TWikibug:Item2153 Clarified docs. TWikibug:Item2698 Improved error reporting.
8808 TWikibug:Item1654 mailnotify must enter the command_line context
8625 TWikibug:Item1508 Making the dashes in the separatator clearer
8606 TWikibug:Item1508 MailerContrib: Brushing up HTML mailnotify template
8602 TWikibug:Item1508 MailerContrib: Cleaning up plaintext e-mail template, removing TEXTAREA
8522 TWikibug:Item1511 arguments to getScriptUrl in wrong order frown
8434 TWikibug:Item1465 Fix 'TWiki.' to '%TWIKIEB%.'
8398 TWikibug:Item1460 polished up the comment a bit
8308 TWikibug:Item1362 moving mailnotify cron script
7848 TWikibug:Item1167 forced all mail operations to generate absolute URLs
7568 TWikibug:tem910 use SCRIPTURL{view} instead of complex url expr
6864 TWikibug:tem624 mailer templates moved the the right places
6861 TWikibug:tem624 Added proper templates support for plain text mails
6809 TWikibug:tem623 don't print anything if verbosity is switched off.
6659 TWikibug:tem528 Updated MailerContrib. it's working and the sendmail parameter is used.
6474 TWikibug:tem420 removed spurious remove_obsolete_locks from MailerContrib
5924 TWikibug:tem153 fix mail URL-fixing scheme
5269 Minor doc fixes
5266 Doc tidy-ups, added filtering of _ webs, added obsolete lock script
5264 Changed default to add web name to user name (I hope)
5263 Minor doc tidyups
5261 Documentation changes, and fixed to scan all webs.
5253 runnable as CGI script, minor bugfixes, removed dependency on DBCacheContrib
5234 Minor doc changes
5231 Made a change an object, added unit tests to CVS, lots of testing.
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
<--/twistyPlugin-->
Home: http://TWiki.org/cgi-bin/view/Plugins/MailerContrib
Feedback: http://TWiki.org/cgi-bin/view/Plugins/MailerContribDev
Appraisal: http://TWiki.org/cgi-bin/view/Plugins/MailerContribAppraisal
Changed:
<
<
Related Topics: TWikiPreferences
>
>
Related Topics: TWikiPreferences, CustomUserGroupNotations
 

Revision 152013-02-16 - TWikiContributor

 

Mailer Contrib

<--
   Contributions to this TWiki extension are appreciated. Please update the page at
   http://twiki.org/cgi-bin/view/Plugins/MailerContrib or provide feedback at
   http://twiki.org/cgi-bin/view/Plugins/MailerContribDev.
   If you are a TWiki contributor please update the extension in the SVN repository.
-->
Send e-mail notification of changes to topics in TWiki webs

Introduction

The Mailer Contrib 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) lets you trivially add a "Subscribe to changes" button to topics

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.

<-- Included by WebChangesAlert -->

Users subscribe to email notifications using their WikiName or an alternative email address, and can specify the webs/topics they wish to track, Whole 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. Please note that the guest user TWikiGuest does not have an email address mapped to it, and will never receive email regardless of the configuration of that user.

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:
  • Using wild-card character in topic names - 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.
  • Unsubscribing to specific topics - 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.
  • Including child-topics in subscription - 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.
  • Subscribing to entire topic ("news mode") - Each topic may optionally be immediately followed by an exclamation mark ! and/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 full topic to be mailed every time even if there have been no changes, and ? will mail the full topic only if there have been changes. One can limit the content of the subscribed topic to send out by inserting %STARTPUBLISH% and %STOPPUBLISH% markers within the topic. Note that "news mode" subscriptions require a corresponding cron job that includes the "-news" option (see details).

Examples: 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 subscribers identified by email addresses. A subscriber identified by an email address alone will only be sent change notifications if the topic they are subscribed to is readable by guest users. You can limit what email addresses can be used in %NOTIFYTOPIC%, or even block use of emails altogether, 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

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

Changed:
<
<
Note: You do not need to install anything on the browser to use this extension. The following instructions are for the administrator who installs the extension on the TWiki server.
>
>
This module is pre-installed. TWiki administrators can upgrade it as needed on the TWiki server.
Added:
>
>
<--/twistyPlugin twikiMakeVisibleInline-->
 
  • For an automated installation, run the configure script and follow "Find More Extensions" in the in the Extensions section.

  • Or, follow these manual installation steps:
    • Download the ZIP file from the extension home on twiki.org (see below).
    • Unzip MailerContrib.zip in your twiki installation directory.
    • Set the ownership of the extracted directories and files to the webserver user.
    • Install the dependencies (if any).

  • To make sure the installation was successful, run the mailnotify script from the command line, with no parameters. In this case it will print out what it would have done to STDOUT.
Additional settings
  • You can change the regular expression that matches email addresses in WebNotify using the {MailerContrib}{EmailFilterIn} setting in =configure. This allows you to limit the domains to which emails can be sent, or even block email addresses altogether.
Added:
>
>
<--/twistyPlugin-->
 

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 subscriptions that include "!" or "?" following the topic)
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.

ALERT! Note: Multiple instances of mailnotify script are not allowed to be executed simultaneously. If you need to run the script multiple times with different options, make sure the cron jobs are scheduled so a previous run has finished before the next starts. You can also write a small script that runs mailnotify in sequence as described in TWiki:Support.DuplicateNotificationsFromMailerCon.

<-- 
  • Set STUB = TWiki::Contrib::Mailer
  • Set SHORTDESCRIPTION = Send e-mail notification of changes to topics in TWiki webs
-->

Developer Notes

The changes mails sent to subscribers 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

Many thanks to the following sponsors for supporting this work:

Added:
>
>
 
Author: TWiki:Main.CrawfordCurrie (http://c-dot.co.uk)
Changed:
<
<
Copyright: © 2004, Wind River Systems;
© 2008, http://WikiRing.com
© 2004-2012 TWiki:TWiki.TWikiContributor
>
>
Copyright: © 2004, Wind River Systems;
© 2008, wikiring.com
© 2004-2013 TWiki:TWiki.TWikiContributor
 
License: GPL (GNU General Public License)
Changed:
<
<
Version: 2012-12-08
Change History:
<-- specify latest version first -->
 
>
>
Version: 2013-02-15
%TWISTY{
Added:
>
>
mode="div" showlink="Show Change History https://twiki.pp.rl.ac.uk/twiki/pub/TWiki/TWikiDocGraphics/toggleopen.gif" hidelink="Hide Change History https://twiki.pp.rl.ac.uk/twiki/pub/TWiki/TWikiDocGraphics/toggleclose.gif" }%
2013-02-15: TWikibug:Item7123: Use TWISTY in installation instructions and change history
 
2012-12-08: TWikibug:Item6962: Configure change: Move contrib settings from top level section to Extensions section -- TWiki:Main.PeterThoeny
2012-01-13: TWikibug:Item6796: Fixing copyright year to 2012
2011-11-07: TWikibug:Item6799: Doc & typo fixes
2011-07-08: TWikibug:Item6725: Change global package variables from "use vars" to "our" -- TWiki:Main.PeterThoeny
2010-07-09: TWikibug:Item6518: Fix for notification e-mail showing %MAKETEXT{"Web"} in subject
2010-06-12: TWikibug:Item6489: Separate WIKITOOLNAME from WEB name; escape WEB name to avoid auto-linking in case web is WikiWord
2010-05-26: TWikibug:Item6474: Fix for mailnotify failing due to non-existing _alert method
2010-05-21: TWikibug:Item6433: More doc fixes
2010-04-25: TWikibug:Item6433: Doc fixes, no code changes
15 Oct 2008 TWikibug:Item: generalised code to enable TWiki:Codev.SubscribePlugin to delegate parsing to MailerContrib - TWiki:Main.SvenDowideit
14 Oct 2008 TWikibug:Item6066: fixed issue for user mappings where cuid = login - TWiki:Main.SvenDowideit
27 Aug 2008 TWikibug:Item5949: fixed problem with unsubscribe that should result in an empty subscription
03 Aug 2008 TWiki 4.2.1 release version
27 Jul 2008 TWikibug:Item5776: TWiki:Main.KennethLavrsen added note to warn against running multiple instances of mailnotify at the same time.
15 May 2008 TWikibug:Item5232: TWiki:Main.CrawfordCurrie added support for non-ascii alphanumerics in topic names to WebNotify. TWikibug:Item5630: TWiki:Main.SvenDowideit fixed some spelling errors
25 Jan 2008 TWikibug:Item4812: added TWiki:Main.BobGoldstein's noexpand patch for groups
2 Nov 2007 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
9 Sep 2007 TWikibug:Item4326 workaround for possible error in WebNotify API in old releases, Should not affect most users.
6 Sep 2007 TWikibug:Item4488 doc tweaks
14550 TWikibug:Item4461 - 'Changed' link now points to most recent changes, not the entire history
22 Jun 2007 TWikibug:Item4284 - added access control checks and email filter
21 May 2007 TWikibug:Item3969 - 8bit email fix (TWiki:Main.WillNorris)
13623 TWikibug:Item4014 no changes was resetting the notify time to 0. Thanks to TWiki:Main.JeffCrawford for nailing this down.
12496 TWikibug:Item3415 mailnotify did not send notifications to intranet users because of wrong call to findUser.
11672 Added newsletter support, after much harassment from TWiki:Main.LynnwoodBrown
11534 TWikibug:Item2153 Clarified docs. TWikibug:Item2698 Improved error reporting.
8808 TWikibug:Item1654 mailnotify must enter the command_line context
8625 TWikibug:Item1508 Making the dashes in the separatator clearer
8606 TWikibug:Item1508 MailerContrib: Brushing up HTML mailnotify template
8602 TWikibug:Item1508 MailerContrib: Cleaning up plaintext e-mail template, removing TEXTAREA
8522 TWikibug:Item1511 arguments to getScriptUrl in wrong order frown
8434 TWikibug:Item1465 Fix 'TWiki.' to '%TWIKIEB%.'
8398 TWikibug:Item1460 polished up the comment a bit
8308 TWikibug:Item1362 moving mailnotify cron script
7848 TWikibug:Item1167 forced all mail operations to generate absolute URLs
7568 TWikibug:tem910 use SCRIPTURL{view} instead of complex url expr
6864 TWikibug:tem624 mailer templates moved the the right places
6861 TWikibug:tem624 Added proper templates support for plain text mails
6809 TWikibug:tem623 don't print anything if verbosity is switched off.
6659 TWikibug:tem528 Updated MailerContrib. it's working and the sendmail parameter is used.
6474 TWikibug:tem420 removed spurious remove_obsolete_locks from MailerContrib
5924 TWikibug:tem153 fix mail URL-fixing scheme
5269 Minor doc fixes
5266 Doc tidy-ups, added filtering of _ webs, added obsolete lock script
5264 Changed default to add web name to user name (I hope)
5263 Minor doc tidyups
5261 Documentation changes, and fixed to scan all webs.
5253 runnable as CGI script, minor bugfixes, removed dependency on DBCacheContrib
5234 Minor doc changes
5231 Made a change an object, added unit tests to CVS, lots of testing.
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
Added:
>
>
</>
<--/twistyPlugin-->
 
Home: http://TWiki.org/cgi-bin/view/Plugins/MailerContrib
Feedback: http://TWiki.org/cgi-bin/view/Plugins/MailerContribDev
Appraisal: http://TWiki.org/cgi-bin/view/Plugins/MailerContribAppraisal

Related Topics: TWikiPreferences

Revision 142012-12-09 - TWikiContributor

 

Mailer Contrib

<--
   Contributions to this TWiki extension are appreciated. Please update the page at
   http://twiki.org/cgi-bin/view/Plugins/MailerContrib or provide feedback at
   http://twiki.org/cgi-bin/view/Plugins/MailerContribDev.
   If you are a TWiki contributor please update the extension in the SVN repository.
-->
Send e-mail notification of changes to topics in TWiki webs

Introduction

The Mailer Contrib 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) lets you trivially add a "Subscribe to changes" button to topics

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.

<-- Included by WebChangesAlert -->

Users subscribe to email notifications using their WikiName or an alternative email address, and can specify the webs/topics they wish to track, Whole 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. Please note that the guest user TWikiGuest does not have an email address mapped to it, and will never receive email regardless of the configuration of that user.

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:
  • Using wild-card character in topic names - 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.
  • Unsubscribing to specific topics - 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.
  • Including child-topics in subscription - 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.
  • Subscribing to entire topic ("news mode") - Each topic may optionally be immediately followed by an exclamation mark ! and/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 full topic to be mailed every time even if there have been no changes, and ? will mail the full topic only if there have been changes. One can limit the content of the subscribed topic to send out by inserting %STARTPUBLISH% and %STOPPUBLISH% markers within the topic. Note that "news mode" subscriptions require a corresponding cron job that includes the "-news" option (see details).

Examples: 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 subscribers identified by email addresses. A subscriber identified by an email address alone will only be sent change notifications if the topic they are subscribed to is readable by guest users. You can limit what email addresses can be used in %NOTIFYTOPIC%, or even block use of emails altogether, 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

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

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

  • For an automated installation, run the configure script and follow "Find More Extensions" in the in the Extensions section.

  • Or, follow these manual installation steps:
    • Download the ZIP file from the extension home on twiki.org (see below).
    • Unzip MailerContrib.zip in your twiki installation directory.
    • Set the ownership of the extracted directories and files to the webserver user.
    • Install the dependencies (if any).

  • To make sure the installation was successful, run the mailnotify script from the command line, with no parameters. In this case it will print out what it would have done to STDOUT.
Additional settings
  • You can change the regular expression that matches email addresses in WebNotify using the {MailerContrib}{EmailFilterIn} 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)

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 subscriptions that include "!" or "?" following the topic)
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.

ALERT! Note: Multiple instances of mailnotify script are not allowed to be executed simultaneously. If you need to run the script multiple times with different options, make sure the cron jobs are scheduled so a previous run has finished before the next starts. You can also write a small script that runs mailnotify in sequence as described in TWiki:Support.DuplicateNotificationsFromMailerCon.

<-- 
  • Set STUB = TWiki::Contrib::Mailer
  • Set SHORTDESCRIPTION = Send e-mail notification of changes to topics in TWiki webs
-->

Developer Notes

The changes mails sent to subscribers 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

Many thanks to the following sponsors for supporting this work:

Author: TWiki:Main.CrawfordCurrie (http://c-dot.co.uk)
Copyright: © 2004, Wind River Systems;
© 2008, http://WikiRing.com
© 2004-2012 TWiki:TWiki.TWikiContributor
License: GPL (GNU General Public License)
Changed:
<
<
Version: 2012-01-13
>
>
Version: 2012-12-08
 
Change History:
<-- specify latest version first -->
 
Added:
>
>
2012-12-08: TWikibug:Item6962: Configure change: Move contrib settings from top level section to Extensions section -- TWiki:Main.PeterThoeny
 
2012-01-13: TWikibug:Item6796: Fixing copyright year to 2012
2011-11-07: TWikibug:Item6799: Doc & typo fixes
2011-07-08: TWikibug:Item6725: Change global package variables from "use vars" to "our" -- TWiki:Main.PeterThoeny
2010-07-09: TWikibug:Item6518: Fix for notification e-mail showing %MAKETEXT{"Web"} in subject
2010-06-12: TWikibug:Item6489: Separate WIKITOOLNAME from WEB name; escape WEB name to avoid auto-linking in case web is WikiWord
2010-05-26: TWikibug:Item6474: Fix for mailnotify failing due to non-existing _alert method
2010-05-21: TWikibug:Item6433: More doc fixes
2010-04-25: TWikibug:Item6433: Doc fixes, no code changes
15 Oct 2008 TWikibug:Item: generalised code to enable TWiki:Codev.SubscribePlugin to delegate parsing to MailerContrib - TWiki:Main.SvenDowideit
14 Oct 2008 TWikibug:Item6066: fixed issue for user mappings where cuid = login - TWiki:Main.SvenDowideit
27 Aug 2008 TWikibug:Item5949: fixed problem with unsubscribe that should result in an empty subscription
03 Aug 2008 TWiki 4.2.1 release version
27 Jul 2008 TWikibug:Item5776: TWiki:Main.KennethLavrsen added note to warn against running multiple instances of mailnotify at the same time.
15 May 2008 TWikibug:Item5232: TWiki:Main.CrawfordCurrie added support for non-ascii alphanumerics in topic names to WebNotify. TWikibug:Item5630: TWiki:Main.SvenDowideit fixed some spelling errors
25 Jan 2008 TWikibug:Item4812: added TWiki:Main.BobGoldstein's noexpand patch for groups
2 Nov 2007 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
9 Sep 2007 TWikibug:Item4326 workaround for possible error in WebNotify API in old releases, Should not affect most users.
6 Sep 2007 TWikibug:Item4488 doc tweaks
14550 TWikibug:Item4461 - 'Changed' link now points to most recent changes, not the entire history
22 Jun 2007 TWikibug:Item4284 - added access control checks and email filter
21 May 2007 TWikibug:Item3969 - 8bit email fix (TWiki:Main.WillNorris)
13623 TWikibug:Item4014 no changes was resetting the notify time to 0. Thanks to TWiki:Main.JeffCrawford for nailing this down.
12496 TWikibug:Item3415 mailnotify did not send notifications to intranet users because of wrong call to findUser.
11672 Added newsletter support, after much harassment from TWiki:Main.LynnwoodBrown
11534 TWikibug:Item2153 Clarified docs. TWikibug:Item2698 Improved error reporting.
8808 TWikibug:Item1654 mailnotify must enter the command_line context
8625 TWikibug:Item1508 Making the dashes in the separatator clearer
8606 TWikibug:Item1508 MailerContrib: Brushing up HTML mailnotify template
8602 TWikibug:Item1508 MailerContrib: Cleaning up plaintext e-mail template, removing TEXTAREA
8522 TWikibug:Item1511 arguments to getScriptUrl in wrong order frown
8434 TWikibug:Item1465 Fix 'TWiki.' to '%TWIKIEB%.'
8398 TWikibug:Item1460 polished up the comment a bit
8308 TWikibug:Item1362 moving mailnotify cron script
7848 TWikibug:Item1167 forced all mail operations to generate absolute URLs
7568 TWikibug:tem910 use SCRIPTURL{view} instead of complex url expr
6864 TWikibug:tem624 mailer templates moved the the right places
6861 TWikibug:tem624 Added proper templates support for plain text mails
6809 TWikibug:tem623 don't print anything if verbosity is switched off.
6659 TWikibug:tem528 Updated MailerContrib. it's working and the sendmail parameter is used.
6474 TWikibug:tem420 removed spurious remove_obsolete_locks from MailerContrib
5924 TWikibug:tem153 fix mail URL-fixing scheme
5269 Minor doc fixes
5266 Doc tidy-ups, added filtering of _ webs, added obsolete lock script
5264 Changed default to add web name to user name (I hope)
5263 Minor doc tidyups
5261 Documentation changes, and fixed to scan all webs.
5253 runnable as CGI script, minor bugfixes, removed dependency on DBCacheContrib
5234 Minor doc changes
5231 Made a change an object, added unit tests to CVS, lots of testing.
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: http://TWiki.org/cgi-bin/view/Plugins/MailerContrib
Feedback: http://TWiki.org/cgi-bin/view/Plugins/MailerContribDev
Appraisal: http://TWiki.org/cgi-bin/view/Plugins/MailerContribAppraisal

Related Topics: TWikiPreferences

Revision 132012-01-14 - TWikiContributor

 

Mailer Contrib

<--
   Contributions to this TWiki extension are appreciated. Please update the page at
   http://twiki.org/cgi-bin/view/Plugins/MailerContrib or provide feedback at
   http://twiki.org/cgi-bin/view/Plugins/MailerContribDev.
   If you are a TWiki contributor please update the extension in the SVN repository.
-->
Send e-mail notification of changes to topics in TWiki webs

Introduction

The Mailer Contrib 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) lets you trivially add a "Subscribe to changes" button to topics

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.

<-- Included by WebChangesAlert -->

Users subscribe to email notifications using their WikiName or an alternative email address, and can specify the webs/topics they wish to track, Whole 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. Please note that the guest user TWikiGuest does not have an email address mapped to it, and will never receive email regardless of the configuration of that user.

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:
  • Using wild-card character in topic names - 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.
  • Unsubscribing to specific topics - 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.
  • Including child-topics in subscription - 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.
  • Subscribing to entire topic ("news mode") - Each topic may optionally be immediately followed by an exclamation mark ! and/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 full topic to be mailed every time even if there have been no changes, and ? will mail the full topic only if there have been changes. One can limit the content of the subscribed topic to send out by inserting %STARTPUBLISH% and %STOPPUBLISH% markers within the topic. Note that "news mode" subscriptions require a corresponding cron job that includes the "-news" option (see details).

Examples: 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 subscribers identified by email addresses. A subscriber identified by an email address alone will only be sent change notifications if the topic they are subscribed to is readable by guest users. You can limit what email addresses can be used in %NOTIFYTOPIC%, or even block use of emails altogether, 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

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

Changed:
<
<
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.
>
>
Note: You do not need to install anything on the browser to use this extension. The following instructions are for the administrator who installs the extension on the TWiki server.
 
Changed:
<
<
Like many other TWiki extensions, this module is shipped with a fully
>
>
  • For an automated installation, run the configure script and follow "Find More Extensions" in the in the Extensions section.
Deleted:
<
<
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)
 
Deleted:
<
<
  • 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.
 
Changed:
<
<
>
>
  • Or, follow these manual installation steps:
Added:
>
>
    • Download the ZIP file from the extension home on twiki.org (see below).
    • Unzip MailerContrib.zip in your twiki installation directory.
    • Set the ownership of the extracted directories and files to the webserver user.
    • Install the dependencies (if any).
 
  • To make sure the installation was successful, run the mailnotify script from the command line, with no parameters. In this case it will print out what it would have done to STDOUT.
Additional settings
  • You can change the regular expression that matches email addresses in WebNotify using the {MailerContrib}{EmailFilterIn} 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)

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 subscriptions that include "!" or "?" following the topic)
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.

ALERT! Note: Multiple instances of mailnotify script are not allowed to be executed simultaneously. If you need to run the script multiple times with different options, make sure the cron jobs are scheduled so a previous run has finished before the next starts. You can also write a small script that runs mailnotify in sequence as described in TWiki:Support.DuplicateNotificationsFromMailerCon.

<-- 
  • Set STUB = TWiki::Contrib::Mailer
  • Set SHORTDESCRIPTION = Send e-mail notification of changes to topics in TWiki webs
-->

Developer Notes

The changes mails sent to subscribers 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

Many thanks to the following sponsors for supporting this work:

Author: TWiki:Main.CrawfordCurrie (http://c-dot.co.uk)
Copyright: © 2004, Wind River Systems;
© 2008, http://WikiRing.com
© 2004-2012 TWiki:TWiki.TWikiContributor
License: GPL (GNU General Public License)
Version: 2012-01-13
Change History:
<-- specify latest version first -->
 
2012-01-13: TWikibug:Item6796: Fixing copyright year to 2012
2011-11-07: TWikibug:Item6799: Doc & typo fixes
2011-07-08: TWikibug:Item6725: Change global package variables from "use vars" to "our" -- TWiki:Main.PeterThoeny
2010-07-09: TWikibug:Item6518: Fix for notification e-mail showing %MAKETEXT{"Web"} in subject
2010-06-12: TWikibug:Item6489: Separate WIKITOOLNAME from WEB name; escape WEB name to avoid auto-linking in case web is WikiWord
2010-05-26: TWikibug:Item6474: Fix for mailnotify failing due to non-existing _alert method
2010-05-21: TWikibug:Item6433: More doc fixes
2010-04-25: TWikibug:Item6433: Doc fixes, no code changes
15 Oct 2008 TWikibug:Item: generalised code to enable TWiki:Codev.SubscribePlugin to delegate parsing to MailerContrib - TWiki:Main.SvenDowideit
14 Oct 2008 TWikibug:Item6066: fixed issue for user mappings where cuid = login - TWiki:Main.SvenDowideit
27 Aug 2008 TWikibug:Item5949: fixed problem with unsubscribe that should result in an empty subscription
03 Aug 2008 TWiki 4.2.1 release version
27 Jul 2008 TWikibug:Item5776: TWiki:Main.KennethLavrsen added note to warn against running multiple instances of mailnotify at the same time.
15 May 2008 TWikibug:Item5232: TWiki:Main.CrawfordCurrie added support for non-ascii alphanumerics in topic names to WebNotify. TWikibug:Item5630: TWiki:Main.SvenDowideit fixed some spelling errors
25 Jan 2008 TWikibug:Item4812: added TWiki:Main.BobGoldstein's noexpand patch for groups
2 Nov 2007 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
9 Sep 2007 TWikibug:Item4326 workaround for possible error in WebNotify API in old releases, Should not affect most users.
6 Sep 2007 TWikibug:Item4488 doc tweaks
14550 TWikibug:Item4461 - 'Changed' link now points to most recent changes, not the entire history
22 Jun 2007 TWikibug:Item4284 - added access control checks and email filter
21 May 2007 TWikibug:Item3969 - 8bit email fix (TWiki:Main.WillNorris)
13623 TWikibug:Item4014 no changes was resetting the notify time to 0. Thanks to TWiki:Main.JeffCrawford for nailing this down.
12496 TWikibug:Item3415 mailnotify did not send notifications to intranet users because of wrong call to findUser.
11672 Added newsletter support, after much harassment from TWiki:Main.LynnwoodBrown
11534 TWikibug:Item2153 Clarified docs. TWikibug:Item2698 Improved error reporting.
8808 TWikibug:Item1654 mailnotify must enter the command_line context
8625 TWikibug:Item1508 Making the dashes in the separatator clearer
8606 TWikibug:Item1508 MailerContrib: Brushing up HTML mailnotify template
8602 TWikibug:Item1508 MailerContrib: Cleaning up plaintext e-mail template, removing TEXTAREA
8522 TWikibug:Item1511 arguments to getScriptUrl in wrong order frown
8434 TWikibug:Item1465 Fix 'TWiki.' to '%TWIKIEB%.'
8398 TWikibug:Item1460 polished up the comment a bit
8308 TWikibug:Item1362 moving mailnotify cron script
7848 TWikibug:Item1167 forced all mail operations to generate absolute URLs
7568 TWikibug:tem910 use SCRIPTURL{view} instead of complex url expr
6864 TWikibug:tem624 mailer templates moved the the right places
6861 TWikibug:tem624 Added proper templates support for plain text mails
6809 TWikibug:tem623 don't print anything if verbosity is switched off.
6659 TWikibug:tem528 Updated MailerContrib. it's working and the sendmail parameter is used.
6474 TWikibug:tem420 removed spurious remove_obsolete_locks from MailerContrib
5924 TWikibug:tem153 fix mail URL-fixing scheme
5269 Minor doc fixes
5266 Doc tidy-ups, added filtering of _ webs, added obsolete lock script
5264 Changed default to add web name to user name (I hope)
5263 Minor doc tidyups
5261 Documentation changes, and fixed to scan all webs.
5253 runnable as CGI script, minor bugfixes, removed dependency on DBCacheContrib
5234 Minor doc changes
5231 Made a change an object, added unit tests to CVS, lots of testing.
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: http://TWiki.org/cgi-bin/view/Plugins/MailerContrib
Feedback: http://TWiki.org/cgi-bin/view/Plugins/MailerContribDev
Appraisal: http://TWiki.org/cgi-bin/view/Plugins/MailerContribAppraisal

Related Topics: TWikiPreferences

Revision 122012-01-14 - TWikiContributor

 

Mailer Contrib

<--
   Contributions to this TWiki extension are appreciated. Please update the page at
   http://twiki.org/cgi-bin/view/Plugins/MailerContrib or provide feedback at
   http://twiki.org/cgi-bin/view/Plugins/MailerContribDev.
   If you are a TWiki contributor please update the extension in the SVN repository.
-->
Send e-mail notification of changes to topics in TWiki webs

Introduction

The Mailer Contrib 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) lets you trivially add a "Subscribe to changes" button to topics

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.

<-- Included by WebChangesAlert -->

Users subscribe to email notifications using their WikiName or an alternative email address, and can specify the webs/topics they wish to track, Whole 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

Changed:
<
<
an email address, then it must be enclosed in 'single' or "double" quotes.
>
>
an email address, then it must be enclosed in 'single' or "double" quotes. Please note that the guest user TWikiGuest does not have an email address mapped to it, and will never receive email regardless of the configuration of that user.
  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:
  • Using wild-card character in topic names - 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.
  • Unsubscribing to specific topics - 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.
  • Including child-topics in subscription - 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.
  • Subscribing to entire topic ("news mode") - Each topic may optionally be immediately followed by an exclamation mark ! and/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 full topic to be mailed every time even if there have been no changes, and ? will mail the full topic only if there have been changes. One can limit the content of the subscribed topic to send out by inserting %STARTPUBLISH% and %STOPPUBLISH% markers within the topic. Note that "news mode" subscriptions require a corresponding cron job that includes the "-news" option (see details).

Examples: 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.

Changed:
<
<
ALERT! Warning: Because an email address is not linked to a user name, there is no way for TWiki to check access controls for subscribers identified by email addresses. A subscriber identified by an email address alone will only be sent change notifications if the topic they are subscribed to is readable by guest users. You can limit what email addresses can be used in %NOTIFYTOPIC%, or even block use of emails altogther, using the {MailerContrib}{EmailFilterIn} setting in =configure.
>
>
ALERT! Warning: Because an email address is not linked to a user name, there is no way for TWiki to check access controls for subscribers identified by email addresses. A subscriber identified by an email address alone will only be sent change notifications if the topic they are subscribed to is readable by guest users. You can limit what email addresses can be used in %NOTIFYTOPIC%, or even block use of emails altogether, 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

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

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 mailnotify script from the command line, with no parameters. In this case it will print out what it would have done to STDOUT.
Additional settings
  • You can change the regular expression that matches email addresses in WebNotify using the {MailerContrib}{EmailFilterIn} 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)

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 subscriptions that include "!" or "?" following the topic)
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.

ALERT! Note: Multiple instances of mailnotify script are not allowed to be executed simultaneously. If you need to run the script multiple times with different options, make sure the cron jobs are scheduled so a previous run has finished before the next starts. You can also write a small script that runs mailnotify in sequence as described in TWiki:Support.DuplicateNotificationsFromMailerCon.

<-- 
  • Set STUB = TWiki::Contrib::Mailer
  • Set SHORTDESCRIPTION = Send e-mail notification of changes to topics in TWiki webs
-->

Developer Notes

The changes mails sent to subscribers 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

Many thanks to the following sponsors for supporting this work:

Author: TWiki:Main.CrawfordCurrie (http://c-dot.co.uk)
Changed:
<
<
Copyright: © 2004, Wind River Systems;
© 2008, http://WikiRing.com
© 2004-2010 TWiki:TWiki.TWikiContributor
>
>
Copyright: © 2004, Wind River Systems;
© 2008, http://WikiRing.com
© 2004-2012 TWiki:TWiki.TWikiContributor
 
License: GPL (GNU General Public License)
Changed:
<
<
Version: 21605 (2011-08-20)
>
>
Version: 2012-01-13
 
Change History:
<-- specify latest version first -->
 
Added:
>
>
2012-01-13: TWikibug:Item6796: Fixing copyright year to 2012
2011-11-07: TWikibug:Item6799: Doc & typo fixes
 
2011-07-08: TWikibug:Item6725: Change global package variables from "use vars" to "our" -- TWiki:Main.PeterThoeny
Changed:
<
<
2010-07-09: TWikibug:Item6518 - Fix for notification e-mail showing %MAKETEXT{"Web"} in subject
2010-06-12: TWikibug:Item6489 - Separate WIKITOOLNAME from WEB name; escape WEB name to avoid auto-linking in case web is WikiWord
2010-05-26: TWikibug:Item6474 - Fix for mailnotify failing due to non-existing _alert method
2010-05-21: TWikibug:Item6433 - more doc fixes
2010-04-25: TWikibug:Item6433 - doc fixes, no code changes
>
>
2010-07-09: TWikibug:Item6518: Fix for notification e-mail showing %MAKETEXT{"Web"} in subject
2010-06-12: TWikibug:Item6489: Separate WIKITOOLNAME from WEB name; escape WEB name to avoid auto-linking in case web is WikiWord
2010-05-26: TWikibug:Item6474: Fix for mailnotify failing due to non-existing _alert method
2010-05-21: TWikibug:Item6433: More doc fixes
2010-04-25: TWikibug:Item6433: Doc fixes, no code changes
 
15 Oct 2008 TWikibug:Item: generalised code to enable TWiki:Codev.SubscribePlugin to delegate parsing to MailerContrib - TWiki:Main.SvenDowideit
14 Oct 2008 TWikibug:Item6066: fixed issue for user mappings where cuid = login - TWiki:Main.SvenDowideit
27 Aug 2008 TWikibug:Item5949: fixed problem with unsubscribe that should result in an empty subscription
03 Aug 2008 TWiki 4.2.1 release version
27 Jul 2008 TWikibug:Item5776: TWiki:Main.KennethLavrsen added note to warn against running multiple instances of mailnotify at the same time.
15 May 2008 TWikibug:Item5232: TWiki:Main.CrawfordCurrie added support for non-ascii alphanumerics in topic names to WebNotify. TWikibug:Item5630: TWiki:Main.SvenDowideit fixed some spelling errors
25 Jan 2008 TWikibug:Item4812: added TWiki:Main.BobGoldstein's noexpand patch for groups
2 Nov 2007 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
9 Sep 2007 TWikibug:Item4326 workaround for possible error in WebNotify API in old releases, Should not affect most users.
6 Sep 2007 TWikibug:Item4488 doc tweaks
14550 TWikibug:Item4461 - 'Changed' link now points to most recent changes, not the entire history
22 Jun 2007 TWikibug:Item4284 - added access control checks and email filter
21 May 2007 TWikibug:Item3969 - 8bit email fix (TWiki:Main.WillNorris)
13623 TWikibug:Item4014 no changes was resetting the notify time to 0. Thanks to TWiki:Main.JeffCrawford for nailing this down.
12496 TWikibug:Item3415 mailnotify did not send notifications to intranet users because of wrong call to findUser.
11672 Added newsletter support, after much harassment from TWiki:Main.LynnwoodBrown
11534 TWikibug:Item2153 Clarified docs. TWikibug:Item2698 Improved error reporting.
8808 TWikibug:Item1654 mailnotify must enter the command_line context
8625 TWikibug:Item1508 Making the dashes in the separatator clearer
8606 TWikibug:Item1508 MailerContrib: Brushing up HTML mailnotify template
8602 TWikibug:Item1508 MailerContrib: Cleaning up plaintext e-mail template, removing TEXTAREA
8522 TWikibug:Item1511 arguments to getScriptUrl in wrong order frown
8434 TWikibug:Item1465 Fix 'TWiki.' to '%TWIKIEB%.'
8398 TWikibug:Item1460 polished up the comment a bit
8308 TWikibug:Item1362 moving mailnotify cron script
7848 TWikibug:Item1167 forced all mail operations to generate absolute URLs
7568 TWikibug:tem910 use SCRIPTURL{view} instead of complex url expr
6864 TWikibug:tem624 mailer templates moved the the right places
6861 TWikibug:tem624 Added proper templates support for plain text mails
6809 TWikibug:tem623 don't print anything if verbosity is switched off.
6659 TWikibug:tem528 Updated MailerContrib. it's working and the sendmail parameter is used.
6474 TWikibug:tem420 removed spurious remove_obsolete_locks from MailerContrib
5924 TWikibug:tem153 fix mail URL-fixing scheme
5269 Minor doc fixes
5266 Doc tidy-ups, added filtering of _ webs, added obsolete lock script
5264 Changed default to add web name to user name (I hope)
5263 Minor doc tidyups
5261 Documentation changes, and fixed to scan all webs.
5253 runnable as CGI script, minor bugfixes, removed dependency on DBCacheContrib
5234 Minor doc changes
5231 Made a change an object, added unit tests to CVS, lots of testing.
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: http://TWiki.org/cgi-bin/view/Plugins/MailerContrib
Feedback: http://TWiki.org/cgi-bin/view/Plugins/MailerContribDev
Appraisal: http://TWiki.org/cgi-bin/view/Plugins/MailerContribAppraisal

Related Topics: TWikiPreferences

Revision 112011-07-09 - TWikiContributor

 

Mailer Contrib

<--
   Contributions to this TWiki extension are appreciated. Please update the page at
   http://twiki.org/cgi-bin/view/Plugins/MailerContrib or provide feedback at
   http://twiki.org/cgi-bin/view/Plugins/MailerContribDev.
   If you are a TWiki contributor please update the extension in the SVN repository.
-->
Send e-mail notification of changes to topics in TWiki webs

Introduction

The Mailer Contrib 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) lets you trivially add a "Subscribe to changes" button to topics

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.

<-- Included by WebChangesAlert -->

Users subscribe to email notifications using their WikiName or an alternative email address, and can specify the webs/topics they wish to track, Whole 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:
  • Using wild-card character in topic names - 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.
  • Unsubscribing to specific topics - 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.
  • Including child-topics in subscription - 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.
  • Subscribing to entire topic ("news mode") - Each topic may optionally be immediately followed by an exclamation mark ! and/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 full topic to be mailed every time even if there have been no changes, and ? will mail the full topic only if there have been changes. One can limit the content of the subscribed topic to send out by inserting %STARTPUBLISH% and %STOPPUBLISH% markers within the topic. Note that "news mode" subscriptions require a corresponding cron job that includes the "-news" option (see details).

Examples: 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 subscribers identified by email addresses. A subscriber identified by an email address alone will only be sent change notifications if the topic they are subscribed to is readable by guest users. You can limit what email addresses can be used in %NOTIFYTOPIC%, 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

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

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 mailnotify script from the command line, with no parameters. In this case it will print out what it would have done to STDOUT.
Additional settings
  • You can change the regular expression that matches email addresses in WebNotify using the {MailerContrib}{EmailFilterIn} 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)

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 subscriptions that include "!" or "?" following the topic)
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.

ALERT! Note: Multiple instances of mailnotify script are not allowed to be executed simultaneously. If you need to run the script multiple times with different options, make sure the cron jobs are scheduled so a previous run has finished before the next starts. You can also write a small script that runs mailnotify in sequence as described in TWiki:Support.DuplicateNotificationsFromMailerCon.

<-- 
  • Set STUB = TWiki::Contrib::Mailer
  • Set SHORTDESCRIPTION = Send e-mail notification of changes to topics in TWiki webs
-->

Developer Notes

The changes mails sent to subscribers 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

Many thanks to the following sponsors for supporting this work:

Changed:
<
<
Author: TWiki:Main/CrawfordCurrie (http://c-dot.co.uk)
Copyright: © 2004, Wind River Systems;
© 2008, http://WikiRing.com
© 2004-2010 TWiki:TWiki/TWikiContributor
>
>
Author: TWiki:Main.CrawfordCurrie (http://c-dot.co.uk)
Copyright: © 2004, Wind River Systems;
© 2008, http://WikiRing.com
© 2004-2010 TWiki:TWiki.TWikiContributor
 
License: GPL (GNU General Public License)
Changed:
<
<
Version: 20895 (2011-05-03)
>
>
Version: 21605 (2011-08-20)
 
Change History:
<-- specify latest version first -->
 
Added:
>
>
2011-07-08: TWikibug:Item6725: Change global package variables from "use vars" to "our" -- TWiki:Main.PeterThoeny
 
2010-07-09: TWikibug:Item6518 - Fix for notification e-mail showing %MAKETEXT{"Web"} in subject
2010-06-12: TWikibug:Item6489 - Separate WIKITOOLNAME from WEB name; escape WEB name to avoid auto-linking in case web is WikiWord
2010-05-26: TWikibug:Item6474 - Fix for mailnotify failing due to non-existing _alert method
2010-05-21: TWikibug:Item6433 - more doc fixes
2010-04-25: TWikibug:Item6433 - doc fixes, no code changes
15 Oct 2008 TWikibug:Item: generalised code to enable TWiki:Codev.SubscribePlugin to delegate parsing to MailerContrib - TWiki:Main.SvenDowideit
14 Oct 2008 TWikibug:Item6066: fixed issue for user mappings where cuid = login - TWiki:Main.SvenDowideit
27 Aug 2008 TWikibug:Item5949: fixed problem with unsubscribe that should result in an empty subscription
03 Aug 2008 TWiki 4.2.1 release version
27 Jul 2008 TWikibug:Item5776: TWiki:Main.KennethLavrsen added note to warn against running multiple instances of mailnotify at the same time.
15 May 2008 TWikibug:Item5232: TWiki:Main.CrawfordCurrie added support for non-ascii alphanumerics in topic names to WebNotify. TWikibug:Item5630: TWiki:Main.SvenDowideit fixed some spelling errors
25 Jan 2008 TWikibug:Item4812: added TWiki:Main.BobGoldstein's noexpand patch for groups
2 Nov 2007 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
9 Sep 2007 TWikibug:Item4326 workaround for possible error in WebNotify API in old releases, Should not affect most users.
6 Sep 2007 TWikibug:Item4488 doc tweaks
14550 TWikibug:Item4461 - 'Changed' link now points to most recent changes, not the entire history
22 Jun 2007 TWikibug:Item4284 - added access control checks and email filter
21 May 2007 TWikibug:Item3969 - 8bit email fix (TWiki:Main.WillNorris)
13623 TWikibug:Item4014 no changes was resetting the notify time to 0. Thanks to TWiki:Main.JeffCrawford for nailing this down.
12496 TWikibug:Item3415 mailnotify did not send notifications to intranet users because of wrong call to findUser.
11672 Added newsletter support, after much harassment from TWiki:Main.LynnwoodBrown
11534 TWikibug:Item2153 Clarified docs. TWikibug:Item2698 Improved error reporting.
8808 TWikibug:Item1654 mailnotify must enter the command_line context
8625 TWikibug:Item1508 Making the dashes in the separatator clearer
8606 TWikibug:Item1508 MailerContrib: Brushing up HTML mailnotify template
8602 TWikibug:Item1508 MailerContrib: Cleaning up plaintext e-mail template, removing TEXTAREA
8522 TWikibug:Item1511 arguments to getScriptUrl in wrong order frown
8434 TWikibug:Item1465 Fix 'TWiki.' to '%TWIKIEB%.'
8398 TWikibug:Item1460 polished up the comment a bit
8308 TWikibug:Item1362 moving mailnotify cron script
7848 TWikibug:Item1167 forced all mail operations to generate absolute URLs
7568 TWikibug:tem910 use SCRIPTURL{view} instead of complex url expr
6864 TWikibug:tem624 mailer templates moved the the right places
6861 TWikibug:tem624 Added proper templates support for plain text mails
6809 TWikibug:tem623 don't print anything if verbosity is switched off.
6659 TWikibug:tem528 Updated MailerContrib. it's working and the sendmail parameter is used.
6474 TWikibug:tem420 removed spurious remove_obsolete_locks from MailerContrib
5924 TWikibug:tem153 fix mail URL-fixing scheme
5269 Minor doc fixes
5266 Doc tidy-ups, added filtering of _ webs, added obsolete lock script
5264 Changed default to add web name to user name (I hope)
5263 Minor doc tidyups
5261 Documentation changes, and fixed to scan all webs.
5253 runnable as CGI script, minor bugfixes, removed dependency on DBCacheContrib
5234 Minor doc changes
5231 Made a change an object, added unit tests to CVS, lots of testing.
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: http://TWiki.org/cgi-bin/view/Plugins/MailerContrib
Feedback: http://TWiki.org/cgi-bin/view/Plugins/MailerContribDev
Appraisal: http://TWiki.org/cgi-bin/view/Plugins/MailerContribAppraisal

Related Topics: TWikiPreferences

Revision 102010-07-09 - TWikiContributor

 

Mailer Contrib

<--
   Contributions to this TWiki extension are appreciated. Please update the page at
   http://twiki.org/cgi-bin/view/Plugins/MailerContrib or provide feedback at
   http://twiki.org/cgi-bin/view/Plugins/MailerContribDev.
   If you are a TWiki contributor please update the extension in the SVN repository.
-->
Send e-mail notification of changes to topics in TWiki webs

Introduction

The Mailer Contrib 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) lets you trivially add a "Subscribe to changes" button to topics

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.

<-- Included by WebChangesAlert -->

Users subscribe to email notifications using their WikiName or an alternative email address, and can specify the webs/topics they wish to track, Whole 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:
  • Using wild-card character in topic names - 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.
  • Unsubscribing to specific topics - 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.
  • Including child-topics in subscription - 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.
  • Subscribing to entire topic ("news mode") - Each topic may optionally be immediately followed by an exclamation mark ! and/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 full topic to be mailed every time even if there have been no changes, and ? will mail the full topic only if there have been changes. One can limit the content of the subscribed topic to send out by inserting %STARTPUBLISH% and %STOPPUBLISH% markers within the topic. Note that "news mode" subscriptions require a corresponding cron job that includes the "-news" option (see details).

Examples: 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 subscribers identified by email addresses. A subscriber identified by an email address alone will only be sent change notifications if the topic they are subscribed to is readable by guest users. You can limit what email addresses can be used in %NOTIFYTOPIC%, 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

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

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 mailnotify script from the command line, with no parameters. In this case it will print out what it would have done to STDOUT.
Additional settings
  • You can change the regular expression that matches email addresses in WebNotify using the {MailerContrib}{EmailFilterIn} 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)

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 subscriptions that include "!" or "?" following the topic)
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.

ALERT! Note: Multiple instances of mailnotify script are not allowed to be executed simultaneously. If you need to run the script multiple times with different options, make sure the cron jobs are scheduled so a previous run has finished before the next starts. You can also write a small script that runs mailnotify in sequence as described in TWiki:Support.DuplicateNotificationsFromMailerCon.

<-- 
  • Set STUB = TWiki::Contrib::Mailer
  • Set SHORTDESCRIPTION = Send e-mail notification of changes to topics in TWiki webs
-->

Developer Notes

The changes mails sent to subscribers 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

Many thanks to the following sponsors for supporting this work:

Author: TWiki:Main/CrawfordCurrie (http://c-dot.co.uk)
Copyright: © 2004, Wind River Systems;
© 2008, http://WikiRing.com
© 2004-2010 TWiki:TWiki/TWikiContributor
License: GPL (GNU General Public License)
Changed:
<
<
Version: 19212 (2011-04-11)
>
>
Version: 20895 (2011-05-03)
 
Change History:
<-- specify latest version first -->
 
2010-07-09: TWikibug:Item6518 - Fix for notification e-mail showing %MAKETEXT{"Web"} in subject
2010-06-12: TWikibug:Item6489 - Separate WIKITOOLNAME from WEB name; escape WEB name to avoid auto-linking in case web is WikiWord
2010-05-26: TWikibug:Item6474 - Fix for mailnotify failing due to non-existing _alert method
2010-05-21: TWikibug:Item6433 - more doc fixes
2010-04-25: TWikibug:Item6433 - doc fixes, no code changes
15 Oct 2008 TWikibug:Item: generalised code to enable TWiki:Codev.SubscribePlugin to delegate parsing to MailerContrib - TWiki:Main.SvenDowideit
14 Oct 2008 TWikibug:Item6066: fixed issue for user mappings where cuid = login - TWiki:Main.SvenDowideit
27 Aug 2008 TWikibug:Item5949: fixed problem with unsubscribe that should result in an empty subscription
03 Aug 2008 TWiki 4.2.1 release version
27 Jul 2008 TWikibug:Item5776: TWiki:Main.KennethLavrsen added note to warn against running multiple instances of mailnotify at the same time.
15 May 2008 TWikibug:Item5232: TWiki:Main.CrawfordCurrie added support for non-ascii alphanumerics in topic names to WebNotify. TWikibug:Item5630: TWiki:Main.SvenDowideit fixed some spelling errors
25 Jan 2008 TWikibug:Item4812: added TWiki:Main.BobGoldstein's noexpand patch for groups
2 Nov 2007 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
9 Sep 2007 TWikibug:Item4326 workaround for possible error in WebNotify API in old releases, Should not affect most users.
6 Sep 2007 TWikibug:Item4488 doc tweaks
14550 TWikibug:Item4461 - 'Changed' link now points to most recent changes, not the entire history
22 Jun 2007 TWikibug:Item4284 - added access control checks and email filter
21 May 2007 TWikibug:Item3969 - 8bit email fix (TWiki:Main.WillNorris)
13623 TWikibug:Item4014 no changes was resetting the notify time to 0. Thanks to TWiki:Main.JeffCrawford for nailing this down.
12496 TWikibug:Item3415 mailnotify did not send notifications to intranet users because of wrong call to findUser.
11672 Added newsletter support, after much harassment from TWiki:Main.LynnwoodBrown
11534 TWikibug:Item2153 Clarified docs. TWikibug:Item2698 Improved error reporting.
8808 TWikibug:Item1654 mailnotify must enter the command_line context
8625 TWikibug:Item1508 Making the dashes in the separatator clearer
8606 TWikibug:Item1508 MailerContrib: Brushing up HTML mailnotify template
8602 TWikibug:Item1508 MailerContrib: Cleaning up plaintext e-mail template, removing TEXTAREA
8522 TWikibug:Item1511 arguments to getScriptUrl in wrong order frown
8434 TWikibug:Item1465 Fix 'TWiki.' to '%TWIKIEB%.'
8398 TWikibug:Item1460 polished up the comment a bit
8308 TWikibug:Item1362 moving mailnotify cron script
7848 TWikibug:Item1167 forced all mail operations to generate absolute URLs
7568 TWikibug:tem910 use SCRIPTURL{view} instead of complex url expr
6864 TWikibug:tem624 mailer templates moved the the right places
6861 TWikibug:tem624 Added proper templates support for plain text mails
6809 TWikibug:tem623 don't print anything if verbosity is switched off.
6659 TWikibug:tem528 Updated MailerContrib. it's working and the sendmail parameter is used.
6474 TWikibug:tem420 removed spurious remove_obsolete_locks from MailerContrib
5924 TWikibug:tem153 fix mail URL-fixing scheme
5269 Minor doc fixes
5266 Doc tidy-ups, added filtering of _ webs, added obsolete lock script
5264 Changed default to add web name to user name (I hope)
5263 Minor doc tidyups
5261 Documentation changes, and fixed to scan all webs.
5253 runnable as CGI script, minor bugfixes, removed dependency on DBCacheContrib
5234 Minor doc changes
5231 Made a change an object, added unit tests to CVS, lots of testing.
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: http://TWiki.org/cgi-bin/view/Plugins/MailerContrib
Feedback: http://TWiki.org/cgi-bin/view/Plugins/MailerContribDev
Appraisal: http://TWiki.org/cgi-bin/view/Plugins/MailerContribAppraisal

Related Topics: TWikiPreferences

Revision 92010-07-09 - TWikiContributor

 

Mailer Contrib

<--
   Contributions to this TWiki extension are appreciated. Please update the page at
   http://twiki.org/cgi-bin/view/Plugins/MailerContrib or provide feedback at
   http://twiki.org/cgi-bin/view/Plugins/MailerContribDev.
   If you are a TWiki contributor please update the extension in the SVN repository.
-->
Changed:
<
<
>
>
  Send e-mail notification of changes to topics in TWiki webs

Introduction

The Mailer Contrib 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) lets you trivially add a "Subscribe to changes" button to topics

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.

<-- Included by WebChangesAlert -->

Users subscribe to email notifications using their WikiName or an alternative email address, and can specify the webs/topics they wish to track, Whole 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:

Added:
>
>
 
  • ... without a Web. prefix
  • ...that exist in this web.
Users may further customize the specific content they will receive using the following controls:
  • Using wild-card character in topic names - 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.
  • Unsubscribing to specific topics - 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.
  • Including child-topics in subscription - 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.
  • Subscribing to entire topic ("news mode") - Each topic may optionally be immediately followed by an exclamation mark ! and/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 full topic to be mailed every time even if there have been no changes, and ? will mail the full topic only if there have been changes. One can limit the content of the subscribed topic to send out by inserting %STARTPUBLISH% and %STOPPUBLISH% markers within the topic. Note that "news mode" subscriptions require a corresponding cron job that includes the "-news" option (see details).

Examples: 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 subscribers identified by email addresses. A subscriber identified by an email address alone will only be sent change notifications if the topic they are subscribed to is readable by guest users. You can limit what email addresses can be used in %NOTIFYTOPIC%, 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

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

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 mailnotify script from the command line, with no parameters. In this case it will print out what it would have done to STDOUT.
Additional settings
  • You can change the regular expression that matches email addresses in WebNotify using the {MailerContrib}{EmailFilterIn} 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)

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 subscriptions that include "!" or "?" following the topic)
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.

ALERT! Note: Multiple instances of mailnotify script are not allowed to be executed simultaneously. If you need to run the script multiple times with different options, make sure the cron jobs are scheduled so a previous run has finished before the next starts. You can also write a small script that runs mailnotify in sequence as described in TWiki:Support.DuplicateNotificationsFromMailerCon.

<-- 
  • Set STUB = TWiki::Contrib::Mailer
  • Set SHORTDESCRIPTION = Send e-mail notification of changes to topics in TWiki webs
-->

Developer Notes

The changes mails sent to subscribers 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

Many thanks to the following sponsors for supporting this work:

Author: TWiki:Main/CrawfordCurrie (http://c-dot.co.uk)
Copyright: © 2004, Wind River Systems;
© 2008, http://WikiRing.com
© 2004-2010 TWiki:TWiki/TWikiContributor
License: GPL (GNU General Public License)
Changed:
<
<
Version: 18799 (2010-05-29)
>
>
Version: 19212 (2011-04-11)
 
Change History:
<-- specify latest version first -->
 
Added:
>
>
2010-07-09: TWikibug:Item6518 - Fix for notification e-mail showing %MAKETEXT{"Web"} in subject
2010-06-12: TWikibug:Item6489 - Separate WIKITOOLNAME from WEB name; escape WEB name to avoid auto-linking in case web is WikiWord
 
2010-05-26: TWikibug:Item6474 - Fix for mailnotify failing due to non-existing _alert method
2010-05-21: TWikibug:Item6433 - more doc fixes
2010-04-25: TWikibug:Item6433 - doc fixes, no code changes
15 Oct 2008 TWikibug:Item: generalised code to enable TWiki:Codev.SubscribePlugin to delegate parsing to MailerContrib - TWiki:Main.SvenDowideit
14 Oct 2008 TWikibug:Item6066: fixed issue for user mappings where cuid = login - TWiki:Main.SvenDowideit
27 Aug 2008 TWikibug:Item5949: fixed problem with unsubscribe that should result in an empty subscription
03 Aug 2008 TWiki 4.2.1 release version
27 Jul 2008 TWikibug:Item5776: TWiki:Main.KennethLavrsen added note to warn against running multiple instances of mailnotify at the same time.
15 May 2008 TWikibug:Item5232: TWiki:Main.CrawfordCurrie added support for non-ascii alphanumerics in topic names to WebNotify. TWikibug:Item5630: TWiki:Main.SvenDowideit fixed some spelling errors
25 Jan 2008 TWikibug:Item4812: added TWiki:Main.BobGoldstein's noexpand patch for groups
2 Nov 2007 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
9 Sep 2007 TWikibug:Item4326 workaround for possible error in WebNotify API in old releases, Should not affect most users.
6 Sep 2007 TWikibug:Item4488 doc tweaks
14550 TWikibug:Item4461 - 'Changed' link now points to most recent changes, not the entire history
22 Jun 2007 TWikibug:Item4284 - added access control checks and email filter
21 May 2007 TWikibug:Item3969 - 8bit email fix (TWiki:Main.WillNorris)
13623 TWikibug:Item4014 no changes was resetting the notify time to 0. Thanks to TWiki:Main.JeffCrawford for nailing this down.
12496 TWikibug:Item3415 mailnotify did not send notifications to intranet users because of wrong call to findUser.
11672 Added newsletter support, after much harassment from TWiki:Main.LynnwoodBrown
11534 TWikibug:Item2153 Clarified docs. TWikibug:Item2698 Improved error reporting.
8808 TWikibug:Item1654 mailnotify must enter the command_line context
8625 TWikibug:Item1508 Making the dashes in the separatator clearer
8606 TWikibug:Item1508 MailerContrib: Brushing up HTML mailnotify template
8602 TWikibug:Item1508 MailerContrib: Cleaning up plaintext e-mail template, removing TEXTAREA
8522 TWikibug:Item1511 arguments to getScriptUrl in wrong order frown
8434 TWikibug:Item1465 Fix 'TWiki.' to '%TWIKIEB%.'
8398 TWikibug:Item1460 polished up the comment a bit
8308 TWikibug:Item1362 moving mailnotify cron script
7848 TWikibug:Item1167 forced all mail operations to generate absolute URLs
7568 TWikibug:tem910 use SCRIPTURL{view} instead of complex url expr
6864 TWikibug:tem624 mailer templates moved the the right places
6861 TWikibug:tem624 Added proper templates support for plain text mails
6809 TWikibug:tem623 don't print anything if verbosity is switched off.
6659 TWikibug:tem528 Updated MailerContrib. it's working and the sendmail parameter is used.
6474 TWikibug:tem420 removed spurious remove_obsolete_locks from MailerContrib
5924 TWikibug:tem153 fix mail URL-fixing scheme
5269 Minor doc fixes
5266 Doc tidy-ups, added filtering of _ webs, added obsolete lock script
5264 Changed default to add web name to user name (I hope)
5263 Minor doc tidyups
5261 Documentation changes, and fixed to scan all webs.
5253 runnable as CGI script, minor bugfixes, removed dependency on DBCacheContrib
5234 Minor doc changes
5231 Made a change an object, added unit tests to CVS, lots of testing.
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: http://TWiki.org/cgi-bin/view/Plugins/MailerContrib
Feedback: http://TWiki.org/cgi-bin/view/Plugins/MailerContribDev
Appraisal: http://TWiki.org/cgi-bin/view/Plugins/MailerContribAppraisal

Related Topics: TWikiPreferences

Revision 82010-05-26 - TWikiContributor

 

Mailer Contrib

Changed:
<
<
>
>
Send e-mail notification of changes to topics in TWiki webs
 
Changed:
<
<
Allows users to "subscribe" to regularly scheduled e-mails containing either:
>
>

Introduction

Added:
>
>
The Mailer Contrib 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) lets you trivially add a "Subscribe to changes" button to topics
Deleted:
<
<
<--

PLEASE DO NOT EDIT THIS TOPIC

It is automatically generated from the subversion repository, and any changes you make will simply be overwritten the next time a release is generated.

Instead, you could check your fix in, raise a bug in the Bugs web, or mail the author. -->

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

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.

Changed:
<
<
<-- Included by WebChangesAlert -->
>
>
<-- Included by WebChangesAlert -->
 
Changed:
<
<
Users subscribe to email notifications using their WikiName or an alternative email address, and can specify the webs/topics they wish to track, Whole groups of users can also be subscribed for notification.
>
>
Users subscribe to email notifications using their WikiName or an alternative email address, and can specify the webs/topics they wish to track, Whole groups of users can also be subscribed for notification.
  The general format of a subscription is:

three spaces * subscriber [ : topics ]

Changed:
<
<
Where subscriber can be a WikiName, an E-mail address, or a
>
>
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:
  • Using wild-card character in topic names - 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.
  • Unsubscribing to specific topics - 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.
  • Including child-topics in subscription - 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.
  • Subscribing to entire topic ("news mode") - Each topic may optionally be immediately followed by an exclamation mark ! and/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 full topic to be mailed every time even if there have been no changes, and ? will mail the full topic only if there have been changes. One can limit the content of the subscribed topic to send out by inserting %STARTPUBLISH% and %STOPPUBLISH% markers within the topic. Note that "news mode" subscriptions require a corresponding cron job that includes the "-news" option (see details).

Examples: 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.

Changed:
<
<
__ALERT! Warning: Because an email address is not linked to a user name, there is no way for TWiki to check access controls for subscribers identified by email addresses. A subscriber identified by an email address alone will only be sent change notifications if the topic they are subscribed to is readable by guest users. You can limit what email addresses can be used in %NOTIFYTOPIC%, or even block use of emails altogther, using the {MailerContrib}{EmailFilterIn} setting in =configure.
>
>
ALERT! Warning: Because an email address is not linked to a user name, there is no way for TWiki to check access controls for subscribers identified by email addresses. A subscriber identified by an email address alone will only be sent change notifications if the topic they are subscribed to is readable by guest users. You can limit what email addresses can be used in %NOTIFYTOPIC%, 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

Added:
>
>
 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

Added:
>
>
 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 mailnotify script from the command line, with no parameters. In this case it will print out what it would have done to STDOUT.
Additional settings
  • You can change the regular expression that matches email addresses in WebNotify using the {MailerContrib}{EmailFilterIn} 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)

Added:
>
>
 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 subscriptions that include "!" or "?" following the topic)
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.
Changed:
<
<
ALERT! Note: Multiple instances of mailnotify script are not allowed to be executed simutaneously. If you need to run the script multiple times with different options, make sure the cron jobs are scheduled so a previous run has finished before the next starts. You can also write a small script that runs mailnotify in sequence as described in TWiki:Support.DuplicateNotificationsFromMailerCon.
>
>
ALERT! Note: Multiple instances of mailnotify script are not allowed to be executed simultaneously. If you need to run the script multiple times with different options, make sure the cron jobs are scheduled so a previous run has finished before the next starts. You can also write a small script that runs mailnotify in sequence as described in TWiki:Support.DuplicateNotificationsFromMailerCon.
 
Added:
>
>
 

Developer Notes

Added:
>
>
 The changes mails sent to subscribers are based on a TWiki template called mailnotify. This template must contain the following definitions.
Added:
>
>
 
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.
Added:
>
>
 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

Deleted:
<
<
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)
Changed:
<
<
Copyright ©: 2004, Wind River Systems; 2006, http://WikiRing.com
License: GPL
Version: 17629 (14 Oct 2008)
Change History:  
14 Oct 2008 TWikibug:Item6066: fixed issue for user mappings where cuid = login
>
>
Copyright: © 2004, Wind River Systems;
© 2008, http://WikiRing.com
© 2004-2010 TWiki:TWiki/TWikiContributor
License: GPL (GNU General Public License)
Version: 18799 (2010-05-29)
Change History:
<-- specify latest version first -->
 
2010-05-26: TWikibug:Item6474 - Fix for mailnotify failing due to non-existing _alert method
Added:
>
>
2010-05-21: TWikibug:Item6433 - more doc fixes
2010-04-25: TWikibug:Item6433 - doc fixes, no code changes
15 Oct 2008 TWikibug:Item: generalised code to enable TWiki:Codev.SubscribePlugin to delegate parsing to MailerContrib - TWiki:Main.SvenDowideit
14 Oct 2008 TWikibug:Item6066: fixed issue for user mappings where cuid = login - TWiki:Main.SvenDowideit
 
27 Aug 2008 TWikibug:Item5949: fixed problem with unsubscribe that should result in an empty subscription
03 Aug 2008 TWiki 4.2.1 release version
27 Jul 2008 TWikibug:Item5776: TWiki:Main.KennethLavrsen added note to warn against running multiple instances of mailnotify at the same time.
15 May 2008 TWikibug:Item5232: TWiki:Main.CrawfordCurrie added support for non-ascii alphanumerics in topic names to WebNotify. TWikibug:Item5630: TWiki:Main.SvenDowideit fixed some spelling errors
25 Jan 2008 TWikibug:Item4812: added TWiki:Main.BobGoldstein's noexpand patch for groups
2 Nov 2007 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
9 Sep 2007 TWikibug:Item4326 workaround for possible error in WebNotify API in old releases, Should not affect most users.
6 Sep 2007 TWikibug:Item4488 doc tweaks
14550 TWikibug:Item4461 - 'Changed' link now points to most recent changes, not the entire history
22 Jun 2007 TWikibug:Item4284 - added access control checks and email filter
21 May 2007 TWikibug:Item3969 - 8bit email fix (TWiki:Main.WillNorris)
13623 TWikibug:Item4014 no changes was resetting the notify time to 0. Thanks to TWiki:Main.JeffCrawford for nailing this down.
12496 TWikibug:Item3415 mailnotify did not send notifications to intranet users because of wrong call to findUser.
11672 Added newsletter support, after much harassment from TWiki:Main.LynnwoodBrown
11534 TWikibug:Item2153 Clarified docs. TWikibug:Item2698 Improved error reporting.
8808 TWikibug:Item1654 mailnotify must enter the command_line context
8625 TWikibug:Item1508 Making the dashes in the separatator clearer
8606 TWikibug:Item1508 MailerContrib: Brushing up HTML mailnotify template
8602 TWikibug:Item1508 MailerContrib: Cleaning up plaintext e-mail template, removing TEXTAREA
8522 TWikibug:Item1511 arguments to getScriptUrl in wrong order frown
8434 TWikibug:Item1465 Fix 'TWiki.' to '%TWIKIEB%.'
8398 TWikibug:Item1460 polished up the comment a bit
8308 TWikibug:Item1362 moving mailnotify cron script
7848 TWikibug:Item1167 forced all mail operations to generate absolute URLs
7568 TWikibug:tem910 use SCRIPTURL{view} instead of complex url expr
6864 TWikibug:tem624 mailer templates moved the the right places
6861 TWikibug:tem624 Added proper templates support for plain text mails
6809 TWikibug:tem623 don't print anything if verbosity is switched off.
6659 TWikibug:tem528 Updated MailerContrib. it's working and the sendmail parameter is used.
6474 TWikibug:tem420 removed spurious remove_obsolete_locks from MailerContrib
5924 TWikibug:tem153 fix mail URL-fixing scheme
5269 Minor doc fixes
5266 Doc tidy-ups, added filtering of _ webs, added obsolete lock script
5264 Changed default to add web name to user name (I hope)
5263 Minor doc tidyups
5261 Documentation changes, and fixed to scan all webs.
5253 runnable as CGI script, minor bugfixes, removed dependency on DBCacheContrib
5234 Minor doc changes
5231 Made a change an object, added unit tests to CVS, lots of testing.
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
Changed:
<
<
Home: TWiki:Plugins/MailerContrib
Feedback: TWiki:Plugins/MailerContribDev
>
>
Home: http://TWiki.org/cgi-bin/view/Plugins/MailerContrib
Feedback: http://TWiki.org/cgi-bin/view/Plugins/MailerContribDev
 
Appraisal: http://TWiki.org/cgi-bin/view/Plugins/MailerContribAppraisal
Changed:
<
<
META FILEATTACHMENT attr="h" comment="" name="wikiringlogo20x20.png" version="1"
>
>
Related Topics: TWikiPreferences
Deleted:
<
<
META FILEATTACHMENT attr="h" comment="" name="logo.gif" version="1"
 

Revision 72008-12-06 - TWikiContributor

 

Mailer Contrib

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) lets you trivially add a "Subscribe to changes" button to topics

<--

PLEASE DO NOT EDIT THIS TOPIC

It is automatically generated from the subversion repository, and any changes you make will simply be overwritten the next time a release is generated.

Instead, you could check your fix in, raise a bug in the Bugs web, or mail the author. -->

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

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.

<-- Included by WebChangesAlert -->

Users subscribe to email notifications using their WikiName or an alternative email address, and can specify the webs/topics they wish to track, Whole 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:
  • Using wild-card character in topic names - 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.
  • Unsubscribing to specific topics - 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.
  • Including child-topics in subscription - 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.
Changed:
<
<
  • Subscribing to entire topic ("news mode") - 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. One can limit the content of the subscribed topic to send out by inserting %STARTPUBLISH% and %STOPPUBLISH% markers within the topic. Note that "news mode" subscriptions require a corresponding cron job that includes the "-news" option (see details).
>
>
  • Subscribing to entire topic ("news mode") - Each topic may optionally be immediately followed by an exclamation mark ! and/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 full topic to be mailed every time even if there have been no changes, and ? will mail the full topic only if there have been changes. One can limit the content of the subscribed topic to send out by inserting %STARTPUBLISH% and %STOPPUBLISH% markers within the topic. Note that "news mode" subscriptions require a corresponding cron job that includes the "-news" option (see details).
  Examples: 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.

Changed:
<
<
__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.
>
>
__ALERT! Warning: Because an email address is not linked to a user name, there is no way for TWiki to check access controls for subscribers identified by email addresses. A subscriber identified by an email address alone will only be sent change notifications if the topic they are subscribed to is readable by guest users. You can limit what email addresses can be used in %NOTIFYTOPIC%, 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

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

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 mailnotify script from the command line, with no parameters. In this case it will print out what it would have done to STDOUT.
Additional settings
  • You can change the regular expression that matches email addresses in WebNotify using the {MailerContrib}{EmailFilterIn} 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)

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 subscriptions that include "!" or "?" following the topic)
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.

ALERT! Note: Multiple instances of mailnotify script are not allowed to be executed simutaneously. If you need to run the script multiple times with different options, make sure the cron jobs are scheduled so a previous run has finished before the next starts. You can also write a small script that runs mailnotify in sequence as described in TWiki:Support.DuplicateNotificationsFromMailerCon.

<-- 
  • Set STUB = TWiki::Contrib::Mailer
  • Set SHORTDESCRIPTION = Supports e-mail notification of changes.
-->

Developer Notes

Changed:
<
<
The changes mails sent to users are based on a TWiki template called mailnotify. This template must contain the following definitions.
>
>
The changes mails sent to subscribers 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

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
Changed:
<
<
Version: 03 Aug 2008
>
>
Version: 17629 (14 Oct 2008)
 
Change History:  
Added:
>
>
14 Oct 2008 TWikibug:Item6066: fixed issue for user mappings where cuid = login
27 Aug 2008 TWikibug:Item5949: fixed problem with unsubscribe that should result in an empty subscription
 
03 Aug 2008 TWiki 4.2.1 release version
27 Jul 2008 TWikibug:Item5776: TWiki:Main.KennethLavrsen added note to warn against running multiple instances of mailnotify at the same time.
15 May 2008 TWikibug:Item5232: TWiki:Main.CrawfordCurrie added support for non-ascii alphanumerics in topic names to WebNotify. TWikibug:Item5630: TWiki:Main.SvenDowideit fixed some spelling errors
25 Jan 2008 TWikibug:Item4812: added TWiki:Main.BobGoldstein's noexpand patch for groups
2 Nov 2007 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
9 Sep 2007 TWikibug:Item4326 workaround for possible error in WebNotify API in old releases, Should not affect most users.
6 Sep 2007 TWikibug:Item4488 doc tweaks
14550 TWikibug:Item4461 - 'Changed' link now points to most recent changes, not the entire history
22 Jun 2007 TWikibug:Item4284 - added access control checks and email filter
21 May 2007 TWikibug:Item3969 - 8bit email fix (TWiki:Main.WillNorris)
13623 TWikibug:Item4014 no changes was resetting the notify time to 0. Thanks to TWiki:Main.JeffCrawford for nailing this down.
12496 TWikibug:Item3415 mailnotify did not send notifications to intranet users because of wrong call to findUser.
11672 Added newsletter support, after much harassment from TWiki:Main.LynnwoodBrown
11534 TWikibug:Item2153 Clarified docs. TWikibug:Item2698 Improved error reporting.
8808 TWikibug:Item1654 mailnotify must enter the command_line context
8625 TWikibug:Item1508 Making the dashes in the separatator clearer
8606 TWikibug:Item1508 MailerContrib: Brushing up HTML mailnotify template
8602 TWikibug:Item1508 MailerContrib: Cleaning up plaintext e-mail template, removing TEXTAREA
8522 TWikibug:Item1511 arguments to getScriptUrl in wrong order frown
8434 TWikibug:Item1465 Fix 'TWiki.' to '%TWIKIEB%.'
8398 TWikibug:Item1460 polished up the comment a bit
8308 TWikibug:Item1362 moving mailnotify cron script
7848 TWikibug:Item1167 forced all mail operations to generate absolute URLs
7568 TWikibug:tem910 use SCRIPTURL{view} instead of complex url expr
6864 TWikibug:tem624 mailer templates moved the the right places
6861 TWikibug:tem624 Added proper templates support for plain text mails
6809 TWikibug:tem623 don't print anything if verbosity is switched off.
6659 TWikibug:tem528 Updated MailerContrib. it's working and the sendmail parameter is used.
6474 TWikibug:tem420 removed spurious remove_obsolete_locks from MailerContrib
5924 TWikibug:tem153 fix mail URL-fixing scheme
5269 Minor doc fixes
5266 Doc tidy-ups, added filtering of _ webs, added obsolete lock script
5264 Changed default to add web name to user name (I hope)
5263 Minor doc tidyups
5261 Documentation changes, and fixed to scan all webs.
5253 runnable as CGI script, minor bugfixes, removed dependency on DBCacheContrib
5234 Minor doc changes
5231 Made a change an object, added unit tests to CVS, lots of testing.
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
Appraisal: http://TWiki.org/cgi-bin/view/Plugins/MailerContribAppraisal

META FILEATTACHMENT attr="h" comment="" name="wikiringlogo20x20.png" version="1"
META FILEATTACHMENT attr="h" comment="" name="logo.gif" version="1"

Revision 62008-08-03 - TWikiContributor

 

Mailer Contrib

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) lets you trivially add a "Subscribe to changes" button to topics

<--

PLEASE DO NOT EDIT THIS TOPIC

It is automatically generated from the subversion repository, and any changes you make will simply be overwritten the next time a release is generated.

Instead, you could check your fix in, raise a bug in the Bugs web, or mail the author. -->

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

Added:
>
>
 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
Changed:
<
<
  1. changes within the respective webs.
>
>
  1. 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.

<-- Included by WebChangesAlert -->
Changed:
<
<
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.
>
>
Users subscribe to email notifications using their WikiName or an alternative email address, and can specify the webs/topics they wish to track, Whole groups of users can also be subscribed for notification.
  The general format of a subscription is:

three spaces * subscriber [ : topics ]

Changed:
<
<
Where subscriber can be a WikiName, an E-mail address, or a
>
>
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:
Changed:
<
<
  • 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.
>
>
  • Using wild-card character in topic names - 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.
  • Unsubscribing to specific topics - 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.
  • Including child-topics in subscription - 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.
  • Subscribing to entire topic ("news mode") - 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. One can limit the content of the subscribed topic to send out by inserting %STARTPUBLISH% and %STOPPUBLISH% markers within the topic. Note that "news mode" subscriptions require a corresponding cron job that includes the "-news" option (see details).
 
Changed:
<
<
For example:
>
>
Examples:
 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

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

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 mailnotify script from the command line, with no parameters. In this case it will print out what it would have done to STDOUT.
Additional settings
  • You can change the regular expression that matches email addresses in WebNotify using the {MailerContrib}{EmailFilterIn} 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)

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
Changed:
<
<
-news Run in news mode (process NewsNotify instead of WebNotify)
>
>
-news Run in "news mode" (process subscriptions that include "!" or "?" following the topic)
 
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.
Added:
>
>
ALERT! Note: Multiple instances of mailnotify script are not allowed to be executed simutaneously. If you need to run the script multiple times with different options, make sure the cron jobs are scheduled so a previous run has finished before the next starts. You can also write a small script that runs mailnotify in sequence as described in TWiki:Support.DuplicateNotificationsFromMailerCon.
 
<-- 
  • Set STUB = TWiki::Contrib::Mailer
  • Set SHORTDESCRIPTION = Supports e-mail notification of changes.
-->

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

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
Changed:
<
<
Version: 16078 (22 Jan 2008)
>
>
Version: 03 Aug 2008
 
Change History:  
Changed:
<
<
2 Nov 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
9 Sep 2007 Bugs:Item4326 workaround for possible error in WebNotify API in old releases, Should not affect most users.
6 Sep 2007 Bugs:Item4488 doc tweaks
14550 Bugs:Item4461 - 'Changed' link now points to most recent changes, not the entire history
22 Jun 2007 Bugs:Item4284 - added access control checks and email filter
21 May 2007 Bugs:Item3969 - 8bit email fix (TWiki:Main.WillNorris)
13623 Bugs:Item4014 no changes was resetting the notify time to 0. Thanks to TWiki:Main.JeffCrawford for nailing this down.
12496 Item3415 mailnotify did not send notifications to intranet users because of wrong call to findUser.
>
>
03 Aug 2008 TWiki 4.2.1 release version
27 Jul 2008 TWikibug:Item5776: TWiki:Main.KennethLavrsen added note to warn against running multiple instances of mailnotify at the same time.
15 May 2008 TWikibug:Item5232: TWiki:Main.CrawfordCurrie added support for non-ascii alphanumerics in topic names to WebNotify. TWikibug:Item5630: TWiki:Main.SvenDowideit fixed some spelling errors
25 Jan 2008 TWikibug:Item4812: added TWiki:Main.BobGoldstein's noexpand patch for groups
2 Nov 2007 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
9 Sep 2007 TWikibug:Item4326 workaround for possible error in WebNotify API in old releases, Should not affect most users.
6 Sep 2007 TWikibug:Item4488 doc tweaks
14550 TWikibug:Item4461 - 'Changed' link now points to most recent changes, not the entire history
Added:
>
>
22 Jun 2007 TWikibug:Item4284 - added access control checks and email filter
21 May 2007 TWikibug:Item3969 - 8bit email fix (TWiki:Main.WillNorris)
13623 TWikibug:Item4014 no changes was resetting the notify time to 0. Thanks to TWiki:Main.JeffCrawford for nailing this down.
12496 TWikibug:Item3415 mailnotify did not send notifications to intranet users because of wrong call to findUser.
 
11672 Added newsletter support, after much harassment from TWiki:Main.LynnwoodBrown
Changed:
<
<
11534 Item2153 Clarified docs. Item2698 Improved error reporting.
8808 Item1654 mailnotify must enter the command_line context
8625 Item1508 Making the dashes in the separatator clearer
8606 Item1508 MailerContrib: Brushing up HTML mailnotify template
8602 Item1508 MailerContrib: Cleaning up plaintext e-mail template, removing TEXTAREA
8522 Item1511 arguments to getScriptUrl in wrong order frown
8434 Item1465 Fix 'TWiki.' to '%TWIKIEB%.'
8398 Item1460 polished up the comment a bit
8308 Item1362 moving mailnotify cron script
7848 Item1167 forced all mail operations to generate absolute URLs
7568 Item910 use SCRIPTURL{view} instead of complex url expr
6864 Item624 mailer templates moved the the right places
6861 Item624 Added proper templates support for plain text mails
6809 Item623 don't print anything if verbosity is switched off.
6659 Item528 Updated MailerContrib. it's working and the sendmail parameter is used.
6474 Item420 removed spurious remove_obsolete_locks from MailerContrib
5924 Item153 fix mail URL-fixing scheme
>
>
11534 TWikibug:Item2153 Clarified docs. TWikibug:Item2698 Improved error reporting.
8808 TWikibug:Item1654 mailnotify must enter the command_line context
8625 TWikibug:Item1508 Making the dashes in the separatator clearer
8606 TWikibug:Item1508 MailerContrib: Brushing up HTML mailnotify template
8602 TWikibug:Item1508 MailerContrib: Cleaning up plaintext e-mail template, removing TEXTAREA
8522 TWikibug:Item1511 arguments to getScriptUrl in wrong order frown
8434 TWikibug:Item1465 Fix 'TWiki.' to '%TWIKIEB%.'
8398 TWikibug:Item1460 polished up the comment a bit
8308 TWikibug:Item1362 moving mailnotify cron script
7848 TWikibug:Item1167 forced all mail operations to generate absolute URLs
7568 TWikibug:tem910 use SCRIPTURL{view} instead of complex url expr
6864 TWikibug:tem624 mailer templates moved the the right places
6861 TWikibug:tem624 Added proper templates support for plain text mails
6809 TWikibug:tem623 don't print anything if verbosity is switched off.
6659 TWikibug:tem528 Updated MailerContrib. it's working and the sendmail parameter is used.
6474 TWikibug:tem420 removed spurious remove_obsolete_locks from MailerContrib
5924 TWikibug:tem153 fix mail URL-fixing scheme
 
5269 Minor doc fixes
5266 Doc tidy-ups, added filtering of _ webs, added obsolete lock script
5264 Changed default to add web name to user name (I hope)
5263 Minor doc tidyups
5261 Documentation changes, and fixed to scan all webs.
5253 runnable as CGI script, minor bugfixes, removed dependency on DBCacheContrib
5234 Minor doc changes
5231 Made a change an object, added unit tests to CVS, lots of testing.
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
Appraisal: http://TWiki.org/cgi-bin/view/Plugins/MailerContribAppraisal

META FILEATTACHMENT attr="h" comment="" name="wikiringlogo20x20.png" version="1"
META FILEATTACHMENT attr="h" comment="" name="logo.gif" version="1"

Revision 52008-01-22 - TWikiContributor

Changed:
<
<

MailerContrib

>
>
 
Changed:
<
<
Add-on to the TWiki kernel that allows users to "subscribe" to regularly scheduled e-mails containing either:
>
>
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."
Added:
>
>
 
<--

PLEASE DO NOT EDIT THIS TOPIC

It is automatically generated from the subversion repository, and any changes you make will simply be overwritten the next time a release is generated.

Instead, you could check your fix in, raise a bug in the Bugs web, or mail the author. -->

Changed:
<
<
WARNING: TWiki-4 only. If you want to use this extension with an earlier version of TWiki, please see here
>
>
WARNING: TWiki-4 only. If you want to use this extension with an earlier version of TWiki, please use revision 17 of the zip.
 
Changed:
<
<

tools/mailnotify

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

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.

<-- Included by WebChangesAlert -->
Changed:
<
<
Users subscribe to email notifications using their WikiName or an alternative email address, and can specify the webs/topics they wish to track using one of these bullet list formats:
>
>
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.
 
Changed:
<
<
three spaces * [ webname . ] wikiName - SMTP mail address
>
>
The general format of a subscription is:
Deleted:
<
<
three spaces * [ webName . ] wikiName
three spaces * SMTP mail address
three spaces * SMTP mail address : topics
three spaces * [ webname . ] wikiName : topics
 
Changed:
<
<
In the above examples, topics is a space-separated list of topic names. The user may further customize the specific content they will receive using the following formats:
  • Specify topics without a Web. prefix
  • Topics must exist in this web.
  • Topics may be specified using * wildcards
  • 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 "unsubscribe" or "don't send notifications regarding this topic". This allows users to elect to filter out certain topics (and their children, to an arbitrary depth). Topic filters ('-') take precedence over topic includes ('+').
>
>
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.

Added:
>
>
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.
Changed:
<
<
  • 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, ? will mail the topic only if there have been changes to it. This only makes sense for subscriptions.
>
>
  • 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
Changed:
<
<
Subscribe Daisy to all changes in all webs that start with Web.
>
>
Subscribe Daisy to all changes to topics that start with Web.
 
Changed:
<
<
>
>
  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
Added:
>
>
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).
Changed:
<
<
If a TWiki group is listed for notification, the group will be recursively expanded to the e-mail addresses of all members.
>
>
If a group is listed for notification, the group will be recursively expanded to the e-mail addresses of all members.
 
Added:
>
>
__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.

Changed:
<
<
Note mailnotify ignores permissions in webs. It is entirely possible for a user to get added to one of the subscription topics in a web, when they are not authorised to view the topics in that web. This could result in them having access to sensitive information, particularly with news mode.
>
>
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.
 
Changed:
<
<
Note that when using the "news mode" ! or ? specifiers are used 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.
 
Changed:
<
<
In addition, the %STARTPUBLISH% and %STOPPUBLISH% markers used by TWiki:Plugins.PublishContrib to delimit the text to be published are respected.
>
>

TWiki/Contrib/MailerContrib code library

Added:
>
>
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.
 
Changed:
<
<

TWiki/Contrib/MailerContrib code library

>
>

Installation Instructions

Deleted:
<
<
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. The main interface is the WebNotify package described below.

package TWiki::Contrib::MailerContrib::WebNotify

Object that represents the contents of a WebNotify topic in a TWiki web

ClassMethod new($web, $topic)

Create a new object by parsing the content of the given topic in the given web. This is the normal way to load a WebNotify topic. If the topic does not exist, it will create an empty object.

ObjectMethod writeWebNotify()

Write the object to the WebNotify 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.

ObjectMethod 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.

ObjectMethod getSubscribers()

Get a list of all subscriber names (unsorted)

ObjectMethod 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)
  • $mode - ! if this is a non-changes subscription and the topics should be mailed evebn if there are no changes. ? to mail the full topic only if there are changes. undef to mail changes only.
Add a subscription, adding the subscriber if necessary.

ObjectMethod 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.

ObjectMethod stringify() -> string

Return a string representation of this object, in WebNotify format.

ObjectMethod processChange($change, $db, $changeSet, $seenSet, $allSet)

  • $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
  • $allSet - ref of a hash that maps topics to email addresses for news subscriptions
Find all subscribers that are interested in the given change. Only the most recent change to each topic listed in the .changes file is retained. This method does not change this object.

ObjectMethod processCompulsory($topic, $db, \%allSet)

  • $topic - topic name
  • $db - TWiki::Contrib::MailerContrib::UpData database of parent references
  • \%allSet - ref of a hash that maps topics to email addresses for news subscriptions

ObjectMethod 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.

ClassMethod new($name)

  • $name - Wikiname, with no web, or email address, of user targeted for notification
Create a new user.

ObjectMethod getEmailAddresses() -> list

Get a list of email addresses for the user(s) represented by this subscription

ObjectMethod 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.

ObjectMethod 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.

ObjectMethod isSubscribedTo($topic) -> $subscription

  • $topic - Topic object we are checking
  • $db - TWiki::Contrib::MailerContrib::UpData database of parents
Check if we have a subscription to the given topic. Return the subscription that matches if we do, undef otherwise.

ObjectMethod isUnsubscribedFrom($topic) -> $subscription

  • $topic - Topic object we are checking
  • $db - TWiki::Contrib::MailerContrib::UpData database of parents
Check if we have an unsubscription from the given topic. Return the subscription that matches if we do, undef otherwise.

ObjectMethod stringify() -> string

Return a string representation of this object, in WebNotify 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.

ClassMethod new($pages, $childDepth, $news)

  • $pages - Wildcarded expression matching subscribed pages
  • $childDepth - Depth of children of $topic to notify changes for. Defaults to 0
  • $mode - ! if this is a non-changes subscription and the topics should be mailed evebn if there are no changes. ? to mail the full topic only if there are changes. undef to mail changes only.
Create a new subscription.

ObjectMethod stringify() -> string

Return a string representation of this object, in WebNotify format.

ObjectMethod 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.

ObjectMethod getMode() -> $mode

Return ! if this is a non-changes subscription and the topics should be mailed even if there are no changes. ? to mail the full topic only if there are changes. undef to mail changes only.


package TWiki::Contrib::MailerContrib::Change

Object that represents a change to a topic.

ClassMethod new($web)

  • $web - Web name
  • $topic - Topic name
  • $author - String author of change
  • $time - String time of change
  • $rev - Revision identifier
Construct a new change object.

ObjectMethod merge($change)

  • $change - Change record to merge
Merge another change record with this one, so that the combined record is a reflection of both changes.

ObjectMethod expandHTML($html) -> string

  • $html - Template to expand keys within
Expand an HTML template using the values in this change. The following keys are expanded: %TOPICNAME%, %AUTHOR%, %TIME%, %REVISION%, %TEXTHEAD%.

Returns the expanded template.

ObjectMethod expandPlain() -> string

Generate a plaintext version of this change.

package TWiki::Contrib::MailerContrib::UpData

Object that lazy-scans topics to extract parent relationships.

ClassMethod new($web)

  • $web - Web we are building parent relationships for
Constructor for a web; initially empty, will lazy-load as topics are referenced.

ObjectMethod getParent($topic) -> string

Get the name of the parent topic of the given topic

package TWiki::Contrib::Mailer

Package of support for extended WebNotify notification, supporting per-topic notification and notification of changes to children.

Also supported is a simple API that can be used to change the WebNotify topic from other code.

StaticMethod mailNotify($webs, $session, $verbose)

  • $webs - filter list of names webs to process. Wildcards (*) may be used.
  • $session - optional session object. If not given, will use a local object.
  • $verbose - true to get verbose (debug) output

Main entry point.

Process the WebNotify 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.

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.
Changed:
<
<
Like many other TWiki extensions, this module is shipped with a fully automatic installer script written using the BuildContrib.
  • If you have TWiki 4.1 or later, and Perl 5.8, you can install from the configure interface (Go to Plugins->Find More Extensions)
    • The webserver user has to have permission to write to all areas of your installation for this to work.
  • If you have a permanent connection to the internet (and Perl 5.8), you are recommended to use the automatic installer script
    • Just download the MailerContrib_installer perl script and run it.
  • Notes:
    • The installer script will:
      • Automatically resolve dependencies,
      • Copy files into the right places in your local install (even if you have renamed data directories),
      • check in new versions of any installed files that have existing RCS histories files in your existing install (such as topics).
      • If the $TWIKI_PACKAGES environment variable is set to point to a directory, the installer will try to get archives from there. Otherwise it will try to download from twiki.org or cpan.org, as appropriate.
      • (Developers only: the script will look for twikiplugins/MailerContrib/MailerContrib.tgz before downloading from TWiki.org)
>
>
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.
Deleted:
<
<
    • If you don't have a permanent connection, you can still use the automatic installer, by downloading all required TWiki archives to a local directory.
      • Point the environment variable $TWIKI_PACKAGES to this directory, and the installer script will look there first for required TWiki packages.
        • $TWIKI_PACKAGES is actually a path; you can list several directories separated by :
      • If you are behind a firewall that blocks access to CPAN, you can build a local CPAN mini-mirror, as described at http://twiki.org/cgi-bin/view/Codev/BuildingDakar#CPAN_local_minimirror
  • If you don't want to use the installer script, or have problems on your platform (e.g. you don't have Perl 5.8), then you can still install manually:
    1. Download and unpack one of the .zip or .tgz archives to a temporary directory.
    2. Manually copy the contents across to the relevant places in your TWiki installation.
 
    1. 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)
    2. Manually edit LocalSite.cfg to set any configuration variables.
Deleted:
<
<
    1. Run configure and enable the module, if it is a plugin.
    2. Repeat from step 1 for any missing dependencies.
 
Changed:
<
<
  • To make sure the installation was successful, run the mailnotify script from the command line, with no parameters. In this case it will print out what it would have done to STDOUT.
>
>
 
Changed:
<
<

Setting up your cron job(s)

You need to set up a cron (or equivalent) job to run tools/mailnotify.
>
>
  • To make sure the installation was successful, run the mailnotify script from the command line, with no parameters. In this case it will print out what it would have done to STDOUT.
Additional settings
Added:
>
>
  • You can change the regular expression that matches email addresses in WebNotify using the {MailerContrib}{EmailFilterIn} setting in =configure. This allows you to limit the domains to which emails can be sent, or even block email addresses altogether.
 
Changed:
<
<
Usage: perl -I <bin> mailnotify [-q] [-news] [ web1 web2 ... webN ] <bin> is the path to the TWiki bin directory, so that the script can find the rest of TWiki.
>
>

Setting up your cron job(s)

You need to set up a cron (or equivalent) job to run the tools/mailnotify perl script.
Added:
>
>
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)
Changed:
<
<
web1 web2 ... webN List of webs to process, separated by spaces or commas. Default is to process all legal TWiki webs. Wildcards (*) are supported.
>
>
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
Changed:
<
<
will generate change notifications for the Public and Private webs every night at midnight.
>
>
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)
 
Added:
>
>
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.

<-- 
  • Set STUB = TWiki::Contrib::Mailer
  • Set SHORTDESCRIPTION = Supports e-mail notification of changes.
-->
Changed:
<
<

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.

Changed:
<
<

Contrib Info

>
>

Contrib Info

 
Added:
>
>
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
Added:
>
>
Version: 16078 (22 Jan 2008)
 
Change History:  
Added:
>
>
2 Nov 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
9 Sep 2007 Bugs:Item4326 workaround for possible error in WebNotify API in old releases, Should not affect most users.
6 Sep 2007 Bugs:Item4488 doc tweaks
14550 Bugs:Item4461 - 'Changed' link now points to most recent changes, not the entire history
22 Jun 2007 Bugs:Item4284 - added access control checks and email filter
21 May 2007 Bugs:Item3969 - 8bit email fix (TWiki:Main.WillNorris)
13623 Bugs:Item4014 no changes was resetting the notify time to 0. Thanks to TWiki:Main.JeffCrawford for nailing this down.
 
12496 Item3415 mailnotify did not send notifications to intranet users because of wrong call to findUser.
11672 Added newsletter support, after much harassment from TWiki:Main.LynnwoodBrown
11534 Item2153 Clarified docs. Item2698 Improved error reporting.
8808 Item1654 mailnotify must enter the command_line context
8625 Item1508 Making the dashes in the separatator clearer
8606 Item1508 MailerContrib: Brushing up HTML mailnotify template
8602 Item1508 MailerContrib: Cleaning up plaintext e-mail template, removing TEXTAREA
8522 Item1511 arguments to getScriptUrl in wrong order frown
8434 Item1465 Fix 'TWiki.' to '%TWIKIEB%.'
8398 Item1460 polished up the comment a bit
8308 Item1362 moving mailnotify cron script
7848 Item1167 forced all mail operations to generate absolute URLs
7568 Item910 use SCRIPTURL{view} instead of complex url expr
6864 Item624 mailer templates moved the the right places
6861 Item624 Added proper templates support for plain text mails
6809 Item623 don't print anything if verbosity is switched off.
6659 Item528 Updated MailerContrib. it's working and the sendmail parameter is used.
6474 Item420 removed spurious remove_obsolete_locks from MailerContrib
5924 Item153 fix mail URL-fixing scheme
5269 Minor doc fixes
5266 Doc tidy-ups, added filtering of _ webs, added obsolete lock script
5264 Changed default to add web name to user name (I hope)
5263 Minor doc tidyups
5261 Documentation changes, and fixed to scan all webs.
5253 runnable as CGI script, minor bugfixes, removed dependency on DBCacheContrib
5234 Minor doc changes
5231 Made a change an object, added unit tests to CVS, lots of testing.
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
Appraisal: http://TWiki.org/cgi-bin/view/Plugins/MailerContribAppraisal
Changed:
<
<
>
>
META FILEATTACHMENT attr="h" comment="" name="wikiringlogo20x20.png" version="1"
Added:
>
>
META FILEATTACHMENT attr="h" comment="" name="logo.gif" version="1"
 

Revision 42007-01-10 - TWikiAdminGroup

 

MailerContrib

Changed:
<
<
Add-on to the TWiki kernel that supports e-mail notification of changes.
>
>
Add-on to the TWiki kernel that allows users to "subscribe" to regularly scheduled e-mails containing either:
Added:
>
>
  • 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."
 
<--

PLEASE DO NOT EDIT THIS TOPIC

It is automatically generated from the subversion repository, and any changes you make will simply be overwritten the next time a release is generated.

Instead, you could check your fix in, raise a bug in the Bugs web, or mail the author. -->

WARNING: TWiki-4 only. If you want to use this extension with an earlier version of TWiki, please see here

Changed:
<
<

Summary of Contents

tools/mailnotify

The main part of the mailer module is a script, tools/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 or a cron job.
>
>

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
Added:
>
>
  1. 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.
 
Added:
>
>
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.

 
<-- Included by WebChangesAlert -->
Changed:
<
<
Subscribers are listed in WebNotify following one of these bullet list formats:
>
>
Users subscribe to email notifications using their WikiName or an alternative email address, and can specify the webs/topics they wish to track using one of these bullet list 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
Changed:
<
<
where topics is a space-separated list of topic names.
>
>
In the above examples, topics is a space-separated list of topic names. The user may further customize the specific content they will receive using the following formats:
 
  • Specify topics without a Web. prefix
  • Topics must exist in this web.
  • Topics may be specified using * wildcards
Added:
>
>
  • 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 "unsubscribe" or "don't send notifications regarding this topic". This allows users to elect to filter out certain topics (and their children, to an arbitrary depth). Topic filters ('-') take precedence over topic includes ('+').
 
  • 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.
Changed:
<
<
  • 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 ('+').
>
>
  • 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, ? will mail the topic only if there have been changes to it. This only makes sense for subscriptions.
  For example:
Added:
>
>
Subscribe Daisy to all changes to topics in this web.
 
Changed:
<
<
>
>
Deleted:
<
<
 
Changed:
<
<
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.
>
>
Subscribe Daisy to all changes in all webs that start with Web.
Added:
>
>
   * 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
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 TWiki group is listed for notification, the group will be recursively expanded to the e-mail addresses of all members.

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.

Changed:
<
<
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).
>
>
Note mailnotify ignores permissions in webs. It is entirely possible for a user to get added to one of the subscription topics in a web, when they are not authorised to view the topics in that web. This could result in them having access to sensitive information, particularly with news mode.
 
Changed:
<
<

TWiki/Contrib/MailerContrib code library

>
>
Note that when using the "news mode" ! or ? specifiers are used 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.
Deleted:
<
<
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.
 
Changed:
<
<

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.
>
>
In addition, the %STARTPUBLISH% and %STOPPUBLISH% markers used by TWiki:Plugins.PublishContrib to delimit the text to be published are respected.

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. The main interface is the WebNotify package described below.
Added:
>
>

package TWiki::Contrib::MailerContrib::WebNotify

Object that represents the contents of a WebNotify topic in a TWiki web

ClassMethod new($web, $topic)

Create a new object by parsing the content of the given topic in the given web. This is the normal way to load a WebNotify topic. If the topic does not exist, it will create an empty object.

ObjectMethod writeWebNotify()

Write the object to the WebNotify 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.

ObjectMethod 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.

ObjectMethod getSubscribers()

Get a list of all subscriber names (unsorted)

ObjectMethod 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)
  • $mode - ! if this is a non-changes subscription and the topics should be mailed evebn if there are no changes. ? to mail the full topic only if there are changes. undef to mail changes only.
Add a subscription, adding the subscriber if necessary.

ObjectMethod 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.

ObjectMethod stringify() -> string

Return a string representation of this object, in WebNotify format.

ObjectMethod processChange($change, $db, $changeSet, $seenSet, $allSet)

  • $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
  • $allSet - ref of a hash that maps topics to email addresses for news subscriptions
Find all subscribers that are interested in the given change. Only the most recent change to each topic listed in the .changes file is retained. This method does not change this object.

ObjectMethod processCompulsory($topic, $db, \%allSet)

  • $topic - topic name
  • $db - TWiki::Contrib::MailerContrib::UpData database of parent references
  • \%allSet - ref of a hash that maps topics to email addresses for news subscriptions

ObjectMethod 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.

ClassMethod new($name)

  • $name - Wikiname, with no web, or email address, of user targeted for notification
Create a new user.

ObjectMethod getEmailAddresses() -> list

Get a list of email addresses for the user(s) represented by this subscription

ObjectMethod 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.

ObjectMethod 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.

ObjectMethod isSubscribedTo($topic) -> $subscription

  • $topic - Topic object we are checking
  • $db - TWiki::Contrib::MailerContrib::UpData database of parents
Check if we have a subscription to the given topic. Return the subscription that matches if we do, undef otherwise.

ObjectMethod isUnsubscribedFrom($topic) -> $subscription

  • $topic - Topic object we are checking
  • $db - TWiki::Contrib::MailerContrib::UpData database of parents
Check if we have an unsubscription from the given topic. Return the subscription that matches if we do, undef otherwise.

ObjectMethod stringify() -> string

Return a string representation of this object, in WebNotify 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.

ClassMethod new($pages, $childDepth, $news)

  • $pages - Wildcarded expression matching subscribed pages
  • $childDepth - Depth of children of $topic to notify changes for. Defaults to 0
  • $mode - ! if this is a non-changes subscription and the topics should be mailed evebn if there are no changes. ? to mail the full topic only if there are changes. undef to mail changes only.
Create a new subscription.

ObjectMethod stringify() -> string

Return a string representation of this object, in WebNotify format.

ObjectMethod 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.

ObjectMethod getMode() -> $mode

Return ! if this is a non-changes subscription and the topics should be mailed even if there are no changes. ? to mail the full topic only if there are changes. undef to mail changes only.


package TWiki::Contrib::MailerContrib::Change

Object that represents a change to a topic.

ClassMethod new($web)

  • $web - Web name
  • $topic - Topic name
  • $author - String author of change
  • $time - String time of change
  • $rev - Revision identifier
Construct a new change object.

ObjectMethod merge($change)

  • $change - Change record to merge
Merge another change record with this one, so that the combined record is a reflection of both changes.

ObjectMethod expandHTML($html) -> string

  • $html - Template to expand keys within
Expand an HTML template using the values in this change. The following keys are expanded: %TOPICNAME%, %AUTHOR%, %TIME%, %REVISION%, %TEXTHEAD%.

Returns the expanded template.

ObjectMethod expandPlain() -> string

Generate a plaintext version of this change.

package TWiki::Contrib::MailerContrib::UpData

Object that lazy-scans topics to extract parent relationships.

ClassMethod new($web)

  • $web - Web we are building parent relationships for
Constructor for a web; initially empty, will lazy-load as topics are referenced.

ObjectMethod getParent($topic) -> string

Get the name of the parent topic of the given topic

package TWiki::Contrib::Mailer

Package of support for extended WebNotify notification, supporting per-topic notification and notification of changes to children.

Also supported is a simple API that can be used to change the WebNotify topic from other code.

StaticMethod mailNotify($webs, $session, $verbose)

  • $webs - filter list of names webs to process. Wildcards (*) may be used.
  • $session - optional session object. If not given, will use a local object.
  • $verbose - true to get verbose (debug) output

Main entry point.

Process the WebNotify 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.

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.1 or later, and Perl 5.8, you can install from the configure interface (Go to Plugins->Find More Extensions)
    • The webserver user has to have permission to write to all areas of your installation for this to work.
  • If you have a permanent connection to the internet (and Perl 5.8), you are recommended to use the automatic installer script
    • Just download the MailerContrib_installer perl script and run it.
  • Notes:
    • The installer script will:
      • Automatically resolve dependencies,
      • Copy files into the right places in your local install (even if you have renamed data directories),
      • check in new versions of any installed files that have existing RCS histories files in your existing install (such as topics).
      • If the $TWIKI_PACKAGES environment variable is set to point to a directory, the installer will try to get archives from there. Otherwise it will try to download from twiki.org or cpan.org, as appropriate.
      • (Developers only: the script will look for twikiplugins/MailerContrib/MailerContrib.tgz before downloading from TWiki.org)
    • If you don't have a permanent connection, you can still use the automatic installer, by downloading all required TWiki archives to a local directory.
      • Point the environment variable $TWIKI_PACKAGES to this directory, and the installer script will look there first for required TWiki packages.
        • $TWIKI_PACKAGES is actually a path; you can list several directories separated by :
      • If you are behind a firewall that blocks access to CPAN, you can build a local CPAN mini-mirror, as described at http://twiki.org/cgi-bin/view/Codev/BuildingDakar#CPAN_local_minimirror
  • If you don't want to use the installer script, or have problems on your platform (e.g. you don't have Perl 5.8), then you can still install manually:
    1. Download and unpack one of the .zip or .tgz archives to a temporary directory.
    2. Manually copy the contents across to the relevant places in your TWiki installation.
    3. 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)
    4. Manually edit LocalSite.cfg to set any configuration variables.
    5. Run configure and enable the module, if it is a plugin.
    6. Repeat from step 1 for any missing dependencies.
 
  • To make sure the installation was successful, run the mailnotify script from the command line, with no parameters. In this case it will print out what it would have done to STDOUT.
Changed:
<
<

Setting up your cron job

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

Setting up your cron job(s)

You need to set up a cron (or equivalent) job to run tools/mailnotify.
 
Changed:
<
<
Usage: perl -I <bin> mailnotify [-q] [ web1 web2 ... webN ] <bin> is the path to the TWiki bin directory (usually ../bin), so that the script can find the rest of TWiki.
>
>
Usage: perl -I <bin> mailnotify [-q] [-news] [ web1 web2 ... webN ] <bin> is the path to the TWiki bin directory, so that the script can find the rest of TWiki.
 
-q Don't print progress information
Added:
>
>
-news Run in news mode (process NewsNotify instead of WebNotify)
 
web1 web2 ... webN List of webs to process, separated by spaces or commas. Default is to process all legal TWiki webs. Wildcards (*) are supported.
Changed:
<
<
For example, perl -I /usr/local/twiki/bin mailnotify -q Public Private will generate notifications for the Public and Private webs.
>
>
For example, assuming TWiki was installed at /usr/local/twiki, this cron entry:
Added:
>
>
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.
0 0 * * 0 cd /usr/local/twiki && perl -I bin tools/mailnotify -news
will generate newsletters from all webs every week on midnight Saturday.
 
Changed:
<
<

Settings

>
>

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.
 
Added:
>
>
Newsletters are sent after formatting using the standard view template, using whatever skin is selected in the topic being mailed.
 

Contrib Info

Author: TWiki:Main/CrawfordCurrie (http://c-dot.co.uk)
Changed:
<
<
Copyright ©: 2004, Wind River Systems
>
>
Copyright ©: 2004, Wind River Systems; 2006, http://WikiRing.com
 
License: GPL
Changed:
<
<
Change History:  
8808 Item1654 mailnotify must enter the command_line context
8625 Item1508 Making the dashes in the separatator clearer
8606 Item1508 MailerContrib: Brushing up HTML mailnotify template
8602 Item1508 MailerContrib: Cleaning up plaintext e-mail template, removing TEXTAREA
8522 Item1511 arguments to getScriptUrl in wrong order frown
8434 Item1465 Fix 'TWiki.' to '%TWIKIEB%.'
8398 Item1460 polished up the comment a bit
8308 Item1362 moving mailnotify cron script
7848 Item1167 forced all mail operations to generate absolute URLs
7568 Item910 use SCRIPTURL{view} instead of complex url expr
6864 Item624 mailer templates moved the the right places
6861 Item624 Added proper templates support for plain text mails
6809 Item623 don't print anything if verbosity is switched off.
6659 Item528 Updated MailerContrib. it's working and the sendmail parameter is used.
6474 Item420 removed spurious remove_obsolete_locks from MailerContrib
5924 Item153 fix mail URL-fixing scheme
5269 Minor doc fixes
5266 Doc tidy-ups, added filtering of _ webs, added obsolete lock script
5264 Changed default to add web name to user name (I hope)
5263 Minor doc tidyups
5261 Documentation changes, and fixed to scan all webs.
5253 runnable as CGI script, minor bugfixes, removed dependency on DBCacheContrib
5234 Minor doc changes
5231 Made a change an object, added unit tests to CVS, lots of testing.
>
>
Change History:  
12496 Item3415 mailnotify did not send notifications to intranet users because of wrong call to findUser.
11672 Added newsletter support, after much harassment from TWiki:Main.LynnwoodBrown
11534 Item2153 Clarified docs. Item2698 Improved error reporting.
8808 Item1654 mailnotify must enter the command_line context
8625 Item1508 Making the dashes in the separatator clearer
8606 Item1508 MailerContrib: Brushing up HTML mailnotify template
8602 Item1508 MailerContrib: Cleaning up plaintext e-mail template, removing TEXTAREA
8522 Item1511 arguments to getScriptUrl in wrong order frown
8434 Item1465 Fix 'TWiki.' to '%TWIKIEB%.'
8398 Item1460 polished up the comment a bit
8308 Item1362 moving mailnotify cron script
7848 Item1167 forced all mail operations to generate absolute URLs
7568 Item910 use SCRIPTURL{view} instead of complex url expr
6864 Item624 mailer templates moved the the right places
6861 Item624 Added proper templates support for plain text mails
6809 Item623 don't print anything if verbosity is switched off.
6659 Item528 Updated MailerContrib. it's working and the sendmail parameter is used.
6474 Item420 removed spurious remove_obsolete_locks from MailerContrib
5924 Item153 fix mail URL-fixing scheme
5269 Minor doc fixes
5266 Doc tidy-ups, added filtering of _ webs, added obsolete lock script
5264 Changed default to add web name to user name (I hope)
5263 Minor doc tidyups
5261 Documentation changes, and fixed to scan all webs.
Added:
>
>
5253 runnable as CGI script, minor bugfixes, removed dependency on DBCacheContrib
5234 Minor doc changes
5231 Made a change an object, added unit tests to CVS, lots of testing.
 
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
Appraisal: http://TWiki.org/cgi-bin/view/Plugins/MailerContribAppraisal

Revision 32006-06-25 - TWikiContributor

Added:
>
>
Add-on to the TWiki kernel that supports e-mail notification of changes.
 
Deleted:
<
<
This module is an add-on to the TWiki kernel that supports e-mail notification of changes.
 
Added:
>
>
 WARNING: TWiki-4 only. If you want to use this extension with an earlier version of TWiki, please see here

Changed:
<
<

Summary of Contents

tools/mailnotify

>
>

Summary of Contents

tools/mailnotify

 The main part of the mailer module is a script, tools/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 or a cron job.

<-- Included by WebChangesAlert -->

Subscribers are listed in WebNotify following one of these bullet list 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 e-mail addresses of all members.

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 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).

Changed:
<
<

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 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.
Changed:
<
<

Installation Instructions

>
>

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 mailnotify script from the command line, with no parameters. In this case it will print out what it would have done to STDOUT.
Changed:
<
<

Setting up your cron job

>
>

Setting up your cron job

 You need to set up a cron (or equivalent) job to run mailnotify.
Changed:
<
<
Usage: perl -I tools/mailnotify [-q] [ web1 web2 ... webN ] is the path to the TWiki bin directory, so that the script can find the rest of TWiki.
>
>
Usage: perl -I <bin> mailnotify [-q] [ web1 web2 ... webN ] <bin> is the path to the TWiki bin directory (usually ../bin), so that the script can find the rest of TWiki.
 
-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.
For example, perl -I /usr/local/twiki/bin mailnotify -q Public Private will generate notifications for the Public and Private webs.
Changed:
<
<

Settings

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

Settings

  • Set STUB = TWiki::Contrib::Mailer
  • Set SHORTDESCRIPTION = Supports e-mail notification of changes.
 
Changed:
<
<

Contrib Info

>
>

Contrib Info

 
Author: TWiki:Main/CrawfordCurrie (http://c-dot.co.uk)
Copyright ©: 2004, Wind River Systems
License: GPL
Change History:  
8808 Item1654 mailnotify must enter the command_line context
8625 Item1508 Making the dashes in the separatator clearer
8606 Item1508 MailerContrib: Brushing up HTML mailnotify template
8602 Item1508 MailerContrib: Cleaning up plaintext e-mail template, removing TEXTAREA
8522 Item1511 arguments to getScriptUrl in wrong order frown
8434 Item1465 Fix 'TWiki.' to '%TWIKIEB%.'
8398 Item1460 polished up the comment a bit
8308 Item1362 moving mailnotify cron script
7848 Item1167 forced all mail operations to generate absolute URLs
7568 Item910 use SCRIPTURL{view} instead of complex url expr
6864 Item624 mailer templates moved the the right places
6861 Item624 Added proper templates support for plain text mails
6809 Item623 don't print anything if verbosity is switched off.
6659 Item528 Updated MailerContrib. it's working and the sendmail parameter is used.
6474 Item420 removed spurious remove_obsolete_locks from MailerContrib
5924 Item153 fix mail URL-fixing scheme
5269 Minor doc fixes
5266 Doc tidy-ups, added filtering of _ webs, added obsolete lock script
5264 Changed default to add web name to user name (I hope)
5263 Minor doc tidyups
5261 Documentation changes, and fixed to scan all webs.
5253 runnable as CGI script, minor bugfixes, removed dependency on DBCacheContrib
5234 Minor doc changes
5231 Made a change an object, added unit tests to CVS, lots of testing.
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
Added:
>
>
Appraisal: http://TWiki.org/cgi-bin/view/Plugins/MailerContribAppraisal
 
Deleted:
<
<
Related Topics: TWikiPreferences
 
Deleted:
<
<
-- TWiki:Main/CrawfordCurrie
 

Revision 22005-03-27 - TWikiContributor

Added:
>
>
 This module is an add-on to the TWiki kernel that supports e-mail notification of changes.
Added:
>
>
WARNING: TWiki-4 only. If you want to use this extension with an earlier version of TWiki, please see here
 

Summary of Contents

tools/mailnotify

The main part of the mailer module is a script, tools/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 or a cron job.

<-- Included by WebChangesAlert -->

Subscribers are listed in WebNotify following one of these bullet list 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.

Changed:
<
<
  • 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 ('+').
>
>
  • 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:
Changed:
<
<
>
>
  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 e-mail addresses of all members.

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

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.
Changed:
<
<
  • 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 mailnotify script from the command line, with no parameters. In this case it will print out what it would have done to STDOUT.
>
>
  • 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 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 mailnotify.

Usage: perl -I tools/mailnotify [-q] [ web1 web2 ... webN ] is the path to the TWiki bin directory, so that the script can find the rest of TWiki.

-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.
For example, perl -I /usr/local/twiki/bin mailnotify -q Public Private will generate notifications for the Public and Private webs.

Settings

Changed:
<
<
  • Name of the perl package
    • Set STUB = TWiki::Contrib::Mailer
>
>
  • 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
Changed:
<
<
Change History:
<-- versions below in reverse order -->
 
>
>
Change History:  
Added:
>
>
8808 Item1654 mailnotify must enter the command_line context
8625 Item1508 Making the dashes in the separatator clearer
8606 Item1508 MailerContrib: Brushing up HTML mailnotify template
8602 Item1508 MailerContrib: Cleaning up plaintext e-mail template, removing TEXTAREA
8522 Item1511 arguments to getScriptUrl in wrong order frown
8434 Item1465 Fix 'TWiki.' to '%TWIKIEB%.'
8398 Item1460 polished up the comment a bit
8308 Item1362 moving mailnotify cron script
7848 Item1167 forced all mail operations to generate absolute URLs
7568 Item910 use SCRIPTURL{view} instead of complex url expr
6864 Item624 mailer templates moved the the right places
6861 Item624 Added proper templates support for plain text mails
6809 Item623 don't print anything if verbosity is switched off.
6659 Item528 Updated MailerContrib. it's working and the sendmail parameter is used.
6474 Item420 removed spurious remove_obsolete_locks from MailerContrib
5924 Item153 fix mail URL-fixing scheme
5269 Minor doc fixes
5266 Doc tidy-ups, added filtering of _ webs, added obsolete lock script
5264 Changed default to add web name to user name (I hope)
5263 Minor doc tidyups
5261 Documentation changes, and fixed to scan all webs.
5253 runnable as CGI script, minor bugfixes, removed dependency on DBCacheContrib
5234 Minor doc changes
5231 Made a change an object, added unit tests to CVS, lots of testing.
 
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

Revision 12005-03-27 - TWikiContributor

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

Summary of Contents

tools/mailnotify

The main part of the mailer module is a script, tools/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 or a cron job.

<-- Included by WebChangesAlert -->

Subscribers are listed in WebNotify following one of these bullet list 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 e-mail addresses of all members.

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

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

Usage: perl -I tools/mailnotify [-q] [ web1 web2 ... webN ] is the path to the TWiki bin directory, so that the script can find the rest of TWiki.

-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.
For example, perl -I /usr/local/twiki/bin mailnotify -q Public Private will generate notifications for the Public and Private webs.

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:
<-- versions below in reverse order -->
 
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

 
This site is powered by the TWiki collaboration platform Powered by PerlCopyright © 1999-2024 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback
Note: Please contribute updates to this topic on TWiki.org at TWiki:TWiki.MailerContrib.