From d23b92573ada7fbebb0bf08a54dbd0a0b091c74b Mon Sep 17 00:00:00 2001 From: mk Date: Wed, 17 Jan 2024 11:23:47 +0100 Subject: [PATCH] chore(concept):[#322] add sequence diagram for receiving EDR token --- ...ioning-of-contract-definiton-for-assets.md | 256 +++++++++++++++--- 1 file changed, 224 insertions(+), 32 deletions(-) diff --git a/docs/concept/#322-Provisioning-of-contract-definiton-for-assets/#322-Provisioning-of-contract-definiton-for-assets.md b/docs/concept/#322-Provisioning-of-contract-definiton-for-assets/#322-Provisioning-of-contract-definiton-for-assets.md index 122103937f..b62f269619 100644 --- a/docs/concept/#322-Provisioning-of-contract-definiton-for-assets/#322-Provisioning-of-contract-definiton-for-assets.md +++ b/docs/concept/#322-Provisioning-of-contract-definiton-for-assets/#322-Provisioning-of-contract-definiton-for-assets.md @@ -11,6 +11,10 @@ - [ ] Should the EDC Management API of the IRS be configured in the business application or should the url be supplied via the JobResponse? - [ ] Does the business app have access to the management API of the EDC configured for the IRS - [ ] Is a distinction is currently necessary for AAS accesses that are not traded via the EDC as we have not currently implemented the case in the IRS +- [ ] Collect policy inside the IRS flow +- [ ] If contract negoation is not valid / not positive how we provide the contractAggreementId to the busines app? Exstend Tombstone extended. +- [ ] tombstone creation + # Table of Contents 1. [Overview](#overview) @@ -31,6 +35,7 @@ During contract negotation the edc stores audits the following artefacts edc:Con 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. + # Summary # Problem Statement @@ -50,22 +55,184 @@ This specific id must therefore be stored and linked for the exchanged asset in # Concept -## EDC Management API +## 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 +````mermaid + +sequenceDiagram + %%{init: {'theme': 'dark', 'themeVariables': { 'fontSize': '15px', 'fontFamily': 'Architects daughter'}}}%% + autonumber + SubmodelDelegate ->> EdcSubmodelFacade : getEndpointReferenceForAsset + EdcSubmodelFacade ->> EdcSubmodelClientImpl: getEndpointReferenceForAsset + note left of EdcSubmodelClientImpl: Get EDR token to call endpoint reference + EdcSubmodelClientImpl ->> EDCCatalogFacade: fetchCatalogByFilter key/value + EDCCatalogFacade ->> EdcControlPlaneClient: getCatalogWithFilter key/value + EdcControlPlaneClient ->> EDC Consumer ControlPlane : GET catalog with filter
[POST /management/v2/catalog/request] + EDC Consumer ControlPlane ->> EdcControlPlaneClient : List + EdcControlPlaneClient ->> EDCCatalogFacade : List + EDCCatalogFacade ->> EdcSubmodelClientImpl : List + EdcSubmodelClientImpl --> ContractNegotiationService : do negotiation for List + ContractNegotiationService --> ContractNegotiationService : startNewNegotiation + ContractNegotiationService --> PolicyCheckerService : isValid + alt is valid + ContractNegotiationService ->> EdcSubmodelClientImpl : return NegotiationResponse + ContractNegotiationService --> EdcSubmodelClientImpl : retrieve NegotiationResponse + EdcSubmodelClientImpl --> EdcSubmodelClientImpl : getContractAgreementId from NegotiationResponse + EdcSubmodelClientImpl --> AsyncPollingService : retrieveEndpointReference + AsyncPollingService --> EdcSubmodelClientImpl : EndpointDataReference + note left of EdcSubmodelClientImpl : received EDR Token to receive assets + EdcSubmodelClientImpl ->> EdcSubmodelFacade : EndpointDataReference + EdcSubmodelFacade ->> SubmodelDelegate : EndpointDataReference + else is not valid + ContractNegotiationService ->> ContractNegotiationService : throw UsagePolicyException + 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 + end + + +```` + +- [ ] TODO : EdcSubmodelFacade.getSubmodelRawPayload -> Payload of submodel +- [ ] TODO : DecentralDigitalTwinRegistryService -> fetchShells : List keys + + + + +## 2. Case 2: IRS proceed EDC contract negotiation fails because of internal EDC error +## 3. Case 3: IRS proceed successful EDC contract negotiation and revokes asset transfers cause by not matching usage policy + +In ContractNegotiationService startNewNegotiation if policy is not valid the policy of catalog item is returned. Tombstone with policy is created to display IRS requestor the catlogItem which could not be fetched because of invalid policy including their specific policy. + +````mermaid + +sequenceDiagram + %%{init: {'theme': 'dark', 'themeVariables': { 'fontSize': '15px', 'fontFamily': 'Architects daughter'}}}%% + autonumber + ContractNegotiationService --> ContractNegotiationService : startNewNegotiation + ContractNegotiationService --> PolicyCheckerService : isValid + alt is valid + ContractNegotiationService ->> EdcSubmodelClientImpl : return NegotiationResponse + ContractNegotiationService --> EdcSubmodelClientImpl : retrieve NegotiationResponse + EdcSubmodelClientImpl --> EdcSubmodelClientImpl : getContractAgreementId from NegotiationResponse + EdcSubmodelClientImpl --> AsyncPollingService : retrieveEndpointReference + AsyncPollingService --> EdcSubmodelClientImpl : EndpointDataReference + note left of EdcSubmodelClientImpl : received EDR Token to receive assets + EdcSubmodelClientImpl ->> EdcSubmodelFacade : EndpointDataReference + EdcSubmodelFacade ->> IRS : EndpointDataReference + else is not valid + ContractNegotiationService ->> ContractNegotiationService : throw UsagePolicyException + note right of ContractNegotiationService : UsagePolicyException MUST cover the policy of catalog item this is relevant to create tombstone afterwards with policy + end + SubmodelDelegate --> ItemContainer: create tombstone with raw policy information + +```` + +- [ ] ContractNegotiationService adds policy information for catalog item to UsagePolicyException +- [ ] Policy for catalog item is added to Tombstone in SubmodelDelegate + + +## 4. Case 4: 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 + } +] +```` + +## 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 Source: https://app.swaggerhub.com/apis/eclipse-tractusx-bot/tractusx-edc/0.5.3#/Contract%20Agreement/getNegotiationByAgreementId -GET /v2/contractagreements/{id} Gets an contract agreement with the given ID -GET /v2/contractagreements/{id}/negotiation Gets a contract negotiation with the given contract agreement ID -## ContractAgreementId for AAS +``` +GET /v2/contractagreements/{id} + Gets an contract agreement with the given ID +GET /v2/contractagreements/{id}/negotiation + Gets a contract negotiation with the given contract agreement ID +``` + +## Mapping of contract ContractAgreementId in theJobResponse + + +### 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. +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 + } + } +``` + +### 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" +] +```` -## ContractAgreementId for submodels +### Add ContractAgreementId to submodels -### Option 1: Provide submodel for contractAgreementId +#### Option 1: Provide contractAgreementId for each submodel: Impact: -1. High invasive changes to the code, api, JobResponse and documentation. +- 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 ...> + } + ] +``` + +#### 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. ```json @@ -85,7 +252,7 @@ Impact: ] ``` -### Example +#### Example ```json "contractAggreements" : [ @@ -104,37 +271,62 @@ Impact: ] ``` +### 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. + + +`````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://dsi-int-2-1llhjasi.c-5e7e41f.stage.kyma.ondemand.com, https://sap-3-2-ap-edc1-cp.foss.cx.shoot.live.k8s-hana.ondemand.com", + "lastAttempt": "2024-01-17T09:02:36.648055745Z", + "retryCounter": 3 + } + } +], +````` -### Option 2: 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 ...> - } - ] -``` # Glossary -| Abbreviation | Name | -|------------------------|--------------------------| -| edc:ContractAgreement | | -| edc:ContractNegotation | | -| AAS | AssetAdministrationShell | - | contractAgreementId | | +| Abbreviation | Name | +|------------------------|------------------------------------| +| edc:ContractAgreement | | +| edc:ContractNegotation | | +| AAS | AssetAdministrationShell | +| contractAgreementId | Unique Id of an contract aggrement | # References -https://app.swaggerhub.com/apis/eclipse-tractusx-bot/tractusx-edc/0.5.3#/Contract%20Agreement/getAgreementById \ No newline at end of file +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 +https://eclipse-edc.github.io/docs/#/submodule/Connector/docs/developer/contracts \ No newline at end of file