This plugin was distributed previously as part of the McKessonApsWikiPlugins package, now as part of the CeryleWikiPlugins. This documentation is updated for the new version as appropriate.

The EmailNotifier plugin uses a wiki page to maintain a list of subscribers. Subscribers receive an email once a day listing all wiki pages which were modified during the previous 24 hours. A subscriber may control when the email is sent and what pages are listed.

While EmailGenerator is already proposing similar functionality, and is a fine example of what you can do with XML-RPC, we wanted an built-in email notification mechanism for our internal wiki. Insert this plugin on a page; all parameters to control email notification are part of the plugin syntax. The EmailNotifier starts running when the plugin is executed for the first time (read the javadoc in the source for details).

Basically, the EmailNotifier plugin kicks off a NotifierThread which sleeps and periodically runs a NotifierTask, which in turn reads the designated subscription page listing the Subscribers to which it will send emails.

Each execution of the plugin updates the parameters that the NotifierTask uses. (There is a "flood limiter" in place to limit parameter updates to no more that once per minute. )

You can download a ready-to-try-it jar (with the source code in it) on, or as part of, CeryleWikiPlugins. (That little TickerPlugin is in there too).

Let's try to keep EmailNotifierPluginDiscussion on it's own page.

This plugin was developed with JDK 1.4, it's not been tested against any older versions and probably will not work with older versions.

I think it's pretty self-explanatory, here are some example usages...

Alternate versions#

There is a rewritten version of this plugin available at http://kaukoluwiki.opendfki.de/wiki/EmailNotifier that supports subscription patterns ("subscribe to all but THIS page" patterns, too) and simpler configuration using an admin webfrontend.

Quick thought...#

It was mentioned to me offline that a "better" way to setup a subscription would be to allow the use of the QueryPlugin syntax to define which pages a user is interested in. Anyone interested? You could subscribe to any pages that linked TO or BY any other page.

Support for RegExp for page names in subscription would be nice enhancement. - MichaelLee

Installation#

  1. Download and install CeryleWikiPlugins
  2. Restart JSPWiki
  3. Edit e.g. your main page and add the plugin tag, see Plugin Parameters below
  4. Set the parameters as appropriate for your site
  5. If after adding the plugin all you see is org/apache/log4j/Logger you need a newer version of Log4j
  6. If your web application server does not contain mail.jar and activation.jar from javamail, you must add it.
  7. Create the notification page (called YourSubscriptionPage below) using the Subscription Page Syntax

Changes to the plugin tag take effect at most once per minute, check the log4j log file and reload the page if you want to make sure.

There will be a message at the place you put the plugin tag saying something like Sandbox next notification at Jul 12, 2004 6:20:00 PM. Subscribe at NotificationList. You cannot change the message or date format without recompiling the code.

To test the email notifications quickly, set hourInterval to 0 and minuteOffset two minutes into the future. Reload the page until you see the correct minuteOffset. Check the log4j log (default /tmp/jspwiki.log) and the servlet container log for errors. You get much more detailed log output by editing jspwiki.properties and setting log4j.rootCategory to DEBUG.

SMTP Authentication#

I AndrewBroughton have added simple SMTP authentication to this plugin. See the McKessonAps_src.zip attachment below, which also includes the jar file for those who are too impatient to compile the src ;-) I will contact JohnVolkar to get this integrated into the main CeryleWikiPlugins jar file. There are now three new parameters useAuthentication, authUsername and authPassword here is an example of how to use
[{INSERT org.ceryle.wiki.plugin.emailnotifier.EmailNotifierPlugin
WHERE server='localhost' from='someone@nowhere.com' subject='Wiki Changes'
subscriptionPage='NotificationList' minuteOffset='01' hourInterval='0'
useAuthentication='true' authUsername='username' authPassword='password'
changedPagePattern='<li><a href=http://www.jspwiki.org:8080/Wiki/Wiki.jsp?page=
CHANGED_PAGE_NAME>CHANGED_PAGE_NAME</a></li> \n'


<HTML><BODY>
<p>
The following pages have changed in the last 24 hours.
<p/>
<ul>
CHANGED_PAGE_LIST
</ul>
<p>
<hr/>
To remove your email address from this list, edit the
<a href=http://www.jspwiki.org:8080/Wiki/Wiki.jsp?page=SUBSCRIPTION_PAGE>SUBSCRIPTION_PAGE</a> page.
</p>
</body></html>
}]

