General Structure of VEC Files & Documents

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.

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:

• General specifications, that are for example required for the provision of basic information or for information reuse (e.g. an InsulationSpecification), and
• PartOrUsageRelatedSpecifications that are specifically used to describe / specify the properties of one or many PartVersions.

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

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.

DocumentVersions as Building Blocks of the Information Exchange

A VEC (e.g. a file or the response of a REST interface) always represents a snapshot of information in a specific, fixed state. The VEC is a means of data exchange, not of data management (see Expected Behaviour of VEC Interfaces).

The cut of information into DocumentVersions is process specific. It reflects the responsibilities and approvals in the process: the content of a DocumentVersion is the scope of information that the process tracks and annotates with meta data. DocumentVersions are therefore the building blocks of an interface architecture — units of information exchanged between process partners, with a scope agreed within the process. There are typical scopes for typical processes (e.g. what a system schematic or a harness description contains), but significant deviations are valid as well.

In contrast to Specifications, DocumentVersions do not represent structural boundaries of the model. Even if two DocumentVersions are contained in the same VEC file, they are clearly separated from the perspective of versioning (see External References), but not from the perspective of the model. In particular, they are no boundary for references:

• Within one VEC file, references between elements in different DocumentVersions (e.g. from an occurrence in a harness description to a PartVersion and its part master data, or from a wire to a connection of a system schematic) are ordinary XML IDREFs.
• Across VEC files, an IDREF cannot span the file boundary. The relationship is established via the PDM identity of the referenced items (PartVersion and DocumentVersion numbers and versions), as assumed by the partitioning rules (rule 2). A VEC whose references can be resolved requires that the creating system includes the referenced information with the appropriate scope.

Combination and Reuse of Documents

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 XML / XSD Representation 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.

The same applies whenever content from several VEC files is combined into one VEC, e.g. to embed information for traceability or to bundle the harnesses of a vehicle network: the assignment of the information to its original DocumentVersions shall be preserved (see also Content from mixed Sources).

This rule applies to the aggregation of information, where the combined information itself remains unchanged. It does not apply to a semantic merge, where the combination creates new content. An example are partial system schematics: when partial systems are merged into an overall system, matching open links are resolved and the ComponentNodes of type OpenLink are removed (see System Schematic – Partial Systems). The result is new information, contained in a new DocumentVersion.

The combination of wiring harnesses into a vehicle network is normally not a semantic merge: a harness does not change or behave differently when it is put into a vehicle. Therefore, the harness descriptions of a vehicle network remain separate DocumentVersions, and information concerning the vehicle network as a whole is added in additional DocumentVersions (see Product Definition – Vehicle Network). Merging the harness descriptions into a single DocumentVersion is possible, but not recommended.

Content from mixed Sources

It is a common scenario that a VEC model contains information from different sources. In some cases it is pretty obvious that the information comes from different sources, e.g. part master data from a component database, a system schematic from an ECAD tool, and a geometry model from a 3D CAD system.

However, there are also use cases where the information from different sources is not so clearly distinguishable by its type. It is even possible, that the same type of information is obtained from different sources. Some examples for such scenarios are:

• Occurrences of components are defined in different places / process steps, e.g. in the electrologic, DMU or in the actual harness design.
• Additional information like placements and routing might come from different tools or process steps as well.

There are two apporoaches to handle such scenarios in the VEC, while keeping the traceability of the information to its source:

• Separate DocumentVersions per Source: In this approach, the information from each source is contained in a separate DocumentVersion. This is the preferred approach, as it clearly separates the information from different sources and preserves traceability in the change management. Each DocumentVersion can be clearly associated with its source, e.g. by using appropriate meta-data like document type, document number, version, etc.
• Single DocumentVersion with individual Specifications: This is approach is used, if all information must be combined into a single DocumentVersion. The information from different sources is kept separated by using individual Specifications for each source. However, this approach lacks the clear representation of source metadata on the DocumentVersion level (e.g. document number & version), which might impact traceability for example in the change management.

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.

Harness Description

A harness description describes a wiring harness as a physical product, regardless of its informational completeness. Its typical content and the scope of a harness description are described in Product Definition of a Harness.

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:

• Usage Node Lists (UsageNodeSpecification),
• Signal Catalogs (SignalSpecification), or
• Standardized Base Specifications (e.g. CavitySpecification, InsulationSpecification)

Extension of Master Data Definitions

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 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)