Filter Type
The Filter
data type is required as input for the search functions to obtain a subset of system objects that match the criteria specified in the filter object.
Syntax
It is possible to create a filter object to use in a search for specific system objects. See the following syntax.
var filter = new Filter(<systemId>, <view>)
Filter Options
After the filter is created, to narrow a search it is necessary to specify additional conditions, namely filter options. These filter options are in AND condition. This means that when all the corresponding properties are specified, system objects are returned only when they match all the filter criteria.
Filter Option | Parameter/Property |
System identifier | |
View root node | |
System objects | |
System objects reference data | name and designation location and descriptor NOTE: It is also possible to specify a filter with only one of these options or mix them as follows: |
Case sensitivity | |
Object model name | |
Function name | |
Discipline and subdiscipline | |
Type and subtype | |
Scope definition |
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 filter 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 search system objects:
- In all the views of the current system:
var filter = new Filter()
- In all the views of the system that matches the given
<systemId>
: var filter = new Filter(<systemId>)
- In the specified
<view>
and belonging to the current system: var filter = new Filter(0, <view>)
- In the specified
<view>
and system that matches the given<systemId>
: var filter = new Filter(<systemId>, <view>)
Property Usage – alias
Property | Type | Default | Annotation |
alias | String | - | Aliases of objects to be used as filter criteria (the alias is provided by the drivers or defined in the Object Configurator application). This option is case sensitive (regardless of the caseSensitive property) and supports the following wildcards used for filtering: ‘*’,’?’ (for example, "*MyAlias*" will return all the objects containing "MyAlias".) |
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. NOTE: In the current version of the product, this filter criterion does not apply to the alias property which is always case sensitive. |
Property Usage – descriptor
Property | Type | Default | Annotation |
descriptor | String | - | Display Name to be used as filter criterion. This option is case sensitive and supports wildcards. |
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 is case sensitive and 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 child nodes under the specified designation.
To refine the search, add a filter by name.
Property Usage – discipline
Property | Type | Default | Annotation |
discipline | Integer Integer Array DisciplineFilter Array | - | Disciplines and subdisciplines to be used as filter criteria. Basically, array of arrays of integers is used to specify any subdisciplines. |
- Disciplines and subdisciplines are defined in the text group: Object Disciplines.
- The discipline and subdiscipline of a system object are 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:
filter.discipline = 100;
- An array of simple values indicating the disciplines:
filter.discipline = [100, 200];
- A DisciplineFilter object, that includes a discipline and any subdisciplines:
filter.discipline = new DisciplineFilter(100, [101, 102]);
- An array of DisciplineFilter objects:
var discipline = new DisciplineFilter(100, [101, 102]);
filter.discipline = [discipline, new DisciplineFilter(500, [501, 502])
Property Usage – functionName
Property | Type | Default | Annotation |
functionName | String String Array | empty string | Names of functions to be used as filter criteria. Default value means all the functions. |
- The search will consider the functions depending on the <
caseSensitive>
value (True or False) for the filter. - A function is a classification that can be applied to system objects. It is possible to assign a function to a system object using the Object Configurator application (in the Main expander, it is possible to select a function from a drop-down menu that contains all the functions that can be applied to that specific system object).
Property Usage – location
Property | Type | Default | Annotation |
location | String | - | Location of the system object to be used as filter criterion. This option is case sensitive and 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 descriptor.
Property Usage – name
Property | Type | Default | Annotation |
name | String | - | CNS names of system objects to be used as filter criteria. This option is case sensitive and 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 – objectModel
Property | Type | Default | Annotation |
objectModel | String String Array | empty string | Names of the object models to be used as filter criteria. The default value means all the object models. Case sensitivity and wildcards are supported. |
- The search will consider the object model names.
Property Usage – scope
Property | Type | Default | Annotation |
scope | String String Array BrowserObject Array | - | Reference to scope definitions to be used as filter criteria. The scope filter can be specified as designation, BrowserObject, or array of those types. If an array is provided, the scopes are put together: if the result of a search matches at least one of the provided scopes, they are returned as results. |
- In Desigo CC, scopes are used to present or conceal groups of system objects. Such objects can be used in many Desigo CC applications (such as, security groups, journaling, macros, and so on). A scope can be in the Scopes application by creating a scope definition. A scope definition is made up of scope rules and/or scope exceptions that include or exclude nodes and subtrees from the view selected in System Browser. A system object can be contained in one or multiple scope definitions.
- The filter by scope can be used together with any other filter conditions. The result of the search will contain all the nodes that will match any other specified conditions and that are part of the scope.
Note that a search by scope might take some time to provide its result.
Property Usage – type
Property | Type | Default | Annotation |
type | Integer Integer Array TypeFilter Array |
| Object types and subtypes to be used as filter criteria. In particular, array of arrays of integers is used to specify the subtypes. |
- Types and subtypes are defined in the text group: Object Types. The type and subtype of a system object are defined in the object model and can be re-defined using the Object Configurator application.
- A filter by type can be one of the following:
- A simple value indicating the type:
filter.type = 8300;
- A TypeFilter object that includes one type and any subtypes:
filter.type = new TypeFilter(8300, [8301]);
- An array of TypeFilter objects:
var type = new TypeFilter(8300, [8301]);
var type2 = new TypeFilter(8400, [8401, 8402]);
filter.type= [type, type2];
Error Handling
Errors can occur in case:
<systemId>
value is negative- Last Execution Error =
"Invalid systemId."
- <systemId> does not represent a valid system
- Last Execution Error =
"System with id <systemId> not found."
- Last Execution Error =
"System with name <systemId> not found."
- The type of
<systemId>
is not valid - Last Execution Error =
"Invalid value type specified for systemId."
<view>
- is specified with numeric value (Last Execution Error =
"No public methods with the specified arguments were found."
) - Is not existing (Last Execution Error =
"No public methods with the specified arguments were found."
or"<View >' not found in <System Id>"
) - The filter object:
- Is created or set with a non-existing <
view>
- Is created with an invalid (numeric) value for the <
Object Model>
.
The script generates an exception and ends with failure. - Invalid <
disciplines>
, <subdisciplines>
, <type>
, or <subtype>
- Invalid <
name
> (filter.name = "name";
) and invalid<descriptor>
(filter.descriptor = "descriptor";
) - The script interrupts (Last Execution Error is
"descriptor is not compatible with name"
.) - Defining an Invalid combination of filter options:
- name + designation
- descriptor + location
- location + designation
<functionName>
is specified with numeric value or the array of functions contains at least a numeric value.- Scope designation is not existing in a Desigo CC system or not visible to the user who executes the script because of insufficient user rights for the scopes.
- A log is traced in the Log Viewer while the script continues running.
- Invalid
<scope>
configuration. - If the provided scope is a valid node but is not a scope node, the script ends with an exception (error message:
"The Scope filter contains objects that are not scopes"
.) The error condition is evaluated the first time a Search is performed using such filter.
Examples of Use
How to create a filter to get all the system objects in all the views of the current system
var filter = new Filter()
How to create a filter to get all the system objects in a specific view of the current system
var filter = new Filter(0, view)
How to create a filter to get all the system objects in all the views of a specific system
var filter = new Filter(systemId)
How to create a filter to get all the system objects in a specific views of a specific system
var filter = new Filter(systemId, view)
How to create a filter to get all the system objects in the Application View
var filter = new Filter(0, "System1.ApplicationView:ApplicationView");
or:
var filter = new Filter();
filter.view = "System1.ApplicationView:ApplicationView";
How to create a filter to get all the system objects in Management View
var filter = new Filter(0, "System1.ManagementView:ManagementView");
How to create a filter to get any system objects that have a specific object model (current system, all views)
var filter = new Filter();
filter.objectModel = "GmsOrganizationMode";
How to create a filter to get any system objects that have certain object models (current system, all views)
var filter = new Filter();
filter.systemId = 0;
filter.view = "System1.ApplicationView:ApplicationView";
filter.objectModel = ["GmsMacro", "GMS_Script", "GmsReaction"]
How to use the ObjectModel filter (name = "GMS_Script") to get all the script objects
(a)
var filter = new Filter();
filter.objectModel = "GMS_SCRIPT";
var result = searchSync(filter);
(b)
var filter = new Filter();
filter.objectModel = "GMS_SCRIPT"
;
filter.caseSensitive = false;
var result = searchSync(filter);
(c)
var filter = new Filter();
filter.objectModel = "GMS_Script"
;
var result = searchSync(filter);
(d)
var filter = new Filter();
filter.objectModel = "GMS_Script"
;
filter.caseSensitive = true;
var result = searchSync(filter);
Samples (a) and (b) return the script objects, while samples (c) and (d) do not return any value, (because the correct name for the object model is "GMS_SCRIPT").
How to create a filter to get all the system objects by alias (using wildcards only)
var filter = new Filter();
filter.alias = "*";
var result = searchSync(filter);
How to create a filter to get any system object for the specified alias (including the text “Item”)
var filter = new Filter();
filter.alias = "*Item*";
var result = searchSync(filter);
How to create a filter to get any system objects belonging to the Fire (100) discipline
var filter = new Filter();
filter.discipline = 100;
Or
filter.discipline = [100, 200, 250];
Or
filter.discipline = [new DisciplineFilter(100), new DisciplineFilter(200), new DisciplineFilter(250)];
When applied, these filters return the system objects having Discipline = 100 (Fire), or having 100, 200 and 250 values (Fire, Energy Management e Notification). In all the cases an array is used.
How to get all the system objects that have Fire discipline and Extinguishing or Detection subdisciplines, or Management System discipline and Applications subdiscipline
filter.discipline = [
new DisciplineFilter(100, [102, 103]),
new DisciplineFilter(0, [1])
];
When applied, this filter returns:
- Any objects having discipline 100 (Fire) and subdisciplines 102 (Extinguishing) or 103 (Detection)
- Any objects having discipline 0 (Management System) and subdiscipline 1 (Applications)
How to get all the system objects that have Zone (8300) type
var filter = new Filter();
filter.type = 8300;
Or
filter.discipline = new TypeFilter(8300);
How to get any system objects that have Zone (8300) type or View Element (8000), Zone (8300) and Heat Generation (8600) types
var filter = new Filter();
filter.type = [8300];
Or
filter.type = [8000, 8300, 8600];
Or
filter.type = [new TypeFilter(8000), new TypeFilter(8300), new TypeFilter(8600)];
How to get any system objects that have Fire (100) discipline, Detection (103) subdiscipline, Zone (8300) type, and Automatic (8301 subtype)
filter.discipline = new DisciplineFilter(100, 103);
filter.type = new TypeFilter(8300, 8301);
var result = searchSync(filter);
How to get any system objects that have Zone (8300) type and Automatic (8301 subtype)
filter.type = new TypeFilter(8300, 8301);
Or
filter.type = new TypeFilter(8300, [8301]);
How to reset the discipline and type properties for a filter
var filter = new Filter();
filter.discipline = [ ];
filter.type = [ ];
var result = searchSync(filter);
These instructions reset the Discipline and Type filters. This means that all the Disciplines and Types are returned.
How to get Script objects using the object model and caseSensitive filters
(a)
var filter = new Filter();
filter.objectModel = "GMS_Script";
var result = searchSync(filter);
(b)
var filter = new Filter();
filter.objectModel = "GMS_Script";
filter.caseSensitive = false;
var result = searchSync(filter);
(c)
var filter = new Filter();
filter.objectModel = "GMS_Script";
var result = searchSync(filter);
(d)
var filter = new Filter();
filter.objectModel = "GMS_Scripts";
filter.caseSensitive = true;
var result = searchSync(filter);
Samples (a) and (b) return the Script objects. Samples (c) and (d) do not return any value, because the object model is invalid.
How to get all the Script objects using the location and caseSensitive filters
(a)
var filter = new Filter();
filter.location = "*.Scripts";
var result = searchSync(filter);
(b)
var filter = new Filter();
filter.location = "*.scripts";
filter.caseSensitive = false;
var result = searchSync(filter);
(c)
var filter = new Filter();
filter.loocation = "ApplicationView.Logics.Scripts";
var result = searchSync(filter);
(d)
var filter = new Filter();
filter.location = "Scripts";
var result = searchSync(filter);
Samples (a), (b), and (c) return the Script objects. Sample (d) does not return any value, because the Scripts alone is not the correct location for the scripts node (See sample (c) for the correct location without wildcard).
How to get all the Script objects using the designation and caseSensitive filters
(a)
var filter = new Filter();
filter.designation = "*.Scripts";
var result = searchSync(filter);
(b)
var filter = new Filter();
filter.designation = "*.scripts";
filter.caseSensitive = false;
var result = searchSync(filter);
(c)
var filter = new Filter();
filter.designation = "Applications.Logics.Scripts";
var result = searchSync(filter);
(d)
var filter = new Filter();
filter.designation = "Scripts";
var result = searchSync(filter);
Samples (a), (b), and (c) return the Script objects. Sample (d) does not return any value, because the Scripts alone is not the correct location for the scripts node (See sample (c) for the correct location without wildcard).
How to get all the Script objects using view, name, and caseSensitive filters
(a)
var filter = new Filter();
filter.view = "System1.ApplicationView:ApplicationView";
filter.name = "Scripts";
var result = searchSync(filter);
(b)
var filter = new Filter();
filter.view = "System1.ApplicationView:ApplicationView";
filter.name = "scripts";
filter.caseSensitive = false;
var result = searchSync(filter);
(c)
var filter = new Filter();
filter.name = "Scripts";
var result = searchSync(filter);
Samples (a) and (b) return one result. Sample (c) also returns nodes defined in the library objects of the Management View.
How to get the virtual objects using view, descriptor, and caseSensitive filters
(a)
var filter = new Filter();
filter.view = "System1.ApplicationView:ApplicationView";
filter.descriptor = "Virtual Objects";
var result = searchSync(filter);
(b)
var filter = new Filter();
filter.view = "System1.ApplicationView:ApplicationView";
filter.descriptor = "virtual objects";
filter.caseSensitive = false;
var result = searchSync(filter);
(c)
var filter = new Filter();
filter.descriptor = "Virtual Objects";
var result = searchSync(filter);
Samples (a) and (b) return one result. Sample (c) also returns nodes defined in the library objects of the Management View.
How to use combinations of location and name filters
(a)
var filter = new Filter();
filter.location = "*.Scripts";
filter.name = "MyScript";
var result = searchSync(filter);
(b)
var filter = new Filter();
filter.location = "*.Scripts";
filter.name = "*script*";
var result = searchSync(filter);
Sample (a) returns a script (if existing) with Designation "*.Scripts.MyScript".
Sample (b) returns all the scripts located in the Scripts folder that have "script" as text in the CNS name.
How to use combinations of designation and descriptor filters
(a)
var filter = new Filter();
filter.designation = "Applications.*";
filter.descriptor= "*script*";
filter.caseSensitive = false;
var result = searchSync(filter);
Sample (a) returns all nodes in the Application View that have "script" as text in the descriptor.
How to create a filter by specifying a function
var filter = new Filter();
filter.functionName = "FanDigital";
var results = searchSync(filter);
if (results== null || results.length == 0) {
console("No objects found");
terminate();
}
console("Objects count = {0}", results.length);
for(var i = 0; i < results.length; i++) {
var obj = results[i];
console("\t : {0}, {1}, {2}",filter.functionName,i, obj);
}
The functionName property is specified while the result will contain all the nodes associated with that function. Also note the use of the filter.FunctionName filter
to access any function present in the objects returned by searchSync
.
How to create a filter by specifying function and case sensitive filters
var filter = new Filter();
filter.functionName = "fandigital";
filter.caseSensitive = false;
var results = searchSync(filter);
if (results== null || results.length == 0)
console("No objects found");
terminate();
}
console("Objects count = {0}", results.length);
for(var i = 0; i < results.length; i++) {
var obj = results[i];
console("\t : {0}, {1}, {2}",filter.functionName,i, obj);
}
The result is the same as in the previous example.
How to create a filter with an array of functions
var filter = new Filter();
filter.functionName = ["FanDigital", "BoilerDigital", "ChillerDigital"];
var results = searchSync(filter);
if (results== null || results.length == 0) {
console("No objects found");
terminate();
}
console("Objects count = {0}", results.length);
for(var i = 0; i < results.length; i++) {
var obj = results[i];
console("\t : {0}, {1}, {2}",filter.functionName, i, obj);
}
How to create a filter with a scope defined with designation and search for all nodes in this scope
var filter = new Filter();
filter.scope = "System1.ManagementView:ManagementView.SystemSettings.ScopesRootFolder.Authorization.DefaultAuthorizationScope";
var results = searchSync(filter);
if (results == null || results.length == 0) {
console("No objects found");
terminate();
}
console("Objects count = {0}", results.length);
for(var i = 0; i < results.length; i++) {
var obj = results[i];
console("\t : {0}, {1}",[i, obj]);
}
The result will contain all the nodes included in the specified scope.
How to create a filter with a scope defined with a BrowserObject and search for all nodes in this scope
var scopeDefinition = new BrowserObject("System1.ManagementView:ManagementView.SystemSettings.ScopesRootFolder.Authorization.DefaultAuthorizationScope");
var filter = new Filter();
filter.scope = scopeDefinition;
var results = searchSync(filter);
if (results == null || results.length == 0) {
console("No objects found");
terminate();
}
console("Objects count = {0}", results.length);
for(var i = 0; i < results.length; i++) {
var obj = results[i];
console("\t : {0}, {1}", i, obj);
}
The result is the same as in the previous example.
How to create a filter with a scope defined with an array of designations and search for all nodes in these scopes
var filter = new Filter();
filter.scope = ["System1.ManagementView:ManagementView.SystemSettings.ScopesRootFolder.Authorization.DefaultAuthorizationScope", "System1.ManagementView:ManagementView.SystemSettings.ScopesRootFolder.scope"];
var results = searchSync(filter);
if (results == null || results.length == 0) {
console("No objects found");
terminate();
}
console("Objects count = {0}", results.length);
for(var i = 0; i < results.length; i++) {
var obj = results[i];
console("\t : {0}, {1}",i, obj);
}
An array of scopes is specified. The result will contain all the nodes defined in those scopes.
How to create a filter with a scope defined with an array of BrowserObject objects and search for all nodes in these scopes
var scopeDefinition1 = new BrowserObject("System1.ManagementView:ManagementView.SystemSettings.ScopesRootFolder.Authorization.DefaultAuthorizationScope");
var scopeDefinition2 = new BrowserObject("System1.ManagementView:ManagementView.SystemSettings.ScopesRootFolder.scope");
var filter = new Filter();
filter.scope = [scopeDefinition1, scopeDefinition2];
var results = searchSync(filter);
if (results == null || results.length == 0) {
console("No objects found");
terminate();
}
console("Objects count = {0}", results.length);
for(var i = 0; i < results.length; i++) {
var obj = results[i];
console("\t : {0}, {1}",i, obj);
}
The scope
property is specified using a BrowserObject array where those scopes were defined. The result will contain all the nodes in such scopes.