Version: 8.1

system.tag.configure

This function is used in Python Scripting.

Description

Creates tags from a given list of Python dictionaries or from a JSON source string. Can be used to overwrite a current tag's configuration.

When utilizing this function, the tag definitions must specify the names of properties with their scripting/JSON name. A reference of these properties can be found on the Tag Properties and Tag Alarm Properties pages.

New in 8.1.33

It is no longer necessary to specify the datatype when editing a dataset tag. The dataset tag will now keep expected structure and correctly deserialize new values.

Client Permission Restrictions

Permission Type: Tag Editing

Client access to this scripting function is blocked to users that do not meet the role/zone requirements for the above permission type. This function is unaffected when run in the Gateway scope.

Syntax

system.tag.configure(basePath, tags, [collisionPolicy])

Parameters

Type	Parameter	Description
String	`basePath`	The starting point where the new tags will be created. When making changes to existing tags with this function, you want to set the path to the parent folder of the existing tag(s), not the tag(s) themselves.
Any	`tags`	A list of tag definitions, where each tag definition is a Python dictionary. Alternatively, a JSON source string may be passed to this parameter. When editing existing tags, it is generally easier to retrieve the tag configurations with system.tag.getConfiguration, modify the results of the getConfiguration call, and then write the new configuration to the parent folder of the existing tag(s).
String	`collisionPolicy`	The action to take when a tag or folder with the same path and name is encountered. Defaults to Overwrite. [optional]. Possible values include: a - Abort and throw an exception. o - Overwrite and replace existing tag's configuration. i - Ignore that item in the list. m - MergeOverwrite, modifying values that are specified in the definition, without impacting values that aren't defined in the definition. Use this when you want to apply a slight change to tags, without having to build a complete configuration object.

Returns

List - A List of QualityCode objects, one for each tag in the list, that is representative of the result of the operation. See Scripting Object Reference.

Scope

Gateway, Vision Client, Perspective Session

Code Examples

Example #1 - Edit Multiple Tags
# This example will retrieve some existing tag configurations, make changes to the configurations,
# and write the new configurations to the original tags.
 
 
# Define a base path. Sometime useful, but we could hardcode the paths
# in the getConfiguration() and configure() calls.
parentPath = "[NewProvider]SomeFolder"
 
# Get the current configurations recursively, which is useful when targeting
# folders and UDT Instances.
configs = system.tag.getConfiguration(parentPath + "/AnotherFolder", True)
 
# The getConfiguration() above always returns a list of dictionaries, and our results
# are inside of the first dictionary.
for tag in configs[0]['tags']:
 
    # Check each node. At this point we may get folders or other nodes
    # that we're uninterested in. Examine tagType to figure it out.
    # Note that we're making sure the tagType is in fact a string for this comparison. 
    if str(tag['tagType']) != 'Folder':
         
        # Make a change to the Tag. If we're iterating over UDT instances,
        # then we can change the parameters here. Commented example below:
        # tag['parameters']['myParam'] = foo
         
        # In our case, we'll just disable the Tags.
        tag['enabled'] = False
 
system.tag.configure(parentPath, configs, "o")

Example #2 - Adding a New Tag
# This example will add a new OPC Tag. It can be further expanded to modify more
# properties on the Tag. Additionally, this example can be used to edit an existing Tag
# by setting the baseTagPath to a Tag that already exists, and by modifying the collision policy.
 
# The provider and folder the Tag will be placed at. 
baseTagPath = "[default]MyFolder"
 
# Properties that will be configured on that Tag.
tagName = "myNewTag"
opcItemPath = "ns=1;s=[Simulator]_Meta:Sine/Sine0"
opcServer = "Ignition OPC-UA Server"
valueSource = "opc"
sampleMode = "TagGroup"
tagGroup = "Default"
 
# Configure the tag.
tag = {
            "name": tagName,           
            "opcItemPath" : opcItemPath,
            "opcServer": opcServer,
            "valueSource": valueSource,
            "sampleMode" : sampleMode,
            "tagGroup" : tagGroup
        }
 
# Set the collision policy to Abort. Thus, if a Tag already exists at the base path,
# we will not override the Tag. If you are overwriting an existing Tag, then set this to "o".
collisionPolicy = "a"
 
# Create the Tag.
system.tag.configure(baseTagPath, [tag], collisionPolicy)

Example #3 - Interacting with Alarms
# The provider and folder the Tag will be placed at. 
baseTagPath = "[default]"
 
