Jump to content

Email notification (documentation)

Add links
From Meta, a Wikimedia project coordination wiki
This is an archived version of this page, as edited by Wikinaut (talk | contribs) at 19:43, 16 June 2005 (→‎Download). It may differ significantly from the current version.

Moved to MediaWiki.org with full history --HappyDog 20:50, 28 November 2006 (UTC)[reply]

Dear visitor:

This page describes a private extension of the current MediaWiki software called EnotifWiki. You can use EnotifWiki under the same license conditions as MediaWiki; it adds a couple of useful extentions to standard Mediawiki and you can get personal assistance for it.
The author tries to keep his version always as close to MediaWiki as possible.

 

ENotif: E-mail notification on changes of watch-listed pages, user_talk page and new pages

  • E-mail notification (ENotif) - a scheme allowing for page change or creation notifications sent as e-mail (listed as enhancement bugzilla 454) and
  • E-mail address confirmation (EConfirm) - a mechanism to confirm the stored e-mail address by mailing a link (enhancement bugzilla 866)

EConfirm: E-mail address confirmation

  • When a user adds or changes the e-mail address during account creation or on the user preferences form, the wiki sends a link for confirmation to this address; the address remains marked as unconfirmed until the user has followed the link which was mailed. All enhanced mail functions, currently a) e-mail to user and b) e-mail notification, do only send mails to confirmed addresses, and nothing is sent to unconfirmed addresses.
  • E-mail address confirmation can be used and configured independently from ENotif: enabled or disabled with the switch $wgEmailConfirmation. If the switch is set to false, messages regarding (un)confirmed addresses are suppressed, and all e-mail functions do work (if e-mails as such are enabled on this wiki) as in standard MediaWiki.
  • When using ENotif, you should always enable EConfirm. In that case, the wiki mails only to confirmed addresses.
  • E-Mail addresses of bureaucrats, developers or sysops become confirmed as they are entered, i.e. without the confirmation cycle. This behaviour can be configured (enabled as described or disabled) with switch $wgEmailConfirmationRequiredForAll.
  • The status (unconfirmed or date/time of confirmation) is always shown beneath the address on the user preferences page
  • E-mail addresses are currently not checked to be compliant with RFC-2822 when they are stored in the database. This is issue of bugzilla:959.
  • If a user changes her e-mail address to another, non-empty address, the wiki automatically sends a link for confirmation.


List of bugzillas which it influences, implements or solves

  • Bug 1932 Tracking ENotif/EConfirm & further enhancements (tracking)
add your address to the CC list of this enhancement bugzilla, if you want to be informed of any changes on one of the others
  • Bug 454 E-mail notification (EN) for page changes of watch-listed pages, user_talk page, and for new pages
