Harness (KBL/VEC Mapping)

Editorial Note: Since the creation of this implementation guideline will span an extended period, the current work-in-progress versions will be published continuously to allow the community to review and provide feedback.

This implementation guideline outlines the core concepts needed to create a dataset for a single wiring harness in the VEC, which is also the use case that lies in the center of the scope of the KBL.

To ease adoption for those already familiar with the KBL, this guideline is structured as a mapping from the KBL model to the VEC model: it explains the VEC concepts together with the KBL concepts they correspond to and shows where the information of a KBL file is found in a VEC. Additionally, a reference implementation of a KBL-to-VEC converter is available on GitHub.

There are fundamentally two approaches to describing such a mapping. One can either start from the source model, explaining how its information is distributed into the target model, or take the opposite approach by defining which information is needed in the target model and where to find it in the source model. For this implementation guideline, the latter approach was chosen as the strategy.

On the one hand, the guideline’s focus is on how to describe a harness in the VEC, which naturally suggests describing the mapping from this perspective. On the other hand, the VEC is the more precise model, meaning that many KBL concepts are distributed across different elements within the VEC. For example, a KBL Node contains information relevant to the VEC concepts of a TopologyNode , GeometryNode2D and GeometryNode3D. It is more logical to describe the mapping of topology and 2D/3D geometry as cohesive units rather than addressing all three concepts in a mixed manner starting from the KBL Node.

The implementation guideline focuses on the structural mapping and covers individual attributes only where they are essential for understanding a concept. If you are interested in those details, please refer to the reference implementation. The guideline describes the concepts and not the converter: where the reference implementation currently deviates from this guideline or does not yet cover a concept, this is pointed out briefly.

The guideline follows a logical order rather than an order dictated by model dependencies. Since the VEC is a graph—not a strict tree—it allows cross-references between branches. As a result, you may encounter cases where a model element references another model element whose mapping is described later in this guideline.

A converter can address this challenge with a two-phase approach, as the reference implementation does: first all VEC elements are created, then the references between them are resolved.

The order of the sections follows the content of a harness description in the VEC (see Product Definition of a Harness):

1. The Overview shows how the content of a KBL file is distributed across the VEC and introduces the principles that recur in all sections.
2. Parts and Documents explains how KBL parts become PartVersions and DocumentVersions.
3. Part Master Data describes the components used in the harness (connectors, terminals, wires, …).
4. Harness Description describes the harness itself: the instances of the components, the bill of material, the variants, the connectivity, and the topology with geometry, placement and routing.
5. Basic Data Types covers the value types used everywhere (units, numerical values, strings, custom properties).

Overview

Everything starts with the model root element VecContent, see the figure below (all attributes omitted).

A KBL file (KBL_container) describes exactly one harness together with the parts used in it. In the VEC, this information is distributed as follows (the figure is conceptual and not precise syntax):

• Every KBL Part (including the Harness and its Modules) is identified by a PartVersion.
• The properties of the components (connectors, terminals, wires, …) are described in one PartMaster document per component.
• Everything that is specific to the harness—the instances of the components, the bill of material, the variants, the connectivity, the topology, the geometry, the placements and the routings—is contained in a single HarnessDescription document.

The following table shows where the KBL content is found in the VEC and in which section of this guideline the mapping is described.

Mapping Principles

The following principles recur throughout the mapping:

Part and usage. Like the KBL, the VEC distinguishes between the definition of a component type (KBL Part, e.g. Connector_housing) and its use in the harness (KBL Connection_or_occurrence, e.g. Connector_occurrence). In the VEC, the definition is made with PartOrUsageRelatedSpecifications in the PartMaster document of the component, the use with PartOccurrences and Roles in the harness description (see the guideline Component Instances). Since the KBL already follows this distinction, most concepts can be mapped in a straightforward manner.

One KBL element, several VEC elements. The VEC is more modular than the KBL. A KBL element often contains information that belongs to different views in the VEC. For example, a KBL Node contains information about the topology (TopologyNode), the geometry (GeometryNode2D or GeometryNode3D) and the placement of components (OnPointPlacement). Each view is described in its own section of this guideline.

