Server-side events in RESTApps [@since 4.5.2]

Events is a broadcasting/messaging way to communicate with RESTApps. The event processing is asynchronous and will be executed on the Sitevision cluster node where the triggering operation took place. A RESTApp can react on events and it can also emit custom events that other RESTApps can react on.

System events

Sitevision emits system events when certain operations on the state of a model object occurs. The name of a system event always starts with the sv namespace and ends with a operation. System events typically also includes a category. Parts are separated with colon.

sv:category:operation

When a event is emitted, RESTApps can act on the specific event and it can also act on the category/categories of the event.

sv:category:operation sv:category

See The System events documentation for detailed info about specific options

Custom events

RESTApps can emit custom events to communicate with other RESTApps (system events can't be emitted).

The name of a custom event can contain the basic ASCII chars (a-Z), numbers (0-9) and some separators (colon, dash and underscore). A custom event name can not start with the system event namespace sv. Like system events, custom events can contain multiple groups, separated with a colon to get the same invocation behaviour as system events.

A custom event can not be emitted during the processing of another event.

Event options

Events can contain arbitrary data. The documentation of the specific event must be consulted to properly handle the event options fully. Though, all events - both system events and custom events - always contain some properties that are added automatically when they are emitted:

// Event options present in all events
{
   event: 'ns:category:operation', // The full name of the event
   emitter: '247.12121212121212',  // The JCR identifier of the emitting user [@since 4.5.5]   
   timestamp: 12345678890123456,   // The timestamp when the event was emitted
   ...
}

Acting on events

Events must be handled in the index.js file of a RESTApp. The on function of the event requireable is used to act on events. The event options will be passed to the callback specified for the on declaration.

Execution version

All events are always executed in the OFFLINE version, i.e. the RESTApp acting on the event will have access to "unpublished/offline" data.

Executing user and permissions [@since 4.5.5]

The processing of events (i.e. the on callback) will be executed as the emitting user. Hence, the permissions when acting on an event adheres to the emitting user. Tip! The JCR identifier of the emitting user is available as 'emitter' in the event options.

Executing code as a specified user is available as of Sitevision 7 via the privileged functionality.

// index.js - Acting on publishing events
var
  events = require('events'),
  log    = require('LogUtil');
  
// Invoked whenever a page is published  
events.on('sv:publishing:publish', function(options) {
   log.info('Handling sv:publishing:publish, options: ' + JSON.stringify(options));
   ...
});

// Invoked whenever a publishing category event occurs (page is published or unpublished)
events.on('sv:publishing', function(options) {
   log.info('Handling ' + options.event + ', options: ' + JSON.stringify(options));
   ...
});

Emitting custom events

The emit function of the event requireable is used to send custom events with options.

// index.js of RESTAPP A - Emitting custom events
var
  events = require('events'),
  router = require('router');
  
router.get('/triggerevent', function(req, res) {

   // Emit a custom event with category 'mycompany' and operation 'myevent'
   events.emit('mycompany:myevent', {
      customData: 'triggerevent requested'
   });

   res.json({
      ...
   });
});

// index.js of RESTApp B - Acting on custom events
var
  events = require('events'),
  log    = require('LogUtil');
  
// Invoked whenever a RESTApp has emitted a 'mycompany:myevent' event
events.on('mycompany:myevent', function(options) {
   log.info('Handling mycompany:myevent, customData: ' + options.customData + ', options: ' + JSON.stringify(options));
   ...
});

// Invoked whenever a RESTApp has emitted an event with the 'mycompany' category
events.on('mycompany', function(options) {
   log.info('Handling ' + options.event + ', options: ' + JSON.stringify(options));
   ...
});

Event restrictions

There are some restrictions for events that is important to be aware of:

RESTApps can't act on the sv namespace (it is not considered a category)
RESTApps can't emit system events (events using the sv namespace)
RESTApps can't emit events when acting on a event (i.e. can't call events.emit within events.on)
Event options named 'event', 'timestamp' and 'emitter' will be overwritten by Sitevision when the event is emitted