add your address to the CC list of this enhancement bugzilla, if you want to be informed of changes and new versions of ENotif only
  • Bug 181 Assign lasting ID to latest revision of articles (OPEN)
  • Bug 505 Specify timezones by location, to allow automatic adjustments (OPEN; TOUCHED HERE BY INTRODUCING $wgTimeCorrectionOverwrite)
  • Bug 536 For pages on watchlist save last seen version number (OK)
  • Bug 581 treat user_talk pages as every other "normal" page (OK)
  • Bug 603 Delete + undelete cycle doesn't preserve old_id (OK in REL1_5)
  • Bug 664 UserMailer.php return-path should be correct (OK)
  • Bug 727 Number of watching users per page to be shown on recent changes view (OK)
  • Bug 782 User option "show only the current revisions of pages" suppresses listing of all older revisions of pages in recent changes view (OK)
  • Bug 804 create an LVR REPOSITORY for last-visited revisions until they are visited (OK)
  • Bug 824 user preference page: do not show help for realname if "realname" field is disabled by sysop (OK)
  • Bug 866 EConfirm (EC): e-mail address confirmation by sending a link comprising a token to the unconfirmed mailaddress (OK)
  • Bug 907 UserMailer() function revision to allow for parameters in the form "name (..) <emailaddress>" (OK)
  • Bug 952 table user got new columns user_email_confirmed, user_email_token, user_email_token_expires
  • Bug 959 Email addresses need to be checked before storing in database to comply with RFC-2822 (OPEN)
  • Bug 1116 E-mail notification for page changes or new pages, where title or body or category matches a regular expression (OPEN)
  • Bug 1133 EmailUser: additional option to send a (blind) copy to oneself (OPEN)
  • Bug 1363 Enotif Reset Nofication Flags does not work (OK)
  • Bug 1370 ENotif mails are not automatically reenabled after sent when watching users visits watched and notified page (OK)
  • Bug 1541 "mail me a new password" email has no FROM: (OK)
  • Bug 1572 Add diff link to "You have new messages" (OK)
  • Bug 1746 Subject of email-notifications must be quoted-printable. (OK)
  • Bug 1831 request for 3 CVS HEAD changes (please fix) (OK)
  • Bug 1855 waste through varchar in database (OK)
  • Bug 1876 Show "You have new messages on your user or user_talk page" -- i.e. both pages are notified (OK)
  • Bug 1891 Assign lasting ID to oldest (=first, =initial) revision of articles (OPEN)
  • Bug 1895 Recent changes views show "(last seen)" -- for "difference to my last seen revision of that page" (OK)
  • Bug 2014 ENotif code clean-up patch for REL1_5 (patchlet #1)
  • Bug 2066 adding e-mail notification for _new_ pages to ENotif patch (patchlet #2)
  • Bug 2082 Related changes views (Special:Recentchangeslinked) do not indicate one's watched page (OPEN)
  • Bug 2105 Any mediawiki mail functions are potentially blocked by missing "space"in php mail() call in UserMailer::userMailer() (OK)
  • Bug 2126 Unable to set new password after using emailed password (problem confirmed and found; will be fixed in Enotif > 3.25)
  • Bug 2259 patch for User.php: login with temp.password also indicates that the e-mail address is valid

Some of the enhancement bugs are marked as (OPEN); this means, that I will implement these enhancements in one my next versions.

"What can I expect and how does it work ?"

Basics

A single e-mail is sent to the watching user x

  • if the WikiSysop has globally enabled this feature in the DefaultSettings.php or LocalSettings.php
  • and if the user has stored an email address in the user preferences
  • and if the user has enabled the personal enotif options in the user preferences

on the event that

  • someone else changes a watched page listed in user x's watch list or
  • someone else changes the user or user_talk page of user x or
  • someone else creates a new page (if enabled by WikiSysop; a user option is shown in the preferences page)

No further mails are sent to you until you re-visit the watched page - or a difference view against it.

Update marker

All users can enjoy a side-effect of enotif - regardless whether they have enabled or disabled their personal enotif options:

  • a garish updated marker  updated (since my last visit)  indicates new contents on watch-listed pages since the last visit (of user x). The updated marker is shown on the a) watchlist page, b) recent changes page close to the bold-titled page names of pages being watched, and c) page history. Be reminded: your own changes never trigger notification mails or "updated" markers, so you are only informed about changes of somebody else, which you have not yet seen.
The marker is so garish and big to attract your attention and because it is directly linked to show you the difference between current and last seen version of that page, see below. Before complaining: you can switch it off by unchecking the corresponding option in your preferences.

improved version shows "(last seen)" to avoid "(last)"

1:  updated (since my last visit) 
Markers indicate all watched pages with unseen changes.
Markers are also direct links to the (same) difference view between the current revision of that page and the(my) last-visited revision.
They link to http://server/testwiki/index.php?title=User:Test&diff=0&oldid=1956 in the example.
2: (last seen) : a direct link to Difference between this revision and the last seen revision (lsr)
not implemented in ENotif version v2.x
These links are also active for older-than lsr revisions (e.g. you can quickly compare any arbitrary revision with the version, you saw last)
Only watched pages having unseen changes bear active (last seen) links; in the example you see some black inactive (last seen) links, because these pages are not watched pages. They cannot show unseen changes, because only watched pages offer information about last seen revision, which is used to determine unseen changes of any watching the user.
3:   (last seen)   :
The(my) last visited revision of that page
not implemented in ENotif version v2.x
4: [4] :
Number of users watching that page
currently switched off in testwiki