Identification. VEC elements are identified by their Identification attribute, which must be unique within its context (see Identifiers). Where the KBL provides an Id, it is used. Where the VEC requires an identification that has no counterpart in the KBL (e.g. for the specifications of a part), the reference implementation derives one, e.g. from the abbreviated class name and the part number (CHS-ECP001706 for the ConnectorHousingSpecification of the part ECP001706). Such derived identifications are a convention of the reference implementation and not a VEC rule.

Parts and Documents

In the KBL, a Part combines the identification of a component (part number, version, company) with its technical description. The VEC separates both: the PartVersion identifies the part, the technical description is contained in the Specifications of a DocumentVersion (see General Structure – Parts and Documents). Each KBL part therefore results in a PartVersion and, for a component, in a PartMaster document.

PartVersions

The concept of parts is quite different in KBL and VEC. In the VEC a PartVersion is just a PDM-Header for the part. The various aspects of a part (e.g. is it a wire or connector) are handled by different types of PartOrUsageRelatedSpecifications contained in the DocumentVersion describing the part. In the KBL, the different types of parts are expressed as subclasses of Part. The concept in the VEC that most closely reflects the approach of the KBL is the PrimaryPartType.

The following PrimaryPartType could be used for KBL Parts:

When mapping into the VEC, a PartVersion Object is required for each KBL Part. Those can be found under /KBL_container/(Accessory|AssemblyPart|CavityPlug|...), /KBL_container/Harness/Module and /KBL_container/Harness/Harness_configuration.

The PDM attributes of the Part are mapped directly to the PartVersion: Part_number, Company_name and Version become PartNumber, CompanyName and PartVersion, which together identify the part in the VEC. Abbreviation and Description (and Localized_description) become localized strings (see Strings and Localized Strings). Each Alias_identification becomes an AliasIdentification, where the KBL Description (“the type of the Alias_identification”) is mapped to the Type. The Part_number_type corresponds to the PartNumberType of the PartVersion.

<!-- KBL -->
    <Connector_housing id="id_315_0">
        <Part_number>ECP001706</Part_number>
        <Company_name>MaybeAnyCompany</Company_name>
        <Alias_id id="id_368_27">
            <Alias_id>TBL001038B</Alias_id>
            <Scope>VOBES</Scope>
            <Description>tab_number</Description>
        </Alias_id>
        <Version>1</Version>
        <Abbreviation>/NULL</Abbreviation>
        <Description>BUCHSENGEHAEUSE_6-POL</Description>
        ...
    </Connector_housing>
<!-- VEC -->
  <PartVersion id="PartVersion_id_315_0">
    ...
    <Description xsi:type="vec:LocalizedString" id="LocalizedString_00238">
      <LanguageCode>De</LanguageCode>
      <Value>BUCHSENGEHAEUSE_6-POL</Value>
    </Description>
    <CompanyName>MaybeAnyCompany</CompanyName>
    <PartNumber>ECP001706</PartNumber>
    <PartVersion>1</PartVersion>
    <PrimaryPartType>ConnectorHousing</PrimaryPartType>
    <AliasId id="AliasIdentification_id_368_27">
      <IdentificationValue>TBL001038B</IdentificationValue>
      <Type>tab_number</Type>
      <Scope>VOBES</Scope>
    </AliasId>
  </PartVersion>

DocumentVersions

In the VEC, all payload data is contained within DocumentVersions. Typically, you would structure those according to the actual documents used in the process. Unfortunately, this concept in its detail form is not present in the KBL. Therefore, for the generic conversion described here, practical assumptions need to be made:

1. It is common practice to describe components in individual datasets/documents and publish them separately → one DocumentVersion for each harness component (e.g. connector, wire and terminal, see Partitioning and Sizing), see section Part Master Data.
2. It is also common for a wiring harness to be fully described in a single 150% dataset, containing all information about the used component occurrences, variants, connectivity, dimensioning, and so on → one DocumentVersion for the harness itself, see section Harness Description.

This means that, for this mapping, a DocumentVersion with DocumentType=PartMaster must be created for each component used in the wiring harness. These are all instances of Part in the KBL except instances of Part_with_title_block.

For the Harness itself, a DocumentVersion with DocumentType=HarnessDescription is created. This document contains all relevant information about the harness as well as the Specifications for the Modules and Harness_configurations.

Identity of the Documents