FYI the changes are

  • org.ceryle.wiki.plugin.emailnotifier.NotifierTask.java - added authentication object
  • org.ceryle.wiki.plugin.emailnotifier.SimpleAuthenticator.java - new authentication class (used Apache Commons email as a basis for this)
  • org.ceryle.wiki.plugin.util.ParamUtil.java - fixed a bug with getBoolean

Plugin Parameters#

Usage 1 - text message, checks every 2 hours for subscribers at 10 minutes after the hour.#

Please, if you cut and paste this text, remove all linefeeds in the first paragraph and between ? and 'page' in the removal link, but you must keep two carriage returns before the start of the body
[{INSERT org.ceryle.wiki.plugin.emailnotifier.EmailNotifierPlugin
WHERE server='your.mail.server' from='your-wiki' subject='your-subject'
subscriptionPage='YourSubscriptionPage' minuteOffset='10' hourInterval='2'
changedPagePattern='* CHANGED_PAGE_NAME\n'

The following pages have changed in the last 24 hours.
----
CHANGED_PAGE_LIST
----
To remove your email address from this list, edit the SUBSCRIPTION_PAGE page.
}]

Usage 2 - html message, checks every hour for subscribers at 5 minutes after the hour.#

Please, if you cut and paste this text, remove all linefeeds in the first paragraph and between ? and 'page' in the removal link, but you must keep two carriage returns before the start of the body
[{INSERT org.ceryle.wiki.plugin.emailnotifier.EmailNotifierPlugin
WHERE server='your.mail.server' from='your-wiki' subject='your-subject'
subscriptionPage='YourSubscriptionPage' minuteOffset='5' hourInterval='1'
changedPagePattern='<li><a href=http://your-web-server:8080/YourWiki/Wiki.jsp?
page=CHANGED_PAGE_NAME>CHANGED_PAGE_NAME</a></li>\n'

<HTML><BODY>
<p>
The following pages have changed in the last 24 hours.
<p/>
<ul>
CHANGED_PAGE_LIST
</ul>
<p>
<hr/>
To remove your email address from this list, edit the
<a href=http://your-web-server:8080/YourWiki/Wiki.jsp?
page=SUBSCRIPTION_PAGE>SUBSCRIPTION_PAGE</a> page.
</p>
</body></html>
}]

The from parameter must be a valid email address with the @ symbol.


Subscription Page Syntax#

As a subscriber you will receive an email once a day listing the pages which were modified during the previous 24 hours. You can control when the email is sent and what pages are listed.

The format for a subscription line is
#

  * <user> <domain> <UTC offset for email> <page 0..n>

Where
#

*
An asterisk marks the start of a subscription line. All others are ignored
<user>
The first part of an email address before the '@' (user.name@domain.org)
<domain>
Is the last part of an email address (user@domain.org)
<UTC offset>
Is the offset in hours at which to send the mail to this subscriber
<page 0..n>
Is a space delimeted set of Wiki page names to subscribe to. Leave empty to subscribe to all changes

Example
#

  * username domain.org 9
  * username domain.org 17 Main News

The example shows the same user who wants to be emailed all page changes at 9am GMT and changes to the pages Main and News at 5pm GMT.

It appears you cannot subscribe to RecentChanges?


ContributedPlugins


You need to be sure to have at least 4 arguments. Specifically, as can be seen in the source code :

        // minimumally canidate line must have: "* name domain houroffset"...
        if (piecesArray.length < 4) return null;
        
        if (!piecesArray[0].equals( "*"))
            return null;

--AnonymousCoward, 07-Feb-2007

I copied and pasted the Code as given by you, but it shown error as Plugin Failed (or) Plugin cant find. But I pasted the .jar files in lib. Actual reason for the error is 1st line of given code is,

{INSERT org.ceryle.wiki.plugin.emailnotifier.EmailNotifier But it should end as, [{INSERT org.ceryle.wiki.plugin.emailnotifier.EmailNotifierPlugin Now error is cleared. --AnonymousCoward, 03-Nov-2008 Hello, I have copied jar files to appropriate place, added to Main page edited code above and refreshed it. After a while nothing happened. No errors in log, no email has been delivered. Where I found intel about errors? Where EmailNotifierPlugin has source codes?

Add new attachment

Only authorized users are allowed to upload new attachments.

List of attachments

Kind Attachment Name Size Version Date Modified Author Change note
zip
McKessonAps_src.zip 216.0 kB 1 07-Jul-2005 15:36 AndrewBroughton
« This page (revision-72) was last changed on 06-Nov-2008 16:12 by 194.228.205.74