General Structure of VEC Files & Documents

Disclaimer: This page or section is currently under review by the community.

The content of this page or section can be subject to change at any time. If you find any issues or if you have any review comments please drop us an issue on the PROSTEP JIRA.

This page or section resolves KBLFRM-996

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, the DocumentVersion plays a double role in the VEC. It can serve as a PDM anchor / reference to a document with no further content (in KBL this was the External_reference). More important, however, 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 are to 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

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

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

Combination & Reuse of Documents

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 peace of information must be indentifiable 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 with the. A DocumentVersion can be contained in multiple VEC (files).

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.

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

Part Master Documents

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. Those specifications are not mandatory and only necessary if the corresponding information aspect is relevant and can be provided. Examples are:

Besides these general specifications a part master document contains a PartOrUsageRelatedSpecification corresonding to the PrimaryPartType (a ConnectorHousingSpecification in the illustration). That Specification provides the component type specific properties. If the component has a secondary component characteristics, more than one PartOrUsageRelatedSpecification can be contained.

Additionally, the document could contain auxillary specifications that are required for the complete component description (the CavitySpecification and SlotSpecification in the illustration). The emphasis here is on “could”, as this is a common case, but a process-specific interpretation. If for example the cavity system is described and released together with the connector (in the same document), it makes sense that the corresponding specification is included in the same DocumentVersion. If the cavity system is defined and released independently, i.e. in a separate document, and used by multiple connectors, it would be appropriate to place it in its own DocumentVersion and reuse the information in the document of the connector (see Reuse of Documents).

Master Data Definition

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

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

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

Previous