[pmwiki-users] email notification of page changes (watchlists)

Patrick R. Michaud pmichaud at pobox.com
Fri May 26 13:01:01 CDT 2006

On pmwiki.org I now have a preliminary implementation of edit
notifications via email.  These allow the creation of custom
"watch lists", with notification emails sent in response to
modifications of pages of interest (i.e., "watchlists").

This feature is currently enabled on pmwiki.org, for those who would
like to experiment with the feature or start watching pmwiki pages.

Watch lists are configured via the Site.NotifyList page.
(For those who want to experiment with this on pmwiki.org, the
password for Site.NotifyList is "quick".) The most basic entry 
in the NotifyList page sends email for any page that changes 
on the site:

    notify=alice at example.com

This causes alice at example.com to start receiving email messages
with lists of pages that have been modified.  Of course, Alice
probably doesn't want to receive a separate message for every 
edit that takes place, so multiple edits are batched together 
according to a 'squelch' setting (similar to the way MailPosts
works now).  The squelch setting indicates the minimum
number of seconds that must elapse after each notify message 
before another is sent.   PmWiki's default squelch is 
10800 seconds (3 hours), so after Alice receives a 
notification email, any edits that take place during the 
next three hours will be batched together and then sent
as a single message.

Alice can change the squelch parameter for her messages.  To
receive at most one notify message per day, Alice would use

    notify=alice at example.com squelch=86400

What if we have someone who wants to watch only a certain set of
pages?  There are several ways to do this.  First, we can specify
a trail with pages to be watched:

    notify=bob at example.com trail=Profiles.Bob

This sends Bob email notifications only for pages listed in the
trail at Profiles.Bob.  This makes it easy for Bob to adjust the
pages he's interested in by simply editing the Profiles.Bob page.

This also means a wiki administrator can control who is allowed
to receive notifications (by restricting editing of the Site.NotifyList
page), while still allowing non-administrators to maintain custom
watch list trails.

Any trail will work, thus to keep track of changes to the PmWiki

    notify=charles at example.com trail=PmWiki.DocumentationIndex

One can also use the "group=", "name=", and "link=" options to
specify watch lists by group (wildcarded), name (wildcarded), or
target link:

    ##   watch pages in Cookbook, PmWiki, and PITS:
    notify=dave at example.com group=Cookbook,PmWiki,PITS

    ##   watch changes to pages in the Skins category
    notify=edward at example.com link=Category.Skins

Multiple email addresses may be specified in the notify line...

    ##   tell admin and myboss about all changes
    notify=admin at example.com,myboss at company.com

...and its okay for an email address to appear on multiple lines.

    ##   tell frank at example.com about Cookbook and Profiles.Frank changes
    notify=frank at example.com group=Cookbook
    notify=frank at example.com name=Profiles.Frank

(If a 'squelch' option appears multiple times for a given
email address, the last one is used.)

There are probably a few details I've left out, but this should be
enough to get things started.  I have a bit more testing to do, but
I'm expecting this to be included in the 2.1.7 release.  

Also note that this is just the first step of the overall plan I wrote 
in http://www.pmichaud.com/pipermail/pmwiki-users/2006-March/023990.html .
At some point in the future we can add features to obfuscate email 
addresses in the Site.NotifyList page, forms for adding and verifying
email addresses to that page, links to add pages to watchlists, etc.

Comments, questions, suggestions welcomed as always.


More information about the pmwiki-users mailing list