EventFilter Type

The EventFilter data type can be used as input for the functions to retrieve events (getEventsSync, getEvents), or subscribe to them (subscribeEvents) to obtain a subset that matches the criteria specified in the event filter object.

Syntax

It is possible to create an EventFilter object. See the following syntax.

var eventFilter = new EventFilter(<systemId>, <view>)

EventFilter Options

After the filter is created, to narrow the number of returned events it is necessary to specify additional conditions, namely event filter options. These filter options are in AND condition. This means that when all the corresponding properties are specified, events are returned only when they match all the filter criteria.

Filter Option	Parameter/Property
System identifier	systemId
View root node or name	view
Case sensitivity	caseSensitive
System objects reference data	name, designation location, descriptor
Discipline	discipline
Visibility	hiddenEvents
Cause	cause
Reference to creation time	fromCreationTime, toCreationTime
Category	category
Event State	state
Source points designation	source
Alarm Classes	alarmClass

Parameters/Properties Usage - systemId and view

Parameter

Type

Default

Use

Annotation

systemId

Integer

String

SystemObject

Optional

Identifier of the system to be used as filter criterion.

It contains the system ID, system name, or a SystemObject.

The default value (0) means the current system; null and the empty string are handled as the default value.

view

String

empty string

Optional

Designation of the root node of the view to be used as filter criterion.

If a designation of a non-root node is specified, the view where the node is defined will be used.

It is also possible to specify the view name.

The default value (empty string) means all the views; null is treated as the default value.

Both <systemId> and <view> can be specified while declaring the EventFilter object as parameter of the constructor, or they can be set later, like any other filter options.

As <systemId> and <view> are optional parameters, a filter can be created depending on specific needs so to return the events:

In all the views of the current system:

var filter = new EventFilter()

In all the views of the system that matches the given <systemId>:

var filter = new EventFilter(<systemId>)

In the specified <view> and belonging to the current system:

var filter = new EventFilter(0, <view>)

In the specified <view> and system that matches the given <systemId>:

var filter = new EventFilter(<systemId>, <view>)

Property Usage – caseSensitive

Property

Type

Default

Annotation

caseSensitive

Boolean

True

Strings comparison to be used as filter criterion (whether case sensitive).

True means case sensitive.

This option applies to all the properties of type String or String Array, except for systemId and view.

Property Usage – designation

Property

Type

Default

Annotation

designation

String

CNS full path (designation) of the system object to be used as filter criterion.

This option supports wildcards.

The designation is the path up to the parent node obtained from the concatenation of CNS names (no spaces are allowed). For example, the designation of the Main Server node is ManagementView.ManagementSystem.Servers.

A search by designation returns all the events generated by the child nodes under the specified designation (first level children).
To refine the search, add a filter by name or descriptor.
To get all the child nodes at any level, add an asterisk at the end.

Property Usage – name

Property

Type

Default

Annotation

name

String

CNS names of system objects to be used as filter criteria.

This option supports wildcards. For example, to search for all the system objects whose name contains the word "analog", set a search for name="*analog*".

Property Usage – location

Property

Type

Default

Annotation

location

String

Location of the system object to be used as filter criterion.

This option supports wildcards.

The location is the path up to the node obtained from the concatenation of CNS descriptions (or Display Name). For example, if the path of a node is Application View.Folder.Node, the location is Application View.Folder. The location of the Main Server node is Project.Management System.Servers.

A search by location returns all the child nodes under the specified location.
To refine the search, add a filter by name or descriptor.
To get all the child nodes at any level, add an asterisk at the end.

Property Usage – descriptor

Property

Type

Default

Annotation

descriptor

String

Display name to be used as filter criterion.

This option supports wildcards.

Property Usage – discipline

Property

Type

Default

Annotation

discipline

Integer

Integer Array

DisciplineFilter

DisciplineFilter Array

Disciplines to be used as filter criteria.

If specified via a DisciplineFilter, subdisciplines are ignored (it is not possible to filter by subdisciplines).

Disciplines are defined in the text group: Object Disciplines.
The discipline of a system object is defined in the object model and can be re-defined using the Object Configurator application.
A filter by discipline can be one of the following:

A simple value indicating the discipline:
eventFilter.discipline = 100;
An array of simple values indicating the disciplines:
eventFilter.discipline = [100, 200];
A DisciplineFilter object (if specified, subdisciplines are ignored):
eventFilter.discipline = new DisciplineFilter(100);
An array of DisciplineFilter objects:
eventFilter.discipline = [new DisciplineFilter(100), new DisciplineFilter(200)];

Property Usage – hiddenEvents

Property	Type	Default	Annotation
hiddenEvents	Boolean	False	Whether to retrieve any events that do not display on Desigo CC clients.

Property Usage – cause

Property

Type

Default

Annotation

hiddenEvents

String

empty string

The event causes to use as filter criteria.

This option supports wildcards.

Property Usage – fromCreationTime, toCreationTime

Property	Type	Default	Annotation
fromCreationTime	DateTime	null	Start date to match with the events creation time.
toCreationTime	DateTime	null	End date to match with the events creation time.

