diff --git a/docs/concept/#322-Provisioning-of-contractAgreementId-for-assets/#322-Provisioning-of-contractAgreementId-for-assets.md b/docs/concept/#322-Provisioning-of-contractAgreementId-for-assets/#322-Provisioning-of-contractAgreementId-for-assets.md index eac6040e5b..4599ed4478 100644 --- a/docs/concept/#322-Provisioning-of-contractAgreementId-for-assets/#322-Provisioning-of-contractAgreementId-for-assets.md +++ b/docs/concept/#322-Provisioning-of-contractAgreementId-for-assets/#322-Provisioning-of-contractAgreementId-for-assets.md @@ -1,13 +1,13 @@ # Concept #322 Provisioning of contract agreement id for assets -| Key | Value | -|---------------|----------------| -| Creation date | 11.01.2024 | -| Issue Id | https://github.com/eclipse-tractusx/item-relationship-service/issues/322 https://github.com/eclipse-tractusx/item-relationship-service/issues/370 | -| State | DRAFT | - +| Key | Value | +|---------------|-----------------------------------------------------------------------------------------------------------------------------------------------------| +| Creation date | 11.01.2024 | +| Issue Id | https://github.com/eclipse-tractusx/item-relationship-service/issues/322 https://github.com/eclipse-tractusx/item-relationship-service/issues/370 | +| State | DRAFT | # Table of Contents + 1. [Overview](#overview) 2. [Summary](#summary) 3. [Problem Statement](#problem-statement) @@ -19,64 +19,78 @@ 9. [Glossary](#glossary) 10. [References](#references) +# Overview -# Overview -The exchange of assets via the EDC takes place after a successful contract negotiation in which it is checked whether the consumer has authorized access to the data asset. -This access is automatically checked by the EDC via so-called AccessPolicies. The consumer is only granted access to the data after a successful check. -During contract negotiation the edc stores audits to the artefacts edc:ContractAgreement and edc:ContractNegotiation. These audit information can be requested over the edc management API. +The exchange of assets via the EDC takes place after a successful contract negotiation in which it is checked whether +the consumer has authorized access to the data asset. +This access is automatically checked by the EDC via so-called AccessPolicies. The consumer is only granted access to the +data after a successful check. +During contract negotiation the edc stores audits to the artefacts edc:ContractAgreement and edc:ContractNegotiation. +These audit information can be requested over the edc management API. To request the mentioned artefacts over the management API the ContractAgreementDto:@id is required. -This specific id must therefore be stored and linked for the exchanged asset in order to be able to determine the corresponding contract agreement later on. +This specific id must therefore be stored and linked for the exchanged asset in order to be able to determine the +corresponding contract agreement later on. +# Summary -# Summary This feature is responsible for collecting the CIDs of EDC contract negotiations regarding during in the IRS processing. -The CIDs are provided in the IRS JobResponse document for collected assets. -For shells and submodels CIDs are collected and provided. -In case of a usage policy mismatch. The irs policy store does not provide the usage policy of the asset. This circumstance is reported in a tombstone which contains the policy of the asset. +The CIDs are provided in the IRS JobResponse document for collected assets. +For shells and submodels CIDs are collected and provided. +In case of a usage policy mismatch. The irs policy store does not provide the usage policy of the asset. This +circumstance is reported in a tombstone which contains the policy of the asset. + +# Problem Statement -# Problem Statement -1. The ContractAgreementDto:@id is currently not delivered via the IRS response, so business apps that use the IRS cannot access the corresponding ContractAggreement under which the assets, delivered by the IRS, were exchanged. -2. Teh EDC management API provides a endpoint ro query contract agreement by assetId. It is not possible to determine which ContractAggreement belongs to which negotiation in case of multiple negotiations for the same asset +1. The ContractAgreementDto:@id is currently not delivered via the IRS response, so business apps that use the IRS + cannot access the corresponding ContractAggreement under which the assets, delivered by the IRS, were exchanged. +2. Teh EDC management API provides a endpoint ro query contract agreement by assetId. It is not possible to determine + which ContractAggreement belongs to which negotiation in case of multiple negotiations for the same asset 3. Business apps must make the contract agreements under which the assets were exchanged available for audit purposes. -# Requirements +# Requirements 1. [ ] Provisioning of ContractAgreementDto:@id via IRS JobReponse for AAS retrieved via EDC. 2. [ ] Provisioning of ContractAgreementDto:@id via IRS JobReponse for submodels retrieved via EDC. 3. [ ] API parameter SHOULD control whether ContractAgreementDto:@id should be returned via the IRSJobResponse -# NFR +# NFR -# Out of scope +# Out of scope -# Assumptions > -- [x] Business app (Trace-X) has access to the management API of the IRS EDC Consumer. -- [x] EDC Management API of EDC Consumer is configured as a parameter in Business app (Trace-X). IRS does not provide API url to EDC Management API via JobResponse. -- [x] In case there negotiation is not executed because of policy mismatch, the catalog offer policy of will be collected inside IRS flow and provided to irs requestor. +# Assumptions -# Concept +- [x] Business app (Trace-X) has access to the management API of the IRS EDC Consumer. +- [x] EDC Management API of EDC Consumer is configured as a parameter in Business app (Trace-X). IRS does not provide + API url to EDC Management API via JobResponse. +- [x] In case there negotiation is not executed because of policy mismatch, the catalog offer policy of will be + collected inside IRS flow and provided to irs requestor. +# Concept -## API Extensions +## API Extensions -## APIs -- POST /irs/jobs +## APIs + +- POST /irs/jobs - POST /irs/orders - POST /irs/ess/orders - POST /ess/bpn/investigation -- parameter name: auditContractNegotiation -- parameter value: boolean value -- parameter default: true -- parameter description: enables and disables auditing including provisioning of ContractAgreementId inside submodels and shells objects -- parameter impacts: enables collection of ContractAgreementId in job processing and provides this information in SubmodelContainers and ShellContainers or policy from CatalogOffer in Tombstone in case of policy mismatch +- parameter name: auditContractNegotiation +- parameter value: boolean value +- parameter default: true +- parameter description: enables and disables auditing including provisioning of ContractAgreementId inside submodels + and shells objects +- parameter impacts: enables collection of ContractAgreementId in job processing and provides this information in + SubmodelContainers and ShellContainers or policy from CatalogOffer in Tombstone in case of policy mismatch -## 1. Case 1: Successful contract negotiation +## 1. Case 1: Successful contract negotiation IRS proceed EDC contract negotiation succeeds. IRS transfers assets and collects contractAgreementId for asset -### Receiving EndpointDataReference / EDR token for Catalog Entry +### Receiving EndpointDataReference / EDR token for Catalog Entry + ````mermaid sequenceDiagram @@ -107,11 +121,9 @@ sequenceDiagram note right of ContractNegotiationService : UsagePolicyException MUST cover the policy of catalog item this is relevant to create tombstone afterwards with policy SubmodelDelegate --> ItemContainer: create tombstone with policy payload end - - ```` -### Receiving Submodel Payload +### Receiving Submodel Payload ````mermaid @@ -129,6 +141,7 @@ sequenceDiagram EdcSubmodelFacade -->> SubmodelDelegate: submodel payload SubmodelDelegate -->> IRS: write contractAgreementId to JobReponse submodels[] ```` + ### Receiving AAS Payload ````mermaid @@ -148,7 +161,6 @@ sequenceDiagram ```` - ````mermaid sequenceDiagram @@ -176,28 +188,25 @@ sequenceDiagram SubmodelDelegate --> IRS : write contractAgreementÍd to submodel inside JobReponse ```` - -## 2. Case 2: IRS proceed EDC contract negotiation fails because of internal EDC error +## 2. Case 2: IRS proceed EDC contract negotiation fails because of internal EDC error ### Case 2.1: GET contract negotiation return 404 and "type": "ObjectNotFound", ```` 404 - [ - { - "message": "Object of type ContractNegotiation with ID=f9600523-f8e4-42b3-b388-485370b4f8f4 was not found", - "type": "ObjectNotFound", - "path": null, - "invalidValue": null - } +[ + { + "message": "Object of type ContractNegotiation with ID=f9600523-f8e4-42b3-b388-485370b4f8f4 was not found", + "type": "ObjectNotFound", + "path": null, + "invalidValue": null + } ] ```` -## 3. Case 3: IRS revokes asset transfers cause by not matching usage policy - - -Usage policy is checked before contract negotiation. in case policy mismatch, no negotiation will be started. +## 3. Case 3: IRS revokes asset transfers cause by not matching usage policy +Usage policy is checked before contract negotiation. in case policy mismatch, no negotiation will be started. ````mermaid @@ -223,9 +232,11 @@ end ```` +## EDC Management API -## EDC Management API -The EDC Management API is provided by EDC consumer. In this case the IRS configured EDC provider logs the required contract aggreements and provides the API to request contract agreements and contract negotations for given contract agreement @id +The EDC Management API is provided by EDC consumer. In this case the IRS configured EDC provider logs the required +contract aggreements and provides the API to request contract agreements and contract negotations for given contract +agreement @id Source: https://app.swaggerhub.com/apis/eclipse-tractusx-bot/tractusx-edc/0.5.3#/Contract%20Agreement/getNegotiationByAgreementId @@ -236,150 +247,159 @@ GET /v2/contractagreements/{id}/negotiation Gets a contract negotiation with the given contract agreement ID ``` -## Mapping of contract ContractAgreementId in theJobResponse - +## Mapping of contract ContractAgreementId in theJobResponse + +### Add ContractAgreementId to shells (AAS) -### Add ContractAgreementId to shells (AAS) The structure of the shells is extended in the same way as the submodels[] structure. -The meta information, which is currently the "contractAgreementId", is written to the shells object. The actual payload of the shell is written to the payload object. +The meta information, which is currently the "contractAgreementId", is written to the shells object. The actual payload +of the shell is written to the payload object. This follows a uniform structure, as can also be found in the submodel object. ```json "shells": [ - { - "contractAgreementId": "", - "payload": { - { - "administration": null, - ... - "globalAssetId": "urn:uuid:a1fa0f85-697d-4c9d-982f-2501af8e8636", - "idShort": "VehicleCombustionA", - "id": "urn:uuid:56ee00a5-ca0f-4366-a00d-193e08e74995", - "specificAssetIds": [ - {} - ], - "submodelDescriptors": [ - {} - ] - } - } - }, - { - "contractAgreementId": "", - "payload": { - { - // aas shell payload - } - } + { + "contractAgreementId": "", + "payload": { + { + "administration": null, + ... + "globalAssetId": "urn:uuid:a1fa0f85-697d-4c9d-982f-2501af8e8636", + "idShort": "VehicleCombustionA", + "id": "urn:uuid:56ee00a5-ca0f-4366-a00d-193e08e74995", + "specificAssetIds": [ + {} + ], + "submodelDescriptors": [ + {} + ] + } + } + }, + { + "contractAgreementId": "", + "payload": { + // aas shell payload + } + } +] ``` -### Add ContractAgreementId to relationships +### Add ContractAgreementId to relationships + In the first version, the ContractAgreementId is not mapped in the "relationship". If this information is required, the requester can register traversal aspect "SingleLevel*" in api parameter "aspects[]" in request POST /irs/jobs. This collects the submodel which include the required ContractAgreementId. - ````json "aspects": [ -"SingleLevelBomAsBuilt" + "SingleLevelBomAsBuilt" ] ```` -### Add ContractAgreementId to submodels +### Add ContractAgreementId to submodels -#### Option 1: Provide contractAgreementId for each submodel: -Impact: -- Redundant information in case multiple submodels were received for the same contractAgreementId. -- JobReponse size is already critical and extends by ~100byte multiples with every submodel and aas shell stored in the JobReponse +#### Option 1: Provide contractAgreementId for each submodel: + +Impact: + +- Redundant information in case multiple submodels were received for the same contractAgreementId. +- JobReponse size is already critical and extends by ~100byte multiples with every submodel and aas shell stored in the + JobReponse ```json - "submodels": [ - - { - "identification": "urn:uuid:f9b6f066-c4de-4bed-b531-2a1cad7bd173", - "aspectType": "urn:bamm:io.catenax.single_level_bom_as_built:1.0.0#SingleLevelBomAsBuilt", - "contractAgreementId": "", - "payload": { - <... submodel payload ...> - } - ] +"submodels": [ + { + "identification": "urn:uuid:f9b6f066-c4de-4bed-b531-2a1cad7bd173", + "aspectType": "urn:bamm:io.catenax.single_level_bom_as_built:1.0.0#SingleLevelBomAsBuilt", + "contractAgreementId": "", + "payload": { + <... submodel payload ...> + } + } +] ``` -#### Option 2: Provide submodel for contractAgreementId +#### Option 2: Provide submodel for contractAgreementId + Impact: + 1. High invasive changes to the code, api, JobResponse and documentation. -2. This variant complicates the optional (activatable/deactivatable) collection of ContractAggreementIds as these are an essential part of the response structure. +2. This variant complicates the optional (activatable/deactivatable) collection of ContractAggreementIds as these are an + essential part of the response structure. ```json - "contractAggreements" : [ - "contractAggreement" : { - "contractAgreementId": "", - "submodels": [ - { - "identification": ">", - "aspectType": "", - "payload": { - <... submodel payload ...> - } - ] - } - - ] +"contractAggreements": [ + "contractAggreement": { + "contractAgreementId": "", + "submodels": [ + { + "identification": ">", + "aspectType": "", + "payload": { + <... submodel payload ...> + } + } + ] + } +] ``` -### Add Tombstone in case of not matching policy +### Add Tombstone in case of not matching policy Tombstone is extended with policy payload when policy is not matched and contract negotiation is not conducted. -The requestor gets the insight which policy does not match and has the opportunity to add the specific policy to the IRS policy store in order to receice further on assets with the specific policy. +The requestor gets the insight which policy does not match and has the opportunity to add the specific policy to the IRS +policy store in order to receice further on assets with the specific policy. -- [ ] Tombstone is extended with policy payload in case policy is invalid AND auditContractNegotiation api parameter is enabled. +- [ ] Tombstone is extended with policy payload in case policy is invalid AND auditContractNegotiation api parameter is + enabled. `````json "tombstones": [ - { - "catenaXId": "urn:uuid:6ce41c0b-c84a-46b0-b4c4-78fce958663d", - "endpointURL": null, - "policy": { - "odrl:hasPolicy": { - "@id": "ZDgzZjhjY2EtMGY2MC00OWMzLWJjNDYtMWE0OTY2MDdlMzhj:cmVnaXN0cnktYXNzZXQ=:Y2IxNzI5MjUtYzUyNS00NmJiLWFiZWQtMDVhMTdkNTFiZTg0", - "@type": "odrl:Set", - "odrl:permission": { - "odrl:target": "registry-asset", - "odrl:action": { - "odrl:type": "USE" - }, - "odrl:constraint": { - "odrl:or": { - "odrl:leftOperand": "PURPOSE", - "odrl:operator": { - "@id": "odrl:eq" - }, - "odrl:rightOperand": "ID 3.0 Trace" - } - } - } - }, - "processingError": { - "processStep": "DigitalTwinRequest", - "errorDetail": "EndpointDataReference was not found. Requested connectorEndpoints: https://test1.doubleSlash.com, https://test2.doubleSlash.com", - "lastAttempt": "2024-01-17T09:02:36.648055745Z", - "retryCounter": 3 + { + "catenaXId": "urn:uuid:6ce41c0b-c84a-46b0-b4c4-78fce958663d", + "endpointURL": null, + "policy": { + "odrl:hasPolicy": { + "@id": "ZDgzZjhjY2EtMGY2MC00OWMzLWJjNDYtMWE0OTY2MDdlMzhj:cmVnaXN0cnktYXNzZXQ=:Y2IxNzI5MjUtYzUyNS00NmJiLWFiZWQtMDVhMTdkNTFiZTg0", + "@type": "odrl:Set", + "odrl:permission": { + "odrl:target": "registry-asset", + "odrl:action": { + "odrl:type": "USE" + } + }, + "odrl:constraint": { + "odrl:or": { + "odrl:leftOperand": "PURPOSE", + "odrl:operator": { + "@id": "odrl:eq" + }, + "odrl:rightOperand": "ID 3.0 Trace" + } } + } + }, + "processingError": { + "processStep": "DigitalTwinRequest", + "errorDetail": "EndpointDataReference was not found. Requested connectorEndpoints: https://test1.doubleSlash.com, https://test2.doubleSlash.com", + "lastAttempt": "2024-01-17T09:02:36.648055745Z", + "retryCounter": 3 } + } ], - ````` -# Glossary +# Glossary -| Abbreviation | Name | Description | -|------------------------|-------------------------|---------------------------------------------| -| edc:ContractAgreement |edc:ContractAgreement | ContractAgreement of negotation in EDC | -| edc:ContractNegotation |edc:ContractNegotation | ContractNegotation of negotation in EDC | -| AAS |AssetAdministrationShell | The Shell object dtored in dDTR registry | -| CID | contractAgreementId | Unique Id of an contract aggrement | +| Abbreviation | Name | Description | +|------------------------|--------------------------|-------------------------------------------| +| edc:ContractAgreement | edc:ContractAgreement | ContractAgreement of negotation in EDC | +| edc:ContractNegotation | edc:ContractNegotation | ContractNegotation of negotation in EDC | +| AAS | AssetAdministrationShell | The Shell object dtored in dDTR registry | +| CID | contractAgreementId | Unique Id of an contract aggrement | -# References +# References https://app.swaggerhub.com/apis/eclipse-tractusx-bot/tractusx-edc/0.5.3#/Contract%20Agreement/getAgreementById https://github.com/eclipse-tractusx/tractusx-edc/blob/main/docs/kit/Development%20View/01_MGMT_API_Walkthrough/02_policies.md diff --git a/docs/concept/TEMPLATE_Concept.md b/docs/concept/TEMPLATE_Concept.md index f15c940530..a9e628559f 100644 --- a/docs/concept/TEMPLATE_Concept.md +++ b/docs/concept/TEMPLATE_Concept.md @@ -1,44 +1,45 @@ -# \[Concept\] \[#ID#\] Summary +# \[Concept\] \[#ID#\] Summary | Key | Value | |---------------|-------------------| | Creation date | | | Ticket Id | | -| State | | +| State | | + +## Table of Contents -# Table of Contents 1. [Overview](#overview) 2. [Summary](#summary) -3. [Problem Statement](#statement) +3. [Problem Statement](#problem-statement) 4. [Requirements](#requirements) 5. [NFR](#nfr) -6. [Out of scope](#outofscope) +6. [Out of scope](#out-of-scope) 7. [Assumptions](#assumptions) 8. [Concept](#concept) 9. [Glossary](#glossary) 10. [References](#references) +## Overview -# Overview - +## Summary -# Summary +## Problem Statement -# Problem Statement +## Requirements -# Requirements +## NFR -# NFR +## Out of scope -# Out of scope +## Assumptions -# Concept +## Concept -# Glossary +## Glossary -| Abbreviation | Name | -|-------------|-----------------------------| -| | | -| | | +| Abbreviation | Name | +|--------------|------| +| | | +| | | -# References \ No newline at end of file +## References \ No newline at end of file