Watchlist Application
Subscribe to pages, spaces and wikis and receive RSS and email notifications when they are modified |
Type | XAR |
Category | Application |
Developed by | |
Rating | |
License | GNU Lesser General Public License 2.1 |
Table of contents
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.
Realtime option is currently experimental and disabled by default.
TheTo enable the feature for testing purposes, edit xwiki.properties and set watchlist.realtime.enabled to true.
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
- New comments
- Rights
- Blog Posts
- Published blog post
- Generic "updated object" for an object update not handled by any of the cases above
- Comments or Annotations
- 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 (wiki:space.page combination) but located on different XWiki instances will be grouped under the same email thread by the email client.
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.
To fix this, you need to configure theAdministrators: 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:
Binding | Data Type | Notes |
---|---|---|
previousFireTime | Date | The last time the current notification was triggered and delivered to the subscribers. |
events | List of WatchListEvent | One 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. |
modifiedDocuments | List of String | List 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_name | String | the subscriber's (i.e. user receiving the message) first name, to be used when addressing him. |
last_name | String | the subscriber's (i.e. user receiving the message) last name, to be used when addressing him. |
subscriberReference | DocumentReference | the subscriber's (i.e. user receiving the message) reference, to be used when unsubscribe URL is created. |
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
xwiki.properties and to change the following lines:
, you can disable the application without uninstalling it. All you need to do is to edit the file#-# [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