From 1b029ece866901ffcb4401fcfd41294635428716 Mon Sep 17 00:00:00 2001 From: Enrico Risa Date: Thu, 18 Apr 2024 14:11:05 +0200 Subject: [PATCH] docs: update walkthrough guide --- .../management-api-walkthrough/02_policies.md | 387 +++++++----------- .../management-api-walkthrough/04_catalog.md | 128 +++--- .../05_contractnegotiations.md | 96 ++--- .../06_transferprocesses.md | 128 +++--- .../08_contractagreements.md | 39 +- 5 files changed, 343 insertions(+), 435 deletions(-) diff --git a/docs/usage/management-api-walkthrough/02_policies.md b/docs/usage/management-api-walkthrough/02_policies.md index f7c8650ec..ac97d1d6c 100644 --- a/docs/usage/management-api-walkthrough/02_policies.md +++ b/docs/usage/management-api-walkthrough/02_policies.md @@ -28,7 +28,7 @@ impacting policy definitions. Policies can be created in the EDC as follows: ```http -POST /v3/assets HTTP/1.1 +POST /v3/policydefinitions HTTP/1.1 Host: https://provider-control.plane/api/management X-Api-Key: password Content-Type: application/json @@ -36,30 +36,25 @@ Content-Type: application/json ```json { - "@context": { - "@vocab": "https://w3id.org/edc/v0.0.1/ns/", - "odrl": "http://www.w3.org/ns/odrl/2/" - }, - "@type": "PolicyDefinitionRequest", + "@context": [ + "https://w3id.org/tractusx/policy/v1.0.0", + "http://www.w3.org/ns/odrl.jsonld", + { + "@vocab": "https://w3id.org/edc/v0.0.1/ns/" + } + ], + "@type": "PolicyDefinition", "@id": "{{POLICY_ID}}", "policy": { - "@type": "odrl:Set", - "odrl:permission": [ + "@type": "Set", + "permission": [ { - "odrl:action": { - "@id": "odrl:use" - }, - "odrl:constraint": [ - { - "odrl:leftOperand": { - "@value": "BusinessPartnerNumber" - }, - "odrl:operator": { - "@id": "odrl:eq" - }, - "odrl:rightOperand": "" - } - ] + "action": "use", + "constraint": { + "leftOperand": "FrameworkAgreement", + "operator": "eq", + "rightOperand": "pcf" + } } ] } @@ -80,6 +75,12 @@ Please note that in JSON-LD, structures that may look different may actually hav or compacted, define additional `@context` objects, refer to a predefined outside `context` or others. Using a parser or the [json-ld playground](https://json-ld.org/playground/) helps to be consistent. +The JSON-LD context to include depends on the type of constraint: + +- ODRL -> `http://www.w3.org/ns/odrl.jsonld` (always) +- BPN/BPN-Groups -> `https://w3id.org/tractusx/edc/v0.0.1` +- VC -> `https://w3id.org/tractusx/policy/v1.0.0` + If the creation of the `policy-definition` was successful, the Management-API will return HTTP 200. #### Catena-X specific `constraints` @@ -122,118 +123,64 @@ For the following Scenarios, we assume there is a **Partner 1 (provider)** who w Partner 2 (consumer) signed the **Traceability Framework Agreement** and followed all the necessary steps that the Credential appears within Partner 2s identity. -So for this example, if Partner 2 does a catalog request to Partner 1, the following credential is provided to -Partner 1: +When doing a catalog request with the [IATP](https://github.com/eclipse-tractusx/identity-trust/blob/main/specifications/verifiable.presentation.protocol.md) presentation flow +the `MembershipCredential` is provided to Partner 1: + +For example: ```json { "@context": [ - "https://w3id.org/2023/catenax/credentials/summary/v1" + "https://www.w3.org/2018/credentials/v1", + "https://w3id.org/catenax/credentials/v1.0.0" ], - "id": "", + "id": "1f36af58-0fc0-4b24-9b1c-e37d59668089", "type": [ "VerifiableCredential", - "SummaryCredential" + "MembershipCredential" ], - "issuer": "", - "issuanceDate": "2023-06-02T12:00:00Z", + "issuer": "did:web:com.example.issuer", + "issuanceDate": "2021-06-16T18:56:59Z", "expirationDate": "2022-06-16T18:56:59Z", "credentialSubject": { - "id": "", - "holderIdentifier": "BPN6789", - "items": [ - "MembershipCredential", - "TraceabilityCredential" - ], - "contractTemplates": "https://public.catena-x.org/contracts/" - } -} -``` -> Note: This specific credential schema will not be supported in upcoming releases but serves the purpose to illustrate -> what such a credential may look like. - -#### Scenario 1 - -Partner 1 wants to create an Access Policy, that Partner 2 can only receive the Contract offer if its BPN matches AND if -it has the Traceability Credential (Traceability Contract Signed). If one of those is missing, Partner 2 won't receive a -Contract Offer. - -##### Partner 1 - Access Policy Example - -```json - { - "@context": { - "odrl": "http://www.w3.org/ns/odrl/2/" - }, - "@type": "PolicyDefinitionRequest", - "@id": "{{POLICY_ID}}", - "policy": { - "@type": "Policy", - "odrl:permission": [ - { - "odrl:action": "use", - "odrl:constraint": { - "@type": "LogicalConstraint", - "odrl:and": [ - { - "@type": "Constraint", - "odrl:leftOperand": "BusinessPartnerNumber", - "odrl:operator": { - "@id": "odrl:eq" - }, - "odrl:rightOperand": "{{CONSUMERS_BPN}}" - }, - { - "@type": "Constraint", - "odrl:leftOperand": "FrameworkAgreement.traceability", - "odrl:operator": { - "@id": "odrl:eq" - }, - "odrl:rightOperand": "active" - } - ] - } - } - ] + "id": "did:web:com.example.participant", + "holderIdentifier": "BPN6789" } } ``` -Each `leftOperand` is resolved by the EDC against a property in the participant's Verfiable Credential. Thus the exact -data structure may not always match between the VC and the policy. - -##### Desired Outcome - -Partner 2 receives the Contract Offer because the BPNs are matching and he owns the Traceability Credential. +For other subsequent requests like Contract negotiation requests and transfer process requests, the presented +credentials are based on the usage/contract policy. -#### Scenario 2 +#### Scenario 1 Partner 1 wants to create an Access Policy, that Partner 2 can receive the Contract Offer if its BPN matches. But a Contract Agreement should only be created if Partner 2 also signed the Traceability Framework Agreement. So in this case, Partner 2 should receive the Contract Offer in the first place, regardless if it signed the Traceability Framework Agreement. The signing of the Agreement should be checked at the time of contract negotiation. -##### Partner 1 - Access Policy Example (Scenario 2) +##### Partner 1 - Access Policy Example (Scenario 1) ```json { - "@context": { - "odrl": "http://www.w3.org/ns/odrl/2/" - }, - "@type": "PolicyDefinitionRequest", + "@context": [ + "https://w3id.org/tractusx/edc/v0.0.1", + "http://www.w3.org/ns/odrl.jsonld", + { + "@vocab": "https://w3id.org/edc/v0.0.1/ns/" + } + ], + "@type": "PolicyDefinition", "@id": "{{POLICY_ID}}", "policy": { - "@type": "Policy", - "odrl:permission": [ + "@type": "Set", + "permission": [ { - "odrl:action": "use", - "odrl:constraint": { - "@type": "Constraint", - "odrl:leftOperand": "BusinessPartnerNumber", - "odrl:operator": { - "@id": "odrl:eq" - }, - "odrl:rightOperand": "{{BPN6789}}" + "action": "use", + "constraint": { + "leftOperand": "BusinessPartnerNumber", + "operator": "eq", + "rightOperand": "BPN6789" } } ] @@ -241,27 +188,28 @@ Agreement. The signing of the Agreement should be checked at the time of contrac } ``` -##### Partner 1 - Usage/Contract Policy Example (Scenario 2) +##### Partner 1 - Usage/Contract Policy Example (Scenario 1) ```json +{ + "@context": [ + "https://w3id.org/tractusx/policy/v1.0.0", + "http://www.w3.org/ns/odrl.jsonld", { - "@context": { - "odrl": "http://www.w3.org/ns/odrl/2/" - }, - "@type": "PolicyDefinitionRequest", + "@vocab": "https://w3id.org/edc/v0.0.1/ns/" + } + ], + "@type": "PolicyDefinition", "@id": "{{POLICY_ID}}", "policy": { - "@type": "Policy", - "odrl:permission": [ + "@type": "Set", + "permission": [ { - "odrl:action": "use", - "odrl:constraint": { - "@type": "Constraint", - "odrl:leftOperand": "FrameworkAgreement.traceability", - "odrl:operator": { - "@id": "odrl:eq" - }, - "odrl:rightOperand": "active" + "action": "use", + "constraint": { + "leftOperand": "FrameworkAgreement", + "operator": "eq", + "rightOperand": "traceability" } } ] @@ -269,49 +217,37 @@ Agreement. The signing of the Agreement should be checked at the time of contrac } ``` -##### Desired Outcome (Scenario 2) +##### Desired Outcome (Scenario 1) Partner 2 receives the Contract Offer and is able to negotiate the contract because he owns the Traceability Credential. -#### Scenario 3 +#### Scenario 2 -Partner 1 wants to create an Access Policy that Partner 2 can receive the Contract Offer if the BPN is matching AND -Partner 2 is identified as a Dismantler (owns the "DismantlerCredential"). +Partner 1 wants to create an Access Policy that Partner 2 can receive the Contract Offer if the BPN is matching +but a Contract Agreement should only be created if Partner 2 is identified as a Dismantler (owns the "DismantlerCredential"). -##### Partner 1 - Access Policy Example (Scenario 3) +##### Partner 1 - Access Policy Example (Scenario 2) ```json { - "@context": { - "odrl": "http://www.w3.org/ns/odrl/2/" - }, - "@type": "PolicyDefinitionRequest", + "@context": [ + "https://w3id.org/tractusx/edc/v0.0.1", + "http://www.w3.org/ns/odrl.jsonld", + { + "@vocab": "https://w3id.org/edc/v0.0.1/ns/" + } + ], + "@type": "PolicyDefinition", "@id": "{{POLICY_ID}}", "policy": { - "@type": "Policy", - "odrl:permission": [ + "@type": "Set", + "permission": [ { - "odrl:action": "use", - "odrl:constraint": { - "@type": "LogicalConstraint", - "odrl:and": [ - { - "@type": "Constraint", - "odrl:leftOperand": "BusinessPartnerNumber", - "odrl:operator": { - "@id": "odrl:eq" - }, - "odrl:rightOperand": "{{BPN6789}}" - }, - { - "@type": "Constraint", - "odrl:leftOperand": "Dismantler", - "odrl:operator": { - "@id": "odrl:eq" - }, - "odrl:rightOperand": "active" - } - ] + "action": "use", + "constraint": { + "leftOperand": "BusinessPartnerNumber", + "operator": "eq", + "rightOperand": "BPN6789" } } ] @@ -319,90 +255,43 @@ Partner 2 is identified as a Dismantler (owns the "DismantlerCredential"). } ``` -##### Desired Outcome (Scenario 3) - -Partner 2 does not receive the Contract Offer as he does not own the Dismantler Credential and is therefore not able to -negotiate the contract or request the data. - -#### Scenario 4 - -Partner 1 wants to create an Access Policy that Partner 2 can receive the Contract Offer if the BPN is matching. -Further, Partner 1 only wants to create an Agreement if Partner 2 is identified as a Dismantler (owns the -"DismantlerCredential"). Otherwise the Negotiation has to fail. - -##### Partner 1 - Access Policy Example (Scenario 4) - -```json -{ - "@context": { - "odrl": "http://www.w3.org/ns/odrl/2/" - }, - "@type": "PolicyDefinitionRequest", - "@id": "{{POLICY_ID}}", - "policy": { - "@type": "Policy", - "odrl:permission": [ - { - "odrl:action": "use", - "odrl:constraint": { - "@type": "LogicalConstraint", - "odrl:and": [ - { - "@type": "Constraint", - "odrl:leftOperand": "BusinessPartnerNumber", - "odrl:operator": { - "@id": "odrl:eq" - }, - "odrl:rightOperand": "{{BPN6789}}" - } - ] - } - } - ] - } -} -``` - -##### Partner 1 - Usage/Contract Policy Example (Scenario 4) +##### Partner 1 - Usage/Contract Policy Example (Scenario 2) ```json { - "@context": { - "odrl": "http://www.w3.org/ns/odrl/2/" - }, - "@type": "PolicyDefinitionRequest", - "@id": "{{POLICY_ID}}", - "policy": { - "@type": "Policy", - "odrl:permission": [ - { - "odrl:action": "use", - "odrl:constraint": { - "@type": "LogicalConstraint", - "odrl:and": [ - { - "@type": "Constraint", - "odrl:leftOperand": "Dismantler", - "odrl:operator": { - "@id": "odrl:eq" - }, - "odrl:rightOperand": "active" - } - ] - } - } - ] + "@context": [ + "https://w3id.org/tractusx/policy/v1.0.0", + "http://www.w3.org/ns/odrl.jsonld", + { + "@vocab": "https://w3id.org/edc/v0.0.1/ns/" } + ], + "@type": "PolicyDefinition", + "@id": "{{POLICY_ID}}", + "policy": { + "@type": "Set", + "permission": [ + { + "action": "use", + "constraint": { + "leftOperand": "Dismantler", + "operator": "eq", + "rightOperand": "active" + } + } + ] + } } ``` -##### Desired Outcome (Scenario 4) +##### Desired Outcome (Scenario 2) Partner 2 receives the Contract Offer in the first place. The contract negotiation, started by Partner 2 fails because he has not been identified as Dismantler and therefore does not own the Dismantler Credential. + #### Writing Policies for the EDC ℹ️ ODRL's model and expressiveness surpass the EDC's current ability to interpret the policies and derive behavior from @@ -439,29 +328,29 @@ it. ```json { - "@context": { - "tx": "https://w3id.org/tractusx/v0.0.1/ns/" - }, - "@type": "PolicyDefinitionRequest", - "@id": "{% uuid 'v4' %}", + "@context": [ + "https://w3id.org/tractusx/edc/v0.0.1", + "http://www.w3.org/ns/odrl.jsonld", + { + "@vocab": "https://w3id.org/edc/v0.0.1/ns/" + } + ], + "@type": "PolicyDefinition", + "@id": "{{POLICY_ID}}", "policy": { "@type": "Set", - "@context": "http://www.w3.org/ns/odrl.jsonld", "permission": [ { "action": "use", - "constraint": [ - { - "leftOperand": "tx:BusinessPartnerGroup", - "operator": "isPartOf", - "rightOperand": "" - } - ] + "constraint": { + "leftOperand": "BusinessPartnerGroup", + "operator": "eq", + "rightOperand": "gold-partners" + } } ] } } - ``` #### Chaining Constraints @@ -471,30 +360,30 @@ and `odrl:xone` (exactly one constraint evaluates to `true`). ```json { - "@context": { - "tx": "https://w3id.org/tractusx/v0.0.1/ns/" - }, - "@type": "PolicyDefinitionRequest", + "@context": [ + "https://w3id.org/tractusx/edc/v0.0.1", + "http://www.w3.org/ns/odrl.jsonld", + { + "@vocab": "https://w3id.org/edc/v0.0.1/ns/" + } + ], + "@type": "PolicyDefinition", "@id": "{{POLICY_ID}}", "policy": { "@type": "Set", - "@context": "http://www.w3.org/ns/odrl.jsonld", "permission": [ { "action": "use", "constraint": [ { - "@type": "LogicalConstraint", "and": [ { - "leftOperand": { - "@value": "" - }, + "leftOperand": "", "operator": "eq", "rightOperand": "" }, { - "leftOperand": "tx:BusinessPartnerGroup", + "leftOperand": "BusinessPartnerGroup", "operator": "isPartOf", "rightOperand": "" } diff --git a/docs/usage/management-api-walkthrough/04_catalog.md b/docs/usage/management-api-walkthrough/04_catalog.md index e384e6d50..79db0081c 100644 --- a/docs/usage/management-api-walkthrough/04_catalog.md +++ b/docs/usage/management-api-walkthrough/04_catalog.md @@ -14,23 +14,19 @@ Content-Type: application/json { "@context": { "edc": "https://w3id.org/edc/v0.0.1/ns/", - "odrl": "http://www.w3.org/ns/odrl/2/" + "@vocab": "https://w3id.org/edc/v0.0.1/ns/" }, - "@type": "edc:CatalogRequest", + "@type": "CatalogRequest", "counterPartyAddress": "https://provider-control.plane/api/v1/dsp", + "counterPartyId": "", "protocol": "dataspace-protocol-http", "querySpec": { - "@type": "edc:QuerySpec", "offset": 0, "limit": 50, "sortField": "https://purl.org/dc/terms/type", "sortOrder": "ASC", "filterExpression": [ { - "@context": { - "edc": "https://w3id.org/edc/v0.0.1/ns/" - }, - "@type": "edc:Criterion", "operandLeft": "edc:someProperty", "operator": "=", "operandRight": "value" @@ -42,6 +38,8 @@ Content-Type: application/json The request body is lean. Mandatory properties are: - `counterPartyAddress` (formerly `providerUrl`): This property points to the DSP-endpoint of the Data Provider's Control Plane. Usually this ends on `/api/v1/dsp`. +- `counterPartyId`: must be the provider BPN. This in not a mandatory property for EDC but it's required for TractusX-EDC. + If omitted the catalog request will fail. - `protocol`: must be `"dataspace-protocol-http"`. The `querySpec` section is optional and allows the Data Consumer to specify what entries from the catalog shall be returned. @@ -68,67 +66,88 @@ The returned payload is a `dcat:Catalog` as required by the [DSP-Specification v ```json { - "@id": "10b1b0f3-5a67-4eee-9404-5a300356a50d", + "@id": "acd67c9c-a5c6-4c59-9474-fcd3f948eab8", "@type": "dcat:Catalog", - "dcat:dataset": [ - { - "@id": "", - "@type": "dcat:Dataset", - "odrl:hasPolicy": { - "@id": "Y29udHJhY3QtZ2V0LTE=:anNvbi1nZXQtMQ==:MDEwODg2ZTItZDhmNi00Y2NjLWFhMWYtY2U2Y2JmYjlmMWQz", - "@type": "odrl:Set", - "odrl:permission": { - "odrl:target": "", - "odrl:action": { - "odrl:type": "http://www.w3.org/ns/odrl/2/use" - }, - "odrl:constraint": { - "odrl:leftOperand": "https://w3id.org/tractusx/v0.0.1/ns/Membership", + "dspace:participantId": "BPNL000000001INT", + "dcat:dataset": { + "@id": "", + "@type": "dcat:Dataset", + "odrl:hasPolicy": { + "@id": "MQ==:MQ==:M2ZmZDRhY2MtMzkyNy00NGI4LWJlZDItNDcwY2RiZGRjN2Ex", + "@type": "odrl:Offer", + "odrl:permission": { + "odrl:action": { + "odrl:type": "http://www.w3.org/ns/odrl/2/use" + }, + "odrl:constraint": { + "odrl:or": { + "odrl:leftOperand": "https://w3id.org/tractusx/v0.0.1/ns/BusinessPartnerGroup", "odrl:operator": { "@id": "odrl:eq" }, - "odrl:rightOperand": "active" + "odrl:rightOperand": "gold-partners" } + } + }, + "odrl:prohibition": [], + "odrl:obligation": [] + }, + "dcat:distribution": [ + { + "@type": "dcat:Distribution", + "dct:format": { + "@id": "AzureStorage-PUSH" + }, + "dcat:accessService": { + "@id": "1338f9ac-1728-4a7e-b3dc-31fe5bc109f6", + "@type": "dcat:DataService", + "dct:terms": "connector", + "dct:endpointUrl": "http://provider-data.plane/api/v1/dsp" + } + }, + { + "@type": "dcat:Distribution", + "dct:format": { + "@id": "HttpData-PULL" }, - "odrl:prohibition": [], - "odrl:obligation": [], - "odrl:target": "" + "dcat:accessService": { + "@id": "1338f9ac-1728-4a7e-b3dc-31fe5bc109f6", + "@type": "dcat:DataService", + "dct:terms": "connector", + "dct:endpointUrl": "http://provider-data.plane/api/v1/dsp" + } }, - "dcat:distribution": [ - { - "@type": "dcat:Distribution", - "dct:format": { - "@id": "HttpProxy" - }, - "dcat:accessService": "b4f2c6b6-d3d1-46e2-a517-6912b7f8a509" + { + "@type": "dcat:Distribution", + "dct:format": { + "@id": "AmazonS3-PUSH" }, - { - "@type": "dcat:Distribution", - "dct:format": { - "@id": "AmazonS3" - }, - "dcat:accessService": "b4f2c6b6-d3d1-46e2-a517-6912b7f8a509" + "dcat:accessService": { + "@id": "1338f9ac-1728-4a7e-b3dc-31fe5bc109f6", + "@type": "dcat:DataService", + "dct:terms": "connector", + "dct:endpointUrl": "http://provider-data.plane/api/v1/dsp" } - ], - "edc:description": "Json Get Asset", - "edc:id": "", - "dct:type": { - "@id": "https://my-namespa.ce/my-asset-type" } - } - ], + ], + "description": "Product EDC Demo Asset 1", + "id": "1" + }, "dcat:service": { - "@id": "b4f2c6b6-d3d1-46e2-a517-6912b7f8a509", + "@id": "1338f9ac-1728-4a7e-b3dc-31fe5bc109f6", "@type": "dcat:DataService", "dct:terms": "connector", - "dct:endpointUrl": "https://provider-data.plane/api/v1/dsp" + "dct:endpointUrl": "http://provider-data.plane/api/v1/dsp" }, - "edc:participantId": "", + "participantId": "", "@context": { - "dct": "https://purl.org/dc/terms/", - "tx": "https://w3id.org/tractusx/v0.0.1/ns/", + "@vocab": "https://w3id.org/edc/v0.0.1/ns/", "edc": "https://w3id.org/edc/v0.0.1/ns/", - "dcat": "https://www.w3.org/ns/dcat/", + "tx": "https://w3id.org/tractusx/v0.0.1/ns/", + "tx-auth": "https://w3id.org/tractusx/auth/", + "cx-policy": "https://w3id.org/catenax/policy/", + "dcat": "http://www.w3.org/ns/dcat#", + "dct": "http://purl.org/dc/terms/", "odrl": "http://www.w3.org/ns/odrl/2/", "dspace": "https://w3id.org/dspace/v0.8/" } @@ -148,13 +167,12 @@ Consequently, if there may be more than one offer for the same Asset, requiring policies included. - The `@id` corresponds to the id of the Asset that can be negotiated for. -- `dcat:Distribution` makes statements over which Data Planes an Asset's data can be retrieved. Currently, the EDC always - returns `HttpProxy` and `AmazonS3` even though not all EDC-deployments have both capabilities. +- `dcat:Distribution` makes statements over which Data Planes an Asset's data can be retrieved. Currently, the TractusX-EDC supports + `HttpData-PULL`, `AmazonS3-PUSH` and `AzureStorage-PUSH` capabilities. - `dcat:hasPolicy` holds the Data Offer that is relevant for the Consumer. - `@id` is the identifier for the Data Offer. The EDC composes this id by concatenating three identifiers in base64-encoding. separated with `:` (colons). The format is `base64(contractDefinitionId):base64(assetId):base64(newUuidV4)`. The last of three UUIDs changes with every request as every /v2/catalog/request call yields a new catalog with new Data Offers. - - The `odrl:target` properties in the Data Offer always hold the Asset's id. - The `odrl:permission`, `odrl:prohibition` and `odrl:obligation` will hold the content of the contractPolicy configured in the [Contract Definition](03_contractdefinitions.md) the Contract Offer was derived from. diff --git a/docs/usage/management-api-walkthrough/05_contractnegotiations.md b/docs/usage/management-api-walkthrough/05_contractnegotiations.md index fc46feef3..71d844f89 100644 --- a/docs/usage/management-api-walkthrough/05_contractnegotiations.md +++ b/docs/usage/management-api-walkthrough/05_contractnegotiations.md @@ -22,25 +22,17 @@ Content-Type: application/json "@context": { "edc": "https://w3id.org/edc/v0.0.1/ns/" }, - "@type": "https://w3id.org/edc/v0.0.1/ns/ContractRequest", - "connectorAddress": "https://provider-control.plane/api/v1/dsp", + "@type": "ContractRequest", + "counterPartyAddress": "https://provider-control.plane/api/v1/dsp", "protocol": "dataspace-protocol-http", - "providerId": "", - "connectorId": "", - "offer": { - "offerId": "", - "assetId": "", - "policy": { - "@context": "http://www.w3.org/ns/odrl.jsonld", - "@type": "Set", - "@id": "", - "action": "use" - } - ] - } + "policy": { + "@id": "", + "@type": "Offer", + "target": "", + "assigner": "", + "permission": [], + "prohibition": [], + "obligation": [] }, "callbackAddresses": [ { @@ -56,22 +48,14 @@ Content-Type: application/json } ``` -- `edc:connectorAddress` sets the coordinates for the connector that the Consumer-EDC shall negotiate with (Provider - EDC). - It will usually end on /api/v1/dsp -- `edc:protocol` must be "dataspace-protocol-http" -- `providerId` is the Data Provider's BPN -- `edc:assetId` and all `odrl:target` properties must be the id of the EDC-Asset/dcat:DataSet that the offer was made - for. -- `edc:connectorId` and `edc:providerId` must both hold the correct BPN for the `edc:connectorAddress`. -- In the `edc:offer` section, the Data Consumer specifies the Data Offer for the negotiation. As there may be multiple +- `counterPartyAddress` sets the coordinates for the connector that the Consumer-EDC shall negotiate with (Provider EDC). + It will usually end in `/api/v1/dsp` +- `protocol` must be `dataspace-protocol-http` +- In the `policy` section, the Data Consumer specifies the Data Offer for the negotiation. As there may be multiple Data Offers for the same DataSet, the Data Consumer must choose one. - - `edc:offerId` is the id of the entry in the [catalog-response](04_catalog.md) that the Consumer wants to negotiate - for. - It will usually be a concatenation of three base64-encoded ids. - - `edc:policy` must hold an identical copy of the Data Offer's contract policy as provided via the catalog-API in - the - `odrl:hasPolicy` field. + It must hold an identical copy of the Data Offer's contract policy as provided via the catalog-API in the `odrl:hasPolicy` field plus: + - `assigner` must hold the BPN of the Provider + - `target` must be the id of the EDC-Asset/dcat:DataSet that the offer was made for. - `callbackAddresses` is a list of Consumer-side endpoints that the Provider's Data Plane writes events to. - `uri` is the http endpoint of the token repository. Mandatory. - `events` is a list of the strings, signifying for what callbacks the specified API shall be used. They are @@ -90,17 +74,17 @@ the `@id` property. ```json { - "@type": "edc:IdResponse", - "@id": "773b8795-45f2-4c57-a020-dc04e639baf3", - "edc:createdAt": 1701289079455, - "@context": { - "dct": "https://purl.org/dc/terms/", - "tx": "https://w3id.org/tractusx/v0.0.1/ns/", - "edc": "https://w3id.org/edc/v0.0.1/ns/", - "dcat": "https://www.w3.org/ns/dcat/", - "odrl": "http://www.w3.org/ns/odrl/2/", - "dspace": "https://w3id.org/dspace/v0.8/" - } + "@type": "IdResponse", + "@id": "773b8795-45f2-4c57-a020-dc04e639baf3", + "edc:createdAt": 1701289079455, + "@context": { + "@vocab": "https://w3id.org/edc/v0.0.1/ns/", + "edc": "https://w3id.org/edc/v0.0.1/ns/", + "tx": "https://w3id.org/tractusx/v0.0.1/ns/", + "tx-auth": "https://w3id.org/tractusx/auth/", + "cx-policy": "https://w3id.org/catenax/policy/", + "odrl": "http://www.w3.org/ns/odrl/2/" + } } ``` @@ -120,13 +104,13 @@ that will look like this: ```json { - "@type": "edc:ContractNegotiation", + "@type": "ContractNegotiation", "@id": "50bf14b9-8f6e-4975-8ada-6f24379a58a2", - "edc:type": "CONSUMER", - "edc:protocol": "dataspace-protocol-http", - "edc:state": "REQUESTING", - "edc:counterPartyId": "", - "edc:counterPartyAddress": "https://provider-control.plane/api/v1/dsp", + "type": "CONSUMER", + "protocol": "dataspace-protocol-http", + "state": "REQUESTING", + "counterPartyId": "", + "counterPartyAddress": "https://provider-control.plane/api/v1/dsp", "callbackAddresses": [ { "transactional": false, @@ -138,14 +122,14 @@ that will look like this: "authCodeId": "auth-code-id" } ], - "edc:createdAt": 1701351116766, + "createdAt": 1701351116766, "@context": { - "dct": "https://purl.org/dc/terms/", - "tx": "https://w3id.org/tractusx/v0.0.1/ns/", + "@vocab": "https://w3id.org/edc/v0.0.1/ns/", "edc": "https://w3id.org/edc/v0.0.1/ns/", - "dcat": "https://www.w3.org/ns/dcat/", - "odrl": "http://www.w3.org/ns/odrl/2/", - "dspace": "https://w3id.org/dspace/v0.8/" + "tx": "https://w3id.org/tractusx/v0.0.1/ns/", + "tx-auth": "https://w3id.org/tractusx/auth/", + "cx-policy": "https://w3id.org/catenax/policy/", + "odrl": "http://www.w3.org/ns/odrl/2/" } } ``` diff --git a/docs/usage/management-api-walkthrough/06_transferprocesses.md b/docs/usage/management-api-walkthrough/06_transferprocesses.md index defce1eeb..df6dad749 100644 --- a/docs/usage/management-api-walkthrough/06_transferprocesses.md +++ b/docs/usage/management-api-walkthrough/06_transferprocesses.md @@ -1,8 +1,32 @@ # Initiation a Transfer Process -Despite the naming, the Transfer Process is not the step that transmits the backend's data from the Provider to the -Consumer. What this API does instead is trigger the Transfer of a Data Plane token from the Provider Control Plane to -the Consumer Control Plane and in turn to a location specified by the Data Consumer. +Transfer process is a set of interactions between Consumer and Provider that gives +the consumer access to a `Dataset` under the terms negotiated the in [Contract Negotiation](05_contractnegotiations.md) phase. + +The processes are handled in the state machine of the Control Planes, but the real data transfer (if necessary) +happens in the provider Data Plane. +TractusX 0.7.0 follows the spec of [DPS](https://github.com/eclipse-edc/Connector/blob/main/docs/developer/data-plane-signaling/data-plane-signaling.md) (Data plane signaling) for Control Plane -> Data Plane communication + +Currently, transfer processes are divided in two modes: + +- Push +- Pull + +## Push + +If the mode is push, for example `AmazonS3-PUSH` mode, once the transfer request has been validated and accepted +by the Provider Control Plane, the transfer switches to the `STARTED` state, and it delegates the data transfer +to the Data Plane via (DPS). The transfer process transition to `COMPLETED` state once the actual transfer +has been completed by the data plane. + +## Pull + +If the mode is pull, for example `HttpData-PULL` mode, once the transfer request has been validated and accepted +by the Provider Control Plane, the transfer switches to the `STARTED` state, and it delegates [EDR](07_edrs.md) creation +to the Data Plane via (DPS). The transfer will stay in `STARTED` state until the transfer process gets manually +terminated/suspended or terminated by the policy monitor depending on the configured policy on the [Contract Agreement](08_contractagreements.md). + +## Transfer Request To trigger this process, the Consumer app makes a request to its EDC's Control Plane: ```http @@ -11,23 +35,22 @@ Host: https://consumer-control.plane/api/management X-Api-Key: password Content-Type: application/json ``` + ```json { "@context": { - "@vocab": "https://w3id.org/edc/v0.0.1/ns/", - "odrl": "http://www.w3.org/ns/odrl/2/" + "@vocab": "https://w3id.org/edc/v0.0.1/ns/" }, + "@type": "TransferRequest", "assetId": "", - "connectorAddress": "", + "counterPartyAddress": "", "contractId": "", "dataDestination": { "type": "" }, - "managedResources": false, - "privateProperties": { - "receiverHttpEndpoint": "" - }, + "privateProperties": {}, "protocol": "dataspace-protocol-http", + "transferType": "HttpData-PULL", "callbackAddresses": [ { "transactional": false, @@ -43,50 +66,41 @@ Content-Type: application/json ``` - `assetId` is the id of the [asset](01_assets.md) that a transfer process should be triggered for. -- `connectorAddress` is the DSP-endpoint of the Data Provider (usually ending on /api/v1/dsp). +- `counterPartyAddress` is the DSP-endpoint of the Data Provider (usually ending on /api/v1/dsp). - `contractId` represents the Contract Agreement that the Provider and Consumer agreed on during the [Contract Negotiation](05_contractnegotiations.md) phase. -- `dataDestination` will in the case of an HTTP-based transfer of the Token be a `DataAddress` object, holding exclusively - the `edc:type` property that must be set to `"HttpProxy"`. -- `managedResources` is a boolean (not a string like in the [assets-API](01_assets.md#http-data-plane)). -- `privateProperties` can be filled with arbitrary data (like in the [assets-API](01_assets.md)). However, there is one property - that will cause changes in EDC behavior: - - `receiverHttpEndpoint` is interpreted by the EDC as the URL that it shall write the Data Plane token to. These messages - will be transmitted via HTTP POST holding plain JSON where the Data Plane Token is written to the property `authCode`. - The Consumer Control Plane will use authentication headers that must be configured during deployment. +- `dataDestination` will in the case of an HTTP PULL-based transfer of the Token be a `DataAddress` object, holding exclusively + the `type` property that must be set to `"HttpProxy"`. +- `privateProperties` can be filled with arbitrary data (like in the [assets-API](01_assets.md)). - `protocol` describes the protocol between the EDCs and will always be `dataspace-protocol-http`. +- `transferType` should be one of the returned format in the [Catalog](04_catalog.md) - `callbackAddresses`: Like the [Contract Negotiation API](05_contractnegotiations.md), an application can also register - a callback listener to get updates on the Transfer Process state. The relevant signal is `contract.negotiation`. + a callback listener to get updates on the Transfer Process state. The relevant signal is `transfer.process`. This call also returns an id, that can be used to monitor the progress. ```json { + "@type": "IdResponse", + "@id": "927c9712-b270-47ee-b391-9e92a4c55a5d", + "createdAt": 1713439560709, "@context": { - "edc": "https://w3id.org/edc/v0.0.1/ns/" - }, - "@id": "177aba51-52d7-44dc-beab-fd6151147024", - "createdAt": 1688465655 + "@vocab": "https://w3id.org/edc/v0.0.1/ns/", + "edc": "https://w3id.org/edc/v0.0.1/ns/", + "tx": "https://w3id.org/tractusx/v0.0.1/ns/", + "tx-auth": "https://w3id.org/tractusx/auth/", + "cx-policy": "https://w3id.org/catenax/policy/", + "odrl": "http://www.w3.org/ns/odrl/2/" + } } ``` ## Checking for Completion -### Token Transfer +### Token Transfer HTTP PULL-BASED -As described in the `receiverHttpEndpoint` section, on a successful Transfer Process, a message will be transmitted to -the specified address holding the Data Plane Token. That's not only the goal of EDC-interaction but also the sign for -a completed process. Here's an example for such a message: - -```json -{ - "id": "177aba51-52d7-44dc-beab-fd6151147024", - "endpoint": "https://provider-data.plane/", - "authKey": "Authorization", - "authCode": "", - "properties": {} -} -``` +As outlined in PULL-BASED scenario the transfer process will remain in the `STARTED` state once the EDR reaches +the Consumer Control Plane. How to handle EDRs consumption check [here](07_edrs.md). ### Polling @@ -103,26 +117,19 @@ yielding ```json { - "@context": { - "edc": "https://w3id.org/edc/v0.0.1/ns/" - }, - "@type": "https://w3id.org/edc/v0.0.1/ns/TransferProcess", - "@id": "process-id", - "correlationId": "correlation-id", - "type": "PROVIDER", - "state": "STARTED", - "stateTimestamp": 1688465655, - "assetId": "asset-id", - "connectorId": "connectorId", - "contractId": "contractId", + "@id": "432b242d-3795-403f-8fac-f7bd41d9cef5", + "@type": "TransferProcess", + "state": "TERMINATED", + "stateTimestamp": 1713439434962, + "type": "CONSUMER", + "assetId": "1", + "contractId": "47e05ca6-c373-4345-9ba8-e4915e02e99e", + "transferType": "HttpData-PULL", + "errorDetail": "Policy not found for contract: 47e05ca6-c373-4345-9ba8-e4915e02e99e", "dataDestination": { + "@type": "DataAddress", "type": "HttpProxy" }, - "privateProperties": { - "receiverHttpEndpoint": "private-value" - }, - "errorDetail": "eventual-error-detail", - "createdAt": 1688465655, "callbackAddresses": [ { "transactional": false, @@ -133,9 +140,16 @@ yielding "authKey": "auth-key", "authCodeId": "auth-code-id" } - ] + ], + "@context": { + "@vocab": "https://w3id.org/edc/v0.0.1/ns/", + "edc": "https://w3id.org/edc/v0.0.1/ns/", + "tx": "https://w3id.org/tractusx/v0.0.1/ns/", + "tx-auth": "https://w3id.org/tractusx/auth/", + "cx-policy": "https://w3id.org/catenax/policy/", + "odrl": "http://www.w3.org/ns/odrl/2/" + } } - ``` Note that the property `errorDetails` will only be returned in certain states and may contain hints to where the communication between the Data Planes failed. The state-machine for the Transfer Process is [documented here](https://eclipse-edc.github.io/docs/#/submodule/Connector/docs/developer/data-transfer?id=transfer-process-state-machine). diff --git a/docs/usage/management-api-walkthrough/08_contractagreements.md b/docs/usage/management-api-walkthrough/08_contractagreements.md index 387ccb2f4..00e895b2c 100644 --- a/docs/usage/management-api-walkthrough/08_contractagreements.md +++ b/docs/usage/management-api-walkthrough/08_contractagreements.md @@ -15,41 +15,44 @@ A Contract Agreement looks like this: ```json { - "@type": "edc:ContractAgreement", + "@type": "ContractAgreement", "@id": "", - "edc:assetId": "", - "edc:policy": { + "assetId": "", + "policy": { "@id": "", - "@type": "odrl:Set", + "@type": "odrl:Agreement", "odrl:permission": { - "odrl:target": "", "odrl:action": { - "odrl:type": "use" + "odrl:type": "http://www.w3.org/ns/odrl/2/use" }, "odrl:constraint": { - "odrl:and": { - "odrl:leftOperand": "BusinessPartnerNumber", + "odrl:or": { + "odrl:leftOperand": "https://w3id.org/catenax/policy/FrameworkAgreement", "odrl:operator": { "@id": "odrl:eq" }, - "odrl:rightOperand": "" + "odrl:rightOperand": "pcf" } } }, "odrl:prohibition": [], "odrl:obligation": [], - "odrl:target": ">ASSET_ID>" + "odrl:assignee": "", + "odrl:assigner": "", + "odrl:target": { + "@id": "" + } }, - "edc:contractSigningDate": 1697720380, - "edc:consumerId": "", - "edc:providerId": "", + "contractSigningDate": 1713441910, + "consumerId": "", + "providerId": "", "@context": { - "dct": "https://purl.org/dc/terms/", - "tx": "https://w3id.org/tractusx/v0.0.1/ns/", + "@vocab": "https://w3id.org/edc/v0.0.1/ns/", "edc": "https://w3id.org/edc/v0.0.1/ns/", - "dcat": "https://www.w3.org/ns/dcat/", - "odrl": "http://www.w3.org/ns/odrl/2/", - "dspace": "https://w3id.org/dspace/v0.8/" + "tx": "https://w3id.org/tractusx/v0.0.1/ns/", + "tx-auth": "https://w3id.org/tractusx/auth/", + "cx-policy": "https://w3id.org/catenax/policy/", + "odrl": "http://www.w3.org/ns/odrl/2/" } } ```