Association Mapping

Association Mapping allows extracted associations to be customized in the output. It also permits new associations to be created in the output by transforming attributes from the source system.

A mapping entry may apply to a relationship from the source, or an attribute from the source depending upon whether it is customizing an association or generating a new one.

For each object from the source system, each mapping entry in the configuration is examined and compared against the object attributes. Each of the source object’s relationships are then examined and compared to the mapping entries.

Note: Including both ‘attribute’ and ‘relationship’ qualifiers on a mapping entry generates an error.

A sample Association mapping is as follows:

<Object>
...
<Associations>

<Association>
<Conditions>
<Attribute name="XYZ" pattern="^.*$"/>
</Conditions>
<Type value="ABC" />
</Association>

</Associations>

...

</Object>

Both forms of Association Mapping entries permit four values to be specified; the type of the association to generate, the ID of the object targeted by the association, the Context ID of the object targeted by the association and the Class ID of the object targeted by the association.

Multi-Value Attributes

The mapping entry below demonstrates how to create multiple associations in the output from an attribute that holds multiple values. Multi-value attributes are assumed to store multiple values delimited with a separator (for example, comma, semi-colon and so on). Each value held in the attribute is assumed to be an object ID, and a separate association is created in the output for each value stored in the attribute.

Note: All associated objects must exist in the same context and have the same classification. Each generated association has the same association type.

<Object>
...
<Associations>

<Association>
<Conditions>
<Attribute name="DecomposedOf" pattern="^.*$"/>
</Conditions>
<Type value="mapped_association" />
<TargetID value="P1;P2;P3;P4" >
<MultiValue separator=";" />
</TargetID>
<TargetClassID value="EQUIPMENT" />
</Association>

</Associations>

...

</Object>

Note: The <MultiValue> tag that designates the ''part_codes'' attribute as being a multivalued attribute whose values are separated with a semi-colon. The <MultiValue> tag is only supported for mapping attributes to associations. If specified for a mapping entry that is mapping relationships, it is silently ignored.

keepUnmappedAssociations Setting

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

If this setting is true, all the associations are included in output EIWM.

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

<Object>
...

<Associations keepUnmappedAssociations="false">

<Association>

<Conditions>

<Attribute name="DecomposedOf" pattern="^.*$"/>

</Conditions>

<Type value="mapped_association" />

<TargetID value="P1;P2;P3;P4" >

<MultiValue separator=";" />

</TargetID>

<TargetClassID value="EQUIPMENT" />

</Association>

</Associations>

...

</Object>

Notes:

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

• Associations containing association types, is referenced in and is identified by, are considered as mandatory.

• The following Object mapping can be used for Associations of a specific Type to be exported to the EIWM file for all objects.

  <Object>

  ...
  <TemplateID id ="default" />
  <ObjectID value="[GlobalId]"/>
  <ClassID value="[ClassName]"/>
  <Associations keepUnmappedAssociations="false">
  <Association relationship="FillsVoids" >
  <Type value="FillsVoids" />
  </Association>
  </Associations>

  ...
  </Object>

  The keepUnmappedAssociations value must be set to false; the Association relationship and Type values should be same to achieve this functionality.

• The following Object mapping can be used for Associations of a specific target to be exported to the EIWM file for all objects.

  <Object>
  ...

  <TemplateID id ="default" />

  <ObjectID value="[GlobalId]"/>

  <ClassID value="[ClassName]"/>

  <Associations keepUnmappedAssociations="false">

  <Association relationship="FillsVoids" >

  <Type value="FillsVoids" />

  <Conditions>

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

  <Attribute name="Name" pattern="M_Single-Flush:0915 x 2134mm:197506:1" />

  </Conditions>

  </Association>

  </Associations>

  ...

  </Object>

  The keepUnmappedAssociations value must be set to false; the Association relationship and Type values should be same and its conditions determine the target.

• Remove: An example of an Association mapping entry to remove an association from the source object is shown below:

  <Associations>

  <Association relationship="TestAssociation">

  <Remove />

  </Association>

  </Associations>

  An example of an Association mapping entry to remove all associations from the source object is shown below:

  <Associations>

  <Association relationship="*" >

  <Remove />

  </Association>

  </Associations>

  Optionally, to avoid including orphaned associated objects, remove the target object by using the keyword ‘includeTarget’. An example of an Association mapping entry that removes an association from the source object and associated object is shown below:

  <Associations>
  <Association relationship="TestAssociation">
  <Remove includeTarget="true"/>
  </Association>
  </Associations>

  This syntax can also be used when an object to be removed has a graphical representation which also needs to be removed. In this case the association type is “GraphicalObjectAssociation”:

  <Object>

  <Conditions>

  <Attribute name="ObjectID" pattern="A002" />

  </Conditions>

  <Remove />

  <Associations>

  <Association relationship="GraphicalObjectAssociation">

  <Remove includeTarget="true"/>

  </Association>

  </Associations>

  </Object>

