data/TWiki/MailerContrib.txt,v
author Colas Nahaboo <colas@nahaboo.net>
Sat, 26 Jan 2008 15:50:53 +0100
changeset 0 414e01d06fd5
child 1 e2915a7cbdfa
permissions -rw-r--r--
RELEASE 4.2.0 freetown
colas@0
     1
head	1.5;
colas@0
     2
access;
colas@0
     3
symbols;
colas@0
     4
locks; strict;
colas@0
     5
comment	@# @;
colas@0
     6
colas@0
     7
colas@0
     8
1.5
colas@0
     9
date	2008.01.22.03.21.28;	author TWikiContributor;	state Exp;
colas@0
    10
branches;
colas@0
    11
next	1.4;
colas@0
    12
colas@0
    13
1.4
colas@0
    14
date	2007.01.16.04.11.59;	author TWikiContributor;	state Exp;
colas@0
    15
branches;
colas@0
    16
next	1.3;
colas@0
    17
colas@0
    18
1.3
colas@0
    19
date	2006.06.25.16.26.31;	author TWikiContributor;	state Exp;
colas@0
    20
branches;
colas@0
    21
next	1.2;
colas@0
    22
colas@0
    23
1.2
colas@0
    24
date	2006.04.01.05.55.29;	author TWikiContributor;	state Exp;
colas@0
    25
branches;
colas@0
    26
next	1.1;
colas@0
    27
colas@0
    28
1.1
colas@0
    29
date	2006.02.01.12.01.22;	author TWikiContributor;	state Exp;
colas@0
    30
branches;
colas@0
    31
next	;
colas@0
    32
colas@0
    33
colas@0
    34
desc
colas@0
    35
@new-topic
colas@0
    36
@
colas@0
    37
colas@0
    38
colas@0
    39
1.5
colas@0
    40
log
colas@0
    41
@buildrelease
colas@0
    42
@
colas@0
    43
text
colas@0
    44
@---+!! Mailer Contrib
colas@0
    45
<a href="http://wikiring.com"><img src="%ATTACHURL%/logo.gif" style="float:right" /></a>
colas@0
    46
colas@0
    47
Allows users to "subscribe" to regularly scheduled e-mails containing either:
colas@0
    48
   * A report on changes to all topics that have changed within a particular TWiki web.
colas@0
    49
   * A report on changes to a specific topic or set of topics the user can define flexibly.
colas@0
    50
   * The entire content of a specific topic or set of topics. This is referred to as "news mode."
colas@0
    51
   * The companion plugin (TWiki:Plugins.SubscribePlugin) lets you trivially add a "Subscribe to changes" button to topics
colas@0
    52
colas@0
    53
<!--
colas@0
    54
colas@0
    55
   PLEASE DO NOT EDIT THIS TOPIC
colas@0
    56
colas@0
    57
   It is automatically generated from the subversion repository, and any changes
colas@0
    58
   you make will simply be overwritten the next time a release is generated.
colas@0
    59
colas@0
    60
   Instead, you could check your fix in, raise a bug in the Bugs web, or mail the author.
colas@0
    61
-->
colas@0
    62
colas@0
    63
colas@0
    64
