Usually, information is stored in a model using object properties (setAttrValue). These properties might be visible to the user or be defined as "hidden", but in all cases, they need to be explicitly defined before a script uses them.

However, there are times when you will want to store information in a less formal way, for example, to remember results of earlier runs of the script, mark objects that are of interest, or keep track of script-related data in general. This kind of data does not need to be visible to the user and does not need the extensive (type) checking that comes with proper profile attributes. This is where tagged values are appropriate.

A tagged value is simply a name-value pair that can be attached to any object within the model package hierarchy. You may store a value of any type, and you may store it under any name as long as this name is unique among the other tagged values on the object.

setTaggedValue, removeTaggedValue

These are the methods to add or remove tagged values:

<object>.setTaggedValue( <name>, <value>[, <persistent>[, <undoable>]] )
<object>.removeTaggedValue( <name>[, <undoable>] )

<object>

A value of the type Object or an expression evaluating to a value of that type.

<name>

A string or an expression evaluating to a value of that type: the name of the tagged value. This name should be unique amongst the other tagged values present on this object.

<value>

A value of any type that has to be stored with the object.

<persistent>

(Optional) A boolean or an expression evaluating to a value of that type: when true, the tagged value will be stored permanently when the model package is saved. When false, the tagged value will remain on the object until the package is closed and is then discarded. If omitted, this parameter is false (values are discarded upon closing).

<undoable>

(Optional) A boolean or an expression evaluating to a value of that type: when true, the tagged value will respond to the use of the undo command. When false, the setting/removing of the tagged value will not be rolled back when the undo command is used. This is only allowed when <persistent> is false: persistent changes must be undoable. If omitted, this parameter is true (setting/removing the value is undoable).

hasTaggedValue

To test if a tagged value exists, you may use this method:

<result> = <object>.hasTaggedValue( <name> )

<object>

A value of the type Object or an expression evaluating to a value of that type.

<name>

A string or an expression evaluating to a value of that type: the name of the tagged value.

<value>

A value of type boolean: true if a tagged value with the name specified is present on this object, false otherwise.

getTaggedValue(s)

To retrieve tagged values, use one of these methods:

<value> = <object>.getTaggedValue( <name> )

<values> = <object>.getTaggedValues([<persistent>])


<object>

A value of the type Object or an expression evaluating to a value of that type.

<name>

A string or an expression evaluating to a value of that type: the name of the tagged value.

<persistent>

(Optional) A boolean or an expression evaluating to a value of that type: when true, getTaggedValues only returns persistent tags; when false, only nonpersistent tags are returned; when omitted, all tags, persistent and nonpersistent, are returned.

<value>

A value of any type that was stored with the object under the name specified. When the tagged value is not found, an undefined value is returned. If you want to test for the tagged value first, use hasTaggedValue.

<values>

A value of type Index containing all tagged values found on the object.


Please note that the tool itself also might use tagged values: these values will not be critical to the functionality, but you might want to be careful in removing or overwriting existing values. By choosing names for your tags that are surely unique, the risk of colliding with existing tool tags is minimal.

This example uses a tagged value to ensure a script is only executed once on a model:

if ( model.hasTaggedValue("processed") ) {
       stop;
}
model.setTaggedValue("processed", "yes", true);
// ... rest of script ...


When importing objects from an external source, the object's external id might be stored in a tagged value to prevent reimporting the same object. For example:

scheme = model.addNewObject("BusinessScheme");
forall line in datasource("separated", "C:\\data.txt", "\t") {
     if ( !line.empty() ) {
            type = line[1]; name = line[2]; id = line[3];
            exists = false;
            forall type obj in model {
                 if ( obj.hasTaggedValue("ext-id") &&
                        obj.getTaggedValue("ext-id") == id ) {
                        exists = true;
                       break;
                 }
            }
            if ( !exists ) {
                   newobj = scheme.addNewObject(line[1],line[2]);
                   newobj.setTaggedValue("ext-id",line[3],true);
            }
      }
}