Skip to content

Commit

Permalink
chore(concept):[#322] add sequence diagram for receiving EDR token
Browse files Browse the repository at this point in the history
  • Loading branch information
@mkanal
mkanal committed Jan 17, 2024
1 parent a044034 commit d23b925
Showing 1 changed file with 224 additions and 32 deletions.
256 changes: 224 additions & 32 deletions ...ract-definiton-for-assets/#322-Provisioning-of-contract-definiton-for-assets.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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.


# <ins>Summary</ins> <a name="summary"></a>

# <ins>Problem Statement</ins> <a name="statement"></a>
Expand All @@ -50,22 +55,184 @@ This specific id must therefore be stored and linked for the exchanged asset in

# <ins>Concept</ins> <a name="concept"></a>

## 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 <br /> [POST /management/v2/catalog/request]
EDC Consumer ControlPlane ->> EdcControlPlaneClient : List<CatalogItems>
EdcControlPlaneClient ->> EDCCatalogFacade : List<CatalogItems>
EDCCatalogFacade ->> EdcSubmodelClientImpl : List<CatalogItems>
EdcSubmodelClientImpl --> ContractNegotiationService : do negotiation for List<CatalogItems>
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
}
]
````

## <ins>EDC Management API </ins>
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
```

## <ins>Mapping of contract ContractAgreementId in theJobResponse</ins>


### <ins>Add ContractAgreementId to shells (AAS) </ins>
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
}
}
```

### <ins>Add ContractAgreementId to relationships</ins>
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
### <ins>Add ContractAgreementId to submodels </ins>

### 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": "<contractAgreementId>",
"payload": {
<... submodel payload ...>
}
]
```

#### <ins>Option 2: Provide submodel for contractAgreementId </ns>
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
Expand All @@ -85,7 +252,7 @@ Impact:
]
```

### Example
#### Example

```json
"contractAggreements" : [
Expand All @@ -104,37 +271,62 @@ Impact:
]
```

### <ins>Add Tombstone in case of not matching policy</ins>

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": "<contractAgreementId>",
"payload": {
<... submodel payload ...>
}
]
```


# <ins>Glossary</ins> <a name="glossary"></a>

| Abbreviation | Name |
|------------------------|--------------------------|
| edc:ContractAgreement | |
| edc:ContractNegotation | |
| AAS | AssetAdministrationShell |
| contractAgreementId | |
| Abbreviation | Name |
|------------------------|------------------------------------|
| edc:ContractAgreement | |
| edc:ContractNegotation | |
| AAS | AssetAdministrationShell |
| contractAgreementId | Unique Id of an contract aggrement |

# <ins>References</ins> <a name="references"></a>

https://app.swaggerhub.com/apis/eclipse-tractusx-bot/tractusx-edc/0.5.3#/Contract%20Agreement/getAgreementById
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

0 comments on commit d23b925

Please sign in to comment.