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.

An Association mapping example 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.

Expand and Interpolate

The Expand feature lets you create multiple associated Tags or Objects in the EIWM output from an attribute value containing text delimited with a separator (such as comma or semicolon). Use any number of Expands to build the tags incrementally.

A separate association is created in the output for each expanded tag and the value is used as the ObjectID of the associated object.

Notes:

• The Expand mapping pattern must contain the expansion character to consider the attribute value for the expansion.

• If an Expand setting is defined along with a MultiValue setting, the MultiValue setting is applied first on the attribute value. Expand settings are then applied on individual values derived from the MultiValue setting to generate expanded/interpolated values.

Examples:

<Association attribute="Name" attributePattern="^[A-Z]{1}[a-z]{5}$" >

<Type value="is a part of" />

<TargetID value="P-101A/D" >

<Expand interpolate = "false">

<Pattern>[A-Z]/[A-Z]</Pattern>

<Char>/</Char>

</Expand>

</TargetID>

</Association>

In the above example, two tags named P-101A and P-101D are created as the interpolate setting is false.

<Association attribute="Name" attributePattern="^[A-Z]{1}[a-z]{5}$" >

<Type value="is a part of" />

<TargetID value="P-101A/D" >

<Expand interpolate = "true">

<Pattern>[A-Z]/[A-Z]</Pattern>

<Char>/</Char>

</Expand>

</TargetID>

</Association>

In the above example, four tags named P- 101A, P- 101B, P- 101C and P-101D are created as the interpolate setting is true.

<Association attribute="HotSide" >

<Type value="is a part of" />

<ContextID value="IPE" />

<TargetID value="07001-QE/QT-003;07001-FE-004A/B/C" >

<MultiValue separator=";" />

<Expand interpolate = "false">

<Pattern>[A-Z][A-Z]/[A-Z][A-Z]</Pattern>

<Char>/</Char>

</Expand>

<Expand interpolate = "false">

<Pattern>[A-Z]/[A-Z]/[A-Z]</Pattern>

<Char>/</Char>

</Expand>

</TargetID>

</Association>

In the above example, tags named "07001-QE-003", "07001-QT-003", "07001-FE-004A", "07001-FE-004B", "07001-FE-004C" are created.

<Association attribute="HotSide" >

<Type value="is a part of" />

<ContextID value="IPE" />

<TargetID value="07001-QE/GT-003;07001-FE-004A/B/C" >

<MultiValue separator=";" />

<Expand interpolate = "true">

<Pattern>[A-Z]/[A-Z]</Pattern>

<Char>/</Char>

</Expand>

<Expand interpolate = "false">

<Pattern>[A-Z]/[A-Z]</Pattern>

<Char>/</Char>

</Expand>

</TargetID>

</Association>

In the above example, the first Expand block creates the following tags "07001-QET-003","07001-QFT-003","07001-QGT-003","07001-FE-004A/B" and "07001-FE-004A/C".

The second Expand block further splits tags "07001-FE-004A/B" and "07001-FE-004A/C" into "07001-FE-004A", "07001-FE-004B" and "07001-FE-004C".

Finally, six tags named "07001-QET-003", "07001-QFT-003", "07001-QGT-003", "07001-FE-004A", "07001-FE-004B" and "07001-FE-004C" are created.

Association Mapping entries can be broadly classified into the following:

• Create: An example of an Association mapping entry that generates an association from an attribute in the source is shown below:

  <Associations>

  <Association>

  <Conditions>

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

  </Conditions>

  <Type value="is DTOtion of" />

  <TargetID value="ID123" />

  <TargetClassID value="EQUIPMENT" />

  <ContextID value="IPE" />

  </Association>

  </Associations>

  Note: Conditions may hold multiple attribute elements. All conditions must be met for the mapping to be applied.

A pattern property can be specified to match only attributes with a value that conforms to the regular expression.

• Update: An example of an Association mapping entry that modifies an existing association in the source is shown below:

  <Associations>
  <Association relationship="TestAssociation" >
  <Type value="mapped association" />
  <TargetID value="abcd1234" />
  <TargetClassID value="EQUIPMENT" />
  </Association>
  </Associations>

• 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.

When extracting data from input sources that have hierarchies between objects, for example between block references, nested block references and drawing items (primitive graphics) in diagrams, these are automatically represented as associations, for example of type "is a part of". To retain these relationships, be careful when defining mappings for other types of associations to not then set "keep unmapped associations" to false.

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".