Wiki source code of Notifications Grouping Strategies
Last modified by Simon Urli on 2023/07/24 14:48
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | {{box cssClass="floatinginfobox"}} | ||
| 2 | {{toc/}} | ||
| 3 | {{/box}} | ||
| 4 | |||
| 5 | By default notifications are grouped so that we expose to the users a set of events concerning same type and/or same documents. | ||
| 6 | Those groups are what are displayed in the alert menu, and what is used to be sent to the users by email. | ||
| 7 | |||
| 8 | {{gallery}} | ||
| 9 | image:CompositeNotification.png | ||
| 10 | image:CompositeNotification2.png | ||
| 11 | {{/gallery}} | ||
| 12 | |||
| 13 | |||
| 14 | 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. | ||
| 15 | |||
| 16 | {{warning}} | ||
| 17 | This work is still at early stage: you should be careful to only change the strategy on test instances for now as it might disturb the user experience. | ||
| 18 | {{/warning}} | ||
| 19 | |||
| 20 | == Available Grouping Strategies == | ||
| 21 | |||
| 22 | We provide two strategies in XWiki Standard, but it's possible for contributors to also implement their own. | ||
| 23 | |||
| 24 | === Default Strategy === | ||
| 25 | |||
| 26 | The default strategy was previously hardcoded in notifications. This strategy consists in grouping events based on: | ||
| 27 | |||
| 28 | * their type | ||
| 29 | * the document they target | ||
| 30 | * their groupId | ||
| 31 | |||
| 32 | A similarity score is computed based on those criteria to decide if events should be grouped or not. | ||
| 33 | 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. | ||
| 34 | |||
| 35 | This strategy hint is named ##default##. | ||
| 36 | |||
| 37 | === Application Type Strategy === | ||
| 38 | |||
| 39 | 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. | ||
| 40 | |||
| 41 | This strategy hint is named ##applicationtype##. | ||
| 42 | |||
| 43 | === Custom Strategy === | ||
| 44 | |||
| 45 | It's possible for developers to add a new strategy by implementing this interface: [[GroupingEventStrategy>>https://github.com/xwiki/xwiki-platform/blob/master/xwiki-platform-core/xwiki-platform-notifications/xwiki-platform-notifications-api/src/main/java/org/xwiki/notifications/GroupingEventStrategy.java]]. | ||
| 46 | |||
| 47 | == Setting the grouping strategy == | ||
| 48 | |||
| 49 | 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. | ||
| 50 | |||
| 51 | 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. | ||
| 52 | |||
| 53 | {{gallery}} | ||
| 54 | image:notification-grouping-xobject.png | ||
| 55 | {{/gallery}} | ||
| 56 | |||
| 57 | == Emails Grouping Strategies == | ||
| 58 | |||
| 59 | 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. | ||
| 60 | |||
| 61 | === Default Email Grouping Strategy === | ||
| 62 | |||
| 63 | The default strategy consists in sending the minimum of email for notifications, so it will always include all composite events available. | ||
| 64 | |||
| 65 | This strategy hint is named ##default##. | ||
| 66 | |||
| 67 | === Per Event Email Grouping Strategy === | ||
| 68 | |||
| 69 | 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. | ||
| 70 | |||
| 71 | This strategy hint is named ##emailperevent##. | ||
| 72 | |||
| 73 | === Separated Mention Email Grouping Strategy === | ||
| 74 | |||
| 75 | 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. | ||
| 76 | |||
| 77 | This strategy hint is named ##separatedmention##. | ||
| 78 | |||
| 79 | === Custom Strategy === | ||
| 80 | |||
| 81 | It's possible for developers to add a new strategy by implementing this interface: [[NotificationEmailGroupingStrategy>>https://github.com/xwiki/xwiki-platform/blob/master/xwiki-platform-core/xwiki-platform-notifications/xwiki-platform-notifications-notifiers/xwiki-platform-notifications-notifiers-api/src/main/java/org/xwiki/notifications/notifiers/email/NotificationEmailGroupingStrategy.java]]. | ||
| 82 | |||
| 83 | == Setting the email grouping strategy == | ||
| 84 | |||
| 85 | 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##: | ||
| 86 | |||
| 87 | {{code}} | ||
| 88 | #-# [Since 15.5RC1] | ||
| 89 | #-# The hint of the strategy component to use for email grouping notifications. Default strategy is to group all | ||
| 90 | #-# notifications in a single email, but other strategies can be provided, e.g. to send as many emails as there was | ||
| 91 | #-# type of notifications. Check online documentation related to notification to see the list of available strategies. | ||
| 92 | #-# | ||
| 93 | #-# The default is : | ||
| 94 | # notifications.emailGroupingStrategyHint = "default" | ||
| 95 | {{/code}} | ||
| 96 | |||
| 97 | {{version since="15.6RC1"}} | ||
| 98 | 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##. | ||
| 99 | |||
| 100 | 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). | ||
| 101 | This value can be overridden by a user if they perform adding the same type of xobject in their own user profile. | ||
| 102 | {{/version}} | ||
| 103 | |||
| 104 | == Limitations == | ||
| 105 | |||
| 106 | 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. |
