Subscribe to pages, spaces and wikis and receive RSS and email notifications when they are modified

Description

The watchlist features can be accessed easily by clicking on their corresponding button. The 4 available entries are:

• Watch this page: you follow modifications affecting the page you are currently viewing
• Watch the current space: you follow the modifications taking place on the whole space you are currently looking at
• Watch the current wiki: you follow modifications taking place on the whole wiki
• Manage your watchlist: change your notification preferences

Starting with XWiki Enterprise 2.5 you can notice a redesign in the action menus. 

Before XWiki 7.4M1, the Watchlist application is available from the notifications menu, in the top bar. Its features can be accessed easily by hovering over the button. The 3 entries available are grouped together:

To manage your watchlist, you can go to your profile and then clicking on "Watchlist" in the left menu:

Managing your watchlist

After clicking on the "Manage your watchlist" button, you get access to a page where you can set your personal notification preferences.

Administrators: Configuring your wiki to send email notifications

Should users be notified by mail when documents on their watchlist are updated, the wiki instance must be set up to send mails. For this go to section "Email" in the Wiki Administration and fill in the following fields:

• Server
• Port
• User (optional)
• Password (optional)
• JavaMail properties (optional)

For more details about configuring authentication for SMTP you can check out the Administration Guide.

Once you have configured the SMTP settings your users can start watching pages, spaces or even the whole wiki. They will receive an e-mail summing up changes. 

The e-mail is send to the e-mail-address users set up in their profile. If a single user prefers not to get e-mail notificationm, the e-mail-address can be left empty, or the notification frequency set to never by chosing the empty notifier (see next section).  
 

Setting the email delay

Depending on your preferences, you can set the email frequency to:

• Realtime (since 7.0RC1)
• One hour
• One day
• One week

To change the frequency follow these steps:

• Hover over "Profile"
• Click "Watchlist"
• Click on the small pencil icon located to the right of the "Watchlist Preferences" section
• Select the desired frequency from the "Notifier" drop-down list

Realtime notifications

Realtime Watchlist notifications allow you to receive an email notification as soon as a page you are watching has been modified by someone else.

Since 7.0RC1 The Realtime option is currently experimental and disabled by default.

To enable the feature for testing purposes, edit xwiki.properties and set watchlist.realtime.enabled to true.

Until 7.1M1 The initial implementation added a considerable performance penalty to any document modification that triggered a real time notification (scaling with the more users inside the wiki using the feature). The feature is still under testing, but it will be soon enabled by default.

Supported displayers

In addition to this, the message will try to reference the document by its type. A document's type is determined by using the class sheet system: if an object exists which has a class on which a sheet binding is set, it is determined that the class gives the type of the document. Example: The document 'Blog.BlogIntroduction' has an object of class 'Blog.BlogPostClass' which has an XWiki.ClassSheetBinding pointing to 'Blog.BlogPostSheet'. This means that the class 'Blog.BlogPostClass' gives the type of the document 'Blog.BlogIntroduction'. We now take the class name 'BlogPostClass', strip the 'Class' suffix, split by camel case and the lower case the result and we end up with 'blog post'. This will be the type of the document and instead of saying "user X deleted the document Blog.BlogIntroduction", we will say "user X deleted the blog post Blog.BlogIntroduction".

This obviously needs to be improved by accepting translations for various languages, based on the class name, and leaving the string manipulation on class name described above to only be performed in the absence of a translation.

Threaded mails per document

When multiple realtime notification emails are received regarding the same document, they will be threaded/grouped by document by the email client:

Multiple XWiki instances on the same machine

If you are running multiple XWiki instances from the same physical machine, you might observe that realtime notification emails for documents having the same name (wiki:space.page combination) but located on different XWiki instances will be grouped under the same email thread by the email client.

Since 7.1 To fix this, you need to configure the Mail Application of one of the two XWiki instances and specify the JavaMail configuration properties in order to be able to distinguish between the 2 instances running on the same machine. The relevant properties are mail.from, mail.user and mail.host. Modifying any of these properties will result in a new type of identifier being generated for the emails sent by the current XWiki instance, thus achieving our objective of differentiating between the 2 XWiki instance running on the same machine and achieving proper email threading in the email client. Of course, this assumes that the email client properly interprets the email identification headers.

Administrators: Customizing the WatchList email template

The template used for watchlist email notifications is customizable. It is stored in an XWiki.Mail object inside the page:

• XWiki.WatchListMessage for scheduled notifications (i.e. hourly, daily, weekly)
• XWiki.WatchListRealtimeMessage for realtime notifications

The XWiki.Mail object has 4 fields:

• Subject: the subject of the mail
• Language: the language in which the Text and HTML fields (see below) are written in. This is to allow to have several XWiki.Mail objects, each for a given language
• Text: the content of the mail when the mail client displays the mail as text
• HTML: the content of the mail when the mail client displays the mail as HTML

When customizing a watchlist message template, you will be writing Velocity code and, in addition to the standard bindings (XWiki API, Script Services, Velocity Tools, etc.), you will also have access to the following WatchList specific bindings:

Auto Watch

Starting with 3.1 an automatic watch is enabled. That mean that each time a user do a major modification to a document or create one it's automatically added in the user watchlist. That way it's easy to follow future contribution to a document in which we are involved on.

It's possible to control its level of action or disable it in xwiki.cfg (xwiki.plugin.watchlist.automaticwatch) or for each user in his profile page (Note that a default value in the profile page means that it uses the setting configured in xwiki.cfg):

• none: never automatically add document in watchlist
• all: add to watchlist any modified document
• major: add to watchlist only document which are not edited as minor edit. That's the default mode.
• new: add to watchlist only newly created documents

Watchlist macro

Starting with 6.0 the Watchlist can be displayed on any document by inserting the {{watchlist}} macro into the documents content. This can be useful especially as a dashboard widget.

Example usage:

If e.g. the watchlist macro is used on the dashboard for the main page, users can see the pages they watch directly after login

Enabling/Disabling the application

Since 9.11.2 and 10.0, you can disable the application without uninstalling it. All you need to do is to edit the file xwiki.properties and to change the following lines: