Watchlist Application

The XWiki Watchlist Application uses the new Mail Sender API and allows to subscribe to pages and wikis and thus receive RSS and email notifications when they are modified.

Starting with XWiki Enterprise 7.4, a new notifications menu was added to the top bar, represented by a bell icon which in the future will be the place where you can find notifications about wiki events like personal messages, page changes and so on.

NotificationsMenu.png 

Add a Wiki to Favorites

To watch a wiki, click the bell icon in the top menu bar which expands the notifications menu and hit the "Off" button next to the globe icon.

WatchWiki.png

To remove the wiki from favorites, simply click the "On" button next to the globe icon.

UnwatchWiki.png

Add a Nested Page and Its Children to Favorites

To watch a nested page and all its children, click the bell icon in the top menu bar which expands the notifications menu and hit the "Off" button next to the sitemap icon.

WatchNestedPage.png

To remove a nested page from favorites (and implicitly all of its children), click the bell icon, then on the "On" button next to the sitemap icon.

UnwatchNestedPage.png

Add a Single Page to Favorites

To watch a single page, either nested or terminal, click the bell icon in the top menu bar which expands the notifications menu and hit the "Off" button next to the file icon.

WatchPage.png

To remove a page from favorites, click the bell icon, then on the "On" button next to the file icon.

UnwatchPage.png

Browse the List of Watched Elements

To manage your watchlist, click your user avatar menu in the top menu bar,

ProfileMenuMyDashboardOption.png

then, in your user profile page, click on the tab "Watchlist" under "Settings".

The wikis, page hierarchies or single pages added to favorites will be displayed in the "Watched elements" live table on your profile. To remove an element from the list, click on the "X" red icon in the "Actions" column.

Watchlist.png

Starting with version 7.2, XWiki has adopted the Nested Pages paradigm. As a consequence, the "Wiki", "Space" and "Document name" livetable columns were merged into a "Location" column. Just like the breadcrumb, this column displays the location of the page in the reference hierarchy.

You can get notifications regarding activity on watched elements using RSS feeds by clicking on "Last modifications feed for your watchlist".

WatchlistRSS.png

Set the Email Frequency

The "Notifier" drop-down list in the "Watchlist Preferences" section allows you to choose the frequency of the email notifications regarding the activity in your wiki or farm. To change the delay, click on the yellow pen located in the top right corner of the section.

WatchlistPreferencesEdit.png

The 4 available options are:

  • Hourly
  • Daily
  • Weekly
  • Realtime

Realtime Notifications

The "Realtime" option has been introduced in XWiki Enterprise 7.x but it currently experimental, which is why it is disabled by default. To enable it, edit the "WEB-INF/xwiki.properties" configuration file, uncomment the parameterwatchlist.realtime.enabled, set it to true and restart XWiki.

The events that are currently triggering realtime notifications include:

  • pages created and deleted
  • page updates including: content and metadata modification, attachments added, edited or deleted.
  • class and object changes including:
    • new comments
    • replies to an existing comment
    • comment updated, either the current user's own comment or one of another user
    • comment deleted, either the current user's own comment or one of another user
    • rights changes
    • blog post changes, more specifically a blog post being published
    • generic "updated an object" events for an object update not handled by any of the cases above
  • generic "updated document" events for an update not handled by any of the cases above

In the below gallery, you can see dedicated screenshots for some of the previously mentioned events.

As shown in the screenshots, the notification message tries to reference the page by its type which is determined using the class sheet system. To be more specific, if an existing object has a class on which a sheet binding is set, then the class gives the page type. For instance, the page "Blog.BlogIntroduction" has an attached object of the class "Blog.BlogPostClass" which has an "XWiki.ClassSheetBinding" pointing to "Blog.BlogPostSheet".

ClassBindingSheet.png

This means that the class "Blog.BlogPostClass" gives the type of the page "Blog.BlogIntroduction". To obtain the type string, strip the "Class" suffix, split the camel case and lower-case the result, which gives "blog post". So, the notification message won't state that "User X deleted the document Blog.BlogIntroduction", but that "User X deleted the blog post Blog.BlogIntroduction". For more details about the class sheet binding system, please refer to the "XWiki Data Model" documentation which is linked below "Related Pages".

When multiple Realtime notification emails are received regarding the same page, they will be grouped by page and by email client.

Watch List Email Template

A default email notification message looks like in the image below:

WatchlistNotificationEmail.png

The template used for watchlist notifications is stored in the "XWiki.Mail" object attached to the page "XWiki.WatchListMessage" which has 4 properties:

  • Subject - the subject of the email message
  • Language - the language of the message. This allows having multiple "XWiki.Mail" objects, each for a given language.
  • Text - the content of the message for the case when the mail client displays the mail as plain text.
  • HTML - the content of the message for the case when the mail client displays the mail as HTML.

WatchlistNotificationEmailTemplate.png

For Realtime notifications, we use another template, namely "XWiki.WatchListRealtimeMessage" which also has an "XWiki.Mail" object attached with the same 4 properties and the standard template. The only differences are in the code.

RealtimeNotificationEmailTemplate.png

Automatic Watch

The "Watchlist Preferences" section also contains a drop-down list dedicated to the automatic page watching. By default, the automatic watch feature is disabled, but you can enable it by choosing one of the other 4 options from the "Automatic Page Watching" drop-down list:

  • Default - any major edit on a page or any page creation generates notifications
  • Any modification - any change on any wiki page generates notifications
  • Major modifications - only the major changes generate notifications
  • New pages - the notifications are generated only when new wiki pages are created

AutomaticDocumentWatching.png

           

Search this space