See further screenshots on the versions page.

Features

  • The ENotif patch was developed for small- to medium-scale MediaWiki implementations. Personalised e-mails (with recipient's name; times expressed in local time of the recipients) for every watching user. [The program flow will be changed in next versions to allow bulk notification mails to be sent, depending on parameters, to save processing time and bandwidth.]
  • The sub-feature notification on user_talk page (UTP) changes could be enabled even for the largest WikiPedia, because the number of UTP changes is surprisingly low - according to Brion Vibber. About 800 alien UTP changes (changes by others than yourself) per day have been counted in August 2004, which would result in the same (relatively low) number of enotifs sent to the UTP owners.
  • All features are configurable (enable/disable) in module DefaultSettings.php respectively LocalSettings.php for the WikiSysop, who can separately allow or disallow notifications for
    1. changes of pages in all name spaces (AO/UO) and/or
    2. changes of user and user_talk pages (AO/UO)
    3. creation of new pages (AO/SO/UO)
user preferences with an authenticated e-mail address and the new page notification option
  • Implements and solves
Bug 1572 Add diff link to "You have new messages" (OK)
Bug 1876 Show "You have new messages on your user or user_talk page" -- i.e. both pages are notified (OK)

(AO) admin option:
allows to disable or fine-tune these extensions globally
(SO) special user option:
for bureaucrats, developers and sysops only
(UO) user option:
if the admin option enables the feature globally, a user option in user preferences is shown and allows the users to opt-in or opt-out to this feature at their discretion.
  • The subject line and text of the notification message are pages in the MediaWiki:namespace and can therefore be changed live by Sysops. You can use several named $variables such as $PAGEEDITOR, see example below.
  • The notification message contains a direkt link to the difference view (last seen) between the current page version and the last one the watching user has seen i.e. the page version just before the page change notification was sent. Remark: the (last seen) link is valid forever, because page revision identifiers are now sticky (permanent), they survive delete/undelete cycles since REL1_5 (this is not the case in older MediaWiki versions).
  • Your own page changes or creation of a page (if enabled) never trigger a notification mail sent to yourself.
  • Minor edits may trigger notification e-mails sent out depending on your preferences (AO/UO).
  • All UTP changes trigger a notification to be sent, no matter whether the changing editor declared the change as minor edit or not.
  • Only one mail is sent on the first page change. Further mails are suppressed until you re-visit the changed page or until you reset all notification flags. A new button has been introduced for this purpose on the watchlist page.
  • On the watchlist page, a new marker  updated (since my last visit)  indicates such watched pages for which a notification mail was sent, meaning that the page has new contents since your last visit (AO/UO).
  • The marker is also shown on your recent changes page and on page history pages for the pages watched by you (already marked bold) and which do have new contents since your last visit (AO/UO).
  • Recent changes view and page(article) footers show number of watching users (AO/UO).
  • If you wish, you can add not-yet existing page names as usual to your watch list and you will receive an email notification as someone creates a page with that name. You will see the updated marker for the page until you actually visit that page.
  • Debuggers can activate server beeps on notification mails, this is disabled by default. (AO)

Prerequisites

You definitely need a working php mail() system on your server. I suggest you quickly check your current wiki installation before trying the E-mail notification patch. Try requesting a temporary password for your wiki user account by clicking the button mail me a temporary password on the wiki login screen. If you soon later receive an e-mail from your "old" wiki, everything looks fine and ready for the installation of ENotif.

ENotif/EConfirm has been developed to work smoothly with

  • php mail()
    thus it is not using the PEAR:Mail() module; see /includes/UserMailer.php
    $wgSMTP = false;

and

  • MySQL database server
    thus it is not checked to work with PostgreSQL
    $wgDBtype = "mysql";
    $wgSearchType = "MyISAM";

For further information such as

  • how to configure the php mail()
  • Why do I need to set up a sender address information ("FROM:")
  • and how to configure MySQL

please consult /includes/DefaultSettings.php

If you want to use it together with PEAR:Mail and/or PostgreSQL

Code security and general issues

The code was peer-reviewed several times and the version 2.00 was committed to CVS HEAD (version 1.5) in December 2004. However, since then, several persons have modified this and that in the CVS HEAD version, which could have led to a non-working version in CVS.

I always publish a complete diff on the accompanying ENotif bugzilla.

►►► "It does not work": common pitfalls

  • Avoid the most common pitfalls from the beginning and read carefully:

Be aware, that

  1. your wiki e-mail system must be working as such - test it by mailing you a temporary password (this is independent from ENotif)
  2. you obviously need an e-mail address - check the address field in user preferences
  3. e-mail address must be marked as confirmed (if EConfirm is mandatory on your wiki)
  4. there are never notifications for your own changes. Change a page watched by A as other user B and check, whether an ENotif is sent to watching user A.
  5. only one ENotif is sent for the first page change of a page you are watching or, when a new page is created (if this feature is enabled)
  6. notification is automatically re-enabled when you visit the current version of the page or the difference view to the current version
  7. you also can clear all notification flags at one click (button on your watchlist)
  8. you need to update the text message cache, if you have customized test strings in a LanguageXX.php file

Inside ENotif and EConfirm

Download

Available versions (see also version history)
see EnotifWiki file release download section on Sourceforge
For MediaWiki developers version (CVS HEAD REL1_5) ENotif/EConfirm v.2.x
  • checkout or update from CVS.
  • This is the version of testwiki, where you can play with it.

ENotif/EConfirm v3.x for CVS REL1_5 alpha1

For MediaWiki version 1.4.5 (CVS REL1_5) http://prdownloads.sourceforge.net/enotifwiki/mediawiki-1.4.5%2Benotifwiki-enea310.tgz?download
This version uses e-mail authentication, which mails a "temporary password", the regular password not being touched by this)
This is changed in newer versions of ENotif for mw 1.5.x.

I as the developer of Enotif would recommend to you to use the better mechanism which is implemented in the version ENotif/EConfirm v3.x for CVS REL1_5 alpha1 - see above

For MediaWiki version 1.4.4 (CVS REL1_4) http://www.wikinaut.de/mw/mw144+en309a.tgz
This version uses e-mail authentication, which mails a "temporary password", the regular password not being touched by this)
This is changed in newer versions of ENotif for mw 1.5.x.

I as the developer of Enotif would recommend to you to use the better mechanism which is implemented in the version ENotif/EConfirm v3.x for CVS REL1_5 alpha1 - see above

For MediaWiki version 1.4.2 (CVS REL1_4) http://www.wikinaut.de/mw/mw142+enea.tgz
This version uses e-mail authentication, which mails a "temporary password", the regular password not being touched by this)
This is changed in newer versions of ENotif for mw 1.5.x.

I as the developer of Enotif would recommend to you to use the better mechanism which is implemented in the version ENotif/EConfirm v3.x for CVS REL1_5 alpha1 - see above

For older MediaWiki versions See my archive or contact me.

Installation

Implementation details and flowcharts

Release Notes

Configuration

ENotif configuration: sysop settings in /includes/DefaultSettings.php

  • in LocalSettings.php or DefaultSettings.php
  • (coming soon)

Notification mail (text templates and variables therein)

  • In languages/Language.php, amongst other new constants, there are two important text templates with $VARIABLES, which get substituted with values when the ENotif mails are composed. The text templates are shown here for the sake of completeness of the documentation, so that you know in advance, what you can change.
  • Please consult /includes/UserMailer.php if you are curious to learn where the variables such as $PAGEEDITOR get their values from, but you usually don't have to study this file.
  • If you encounter problems with the message cache - e.g. that your changes on LanguageXX.php are not effective and do not work - please consult the pages you get with this search on MetaWiki. It is standard MediaWiki procedure, that you need to run an update program in certain cases !
