Watchlist Application

Last modified by Simon Urli on 2024/06/04 08:45

watchlist.pngSubscribe to pages, spaces and wikis and receive RSS and email notifications when they are modified
Developed by

XWiki Development Team

2 Votes
LicenseGNU Lesser General Public License 2.1


Since 11.1RC1, Watchlist Application is deprecated and not installed by default on XWiki. It has been replaced by the Notifications Application

For older versions but beyond 10.1RC1 and 9.11.4, the Watchlist Application was installed but disabled by default in XWiki. See how to enable it anyway.

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:

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

  • Watch this page
  • Watch the current space
  • Watch the current wiki
  • Manage your watchlist

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 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

  • Document created
  • Document deleted
  • Document updated
    • Document content
    • Document metadata
    • Document attachments
      • Attachments added
      • Attachments updated
      • Attachments deleted
    • Document class
    • Document objects
      • More than 1 object
      • 1 object
        • Comments or Annotations
          • New comments
            • New comment by guest user
          • New reply comment
            • New comment in reply to a guest user's comment
          • Updated comment
            • Updated own comment
            • Updated someone else's comment
          • Removed comment
            • Removed own comment
            • Removed someone else's comment
        • Rights
        • Blog Posts
          • Published blog post
        • Generic "updated object" for an object update not handled by any of the cases above
    • Generic "updated document" for an update not handled by any of the cases above

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 ( 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 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:

BindingData TypeNotes
previousFireTimeDateThe last time the current notification was triggered and delivered to the subscribers.
eventsList of WatchListEventOne event per modified document. For Realtime notifications, there will always be 1 event to display, while for Scheduled notifications there can be more than 1.
modifiedDocumentsList of StringList of prefixed full names of the documents that were modified. Again, for a realtime notification, this list will always contain just 1 document name.
first_nameStringthe subscriber's (i.e. user receiving the message) first name, to be used when addressing him.
last_nameStringthe subscriber's (i.e. user receiving the message) last name, to be used when addressing him.
subscriberReferenceDocumentReferencethe subscriber's (i.e. user receiving the message) reference, to be used when unsubscribe URL is created. Since 7.4.2. Before (6.4.8+) you had to use subscriber which was a String value.

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

The watchlist macro is no longer available but you can replace it with the macro dedicated to manage the notifications filters:
For more information see the Notification Application documentation.

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 and to change the following lines: 

#-# [Since 10.0]
#-# [Since 9.11.2]
#-# Controls if the notifications feature is enabled. Default value is true.
#-# Thanks to this option, you can disable the application without uninstalling it.
watchlist.enabled = false

Get Connected