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 | |
View root node or name | |
Case sensitivity | |
System objects reference data | |
Discipline | |
Visibility | |
Cause | |
Reference to creation time | |
Category | |
Event State | |
Source points designation | |
Alarm Classes |
Parameters/Properties Usage - systemId and view
Parameter |
Type |
Default |
Use |
Annotation |
systemId |
Integer String |
0 |
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; |
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; |
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 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 |
category | Integer Integer Array EventCategory Array | null | The categories to be used as filter criteria. |
- Categories are defined in the text group: Category.
- The value of the category option can be one of the following:
- A simple value indicating the category ID:
eventFilter.category = 1
; - An array of simple values indicating the IDs of the categories:
eventFilter.category = [1, 2];
- An
EventCategory
object:eventFilter.category = new EventCategory(15);
- An array of
EventCategory
objects:eventFilter.category = [new EventCategory(1), new EventCategory(2)];
- An
EventCategories
object:eventFilter.category = getEventCategories([1,2,3]);
Property Usage – state
Property | Type | Default | Annotation |
state | Integer Integer Array EventState Array | - | 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
objectseventFilter.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 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")
Or
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)];
Or
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"];
Or
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;