Since the KBL has no explicit document concept, the identity of the documents must be derived. The natural choice is the identity of the described part: DocumentNumber, DocumentVersion and CompanyName of the document are taken from Part_number, Version and Company_name of the part, and the document references the part as ReferencedPart. If the identities of the actual documents in the process are known, they should be used instead.

  <DocumentVersion id="DocumentVersion_id_315_0">
    ...
    <CompanyName>MaybeAnyCompany</CompanyName>
    <DocumentNumber>ECP001706</DocumentNumber>
    <DocumentType>PartMaster</DocumentType>
    <DocumentVersion>1</DocumentVersion>
    <ReferencedPart>PartVersion_id_315_0</ReferencedPart>
    <RelatedDocument>DocumentVersion_External_reference_1</RelatedDocument>
    <Specification xsi:type="vec:ConnectorHousingSpecification" id="ConnectorHousingSpecification_id_315_0">
      <Identification>CHS-ECP001706</Identification>
      ...

The same applies to the HarnessDescription, whose identity is derived from the Harness. A harness description defines not only the harness, but also its modules and harness configurations. All PartVersions defined in the document should therefore be referenced as ReferencedPart (see Product Definition of a Harness). The reference implementation currently references only the PartVersion of the harness.

  <DocumentVersion id="DocumentVersion_id_328_0_1">
    ...
    <CompanyName>MaybeAnyCompany</CompanyName>
    <DocumentNumber>LTG0011200</DocumentNumber>
    <DocumentType>HarnessDescription</DocumentType>
    <DocumentVersion>2.4.0</DocumentVersion>
    <ReferencedPart>PartVersion_id_328_0</ReferencedPart>
    <RelatedDocument>DocumentVersion_External_reference_12 DocumentVersion_id_322_0 DocumentVersion_id_322_1</RelatedDocument>
    ...

Title Block and PDM Information

The KBL distributes the information of a drawing title block over several places: Creation, Approval and Change_description are defined directly in the KBL_container and reference the parts they apply to (Is_applied_to); a Part can have Changes and a Copyright_note; and the Part_with_title_block (i.e. the Harness, Module and Harness_configuration) adds project and car classification information. In the VEC, this is meta information of the DocumentVersion that contains the definition (see PDM Information), and in some cases of the PartVersion.

The target DocumentVersion of a Creation, Approval or Change_description is the document that describes the part referenced by Is_applied_to. The structures are not identical: in the VEC, persons are described by a Person, and some attributes are mandatory that have no KBL source (e.g. the Status of an Approval), so they have to be filled with a default value (see Default Values).

The title block information of the KBL Harness belongs to the HarnessDescription. The title block information of a Module or Harness_configuration does not have a document of its own in the VEC, since modules and configurations are defined within the HarnessDescription. Where it differs from the harness, it can only be preserved on the PartVersion (e.g. Project, CopyrightInformation).

External References

A KBL External_reference identifies a document that is not part of the KBL file (e.g. a 3D model or a drawing). Its counterpart in the VEC is a DocumentVersion that contains only PDM information and no specifications (see Usages of the DocumentVersion). Document_number, Change_level, Data_format, Creating_system and Location are mapped to the attributes of the same meaning. The KBL Document_type literals (part master, geometry model, harness description, …) have direct counterparts in the VEC DocumentType (PartMaster, GeometryModel, HarnessDescription, …). Values outside the KBL enumeration are kept as they are.

<!-- KBL -->
    <External_reference id="External_reference_1">
        <Document_type>EKR</Document_type>
        <Document_number>ECP001706</Document_number>
        <Change_level>011112</Change_level>
        <File_name>ECP001706.CATPart</File_name>
        <Data_format>catPart</Data_format>
        <Creating_system>CATIA V5R19 SP9</Creating_system>
    </External_reference>
<!-- VEC -->
  <DocumentVersion id="DocumentVersion_External_reference_1">
    <CompanyName>ACME Inc.</CompanyName>
    <DocumentNumber>ECP001706</DocumentNumber>
    <DocumentType>EKR</DocumentType>
    <DocumentVersion>011112</DocumentVersion>
    <CreatingSystem>CATIA V5R19 SP9</CreatingSystem>
    <DataFormat>catPart</DataFormat>
    <FileName>ECP001706.CATPart</FileName>
  </DocumentVersion>

