Notifications Application
 | Display notifications about events happening in the wiki. |
| Type | XAR |
| Category | Application |
| Developed by | |
| Rating | |
| License | GNU Lesser General Public License 2.1 |
| Bundled With | XWiki Standard |
Table of contents
Description
This application contributes content in the Alert menu (contributed by the Alerts Application) in the top bar, represented by a bell:
You can find under this menu the notifications about some events happening on the wiki (a page has been modified, a new blog post has been posted, etc...).
The number of notifications is displayed on the top menu, just above the bell:
If you have more than 20 unread notifications, you will not see the real count but this instead:
When you open the menu, the content of the notifications is loaded:
Then you can see the list of notifications:
If you click on the little button with the "check" icon, you mark the notification as "read".
When the notification is read, the button disappear and the background color changes:
The "Clear All" link will remove all notifications that were sent till now.
When no notification is available, you will see the following:
Group of notifications with details
Similar notifications are grouped together in order to avoid a batch of identical content. Only one notification is displayed, and it is possible to see the details of all activities in the "Details" section (if any).
XWiki 15.5+ We started to expose different ways of grouping notifications. All the details can be found on the dedicated page about Notification Grouping Strategies.
Get a notification RSS feed
You can get a RSS feed of the notifications occurring in your wiki. This feed can be accessed either through a link in your notification tray (or at the bottom of the notifications macro).
Notifications Macro
The Notifications Macro is provided by its own application.
Settings
On the notifications menu, you also have a link to go to the "settings" of the notifications: those settings are also available from your user profile.
By default, users only get notifications when they are mentioned or when actions are performed on pages they created or updated. For receiving other notifications, you need to select which "types" of notifications you want to receive. When a page is created? When a blog post is published?
You can enable or disable all notification types that belong to a particular application by clicking on the bells associated to this application. By default all notifications types are enabled. If some types are enabled and other are disabled inside an application, the switch looks like the next screenshot, meaning that the application's notifications are partially enabled:
Note that you only receive notifications that occur after you turn on the notifications types.
Watched Entities
You can also decide to watch some entities. Either a location (a page, a page with its children or a wiki) or a user.
Using it
XWiki 16.5.0+
A button is present in all pages next to the edit button. This buttons shows by default the current state of the page:
- Followed: if you're following the page to receive notifications about it
- Blocked: if you're blocking the page to not receive notifications about it
- Not set: in case you haven't set any preferences for watching or blocking it
- Custom: this appear if you have some preferences corresponding to that page but that are specific to some specific event types, or some specific formats (e.g. you only want to receive some notifications by email for a specific location).
If you click on the button, you will obtain a modal window explaining the current state (e.g. you might have a page followed because you are actually following a space containing that page), and allowing you to perform actions to change that state.
That modal also contains a link to access directly the notification filters settings: this is useful if you want to properly review your settings or perform custom actions from there. Note that if the current state is custom you can only perform actions from the notification filters settings.
XWiki <16.5.0
To watch a location, all you need is to go to that place, and then click on the "alert" menu (represented by a bell).
Here you can decide to watch either this page, this page and its children, or the entire wiki.
On the notifications settings (in your user profile), you will see the watched entities in the filters box:
Auto Watch
By default, a page where you have made a major modification is automatically added to the list of pages you watch. It means you will be notified about changes on your work. You can change this behavior in the settings:
Follow a user
If you go to the profile of an user, using the User Index for example, you can see decide to watching a user. It means you will receive all notifications about events triggered by this user.
In your user profile, if you go to the "network" tab, you can see the list of users you are watching and the events that have performed:
Default Watch Settings
XWiki <15.5 By default for new users the whole wiki is watched. However, by default in this version, there's no application type enabled for notifications, except specific ones like Mention. This means that new users won't receive notifications, until they started to watch something and enabled some applciation types. There is a mechanism to automatically enable some application types whenever the users perform editions.
XWiki 15.5+ Starting with this version, by default nothing is watched for new users. However, all application types are now enabled. So users will keep not receiving anything, until they started to watch something.
Watch and custom filters
Watching a location automatically create a custom notification filter, associated to that location, that targets all event types and all notification formats (alert and email).
XWiki 15.5+
Users are able to create their own custom notification filters, targeting only some specific events. So the watch buttons might be in an undecided state if there's an existing filter targeting the same location, but only some specific events, or some specific format. The idea is to inform the user that there's already a filter for this location and that using the watch buttons might impact the filter.
If a filter is not targeting all event types and all formats, and is actually in contradiction with the filter that would be created by the watch button, then this filter will be automatically disabled when using the watch button. For example, if a user had a filter to ignore all mentions on a space, then watching that exact same space will automatically disable that filter. The user can always review their filters and enable them back.
XWiki 16.3.0+
The custom filters are all displayed in a live data which can now be filtered and sorted out:
Filters
There is a "Filter" box on the bottom of the settings we have yet described.
XWiki <13.2 This table contains two kind of filters: To add a new location filter, click on the "add a filter" button: You will see a picker that will let you chose either a page or a wiki and a selector to choose if the filter should be inclusive or exclusive. When you select a page, the filter will also be applied on its nested pages, unless it is a terminal page. You can also define exclusive filters. You can then exclude some pages from your notifications. Note that exclusive filters take precedence over inclusive filters. Filters have been split into two different tables: 
- some system filters that you can only enable or disable, which are described in the table. "System user" refers to the superadmin account.
- custom location filters that allow you to restrict on which locations you want to receive notifications, for each event type
XWiki 13.2+ 
XWiki 14.1+ Note that the "System Event" filter doesn't filter out events that target the user explicitly.
Hidden (technical) pages
XWiki 16.3.0+ All filters are displayed even those about hidden pages.
XWiki <16.3.0 Filters that concern hidden pages are not shown in the table, unless you have enabled the option to see hidden pages. That is why you can end up in a situation where filters exist but are not listed there.
Filter your own events
By default, one don't receive notification about one's own activity (XWiki 14.1+ unless the event that triggered the notification targets explicitly that user). You have the ability to disable this filter in the "Advanced filtering options" section of your own notification settings. It's a per user setting, not a global one.
Filter events that you have marked as read
You can hide the notifications that you have marked as "read", so they won't appear anymore in the notifications menu nor in the emails.
Filter minor events
Minor events are not displayed on the notifications. But you can disable this filter.
Emails
You can also select some types of notifications that you will receive by email. You can have different choices enabled by email and in the menu. Then, on the very bottom of the page, you can select the interval between 2 emails. For example, if you choose "Daily" (default), you will receive one email every day with the recap of the events that have happened during the day. Of course, if there were no activity in this period of time, no email is sent.
Live notifications emails can be sent to a user. The wiki administrator can also define a "grace time" for live email notifications ; 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. You can get more informations on how to configure this feature here.
Of course, it works only if the user has properly filled her e-mail address.
You can edit the frequency of your email notifications by using the selector just at the bottom of the notification preferences pane in your profile page :
The notifications are sorted by pages and dates, and a table of content summarizes all notifications contained in the email:
A breadcrumb is displayed on top of each notification that concern a page:
Details of the changes
The changes are displayed in the email content:
Select the level of details about the changes
In the user profile of the user, you can select the level of details that you receive on the email, about the changes that have happened to the wiki:
The current choices are:
- Standard
- Nothing
Macros for settings
The application proposes different wiki macros to handle the user's settings that could be called in many pages. These macros are:
| Macro Usage | Screenshot |
|---|---|
| {{notificationsEmailPreferences/}} |  |
| {{notificationsApplicationsPreferences/}} |  |
| XWiki <13.2 {{notificationsFiltersPreferences/}} |  |
| XWiki 13.2+ {{notificationsSystemFiltersPreferences/}} |  |
| XWiki 13.2+ {{notificationsCustomFiltersPreferences/}} |  |
Enable and disable the extension
The extension status can be toggled by editing the configuration variable "notifications.enabled" in xwiki.properties and restarting the server.
# Notifications
#-------------------------------------------------------------------------------------
#-# [Since 9.4RC1]
#-# Indicates if the notification module should be enabled on the platform.
#-#
#-# The default is :
# notifications.enabled = true
Enable and disable the email feature
The administrator can disable the "email" notifications by editing the configuration variable "notifications.emails.enabled" in xwiki.properties and restarting the server.
#-# Indicates if the notifications module can send emails.
#-#
#-# The default is :
# notifications.emails.enabled = true
Customize live email notifications grace time
The wiki users can receive live email notifications when an event is triggered in the wiki. In order to reduce the load on the server and on your MTA, you can define a live notification grace time in xwiki.properties with the variable notifications.emails.live.graceTime. The server should be restarted for the changes to take effect.
#-# Indicate the grace time used when sending live email notifications.
#-# When an event is triggered in the wiki (for example, a document update), the platform will wait X minutes
#-# before sending live notifications emails. During this time, if events of the same kind are recieved, they will
#-# be grouped in the same email.
#-#
#-# The grace time define the period (in minutes) for which the platform should wait before sending a notification
#-# mail after an event.
#-#
#-# The default is :
# notifications.emails.live.graceTime = 10
Threads, cache and filtering systems
The notifications can be quickly resource consuming as the number of filters grows rapidly when the autowatch settings is enabled, and when lots of users are interacting in a wiki. Several settings have been added to handle the scalability of the notifications. It's generally advised to keep the default settings to avoid any performance issues.
Threads
#-# XWiki instance.
#-# This properties controls the size of this pool. Any number lower than 1 disable the thread pool system.
#-#
#-# The default is :
# notifications.rest.poolSize=2
#-# [Since 12.5RC1]
#-# The async notifications renderer is using a dedicated thread pool to limit the impact on the rest of the XWiki
#-# instance.
#-# This properties controls the size of this pool.
#-#
#-# The default is :
# notifications.async.poolSize = 2
All the requests which are searching for notifications for the current user go trough a thread pool with low priority in order to limit the impact of this feature on the rest of the XWiki instance. By default only 2 threads are allocated but it's possible to modify this (or disable the system completely) in xwiki.properties.
Note that notifications.rest.poolSize is used for the search for notifications in REST API, which is mainly used for the notification counter in standard version of XWiki.
notifications.async.poolSize is used to retrieve and render the notifications in the standard notification area, under the bell.
Cache
#-# [Since 11.3]
#-# Enable or disable caching of notification search result in the REST or async API.
#-#
#-# The default is :
# notifications.rest.cache = true
This cache allows to keep in memory already computed requests for notifications, both for counting the notifications and displaying them. By default, it keeps information 24 hours and is invalidated for a user when they changes their own settings.
Administrators
Administrators can go to Administration > Notifications to configure some settings about the notifications.
Some properties can be overridden by users. The inheritance is "Main Wiki preferences < Current Wiki preferences < User preferences".
XWiki 13.2+ Administrators can also directly change users' notification settings by going to their profile and click on "Notifications" tab in the menu. The UI is the same as what the user is seeing to customize their own notification settings.
Enabling notifications for all users by default
In the administration, you can select which application and/or event types should be enabled by default for all users.
Choosing the default frequency of notification emails
XWiki 14.10+ Administrators can select the default frequency used for sending emails to users about the changes that have happened on the wiki. This frequency is set to Daily by default.
Choosing the default level of details about the changes in the email
Administrators can select the level of details that users receive on the email, about the changes that have happened to the wiki.
Choosing the default auto-watched mode
Administrators can select what is the default auto watching page behavior.
You can also edit the xwiki.properties file:
#-# [Since 10.6RC1]
#-# The automatic watch mode used by default. The value can be changed by an administrator in the wiki's administration
#-# or by any user in their own settings.
#-#
#-# Possible values:
#-#
#-# - none: no page is added to the list of watched pages automatically.
#-# - all: everytime a user makes a change on a page, it is automatically added to her list of watched pages.
#-# - major: everytime a user makes a major change on a page, it is automatically added to her list of watched pages.
#-# - new: only pages created by a user are added to her list of watched pages.
#-#
#-# The default is :
# notifications.watchedEntities.autoWatch = major
Customizing the notification email template
The template used for email notifications is customizable. It is stored in an XWiki.Mail object inside the page XWiki.Notifications.MailTemplate.
It is possible to attach images to that templates, and they will be embedded in the notifications email.
To display them in the email, you need to use the syntax <img src="cid:myImage.png" /> in the HTML xproperty (for the Text xproperty, you'll need to decide what you want to display but it can't be an image since that's not textual 
).
Create global notification filters
XWiki 13.3+
Administrators are now able to create custom notification filters globally: it means those filters will be copied to any new users registered on the wiki. Existing users won't have any changes when the filters are modified.
Developers
Send notifications
See Tutorial: How to send notifications.
Override default notification templates in wiki pages
A wiki administrator can change the way notifications are displayed in the notification tray using the NotificationDisplayerClass XObject. You can get more informations about this feature in the Notifications API documentation.
Prerequisites & Installation Instructions
We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager). Note that installing Extensions when being offline is currently not supported and you'd need to use some complex manual method.
You can also use the following manual method, which is useful if this extension cannot be installed with the Extension Manager or if you're using an old version of XWiki that doesn't have the Extension Manager:
- Log in the wiki with a user having Administration rights
- Go to the Administration page and select the Import category
- Follow the on-screen instructions to upload the downloaded XAR
- Click on the uploaded XAR and follow the instructions
- You'll also need to install all dependent Extensions that are not already installed in your wiki
Dependencies
Dependencies for this extension (org.xwiki.platform:xwiki-platform-notifications-ui 16.9.0):
- org.xwiki.platform:xwiki-platform-notifications-preferences-default 16.9.0
- org.xwiki.platform:xwiki-platform-notifications-macro-ui 16.9.0
- org.xwiki.platform:xwiki-platform-notifications-script 16.9.0
- org.xwiki.platform:xwiki-platform-notifications-filters-default 16.9.0
- org.xwiki.platform:xwiki-platform-notifications-notifiers-default 16.9.0
- org.xwiki.platform:xwiki-platform-notifications-filters-watch 16.9.0
- org.xwiki.platform:xwiki-platform-notifications-rest 16.9.0
- org.xwiki.platform:xwiki-platform-eventstream-store-solr 16.9.0
- org.webjars:bootstrap-switch 3.3.4
- org.xwiki.platform:xwiki-platform-rendering-macro-velocity 16.9.0
- org.xwiki.platform:xwiki-platform-icon-script 16.9.0
- org.xwiki.platform:xwiki-platform-user-profile-ui 16.9.0
- org.xwiki.rendering:xwiki-rendering-macro-html 16.9.0
- org.xwiki.platform:xwiki-platform-alerts-ui 16.9.0
- org.xwiki.platform:xwiki-platform-date 16.9.0
- org.xwiki.platform:xwiki-platform-rendering-macro-code 16.9.0
- org.xwiki.platform:xwiki-platform-livedata-macro 16.9.0
- org.xwiki.platform:xwiki-platform-livedata-livetable 16.9.0
- org.xwiki.platform:xwiki-platform-notifications-webjar 16.9.0
