TWiki/MailerContrib.mdwn

   1 # <a name="Mailer Contrib"></a><a name=" Mailer Contrib"></a> Mailer Contrib
   2
   3 [![](http://www.dementia.org/twiki//view/logo.gif)](http://wikiring.com)
   4
   5 Allows users to "subscribe" to regularly scheduled e-mails containing either:
   6
   7 - A report on changes to all topics that have changed within a particular TWiki web.
   8 - A report on changes to a specific topic or set of topics the user can define flexibly.
   9 - The entire content of a specific topic or set of topics. This is referred to as "news mode."
  10 - The companion plugin (TWiki:Plugins.SubscribePlugin) lets you trivially add a "Subscribe to changes" button to topics
  11
  12 <div>WARNING: TWiki-4 only. If you want to use this extension with an earlier version of TWiki, please use <a href="http://twiki.org/cgi-bin/attach/Plugins/%TOPIC%?filename=%TOPIC%.zip&revInfo=1" target="_top">revision 17 of the zip</a>.</div>
  13
  14 <div>
  15   <ul>
  16     <li><a href="#tools/mailnotify"> tools/mailnotify</a></li>
  17     <li><a href="#TWiki/Contrib/_MailerContrib cod"> TWiki/Contrib/MailerContrib code library</a></li>
  18     <li><a href="#Installation Instructions"> Installation Instructions</a><ul>
  19         <li><a href="#Setting up your cron job(s)"> Setting up your cron job(s)</a></li>
  20       </ul>
  21     </li>
  22     <li><a href="#Developer Notes"> Developer Notes</a><ul>
  23         <li><a href="#Contrib Info"> Contrib Info</a></li>
  24       </ul>
  25     </li>
  26   </ul>
  27 </div>
  28
  29 ## <a name="tools/mailnotify"></a> tools/mailnotify
  30
  31 The central component of MailerContrib is a script, `tools/mailnotify`, that generates and sends out the emails based on analysis of
  32
  33 1. users' subcriptions listed in the WebNotify topic in each web, and
  34 2. changes within the respective webs.
  35
  36 This script is designed to be run from `cron` (or an equivalent off-line job scheduler), or from the command-line.
  37
  38 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.
  39
  40 Each web can optionally contain a topic called WebNotify.
  41
  42 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.
  43
  44 The general format of a subscription is:
  45
  46 _three spaces_ `*` _subscriber_ [ `:` _topics_ ]
  47
  48 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.
  49
  50 _topics_ is an optional space-separated list of topics:
  51
  52 - ... **without** a _Web._ prefix
  53 - ...that exist in this web.
  54
  55 Users may further customize the specific content they will receive using the following controls:
  56
  57 - **Using wild-card character in topic names** - You can use `*` in a topic name, where it is treated as a [wildcard character](http://en.wikipedia.org/wiki/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.
  58 - **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.
  59 - **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.
  60 - **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|Main/TOPIC#Setting_up_your_cron_job_s]]).
  61
  62 Examples: Subscribe Daisy to all changes to topics in this web.
  63
  64        * daisy.cutter@flowers.com
  65
  66 Subscribe Daisy to all changes to topics that start with `Web`.
  67
  68        * daisy.cutter@flowers.com : Web*
  69
  70 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`
  71
  72        * DaisyCutter: Petal* (1) WeedKillers (3) Pretty*Flowers
  73
  74 Subscribe StarTrekFan to changes to all topics that start with `Star` **except** those that end in `Wars`, `sInTheirEyes` or `shipTroopers`.
  75
  76        * StarTrekFan: Star* - *Wars - *sInTheirEyes - *shipTroopers
  77
  78 Subscribe Daisy to the full content of NewsLetter whenever it has changed
  79
  80        * daisy@flowers.com: NewsLetter?
  81
  82 Subscribe buttercup to NewsLetter and its immediate children, even if it hasn't changed.
  83
  84        * buttercup@flowers.com: NewsLetter! (1)
  85
  86 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]]:
  87
  88        * GardenGroup: AllNewsLetters? (3)
  89        * petunia@flowers.com: - ManureNewsLetter
  90
  91 Subscribe `IT:admins` (a non-TWiki group defined by an alternate user mapping) to all changes to Web\* topics.
  92
  93        * 'IT:admins' : Web*
  94
  95 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).
  96
  97 If a _group_ is listed for notification, the group will be recursively expanded to the e-mail addresses of all members.
  98
  99 \_\_%X% 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`.
 100
 101 **_%T% Tip:_** List names in alphabetical order to make it easier to find the names.
 102
 103 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.
 104
 105 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.
 106
 107 In addition, the %STARTPUBLISH% and %STOPPUBLISH% markers used by TWiki:Plugins.PublishContrib to delimit the text to be published are respected in news mode.
 108
 109 ## <a name="TWiki/Contrib/_MailerContrib cod"></a> TWiki/Contrib/MailerContrib code library
 110
 111 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.
 112
 113 ## <a name="Installation Instructions"></a> Installation Instructions
 114
 115 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.
 116
 117 Like many other TWiki extensions, this module is shipped with a fully automatic installer script written using the BuildContrib.
 118
 119 - If you have TWiki 4.2 or later, you can install from the `configure` interface (Go to Plugins-&gt;Find More Extensions)
 120   - See the [installation supplement](http://twiki.org/cgi-bin/view/Plugins/BuildContribInstallationSupplement) on TWiki.org for more information.
 121 - If you have any problems, then you can still install manually from the command-line:
 122   1. Download one of the `.zip` or `.tgz` archives
 123   2. Unpack the archive in the root directory of your TWiki installation.
 124   3. Run the installer script ( `perl <module>_installer` )
 125   4. Run `configure` and enable the module, if it is a plugin.
 126   5. Repeat for any missing dependencies.
 127 - If you are **still** having problems, then instead of running the installer script:
 128   1. Make sure that the file permissions allow the webserver user to access all files.
 129   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)
 130   3. Manually edit LocalSite.cfg to set any configuration variables.
 131
 132 <div class="twikiAlert">%X% WARNING: SYSTEMWEB is not defined in this TWiki. Please add these definitions to your [[Main/TWikiPreferences]], if they are not already there:<br /><pre>   * Set SYSTEMWEB = %TWIKIWEB%<br />   * Set USERSWEB = %MAINWEB%</pre></div>
 133
 134 - 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`.
 135
 136 **Additional settings**
 137
 138 - 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.
 139
 140 ### <a name="Setting up your cron job(s)"></a> Setting up your cron job(s)
 141
 142 You need to set up a `cron` (or equivalent) job to run the `tools/mailnotify` perl script.
 143
 144 The script is used as follows: <code>perl -I _bin_ mailnotify [-q] [-news] [ _web1 web2 ... webN_ ]</code>
 145
 146 <table border="1" cellpadding="0" cellspacing="0">
 147   <tr>
 148     <td><em>bin</em></td>
 149     <td> path to the TWiki bin directory, so that the script can find the rest of TWiki. </td>
 150   </tr>
 151   <tr>
 152     <td><code>-q</code></td>
 153     <td> Don't print progress information </td>
 154   </tr>
 155   <tr>
 156     <td><code>-news</code></td>
 157     <td> Run in "news mode" (process subscriptions that include "!" or "?" following the topic) </td>
 158   </tr>
 159   <tr>
 160     <td><code><i>web1 web2 ... webN</i></code></td>
 161     <td> List of webs to process, separated by spaces or commas. The default is to process all webs. Wildcards (*) are supported. </td>
 162   </tr>
 163 </table>
 164
 165 For example, assuming TWiki was installed at `/usr/local/twiki`, this cron entry:
 166
 167     0 0 * * * cd /usr/local/twiki && perl -I bin tools/mailnotify -q Public Private
 168
 169 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)
 170
 171     0 0 * * * cd /usr/local/twiki && perl -I bin tools/mailnotify -q -Sandbox
 172
 173 will generate change notifications for all webs, except the `Sandbox` web.
 174
 175     0 0 * * 0 cd /usr/local/twiki && perl -I bin tools/mailnotify -news
 176
 177 will generate newsletters from **all** webs every week on midnight Saturday.
 178
 179 %X% 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.
 180
 181 ## <a name="Developer Notes"></a> Developer Notes
 182
 183 The changes mails sent to subscribers are based on a TWiki template called `mailnotify`. This template must contain the following definitions.
 184
 185 <table border="1" cellpadding="0" cellspacing="0">
 186   <tr>
 187     <td><code>HTML:before</code></td>
 188     <td> Section of a HTML mail before the changes </td>
 189   </tr>
 190   <tr>
 191     <td><code>HTML:middle</code></td>
 192     <td> Repeated in a HTML mail for each change </td>
 193   </tr>
 194   <tr>
 195     <td><code>HTML:after</code></td>
 196     <td> Section of a HTML mail after the changes </td>
 197   </tr>
 198   <tr>
 199     <td><code>PLAIN:before</code></td>
 200     <td> Section of a plain text mail before the changes </td>
 201   </tr>
 202   <tr>
 203     <td><code>PLAIN:middle</code></td>
 204     <td> Repeated in a plain text mail for each changes </td>
 205   </tr>
 206   <tr>
 207     <td><code>PLAIN:after</code></td>
 208     <td> Section of a plain text mail after the changes </td>
 209   </tr>
 210   <tr>
 211     <td><code>MailNotifyBody</code></td>
 212     <td> All the above are embedded in this. %HTML_TEXT% expands to the HTML obtained by expanding the <code>HTML:*</code> templates, and %PLAIN_TEXT% from the <code>PLAIN:*</code> templates. </td>
 213   </tr>
 214 </table>
 215
 216 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.
 217
 218 Newsletters are sent after formatting using the standard `view` template, using whatever skin is selected in the topic being mailed.
 219
 220 ### <a name="Contrib Info"></a> Contrib Info
 221
 222 Another great TWiki extension from the [![](http://www.dementia.org/twiki//view/wikiring.png) **WikiRing** ](http://wikiring.com) - working together to improve your wiki experience!
 223
 224 Many thanks to the following sponsors for supporting this work:
 225
 226 - [Wind River](http://www.windriver.com)
 227 - [WikiGardens](http://wikigardens.com)
 228
 229 <table border="1" cellpadding="0" cellspacing="0">
 230   <tr>
 231     <td align="right"> Author: </td>
 232     <td> TWiki:Main/CrawfordCurrie (<a href="http://c-dot.co.uk" target="_top">http://c-dot.co.uk</a>) </td>
 233   </tr>
 234   <tr>
 235     <td align="right"> Copyright ©: </td>
 236     <td> 2004, Wind River Systems; 2006, <a href="http://WikiRing.com" target="_top">http://WikiRing.com</a></td>
 237   </tr>
 238   <tr>
 239     <td align="right"> License: </td>
 240     <td> GPL </td>
 241   </tr>
 242   <tr>
 243     <td align="right"> Version: </td>
 244     <td> 17629 (14 Oct 2008) </td>
 245   </tr>
 246   <tr>
 247     <td align="right"> Change History: </td>
 248     <td>   </td>
 249   </tr>
 250   <tr>
 251     <td align="right"> 14 Oct 2008 </td>
 252     <td> TWikibug:Item6066: fixed issue for user mappings where cuid = login </td>
 253   </tr>
 254   <tr>
 255     <td align="right"> 27 Aug 2008 </td>
 256     <td> TWikibug:Item5949: fixed problem with unsubscribe that should result in an empty subscription </td>
 257   </tr>
 258   <tr>
 259     <td align="right"> 03 Aug 2008 </td>
 260     <td> TWiki 4.2.1 release version </td>
 261   </tr>
 262   <tr>
 263     <td align="right"> 27 Jul 2008 </td>
 264     <td> TWikibug:Item5776: TWiki:Main.KennethLavrsen added note to warn against running multiple instances of mailnotify at the same time. </td>
 265   </tr>
 266   <tr>
 267     <td align="right"> 15 May 2008 </td>
 268     <td> TWikibug:Item5232: TWiki:Main.CrawfordCurrie added support for non-ascii alphanumerics in topic names to [[Main/WebNotify]]. TWikibug:Item5630: TWiki:Main.SvenDowideit fixed some spelling errors </td>
 269   </tr>
 270   <tr>
 271     <td align="right"> 25 Jan 2008 </td>
 272     <td> TWikibug:Item4812: added TWiki:Main.BobGoldstein's noexpand patch for groups </td>
 273   </tr>
 274   <tr>
 275     <td align="right"> 2 Nov 2007 </td>
 276     <td> 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 </td>
 277   </tr>
 278   <tr>
 279     <td align="right"> 9 Sep 2007 </td>
 280     <td> TWikibug:Item4326 workaround for possible error in WebNotify API in old releases, Should not affect most users. </td>
 281   </tr>
 282   <tr>
 283     <td align="right"> 6 Sep 2007 </td>
 284     <td> TWikibug:Item4488 doc tweaks </td>
 285   </tr>
 286   <tr>
 287     <td align="right"> 14550 </td>
 288     <td> TWikibug:Item4461 - 'Changed' link now points to most recent changes, not the entire history </td>
 289   </tr>
 290   <tr>
 291     <td align="right"> 22 Jun 2007 </td>
 292     <td> TWikibug:Item4284 - added access control checks and email filter </td>
 293   </tr>
 294   <tr>
 295     <td align="right"> 21 May 2007 </td>
 296     <td> TWikibug:Item3969 - 8bit email fix (TWiki:Main.WillNorris) </td>
 297   </tr>
 298   <tr>
 299     <td align="right"> 13623 </td>
 300     <td> TWikibug:Item4014 no changes was resetting the notify time to 0. Thanks to TWiki:Main.JeffCrawford for nailing this down. </td>
 301   </tr>
 302   <tr>
 303     <td align="right"> 12496 </td>
 304     <td> TWikibug:Item3415 mailnotify did not send notifications to intranet users because of wrong call to findUser. </td>
 305   </tr>
 306   <tr>
 307     <td align="right"> 11672 </td>
 308     <td> Added newsletter support, after much harassment from TWiki:Main.LynnwoodBrown </td>
 309   </tr>
 310   <tr>
 311     <td align="right"> 11534 </td>
 312     <td> TWikibug:Item2153 Clarified docs. TWikibug:Item2698 Improved error reporting. </td>
 313   </tr>
 314   <tr>
 315     <td align="right"> 8808 </td>
 316     <td> TWikibug:Item1654 mailnotify must enter the command_line context </td>
 317   </tr>
 318   <tr>
 319     <td align="right"> 8625 </td>
 320     <td> TWikibug:Item1508 Making the dashes in the separatator clearer </td>
 321   </tr>
 322   <tr>
 323     <td align="right"> 8606 </td>
 324     <td> TWikibug:Item1508 [[Main/MailerContrib]]: Brushing up HTML mailnotify template </td>
 325   </tr>
 326   <tr>
 327     <td align="right"> 8602 </td>
 328     <td> TWikibug:Item1508 [[Main/MailerContrib]]: Cleaning up plaintext e-mail template, removing TEXTAREA </td>
 329   </tr>
 330   <tr>
 331     <td align="right"> 8522 </td>
 332     <td> TWikibug:Item1511 arguments to getScriptUrl in wrong order :-( </td>
 333   </tr>
 334   <tr>
 335     <td align="right"> 8434 </td>
 336     <td> TWikibug:Item1465 Fix 'TWiki.' to '%TWIKIEB%.' </td>
 337   </tr>
 338   <tr>
 339     <td align="right"> 8398 </td>
 340     <td> TWikibug:Item1460 polished up the comment a bit </td>
 341   </tr>
 342   <tr>
 343     <td align="right"> 8308 </td>
 344     <td> TWikibug:Item1362 moving mailnotify cron script </td>
 345   </tr>
 346   <tr>
 347     <td align="right"> 7848 </td>
 348     <td> TWikibug:Item1167 forced all mail operations to generate absolute URLs </td>
 349   </tr>
 350   <tr>
 351     <td align="right"> 7568 </td>
 352     <td> TWikibug:tem910 use SCRIPTURL{view} instead of complex url expr </td>
 353   </tr>
 354   <tr>
 355     <td align="right"> 6864 </td>
 356     <td> TWikibug:tem624 mailer templates moved the the right places </td>
 357   </tr>
 358   <tr>
 359     <td align="right"> 6861 </td>
 360     <td> TWikibug:tem624 Added proper templates support for plain text mails </td>
 361   </tr>
 362   <tr>
 363     <td align="right"> 6809 </td>
 364     <td> TWikibug:tem623 don't print anything if verbosity is switched off. </td>
 365   </tr>
 366   <tr>
 367     <td align="right"> 6659 </td>
 368     <td> TWikibug:tem528 Updated [[Main/MailerContrib]]. it's working and the sendmail parameter is used. </td>
 369   </tr>
 370   <tr>
 371     <td align="right"> 6474 </td>
 372     <td> TWikibug:tem420 removed spurious remove_obsolete_locks from [[Main/MailerContrib]]</td>
 373   </tr>
 374   <tr>
 375     <td align="right"> 5924 </td>
 376     <td> TWikibug:tem153 fix mail URL-fixing scheme </td>
 377   </tr>
 378   <tr>
 379     <td align="right"> 5269 </td>
 380     <td> Minor doc fixes </td>
 381   </tr>
 382   <tr>
 383     <td align="right"> 5266 </td>
 384     <td> Doc tidy-ups, added filtering of _ webs, added obsolete lock script </td>
 385   </tr>
 386   <tr>
 387     <td align="right"> 5264 </td>
 388     <td> Changed default to add web name to user name (I hope) </td>
 389   </tr>
 390   <tr>
 391     <td align="right"> 5263 </td>
 392     <td> Minor doc tidyups </td>
 393   </tr>
 394   <tr>
 395     <td align="right"> 5261 </td>
 396     <td> Documentation changes, and fixed to scan all webs. </td>
 397   </tr>
 398   <tr>
 399     <td align="right"> 5253 </td>
 400     <td> runnable as CGI script, minor bugfixes, removed dependency on [[Main/DBCacheContrib]]</td>
 401   </tr>
 402   <tr>
 403     <td align="right"> 5234 </td>
 404     <td> Minor doc changes </td>
 405   </tr>
 406   <tr>
 407     <td align="right"> 5231 </td>
 408     <td> Made a change an object, added unit tests to CVS, lots of testing. </td>
 409   </tr>
 410   <tr>
 411     <td align="right"> 4 March 2005 </td>
 412     <td> 1.010 Dakar release ready. </td>
 413   </tr>
 414   <tr>
 415     <td align="right"> 12 Oct 2004 </td>
 416     <td> 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) </td>
 417   </tr>
 418   <tr>
 419     <td align="right"> 6 Oct 2004 </td>
 420     <td> 1.003 Excluded _ webs from processing, added <code>bin/remove_obsolete_locks</code> for full reverse-compatibility </td>
 421   </tr>
 422   <tr>
 423     <td align="right"> 1 Oct 2004 </td>
 424     <td> 1.002 PeterThoeny provided additional documentation </td>
 425   </tr>
 426   <tr>
 427     <td align="right"> 27 Sep 2004 </td>
 428     <td> 1.001 runnable as CGI script, minor bugfixes, removed dependency on DBCacheContrib </td>
 429   </tr>
 430   <tr>
 431     <td align="right"> 8 Sep 2004 </td>
 432     <td> 1.000 Initial version </td>
 433   </tr>
 434   <tr>
 435     <td align="right"> Home: </td>
 436     <td> TWiki:Plugins/%TOPIC% </td>
 437   </tr>
 438   <tr>
 439     <td align="right"> Feedback: </td>
 440     <td> TWiki:Plugins/%TOPIC%Dev </td>
 441   </tr>
 442   <tr>
 443     <td align="right"> Appraisal: </td>
 444     <td><a href="http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Appraisal" target="_top">http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Appraisal</a></td>
 445   </tr>
 446 </table>