Notifications Grouping Strategies
By default notifications are grouped so that we expose to the users a set of events concerning same type and/or same documents.
Those groups are what are displayed in the alert menu, and what is used to be sent to the users by email.
Starting with XWiki 15.5RC1 it's possible to chose those strategies: before that version, the default strategy was systematically used and couldn't be changed. The strategy is applied based on wiki or user preferences, per channel: one can chose a different strategy for alert notifications and for email notifications. Also the strategy only concerns how events are grouped: the criteria for getting the events is based on filters defined by users.
Available Grouping Strategies
We provide two strategies in XWiki Standard, but it's possible for contributors to also implement their own.
Default Strategy
The default strategy was previously hardcoded in notifications. This strategy consists in grouping events based on:
- their type
- the document they target
- their groupId
A similarity score is computed based on those criteria to decide if events should be grouped or not.
Basically, two events with same type and targeting same documents will be grouped. Two events targeting same document with different types won't be grouped, unless they share the same groupId, which is used internally to define if two events are triggered during the same session. Finally two events without any document but of the same type will also be grouped.
This strategy hint is named default.
Application Type Strategy
This strategy consists in grouping all events sharing the same type: it doesn't perform any check on other properties of the event. So events concerning different documents might be grouped together.
This strategy hint is named applicationtype.
Custom Strategy
It's possible for developers to add a new strategy by implementing this interface: GroupingEventStrategy.
Setting the grouping strategy
The strategy can be set globally for a wiki, or per user. Each strategy needs to be defined for a specific channel: either the alert (for being used in the notification alert area), or for the email.
As of XWiki 15.5RC1 we don't provide yet an UI to chose the strategy, it's currently done through an XObject, either in the user profile or in XWiki.XWikiPreferences document.
Emails Grouping Strategies
Besides the way events are grouped to form composite events, it's also possible to chose how many emails should be sent for notifications and what composite events they should be composed of.
Default Email Grouping Strategy
The default strategy consists in sending the minimum of email for notifications, so it will always include all composite events available.
This strategy hint is named default.
Per Event Email Grouping Strategy
This strategy will send one email per composite event. The idea is to use this strategy in combination with the Application Type Grouping Strategy in order to send one notification email per notification type for the users.
This strategy hint is named emailperevent.
Separated Mention Email Grouping Strategy
This strategy consists in trying to always send a separate email in case of mentions. So the user might receive 0, 1 or 2 notifications emails. If there's no notifications, they won't receive any email, if the notifications only concerns mentions, or only concerns other events they'll receive a single email, but if there's notifications about mentions and other events, they will receive one email for all the mentions, and one email for the others notifications.
This strategy hint is named separatedmention.
Custom Strategy
It's possible for developers to add a new strategy by implementing this interface: NotificationEmailGroupingStrategy.
Setting the email grouping strategy
The email grouping strategy can be set globally at farm level, for all the schedulers (hourly, daily, weekly and live) through a configuration defined in xwiki.properties:
#-# The hint of the strategy component to use for email grouping notifications. Default strategy is to group all
#-# notifications in a single email, but other strategies can be provided, e.g. to send as many emails as there was
#-# type of notifications. Check online documentation related to notification to see the list of available strategies.
#-#
#-# The default is :
# notifications.emailGroupingStrategyHint = "default"
XWiki 15.6+
The email grouping strategy can be defined at different levels (per wiki, and per user) and is specific for a given scheduler, using a new dedicated XObject XWiki.Notifications.Code.NotificationEmailGroupingStrategyPreferenceClass.
So an admin can add one or severals xobjects in XWiki.XWikiPreferences for defining the different strategies for each scheduler, at wiki level: the xobject needs to contain the name of the strategy to use, and the name of scheduler (hourly, daily, weekly or live).
This value can be overridden by a user if they perform adding the same type of xobject in their own user profile.
Limitations
Notifications templates were originally implemented to only handle a single way of grouping events. So it's possible that the different strategies are not working properly with older notifications templates. In XWiki 15.5RC1 the bundled templates are not yet working for all strategies, the status can be followed there: https://jira.xwiki.org/browse/XWIKI-21033.
