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
withinevents.on
) - Event options named 'event', 'timestamp' and 'emitter' will be overwritten by Sitevision when the event is emitted