Attribute Mapping

Attribute Mapping determines how attributes from the source system are transformed to match the requirement of the target system. For each attribute from the source system, each mapping entry is examined to determine whether the attribute matches.

Note: The attribute qualifier is required in attribute mapping entries. You may specify a pattern property to match only attributes with a value that conforms to the regular expression.

Attribute mapping entries permit the following Values to be specified:

• Conditions to match

• Name of the attribute

• Value of the attribute

• Units of the attribute

A sample Attribute mapping example is as follows:

<Object>
...
<Attributes>

<Attribute>

<Name value="XYZ" />

<Value value="ABC" />

</Attribute>

</Attributes>

...

</Object>

Attribute Mapping entries can be broadly classified into the following:

Create:

The simplest form of attribute mapping entry to create a new attribute is shown below:

<Object>
...
<Attributes>
<Attribute>

<Name value="Identifier" />

<Value value="[Tag]" />

</Attribute>

</Attributes>

...

</Object>

This mapping entry adds a new attribute named Identifier to the source system. The attribute value is taken directly from the value of the Tag attribute from the source system.

The attribute mapping entry to create a new attribute matching a simple condition, is shown below:

<Object>
...

<Attributes>

<Attribute name="Tag" pattern="^[A-Za-z]+$" >

<Name value="Identifier" />

<Value value="[Tag]" />

</Attribute>

<Attributes>

...

</Object>

This mapping entry indicates that for all the objects matching the condition, if the Tag attribute in the source system is present, then a new attribute named Identifier is added. The attribute value is taken directly from the value of the Tag attribute from the source system.

The attribute mapping entry to create a new attribute taking multiple attributes with their corresponding patterns to match specific format is shown below:

<Object>
...
<Attributes>

<Attribute>
<Conditions>
<Attribute name="ClassName" pattern="Window" />
<Attribute name="SubType" pattern="Solid" />
</Conditions>
<Name value="Type" />
<Value value="[SubType] [ClassName]">
<Transforms>
<Replace pattern="\d{2}" value="yyy" />
</Transforms>
</Value>
<Units value="psi" />
</Attribute>

</Attributes>

...

</Object>

You may use a lookup to obtain the attribute value. You may use transforms to modify the attribute value from the source system.

Transforms may be combined with a lookup, in which case the transform is applied to the source value and the resulting value is passed to lookup:

<Object>
...
<Attributes>

<Attribute name="Tag" pattern="^[A-Za-z]+$" >

<Name value="Identifier" />

<Value value="[Tag]">

<Transforms>

<Replace pattern="\d{2}" value="yyy" />

</Transforms>

<Lookup Id="Attribute Value Map" >

<FailAction action = "FixedValue" value="[Name]" />

</Lookup>

</Value>

</Attribute>

</Attributes>

...

</Object>

Update:

The simplest form of attribute mapping entry is to update an existing attribute:

<Object>
...
<Attributes>

<Attribute name="Tag" pattern="^[A-Za-z]+$" >

<Value value="abcdef123" />

<!-- One can do transform or lookup here on the value if required -->

</Attribute>

</Attributes>

...

</Object>

This mapping entry indicates that for all the objects matching the condition, the Tag attribute in the source system, if present and matching the pattern then, the attribute value of Tag is fixed to abcdef123.

<Object>
...

<Attributes>

<Attribute name="Tag">

<Value value="ID#[Tag]" />

<!-- One can do transform or lookup here on the value if required -->

</Attribute>

</Attributes>

...

</Object>

This mapping entry indicates that for all the objects matching the condition, the Tag attribute in the source system, if present, then the attribute value of Tag is prefixed with the text ID#.

You can also use IncludeAssociatedObjectAttributes to modify the value of an attribute, as shown below:

<Object>

<IncludeAssociatedObjectAttributes>

<AssociationType pattern="^FillsVoids$" />

<Conditions>

<Attribute name = "ClassName" pattern = "^OPENINGELEMENT" />

<Attribute name = "Name" pattern = "^element1$" />

</Conditions>

</IncludeAssociatedObjectAttributes>

<Attributes >

<Attribute name="Tag" pattern="^[A-Za-z]+$" >

<Name value="Identifier" />

<Value value="[Tag] [associated:Tag]" />

</Attribute>

</Attributes>

...

</Object>

In the above case, the value of the Tag attribute along with the value of Tag of the first associated object matching the condition is used to derive the attribute value. You must use the prefix "associated:" to resolve the value from its associated objects.

<Object>

...

<IncludeAssociatedObjectAttributes>

<AssociationType pattern="^FillsVoids$" />

<Conditions>

<Attribute name = "ClassName" pattern = "^OPENINGELEMENT" />

<Attribute name = "Name" pattern = "^element1$" />

</Conditions>

</IncludeAssociatedObjectAttributes>

<Attributes >

