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

systemId

View root node

view

System objects

alias

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:
- designation + name
-
location + descriptor
Any other mix of these filters is not allowed (an exception is thrown while the script execution terminates).

Case sensitivity

caseSensitive

Object model name

objectModel

Function name

functionName

Discipline and subdiscipline

discipline

Type and subtype

type

Scope definition

scope

Parameters/Properties Usage - systemId and view

Parameter

Type

Default

Use

Annotation

systemId

Integer

String

SystemObject

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; 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 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

DisciplineFilter Array

DisciplineFilters

-

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

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

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