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

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 EventFilter object.
  • 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

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 SubscribeEventsResult object 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);

        }

    );

 

}