Two details need attention:

• The CompanyName is mandatory in the VEC, but the KBL External_reference has no company. If the company is not known from the context, /NULL should be used (see Default Values). The value ACME Inc. in the example is a placeholder of the reference implementation.
• The FileName of a VEC DocumentVersion is reserved for documents that are part of the VEC package; otherwise it shall be omitted (see External References). The KBL File_name refers to a file outside of the KBL, so it should only be kept if the document is packaged together with the VEC file. The document can still be resolved via its domain key or via the Location, if given in the KBL.

The KBL External_references of a Part are the documents associated with the part (e.g. its 3D model). In the VEC, this relation can be expressed with different associations; the one with the most specific semantics should be chosen (see External References). For documents describing the part, this is ReferencedPart of the referenced DocumentVersion. The reference implementation uses the more general RelatedDocument of the PartMaster document (see the example above).

Part Master Data

For all components used in a wiring harness, a minimum set of part master data is required. A PartMaster document contains all PartOrUsageRelatedSpecifications that are required to describe the component. For a general description of this concept see the Guideline “Component Description”. The following specifications have to be created. The mapping of those is described in the following sections:

The following table defines the PartOrUsageRelatedSpecification that are used to define each Part. Auxiliary specifications that might required by the PartOrUsageRelatedSpecification for a complete definition (e.g. WireReceptionSpecification, CavitySpecification or InsulationSpecification) are listed in the corresponding section.

General Technical Information

Connector Housings

Terminals

Cavity Seals and Cavity Plugs

Wires

Wire Protections, Fixings and Accessories

Component Boxes, Fuses and other E/E Components

Assembly Parts

Harness Description

A HarnessDescription document contains all Specifications that are required to describe a Harness. The specifications in the VEC provide a more “view oriented” modelling approach than the KBL. Each specification representing a specific view on the product model, with the possibility to have links between the views. The following sections will describe the mapping topic by topic (or, in other words view by view).

A VEC derived from a single KBL contains one HarnessDescription document for the Harness defined in the KBL.

Instances of Components

Bill of Material / Part Structure

One central view on the product is the bill of material (BoM) or part structure. The information which parts (components) are used for the harness, its variants and modules.

The KBL has a very explicit definition of the part structure with predefined levels and semantics, compare the diagram below (Note: The diagram is, for the sake of simplicity, conceptually, and not precisely KBL syntax):

• Harness: The container for all variants and part occurrences that compose a harness description (150% definition).
• Module: A subset of part occurrences the is used for variant management within the harness (< 100%).
• Harness_configuration: A set of Modules used to define specific variants of a harness (= 100%)
• Module_configuration: A subset of part occurrences without part number (< 100%).
• Assembly_part: A predefined part consisting of multiple parts, that is used within a harness (e.g. a USB-Cable).
• Connection_or_occurrence: An occurrence (usage) of a part/component within the harness with capability to define usage specific information (e.g. wire length).

In contrast, the VEC provides a highly generic and flexible concept for representing Bills of Material (BoMs). While a strictly defined and semantically precise model, like the one in KBL, has clear advantages — such as unambiguous interpretation and validation — it must also be capable of reflecting real-world complexity. The rigid semantics of the KBL work well within its original scope, but become increasingly insufficient when moving beyond it.

In broader application scenarios, additional concepts are often required, such as production modules, lead sets, or vehicle configurations e.g. for cost and variant calculations. Furthermore, the interpretation of certain concepts may vary depending on the stakeholder’s perspective. For example, an OEM might define a structure as an assembly, whereas a Tier1-supplier may regard the same structure as a module. This highlights the need for more adaptable and context-aware modeling approaches, as supported by the VEC. The basic concepts are illustrated in the following diagram:

The CompositionSpecification serves as a container for defining PartOccurrences. At this stage, it is not yet associated with any specific part and does not represent a configuration of parts. Such an independent container is necessary, particularly when describing variant-rich (150%) products, where individual occurrences of parts cannot always be uniquely assigned to a single configuration unit and may be reused in multiple contexts (150% definition).

Using the PartStructureSpecification, subsets of the previously defined PartOccurrences can now be selected and defined as the Bill of Material (BoM) for a specific PartVersion. These PartVersions can, in turn, be instantiated as PartOccurrences to define another level of the BoM.

