System events are messages that are broadcasted across the Xpert.ivy system and that will be delivered to any interested party. System events have a name and are categorized, and they may carry an optional parameter object. System events can only be sent within the same Application on a Xpert.ivy Server.

Currently two categories are defined: SystemEventCategory.THIRD_PARTY and SystemEventCategory.WORKFLOW. The category THIRD_PARTY can be used to send (and receive) system events that are generated by integrated third party applications (or processes). The category is reserved exclusively for this purpose; i.e. the Xpert.ivy server will never generate any events of this type.

The Xpert.ivy system itself currently only generates events of the category WORKFLOW. Inside this category, events with the following names are generated:

All of those events carry a parameter object of the type WorkflowSystemEventParameter which gives access to the identifiers of the workflow objects that have been created or modified. More system defined categories and events can be expected in the future.

To send system events, client and/or third party applications must first create a SystemEvent object and then get a hold of an IApplication object, which offers the method sendSystemEvent(SystemEvent event). Only events of the category THIRD_PARTY can be sent by process applications, attempts to send system events of different categories will result in an error.

To receive system events, clients must implement the interface ISystemEventListener and must then register themselves on an IApplication object using the method addSystemEventListener(EnumSet<SystemEventCategory> categories, ISystemEventListener listener). It is strongly recommended, that the similar remove method is used, as soon as clients are no longer interested in a specific event category.

Clients should only listen to system events they know the name of, all other events should be ignored. Clients should handle received events as fast as possible, because handling will block the delivery of events to other receivers. Also the received parameter object should never be modified (it shouldn't be modifiable in the first place), since this may affect the handling by other receivers which will consequently receive a modified event object.

In Java, the handling of system events generally results in code similar to the following:

/** 
 * Registers this participant for workflow system events.
 */ 
 public void registerForWorkflowEvents(IApplication application) 
 { 
    application.addSystemEventListener(EnumSet.of(SystemEventCategory.WORKFLOW));
 }

/** 
 * Unregister this participant for all system events.
 */ 
 public void unregister(IApplication application) 
 { 
    application.removeSystemEventListener(EnumSet.allOf(SystemEventCategory.class));
 }

/** 
 * Implementation of ISystemEventListener.handleSystemEvent(...) 
 * Events will only be delivered for the categories that this listener registered for 
 */ 
 public void handleSystemEvent(SystemEvent event) 
 { 
    String eventName = event.getName(); 
    if ("thirdparty.mysystem.myevent".equals(eventName)) 
    { 
        // do something 
    } 
    else if (WorkflowSystemEvent.TASK_CHANGED.equals(eventName)) 
    { 
        // do something 
    } 
    // else: ignore event 
 } 

 /**
  * Distribute a new system event to all interested/registered listeners of my event.
  * MyEventParameter can be of any (serializable) type, the type is part of the event definition,
  * clients will have to cast accordingly.
  */
 public void sendMyEvent(IApplication application, MyEventParameter param)
 {
    	SystemEvent event = new SystemEvent(SystemEventCategory.THIRD_PARTY, "thirdparty.mysystem.myevent", param);
    application.sendSystemEvent(event);
 }

Rich Dialogs can also send and receive SystemEvents via the broadcast mechanism. Read the section below to learn how.

By using the event broadcast mechanism in combination with the System Events framework, Rich Dialogs can receive and send system events as broadcast events.