%%(font-size:75%;color:gray;padding-bottom:1em) 
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|JohnVolkar] 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

# Download and install CeryleWikiPlugins
# Restart JSPWiki
# Edit e.g. your main page and add the plugin tag, see Plugin Parameters below
# Set the parameters as appropriate for your site
# If after adding the plugin all you see is {{org/apache/log4j/Logger}} you need a newer version of [Log4j]
# If your web application server does not contain {{mail.jar}} and {{activation.jar}} from [javamail|http://java.sun.com/products/javamail/], you must add it.
# 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?