Event Stream Module

Last modified by Clément Aubin on 2017/07/10 11:46

cogActivity events manipulation API
TypeJAR
Developed by

XWiki Development Team

Rating
Rate!
0 Votes
LicenseGNU Lesser General Public License 2.1
Bundled With

XWiki Enterprise, XWiki Enterprise Manager

Description

The Event stream module offers APIs to manipulate activity events. An activity event is a recorded event that occurred at some point in the wiki.

This API replaces the older, deprecated, Activity Stream Plugin.

Note that since XWiki 9.6RC1, you can also define custom events inside wiki pages through the EventClass XObject.

Events

Events are identified by:

  • an identifier unique for each event
  • a group identifier used for all the events caused during the same action
  • the exact date and time when the event occurred
  • an importance which allows to order events in the same group, or in the same stream

Events contain:

Events are categorized into:

  • the application that created them, like blog, user statuses, or the general wiki
  • an eventual sub-stream inside the application, for example a space for wiki events, or a certain group for user statuses
  • the particular type of event, like adding a comment, updating an attachment, setting a new user status

Events target:

  • the wiki,
  • the space,
  • and the document affected by the event
  • and an eventual entity inside the document, for example an individual attachment for attachment events, or an individual object for comment events.

Events can store some more information about the context in which they occur:

  • the user that caused the event
  • the version of the target document at the time that the event occurred
  • the display title of the target document at the time that the event occurred
  • the requested URL that caused the event

Code Samples

Adding an event to the event stream

 // [...]

 // Some imports we will need :

import org.xwiki.eventstream.Event;
import org.xwiki.eventstream.EventFactory;
import org.xwiki.eventstream.EventStream;

 // [...]

 // Some requirements to add events :

 @Inject
 private EventFactory eventFactory;

 @Inject
 private EventStream eventStream;

 // [...]

 // Adding an event to the stream :
 Event event = this.eventFactory.createEvent();
  event.setDocument(someDocument.getDocumentReference());

  event.setApplication("yowler"); // (It's like twitter, but only for cats)
 event.setType("yowl");

  Map<String, String> params = new HashMap<String, String>();
  params.put("yowled", "meoooow !");

  event.setParameters(params);
 this.eventStream.addEvent(event);

Retrieving events from the stream

  Query query = this.queryManager.createQuery("where event.application='yowler'", Query.HQL);
  query.setLimit(15);

  List<Event> yowlerEvents = this.eventStream.searchEvents(query)

 for(Event event : yowlerEvents) {
   // Do anything with those events
 }

Define custom events in wiki pages

Since XWiki 9.6RC1, the EventClass XObject allows anyone with the admin rights on the current wiki to define a custom event. In order to demonstrate how a custom event definition can be useful, we will use one event defined in the Blog application that should be triggered when a blog post is published, and "translate" it into its equivalent XObject definition.

First of all, we have to create an XObject of type EventClass in any wiki page (a hidden page with restricted access rights is still preferred). This XObject has several parameters : 

  • Application: The name of the application related to the event;
  • Event Type: The type (name) of the event;
  • Event Icon: The name of the icon associated to the event;
  • Event description: A short description of the event that can be displayed to the user;
  • Listen to …: A list of events that can be used to trigger this custom event. Only one event in this list is needed to trigger the custom event.
  • Object Type: A list of XObject types that should be linked to the document that is the source of the event, note that you can leave this field blank in case where one of the triggering events defined in the Listen to … field doesn’t have a particular document attached to it;
  • Validation Template: In this template, you can define specific conditions in order to allow (or not) the triggering of the custom event :
    • The template comes with two additional context variables :
      • event: the event, which is an instance of one of the classes defined in the Listen to … field;
      • source: the source of the event;
    • In order to validate the triggering of the custom event, the template should return "true" once rendered;
    • If the Validation Template field is left blank, the template rendering will be ignored.
The Application and the Event description parameters can both be set with translation keys in order to be displayed in multiple languages.

Here is one example of an XObject that copy the same comportment of the BlogPostPublishedEvent in the Blog application :

XObjectEventExample.png

Once your XObject is defined … everything is done ! The event is now registered. If you use the notifications application provided by default with XWiki Platform, every user should now see the custom event in their notification center, and should be able to subscribe to it : 

XObjectEventNotificationCenter.png

User notifications preferences are not deleted when you remove a custom event from your wiki. If you create a new custom event with the same Event Type, the user preferences will be restored.

Events sent by the Event Stream

Since XWiki 9.6RC1, the Event Stream can send two new events :

In order to avoid event loops (an event from the observation manager that adds a new event to the event stream that triggers another event from the observation manager that adds new events to the event stream and so on …), the default implementation of the Event Stream will not allow more than one EventStreamEvent to be added to the Event Stream in the same execution context.

You can find out more checking out this module source code :

https://github.com/xwiki/xwiki-platform/tree/master/xwiki-platform-core/xwiki-platform-eventstream

Tags:
Created by Jerome on 2011/08/15 17:50
    

Get Connected