Custom Global Filters for Tags and Areas

Global tag and area filtering is applied on a per-user basis and therefore is also referred to as User Tag Filtering (UTF) or User Area Filtering (UAF).

Global filters are applied on a user-by-user basis to all tags and alarms in the system that a user can see. Whether a user is able to apply a user filter is based on a Global Filtering security privilege and the UserFilterMode configuration setting

The global filters are stored in a UserFilters network value in the session with an instance name based on the realm and account ID. These are retained for the user across a network. The UserFilters network value is a structure with elements Areas and Tags that contains dictionaries of patterns used for global area and tag filtering. Helper functions are available, which can aid in setting the user filters programmatically and which constitute the API for user filtering.

In the following examples, "Session" is an object reference returned by GetUserSession().

Session.IsUserFilterEnabled():

This is a public module to get the current status of user filtering, which returns a structure of Booleans. Its elements are Areas, Tags and Any.

The Areas element is true if there is at least one Global Area Filter active. The Tags element is true if there is at least one Global Tag Filter active. The Any element is true if either filter is active. For example:

\GetUserSession().IsUserFilterEnabled().Any

... will return TRUE (1) if either of an area filter or a tag filter is active.

Session.SetUserAreaFilter(AreaFilterDict):

This module takes in a dictionary of area patterns and assigns it to the UserFilters.Areas NetworkValue. This is the API by which global area filters can be set. It takes a single parameter, which is a dictionary, keyed by Area patterns (e.g. North, South*st, W?st), with values TRUE. Any tag or alarm with an area that passes any of the filters in the set (ORed) will be shown, otherwise they will be hidden. If no areas match the filter, nothing will be shown. To clear the filter (show alarms and tags irrespective of their areas), the call is SetUserAreaFilter(Invalid), which also sets the UserFilter.Areas Network value to Invalid.

Setting any of the filters to "*" is equivalent to showing all areas, and the UserFilters.Areas network value will be set to Invalid.

Session.SetUserTagFilter(TagFilterDict):

This module takes in a dictionary of name patterns and assigns it to the UserFilters.Tags NetworkValue. This is the API by which global tag filters can be set. It takes a single parameter, which is a dictionary, keyed by tag patterns (e.g. Tag1, Tag1\Tag2*, *Pump*, *\Chlorine), with values TRUE if all of the tag's children are to be included, and FALSE if not (this is only necessary for the Global Filter Dialog GUI tool if it is to be used). Any tag or alarm with a name which passes any of the filters in the set (ORed) will be shown otherwise they will be hidden. If no names match the filter, nothing will be shown. To clear the filter (show alarms and tags irrespective of their names), the call is SetUserTagFilter(Invalid), which also sets the UserFilter.Tags Network value to Invalid. Note: Setting any of the filters to "*" is equivalent to showing all tag names, and the UserFilters.Tag network value will be set to Invalid.

Best Practices for User Filters

Special considerations are made for "\" characters. To ensure that parent tags as well as their children are captured by the tag filter, it is required that each filter be followed by a \, and that all \ characters be replaced by \\ for the pattern match. This is handled within the API where, (for example) if dictionary Key "Tag1" is passed into the API, it will be stored as "Tag1\\" in the Network Value. From an efficiency standpoint, the best filters formats (Dictionary keys) are:

• An exact tag name with no wildcards.
  For example, A\B\C\D for just one tag.
• An exact tag name followed by "\*".
  For example, A\B\C\D\* for A\B\C\D and all of its children.

In the case where you want to see the parents of A\B\C\D, but not all of their children, the pattern set would be: A\ , A\B\ , A\B\C\ , A\B\C\D\*.

Other patterns are possible and should work, but may be much slower.

Master/Subordinate filters

This is a requirement for filtering alarms. Due to the nature of subordinate applications, when using Realm/User tag filtering it is a requirement that the filters contain the explicit name of the subordinate tag in the master followed by a "backslash character, "\". Do not use wild cards in the subordinate application name, except at the beginning. Following are some examples of filters to be used in the master application, where SubApp is the subordinate tag:

Good examples. The following will work

SubApp\MyAlarms\*

MasterFolder\SubApp\My?Alarms\*MoreTags?\*Wh?*ateverWildcards

*MyAlarms\*

Bad examples. Do not create filters like these.

Master*Folder?\SubApp\MyAlarms\*

MyAlarms\*

*\MyAlarms\*

\*MyAlarms*