subscribeEvents and unsubscribeEvents
The following methods allows subscribing and unsubscribing for changes of events.
subscribeEvents
The subscribeEvents function allows subscribing to events matching the given <eventFilter>, if specified. Then it calls the provided <callback> with the operation result.
If the <eventFilter> is not provided or is null, all the events of the current system are returned.
The event subscription remains active until the unsubscribeEvents function is called.
Syntax
var result = subscribeEvents(<callback>, <eventFilter>);
Parameters Usage
Parameter | Type | Default | Use | Annotation |
callback | Function | - | Mandatory | Object that identifies the callback function invoked to provide the events matching the filter. |
eventFilter | - | Optional | The event filter to match. |
Result
If the subscribe operation is successful, the subscribeEvents function returns a SubscribeEventsResult object containing the result of the subscribeEvents function. This result must be used to perform the corresponding unsubscription.
If any errors occurred during the subscribe operation, the error property of the SubscribeEventsResult indicates the reason why the operation failed.
It is necessary to keep this result in a global variable to use as input parameter for the unsubscribeEvents function.
The callback is a function declared as follows, and is called when an event is created or changes:
function subscribeEventsCallback(<eventItems>)
{
//... Do callback stuff here ...
}
Where <eventItems> is an EventItems collection.
Error Handling
Errors can occur in case:
- The callback is missing, invalid, null, or empty.
- The filter is not an
EventFilterobject. - The category specified in the filter is not configured in the event schema.
Examples of Use
How to subscribe to events
var eventFilter = new EventFilter();
// Set eventFilter properties...
var subscribeEventsResult = subscribeEvents(callback, eventFilter);
function callback(eventItems)
{
// Do something with eventItems...
}
It is possible to specify any combination of the event filter options. For more details, see EventFilter Type.
The callback parameter is an EventItem array, where each element has the properties described in EventItem Type.
How to subscribe to retrieve all the events in the current system
The following code sample allows printing to the Console expander the event ID of each notified event.
var subscribeEventsResult = subscribeEvents(callback);
function callback(events)
{
events.forEach(
function(event)
{
console(event.id);
}
);
}
Note that no event filter is provided, so the default values are used (all the views of the current system).
Since the unsubscribeEvents function is not called, this script remains running until it is manually stopped.
How to subscribe to retrieve all the events in Management View for the system with id 2, having state ReadyToBeReset or ReadyToBeClosed, and the most important category
The following code sample allows printing to the Console expander the event ID of each notified event.
var eventFilter = new EventFilter(2, "ManagementView");
eventFilter.state = [new EventState(5), new EventState(6)];
eventFilter.category = getEventCategories(1);
var subscribeEventsResult = subscribeEvents(callback, eventFilter);
function callback(events)
{
events.forEach(
function(event)
{
console(event.id);
}
);
}
Since the unsubscribeEvents function is not called, this script remains running until it is manually stopped.
unsubscribeEvents
The unsubscribeEvents method allows terminating any event subscription created by calling the subscribeEvents function. On this purpose, the result of the subscribeEvents invocation must be provided as parameter.
Syntax
var result = unsubscribeEvents(<subscribeEventsResult>);
Parameters Usage
Parameter | Type | Default | Use | Annotation |
subscribeEventsResult | - | Mandatory | The result of a successful subscribeEvents call. |
Result
If any errors occurred during the unsubscribe operation, the error property of the UnsubscribeEventsResult object indicates the reason why the operation failed.
Error Handling
Errors can occur in case:
- The
SubscribeEventsResultobject is missing, invalid, null, or empty.
Examples of Use
How to subscribe to retrieve all the events in the current system, and then unsubscribe after the first notification
var subscribeEventsResult = subscribeEvents(callback);
function callback(eventItems)
{
// Do something with eventItems...
unsubscribeEvents(subscribeEventsResult);
}
How to subscribe to retrieve all the events in the current system, and then unsubscribe after an hour
console("Start monitoring events: {0}", new Date())
var subscribeEventsResult = subscribeEvents(callback);
if (subscribeEventsResult.error != null)
terminate();
setTimeout(timeoutElapsed, 60 * 60 * 1000);
function timeoutElapsed()
{
console("Stop monitoring events: {0}", new Date())
unsubscribeEvents(subscribeEventsResult);
}
function callback(events)
{
console("--- events count = {0}", events.length)
events.forEach(
function(event)
{
console(event.id);
}
);
}