Property Usage – category

Property

Type

Default

Annotation

Property Usage – state

Property

Type

Default

Annotation

state

Integer

Integer Array

EventState

EventState Array

EventStates

The states to be used as filter criteria.

Event states are defined in the text group: Alarm State.
The value of the state option can be one of the following:

A simple value indicating the state ID:
eventFilter.state = 8;
An array of simple values indicating the IDs of the states:
eventFilter.state = [5, 6];
An EventState object:
eventFilter.state = new EventState(8);
An array of EventState objects
eventFilter.state = [new EventState(5), new EventState(6)];
An EventStates object:
var eventItem = ...
eventFilter.state = eventItem.state;

Property Usage – source

Property

Type

Default

Annotation

source

String

String Array

BrowserObject

BrowserObject Array

Designation of the system objects to be used as filter criteria.

If the provided value is String or String Array, this option supports wildcards.

A filter by source allows specifying designations with or without wildcards, or a list of the affected points.

Property Usage – alarmClass

Property

Type

Default

Annotation

alarmClass

String

String Array

The alarm classes to use as filter criteria.

This option supports wildcards.

Examples of Use

How to create an EventFilter to get the events generated by the system objects in all the views of the current system

var eventFilter = new EventFilter();

How to create an EventFilter to get the events generated by the system objects in the Application View of the system with name "System2"

var filter = new EventFilter("System2", "ApplicationView")

var eventFilter = new EventFilter();

eventFilter.systemId = "System2";

eventFilter.view = "ApplicationView";

How to create an EventFilter to get the events generated by the first level child nodes of the FieldNetworks node in the system with name "System2"

var eventFilter = new EventFilter();

eventFilter.designation = "System2.ManagementView:ManagementView.FieldNetworks";

How to create an EventFilter to get the events generated by the child nodes of the FieldNetworks node, at any level, having a name containing "building"

var eventFilter = new EventFilter();

eventFilter.designation = "System1.ManagementView:ManagementView.FieldNetworks*"

eventFilter.name = "*building*";

eventFilter.caseSensitive = false;

How to create an EventFilter to get the events generated by the child nodes of the FieldNetworks node, at any level, having a name starting with "Device" (case sensitive, in system with id 1)

var eventFilter = new EventFilter(1, "ManagementView");

eventFilter.location = "Project.Field Networks*";

eventFilter.descriptor = "Device*";

How to create an EventFilter to get the events generated by the system objects with Fire or Security disciplines in the current system

var eventFilter = new EventFilter();

eventFilter.discipline = [new DisciplineFilter(100), new DisciplineFilter(150)];

eventFilter.discipline = [100, 150];

How to create an EventFilter to get the events whose cause contains the text "failure" in the current system

var eventFilter = new EventFilter();

eventFilter.cause = "*failure*";

eventFilter.caseSensitive = false;

How to create an EventFilter to get the events created yesterday in the current system

var yesterday = new Date((new Date()).valueOf() - 1000*60*60*24);

var eventFilter = new EventFilter();

eventFilter.fromCreationTime = yesterday;

How to create an EventFilter to get the events created before yesterday in System2

var yesterday = new Date();

yesterday.setDate(yesterday.getDate() - 1);

yesterday.setHours(0,0,0,0);

var eventFilter = new EventFilter("System2");

eventFilter.toCreationTime = yesterday;

How to create an EventFilter to get the events having the most important category, under the Logics node of the current system

var eventFilter = new EventFilter();

eventFilter.category = getEventCategories(1);

eventFilter.designation = "System1.ApplicationView:ApplicationView.Logics";

How to create an EventFilter to get the events with category Fault in the Management View of the current system

var eventFilter = new EventFilter(0, "ManagementView");

eventFilter.category = new EventCategory(2);

How to create an EventFilter to get the events having state ReadyToBeReset or ReadyToBeClosed

var eventFilter = new EventFilter();

eventFilter.state = [new EventState(5), new EventState(6)];

How to create an EventFilter to get the events generated by specific system objects in the current system

var eventFilter = new EventFilter();

eventFilter.source = ["System1.ApplicationView:ApplicationView.Logics.MacroRoot.Macro1", "System1.ApplicationView:ApplicationView.Logics.MacroRoot.Macro2"];

var browserObject1 = "System1.ApplicationView:ApplicationView.Logics.MacroRoot.Macro1";

var browserObject2 = "System1.ApplicationView:ApplicationView.Logics.MacroRoot.Macro2";

eventFilter.source = [browserObject1, browserObject2];

How to create an EventFilter to get the events generated by system objects whose name matches the given designation in the current system

var eventFilter = new EventFilter();

eventFilter.source = "System1.ApplicationView:ApplicationView.Logics.MacroRoot.Macro?";

How to create an EventFilter to get the events whose alarm class contains the text "information" or "fault"

var eventFilter = new EventFilter();

eventFilter.alarmClass = ["*information*", "*fault*"]

eventFilter.caseSensitive = false;