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.

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 terminates 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 terminates 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.