Notifications Application

The XWiki Notifications Application allows to subscribe to wiki pages or even whole wikis and thus receive realtime alerts and email notifications whenever a modification occurs. 

The Notifications Application is currently experimental and it is meant to replace the Watchlist Application in future XWiki releases.

Watch XWiki Entities

In order to receive alerts when a page has been modified by someone else you first have to add it to your favorites. To do so, click the bell icon in the top menu bar to expand the notifications menu, then click the "ON" button next to:

  • the file icon to watch just the current page
  • the sitemap icon to watch the current nested page and its child pages
  • the globe icon to add the entire wiki to favorites

WatchlistSettings.png

Alerts

Whenever someone else modifies a page in your favorites list, posts a blog article or submits a comment, you will see a number of notifications displayed on the top menu bar, just above the bell icon. In case there are more than 20 unread alert messages, you will see the value 20+.

NotificationsBar.pngNotifications20.png

To mark a notification as "read" simply click the "checked" button - the button will then disappear and the background color will turn white. In case you wish to mark all notifications sent so far as read, click on "Clear all".

NotificationRead.png

Similar notifications are grouped together in order to avoid a batch of identical content. This is why only one notification is displayed, but it is possible to list all activities (if any) by expanding the "Details" section.

Finally, you may subscribe to the RSS feed of the wiki notifications, either through your notifications center settings or directly by clicking the "RSS Feed" link.

Coexistence with the Watchlist Application

If the Watchlist Application is installed, you will see two rows of buttons and settings in the menu: the first for the watch list, and the second for the notifications. Similarly, the "Settings" panel in your user profile page will display 2 categories: Watchlist and Notifications.

WatchedEntitiesWithWatchlist.pngWatchedEntitiesWithWatchlistUser.png

You will also receive 2 sets of emails: one from the Watchlist, and one from the Notifications Application. To avoid conflict, the "Watched Entities" feature is disabled by default. This is why we recommend to uninstall the Watchlist Application using the Extension Manager, then to enable the "Watched Entities" feature as follows:

  • edit the "WEB-INF/xwiki.properties" file
  • uncomment the parameter "otifications.watchedEntities.enabled" and set it to "true"
  • restart XWiki
If you upgraded your XWiki, all the pages that you watched in the Watchlist Application are automatically watched by the Notifications Application, thanks to the Notifications - Watchlist Bridge Module.

Notifications Settings

The "Settings" link in the alerts menu redirects to the "Notifications" section in your user profile page where both in-wiki alerts and email notifications are turned off by default. To enable notifications:

  • click the bell icon to enable notifications for all event types OR
  • click the downward arrow icon and for each application and enable / disable notifications for the event types you are interested in: a blog article is published, a page is created, edited or deleted, a comment is submitted. 

NotificationApplications.png

Check the table below to learn what each switch button means:

Toggle ButtonComment
AllDisabled.pngNotifications disabled for all event types
PartiallyEnabled.pngNotifications enabled for some event types
AllEnabled.pngNotifications enabled for all event types

Set the Email Frequency

The "Email Frequency" drop-down list in the "Email Preferences" section allows you to choose how often you will receive email notifications regarding the activity in your wiki or farm. The 4 available options are:

  • Hourly
  • Daily
  • Weekly
  • Live

EmailPreferences.png

Automatic Watch

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:

  • Never
  • Every time I make a modification - any change on any wiki page generates notifications
  • Every time I make a major modification - only the major changes generate notifications
  • Only when I create a new page - the notifications are generated only when new wiki pages are created

AutomaticDocumentWatching.png

Filters

The "Filters" livetable displays the list of wikis, page hierarchies or single pages added to favorites and allows you to restrict on witch locations you want to receive notifications, for each event type. To remove an element from the list, click on the red "X" button in the "Actions" column.

FiltersUserProfile.png

To create a filter, click on "+ Add filter" and fill in the form fields:

  • "Filter type" - can be inclusive or exclusive, meaning that notifications that come from a page that matches an exclusive filter will then be discarded. Exclusive filters take precedence over the inclusive ones.
  • "Notification Format" - whether the notification should be sent as alert, email or both.
  • "Event type" - the event(s) targeted by the filter:
    • a blog post is published
    • a new page is created
    • a page is modified or deleted
    • a comment is submitted 
  • "Filter Scope" - the page(s) targeted by the filter. Note that when you select a nested page, the filter will also apply for the child pages.

NewFilterForm.png

The new filter will appear as enabled in your notifications center.

NewFilterAdded.png

The same behavior applies to system filters - they are enabled by default. However, you may disable them by clicking on "Advanced filtering options" and unchecking the corresponding button in the "Toggle" column.

DisableDefaultFilter.png

Live Notifications

The "Live" option is 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

The wiki administrators can also define a "grace time" for live email notifications meaning that when an event that triggers a notification is sent, the platform will wait for the duration of this grace time before sending a notification email. If during this interval, a new event of the same kind is sent, the two events will be grouped in the same email. To set up a grace time:

  • edit the "WEB-INF/xwiki.properties" file
  • uncomment the parameter "notifications.emails.live.graceTime" and set it to a new value in minutes (by default it is set to 10 minutes)
  • restart XWiki

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.

         

Search this space