This recursive structure allows for the representation of hierarchical BoMs of arbitrary depth, as well as parallel BoM structures—for example, engineering BoM (EBOM) and manufacturing BoM (MBOM).

The assignment to semantics commonly used in harness development (such as harness, module, etc.) is done via the content attribute of the PartStructureSpecification with literals defined in PartStructureContentType. This classification then implies semantic constraints — for example, with respect to completeness (e.g. 100%, 150%) and the types of elements that are allowed.

A typical example: a variant usually consists of modules, which means that only PartOccurrences representing modules may be referenced in a variant’s BoM.

As shown in the diagram above, the Bill of Materials (BoM) structure in KBL essentially consists of three levels:

1. Harness / Harness_configuration: This represents the top level of the hierarchical BoM. The interpretation of the Harness element varies depending on whether the context is a staged wiring harness (Stufenleitungssatz) or a customer-specific harness (KSK):

   • In the case of a KSK, the Harness represents a 150% BoM of all orderable modules. Existing Harness_configuration elements are orthogonal to this and typically represent predefined variants, e.g., for calculation purposes.
   • For staged harnesses, the Harness element merely serves as a container for defining the various variants, which are modeled as Harness_configuration elements.

2. Modules: Break down the complete set of all occurrences (150%) into smaller subsets suitable for variant management.

3. Connection_or_occurrence: All instances of the harness components (e.g. connectors, wires)

The basic mapping of those concepts into the generic approach of the VEC is illustrated in the diagram below.

Each layer consists of a part master definition (PartVersion), that is used to create instances (PartOccurrence) within a container for the layer (CompositionSpecification). Each layer defines its own container (see Composite Parts – Layers and Control Information). The PartOccurrence of one layer are then used to define the part master definition of the next layer (PartStructureSpecification and PartVersion).

Mapping KBL Classification to PartStructureContentType

The following table defines the Mapping between KBL classifications and PartStructureContentTypes.

XML Representation

The following XML listings explain the BoM mapping in detail. They start from the lowest level (the components) and the end at the top (the harness).

The first step is to create the basic occurrences for the harness. For every Connection_or_occurrence in the KBL Harness a PartOccurrence is created. An exception is the KBL Connection, which is not representing an occurrence of a component, and therefore no PartOccurrence is created in the VEC. The Roles are omitted in the snippet below, as this a separate topic, handled in Instances of Components. The Identification used for the CompositionSpecification is COMPONENTS. The identifications COMPONENTS and MODULES are a recommendation for this mapping and not a general VEC convention.

    <Specification xsi:type="vec:CompositionSpecification" id="CompositionSpecification_00289">
      <Identification>COMPONENTS</Identification>
      <Component id="PartOccurrence_00290">
        <Identification>GenericIdentifier-0</Identification>
        <Part>PartVersion_00375</Part>
        ...
      </Component>
      <Component id="PartOccurrence_00291">
        <Identification>GenericIdentifier-1</Identification>
        <Part>PartVersion_00375</Part>
        ...
      </Component>
      ...
    </Specification>

For each module, a PartStructureSpecification is created, referencing the occurrences that belong to the module, defined above.

    <Specification xsi:type="vec:PartStructureSpecification" id="PartStructureSpecification_00368">
      <Identification>PSS-MDL123456</Identification>
      <DescribedPart>PartVersion_00504</DescribedPart>
      <Content>Module</Content>
      <InBillOfMaterial>PartOccurrence_00291 PartOccurrence_00290 ...</InBillOfMaterial>
    </Specification>

To define the next layer, instances of the modules are required. Those are created within a separate CompositionSpecification with the Identification = 'MODULES' (a recommendation for this mapping, see above). The module PartOccurrence references the module’s PartStructureSpecification, whose InBillOfMaterial are the component PartOccurrences defined above. No component occurrences are cloned for the module occurrence. This is, because modules are normally defined in-place (see Instantiation Approaches). As the composition of the module is already defined by its PartStructureSpecification, the PartWithSubComponentsRole of the module occurrence should not reference the component occurrences as SubComponent (see Composite Parts).

    <Specification xsi:type="vec:CompositionSpecification" id="CompositionSpecification_00286">
      <Identification>MODULES</Identification>
      <Component id="PartOccurrence_00287">
        <Identification>MDL123456</Identification>
        <Role xsi:type="vec:PartWithSubComponentsRole" id="PartWithSubComponentsRole_00288">
          <Identification>MDL123456</Identification>
          <PartStructureSpecification>PartStructureSpecification_00368</PartStructureSpecification>
        </Role>
        <Part>PartVersion_00504</Part>
      </Component>
    </Specification>

