Send a notification to the admin

Help / Discuss
#1

Hello fellow XWikiers,

I’ve been hunting since quite a bit on how to generate a notification in the stream of the user currently running the page and I must say that I am lost again.

Creating an event is ok… E.g. using this example sending a yowler to the new event store.
But such an event is just put in the store and nothing makes it that it can be watched by “my target user group” (XWiki Admins or simply the user currently requesting)?

What is the clean way for an extension to post such a notification (in this case: a warning that a configuration needs to be cared for, to be sent after application upgrade)? Even creating a page would post a DocumentCreatedEvent but that does not make it watched.

Thanks in advance.

Paul

#2

Events or Notifications? (they’re not the same)

For notifications, see https://extensions.xwiki.org/xwiki/bin/view/Extension/Notifications%20Application/#HDevelopers

#3

Well… An event is needed to generate notifications as explained in the page linked from your link above (Tutorial: How to send notifications?).

From reading there I summarise that the following groovy should send notifications to all:

    import org.xwiki.observation.ObservationManager
    import org.xwiki.eventstream.RecordableEvent;
    import com.xpn.xwiki.web.Utils;
    
    public class BlogPostPublishedEvent implements RecordableEvent
    {
            @Override
            public boolean matches(Object otherEvent)
            {
                    return otherEvent != null && otherEvent instanceof BlogPostPublishedEvent;
            }
    }

    def event = new BlogPostPublishedEvent();
    Utils.getComponent(ObservationManager.class).notify(event, "groovy down here", doc);

However… I don’t see any notification…
Paul

#4

Have you implemented a notification type/renderer for your event?

#5

The notifications should actually be sent, you can check on the database you should be able to see them.
Your problem is I think to be able to display the notifications for your users, and for that you need to have a dedicated filter to display the notifications with the right type. You can check for example what I’ve done to create a dedicated filter preference for the Mentions notifications, there: https://github.com/xwiki/xwiki-platform/blob/master/xwiki-platform-core/xwiki-platform-mentions/xwiki-platform-mentions-notifications/src/main/java/org/xwiki/mentions/internal/descriptors/MentionEventDescriptor.java#L86-L103

You can see that I create a preference with a property containing the actual type of event I want to retrieve for all users.
But note that creating such a preference programmatically won’t allow users to opt-out for those notifications… You might want a dedicated descriptor to allow users to switch on/off those notifications.

#6

Well… no, I don’t see this documented…
I only see below how to change the rendering and how to create new filters. Both that do not seem to be necessary.

@surli : is this the only way to enable reception of such a notification from a user without him doing anything? (as a “mention” is supposed to do).

Paul

#7

AFAIK we don’t have a generic notification displayer for any event. Each notification “type” handles its known notifications with its displayer (I’m probably using the wrong terminology, I don’t know this module well at all).

By “type” I mean what you see when you go your notifications preferences in the UI. “Pages”, “Mentions”, “Blog”, etc.

#8

It’s called “Applications” apparently (displayed with {{notificationsApplicationsPreferences/}}).

IMO the https://extensions.xwiki.org/xwiki/bin/view/Extension/Notifications%20Application/ doc page is missing a terminology section.

#9

And it seems that at the code level it’s called a RecordableEventDescriptor (see https://extensions.xwiki.org/xwiki/bin/view/Extension/Notifications%20API/#HRecordableEventDescriptor)… Not great to have 2 different names…

#10

That’s getting more and more confused.

In any case, I wish not to make any dedicated displayer or require an action from the user: This notification follows an application upgrade and is only useful if it is presented as part of the normal stream of notifications that the user sees.

As far as I understand, only the solution of Simon is doable: Change filter preferences to force interest to such a (newly built) event-type.

paul

#11

So… maybe sending a MentionEvent is the right thing for me to notify the admin of a configuration change? I tried executing this:

    def params = new MentionEventParams();
    params.setDocumentReference(docFullName);
    params.setLocation(MentionLocation.DOCUMENT);

    def event = new MentionEvent(new HashSet(["XWiki.Admin", "XWiki.PL"]), params);
    Utils.getComponent(ObservationManager.class).notify(event, "groovy down here", doc);

It executes without error but I can’t see a notification as user Admin or PL. Should I not?

paul

#12

No definitely not the right thing to do :slight_smile: MentionEvent is a dedicated EventType for Mention application, you shouldn’t use it for your usecase!

Best solution would be:

  1. Create a dedicated TargetableEvent event type for your need (targetable to target specific people, can be other thing, see https://extensions.xwiki.org/xwiki/bin/view/Extension/Notifications%20API/#HTargetableEvent)
  2. Create a descriptor for it (see https://extensions.xwiki.org/xwiki/bin/view/Extension/Notifications%20API/#HRecordableEventDescriptor)
  3. Activate by default the events for your users by using a piece of code like I did for Mentions. Note that in the future I’d like it to be more easy to activate by default (see: https://jira.xwiki.org/browse/XWIKI-17426)

Now we could decide to create some dedicated “System Event” type to send generic notifications about the wiki on users, and to rely on it for your usecase, but that would be something to do on platform directly.

#13

Note that if you want to target admins, you can actually use a reference to a group but only since XWiki 12.3RC1 (https://jira.xwiki.org/browse/XWIKI-17176).

#14

Hold on… I agree this is “stealing” (or… “bending purposes”),
I really had intended to make this a mention with saving a page where the admin in question would be named). But in any case, your answer does not tell me why this is not working and thus if I am choosing the right events for my purpose.

Does my script example contain something that makes it so that the mention would not be rendered as a notification to a normal admin running an xwiki 12.5?

paul

#15

So strictly speaking about making your script work, I think it just miss a parameter: MentionEventParams#setUserReference. This is mandatory since I think the notifications filters out events without a source user.

Now I still think it’s a bad idea to use mentions for that:

  1. you won’t be able to customize the notification message: customization of notification message is based on the event type, so the only to customize it there would be to customize all the mention events in your wiki…
  2. a user could disable the mentions events in his notification settings and stop receiving your event, which might not be wanted
  3. on the exact opposite, a user might want to disable your notifications, and not know which settings to switch off if you customize the display

Moreover, the Events are not only targeting the notification system, so it’s not the case right now but you could have some script or extensions triggered by a MentionEvent.
That’s why I really don’t like the idea of reusing an event for a completely different semantic. Now I completely agree that your usecase is valid and we’d need a dedicated event type a bit generic that we could reuse easily when needed to send a notification globally for some system purpose.