MediaWiki:email_notification_body

This is the text template for the body of the notification mails. It resides in file /languages/Language.php and can be adapted by yourself according to your needs. You can change the text before or after the installation of your EnotifWiki. However, when you changed the text in the file /languages/Language.php after the installation, then it might be necessary to run once the program

run /maintenance/php rebuildMessages.php --rebuild

as explained above. This might take a few seconds. A detailed explanation, why this might be necessary, can be found on here.

Alternatively, you can also change the text live on your wiki by editing the page [[MediaWiki:email_notification_body]], but such a change must be done for every wiki, if you run several wikis. 

Dear $WATCHINGUSERNAME,

the {{SITENAME}} page $PAGETITLE has been $CHANGEDORCREATED on $PAGEEDITDATE by $PAGEEDITOR,
see {{SERVER}}{{localurl:$PAGETITLE_RAWURL}} for the current version.

$NEWPAGE

Editor\'s summary: $PAGESUMMARY $PAGEMINOREDIT

Contact the editor:

mail {{SERVER}}{{localurl:Special:Emailuser|target=$PAGEEDITOR_RAWURL}}
wiki {{SERVER}}{{localurl:User:$PAGEEDITOR_RAWURL}}

There will be no other notifications in case of further changes unless you visit this page.
You could also reset the notification flags for all your watched pages on your watchlist.

             Your friendly {{SITENAME}} notification system

---
To change your watchlist settings, visit
{{SERVER}}{{localurl:Special:Watchlist|magic=yes}}

Feedback and further assistance:
{{SERVER}}{{localurl:WikiHelpdesk}}'
MediaWiki:email_notification_subject

The previous section explains how you can change this text (change file /language/Language.php and run a maintenance program, or edit page [[MediaWiki:email_notification_subject]]). 

{{SITENAME}} page $PAGETITLE has been $CHANGEDORCREATED by $PAGEEDITOR

Notification mail (sample)

  • The subject text comes from language/Language.php MediaWiki:email_notification_subject as described above
  • The body text comes from languages/Language.php MediaWiki:email_notification_body as described above
  • This comprehensive (and therefore heavy) example shows all possibilities. If you wish to shorten the mail, you need to edit the Language.php file(s) or to change the mentioned MediaWiki: pages in your live system.

Example for a typical email notification message 

MIME-Version: 1.0
Content-type: text/plain; charset=utf-8
X-Mailer: MediaWiki mailer

    From: WikiAdmin <admin@myserver.com>
Reply-To: reply@not.possible
      To: Albert Einstein <user@userdomain.de>
 Subject: Testwiki page Main Page has been changed by TestUser

Dear Albert Einstein,

the Testwiki page Main_Page has been changed on 21:25:06, 19 Apr 2005 by TestUser,
see http://www.myserver.com/testwiki/index.php/Main_Page for the current version.

See http://www.myserver.com/testwiki/index.php?title=Main_Page&diff=0&oldid=9807 for all changes since your last visit.

Editor's summary: typo correction: I like ENotif 

Contact the editor:
mail http://www.myserver.com/testwiki/index.php?title=Special:Emailuser&target=TestUser
wiki http://www.myserver.com/testwiki/index.php/User:TestUser

There will be no other notifications in case of further changes unless you visit this page.
You could also reset the notification flags for all your watched pages on your watchlist.

             Your friendly Testwiki notification system

---
To change your watchlist settings, visit
http://www.myserver.com/testwiki/index.php?title=Special:Watchlist&magic=yes

Feedback and further assistance:
http://www.myserver.com/testwiki/index.php/WikiHelpdesk

Internationalisation (I18N)

Retrieved from "https://meta.wikimedia.org/w/index.php?title=Email_notification_(documentation)&oldid=143313"