Using the Parent Object's Attributes When Updating Associated Objects

When updating an associated object, for example, in setting the ObjectID of a dataset, it might be necessary to use one of the parent object's attribute values. This is done using transformer syntax like [parent:attributeName] to resolve attribute values from the parent object. This example assigns a parent attribute in the associated dataset object when assigning a targetID:

<Association relationship="IsDefinedBy">

<Conditions>

<Attribute name="ClassName" pattern="DATASET" />

</Conditions>

<Type value="has dataset" />

<TargetID value="[parent:ObjectID]@_[GlobalID] Dataset" />

<TargetClassID value="Dataset"/>

</Association>

The prefix "parent:" can be applied when resolving values of TargetID, TargetClassID, TargetName and ContextID elements that are sub elements to the Association object.

Attributes from associated objects can also be used, as shown below:

<Object>

<Conditions>

<Attribute name="DrawingItemType" pattern="Connector" />

</Conditions>

<IncludeAssociatedObjectAttributes type="[a-z]{3} [a-z]{7}" refID="IAOA1">

<Conditions>

<Attribute name="ItemProperty" pattern="PipingMaterialsClass" />

</Conditions>

</IncludeAssociatedObjectAttributes>

<IncludeAssociatedObjectAttributes type="has dataset" refID="IAOA2">

<Conditions>

<Attribute name="ItemProperty" pattern="[A-Z]{1}[a-z]{2}[A-Z]{1}[a-z]{7}[A-Z]{1}[a-z]{1}" />

</Conditions>

</IncludeAssociatedObjectAttributes>

<IncludeAssociatedObjectAttributes type="has dataset" refID="IAOA3">

<Conditions>

<Attribute name="ItemProperty" pattern="NominalDiameter" />

</Conditions>

</IncludeAssociatedObjectAttributes>

<ObjectID value="[IAOA1:ItemValue]-[IAOA2:ItemValue]-[IAOA3:ItemValue]">

</Object>

For example, the above configuration might result in an Object, with an attribute named "DrawingItemType" and value of "Connector", having an ObjectID = "A3B-6-150 mm", where:

• [IAOA1:ItemValue] = "A3B", from the value of the "ItemValue" attribute belonging to the associated Object whose association relationship is matching the pattern "[a-z]{3} [a-z]{7}" and its attribute "ItemProperty" has the value "PipingMaterialsClass".

• [IAOA2:ItemValue] = "6", from the value of the "ItemValue" attribute belonging to the associated Object whose association relationship is matching the pattern "has dataset" and its attribute "ItemProperty" has the value that is matching the regex "[A-Z]{1}[a-z]{2}[A-Z]{1}[a-z]{7}[A-Z]{1}[a-z]{1}".

• [IAOA3:ItemValue] = "150 mm", from the value of the "ItemValue" attribute belonging to the associated Object whose association relationship is matching the pattern "has dataset" and its attribute "ItemProperty" has the value "NominalDiameter".

The relationships between block references, nested block references and drawing items (primitive graphics) are represented in the output model by their associations of type "is a part of". To maintain these relationships, you must not remove these associations during mapping, for example, by defining mappings for other types of associations and then setting "keep unmapped associations" to false.

If you use unique identifiers when defining tags for structures with nested objects during mapping, you can highlight selected objects in Workhub and Dashboard on any level of the structure by selecting the objects in the Explorer's tree.

Create new associations via attributes containing the target identifier:

Relationships such as in hierarchies can be created via new associations between the related objects when a source object has an attribute containing the identifier of the target object. If the target object was already extracted or created by a previous transformation, then an association will be created between the source and target objects. If the target object doesn't exist, then a new object will be created and assigned an ObjectID corresponding to the source attribute value, and an association will be created between this new object and the source object.

Example base mapping configuration to create an association based on an attribute value:

<Object>
<Associations>
<Association>
<Type value="is a part of" />
<Conditions>
<Attribute name="IfcSpatialContainer GUID" />
</Conditions>
<TargetID value="[IfcSpatialContainer GUID]" />
</Association>
</Associations>
</Object>