As a Module is now a regular PartOccurrence the generic concepts in the VEC for PartOccurrences can now be applied (e.g. Variant Management, see below) and no module specific modelling concepts, like the KBL Logistic_control_information are required.

Based on the module PartOccurrences, now a PartStructureSpecification for the harness can be defined.

    <Specification xsi:type="vec:PartStructureSpecification" id="PartStructureSpecification_00367">
      <Identification>PSS-LTG0011200</Identification>
      <DescribedPart>PartVersion_00500</DescribedPart>
      <Content>Harness</Content>
      <InBillOfMaterial>PartOccurrence_00287 ...</InBillOfMaterial>
    </Specification>

Variant Management (Logistic Control Information)

The KBL uses the Module_configuration element and its Logistic_control_information attribute to define variant management information. In contrast, the VEC offers a more flexible approach, allowing variant management data to be associated with almost any element that is a subclass of ConfigurableElement. Additionally, the VEC introduces an indirection layer, enabling elements to be supplemented with variant management information either retrospectively or externally. It is also possible to assign different control information to an element depending on the context.

As a result, the single Logistic_control_information attribute in the KBL is mapped to a more comprehensive set of classes and attributes in the VEC, providing greater flexibility and specificity in variant management. Specifically, two specifications are required for this purpose, with one instance of each per harness description (DocumentVersion with DocumentType=HarnessDescription):

1. The VariantConfigurationSpecification defines the set of configuration terms used. For each distinct Logistic_control_information string, a corresponding VariantConfiguration should be created.
2. The ConfigurationConstraintSpecification assigns these terms to specific elements. For each Module with a Logistic_control_information, a ConfigurationConstraint should be created to link the corresponding PartOccurrence to the appropriate VariantConfiguration.

The following XML snippet illustrates the required specifications and their relationships.

    <Specification xsi:type="vec:VariantConfigurationSpecification" id="VariantConfigurationSpecification_00403">
      <Identification>VCS-LTG0011200</Identification>
      <VariantConfiguration id="VariantConfiguration_00404">
        <Identification>VarConf_MDL123456</Identification>
        <LogisticControlExpression>L0L+ALL</LogisticControlExpression>
        <ConfigurationType>Logistic</ConfigurationType>
      </VariantConfiguration>
    </Specification>
    <Specification xsi:type="vec:ConfigurationConstraintSpecification" id="ConfigurationConstraintSpecification_00405">
      <Identification>CCS-LTG0011200</Identification>
      <ConfigurationConstraint id="ConfigurationConstraint_00406">
        <Identification>ConfConstraint_MDL123456</Identification>
        <ConfigInfo>VariantConfiguration_00404</ConfigInfo>
        <ConstrainedElements>PartOccurrence_00408</ConstrainedElements>
      </ConfigurationConstraint>
    </Specification>
    <Specification xsi:type="vec:CompositionSpecification" id="CompositionSpecification_00407">
      <Identification>MODULES</Identification>
      <Component id="PartOccurrence_00408">
        <Identification>MDL123456</Identification>
        <Role xsi:type="vec:PartWithSubComponentsRole" id="PartWithSubComponentsRole_00409">
          <Identification>MDL123456</Identification>
          <PartStructureSpecification>PartStructureSpecification_00589</PartStructureSpecification>
          <SubComponent>...</SubComponent>
        </Role>
        <Part>PartVersion_00725</Part>
      </Component>
    </Specification>

Connectivity

Topology

Geometry

Placement

Routing

Basic Data Types

Numerical Values

Strings and Localized Strings

Custom Properties and Instructions

Units

To define numerical values, both the VEC and the KBL require units. If the attributes Si_unit_name, Si_prefix, and Si_dimension have been used to define a KBL Unit, it can be mapped straight forward to a SIUnit in the VEC.