General Structure of VEC Files & Documents

Change History

Id Subject Date
Latest Commit KBLFRM-984, KBLFRM-945, KBLFRM-931, KBLFRM-994, KBLFRM-1038: Resolved multiple requests in the area of Component Description & Instances and made refactoring to the whole structure. 2022-10-21
KBLFRM-996  Integrated Review Comments for the whole page 2020-11-27
KBLFRM-996  Created Guideline for General Structure of VEC Files 2020-06-22

The VEC has two major key concepts: PartVersion and DocumentVersion. Both are ItemVersions and both are used to reference / identify a piece of relevant information in a PDM context unambigiously.

Whereas the PartVersion “just” represents a PDM anchor / reference for a part or component plus some Meta-Information, the DocumentVersion has different characters in the VEC (for more details see section Usages of the DocumentVersion):

  1. It can serve as a plain PDM anchor / reference to a document, with no further content / information in the VEC, like the PartVersion for parts (VEC equivalent to the KBL External_reference).
  2. However, more important is that the DocumentVersion is the container for any payload information contained in the VEC.

From a meta data perspective, the VEC does not differentiate between documents that are contained in the VEC itself or in some external place somewhere else. This guideline is intended to provide guidance on how these concepts should be used and how an appropriate distribution of documents can look alike.

Fundamentals

On the root level, a VEC contains mainly PartVersions and DocumentVersions and some other unversioned (and constant) information, e.g. the definition of the Units used within the VEC. This is illustrated in figure Basic Structure.

Basic Structure
Basic Structure

One of the core concepts of the VEC is, that there is no restriction for the type of information that can be contained in a DocumentVersion nor the valid combinations of different types of information that can be contained together. This enables the DocumentVersion to reflect the actual circumstances of the domain or process and thus represents an actual technical document with a corresponding release and versioning.

Reasonable combinations of information are driven by the use cases (with process specific variations). The description of some common use case is part of this guideline.

A document can contain any number of Specifications. The Specifications represent the information modules of the VEC and each defines a certain type or aspect of information. The Specifications in a document can be thought of like drawers, where each drawer contains a specific aspect of the vehicle network. A distinction can be made here between:

The distribution of information into different documents is mainly driven by the requirements of the process. Nevertheless, certain best practices and minimal content can be defined for certain types of documents.

Parts and Documents

One of the most fundamental concepts of the VEC is the separation of a part / component from its definition (specification). In this, the PartOrUsageRelatedSpecification plays a major role.

In the VEC a part (PartVersion) does not contain any information about the part, except its PDM Information (PartNumber, PartVersion, …). All the information about the technical properties of a part is expressed by a subclass of PartOrUsageRelatedSpecifications (e.g. a WireSpecification). The PartOrUsageRelatedSpecification is contained in a DocumentVersion. As mentioned above, the distribution of these specifications into different documents is driven by the process / domain (see object diagram Parts and Documents).

Parts and Documents
Parts and Documents

This approach enables the VEC to address for example the following scenarios properly:

  • The description of a part is changed, but the part itself is not changed (rereleased). This can happen for example if the actual technical properties of the part stay the same, but the description is extended or corrected. In this case, a new version of the document is created. However, the PartVersion stays the same.
  • A document and the contained specifications are describing more than one part (e.g. a drawing for a certain class/family of terminals, seals & plugs). In this case it can happen that the document and the specifications are changed, but not all of the described parts have to be changed (rereleased). E

Usages of the DocumentVersion

As mentioned in the introduction, the DocumentVersions VEC can be used in different ways:

  • Plain PDM reference (a.k.a as external reference): In this case, the DocumentVersion in the VEC only contains meta-data and no payload-data (no Specifications). This is described in detail here.
  • Digital Representation of an external Document: There are use cases where existing documents can represented in the means of the VEC. In other words the VEC DocumentVersion is a digital representation of the original document. For example, the information of a component data sheet (as PDF) might be also represented in VEC in a digitally evaluable way (PartOrUsageRelatedSpecification). In this case the same mechanisms like for the plain PDM reference can be used, plus payload-data in DocumentVersion.
  • Native VEC Documents: The VEC DocumentVersion itself is the source of information. This case is quite similar to the digital representation scenario. However, external links (if defined) will resolve to the VEC file itself.

However, regardless of the use of the DocumentVersion, it always represents the meta-data of the entity in the process, which does not change depending on its VEC representation. Meaning, if for example a system schematic is referenced as external document in one place (VEC file) and is used as a native document / digital representation in another place, it is still a system schematic (DocumentType) with the same DocumentNumber & Version.