<div class="twikiBroadcastMessage">WARNING: TWiki-4 only. If you want to use this extension with an earlier version of TWiki, please use [[http://twiki.org/cgi-bin/attach/Plugins/%TOPIC%?filename=%TOPIC%.zip&revInfo=1][revision 17 of the zip]].</div>
colas@0
    65
colas@0
    66
%TOC%
colas@0
    67
colas@0
    68
---++ tools/mailnotify
colas@0
    69
The central component of !MailerContrib is a script, =tools/mailnotify=, that generates and sends out the emails based on analysis of
colas@0
    70
   1 users' subcriptions listed in the <nop>%NOTIFYTOPIC%  topic in each web, and
colas@0
    71
   1  changes within the respective webs.
colas@0
    72
This script is designed to be run from =cron= (or an equivalent off-line job scheduler), or from the command-line. 
colas@0
    73
colas@0
    74
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.
colas@0
    75
colas@0
    76
Each web can optionally contain a topic called <nop>%NOTIFYTOPIC%.
colas@0
    77
<!-- Included by %TWIKIWEB%.WebChangesAlert -->
colas@0
    78
%STARTINCLUDE%
colas@0
    79
Users subscribe to email notifications using their %TWIKIWEB%.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.
colas@0
    80
colas@0
    81
The general format of a subscription is:
colas@0
    82
colas@0
    83
_three spaces_ =*= _subscriber_ [ =:= _topics_ ]
colas@0
    84
colas@0
    85
Where _subscriber_ can be a %TWIKIWEB%.WikiName, an E-mail address, or a
colas@0
    86
group name. If _subscriber_ contains any characters that are not legal in
colas@0
    87
an email address, then it must be enclosed in 'single' or "double" quotes.
colas@0
    88
colas@0
    89
_topics_ is an optional space-separated list of topics:
colas@0
    90
   * ... *without* a _Web._ prefix
colas@0
    91
   * ...that exist in this web.
colas@0
    92
Users may further customize the specific content they will receive using the following controls:
colas@0
    93
   * You can use =*= in a topic name, where it is treated as a [[http://en.wikipedia.org/wiki/Wildcard_character][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.
colas@0
    94
   * 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.
colas@0
    95
   * 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.
colas@0
    96
   * 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.
colas@0
    97
colas@0
    98
For example:
colas@0
    99
Subscribe Daisy to all changes to topics in this web.
colas@0
   100
<verbatim>
colas@0
   101
   * daisy.cutter@@flowers.com
colas@0
   102
</verbatim>
colas@0
   103
Subscribe Daisy to all changes to topics that start with =Web=.
colas@0
   104
<verbatim>
colas@0
   105
   * daisy.cutter@@flowers.com : Web*
colas@0
   106
</verbatim>
colas@0
   107
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=
colas@0
   108
<verbatim>
colas@0
   109
   * DaisyCutter: Petal* (1) WeedKillers (3) Pretty*Flowers
colas@0
   110
</verbatim>
colas@0
   111
Subscribe !StarTrekFan to changes to all topics that start with =Star= *except* those that end in =Wars=, =sInTheirEyes= or =shipTroopers=.
colas@0
   112
<verbatim>
colas@0
   113
   * StarTrekFan: Star* - *Wars - *sInTheirEyes - *shipTroopers
colas@0
   114
</verbatim>
colas@0
   115
Subscribe Daisy to the full content of !NewsLetter whenever it has changed
colas@0
   116
<verbatim>
colas@0
   117
   * daisy@@flowers.com: NewsLetter?
colas@0
   118
</verbatim>
colas@0
   119
Subscribe buttercup to !NewsLetter and its immediate children, even if it hasn't changed.
colas@0
   120
<verbatim>
colas@0
   121
   * buttercup@@flowers.com: NewsLetter! (1)
colas@0
   122
</verbatim>
colas@0
   123
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:
colas@0
   124
<verbatim>
colas@0
   125
   * GardenGroup: AllNewsLetters? (3)
colas@0
   126
   * petunia@@flowers.com: - ManureNewsLetter
colas@0
   127
</verbatim>
colas@0
   128
Subscribe =IT:admins= (a non-TWiki group defined by an alternate user mapping) to all changes to Web* topics.
colas@0
   129
<verbatim>
colas@0
   130
   * 'IT:admins' : Web*
colas@0
   131
</verbatim>
colas@0
   132
colas@0
   133
A user may be listed many times in the <nop>%NOTIFYTOPIC% topic. Where a user has several lines in <nop>%NOTIFYTOPIC% 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).
colas@0
   134
colas@0
   135
If a _group_ is listed for notification, the group will be recursively expanded to the e-mail addresses of all members.
colas@0
   136
colas@0
   137
__%X% 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 <nop>%NOTIFYTOPIC%, or even block use of emails altogther, using the ={MailerContrib}{EmailFilterIn} setting in =configure=.
colas@0
   138
colas@0
   139
__%T% Tip:__ List names in alphabetical order to make it easier to find the names.
colas@0
   140
%STOPINCLUDE%
colas@0
   141
colas@0
   142
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.
colas@0
   143
colas@0
   144
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.
colas@0
   145
colas@0
   146
In addition, the %<nop>STARTPUBLISH% and %<nop>STOPPUBLISH% markers used by TWiki:Plugins.PublishContrib to delimit the text to be published are respected in news mode.
colas@0
   147
colas@0
   148
---++ TWiki/Contrib/MailerContrib code library
colas@0
   149
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.
colas@0
   150
colas@0
   151
---++ Installation Instructions
colas@0
   152
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.
colas@0
   153
colas@0
   154
Like many other TWiki extensions, this module is shipped with a fully
colas@0
   155
automatic installer script written using the Build<nop>Contrib.
colas@0
   156
   * If you have TWiki 4.2 or later, you can install from the =configure= interface (Go to Plugins->Find More Extensions)
colas@0
   157
      * See the [[http://twiki.org/cgi-bin/view/Plugins/BuildContribInstallationSupplement][installation supplement]] on TWiki.org for more information.
colas@0
   158
   * If you have any problems, then you can still install manually from the command-line:
colas@0
   159
      1 Download one of the =.zip= or =.tgz= archives
colas@0
   160
      1 Unpack the archive in the root directory of your TWiki installation.
colas@0
   161
      1 Run the installer script ( =perl &lt;module&gt;_installer= )
colas@0
   162
      1 Run =configure= and enable the module, if it is a plugin.
colas@0
   163
      1 Repeat for any missing dependencies.
colas@0
   164
   * If you are *still* having problems, then instead of running the installer script:
colas@0
   165
      1 Make sure that the file permissions allow the webserver user to access all files.
colas@0
   166
      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)
colas@0
   167
      1 Manually edit !LocalSite.cfg to set any configuration variables.
colas@0
   168
colas@0
   169
%IF{"defined 'SYSTEMWEB'" else="<div class='twikiAlert'>%X% WARNING: SYSTEMWEB is not defined in this TWiki. Please add these definitions to your %MAINWEB%.TWikiPreferences, if they are not already there:<br><pre>   * <nop>Set SYSTEMWEB = %<nop>TWIKIWEB%<br>   * <nop>Set USERSWEB = %<nop>MAINWEB%</pre></div>"}%
colas@0
   170
colas@0
   171
   * 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=.
colas@0
   172
*Additional settings*
colas@0
   173
   * You can change the regular expression that matches email addresses in <nop>%NOTIFYTOPIC% 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.
colas@0
   174
colas@0
   175
---+++ Setting up your cron job(s)
colas@0
   176
You need to set up a =cron= (or equivalent) job to run the =tools/mailnotify= perl script.
colas@0
   177
colas@0
   178
The script is used as follows: <code>perl -I _bin_ mailnotify [-q] [-news] [ <i>web1 web2 ... webN</i> ]</code>
colas@0
   179
| _bin_ | path to the TWiki bin directory, so that the script can find the rest of TWiki. |
colas@0
   180
| =-q= | Don't print progress information |
colas@0
   181
| =-news= | Run in news mode (process !NewsNotify instead of <nop>%NOTIFYTOPIC%) |
colas@0
   182
| <code><i>web1 web2 ... webN</i></code> | List of webs to process, separated by spaces or commas. The default is to process all webs. Wildcards (*) are supported. |
colas@0
   183
For example, assuming TWiki was installed at =/usr/local/twiki=, this cron entry:
colas@0
   184
<verbatim>
colas@0
   185
0 0 * * * cd /usr/local/twiki && perl -I bin tools/mailnotify -q Public Private
colas@0
   186
</verbatim>
colas@0
   187
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)
colas@0
   188
<verbatim>
colas@0
   189
0 0 * * * cd /usr/local/twiki && perl -I bin tools/mailnotify -q -Sandbox
colas@0
   190
</verbatim>
colas@0
   191
will generate change notifications for all webs, except the =Sandbox= web.
colas@0
   192
<verbatim>
colas@0
   193
0 0 * * 0 cd /usr/local/twiki && perl -I bin tools/mailnotify -news
colas@0
   194
</verbatim>
colas@0
   195
will generate newsletters from *all* webs every week on midnight Saturday.
colas@0
   196
colas@0
   197
<!--
colas@0
   198
	* Set STUB = TWiki::Contrib::Mailer
colas@0
   199
	* Set SHORTDESCRIPTION = Supports e-mail notification of changes.
colas@0
   200
-->
colas@0
   201
---++ Developer Notes
colas@0
   202
The changes mails sent to users are based on a TWiki template called =mailnotify=. This template must contain the following definitions. 
colas@0
   203
| =HTML:before= | Section of a HTML mail before the changes |
colas@0
   204
| =HTML:middle= | Repeated in a HTML mail for each change |
colas@0
   205
| =HTML:after= | Section of a HTML mail after the changes |
colas@0
   206
| =PLAIN:before= | Section of a plain text mail before the changes |
colas@0
   207
| =PLAIN:middle= | Repeated in a plain text mail for each changes |
colas@0
   208
| =PLAIN:after= | Section of a plain text mail after the changes |
colas@0
   209
| =MailNotifyBody= | All the above are embedded in this. %<nop>HTML_TEXT% expands to the HTML obtained by expanding the =HTML:*= templates, and %<nop>PLAIN_TEXT% from the =PLAIN:*= templates. |
colas@0
   210
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.
colas@0
   211
colas@0
   212
Newsletters are sent after formatting using the standard =view= template, using whatever skin is selected in the topic being mailed.
colas@0
   213
colas@0
   214
---+++ Contrib Info
colas@0
   215
colas@0
   216
Another great TWiki extension from the <a style="text-decoration:none" href="http://wikiring.com"><img src="%ATTACHURLPATH%/wikiring.png" alt="" /> *WikiRing* </a> - working together to improve your wiki experience!
colas@0
   217
colas@0
   218
Many thanks to the following sponsors for supporting this work:
colas@0
   219
   * [[http://www.windriver.com][Wind River]]
colas@0
   220
   * [[http://wikigardens.com][WikiGardens]]
colas@0
   221
colas@0
   222
|  Author: | TWiki:Main/CrawfordCurrie (http://c-dot.co.uk) |
colas@0
   223
|  Copyright &copy;: | 2004, Wind River Systems; 2006, http://WikiRing.com |
colas@0
   224
|  License: | GPL |
colas@0
   225
|  Version: | 16078 (22 Jan 2008) |
colas@0
   226
|  Change History: | |
colas@0
   227
|  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 |
colas@0
   228
|  9 Sep 2007 | Bugs:Item4326 workaround for possible error in !WebNotify API in old releases, Should not affect most users. |
colas@0
   229
|  6 Sep 2007 | Bugs:Item4488 doc tweaks |
colas@0
   230
|  14550 | Bugs:Item4461 - 'Changed' link now points to most recent changes, not the entire history |
colas@0
   231
|  22 Jun 2007 | Bugs:Item4284 - added access control checks and email filter |
colas@0
   232
|  21 May 2007 | Bugs:Item3969 - 8bit email fix (TWiki:Main.WillNorris) |
colas@0
   233
|  13623 | Bugs:Item4014 no changes was resetting the notify time to 0. Thanks to TWiki:Main.JeffCrawford for nailing this down. |
colas@0
   234
|  12496 | <a rel='nofollow' href='http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/Item3415'>Item3415</a> mailnotify did not send notifications to intranet users because of wrong call to findUser. |
colas@0
   235
|  11672 | Added newsletter support, after much harassment from TWiki:Main.LynnwoodBrown |
colas@0
   236
|  11534 | <a rel='nofollow' href='http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/Item2153'>Item2153</a> Clarified docs.  <a rel='nofollow' href='http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/Item2698'>Item2698</a> Improved error reporting. |
colas@0
   237
|  8808 | <a rel='nofollow' href='http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/Item1654'>Item1654</a>  mailnotify must enter the command_line context |
colas@0
   238
|  8625 | <a rel='nofollow' href='http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/Item1508'>Item1508</a>  Making the dashes in the separatator clearer |
colas@0
   239
|  8606 | <a rel='nofollow' href='http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/Item1508'>Item1508</a>  MailerContrib: Brushing up HTML mailnotify template |
colas@0
   240
|  8602 | <a rel='nofollow' href='http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/Item1508'>Item1508</a>  MailerContrib: Cleaning up plaintext e-mail template, removing TEXTAREA |
colas@0
   241
|  8522 | <a rel='nofollow' href='http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/Item1511'>Item1511</a>  arguments to getScriptUrl in wrong order :-( |
colas@0
   242
|  8434 | <a rel='nofollow' href='http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/Item1465'>Item1465</a>  Fix 'TWiki.' to '%TWIKIEB%.' |
colas@0
   243
|  8398 | <a rel='nofollow' href='http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/Item1460'>Item1460</a>  polished up the comment a bit |
colas@0
   244
|  8308 | <a rel='nofollow' href='http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/Item1362'>Item1362</a>  moving mailnotify cron script |
colas@0
   245
|  7848 | <a rel='nofollow' href='http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/Item1167'>Item1167</a>  forced all mail operations to generate absolute URLs |
colas@0
   246
|  7568 | <a rel='nofollow' href='http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/Item910'>Item910</a>  use SCRIPTURL{view} instead of complex url expr |
colas@0
   247
|  6864 | <a rel='nofollow' href='http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/Item624'>Item624</a>  mailer templates moved the the right places |
colas@0
   248
|  6861 | <a rel='nofollow' href='http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/Item624'>Item624</a>  Added proper templates support for plain text mails |
colas@0
   249
|  6809 | <a rel='nofollow' href='http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/Item623'>Item623</a>  don't print anything if verbosity is switched off. |
colas@0
   250
|  6659 | <a rel='nofollow' href='http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/Item528'>Item528</a>  Updated MailerContrib. it's working and the sendmail parameter is used. |
colas@0
   251
|  6474 | <a rel='nofollow' href='http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/Item420'>Item420</a>  removed spurious remove_obsolete_locks from MailerContrib |
colas@0
   252
|  5924 | <a rel='nofollow' href='http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/Item153'>Item153</a>  fix mail URL-fixing scheme |
colas@0
   253
|  5269 | Minor doc fixes |
colas@0
   254
|  5266 | Doc tidy-ups, added filtering of _ webs, added obsolete lock script |
colas@0
   255
|  5264 | Changed default to add web name to user name (I hope) |
colas@0
   256
|  5263 | Minor doc tidyups |
colas@0
   257
|  5261 | Documentation changes, and fixed to scan all webs. |
colas@0
   258
|  5253 | runnable as CGI script, minor bugfixes, removed dependency on DBCacheContrib |
colas@0
   259
|  5234 | Minor doc changes |
colas@0
   260
|  5231 | Made a change an object, added unit tests to CVS, lots of testing. |
colas@0
   261
|  4 March 2005 | 1.010 Dakar release ready. |
colas@0
   262
|  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) |
colas@0
   263
|  6 Oct 2004 | 1.003 Excluded _ webs from processing, added =bin/remove_obsolete_locks= for full reverse-compatibility |
colas@0
   264
|  1 Oct 2004 | 1.002 Peter<nop>Thoeny provided additional documentation |
colas@0
   265
|  27 Sep 2004 | 1.001 runnable as CGI script, minor bugfixes, removed dependency on DB<nop>CacheContrib |
colas@0
   266
|  8 Sep 2004 | 1.000 Initial version |
colas@0
   267
|  Home: | TWiki:Plugins/%TOPIC% |
colas@0
   268
|  Feedback: | TWiki:Plugins/%TOPIC%Dev |
colas@0
   269
|  Appraisal: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Appraisal |
colas@0
   270
colas@0
   271
%META:FILEATTACHMENT{name="wikiringlogo20x20.png" attr="h" comment="" version="1"}%
colas@0
   272
%META:FILEATTACHMENT{name="logo.gif" attr="h" comment="" version="1"}%
colas@0
   273
@
colas@0
   274
colas@0
   275
colas@0
   276
1.4
colas@0
   277
log
colas@0
   278
@buildrelease
colas@0
   279
@
colas@0
   280
text
colas@0
   281
@d1 2
colas@0
   282
a2 2
colas@0
   283
%META:TOPICINFO{author="TWikiAdminGroup" date="1168425636" format="1.1" version="4"}%
colas@0
   284
---+!! %TOPIC%
colas@0
   285
d4 1
colas@0
   286
a4 1
colas@0
   287
Add-on to the TWiki kernel that allows users to "subscribe" to regularly scheduled e-mails containing either:
colas@0
   288
d8 1
colas@0
   289
d21 1
colas@0
   290
a21 1
colas@0
   291
*WARNING: TWiki-4 only. If you want to use this extension with an earlier version of TWiki, please see [[http://twiki.org/cgi-bin/view/Plugins/%TOPIC%?rev=1.17][here]]*
colas@0
   292
d25 2
colas@0
   293
a26 2
colas@0
   294
---+ <code>tools/mailnotify</code>
colas@0
   295
The central component of MailerContrib is a script, =tools/mailnotify=, that generates and sends out the emails based on analysis of
colas@0
   296
d36 1
colas@0
   297
a36 1
colas@0
   298
Users subscribe to email notifications using their %TWIKIWEB%.WikiName or an alternative email address, and can specify the webs/topics they wish to track using one of these bullet list formats:
colas@0
   299
d38 14
colas@0
   300
a51 11
colas@0
   301
_three spaces_ * [ _webname_ . ] _wikiName_ - _SMTP mail address_ <br />
colas@0
   302
_three spaces_ * [ _webName_ . ] _wikiName_ <br />
colas@0
   303
_three spaces_ * _SMTP mail address_ <br />
colas@0
   304
_three spaces_ * _SMTP mail address_ : _topics_ <br />
colas@0
   305
_three spaces_ * [ _webname_ . ] _wikiName_ : _topics_
colas@0
   306
colas@0
   307
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:
colas@0
   308
   * Specify topics without a _Web._ prefix
colas@0
   309
   * Topics must exist in this web.
colas@0
   310
   * Topics may be specified using * wildcards
colas@0
   311
   * 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 ('+').
colas@0
   312
d53 1
colas@0
   313
a53 1
colas@0
   314
   * 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.
colas@0
   315
d60 1
colas@0
   316
a60 1
colas@0
   317
Subscribe Daisy to all changes in all webs that start with =Web=.
colas@0
   318
d62 1
colas@0
   319
a62 1
colas@0
   320
   * daisy.cutter@@flowers.com: Web*
colas@0
   321
d85 5
colas@0
   322
d92 3
colas@0
   323
a94 1
colas@0
   324
If a _TWiki group_ is listed for notification, the group will be recursively expanded to the e-mail addresses of all members.
colas@0
   325
d101 1
colas@0
   326
a101 130
colas@0
   327
%RED% __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. %ENDCOLOR%
colas@0
   328
colas@0
   329
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.
colas@0
   330
colas@0
   331
In addition, the %<nop>STARTPUBLISH% and %<nop>STOPPUBLISH% markers used by TWiki:Plugins.PublishContrib to delimit the text to be published are respected.
colas@0
   332
colas@0
   333
---+ <code>TWiki/Contrib/MailerContrib</code> code library
colas@0
   334
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 =Web<nop>Notify= package described below.
colas@0
   335
colas@0
   336
---+ package TWiki::Contrib::MailerContrib::WebNotify
colas@0
   337
Object that represents the contents of a %NOTIFYTOPIC% topic in a TWiki web
colas@0
   338
colas@0
   339
colas@0
   340
---++ ClassMethod new($web, $topic)
colas@0
   341
Create a new object by parsing the content of the given topic in the
colas@0
   342
given web. This is the normal way to load a %NOTIFYTOPIC% topic. If the
colas@0
   343
topic does not exist, it will create an empty object.
colas@0
   344
colas@0
   345
colas@0
   346
---++ ObjectMethod writeWebNotify()
colas@0
   347
Write the object to the %NOTIFYTOPIC% topic it was read from.
colas@0
   348
If there is a problem writing the topic (e.g. it is locked),
colas@0
   349
the method will return an error message. If everything is ok
colas@0
   350
it will return undef.
colas@0
   351
colas@0
   352
colas@0
   353
---++ ObjectMethod getSubscriber($name, $noAdd)
colas@0
   354
   * =$name= - Name of subscriber (wikiname with no web or email address)
colas@0
   355
   * =$noAdd= - If false or undef, a new subscriber will be created for this name
colas@0
   356
Get a subscriber from the list of subscribers, and return a reference
colas@0
   357
to the Subscriber object. If $noAdd is true, and the subscriber is not
colas@0
   358
found, undef will be returned. Otherwise a new Subscriber object will
colas@0
   359
be added if necessary.
colas@0
   360
colas@0
   361
colas@0
   362
---++ ObjectMethod getSubscribers()
colas@0
   363
Get a list of all subscriber names (unsorted)
colas@0
   364
colas@0
   365
colas@0
   366
---++ ObjectMethod subscribe($name, $topics, $depth)
colas@0
   367
   * =$name= - Name of subscriber (wikiname with no web or email address)
colas@0
   368
   * =$topics= - wildcard expression giving topics to subscribe to
colas@0
   369
   * =$depth= - Child depth to scan (default 0)
colas@0
   370
   * =$mode= - ! if this is a non-changes subscription and the topics should
colas@0
   371
   be mailed evebn if there are no changes. ? to mail the full topic only
colas@0
   372
   if there are changes. undef to mail changes only.
colas@0
   373
Add a subscription, adding the subscriber if necessary.
colas@0
   374
colas@0
   375
colas@0
   376
---++ ObjectMethod unsubscribe($name, $topics, $depth)
colas@0
   377
   * =$name= - Name of subscriber (wikiname with no web or email address)
colas@0
   378
   * =$topics= - wildcard expression giving topics to subscribe to
colas@0
   379
   * =$depth= - Child depth to scan (default 0)
colas@0
   380
Add an unsubscription, adding the subscriber if necessary. An unsubscription
colas@0
   381
is a specific request to ignore notifications for a topic for this
colas@0
   382
particular subscriber.
colas@0
   383
colas@0
   384
colas@0
   385
---++ ObjectMethod stringify() -> string
colas@0
   386
Return a string representation of this object, in %NOTIFYTOPIC% format.
colas@0
   387
colas@0
   388
colas@0
   389
---++ ObjectMethod processChange($change, $db, $changeSet, $seenSet, $allSet)
colas@0
   390
   * =$change= - ref of a TWiki::Contrib::Mailer::Change
colas@0
   391
   * =$db= - TWiki::Contrib::MailerContrib::UpData database of parent references
colas@0
   392
   * =$changeSet= - ref of a hash mapping emails to sets of changes
colas@0
   393
   * =$seenSet= - ref of a hash recording indices of topics already seen
colas@0
   394
   * =$allSet= - ref of a hash that maps topics to email addresses for news subscriptions
colas@0
   395
Find all subscribers that are interested in the given change. Only the most
colas@0
   396
recent change to each topic listed in the .changes file is retained. This
colas@0
   397
method does _not_ change this object.
colas@0
   398
colas@0
   399
colas@0
   400
---++ ObjectMethod processCompulsory($topic, $db, \%allSet)
colas@0
   401
   * =$topic= - topic name
colas@0
   402
   * =$db= - TWiki::Contrib::MailerContrib::UpData database of parent references
colas@0
   403
   * =\%allSet= - ref of a hash that maps topics to email addresses for news subscriptions
colas@0
   404
colas@0
   405
colas@0
   406
---++ ObjectMethod isEmpty() -> boolean
colas@0
   407
Return true if there are no subscribers
colas@0
   408
colas@0
   409
colas@0
   410
---+ package TWiki::Contrib::MailerContrib::Subscriber
colas@0
   411
Object that represents a subscriber to notification. A subscriber is
colas@0
   412
a name (which may be a wikiName or an email address) and a list of
colas@0
   413
subscriptions which describe the topis subscribed to, and
colas@0
   414
unsubscriptions representing topics they are specifically not
colas@0
   415
interested in. The subscriber
colas@0
   416
name may also be a group, so it may expand to many email addresses.
colas@0
   417
colas@0
   418
colas@0
   419
---++ ClassMethod new($name)
colas@0
   420
   * =$name= - Wikiname, with no web, or email address, of user targeted for notification
colas@0
   421
Create a new user.
colas@0
   422
colas@0
   423
colas@0
   424
---++ ObjectMethod getEmailAddresses() -> list
colas@0
   425
Get a list of email addresses for the user(s) represented by this
colas@0
   426
subscription
colas@0
   427
colas@0
   428
colas@0
   429
---++ ObjectMethod subscribe($subs)
colas@0
   430
   * =$subs= - Subscription object
colas@0
   431
Add a new subscription to this subscriber object.
colas@0
   432
The subscription will always be added, even if there is
colas@0
   433
a wildcard overlap with an existing subscription.
colas@0
   434
colas@0
   435
colas@0
   436
---++ ObjectMethod unsubscribe($subs)
colas@0
   437
   * =$subs= - Subscription object
colas@0
   438
Add a new unsubscription to this subscriber object.
colas@0
   439
The unsubscription will always be added, even if there is
colas@0
   440
a wildcard overlap with an existing subscription or unsubscription.
colas@0
   441
colas@0
   442
An unsubscription is a statement of the subscribers desire _not_
colas@0
   443
to be notified of changes to this topic.
colas@0
   444
colas@0
   445
colas@0
   446
---++ ObjectMethod isSubscribedTo($topic) -> $subscription
colas@0
   447
   * =$topic= - Topic object we are checking
colas@0
   448
   * =$db= - TWiki::Contrib::MailerContrib::UpData database of parents
colas@0
   449
Check if we have a subscription to the given topic. Return the subscription
colas@0
   450
that matches if we do, undef otherwise.
colas@0
   451
colas@0
   452
colas@0
   453
---++ ObjectMethod isUnsubscribedFrom($topic) -> $subscription
colas@0
   454
   * =$topic= - Topic object we are checking
colas@0
   455
   * =$db= - TWiki::Contrib::MailerContrib::UpData database of parents
colas@0
   456
Check if we have an unsubscription from the given topic. Return the subscription that matches if we do, undef otherwise.
colas@0
   457
d103 1
colas@0
   458
d105 2
colas@0
   459
a106 2
colas@0
   460
---++ ObjectMethod stringify() -> string
colas@0
   461
Return a string representation of this object, in Web<nop>Notify format.
colas@0
   462
d108 1
colas@0
   463
a108 104
colas@0
   464
colas@0
   465
---+ package TWiki::Contrib::MailerContrib::Subscription
colas@0
   466
Object that represents a single subscription of a user to
colas@0
   467
notification on a page. A subscription is expressed as a page
colas@0
   468
spec (which may contain wildcards) and a depth of children of
colas@0
   469
matching pages that the user is subscribed to.
colas@0
   470
colas@0
   471
colas@0
   472
---++ ClassMethod new($pages, $childDepth, $news)
colas@0
   473
   * =$pages= - Wildcarded expression matching subscribed pages
colas@0
   474
   * =$childDepth= - Depth of children of $topic to notify changes for. Defaults to 0
colas@0
   475
   * =$mode= - ! if this is a non-changes subscription and the topics should
colas@0
   476
   be mailed evebn if there are no changes. ? to mail the full topic only
colas@0
   477
   if there are changes. undef to mail changes only.
colas@0
   478
Create a new subscription.
colas@0
   479
colas@0
   480
colas@0
   481
---++ ObjectMethod stringify() -> string
colas@0
   482
Return a string representation of this object, in Web<nop>Notify format.
colas@0
   483
colas@0
   484
colas@0
   485
---++ ObjectMethod matches($topic, $db, $depth) -> boolean
colas@0
   486
   * =$topic= - Topic object we are checking
colas@0
   487
   * =$db= - TWiki::Contrib::MailerContrib::UpData database of parent names
colas@0
   488
   * =$depth= - If non-zero, check if the parent of the given topic matches as well. undef = 0.
colas@0
   489
Check if we match this topic. Recurses up the parenthood tree seeing if
colas@0
   490
this is a child of a parent that matches within the depth range.
colas@0
   491
colas@0
   492
colas@0
   493
---++ ObjectMethod getMode() -> $mode
colas@0
   494
Return ! if this is a non-changes subscription and the topics should
colas@0
   495
be mailed even if there are no changes. ? to mail the full topic only
colas@0
   496
if there are changes. undef to mail changes only.
colas@0
   497
colas@0
   498
colas@0
   499
---
colas@0
   500
---+ package TWiki::Contrib::MailerContrib::Change
colas@0
   501
Object that represents a change to a topic.
colas@0
   502
colas@0
   503
colas@0
   504
---++ ClassMethod new($web)
colas@0
   505
   * =$web= - Web name
colas@0
   506
   * =$topic= - Topic name
colas@0
   507
   * =$author= - String author of change
colas@0
   508
   * =$time= - String time of change
colas@0
   509
   * =$rev= - Revision identifier
colas@0
   510
Construct a new change object.
colas@0
   511
colas@0
   512
colas@0
   513
---++ ObjectMethod merge($change)
colas@0
   514
   * =$change= - Change record to merge
colas@0
   515
Merge another change record with this one, so that the combined
colas@0
   516
record is a reflection of both changes.
colas@0
   517
colas@0
   518
colas@0
   519
---++ ObjectMethod expandHTML($html) -> string
colas@0
   520
   * =$html= - Template to expand keys within
colas@0
   521
Expand an HTML template using the values in this change. The following
colas@0
   522
keys are expanded: %<nop>TOPICNAME%, %<nop>AUTHOR%, %<nop>TIME%,
colas@0
   523
%<nop>REVISION%, %<nop>TEXTHEAD%.
colas@0
   524
colas@0
   525
Returns the expanded template.
colas@0
   526
colas@0
   527
colas@0
   528
---++ ObjectMethod expandPlain() -> string
colas@0
   529
Generate a plaintext version of this change.
colas@0
   530
colas@0
   531
colas@0
   532
---+ package TWiki::Contrib::MailerContrib::UpData
colas@0
   533
Object that lazy-scans topics to extract
colas@0
   534
parent relationships.
colas@0
   535
colas@0
   536
colas@0
   537
---++ ClassMethod new($web)
colas@0
   538
   * =$web= - Web we are building parent relationships for
colas@0
   539
Constructor for a web; initially empty, will lazy-load as topics
colas@0
   540
are referenced.
colas@0
   541
colas@0
   542
colas@0
   543
---++ ObjectMethod getParent($topic) -> string
colas@0
   544
Get the name of the parent topic of the given topic
colas@0
   545
colas@0
   546
colas@0
   547
---+ package TWiki::Contrib::Mailer
colas@0
   548
colas@0
   549
Package of support for extended Web<nop>Notify notification, supporting per-topic notification and notification of changes to children.
colas@0
   550
colas@0
   551
Also supported is a simple API that can be used to change the Web<nop>Notify topic from other code.
colas@0
   552
colas@0
   553
colas@0
   554
---++ StaticMethod mailNotify($webs, $session, $verbose)
colas@0
   555
   * =$webs= - filter list of names webs to process. Wildcards (*) may be used.
colas@0
   556
   * =$session= - optional session object. If not given, will use a local object.
colas@0
   557
   * =$verbose= - true to get verbose (debug) output
colas@0
   558
colas@0
   559
Main entry point.
colas@0
   560
colas@0
   561
Process the Web<nop>Notify topics in each web and generate and issue
colas@0
   562
notification mails. Designed to be invoked from the command line; should
colas@0
   563
only be called by =mailnotify= scripts.
colas@0
   564
colas@0
   565
colas@0
   566
colas@0
   567
---+ Installation Instructions
colas@0
   568
d111 12
colas@0
   569
a122 19
colas@0
   570
Like many other TWiki extensions, this module is shipped with a fully automatic installer script written using the Build<nop>Contrib.
colas@0
   571
   * 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)
colas@0
   572
      * The webserver user has to have permission to write to all areas of your installation for this to work.
colas@0
   573
   * If you have a permanent connection to the internet (and Perl 5.8), you are recommended to use the automatic installer script
colas@0
   574
      * Just download the =MailerContrib_installer= perl script and run it.
colas@0
   575
   * *Notes:*
colas@0
   576
      * The installer script will:
colas@0
   577
         * Automatically resolve dependencies,
colas@0
   578
         * Copy files into the right places in your local install (even if you have renamed data directories),
colas@0
   579
         * check in new versions of any installed files that have existing RCS histories files in your existing install (such as topics).
colas@0
   580
         * 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.
colas@0
   581
         * (Developers only: the script will look for twikiplugins/MailerContrib/MailerContrib.tgz before downloading from TWiki.org)
colas@0
   582
      * 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.
colas@0
   583
         * Point the environment variable =$TWIKI_PACKAGES= to this directory, and the installer script will look there first for required TWiki packages.
colas@0
   584
            * =$TWIKI_PACKAGES= is actually a path; you can list several directories separated by :
colas@0
   585
         * 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
colas@0
   586
   * 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:
colas@0
   587
      1 Download and unpack one of the =.zip= or =.tgz= archives to a temporary directory.
colas@0
   588
      1 Manually copy the contents across to the relevant places in your TWiki installation.
colas@0
   589
a124 2
colas@0
   590
      1 Run =configure= and enable the module, if it is a plugin.
colas@0
   591
      1 Repeat from step 1 for any missing dependencies.
colas@0
   592
d126 5
colas@0
   593
a130 1
colas@0
   594
   * 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.
colas@0
   595
d132 2
colas@0
   596
a133 2
colas@0
   597
---++ Setting up your cron job(s)
colas@0
   598
You need to set up a =cron= (or equivalent) job to run =tools/mailnotify=.
colas@0
   599
d135 2
colas@0
   600
a136 2
colas@0
   601
Usage: <code>perl -I &lt;bin&gt; mailnotify [-q] [-news] [ <i>web1 web2 ... webN</i> ]</code>
colas@0
   602
&lt;bin&gt; is the path to the TWiki bin directory, so that the script can find the rest of TWiki.
colas@0
   603
d139 1
colas@0
   604
a139 1
colas@0
   605
| <code><i>web1 web2 ... webN</i></code> | List of webs to process, separated by spaces or commas. Default is to process all legal TWiki webs. Wildcards (*) are supported. |
colas@0
   606
d144 5
colas@0
   607
a148 1
colas@0
   608
will generate change notifications for the =Public= and =Private= webs every night at midnight.
colas@0
   609
d158 1
colas@0
   610
a158 1
colas@0
   611
---+ Developer Notes
colas@0
   612
d171 7
colas@0
   613
a177 1
colas@0
   614
---++ Contrib Info
colas@0
   615
d182 1
colas@0
   616
d184 7
colas@0
   617
d228 2
colas@0
   618
a229 1
colas@0
   619
colas@0
   620
@
colas@0
   621
colas@0
   622
colas@0
   623
1.3
colas@0
   624
log
colas@0
   625
@buildrelease
colas@0
   626
@
colas@0
   627
text
colas@0
   628
@d1 1
colas@0
   629
d4 4
colas@0
   630
a7 1
colas@0
   631
Add-on to the TWiki kernel that supports e-mail notification of changes.
colas@0
   632
d24 5
colas@0
   633
a28 3
colas@0
   634
---++ Summary of Contents
colas@0
   635
---+++ <code>tools/mailnotify</code>
colas@0
   636
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 <nop>%NOTIFYTOPIC% 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.
colas@0
   637
d30 3
colas@0
   638
d35 1
colas@0
   639
a35 1
colas@0
   640
Subscribers are listed in <nop>%NOTIFYTOPIC% following one of these bullet list formats:
colas@0
   641
d43 1
colas@0
   642
a43 1
colas@0
   643
where _topics_ is a space-separated list of topic names.
colas@0
   644
d47 1
colas@0
   645
d49 1
colas@0
   646
a49 1
colas@0
   647
   * 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 ('+').
colas@0
   648
d52 25
colas@0
   649
d78 2
colas@0
   650
a79 4
colas@0
   651
   * daisy@@flowers.com
colas@0
   652
   * daisy@@flowers.com: Web*
colas@0
   653
   * DaisyCutter: Petal* (1) WeedKillers (3) Red*Phlox
colas@0
   654
   * StarTrekFan: * - *Wars - *sInTheirEyes - *shipTroopers
colas@0
   655
d81 1
colas@0
   656
a81 1
colas@0
   657
A user may be listed many times in the <nop>%NOTIFYTOPIC% topic. Where a user has several lines in <nop>%NOTIFYTOPIC% that all match the same topic, they will only be notified of changes to that topic _once_.
colas@0
   658
d90 124
colas@0
   659
a213 1
colas@0
   660
%RED% __Note__ =mailnotify= ignores permissions in webs. It is entirely possible for a user to get added to a <nop>%NOTIFYTOPIC% 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%
colas@0
   661
a214 2
colas@0
   662
---+++ <code>TWiki/Contrib/MailerContrib</code> code library
colas@0
   663
The second part of the module is a code library that provides the services for other applications to modify <nop>%NOTIFYTOPIC% 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 =Web<nop>Notify= package described below.
colas@0
   664
d216 139
colas@0
   665
a354 5
colas@0
   666
---++ Installation Instructions
colas@0
   667
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.
colas@0
   668
   * Download the ZIP file from the Plugin web (see below)
colas@0
   669
   * Unzip ==%TOPIC%.zip== in your twiki installation directory.
colas@0
   670
   * Run the installer script =MailContrib_intaller.pl= or alternatively resolve all dependencies manually.
colas@0
   671
d357 2
colas@0
   672
a358 2
colas@0
   673
---++ Setting up your cron job
colas@0
   674
You need to set up a =cron= (or equivalent) job to run =mailnotify=.
colas@0
   675
d360 2
colas@0
   676
a361 2
colas@0
   677
<code>Usage: perl -I &lt;bin&gt; mailnotify [-q] [ <i>web1 web2 ... webN</i> ]</code>
colas@0
   678
&lt;bin&gt; is the path to the TWiki bin directory (usually =../bin=), so that the script can find the rest of TWiki.
colas@0
   679
d363 1
colas@0
   680
d365 9
colas@0
   681
a373 1
colas@0
   682
For example, =perl -I /usr/local/twiki/bin mailnotify -q Public Private= will generate notifications for the Public and Private webs.
colas@0
   683
d375 1
colas@0
   684
a375 1
colas@0
   685
---++ Settings
colas@0
   686
d378 13
colas@0
   687
d395 1
colas@0
   688
a395 1
colas@0
   689
|  Copyright &copy;: | 2004, Wind River Systems |
colas@0
   690
d397 28
colas@0
   691
a424 25
colas@0
   692
| Change History: | |
colas@0
   693
| 8808 | <a rel='nofollow' href='http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1654'>Item1654</a>  mailnotify must enter the command_line context |
colas@0
   694
| 8625 | <a rel='nofollow' href='http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1508'>Item1508</a>  Making the dashes in the separatator clearer |
colas@0
   695
| 8606 | <a rel='nofollow' href='http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1508'>Item1508</a>  MailerContrib: Brushing up HTML mailnotify template |
colas@0
   696
| 8602 | <a rel='nofollow' href='http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1508'>Item1508</a>  MailerContrib: Cleaning up plaintext e-mail template, removing TEXTAREA |
colas@0
   697
| 8522 | <a rel='nofollow' href='http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1511'>Item1511</a>  arguments to getScriptUrl in wrong order :-( |
colas@0
   698
| 8434 | <a rel='nofollow' href='http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1465'>Item1465</a>  Fix 'TWiki.' to '%TWIKIEB%.' |
colas@0
   699
| 8398 | <a rel='nofollow' href='http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1460'>Item1460</a>  polished up the comment a bit |
colas@0
   700
| 8308 | <a rel='nofollow' href='http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1362'>Item1362</a>  moving mailnotify cron script |
colas@0
   701
| 7848 | <a rel='nofollow' href='http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1167'>Item1167</a>  forced all mail operations to generate absolute URLs |
colas@0
   702
| 7568 | <a rel='nofollow' href='http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item910'>Item910</a>  use SCRIPTURL{view} instead of complex url expr |
colas@0
   703
| 6864 | <a rel='nofollow' href='http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item624'>Item624</a>  mailer templates moved the the right places |
colas@0
   704
| 6861 | <a rel='nofollow' href='http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item624'>Item624</a>  Added proper templates support for plain text mails |
colas@0
   705
| 6809 | <a rel='nofollow' href='http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item623'>Item623</a>  don't print anything if verbosity is switched off. |
colas@0
   706
| 6659 | <a rel='nofollow' href='http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item528'>Item528</a>  Updated MailerContrib. it's working and the sendmail parameter is used. |
colas@0
   707
| 6474 | <a rel='nofollow' href='http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item420'>Item420</a>  removed spurious remove_obsolete_locks from MailerContrib |
colas@0
   708
| 5924 | <a rel='nofollow' href='http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item153'>Item153</a>  fix mail URL-fixing scheme |
colas@0
   709
| 5269 | Minor doc fixes |
colas@0
   710
| 5266 | Doc tidy-ups, added filtering of _ webs, added obsolete lock script |
colas@0
   711
| 5264 | Changed default to add web name to user name (I hope) |
colas@0
   712
| 5263 | Minor doc tidyups |
colas@0
   713
| 5261 | Documentation changes, and fixed to scan all webs. |
colas@0
   714
| 5253 | runnable as CGI script, minor bugfixes, removed dependency on DBCacheContrib |
colas@0
   715
| 5234 | Minor doc changes |
colas@0
   716
| 5231 | Made a change an object, added unit tests to CVS, lots of testing. |
colas@0
   717
@
colas@0
   718
colas@0
   719
colas@0
   720
1.2
colas@0
   721
log
colas@0
   722
@buildrelease
colas@0
   723
@
colas@0
   724
text
colas@0
   725
@d1 4
colas@0
   726
a4 1
colas@0
   727
%META:TOPICINFO{author="TWikiContributor" date="1111929255" format="1.0" version="2"}%
colas@0
   728
d12 1
colas@0
   729
a12 1
colas@0
   730
   Instead, you could check your fix in, raise a bug in the Bugs web, or mail thge author.
colas@0
   731
d14 1
colas@0
   732
a14 1
colas@0
   733
This module is an add-on to the TWiki kernel that supports e-mail notification of changes.
colas@0
   734
d20 2
colas@0
   735
a21 2
colas@0
   736
---+ Summary of Contents
colas@0
   737
---++ <code>tools/mailnotify</code>
colas@0
   738
d59 1
colas@0
   739
a59 1
colas@0
   740
---++ <code>TWiki/Contrib/MailerContrib</code> code library
colas@0
   741
d62 1
colas@0
   742
a62 1
colas@0
   743
---+ Installation Instructions
colas@0
   744
d69 1
colas@0
   745
a69 1
colas@0
   746
---+ Setting up your cron job
colas@0
   747
d72 2
colas@0
   748
a73 2
colas@0
   749
<code>Usage: perl -I <bin> tools/mailnotify [-q] [ <i>web1 web2 ... webN</i> ]</code>
colas@0
   750
<bin> is the path to the TWiki bin directory, so that the script can find the rest of TWiki.
colas@0
   751
d78 3
colas@0
   752
a80 3
colas@0
   753
---+ Settings
colas@0
   754
   * Name of the perl package
colas@0
   755
      * Set STUB = TWiki::Contrib::Mailer
colas@0
   756
d82 1
colas@0
   757
a82 1
colas@0
   758
---+ Contrib Info
colas@0
   759
d120 1
colas@0
   760
a121 1
colas@0
   761
__Related Topics:__ %TWIKIWEB%.TWikiPreferences
colas@0
   762
a122 1
colas@0
   763
-- TWiki:Main/CrawfordCurrie
colas@0
   764
@
colas@0
   765
colas@0
   766
colas@0
   767
1.1
colas@0
   768
log
colas@0
   769
@buildrelease
colas@0
   770
@
colas@0
   771
text
colas@0
   772
@d1 2
colas@0
   773
a2 1
colas@0
   774
%META:TOPICINFO{author="TWikiContributor" date="1111929255" format="1.0" version="1"}%
colas@0
   775
d4 7
colas@0
   776
d13 2
colas@0
   777
d32 5
colas@0
   778
a36 5
colas@0
   779
	* Specify topics without a _Web._ prefix
colas@0
   780
	* Topics must exist in this web.
colas@0
   781
	* Topics may be specified using * wildcards
colas@0
   782
	* 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.
colas@0
   783
	* 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 ('+').
colas@0
   784
d40 4
colas@0
   785
a43 4
colas@0
   786
	* daisy@@flowers.com
colas@0
   787
	* daisy@@flowers.com: Web*
colas@0
   788
	* DaisyCutter: Petal* (1) WeedKillers (3) Red*Phlox
colas@0
   789
	* StarTrekFan: * - *Wars - *sInTheirEyes - *shipTroopers
colas@0
   790
d61 4
colas@0
   791
a64 4
colas@0
   792
	* Download the ZIP file from the Plugin web (see below)
colas@0
   793
	* Unzip ==%TOPIC%.zip== in your twiki installation directory.
colas@0
   794
	* Run the installer script =MailContrib_intaller.pl= or alternatively resolve all dependencies manually.
colas@0
   795
	* 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.
colas@0
   796
d76 2
colas@0
   797
a77 2
colas@0
   798
	* Name of the perl package
colas@0
   799
		* Set STUB = TWiki::Contrib::Mailer
colas@0
   800
d84 25
colas@0
   801
a108 1
colas@0
   802
|  Change&nbsp;History: | <!-- versions below in reverse order -->&nbsp; |
colas@0
   803
@