External References

Change History

Id Subject Date
Latest Commit Moved "XML-Representation" from Specification to Guidelines. Consolidated... 2024-05-17
KBLFRM-1046  Added Guideline for External References 2022-08-25

For reasons of traceability (e.g. requirements) or because certain information is better represented in other standards than in the VEC format (e.g. 3D models for components), it is necessary to be able to reference external documents from VEC elements. This guideline describes how these external documents can be addressed and what concepts exist to connect those documents with VEC model elements (and when to use which).

Referencing an external Document

As described in the Implementation Guideline “General Structure” the DocumentVersion serves several purposes, one of which is the referencing of external Documents. So, whenever a connection between a VEC element and an external document should be created, a DocumentVersion is required to address the document. Such a DocumentVersion should contain no payload data (Specification). However, it contains the same meta-data as it would, when included as a full featured document (e.g. DocumentType).

A index.vec file consists practically only of such external references, as described in the recommendation Chapter “VEC-Packgage” and in the corresponding Implementation Guideline.

There are different possibilities to resolve such a reference and retrieve the actual document:

  1. PDM reference with Domain Key: Per definition, a document version is unambiguously identified with its DocumentNumber, DocumentVersion and CompanyName. With context knowledge about the process, the document can be resolved in the corresponding PDM / Document Management System.
  2. FileName: If the document is packaged together with VEC file (VEC Package) the filename attribute of DocumentVersion can point to a location within the VEC Package. If the document is not part of the VEC Package, the FileName-Attribute shall be omitted.
  3. Location: If the document can be resolved outside the VEC package, the Location-Attribute can point to a location (via an URN or URL) where the document can be resolved. For files that are stored following a specific procedure or systematics (e.g. in PDM System) the usage of URNs should be the preferred way. This decouples the referencing from a concrete physical location, which might be different in different contexts or might be changed over the time.

Connecting VEC Model Elements

After defining an external reference as DocumentVersion there are multiple approaches to create connections to VEC model elements. Some approaches have a specific semantic, some are more generic. The different possibilities are summarized below. If there are more than one possibility for a specific element, you have to choose the one with most specific semantics.

External Mapping

External Mapping
External Mapping

The diagram above shows the usage of the external mapping mechanism. The elements highlighted in yellow represent the actual information described by this VEC instance. The elements highlighted in blue are defining the mapping itself and the DocumentVersion highlighted in green represents the link to the mapped document (in this case a SVG-symbol).

The ExternalMapping in this example defines that a representation of the referenced ConnectorHousingSpecification can be found in the SVG-symbol under the key ID_27101123. This is especially useful, if one wants address specific subelements (e.g. for highlighting). In the example, the Cavitys of the connector could also be mapped to specific symbols within the SVG.

The actual content data of the VEC-file (highlighted in yellow) and the mapping information is separated into two different DocumentVersion elements. This means even though both information are contained in the same VEC-file, from the perspective of a versioning mechanism they are clearly separated.

External Installation Instructions

External Installation Instructions
External Installation Instructions

The usage of file-based installation instructions is quite similar to the described approach for external documents. The FileBasedInstruction defines a pointer to the file packaged together with the VEC-file in the container and is referenced by the PartOccurrence.

The same effect could be achieved if a DocumentBasedInstruction is used, pointing to an external document (defined as described in the section before).

Important: The difference between the two approaches is that for the DocumentBasedInstruction a DocumentVersion is required. This means that the external file must be an official document with a document number, an appropriate versioning and so on. The FileBasedInstruction can point to any file needed (within a VEC package).

It is forbidden to use the FileBasedInstruction approach, if the external file is a valid document.