Notifications Filters API

Version 14.1 by Admin on 2021/03/17 17:53

bellHandle the filters that can be applied on notifications
TypeJAR
CategoryAPI
Developed by

XWiki Development Team

Rating
0 Votes
LicenseGNU Lesser General Public License 2.1
Bundled With

XWiki Standard

Installable with the Extension Manager

Description

This page contains technical explanations about the Notification Filtering feature. It is designed to be read by developers who want to enter in the details of the working of XWiki. If you simply want to learn how to use the Notifications in XWiki, please look at Notifications Application.

You need to be comfortable with the XWiki Data Model and the XWiki Component System to understand what will be described here.

This module is quite new (XWiki 9.7 - XWiki 9.8) and still unstable. What is described here can still change and breakages are possible.

Concepts

By default, when a user selects an event type to survey, she receives notifications for all events of that event type (except the ones that are anterior to a date configured by that user).

That might be too much. That is why we have introduced the Notification Filters. A notification filter introduce restrictions for an event type. For example, it will restricts "update" events on the page Movies and this children, meaning that all events that do not concern pages contained under Movies will not be seen as notification.

But you could image other filters: display only notifications about events sent by a particular user, or about pages containing a specific keyword... It's up to you (and the developers who work for you)!

You can also create filters that are not bound to any event type. We call them global filters internally. They can implement the same restrictions, except that they will concern all events.

Inclusive and Exclusive notification filters

Your can also design you filter not to restrict the events given by the Notification Manager on some conditions (we call that kind of filters exclusive filters), but to add other events to that list. We call them inclusive filters. They are not "filters" strictly speaking, but we implement them with the same component role.

Notification Filter Preferences

A Notification Filter provides a generic mechanism to filter on events according to some rules. For example, the ScopeNotificationFilter implements the algorithm to restrict the notifications of any set of locations. But if you want to select the location on which you want to restrict, you need to tell it to the ScopeNotificationFilter with a NotificationFilterPreferences.

A NotificationFilterPreferences is a generic object that can contain some properties, such as: APPLICATION, PAGE, USER, etc... the complete list is here. Each NotificationFilterPreferences specifies which filter it concerns thanks to the method getFilterName(). For example, if the filter preference concerns the  ScopeNotificationFilter, getFilterName() will return scopeNotificationFilter, which is the filter hint. The way the preference is used by the Notification Filter is up to that filter. There is no imposed behavior.

You can even decide not to use the Notification Filter Preferences mechanism and implement your own way of giving more information to your Notification Filter. 

Notification Filter Preferences Displayer

Notification Filter Preference Provider

Because a notification filter preference object can be stored at several level (on the user level or on the wiki level for example), we need to be able to implement this different sources and the way the return preferences. This is the role of the NotificationFilterPreferenceProvider.

For example, the UserProfileNotificationFilterPreferenceProvider provides method to load, store and update the notification filter preferences that are stored with XObjects on the user's page.

Abstract Syntax Tree (AST)

We have introduced an Abstract Syntax Tree (AST) to generate the query that fetch the events we want to display as notifications.

This AST has been created for 2 reasons:

  • in the future, the events might be stored in a different way, and the current HQL query might be not effective on a different storage (such as NoSQL). This AST abstracts the language so the query could still be effective, as soon as we have a translator for the target language.
  • it's easier for developers to write a NotificationFilter by generating an AST than generating a good HQL query that must escape its values and co-exists with other filters...

See the current list of available expression nodes.

Since theses nodes have been created for our own implementation needs, please open a JIRA issue if you wish to have more.

How to create my own Notification Filter?

What you need to do is to create your own implementation of https://github.com/xwiki/xwiki-platform/blob/master/xwiki-platform-core/xwiki-platform-notifications/xwiki-platform-notifications-filters/xwiki-platform-notifications-filters-api/src/main/java/org/xwiki/notifications/filters/NotificationFilter.java##.

There is 2 main methods to implement:

  • filterExpression(): generate an AST to customize the query that will look for events to display as notifications
  • filterEvent(): after the query is executed, return if the given event should be displayed or not according to criteria that was not possible to implement in the AST. It is also used on the Live Notification Email mode, so it needs to do at least what filterExpression() does.

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).

You can also use the manual method which involves dropping the JAR file and all its dependencies into the WEB-INF/lib folder and restarting XWiki.

Dependencies

Dependencies for this extension (org.xwiki.platform:xwiki-platform-notifications-filters-api 13.1):

Tags:
    

Get Connected