Skip to main content
Version: 8.1

system.tag.browse

This function is used in Python Scripting.

Description​

Returns a list of nodes found at the specified path. The list objects are returned as dictionaries with some basic information about each node.

Client Permission Restrictions​

This scripting function has no Client Permission restrictions.

Syntax​

system.tag.browse(path, filter)

Parameters​

TypeParameterDescription
StringpathThe path that will be browsed, typically to a folder or UDT instance.
Dictionary[String, Any]filterA dictionary of browse filter keys. Keys are listed below.

Returns​

Results - A Results object which contains a list of Tag dictionaries, one for each Tag found during the browse. See Scripting Object Reference.

Scope​

Gateway, Vision Client, Perspective Session

Filter Keys​

The following keys represent filter criteria that can be used by the filter parameter.

  • name - The name of the item. Utilizes the * character as a wildcard character.

    # Literally search for "MyTag"
    {"name":"MyTag"}

    # Searches for any names that contain "Tag" in their name
    {"name":"*Tag*"}

  • dataType - Represents the data type on the Tag. Valid values can be found on the Tag Properties page.

    {"dataType":"Int4"}

  • valueSource - Represents how the node derives its value. Generally only used by nodes with a Tag type of "AtomicTag". Valid values can be found on the Value Source description on the Tag Properties page.

    {"valueSource":"opc"}

  • tagType - The type of the node (Tag, folder, UDT instance, etc). A list of possible types can be found on the Tag Properties page.

    {"tagType":"AtomicTag"}

  • typeId - Represents the UDT type of the node. If the node is a UDT definition, then the value will be None. If the node is not a UDT, then this filter choice will not remove the element. As such, this filter functions best when paired with a tagType filter with a value of UdtInstance.

    {"typeId":"myUDT", "tagType":"UdtInstance"}

  • quality - Represents the quality on the node. While there are many types of quality codes, this function only recognizes "Bad" and "Good". More granular quality codes are ignored.

    {"quality":"Good"}

  • maxResults - Limits the amount of results that will be returned by the function.

    {"maxResults":10}

  • ​

    New in 8.1.2
    recursive - Allows the browse to find all Tags inside the starting folder or UDT instance, even if they are inside nested folders or UDT instances themselves. Accepted values are True and False. False is the default, meaning that the browse will only return tags directly inside the starting folder or UDT instance.

    {"recursive":True}

Results Object​

The contents of each dictionary in the Results object varies based on the tagType of the node in question.

General Keys​

By default all dictionaries contain the following:

  • fullPath - A fully qualified Tag path to the node, including the name of the node. The value returned by this key is a BasicTagPath. However you can easily cast the variable to a string:

    # Browse the Tag Provider named "default".
    results = system.tag.browse("[default]")

    for i in results.getResults():
        stringPath = str(i['fullPath'])

        # Do something useful with the stringPath...

  • hasChildren - A boolean representing if the node contains sub-nodes, such as folders and UDT definitions. Useful in cases where you need to recursively call the browse function.

  • name - The name of the node. The value returned by this key is unicode. However, you can easily cast the variable to a string:

    # Browse the Tag Provider named "default".
    results = system.tag.browse("[default]")

    for i in results.getResults():
        stringType = str(i['name'])

        # Do something useful with the stringType...

  • tagType - The type of the node. The value returned by this key is TagObjectType. However, you can easily cast the variable to a string:

    # Browse the Tag Provider named "default".
    results = system.tag.browse("[default]")

    for i in results.getResults():
        stringType = str(i['tagType'])

        # Do something useful with the stringType...

Tag Keys​

If the node is a Tag (tagType = AtomicTag), then it will also contains the following keys:

KeyDescription
dataTypeThe data type of the tag.
valueSourceRepresents how the Tag derives its value.
valueThe last known qualified value on the tag.

UDT Keys​

Both UDT Instances and UDT Definitions add the following key:

KeyDescription
tagIdRepresents the parent UDT.
tagTypeRepresents the type of the node. UDT Definitions will have a value of None.

Code Examples​

Example #1 - Simple Browse
# This simple script will browse a given Tag path, in this case the root of the provider called default, and print the results.
 
results = system.tag.browse(path = '[default]', filter = {})
for result in results.getResults():
    print result
Example #2 - Filtered Browse
# This simple script will browse a given Tag path, in this case the root of the provider called default, and print the results.
# It also is filtering out anything that is not Atomic Tag, like folders and UDT Instances.
 
results = system.tag.browse(path = '[default]', filter = {'tagType':'AtomicTag'})
for result in results.getResults():
    print result
Example #3 - Wildcards with the Name Parameter
# Similar to the Filtered Browse above, except a wildcard character may be used when filtering on the name parameter
# The wildcard character ( the * character) represents any number of characters, including none. 
 
results = system.tag.browse(path = '[default]', filter = {'name':'*M*'})
for result in results.getResults():
    print result
Example #4 - Simple Browse with Condition
# This simple script will browse a given Tag path, in this case the root of the Tag Provider called default, and print the results.
# After it browses, it finds all of the items that do not have children and prints only those.
 
results = system.tag.browse(path = '[default]', filter = {})
for result in results.getResults():
    if result['hasChildren'] == False:
        print result
Example #5 - Recursive Browse
# This script has created a browseTags function which can be called with a Tag path and filter.
# The function will recursively find all items under that path by going into folders and UDT Instances.
# This example gives the initial path of '[default]', meaning it will find every item in the Tag Provider called default.
 
results = system.tag.browse("[default]", {"tagType":"UdtInstance", "recursive":True}).results
for result in results:
        print str(result['fullPath'])