<Attribute>

<Name value="Identifier" />

<Value value="[associated:Tag]" appendSeparator=";" />

</Attribute>

</Attributes>

...

</Object>

When there is more than one associated object with a Tag attribute and you need to include all of them, all these values can be aggregated into a single symbol-separated list value. In the above case, the value of the attribute Tag present in all associated objects matching the condition is used to derive the attribute Identifier value. All the values are joined using the separator string ";" defined by appendSeparator. You must use the prefix "associated:" to resolve the value from its associated objects.

The following example supports the case when there are associated object attributes more than one descendant level below the main object.

<Object>

...

<Conditions>

<Attribute name = "ClassName" pattern = "^DOOR$" />

</Conditions>

<TemplateID id ="default" />

<ObjectID value="[GlobalId]" />

<IncludeAssociatedObjectAttributes>

<AssociationType pattern="^Materials$" />

<Conditions>

<Attribute name = "ClassName" pattern = "^MATERIAL$" />

</Conditions>

</IncludeAssociatedObjectAttributes>

<Attributes>

<Attribute>

<Name value="Materials" />

<Value value="[associated{descendantLevel=2}:Name]" appendSeparator=";" />

</Attribute>

</Attributes>

...

</Object>

In the above case, the material values are in Material objects located two levels down in the object hierarchy: DOOR is associated (via the inverse relationship RELASSOCIATESMATERIAL) with MATERIALLIST, which is directly associated with two MATERIAL objects. You must therefore use the prefix "associated{descendantLevel=<level>}:" to resolve the value from its associated objects that are specified to a certain level in the object hierarchy. All of these values are joined using the separator string ";" defined by appendSeparator.

Remove:

The simplest form of an attribute mapping entry to remove an existing attribute is shown below:

The following mapping entry removes the attribute Tag from an object, if the attribute Tag is present in the source system.

<Object>
...

<Attributes>

<Attribute name="Tag" >

<Remove />

</Attribute>

</Attributes>

...

</Object>

The following mapping entry removes the attribute Tag from an object, if the attribute Tag is present in the source system and also matches the pattern.

<Object>
...

<Attributes>

<Attribute name="Tag" pattern="^[A-Za-z0-9]+$" >

<Remove />

</Attribute>

</Attributes>

...

</Object>

The following mapping entry removes all the attributes matching the pattern from an object.

<Object>
...

<Attributes>

<Attribute name="*" pattern="^[A-Za-z0-9]+$" >

<Remove />

</Attribute>

The following mapping entry removes all the attributes present in an object.

<Object>
...

<Attributes>

<Attribute name="*" >

<Remove />

</Attribute>

...

</Object>

keepUnmappedAttributes

This setting determines whether attributes that are not matched are included in the output EIWM file.

If this setting is true, then all the attributes are included in the output EIWM file.

If this setting is false, then only those attributes that have a matching mapping entry are included in the output EIWM file.

<Object>
...
<Attributes keepUnmappedAttributes="true">

<Attribute name="Tag">

<Value value="ID#[Tag]" />

</Attribute>

</Attributes>

...

</Object>

Notes:

The keepUnmappedAttributes setting is optional. By default, the keepUnmappedAttributes attribute value is true if the setting is not provided.

The following attributes are included in the EIWM file regardless of their mapping or of the value of keepUnmappedAttributes attribute being set to false:

• GlobalID

• Name

• ObjectID

• ObjectName

• ClassID

• Context

• RevisionID

• TemplateID

• IncidentalClassification

Excluding Objects from Output Files

You can add the following special attributes to specific objects to exclude them from the various output files:

• #EXCLUDE_FROM_EIWM# - excludes the objects from the EIWM file (but not associations to those objects from other objects).

• #EXCLUDE_FROM_CSV# - excludes the objects from CSV files, both CSV reports and CSV load files.

• #EXCLUDE_DOCUMENT_ASSOCIATIONS# - excludes the references to Document objects (usually represented by 'is referenced in' associations) in the EIWM file.

• #EXCLUDE_FROM_XGL# - excludes the object's hotspot (SELECTIONID) tagging information from XGL/ZGL the file, if produced.

It's possible to create multiple EXCLUDE attributes of different types on the same object to exclude it from the relevant multiple output files. If you do not want the EXCLUDE attribute for one type of output file appearing as an attribute in another type of output file, then set the attribute's system parameter to "true".

For example, the following configuration will exclude from a CSV file all objects that do not have a Class ID defined and the #EXCLUDE_FROM_CSV# attribute won't be included in the EIWM file:

<Object>
<Conditions>
<Attribute name="ClassID" pattern="" />
</Conditions>
<Attributes>
<Attribute system="true" >
<Name value="#EXCLUDE_FROM_CSV#"/>
<Value value=""/>
</Attribute>
</Attributes>
</Object>