External References
Change History
Id | Subject | Date |
Latest Commit | Removed review tags and added whitepaper pdf version. | 2022-12-16 |
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).
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:
- 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.
- 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.
- 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 an external Document with VEC Model Elements
After defining an external reference as DocumentVersion there are multiple ways to create connections to VEC model elements. Some have 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.
- DocumentVersion.ReferencedPart → PartVersion: The document describes the part in some way (e.g. a component drawing). See “Parts and Documents”.
- DocumentVersion.RelatedDocument: The association is an informative link which DocumentVersion are related to each other (e.g. by derivation, A Harness-Drawing is related to a 3D-Model). See “Parts and Documents”.
- RequirementsConformanceStatement.DocumentVersion: Some PartVersions are satisfying (or not) the requirements defined in the external document. See “Conformance to Requirements”.
- ExternalMappingSpecification.MappedDocument: The external document is a different view on the same content described by this specific VEC and a mapping / active linking between the same elements in both views should be created. For example a harness and its drawing in SVG. See “External Mapping”.
- DocumentBasedInstruction.ReferencedDocument: An OccurrenceOrUsage has specific installation instructions that are defined in an external document (e.g. a manual or a working specification). See “Installation Instructions”.
- ExtendableElement.ReferencedExternalDocuments: The referenced document contains additional information about the VEC element, that cannot be represented in the VEC in an appropriate way. See “Parts and Documents”.
- DocumentRelatedAssignmentGroup.RelatedDocumentVersion: A DocumentRelatedAssignmentGroup allows the creation of traceability links to elements in a DocumentVersion for a set of VEC objects. The semantic of the traceability link is defined by the DocumentRelationType, for example requirements that apply to these VEC elements. See “Assignment Group”.