# Create a list of alarms, where each alarm is a Python dictionary.
alarms = [
            {
                "name":"My scripting alarm",               
                "mode":"AboveValue",               
                "setpointA":10
            }
        ]
 
# Configure the list of Tags. We're only interacting with a single Tag, but still need to pass
# a list as an argument.
tags = [
            {
                "alarms":alarms,
                "name":"myTag"
            }
        ]
 
# Abort if this example attempts to overwrite any of your existing Tags.
collisionPolicy = "a"
 
# Create the Tag.
system.tag.configure(baseTagPath, tags, collisionPolicy)

Example #4 - Add UDT Instance
# This example will add a new UDT Instance. It can be further expanded to modify more
# properties on the Tag. Additionally, this example can be used to edit an existing Tag
# by setting the baseTagPath to a Tag that already exists, and by modifying the collision policy.
  
# The provider and folder the Tag will be placed at.
baseTagPath = "[default]Motors"
  
# Properties that will be configured on that Tag.
tagName = "Motor 1"
typeId = "Motor"
tagType = "UdtInstance"
# Parameters to pass in.
motorNum = "1"
  
# Configure the Tag.
tag = {
            "name": tagName,         
            "typeId" : typeId,
            "tagType" : tagType,
            "parameters" : {
              "motorNum" : motorNum
              }
       }
 
# Set the collision policy to Abort. That way if a tag already exists at the base path,
# we will not override the Tag. If you are overwriting an existing Tag, then set this to "o".
collisionPolicy = "a"
  
# Create the Tag.
system.tag.configure(baseTagPath, [tag], collisionPolicy)

Example #5 - Adding Folders in other Folders
# Folders are nodes with a 'tagType' set to 'Folder'.
# Each folder can contain a 'tags' value, which containers other tags and folders.
 
Tags={'tagType': 'Folder',
        'name': 'NewFolderName',
        'tags' : [
                    {
                    'name': 'anotherfolder',
                    'tagType': 'Folder',
                    'tags': [{}]            # There aren't any objects defined here, so this will just be an empty folder.                 
                    }
                ]
        }
 
system.tag.configure(   basePath = '',
                        tags = Tags,
                        collisionPolicy = "o"
                    )

Example #6 - UDT Parameters and Bindings
# This example configures bindings that make use of three UDT parameters.
tag = {
  "name": "UDTName",
  "parameters": {
    "device": {
      "dataType": "String",
      "value": "[Sample_Device]"
    },
    "opcPath": {
      "dataType": "String",
      "value": "_Meta:Ramp/Ramp0"
    },
    "opcServer": {
      "dataType": "String",
      "value": "Ignition OPC UA Server"
    }
  },
  "tagType": "UdtType",
  "tags": [
    {
    # Creating a binding involves change the key to an object, with a "bindType" key set to "parameter", and a
    #  "binding" key set to the binding. Note that the actual binding can consist multiple parameters and characters
      "opcItemPath": {
        "bindType": "parameter",
        "binding": "{device}{opcPath}"
      },
      "opcServer": {
        "bindType": "parameter",
        "binding": "{opcServer}"
      },
      "valueSource": "opc",
      "name": "New Tag",
      "tagType": "AtomicTag"
    }
  ]
}
 
path = "[default]"
system.tag.configure(path, [tag], "o")

Example #7 - Writing to Parameters in UDT Definition

In this example, we're going to change the value on a UDT Definition parameter with a script. It assumes there is a UDT Definition already configured at the root of the Data Types folder (in this case, named "myUdtDef"), and contains a parameter (named "myParam").

Tag Browser	Tag Editor

# UDT Definitions reside in the "_types_" folder, which can be retrieved
# via the Tag Browser : right-click > Copy Tag Path.
# Retrieving the existing configuration is much easier than typing it all out.
tag = system.tag.getConfiguration("[default]_types_/myUdtDef")
 
# This line is accessing the first tag in our results (the UDT Definition), then returns the
# 'parameters' dictionary, which then provides access to individual parameters.
tag[0]['parameters']['myParam'] = '300'
 
# Overwrite the existing configuration.
collisionPolicy = "o"
  
# Write the new configuration to our existing UDT Definition.
# Note that the first parameter is to the parent folder of the Definition,
# not a path to the Definition.
system.tag.configure("[default]_types_", tag, collisionPolicy)
 
# Once the configure call finishes, myParam on the Definition should have a value of 300.

Description​

Client Permission Restrictions​

Syntax​

Parameters​

Returns​

Scope​

Code Examples​