Merge pull request #678 from catenax-ng/feature/#296-support-has-alte…

…rnatives

feat(impl):[#296] has alternatives support

CHANGELOG.md

@@ -5,12 +5,14 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
+### Added
+- Added support for `hasAlternatives` property in SingleLevelBomAsBuilt aspect
+
 ### Changed
 - Updated edc dependencies to 0.2.1
 - Update deprecated field `providerUrl` to `counterPartyAddress` in EDC catalog request
 - Update ESS EDC notification creation asset endpoint to v3
 
-
 ## [4.2.0] - 2023-11-28
 ### Changed
 - Changed default behaviour of IRS - when aspects list is not provided or empty in request body, IRS will not collect any submodel now (previously default aspects were collected).

docs/src/api/irs-api.yaml

@@ -1068,6 +1068,7 @@ components:
             linkedItem:
               assembledOn: 2022-02-03T14:48:54.709Z
               childCatenaXId: urn:uuid:a45a2246-f6e1-42da-b47d-5c3b58ed62e9
+              hasAlternatives: false
               lastModifiedOn: 2022-02-03T14:48:54.709Z
               lifecycleContext: asBuilt
               quantity:
@@ -1187,6 +1188,7 @@ components:
             linkedItem:
               assembledOn: 2022-02-03T14:48:54.709Z
               childCatenaXId: urn:uuid:a45a2246-f6e1-42da-b47d-5c3b58ed62e9
+              hasAlternatives: false
               lastModifiedOn: 2022-02-03T14:48:54.709Z
               lifecycleContext: asBuilt
               quantity:
@@ -1375,6 +1377,7 @@ components:
             linkedItem:
               assembledOn: 2022-02-03T14:48:54.709Z
               childCatenaXId: urn:uuid:a45a2246-f6e1-42da-b47d-5c3b58ed62e9
+              hasAlternatives: false
               lastModifiedOn: 2022-02-03T14:48:54.709Z
               lifecycleContext: asBuilt
               quantity:
@@ -2105,20 +2108,24 @@ components:
           maxLength: 45
           minLength: 45
           pattern: "^urn:uuid:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
+        hasAlternatives:
+          type: boolean
+          description: Expresses whether the part is built-in or whether it is one
+            of several options.
         lastModifiedOn:
           type: string
-          example: 2022-02-03T14:48:54.709Z
           format: date-time
           description: Last datetime item was modified.
+          example: 2022-02-03T14:48:54.709Z
         lifecycleContext:
           type: string
-          example: asBuilt
           description: The lifecycle context in which the child part was assembled
             into the parent part.
           enum:
             - asBuilt
             - asPlanned
             - asSpecified
+          example: asBuilt
         quantity:
           $ref: '#/components/schemas/Quantity'
     MeasurementUnit:

docs/src/docs/arc42/scope-context/technical-context.adoc

@@ -31,52 +31,49 @@ The integrated EDC client in the IRS is responsible for creating restful request
 ==== Traversal Aspect
 
 |===
-|Name | Description |
-|SingelLevelBomAsBuilt|The aspect provides the child parts (one structural level down) which the given object assembles.| 1.1.0
-|SingelLevelUsageAsBuilt | The aspect provides the information in which parent part(s)/product(s) the given item is assembled in. Could be a 1:1 relationship in terms of a e.g. a brake component or 1:n for e.g. coatings. The given item as well as the parent item must refer to an object from as-built lifecycle phase, i.e. a batch or a serialized part. | [X.X.X]|
+| Name | Description |
+| SingleLevelBomAsBuilt | The single-level bill of material represents one sub-level of an assembly and does not include any lower-level subassemblies. The as-built lifecycle references all child items as manufactured by the manufacturer referencing only child items in an as-built lifecycle themselves, unless parts can only be tracked by an part ID. If it's unclear which item has been built-in into the parent item, all potential parts must be listed. This is the case when, e.g. the same item is supplied by two suppliers and the item is only tracked by a customer part ID during assembly, these items can not be differentiated from each other. | 2.0.0
+| SingleLevelUsageAsBuilt | The aspect provides the information in which parent part(s)/product(s) the given item is assembled in. Could be a 1:1 relationship in terms of a e.g. a brake component or 1:n for e.g. coatings. The given item as well as the parent item must refer to an object from as-built lifecycle phase, i.e. a batch or a serialized part. | 2.0.0
 |===
 
 ==== Semantic Model
 
 |===
-|Name | Description | Version range
-|SerialPart | A serialized part is an instantiation of a (design-) part, where the particular instantiation can be uniquely identified by means of a serial numbers or a similar identifier (e.g. VAN) or a combination of multiple identifiers (e.g. combination of manufacturer, date and number) | [1.0,0, 1.1.0]
-|SingelLevelBomAsBuilt|The aspect provides the child parts (one structural level down) which the given object assembles.| [1.0.0,1.1.0]
-|SingelLevelUsageAsBuilt| The aspect provides the information in which parent part(s)/product(s) the given item is assembled in. Could be a 1:1 relationship in terms of a e.g. a brake component or 1:n for e.g. coatings. The given item as well as the parent item must refer to an object from as-built lifecycle phase, i.e. a batch or a serialized part. | [1.0.0,1.0.1]
-|Batch|A batch is a quantity of (semi-) finished products or (raw) material product that have been produced under the same circumstances (e.g. same production location), as specified groups or amounts, within a certain time frame. Every batch can differ in the number or amount of products. Different batches can have varied specifications, e.g., different colors. A batch is identified via a Batch ID.| [1.0.0,2.0.0]
-|JustInSequencePart| A just-in-sequence part is an instantiation of a (design-) part, where the particular instantiation can be uniquely identified by means of a combination of several IDs related to a just-in-sequence process | [1.0.0]
-|TractionBatteryCode| The traction battery code is an identification code for any automotive traction battery, ultracapacitor and other reachargeble energy storage device. It allows to carry information as required by the National Standard of the People's Republic of China according to GB/T 34014-2017 published by the Standardization Administration of China (SAC).| 1.0.0
+| Name | Description | Version range
+| SerialPart | A serialized part is an instantiation of a (design-) part, where the particular instantiation can be uniquely identified by means of a serial numbers or a similar identifier (e.g. VAN) or a combination of multiple identifiers (e.g. combination of manufacturer, date and number) | [1.0,0, 1.1.0]
+| Batch | A batch is a quantity of (semi-) finished products or (raw) material product that have been produced under the same circumstances (e.g. same production location), as specified groups or amounts, within a certain time frame. Every batch can differ in the number or amount of products. Different batches can have varied specifications, e.g., different colors. A batch is identified via a Batch ID.| [1.0.0, 2.0.0]
+| JustInSequencePart | A just-in-sequence part is an instantiation of a (design-) part, where the particular instantiation can be uniquely identified by means of a combination of several IDs related to a just-in-sequence process | 1.0.0
+| TractionBatteryCode | The traction battery code is an identification code for any automotive traction battery, ultracapacitor and other reachargeble energy storage device. It allows to carry information as required by the National Standard of the People's Republic of China according to GB/T 34014-2017 published by the Standardization Administration of China (SAC).| 1.0.0
 |===
 
 === Overview asPlanned
 
 ==== Traversal Aspect
 
 |===
-|Name | Description |
-|SingelLevelBomAsPlanned | The single-level Bill of Material represents one sub-level of an assembly and does not include any lower-level subassemblies. In as planned lifecycle state all variants are covered (\"120% BoM\"). If multiple versions of child parts exist that can be assembled into the same parent part, all versions of the child part are included in the BoM. If there are multiple suppliers for the same child part, each supplier has an entry for their child part in the BoM.| 1.1.0
-|SingelLevelUsageAsPlanned | The aspect provides the information in which parent part(s)/product(s) the given item is assembled in. This could be a 1:1 relationship in terms of a e.g. a brake component or 1:n for e.g. coatings. The given item as well as the parent item must refer to an object from as planned lifecycle phase. If multiple versions of parent parts exist that the child part can be assembled into, all versions of the parent part are included in the usage list. | 1.1.0
+| Name | Description |
+| SingleLevelBomAsPlanned | The single-level Bill of Material represents one sub-level of an assembly and does not include any lower-level subassemblies. In as planned lifecycle state all variants are covered (\"120% BoM\"). If multiple versions of child parts exist that can be assembled into the same parent part, all versions of the child part are included in the BoM. If there are multiple suppliers for the same child part, each supplier has an entry for their child part in the BoM.| 2.0.0
+| SingleLevelUsageAsPlanned | The aspect provides the information in which parent part(s)/product(s) the given item is assembled in. This could be a 1:1 relationship in terms of a e.g. a brake component or 1:n for e.g. coatings. The given item as well as the parent item must refer to an object from as planned lifecycle phase. If multiple versions of parent parts exist that the child part can be assembled into, all versions of the parent part are included in the usage list. | Not supported
 |===
 
 ==== Semantic Model
 |===
-|Name | Description |
-|PartAsPlanned | A Part as Planned represents an item in the Catena-X Bill of Material (BOM) in As-Planned lifecycle status in a specific version.| [ , ]
-|PartSiteInformationAsPlanned|The aspect provides site related information for a given as planned item (i.e. a part type or part instance that is uniquely identifiable within Catena-X via its Catena-X ID). A site is a delimited geographical area where a legal entity does business. In the \"as planned\" lifecycle context all potentially related sites are listed including all sites where e.g. production of this part (type) is planned.| 1.0.0
-|SingelLevelUsageAsPlanned | The aspect provides the information in which parent part(s)/product(s) the given item is assembled in. This could be a 1:1 relationship in terms of a e.g. a brake component or 1:n for e.g. coatings. The given item as well as the parent item must refer to an object from as planned lifecycle phase. If multiple versions of parent parts exist that the child part can be assembled into, all versions of the parent part are included in the usage list.| [1.0.0,1.1.0]
+| Name | Description |
+| PartAsPlanned | A Part as Planned represents an item in the Catena-X Bill of Material (BOM) in As-Planned lifecycle status in a specific version. | [1.0,0, 1.0.1]
+| PartSiteInformationAsPlanned |The aspect provides site related information for a given as planned item (i.e. a part type or part instance that is uniquely identifiable within Catena-X via its Catena-X ID). A site is a delimited geographical area where a legal entity does business. In the \"as planned\" lifecycle context all potentially related sites are listed including all sites where e.g. production of this part (type) is planned. | 1.0.0
 |===
 
 === Overview asSpecified
 
 ==== Traversal Aspect
 |===
-|Name | Description |
-|SingelLevelBomAsSpecified| The SingleLevelBomAsSpecified defines the view of the OEM or producer of the whole product, e.g. the OEM of a vehicle. It is free of any supplier-related information and specifies the promised and guaranteed content of the whole product to the end customer. This “top-down” view is in contrast to the “bottom-up” view of the SingleLevelBoMAsPlanned, though several sub-aspects are shared. The BomAsSpecified is merely one aspect, which is attached to the twin of the whole product and itself does neither introduce further twins nor reference them. Instead it merely comprises all functional information required by dismantlers, workshops or requestors for used parts to search for and to make a match on the market place. | 2.0.0
+| Name | Description |
+| SingleLevelBomAsSpecified | The SingleLevelBomAsSpecified defines the view of the OEM or producer of the whole product, e.g. the OEM of a vehicle. It is free of any supplier-related information and specifies the promised and guaranteed content of the whole product to the end customer. This “top-down” view is in contrast to the “bottom-up” view of the SingleLevelBoMAsPlanned, though several sub-aspects are shared. The BomAsSpecified is merely one aspect, which is attached to the twin of the whole product and itself does neither introduce further twins nor reference them. Instead it merely comprises all functional information required by dismantlers, workshops or requestors for used parts to search for and to make a match on the market place. | 1.0.0
 |===
 
 ==== Semantic Model
 |===
-|Name | Description |
-|SingelLevelBomAsSpecified| The SingleLevelBomAsSpecified defines the view of the OEM or producer of the whole product, e.g. the OEM of a vehicle. It is free of any supplier-related information and specifies the promised and guaranteed content of the whole product to the end customer. This “top-down” view is in contrast to the “bottom-up” view of the SingleLevelBoMAsPlanned, though several sub-aspects are shared. The BomAsSpecified is merely one aspect, which is attached to the twin of the whole product and itself does neither introduce further twins nor reference them. Instead it merely comprises all functional information required by dismantlers, workshops or requestors for used parts to search for and to make a match on the market place. | [1.0.0,2.0.0]
+| Name | Description |
+| PartAsSpecified | The aspect model PartAsSpecified belongs to the Part Catalogue. A PartAsSpecified represents a certain OEM catalog part on part number level. Providing a digital representation of the part as specified by the OEM. The link to the serialized part is done via the partId, this can only be done if the respective DT was provided by the supplier within the value chain. | [1.0.0, 1.0.1, 2.0.0]
 
 |===

irs-edc-client/src/main/java/org/eclipse/tractusx/irs/edc/client/SingleLevelBomAsBuilt.java

@@ -73,11 +73,13 @@ public List<Relationship> asRelationships() {
         private ZonedDateTime lastModifiedOn;
         private String catenaXId;
         private String businessPartner;
+        private boolean hasAlternatives;
 
         public Relationship toRelationship(final String catenaXId) {
             final LinkedItem.LinkedItemBuilder linkedItem = LinkedItem.builder()
                                                                       .childCatenaXId(GlobalAssetIdentification.of(this.catenaXId))
                                                                       .lifecycleContext(BomLifecycle.AS_BUILT)
+                                                                      .hasAlternatives(this.hasAlternatives)
                                                                       .assembledOn(this.createdOn)
                                                                       .lastModifiedOn(this.lastModifiedOn);
 

irs-edc-client/src/main/java/org/eclipse/tractusx/irs/edc/client/SingleLevelBomAsPlanned.java

@@ -78,6 +78,7 @@ public Relationship toRelationship(final String catenaXId) {
             final LinkedItem.LinkedItemBuilder linkedItem = LinkedItem.builder()
                                                                       .childCatenaXId(GlobalAssetIdentification.of(this.catenaXId))
                                                                       .lifecycleContext(BomLifecycle.AS_PLANNED)
+                                                                      .hasAlternatives(Boolean.FALSE)
                                                                       .assembledOn(this.createdOn)
                                                                       .lastModifiedOn(this.lastModifiedOn);
 

irs-edc-client/src/main/java/org/eclipse/tractusx/irs/edc/client/SingleLevelBomAsSpecified.java

@@ -79,6 +79,7 @@ public Relationship toRelationship(final String catenaXId) {
             final LinkedItem.LinkedItemBuilder linkedItem = LinkedItem.builder()
                                                                       .childCatenaXId(GlobalAssetIdentification.of(this.childCatenaXId))
                                                                       .lifecycleContext(BomLifecycle.AS_SPECIFIED)
+                                                                      .hasAlternatives(Boolean.FALSE)
                                                                       .assembledOn(childPart.getCreatedOn())
                                                                       .lastModifiedOn(childPart.getLastModifiedOn());
 

irs-edc-client/src/main/java/org/eclipse/tractusx/irs/edc/client/SingleLevelUsageAsBuilt.java

@@ -96,6 +96,7 @@ public Relationship toRelationship(final String catenaXId, final String business
             final LinkedItem.LinkedItemBuilder linkedItem = LinkedItem.builder()
                                                                       .childCatenaXId(GlobalAssetIdentification.of(catenaXId))
                                                                       .lifecycleContext(BomLifecycle.AS_BUILT)
+                                                                      .hasAlternatives(Boolean.FALSE)
                                                                       .assembledOn(this.createdOn)
                                                                       .lastModifiedOn(this.lastModifiedOn);
 

irs-models/src/main/java/org/eclipse/tractusx/irs/component/LinkedItem.java

@@ -61,4 +61,7 @@ public class LinkedItem {
     @JsonUnwrapped
     private GlobalAssetIdentification childCatenaXId;
 
+    @Schema(description = "Expresses whether the part is built-in or whether it is one of several options.", implementation = Boolean.class)
+    private boolean hasAlternatives;
+
 }

irs-models/src/main/java/org/eclipse/tractusx/irs/data/CxTestDataContainer.java

@@ -58,7 +58,7 @@ public static class CxTestData {
         public static final String SINGLE_LEVEL_BOM_AS_BUILT_ASPECT_TYPE = "urn:bamm:io.catenax.single_level_bom_as_built:2.0.0#SingleLevelBomAsBuilt";
         public static final String SINGLE_LEVEL_USAGE_BUILT_ASPECT_TYPE = "urn:bamm:io.catenax.single_level_usage_as_built:2.0.0#SingleLevelUsageAsBuilt";
         public static final String SINGLE_LEVEL_BOM_AS_SPECIFIED_ASPECT_TYPE = "urn:bamm:io.catenax.single_level_bom_as_specified:1.0.0#SingleLevelBomAsSpecified";
-        public static final String PART_AS_PLANNED_ASPECT_TYPE = "urn:bamm:io.catenax.part_as_planned:1.0.0#PartAsPlanned";
+        public static final String PART_AS_PLANNED_ASPECT_TYPE = "urn:bamm:io.catenax.part_as_planned:1.0.1#PartAsPlanned";
         public static final String SINGLE_LEVEL_BOM_AS_PLANNED_ASPECT_TYPE = "urn:bamm:io.catenax.single_level_bom_as_planned:2.0.0#SingleLevelBomAsPlanned";
         public static final String BATCH_ASPECT_TYPE = "urn:bamm:io.catenax.batch:2.0.0#Batch";
         public static final String MATERIAL_FOR_RECYCLING_ASPECT_TYPE = "urn:bamm:io.catenax.material_for_recycling:1.1.0#MaterialForRecycling";

irs-models/src/main/resources/test_data/CX_Testdata.json

@@ -331371,7 +331371,18 @@
         "businessPartner" : "BPNL00000003B0Q0",
         "createdOn" : "2022-02-03T14:48:54.709Z",
         "lastModifiedOn" : "2022-02-03T14:48:54.709Z"
-      } ]
+      },
+{
+        "catenaXId" : "urn:uuid:72ec2897-4e20-475c-a28b-019cf5b42a18",
+        "quantity" : {
+          "quantityNumber" : 2.5,
+          "measurementUnit" : "unit:litre"
+        },
+        "hasAlternatives" : true,
+        "businessPartner" : "BPNL00000003CNKC",
+        "createdOn" : "2022-02-03T14:48:54.709Z",
+        "lastModifiedOn" : "2022-02-03T14:48:54.709Z"
+      }	  ]
     } ],
     "urn:bamm:io.catenax.battery.product_description:1.0.1#ProductDescription" : [ {
       "minimalStateOfHealth" : {