TWiki/MailerContrib.mdwn

   1 This module is an add-on to the TWiki kernel that supports e-mail notification of changes.
   2
   3 **WARNING: TWiki-4 only. If you want to use this extension with an earlier version of TWiki, please see [here](http://twiki.org/cgi-bin/view/Plugins/%TOPIC%?rev=1.17)**
   4
   5 <div>
   6   <ul>
   7     <li><a href="#Summary of Contents"> Summary of Contents</a><ul>
   8         <li><a href="#tools/mailnotify"> <code>tools/mailnotify</code></a></li>
   9         <li><a href="#TWiki/Contrib/_MailerContrib cod"> <code>TWiki/Contrib/MailerContrib</code> code library</a></li>
  10       </ul>
  11     </li>
  12     <li><a href="#Installation Instructions"> Installation Instructions</a></li>
  13     <li><a href="#Setting up your cron job"> Setting up your cron job</a></li>
  14     <li><a href="#Settings"> Settings</a></li>
  15     <li><a href="#Contrib Info"> Contrib Info</a></li>
  16   </ul>
  17 </div>
  18
  19 # <a name="Summary of Contents"></a> Summary of Contents
  20
  21 ## <a name="tools/mailnotify"></a> `tools/mailnotify`
  22
  23 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.
  24
  25 Subscribers are listed in WebNotify following one of these bullet list formats:
  26
  27 _three spaces_ \* [ _webname_ . ] _wikiName_ - _SMTP mail address_<br />_three spaces_ \* [ _webName_ . ] _wikiName_<br />_three spaces_ \* _SMTP mail address_<br />_three spaces_ \* _SMTP mail address_ : _topics_<br />_three spaces_ \* [ _webname_ . ] _wikiName_ : _topics_
  28
  29 where _topics_ is a space-separated list of topic names.
  30
  31 - Specify topics without a _Web._ prefix
  32 - Topics must exist in this web.
  33 - Topics may be specified using \* wildcards
  34 - 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.
  35 - 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 ('+').
  36
  37 For example:
  38
  39        * daisy@flowers.com
  40        * daisy@flowers.com: Web*
  41        * DaisyCutter: Petal* (1) WeedKillers (3) Red*Phlox
  42        * StarTrekFan: * - *Wars - *sInTheirEyes - *shipTroopers
  43
  44 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_.
  45
  46 If a _TWiki group_ is listed for notification, the group will be recursively expanded to the e-mail addresses of all members.
  47
  48 **_%T% Tip:_** List names in alphabetical order to make it easier to find the names.
  49
  50 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.
  51
  52 %RED% **_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). %ENDCOLOR%
  53
  54 ## <a name="TWiki/Contrib/_MailerContrib cod"></a> `TWiki/Contrib/MailerContrib` code library
  55
  56 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.
  57
  58 # <a name="Installation Instructions"></a> Installation Instructions
  59
  60 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.
  61
  62 - Download the ZIP file from the Plugin web (see below)
  63 - Unzip <code>**%TOPIC%.zip**</code> in your twiki installation directory.
  64 - Run the installer script `MailContrib_intaller.pl` or alternatively resolve all dependencies manually.
  65 - 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.
  66
  67 # <a name="Setting up your cron job"></a> Setting up your cron job
  68
  69 You need to set up a `cron` (or equivalent) job to run `mailnotify`.
  70
  71 <code>Usage: perl -I  tools/mailnotify [-q] [ _web1 web2 ... webN_ ]</code>  is the path to the TWiki bin directory, so that the script can find the rest of TWiki.
  72
  73 <table border="1" cellpadding="0" cellspacing="0">
  74   <tr>
  75     <td><code>-q</code></td>
  76     <td> Don't print progress information </td>
  77   </tr>
  78   <tr>
  79     <td><code><i>web1 web2 ... webN</i></code></td>
  80     <td> List of webs to process, separated by spaces or commas. Default is to process all legal TWiki webs. Wildcards (*) are supported. </td>
  81   </tr>
  82 </table>
  83
  84 For example, `perl -I /usr/local/twiki/bin mailnotify -q Public Private` will generate notifications for the Public and Private webs.
  85
  86 # <a name="Settings"></a> Settings
  87
  88 - Name of the perl package
  89   - Set STUB = TWiki::Contrib::Mailer
  90
  91 # <a name="Contrib Info"></a> Contrib Info
  92
  93 <table border="1" cellpadding="0" cellspacing="0">
  94   <tr>
  95     <td align="right"> Author: </td>
  96     <td> TWiki:Main/CrawfordCurrie (<a href="http://c-dot.co.uk" target="_top">http://c-dot.co.uk</a>) </td>
  97   </tr>
  98   <tr>
  99     <td align="right"> Copyright ©: </td>
 100     <td> 2004, Wind River Systems </td>
 101   </tr>
 102   <tr>
 103     <td align="right"> License: </td>
 104     <td> GPL </td>
 105   </tr>
 106   <tr>
 107     <td> Change History: </td>
 108     <td>   </td>
 109   </tr>
 110   <tr>
 111     <td> 8808 </td>
 112     <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1654" rel="nofollow">Item1654</a> mailnotify must enter the command_line context </td>
 113   </tr>
 114   <tr>
 115     <td> 8625 </td>
 116     <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1508" rel="nofollow">Item1508</a> Making the dashes in the separatator clearer </td>
 117   </tr>
 118   <tr>
 119     <td> 8606 </td>
 120     <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1508" rel="nofollow">Item1508</a> [[Main/MailerContrib]]: Brushing up HTML mailnotify template </td>
 121   </tr>
 122   <tr>
 123     <td> 8602 </td>
 124     <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1508" rel="nofollow">Item1508</a> [[Main/MailerContrib]]: Cleaning up plaintext e-mail template, removing TEXTAREA </td>
 125   </tr>
 126   <tr>
 127     <td> 8522 </td>
 128     <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1511" rel="nofollow">Item1511</a> arguments to getScriptUrl in wrong order :-( </td>
 129   </tr>
 130   <tr>
 131     <td> 8434 </td>
 132     <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1465" rel="nofollow">Item1465</a> Fix 'TWiki.' to '%TWIKIEB%.' </td>
 133   </tr>
 134   <tr>
 135     <td> 8398 </td>
 136     <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1460" rel="nofollow">Item1460</a> polished up the comment a bit </td>
 137   </tr>
 138   <tr>
 139     <td> 8308 </td>
 140     <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1362" rel="nofollow">Item1362</a> moving mailnotify cron script </td>
 141   </tr>
 142   <tr>
 143     <td> 7848 </td>
 144     <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1167" rel="nofollow">Item1167</a> forced all mail operations to generate absolute URLs </td>
 145   </tr>
 146   <tr>
 147     <td> 7568 </td>
 148     <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item910" rel="nofollow">Item910</a> use SCRIPTURL{view} instead of complex url expr </td>
 149   </tr>
 150   <tr>
 151     <td> 6864 </td>
 152     <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item624" rel="nofollow">Item624</a> mailer templates moved the the right places </td>
 153   </tr>
 154   <tr>
 155     <td> 6861 </td>
 156     <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item624" rel="nofollow">Item624</a> Added proper templates support for plain text mails </td>
 157   </tr>
 158   <tr>
 159     <td> 6809 </td>
 160     <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item623" rel="nofollow">Item623</a> don't print anything if verbosity is switched off. </td>
 161   </tr>
 162   <tr>
 163     <td> 6659 </td>
 164     <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item528" rel="nofollow">Item528</a> Updated [[Main/MailerContrib]]. it's working and the sendmail parameter is used. </td>
 165   </tr>
 166   <tr>
 167     <td> 6474 </td>
 168     <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item420" rel="nofollow">Item420</a> removed spurious remove_obsolete_locks from [[Main/MailerContrib]]</td>
 169   </tr>
 170   <tr>
 171     <td> 5924 </td>
 172     <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item153" rel="nofollow">Item153</a> fix mail URL-fixing scheme </td>
 173   </tr>
 174   <tr>
 175     <td> 5269 </td>
 176     <td> Minor doc fixes </td>
 177   </tr>
 178   <tr>
 179     <td> 5266 </td>
 180     <td> Doc tidy-ups, added filtering of _ webs, added obsolete lock script </td>
 181   </tr>
 182   <tr>
 183     <td> 5264 </td>
 184     <td> Changed default to add web name to user name (I hope) </td>
 185   </tr>
 186   <tr>
 187     <td> 5263 </td>
 188     <td> Minor doc tidyups </td>
 189   </tr>
 190   <tr>
 191     <td> 5261 </td>
 192     <td> Documentation changes, and fixed to scan all webs. </td>
 193   </tr>
 194   <tr>
 195     <td> 5253 </td>
 196     <td> runnable as CGI script, minor bugfixes, removed dependency on [[Main/DBCacheContrib]]</td>
 197   </tr>
 198   <tr>
 199     <td> 5234 </td>
 200     <td> Minor doc changes </td>
 201   </tr>
 202   <tr>
 203     <td> 5231 </td>
 204     <td> Made a change an object, added unit tests to CVS, lots of testing. </td>
 205   </tr>
 206   <tr>
 207     <td align="right"> 4 March 2005 </td>
 208     <td> 1.010 Dakar release ready. </td>
 209   </tr>
 210   <tr>
 211     <td align="right"> 12 Oct 2004 </td>
 212     <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>
 213   </tr>
 214   <tr>
 215     <td align="right"> 6 Oct 2004 </td>
 216     <td> 1.003 Excluded _ webs from processing, added <code>bin/remove_obsolete_locks</code> for full reverse-compatibility </td>
 217   </tr>
 218   <tr>
 219     <td align="right"> 1 Oct 2004 </td>
 220     <td> 1.002 PeterThoeny provided additional documentation </td>
 221   </tr>
 222   <tr>
 223     <td align="right"> 27 Sep 2004 </td>
 224     <td> 1.001 runnable as CGI script, minor bugfixes, removed dependency on DBCacheContrib </td>
 225   </tr>
 226   <tr>
 227     <td align="right"> 8 Sep 2004 </td>
 228     <td> 1.000 Initial version </td>
 229   </tr>
 230   <tr>
 231     <td align="right"> Home: </td>
 232     <td> TWiki:Plugins/%TOPIC% </td>
 233   </tr>
 234   <tr>
 235     <td align="right"> Feedback: </td>
 236     <td> TWiki:Plugins/%TOPIC%Dev </td>
 237   </tr>
 238 </table>
 239
 240 **_Related Topics:_** [[TWikiPreferences]]
 241
 242 -- TWiki:Main/CrawfordCurrie