Combination and Reuse of Documents

DocumentVersions in the Information Flow
DocumentVersions in the Information Flow

Typically, information is flowing through the process. It is created somewhere, passed on to someone else and is used there to create other information blocks. To make these information flows traceable each piece of information must be identifiable and must have a change indicator. In the VEC this is done by the DocumentVersion. In order to preserve this traceability along the process, the assignment of information pieces to its original DocumentVersion shall remain unchanged.

An illustrative example for this, is the distribution and use of component master data (compare figure on the right). As described in “Partitioning and Sizing of VEC Files” component master data is best provided with one VEC per component, containing at least one DocumentVersion with the component’s specifications (VEC A, B, C).

If a wiring harness is created with these components, the component master data (at least a portion of it) is required in the data set of the harness (VEC NEW). However, the information is not integrated into the DocumentVersion of the harness (DocumentVersion NEW), as this would lead to a loss of traceability, even if the structures of the VEC would allow such an approach. Instead, copies of the DocumentVersions containing the component’s part master data are placed beside the DocumentVersion of the harness, within the same VEC.

A DocumentVersion in the VEC and the physical VEC file shall not be equated. A DocumentVersion is a logical entity and can be contained in multiple VEC (files). Conversely, a VEC file can contain multiple DocumentVersions.

Even though the logical content (the represented object graph) of a self contained DocumentVersion might be copied from one VEC file to another without problem, the actual XML snippet might require adaption. At least the XML ID-attributes must be checked for uniqueness and, in case of a conflict, changed. Referencing IDREF(S) also have to be changed accordingly.

Types of Documents

The DocumentType is an OpenEnumeration that defines some document types that are common in the harness development process. The following sections describe typical content that can be expected in the DocumentVersions of a specific type, if the content is represented in the VEC.

However, as the DocumentVersion is primary an entity from the domain of the creating process, the content and the given Specifications may vary.

Part Master

A part master document describes the properties of a component or a group of components (a PartVersion or a set of PartVersion). It contains some general purpose specifications that provide information for any component type. A detailed description can be found in the “Component Description” Guideline.

Master Data Definition

In contrast to PartMaster documents MasterDataDefintions are not related to a specific component or a set of components (equivalent to part, part number, etc.). MasterDataDefintions are predefined standard information pieces in the process declared by some central organizational unit.

It is a common approach to manage certain information centrally and distribute it in the development processes. The definition of this information is usually independent of specific development projects and ensures the adherence to certain conventions and guidelines across (all) development projects. The component master data is a very specific aspect of this information as it always refers to a component (with a part number). In addition, there is a wide range of other information that is not directly related to a specific component but is nevertheless managed centrally.

Such DocumentVersions with central definition, that are not related to specific PartVersion are summarized under the DocumentType MasterDataDefinition. Examples for such centrally distributed informations are:

Extension of Master Data Definitions

Master Data Extension
Master Data Extension

A VEC that requires master data definitions of a specific type (e.g. signals, usage nodes) can obtain these from different sources (e.g. seperate signal catalogues for power & information). A special use case of this is the addition / extension of a master data definition with individual information in a specific development artifact.

Example: New signals might be required in the system schematic of a new series that are not (yet) included in the master data definition. These additions could be contained in a local signal catalog of system schematic, while the central master data catalog is used for the other signals. When the development process has progressed, these local definitions might be included in the master data definition.

The VEC specification makes no assumptions about consistency relationships between such multiple sources for the same type of information. This is due to the fact that such restrictions are usually the result of process specific definitions (see the following examples).

The following bulletins illustrate some examples of different, process specific consistency relationships. The examples are from the context of the above mentioned “signal catalogues”.

  • Different Sources for separate domains (e.g. power signals vs. information signals): In this case, there should be no overlaps between the defined entities.
  • Local / project specific definitions vs. global definitions: In this case it depends on the degree of freedom allow for project specific definition. Or, viewed from the other direction, on the binding nature of the global definitions. This determines whether only new information may be added or whether existing elements may be overwritten with other information.

In any case, the order of precedence has to be defined for the different sources. However, this is mainly an issue for the business logic of an authoring use case (which elements can be defined or selected by the user in a certain context). In the data exchange use of the VEC, the elements from the different sources are explicitly referenced. So at any time it is unambiguously defined which elements have been used / selected, even though the rules why an element took precedence over another are not contained in the VEC (compare figure Master Data Extension)