From 3e89b3189eb3c91026379c4c44a4b33a1023bb23 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?David=20G=C3=B6rzig?= <132340784+dvg36@users.noreply.github.com> Date: Wed, 27 Nov 2024 11:54:07 +0100 Subject: [PATCH 01/14] adapt deplyoment for community days --- .../tutorials/e2e/connect/deployComponents.md | 316 +++++------------- 1 file changed, 92 insertions(+), 224 deletions(-) diff --git a/docs/tutorials/e2e/connect/deployComponents.md b/docs/tutorials/e2e/connect/deployComponents.md index 2cb4dd5c3ba..ed1d8d28502 100644 --- a/docs/tutorials/e2e/connect/deployComponents.md +++ b/docs/tutorials/e2e/connect/deployComponents.md @@ -38,43 +38,6 @@ This chapter aligns with the README for the Tractus-X umbrella charts following ::: -:::warning -If you are [not] the only user on your system working with the turorial, means you are working in a multi-user environment, please ensure, that you understand your impact on other minikube profiles of other users and Umbralla namespaces. Please check, if other user are working on the same system by checking the existance of other minikube profiles with the command: - -```bash -minikube profile list -``` - -Please ensure you are explicitly defining the profile with the `-f` parameter and [never] using options like **--all**. To avoid disturbing other we use the environment variable [$USER] any time we specify a name for a minikube profile of an Umbrella namespace. - -So if your minikube cluster will not be the only one running in your system, please - -- use specific names for your cluster profile and namespaces for helm​ - - Proposed name for the cluster profile: **minikube-$USER** - - Proposed name for the umbrella namespace: **umbrella-$USER** ​ - -- Ensure you are using the option `-p`, everytime you calling minikube ​ - -```bash -minikube –p minikube-$USER ​ -``` - -Ensure you are using the option **–n**, every time you calling helm​ - -```bash -helm –n umbrella-$USER -``` - -Before you enable ingress enter:​ - -```bash -minikube profile minikube-$USER​ -``` - -This will ensure that ingress is working in the correct environment of your cluster profile. - -::: - ### Overview Perform the following steps to begin deploying the TXD: @@ -93,7 +56,7 @@ For the most bare-bones installation of the dataspace, execute the following com ```bash # get the tutorial including the config file for the cluster by cloning the repository locally -git clone [https://github.com/eclipse-tractusx/tractus-x-umbrella.git](https://github.com/eclipse-tractusx/tractus-x-umbrella.git") +git clone https://github.com/eclipse-tractusx/tractus-x-umbrella.git ``` Now we will find the directory [tractus-x-umbrella] under your current working directory. Change into this directory: @@ -107,22 +70,14 @@ cd tractus-x-umbrella To start the cluster we just call **minikube start**. If we have more than one instance, we use -p option to set the profile name minikube-$USER. We use the other options to request the appropiate resources. ```bash -minikube start [-p minikube-$USER] --cpus=4 --memory 6gb +minikube start --cpus=4 --memory 6gb # Start the cluster, if -p option is used with the profile name minikube-$USER ``` -We now switch the context to minikube profile. This is required to ensure Ingress gets the correct data of the cluster. But it is not needed, if you run only one minikube cluster on your system. - -```bash -minikube profile minikube-$USER -# Switch the context to minikube profile -``` - You can check your minikube cluster any time by starting the Minikube dashboard: ```bash -minikube [-p minikube-$USER] dashboard -# if -p option is used, with the profile name minikube-$USER +minikube dashboard ``` ### Setting up the local internal netwok @@ -130,8 +85,7 @@ minikube [-p minikube-$USER] dashboard In order to enable the local access via ingress, use the according addon for Minikube: ```bash -minikube [-p minikube-$USER] addons enable ingress -# if -p option is used, with the profile name minikube-$USER +minikube addons enable ingress ``` Now add these hostnames to your /etc/hosts. You should ensure that you have access and the /etc/hosts file group entry should be assigend to the group **docker**. Check this with the following commands: @@ -150,15 +104,13 @@ Alternatively configure the DNS Service to be enabled for Ingress. ::: ```bash -minikube [-p minikube-$USER] addons enable ingress-dns -# if -p option is used, with the profile name minikube-$USER +minikube addons enable ingress-dns ``` Find out the IP Address of your minikube cluster by entering: ```bash -minikube [-p minikube-$USER] ip -# if -p option is used, with the profile name minikube-$USER +minikube ip ``` In the following steps, replace `192.168.49.2` with your `minikube ip` if it differs. @@ -168,7 +120,7 @@ In the following steps, replace `192.168.49.2` with your `minikube ip` if it dif Create a file in /etc/resolver/minikube-test with the following contents. ```properties -domain arena.test +domain tx.test nameserver 192.168.49.2 search_order 1 timeout 5 @@ -177,18 +129,25 @@ timeout 5 If you still face DNS issues, add the hosts to your /etc/hosts file: ```properties -192.168.49.2 centralidp.arena.test -192.168.49.2 sharedidp.arena.test -192.168.49.2 portal.arena.test -192.168.49.2 portal-backend.arena.test -192.168.49.2 managed-identity-wallets.arena.test -192.168.49.2 semantics.arena.test -192.168.49.2 sdfactory.arena.test -192.168.49.2 dataconsumer-1-dataplane.arena.test -192.168.49.2 dataconsumer-1-controlplane.arena.test -192.168.49.2 dataprovider-dataplane.arena.test -192.168.49.2 dataconsumer-2-dataplane.arena.test -192.168.49.2 dataconsumer-2-controlplane.arena.test +192.168.49.2 centralidp.tx.test +192.168.49.2 sharedidp.tx.test +192.168.49.2 portal.tx.test +192.168.49.2 portal-backend.tx.test +192.168.49.2 semantics.tx.test +192.168.49.2 sdfactory.tx.test +192.168.49.2 ssi-credential-issuer.tx.test +192.168.49.2 dataconsumer-1-dataplane.tx.test +192.168.49.2 dataconsumer-1-controlplane.tx.test +192.168.49.2 dataprovider-dataplane.tx.test +192.168.49.2 dataprovider-controlplane.tx.test +192.168.49.2 dataconsumer-2-dataplane.tx.test +192.168.49.2 dataconsumer-2-controlplane.tx.test +192.168.49.2 bdrs-server.tx.test +192.168.49.2 iatpmock.tx.test +192.168.49.2 business-partners.tx.test +192.168.49.2 pgadmin4.tx.test +192.168.49.2 ssi-dim-wallet-stub.tx.test +192.168.49.2 dataprovider-submodelserver.tx.test ``` Additional network setup for Mac: @@ -202,51 +161,25 @@ We also recommend to execute the usage example after install to check proper set For Windows edit the hosts file under `C:\Windows\System32\drivers\etc\hosts`: ```properties -192.168.49.2 centralidp.arena.test -192.168.49.2 sharedidp.arena.test -192.168.49.2 portal.arena.test -192.168.49.2 portal-backend.arena.test -192.168.49.2 managed-identity-wallets.arena.test -192.168.49.2 semantics.arena.test -192.168.49.2 sdfactory.arena.test -192.168.49.2 dataconsumer-1-dataplane.arena.test -192.168.49.2 dataconsumer-1-controlplane.arena.test -192.168.49.2 dataprovider-dataplane.arena.test -192.168.49.2 dataconsumer-2-dataplane.arena.test -192.168.49.2 dataconsumer-2-controlplane.arena.test -``` - -#### Adjusting the Config files for multi user usage - -In case we have to modify the values within the configuartion files as we run in a multi use environment, we need to adjust the domians names within the configuration files. A simple way is to update the file by using **sed** as line editor. - -```bash -# adjust values.yaml -# -DOMAIN_NAME="$USER.test" -CONFIG_FILE="alues-adopter-data-exchange.yaml" -cp values.yaml values.yaml.orig -cat values.yaml.orig | sed s/tx.test/$DOMAIN_NAME/ > values.yaml -echo "file values.yaml updated with actual dommainame $DOMAIN_NAME" -cp $CONFIG_FILE $CONFIG_FILE.orig -cat $CONFIG_FILE.orig | sed s/tx.test/$DOMAIN_NAME/ > $CONFIG_FILE -echo "file $CONFIG_FILE updated with actual dommainame $DOMAIN_NAME" -# Adjust further files: concept/seeds-overall-data.md, init-container/iam/centralidp/CX-Central-realm.json, init --container/iam/sharedidp/CX-operator-realm.json. init-container/iam/sharedidp/CX-operator-users-0.json -# -cd ../.. -echo "Modifing file concept/seeds-overall-data.md, ..." -cp concept/seeds-overall-data.md concept/seeds-overall-data.md.orig -cat concept/seeds-overall-data.md.orig | sed s/tx.test/$DOMAIN_NAME/ > concept/seeds-overall-data.md -echo "Modifing file init-container/iam/centralidp/CX-Central-realm.json ..." -cp init-container/iam/centralidp/CX-Central-realm.json init-container/iam/centralidp/CX-Central-realm.json.orig -cat init-container/iam/centralidp/CX-Central-realm.json.orig | sed s/tx.test/$DOMAIN_NAME/ > init-container/iam/centralidp/CX-Central-realm.json -echo "Modifing file init-container/iam/sharedidp/CX-operator-realm.json ..." -cp init-container/iam/sharedidp/CX-Operator-realm.json init-container/iam/sharedidp/CX-Operator-realm.json.orig -cat init-container/iam/sharedidp/CX-Operator-realm.json.orig | sed s/tx.test/$DOMAIN_NAME/ > init-container/iam/sharedidp/CX-Operator-realm.json -echo "Modifing file init-container/iam/sharedidp/CX-operator-realm.json ..." -cp init-container/iam/sharedidp/CX-Operator-users-0.json init-container/iam/sharedidp/CX-Operator-users-0.json.orig -cat init-container/iam/sharedidp/CX-Operator-users-0.json.orig | sed s/tx.test/$DOMAIN_NAME/ > init-container/iam/sharedidp/CX-Operator-users-0.json +192.168.49.2 centralidp.tx.test +192.168.49.2 sharedidp.tx.test +192.168.49.2 portal.tx.test +192.168.49.2 portal-backend.tx.test +192.168.49.2 semantics.tx.test +192.168.49.2 sdfactory.tx.test +192.168.49.2 ssi-credential-issuer.tx.test +192.168.49.2 dataconsumer-1-dataplane.tx.test +192.168.49.2 dataconsumer-1-controlplane.tx.test +192.168.49.2 dataprovider-dataplane.tx.test +192.168.49.2 dataprovider-controlplane.tx.test +192.168.49.2 dataconsumer-2-dataplane.tx.test +192.168.49.2 dataconsumer-2-controlplane.tx.test +192.168.49.2 bdrs-server.tx.test +192.168.49.2 iatpmock.tx.test +192.168.49.2 business-partners.tx.test +192.168.49.2 pgadmin4.tx.test +192.168.49.2 ssi-dim-wallet-stub.tx.test +192.168.49.2 dataprovider-submodelserver.tx.test ``` ### Install Helm Charts @@ -261,82 +194,9 @@ Those jobs will recreate pods until one run is successful. ::: -#### Use released chart - -```bash -helm repo add tractusx-dev https://eclipse-tractusx.github.io/charts/dev -``` - -##### :grey_question: Command explanation - -:::info - -`helm install` is used to install a chart in Kubernetes using Helm. - -- `--set COMPONENT_1.enabled=true,COMPONENT_2.enabled=true` Enables the components by setting their respective enabled values to true. -- `umbrella` is the release name for the chart. -- `tractusx-dev/umbrella` specifies the chart to install, with *tractusx-dev* being the repository name and *umbrella* being the chart name. -- `--namespace umbrella` specifies the namespace in which to install the chart. -- `--create-namespace` create a namespace with the name `umbrella`. - -::: - -##### Option 1 - -Install with your chosen components enabled: - -```bash -helm install \ - --set COMPONENT_1.enabled=true,COMPONENT_2.enabled=true,COMPONENT_3.enabled=true \ - umbrella tractusx-dev/umbrella \ - --namespace umbrella \ - --create-namespace -``` - -##### Option 2 - -Choose to install one of the predefined subsets (currently in focus of the **E2E Adopter Journey**): - -###### Data Exchange Subset - -```bash -helm install \ - --set centralidp.enabled=true,managed-identity-wallet.enabled=true,dataconsumerOne.enabled=true,tx-data-provider.enabled=true \ - umbrella tractusx-dev/umbrella \ - --namespace umbrella \ - --create-namespace -``` - -###### Optional - -Enable `dataconsumerTwo` at upgrade: - -```bash -helm install \ - --set centralidp.enabled=true,managed-identity-wallet.enabled=true,dataconsumerOne.enabled=true,tx-data-provider.enabled=true,dataconsumerTwo.enabled=true \ - umbrella tractusx-dev/umbrella \ - --namespace umbrella -``` - -###### Portal Subset - -```bash -helm install \ - --set portal.enabled=true,centralidp.enabled=true,sharedidp.enabled=true \ - umbrella tractusx-dev/umbrella \ - --namespace umbrella \ - --create-namespace -``` - -To set your own configuration and secret values, install the helm chart with your own values file: - -```bash -helm install -f your-values.yaml umbrella tractusx-dev/umbrella --namespace umbrella --create-namespace -``` - #### Use local repository -Make sure to clone the [tractus-x-umbrella](https://github.com/eclipse-tractusx/tractus-x-umbrella) repository beforehand. +Make sure you cloned the [tractus-x-umbrella](https://github.com/eclipse-tractusx/tractus-x-umbrella) repository beforehand. Then navigate to the chart directory: @@ -365,16 +225,6 @@ helm dependency update ##### Option 1 -Install your chosen components by having them enabled in a `your-values.yaml` file: - -```bash -helm install -f your-values.yaml umbrella . --namespace umbrella --create-namespace -``` - -> In general, all your specific configuration and secret values should be set by installing with an own values file. - -##### Option 2 - Choose to install one of the predefined subsets (currently in focus of the **E2E Adopter Journey**): ###### Data Exchange Subset @@ -402,6 +252,17 @@ helm upgrade -f values-adopter-data-exchange.yaml umbrella . --namespace umbrell helm install -f values-adopter-portal.yaml umbrella . --namespace umbrella --create-namespace ``` +##### Option 2 + +Install your chosen components by having them enabled in a `your-values.yaml` file: + +```bash +helm install -f your-values.yaml umbrella . --namespace umbrella --create-namespace +``` + +> In general, all your specific configuration and secret values should be set by installing with an own values file. + + #### Get to know the Portal Perform first login and send out an invitation to a company to join the network (SMTP account required to be configured in custom values.yaml file). @@ -445,17 +306,17 @@ tractusx-umbr3lla! The relevant hosts are the following: -- -- -- -- +- +- +- +- In case that you have TLS enabled (see [Self-signed TLS setup (Optional)](#self-signed-tls-setup-optional)), make sure to accept the risk of the self-signed certificates for all the hosts before performing the first login: -- -- -- -- +- +- +- +- ### Uninstall Helm Charts @@ -475,23 +336,29 @@ If persistance for one or more components is enabled, the persistent volume clai Currently enabled ingresses: -- [centralidp.arena.test/auth](http://centralidp.arena.test/auth/) -- [sharedidp.arena.test/auth](http://sharedidp.arena.test/auth/) -- [portal-backend.arena.test](http://portal-backend.arena.test) - - [portal-backend.arena.test/api/administration/swagger/index.html](http://portal-backend.arena.test/api/administration/swagger/index.html) - - [portal-backend.arena.test/api/registration/swagger/index.html](http://portal-backend.arena.test/api/registration/swagger/index.html) - - [portal-backend.arena.test/api/apps/swagger/index.html](http://portal-backend.arena.test/api/apps/swagger/index.html) - - [portal-backend.arena.test/api/services/swagger/index.html](http://portal-backend.arena.test/api/services/swagger/index.html) - - [portal-backend.arena.test/api/notification/swagger/index.html](http://portal-backend.arena.test/api/notification/swagger/index.html) -- [portal.arena.test](http://portal.arena.test) -- [managed-identity-wallets.arena.test/ui/swagger-ui/index.html](http://managed-identity-wallets.arena.test/ui/swagger-ui/index.html) -- [semantics.arena.test/discoveryfinder/swagger-ui/index.html](http://semantics.arena.test/discoveryfinder/swagger-ui/index.html) -- [dataconsumer-1-controlplane.arena.test](http://dataconsumer-1-controlplane.arena.test) -- [dataconsumer-1-dataplane.arena.test](http://dataconsumer-1-dataplane.arena.test) -- [dataprovider-dataplane.arena.test](http://dataprovider-dataplane.arena.test) -- [dataconsumer-2-controlplane.arena.test](http://dataconsumer-2-controlplane.arena.test) -- [dataconsumer-2-dataplane.arena.test](http://dataconsumer-2-dataplane.arena.test) -- [pgadmin4.arena.test](http://pgadmin4.arena.test) +- http://centralidp.tx.test/auth/ +- http://sharedidp.tx.test/auth/ +- http://portal-backend.tx.test + - http://portal-backend.tx.test/api/administration/swagger/index.html + - http://portal-backend.tx.test/api/registration/swagger/index.html + - http://portal-backend.tx.test/api/apps/swagger/index.html + - http://portal-backend.tx.test/api/services/swagger/index.html + - http://portal-backend.tx.test/api/notification/swagger/index.html +- http://portal.tx.test +- http://semantics.tx.test/discoveryfinder/swagger-ui/index.html +- http://ssi-credential-issuer.tx.test/api/issuer/swagger/index.html +- http://dataconsumer-1-controlplane.tx.test +- http://dataconsumer-1-dataplane.tx.test +- http://dataprovider-dataplane.tx.test +- http://dataconsumer-2-controlplane.tx.test +- http://dataconsumer-2-dataplane.tx.test +- http://business-partners.tx.test/pool +- http://business-partners.tx.test/orchestrator +- http://bdrs-server.tx.test +- http://iatpmock.tx.test +- http://pgadmin4.tx.test +- http://ssi-dim-wallet-stub.tx.test +- http://dataprovider-submodelserver.tx.test ### Database Access @@ -499,7 +366,7 @@ This chart also contains a pgadmin4 instance for easy access to the deployed Pos pgadmin4 is by default enabled with in the predefined subsets for data exchange and portal. -Address: [pgadmin4.arena.test](http://pgadmin4.arena.test) +Address: [pgadmin4.tx.test](http://pgadmin4.tx.test) Credentials to login into pgadmin4: @@ -633,8 +500,8 @@ dbpassworddataconsumertwo Access to admin consoles: -- [http://centralidp.arena.test/auth/](http://sharedidp.arena.test/auth/) -- [http://sharedidp.arena.test/auth/](http://sharedidp.arena.test/auth/) +- [http://centralidp.tx.test/auth/](http://sharedidp.tx.test/auth/) +- [http://sharedidp.tx.test/auth/](http://sharedidp.tx.test/auth/) Default username for centralidp and sharedidp: @@ -749,6 +616,7 @@ Build fuseki docker image by following the below steps: This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). - SPDX-License-Identifier: CC-BY-4.0 +- SPDX-FileCopyrightText: 2024 ARENA2036 e.V. - SPDX-FileCopyrightText: 2024 sovity GmbH - SPDX-FileCopyrightText: 2024 SAP SE - SPDX-FileCopyrightText: 2024 msg systems AG From 6a4cdb5794ad0621ed149f51de1d889d7ded6bfd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?David=20G=C3=B6rzig?= <132340784+dvg36@users.noreply.github.com> Date: Wed, 27 Nov 2024 13:33:14 +0100 Subject: [PATCH 02/14] Adapt provide data for community days --- docs/tutorials/e2e/boost/provideData.md | 510 +++++++++++++++--------- 1 file changed, 321 insertions(+), 189 deletions(-) diff --git a/docs/tutorials/e2e/boost/provideData.md b/docs/tutorials/e2e/boost/provideData.md index c5a4c33309d..446796e32d6 100644 --- a/docs/tutorials/e2e/boost/provideData.md +++ b/docs/tutorials/e2e/boost/provideData.md @@ -22,107 +22,61 @@ Alice, as a data consumer, wants to consume data from Bob. Bob, as a data provid Action (Bob): Create this asset using the following `curl` command: ```shell -curl --location 'http://dataprovider-controlplane.tx.test/management/v3/assets' \ ---header 'Content-Type: application/json' \ ---header 'X-Api-Key: TEST2' \ + +curl -L -X POST 'http://dataprovider-controlplane.tx.test/management/v3/assets' \ +-H 'Content-Type: application/json' \ +-H 'X-Api-Key: TEST2' \ --data-raw '{ - "@context": {}, - "@type": "Asset", - "@id": "3", - "properties": { - "description": "Product EDC Demo Asset 3" - }, - "dataAddress": { - "@type": "DataAddress", - "type": "HttpData", - "baseUrl": "https://jsonplaceholder.typicode.com/todos/3" - } -}' | jq + "@context": {}, + "@id": "200", + "properties": { + "description": "Product EDC Demo Asset" + }, + "dataAddress": { + "@type": "DataAddress", + "type": "HttpData", + "baseUrl": "https://jsonplaceholder.typicode.com/todos/3" + } +}'| jq ``` -Just to be sure, that the asset was created succesfully, Bob can check the asset using the following `curl` command: +Just to be sure, that the asset was created succesfully, Bob can check the asset using the following `curl` commands: ```shell -curl -X POST http://dataprovider-controlplane.tx.test/management/v2/assets/request -H "x-api-key: TEST2" -H "content-type: application/json" | jq + +curl -L -X GET 'http://dataprovider-controlplane.tx.test/management/v3/assets/200' \ +-H 'X-Api-Key: TEST2' | jq + +//or the whole catalog + +curl -L -X POST http://dataprovider-controlplane.tx.test/management/v3/assets/request -H "x-api-key: TEST2" -H "content-type: application/json" | jq ``` -The result shows the already existing assets and the newly created asset. +The result for the first command shows just the newly created asset. ```json -[ - { - "@id": "registry-asset", - "@type": "edc:Asset", - "edc:properties": { - "edc:type": "data.core.digitalTwinRegistry", - "edc:description": "Digital Twin Registry Endpoint of IRS DEV", - "edc:id": "registry-asset" - }, - "edc:dataAddress": { - "@type": "edc:DataAddress", - "edc:proxyPath": "true", - "edc:type": "HttpData", - "edc:proxyMethod": "true", - "edc:proxyQueryParams": "true", - "edc:proxyBody": "true", - "edc:baseUrl": "http://umbrella-dataprovider-dtr:8080/api/v3.0" - }, - "@context": { - "dct": "http://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/" - } +{ + "@id": "200", + "@type": "Asset", + "properties": { + "description": "Product EDC Demo Asset", + "id": "200" }, - { - "@id": "urn:uuid:dc641d45-95e7-4284-a472-43f30255d0cb", - "@type": "edc:Asset", - "edc:properties": { - "edc:description": "IRS EDC Test Asset", - "edc:id": "urn:uuid:dc641d45-95e7-4284-a472-43f30255d0cb" - }, - "edc:dataAddress": { - "@type": "edc:DataAddress", - "edc:proxyPath": "true", - "edc:type": "HttpData", - "edc:proxyMethod": "false", - "edc:proxyQueryParams": "false", - "edc:proxyBody": "false", - "edc:baseUrl": "http://umbrella-dataprovider-submodelserver:8080" - }, - "@context": { - "dct": "http://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/" - } + "dataAddress": { + "@type": "DataAddress", + "type": "HttpData", + "baseUrl": "https://jsonplaceholder.typicode.com/todos/3" }, - { - "@id": "3", - "@type": "edc:Asset", - "edc:properties": { - "edc:description": "Product EDC Demo Asset 3", - "edc:id": "3" - }, - "edc:dataAddress": { - "@type": "edc:DataAddress", - "edc:type": "HttpData", - "edc:baseUrl": "https://jsonplaceholder.typicode.com/todos/3" - }, - "@context": { - "dct": "http://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/" - } + "@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/" } -] +} + ``` ## Request catalog @@ -132,21 +86,28 @@ Bob tells Alice, that he created an asset, and she should now be able to request Action (Alice): Execute a request using the following `curl` commands: ```shell -curl --location 'http://dataconsumer-1-controlplane.tx.test/management/v2/catalog/request' \ ---header 'Content-Type: application/json' \ ---header 'X-Api-Key: TEST1' \ + +curl -L -X POST 'http://dataconsumer-1-controlplane.tx.test/management/v2/catalog/request' \ +-H 'Content-Type: application/json' \ +-H 'X-Api-Key: TEST1' \ --data-raw '{ - "@context": {}, - "protocol": "dataspace-protocol-http", - "counterPartyAddress": "http://dataprovider-controlplane.tx.test/api/v1/dsp", - "querySpec": { - "offset": 0, - "limit": 100 - } + "@context": { + "@vocab": "https://w3id.org/edc/v0.0.1/ns/" + }, + "@type": "CatalogRequest", + "counterPartyAddress": "http://dataprovider-controlplane.tx.test/api/v1/dsp", + "counterPartyId": "BPNL00000003AYRE", + "protocol": "dataspace-protocol-http", + "querySpec": { + "offset": 0, + "limit": 50 + } }' | jq + + ``` -The requested catalog looks like this: +The requested catalog might look like this but the content may differ: ```json { @@ -263,10 +224,10 @@ The requested catalog looks like this: ## Create first access policy -Let´s see if Alice can see the Asset (ID: 3). +Let´s see if Alice can see the Asset (ID: 200). :::info -As you can see in the response, the data offer "Product EDC Demo Asset 3" (asset ID: 3) does not appear. Unfortunately, Alice sees some contract offers but she cannot find the contract offer from Bob. +As you can see in the response, the data offer "Product EDC Demo Asset" (asset ID: 200) does not appear. Unfortunately, Alice sees some contract offers but she cannot find the contract offer from Bob. ::: Alice calls Bob and says she can´t see the asset. Bob remembers that he did not create an access policy. An access policy defines who is allowed to see a data offering. @@ -274,17 +235,38 @@ Alice calls Bob and says she can´t see the asset. Bob remembers that he did not Action (Bob): Create the access policy using the following `curl` command: ```shell -curl --location 'http://dataprovider-controlplane.tx.test/management/v2/policydefinitions' \ ---header 'Content-Type: application/json' \ ---header 'X-Api-Key: TEST2' \ + +curl -L -X POST 'http://dataprovider-controlplane.tx.test/management/v2/policydefinitions' \ +-H 'Content-Type: application/json' \ +-H 'X-Api-Key: TEST2' \ --data-raw '{ "@context": { "odrl": "http://www.w3.org/ns/odrl/2/" }, "@type": "PolicyDefinitionRequestDto", - "@id": "3-1", + "@id": "200", "policy": { - "@type": "Policy" + "@type": "odrl:Set", + "odrl:permission": [ + { + "odrl:action": "USE", + "odrl:constraint": { + "@type": "LogicalConstraint", + "odrl:or": [ + { + "@type": "Constraint", + "odrl:leftOperand": { + "@id": "BusinessPartnerNumber" + }, + "odrl:operator": { + "@id": "odrl:eq" + }, + "odrl:rightOperand": "BPNL00000003AZQP" + } + ] + } + } + ] } }' | jq ``` @@ -292,19 +274,21 @@ curl --location 'http://dataprovider-controlplane.tx.test/management/v2/policyde The policy was successfully created, if the response is something like this ```json + { - "@type": "edc:IdResponse", - "@id": "3-1", - "edc:createdAt": 1715627034106, + "@type": "IdResponse", + "@id": "200", + "createdAt": 1732640748595, "@context": { - "dct": "http://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/" } } + ``` ## Request catalog - second try @@ -314,18 +298,24 @@ Now that Bob created an access policy, Alice can once again try to access Bob's Action (Alice): Execute the request again using the following `curl` command: ```shell -curl --location 'http://dataconsumer-1-controlplane.tx.test/management/v2/catalog/request' \ ---header 'Content-Type: application/json' \ ---header 'X-Api-Key: TEST1' \ + +curl -L -X POST 'http://dataconsumer-1-controlplane.tx.test/management/v2/catalog/request' \ +-H 'Content-Type: application/json' \ +-H 'X-Api-Key: TEST1' \ --data-raw '{ - "@context": {}, - "protocol": "dataspace-protocol-http", - "counterPartyAddress": "http://dataprovider-controlplane.tx.test/api/v1/dsp", - "querySpec": { - "offset": 0, - "limit": 100 - } + "@context": { + "@vocab": "https://w3id.org/edc/v0.0.1/ns/" + }, + "@type": "CatalogRequest", + "counterPartyAddress": "http://dataprovider-controlplane.tx.test/api/v1/dsp", + "counterPartyId": "BPNL00000003AYRE", + "protocol": "dataspace-protocol-http", + "querySpec": { + "offset": 0, + "limit": 50 + } }' | jq + ``` ## Create first contract definition @@ -347,61 +337,78 @@ Contract definitions state how assets and policies are linked together. Contract Find additional information on transferring data in the [Developer's Handbook](https://github.com/eclipse-edc/docs/blob/main/developer/handbook.md). -Since an access policy has already been created, a contract policy must be created and linked in a contract definition. +An access policy has already been created and it can also be used as a contract policy. + +Let's check if the policy is created correctly: -Action (BoB): Create the contract policy using the following `curl` command: ```shell -curl --location 'http://dataprovider-controlplane.tx.test/management/v2/policydefinitions' \ ---header 'Content-Type: application/json' \ ---header 'X-Api-Key: TEST2' \ ---data-raw '{ - "@context": { - "odrl": "http://www.w3.org/ns/odrl/2/" - }, - "@type": "PolicyDefinitionRequestDto", - "@id": "3-2", - "policy": { - "@type": "Policy" - } -}' | jq +curl -L -X GET 'http://dataprovider-controlplane.tx.test/management/v2/policydefinitions/200' \ +-H 'X-Api-Key: TEST2' | jq + ``` -And again the policy was successfully created +The policy with ID: 200 was successfully created, if the response is something like this ```json + { - "@type": "edc:IdResponse", - "@id": "3-2", - "edc:createdAt": 1715627218849, + "@id": "200", + "@type": "PolicyDefinition", + "createdAt": 1732640748595, + "policy": { + "@id": "d7f2161b-1670-4461-ab36-e5aeefcab2e9", + "@type": "odrl:Set", + "odrl:permission": { + "odrl:action": { + "@id": "USE" + }, + "odrl:constraint": { + "odrl:or": { + "odrl:leftOperand": { + "@id": "BusinessPartnerNumber" + }, + "odrl:operator": { + "@id": "odrl:eq" + }, + "odrl:rightOperand": "BPNL00000003AZQP" + } + } + }, + "odrl:prohibition": [], + "odrl:obligation": [] + }, "@context": { - "dct": "http://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/" } } + ``` + Action (Bob): Create a contract definition including the asset and the policies you have created. For this, use the following `curl` command: ```shell -curl --location 'http://dataprovider-controlplane.tx.test/management/v2/contractdefinitions' \ ---header 'Content-Type: application/json' \ ---header 'X-Api-Key: TEST2' \ + +curl -L -X POST 'http://dataprovider-controlplane.tx.test/management/v2/contractdefinitions' \ +-H 'Content-Type: application/json' \ +-H 'X-Api-Key: TEST2' \ --data-raw '{ "@context": {}, - "@id": "3", + "@id": "200", "@type": "ContractDefinition", - "accessPolicyId": "3-1", - "contractPolicyId": "3-2", + "accessPolicyId": "200", + "contractPolicyId": "200", "assetsSelector": { "@type": "CriterionDto", "operandLeft": "https://w3id.org/edc/v0.0.1/ns/id", "operator": "=", - "operandRight": "3" + "operandRight": "200" } }' | jq ``` @@ -409,19 +416,21 @@ curl --location 'http://dataprovider-controlplane.tx.test/management/v2/contract As a check, the result should look like this: ```json + { - "@type": "edc:IdResponse", - "@id": "3", - "edc:createdAt": 1715627302307, + "@type": "IdResponse", + "@id": "200", + "createdAt": 1732698850793, "@context": { - "dct": "http://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/" } } + ``` ## Request catalog - third try @@ -430,53 +439,175 @@ Let´s see if Alice can finally see the Asset. Action (Alice): Execute the request again using the following `curl` command: ```shell -curl --location 'http://dataconsumer-1-controlplane.tx.test/management/v2/catalog/request' \ ---header 'Content-Type: application/json' \ ---header 'X-Api-Key: TEST1' \ + +curl -L -X POST 'http://dataconsumer-1-controlplane.tx.test/management/v2/catalog/request' \ +-H 'Content-Type: application/json' \ +-H 'X-Api-Key: TEST1' \ --data-raw '{ - "@context": {}, - "protocol": "dataspace-protocol-http", - "counterPartyAddress": "http://dataprovider-controlplane.tx.test/api/v1/dsp", - "querySpec": { - "offset": 0, - "limit": 100 - } + "@context": { + "@vocab": "https://w3id.org/edc/v0.0.1/ns/" + }, + "@type": "CatalogRequest", + "counterPartyAddress": "http://dataprovider-controlplane.tx.test/api/v1/dsp", + "counterPartyId": "BPNL00000003AYRE", + "protocol": "dataspace-protocol-http", + "querySpec": { + "offset": 0, + "limit": 50 + } }' | jq ``` In the response an additional entry should appear: ```json + + { - "@id": "3", + "@id": "a8bef433-83ac-4fe0-a2c1-3f988dc187d4", + "@type": "dcat:Catalog", + "dspace:participantId": "BPNL00000003AYRE", + "dcat:dataset": [ + { + "@id": "200", "@type": "dcat:Dataset", - "odrl:hasPolicy": { - "@id": "Mw==:Mw==:ZDA5YzE2ZWYtMzkyZC00ODExLWE5NjEtN2U4ZjRhMTU3ZGRh", - "@type": "odrl:Set", - "odrl:permission": [], - "odrl:prohibition": [], - "odrl:obligation": [], - "odrl:target": "3" - }, + "odrl:hasPolicy": [ + { + "@id": "MjAw:MjAw:ODliYzY2OWItYjkyYS00NmU2LWEzYjktNzI1MjdjM2U3MTY0", + "@type": "odrl:Offer", + "odrl:permission": { + "odrl:action": { + "@id": "USE" + }, + "odrl:constraint": { + "odrl:or": { + "odrl:leftOperand": { + "@id": "BusinessPartnerNumber" + }, + "odrl:operator": { + "@id": "odrl:eq" + }, + "odrl:rightOperand": "BPNL00000003AZQP" + } + } + }, + "odrl:prohibition": [], + "odrl:obligation": [] + } + + ], "dcat:distribution": [ { "@type": "dcat:Distribution", "dct:format": { - "@id": "HttpProxy" + "@id": "AzureStorage-PUSH" }, - "dcat:accessService": "49a693e0-835d-457a-99b4-e781f2bd643d" + "dcat:accessService": { + "@id": "cf8a77da-dbe9-4d95-bd15-7a250706511e", + "@type": "dcat:DataService", + "dcat:endpointDescription": "dspace:connector", + "dcat:endpointUrl": "http://dataprovider-controlplane.tx.test/api/v1/dsp", + "dct:terms": "dspace:connector", + "dct:endpointUrl": "http://dataprovider-controlplane.tx.test/api/v1/dsp" + } }, { "@type": "dcat:Distribution", "dct:format": { - "@id": "AmazonS3" + "@id": "HttpData-PULL" }, - "dcat:accessService": "49a693e0-835d-457a-99b4-e781f2bd643d" + "dcat:accessService": { + "@id": "cf8a77da-dbe9-4d95-bd15-7a250706511e", + "@type": "dcat:DataService", + "dcat:endpointDescription": "dspace:connector", + "dcat:endpointUrl": "http://dataprovider-controlplane.tx.test/api/v1/dsp", + "dct:terms": "dspace:connector", + "dct:endpointUrl": "http://dataprovider-controlplane.tx.test/api/v1/dsp" + } + }, + { + "@type": "dcat:Distribution", + "dct:format": { + "@id": "HttpData-PUSH" + }, + "dcat:accessService": { + "@id": "cf8a77da-dbe9-4d95-bd15-7a250706511e", + "@type": "dcat:DataService", + "dcat:endpointDescription": "dspace:connector", + "dcat:endpointUrl": "http://dataprovider-controlplane.tx.test/api/v1/dsp", + "dct:terms": "dspace:connector", + "dct:endpointUrl": "http://dataprovider-controlplane.tx.test/api/v1/dsp" + } + }, + { + "@type": "dcat:Distribution", + "dct:format": { + "@id": "AmazonS3-PULL" + }, + "dcat:accessService": { + "@id": "cf8a77da-dbe9-4d95-bd15-7a250706511e", + "@type": "dcat:DataService", + "dcat:endpointDescription": "dspace:connector", + "dcat:endpointUrl": "http://dataprovider-controlplane.tx.test/api/v1/dsp", + "dct:terms": "dspace:connector", + "dct:endpointUrl": "http://dataprovider-controlplane.tx.test/api/v1/dsp" + } + }, + { + "@type": "dcat:Distribution", + "dct:format": { + "@id": "AmazonS3-PUSH" + }, + "dcat:accessService": { + "@id": "cf8a77da-dbe9-4d95-bd15-7a250706511e", + "@type": "dcat:DataService", + "dcat:endpointDescription": "dspace:connector", + "dcat:endpointUrl": "http://dataprovider-controlplane.tx.test/api/v1/dsp", + "dct:terms": "dspace:connector", + "dct:endpointUrl": "http://dataprovider-controlplane.tx.test/api/v1/dsp" + } + }, + { + "@type": "dcat:Distribution", + "dct:format": { + "@id": "AzureStorage-PULL" + }, + "dcat:accessService": { + "@id": "cf8a77da-dbe9-4d95-bd15-7a250706511e", + "@type": "dcat:DataService", + "dcat:endpointDescription": "dspace:connector", + "dcat:endpointUrl": "http://dataprovider-controlplane.tx.test/api/v1/dsp", + "dct:terms": "dspace:connector", + "dct:endpointUrl": "http://dataprovider-controlplane.tx.test/api/v1/dsp" + } } ], - "edc:description": "Product EDC Demo Asset 3", - "edc:id": "3" + "description": "Product EDC Demo Asset", + "id": "200" } + ], + "dcat:service": { + "@id": "cf8a77da-dbe9-4d95-bd15-7a250706511e", + "@type": "dcat:DataService", + "dcat:endpointDescription": "dspace:connector", + "dcat:endpointUrl": "http://dataprovider-controlplane.tx.test/api/v1/dsp", + "dct:terms": "dspace:connector", + "dct:endpointUrl": "http://dataprovider-controlplane.tx.test/api/v1/dsp" + }, + "participantId": "BPNL00000003AYRE", + "@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/", + "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/" + } +} + ``` :::info @@ -488,6 +619,7 @@ Finally Alice can see the Contract Offer from Bob. Congratulations on yor first This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). - SPDX-License-Identifier: CC-BY-4.0 +- SPDX-FileCopyrightText: 2024 ARENA2036 e.V. - SPDX-FileCopyrightText: 2023 sovity GmbH - SPDX-FileCopyrightText: 2023 SAP SE - SPDX-FileCopyrightText: 2023 msg systems AG From 038c2bc443eca9886d633aa2c760d3ac98ab5e9a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?David=20G=C3=B6rzig?= <132340784+dvg36@users.noreply.github.com> Date: Wed, 27 Nov 2024 14:30:18 +0100 Subject: [PATCH 03/14] adapt consume data for community days --- docs/tutorials/e2e/boost/consumeData.md | 223 +++++++++++++----------- 1 file changed, 122 insertions(+), 101 deletions(-) diff --git a/docs/tutorials/e2e/boost/consumeData.md b/docs/tutorials/e2e/boost/consumeData.md index 7215ee8ef45..339d298759f 100644 --- a/docs/tutorials/e2e/boost/consumeData.md +++ b/docs/tutorials/e2e/boost/consumeData.md @@ -14,55 +14,74 @@ To see Bob's data offerings, Alice must request access to his catalog. The catal So Alice requests Bob's catalog using the following `curl` commands: ```shell -curl --location 'http://dataconsumer-1-controlplane.tx.test/management/v2/catalog/request' \ ---header 'Content-Type: application/json' \ ---header 'X-Api-Key: TEST1' \ + +curl -L -X POST 'http://dataconsumer-1-controlplane.tx.test/management/v2/catalog/request' \ +-H 'Content-Type: application/json' \ +-H 'X-Api-Key: TEST1' \ --data-raw '{ - "@context": {}, - "protocol": "dataspace-protocol-http", - "counterPartyAddress": "http://dataprovider-controlplane.tx.test/api/v1/dsp", - "querySpec": { - "offset": 0, - "limit": 100 - } + "@context": { + "@vocab": "https://w3id.org/edc/v0.0.1/ns/" + }, + "@type": "CatalogRequest", + "counterPartyAddress": "http://dataprovider-controlplane.tx.test/api/v1/dsp", + "counterPartyId": "BPNL00000003AYRE", + "protocol": "dataspace-protocol-http", + "querySpec": { + "offset": 0, + "limit": 50 + } }' | jq ``` -The response shows all available data offerings in Bob's catalog. Bob has already told Alice that he gave the Asset the ID 3, and added a simple description to make it easier for Alice to identify. +The response shows all available data offerings in Bob's catalog. Bob has already told Alice that he gave the Asset the ID 200, and added a simple description to make it easier for Alice to identify. -Alice finds the Asset with the ID 3 and the description "Product EDC Demo Asset 3" in the catalog. Now that she is sure which Asset she wants to consume, she wants to start the data transfer. +Alice finds the Asset with the ID 200 and the description "Product EDC Demo Asset" in the catalog. Now that she is sure which Asset she wants to consume, she wants to start the data transfer. ## Negotiate a contract :::info -Dont forget to change the `offerId`with the one you received in the previous step in your catalog request. +Dont forget to change the `offerId`with the one you received in the previous step in your catalog request. The `offerId` could look like this: "@id": "MjAw:MjAw:ODliYzY2OWItYjkyYS00NmU2LWEzYjktNzI1MjdjM2U3MTY0" ::: But before she can transfer the data, she must negotiate the contract with Bob. To do this, she uses the following `curl` command: ```shell -curl --location 'http://dataconsumer-1-controlplane.tx.test/management/v2/contractnegotiations' \ ---header 'Content-Type: application/json' \ ---header 'X-Api-Key: TEST1' \ + +curl -L -X POST 'http://dataconsumer-1-controlplane.tx.test/management/v2/contractnegotiations' \ +-H 'Content-Type: application/json' \ +-H 'X-Api-Key: TEST1' \ --data-raw '{ - "@context": { - "odrl": "http://www.w3.org/ns/odrl/2/" - }, - "@type": "NegotiationInitiateRequestDto", - "connectorAddress": "http://dataprovider-controlplane.tx.test/api/v1/dsp", - "protocol": "dataspace-protocol-http", - "providerId": "BPNL00000003AYRE", - "offer": { - "offerId": "Mw==:Mw==:NTYzYWRkYTItNmEzMy00YTNhLWFmOTQtYjVjOWM0ZDMyODA1", - "assetId": "3", - "policy": { - "@type": "odrl:Set", - "odrl:permission": [], - "odrl:prohibition": [], - "odrl:obligation": [], - "odrl:target": "3" - } - } + "@context": { + "@vocab": "https://w3id.org/edc/v0.0.1/ns/" + }, + "@type": "NegotiationInitiateRequestDto", + "counterPartyAddress": "http://dataprovider-controlplane.tx.test/api/v1/dsp", + "protocol": "dataspace-protocol-http", + "policy": { + "@context": "http://www.w3.org/ns/odrl.jsonld", + "@type": "odrl:Offer", + // highlight-next-line + "@id": "---Insert offer ID here---", + "assigner": "BPNL00000003AYRE", + "permission": { + "odrl:target": "200", + "odrl:action": { + "odrl:type": "USE" + }, + "odrl:constraint": { + "odrl:or": { + "odrl:leftOperand": "BusinessPartnerNumber", + "odrl:operator": { + "@id": "odrl:eq" + }, + "odrl:rightOperand": "BPNL00000003AZQP" + } + } + }, + "prohibition": [], + "obligation": [], + "target": "200" + } }' | jq ``` @@ -70,34 +89,30 @@ The response should look like this: ```json { - "@type": "edc:IdResponse", - "@id": "65356596-dd7c-4ad4-8fc6-8512be6f0ec2", - "edc:createdAt": 1715669329095, + "@type": "IdResponse", + // highlight-next-line + "@id": "f42396cd-be8d-498b-b74d-8c0ead798ad5", + "createdAt": 1732699413292, "@context": { - "dct": "http://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/" } } + ``` In the response, Alice gets a UUID (attribute is `@id`). This is the ID of the created contract negotiation. Alice can now use this ID to see the current status of the negotiation and - if the negotiation was successful - the ID of the created contract agreement. :::tip -Make sure to replace `` in the URL with the UUID you just received. in the current case the UUID is `65356596-dd7c-4ad4-8fc6-8512be6f0ec2`. So the curl command should look like this: - -```shell -curl --location 'http://dataconsumer-1-controlplane.tx.test/management/v2/contractnegotiations/65356596-dd7c-4ad4-8fc6-8512be6f0ec2' \ ---header 'X-Api-Key: TEST1' | jq -``` - +Make sure to replace `` in the URL with the UUID you just received. in the current case the UUID is `f42396cd-be8d-498b-b74d-8c0ead798ad5`. ::: ```shell -curl --location 'http://dataconsumer-1-controlplane.tx.test/management/v2/contractnegotiations/' \ +curl -L -X GET 'http://dataconsumer-1-controlplane.tx.test/management/v2/contractnegotiations/' \ --header 'X-Api-Key: TEST1' | jq ``` @@ -105,33 +120,35 @@ curl --location 'http://dataconsumer-1-controlplane.tx.test/management/v2/contra - If the negotiation was **unsuccessful**, the negotiation state (`edc:state`) will be `TERMINATED` and no contract agreement ID will be present. ```json + { - "@type": "edc:ContractNegotiation", - "@id": "65356596-dd7c-4ad4-8fc6-8512be6f0ec2", - "edc:type": "CONSUMER", - "edc:protocol": "dataspace-protocol-http", - "edc:state": "FINALIZED", - "edc:counterPartyId": "BPNL00000003AYRE", - "edc:counterPartyAddress": "http://dataprovider-controlplane.tx.test/api/v1/dsp", - "edc:callbackAddresses": [], - "edc:createdAt": 1715669329095, - "edc:contractAgreementId": "Mw==:Mw==:N2RhZGI3OGMtYzUxNC00OTkzLWI3MzktNDE3YmJhMDNkMDU4", + "@type": "ContractNegotiation", + "@id": "f42396cd-be8d-498b-b74d-8c0ead798ad5", + "type": "CONSUMER", + "protocol": "dataspace-protocol-http", + "state": "FINALIZED", + "counterPartyId": "BPNL00000003AYRE", + "counterPartyAddress": "http://dataprovider-controlplane.tx.test/api/v1/dsp", + "callbackAddresses": [], + "createdAt": 1732699413292, + "contractAgreementId": "76e8435b-ddb9-4005-a6b1-4b6cfdd17306", "@context": { - "dct": "http://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/" } } + ``` Alice now has a contract with Bob and can begin transferring the asset's data. ## Starting the data transfer -Alice wants to send the data to her backend application (""). So she uses the following command to direct the data from Asset 3 to her desired data sink. +Alice wants to send the data to her backend application (""). So she uses the following command to direct the data from Asset 200 to her desired data sink. :::warning @@ -143,47 +160,55 @@ Replace `` with the contract agreement ID you received in t ::: ```shell -curl --location 'http://dataconsumer-1-controlplane.tx.test/management/v2/transferprocesses' \ ---header 'Content-Type: application/json' \ ---header 'X-Api-Key: TEST1' \ + +curl -L -X POST 'http://dataconsumer-1-controlplane.tx.test/management/v2/transferprocesses' \ +-H 'Content-Type: application/json' \ +-H 'X-Api-Key: TEST1' \ --data-raw '{ - "@context": { - "odrl": "http://www.w3.org/ns/odrl/2/" - }, - "assetId": "3", - "connectorAddress": "http://dataprovider-controlplane.tx.test/api/v1/dsp", - "connectorId": "BPNL00000003AYRE", - "contractId": "", - "dataDestination": { - "type": "HttpProxy" - }, - "privateProperties": { + "@context": { + "@vocab": "https://w3id.org/edc/v0.0.1/ns/" + }, + "@type": "TransferRequest", + "protocol": "dataspace-protocol-http", + "counterPartyAddress": "http://dataprovider-controlplane.tx.test/api/v1/dsp", + // highlight-next-line + "contractId": "", + "assetId": "200", + "transferType": "HttpData-PULL", + "dataDestination": { + "type": "HttpProxy" + }, + "connectorId": "BPNL00000003AZQP", + "privateProperties": { "receiverHttpEndpoint": "" }, - "protocol": "dataspace-protocol-http", - "transferType": { - "contentType": "application/octet-stream", - "isFinite": true + "callbackAddresses": [ + { + "transactional": true, + "uri": "http://dataprovider-submodelserver.tx.test/api/v1/transfers" } + ] }' | jq + ``` The response in this case looks like this: ```json { - "@type": "edc:IdResponse", - "@id": "9d6a0507-25f5-4a81-8885-a47bc3809451", - "edc:createdAt": 1715669899367, + "@type": "IdResponse", + // highlight-next-line + "@id": "e547fbfc-8229-4366-9039-125a82b0ea43", + "createdAt": 1732713519152, "@context": { - "dct": "http://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/" } -} + ``` Just to make sure everything worked, Alice uses another `curl` command to check if the transfer was successful. @@ -191,18 +216,14 @@ Just to make sure everything worked, Alice uses another `curl` command to check In the response, Alice gets a UUID. This is the ID of the created transfer. Alice can now use this ID to see the current status of the transfer. :::tip -Make sure to replace `` in the URL with the UUID you just received. In our case, the UUID is `9d6a0507-25f5-4a81-8885-a47bc3809451`. So the curl command should look like this: +Make sure to replace `` in the URL with the UUID you just received. In our case, the UUID is `e547fbfc-8229-4366-9039-125a82b0ea43`. +::: ```shell -curl --location 'http://dataconsumer-1-controlplane.tx.test/management/v2/transferprocesses/9d6a0507-25f5-4a81-8885-a47bc3809451' \ ---header 'X-Api-Key: TEST1' | jq -``` -::: +curl -L -X GET 'http://dataconsumer-1-controlplane.tx.test/management/v2/transferprocesses/{{transfer_id}}' \ +-H 'X-Api-Key: TEST1' -```shell -curl --location 'http://dataconsumer-1-controlplane.tx.test/management/v2/transferprocesses/' \ ---header 'X-Api-Key: TEST1' | jq ``` - If the transfer was **successful**, Alice will see an ouput as shown below. From ccddb61ba033fa6902a9710a3ad0d02b5fb62e16 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?David=20G=C3=B6rzig?= <132340784+dvg36@users.noreply.github.com> Date: Wed, 27 Nov 2024 14:59:16 +0100 Subject: [PATCH 04/14] adapt deploy components for community days --- docs/tutorials/e2e/connect/deployComponents.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/tutorials/e2e/connect/deployComponents.md b/docs/tutorials/e2e/connect/deployComponents.md index ed1d8d28502..8547ccdb0d2 100644 --- a/docs/tutorials/e2e/connect/deployComponents.md +++ b/docs/tutorials/e2e/connect/deployComponents.md @@ -207,6 +207,7 @@ cd charts/umbrella/ Download the chart dependencies: ```bash +helm dependency update ../tx-data-provider helm dependency update ``` @@ -227,6 +228,12 @@ helm dependency update Choose to install one of the predefined subsets (currently in focus of the **E2E Adopter Journey**): +:::note + +This will take a while. So please be patient. + +::: + ###### Data Exchange Subset ```bash From 5671e7f5e960bf69b1c5ceed91540398d7d5b7b7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?David=20G=C3=B6rzig?= <132340784+dvg36@users.noreply.github.com> Date: Wed, 27 Nov 2024 15:24:23 +0100 Subject: [PATCH 05/14] adapt consumeData for comunity days --- docs/tutorials/e2e/boost/provideData.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/tutorials/e2e/boost/provideData.md b/docs/tutorials/e2e/boost/provideData.md index 446796e32d6..87c2e025d40 100644 --- a/docs/tutorials/e2e/boost/provideData.md +++ b/docs/tutorials/e2e/boost/provideData.md @@ -44,10 +44,12 @@ Just to be sure, that the asset was created succesfully, Bob can check the asset ```shell +// get your asset by ID + curl -L -X GET 'http://dataprovider-controlplane.tx.test/management/v3/assets/200' \ -H 'X-Api-Key: TEST2' | jq -//or the whole catalog +// or get the whole catalog curl -L -X POST http://dataprovider-controlplane.tx.test/management/v3/assets/request -H "x-api-key: TEST2" -H "content-type: application/json" | jq ``` From 33e0d4c641eb96925e92ea4a92b1a28d1a0422a6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?David=20G=C3=B6rzig?= <132340784+dvg36@users.noreply.github.com> Date: Wed, 27 Nov 2024 18:05:10 +0100 Subject: [PATCH 06/14] add edr request --- docs/tutorials/e2e/boost/consumeData.md | 218 +++++++++++++++++++++++- 1 file changed, 217 insertions(+), 1 deletion(-) diff --git a/docs/tutorials/e2e/boost/consumeData.md b/docs/tutorials/e2e/boost/consumeData.md index 339d298759f..a14c5baafe3 100644 --- a/docs/tutorials/e2e/boost/consumeData.md +++ b/docs/tutorials/e2e/boost/consumeData.md @@ -33,6 +33,10 @@ curl -L -X POST 'http://dataconsumer-1-controlplane.tx.test/management/v2/catalo }' | jq ``` + +Ab hier überflüssig bis siehen unten + + The response shows all available data offerings in Bob's catalog. Bob has already told Alice that he gave the Asset the ID 200, and added a simple description to make it easier for Alice to identify. Alice finds the Asset with the ID 200 and the description "Product EDC Demo Asset" in the catalog. Now that she is sure which Asset she wants to consume, she wants to start the data transfer. @@ -222,7 +226,7 @@ Make sure to replace `` in the URL with the UUID you just received. In our c ```shell curl -L -X GET 'http://dataconsumer-1-controlplane.tx.test/management/v2/transferprocesses/{{transfer_id}}' \ --H 'X-Api-Key: TEST1' +-H 'X-Api-Key: TEST1' | jq ``` @@ -320,3 +324,215 @@ This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses - SPDX-FileCopyrightText: 2023 msg systems AG - SPDX-FileCopyrightText: 2023 Materna Information & Communications SE - Source URL: [https://github.com/eclipse-tractusx/eclipse-tractusx.github.io](https://github.com/eclipse-tractusx/eclipse-tractusx.github.io) + + + + + + +Hier gehts los + + + +Erster Schritt ist Catalog request. + + +RESPONSE +... + + { + "@id": "200", + "@type": "dcat:Dataset", + "odrl:hasPolicy": { + "@id": "MjAw:MjAw:Y2ZjMzdlNmUtODAwNi00NGJjLWJhMWYtNjJkOWIzZWM0ZTQ3", + "@type": "odrl:Offer", + "odrl:permission": { + "odrl:action": { + "odrl:type": "USE" + }, + "odrl:constraint": { + "odrl:or": { + "odrl:leftOperand": "BusinessPartnerNumber", + "odrl:operator": { + "@id": "odrl:eq" + }, + "odrl:rightOperand": "BPNL00000003AZQP" + } + } + }, +... + + + +Von da bekommen wir Policy offer ID. +Dann Initiate EDR +Am besten alles unter taget: 200 komplett aus Catalog response kopieren + + + +curl -L -X POST 'http://dataconsumer-1-controlplane.tx.test/management/v2/edrs' \ + -H 'Content-Type: application/json' \ + -H 'X-Api-Key: TEST1' \ + --data-raw '{ + "@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": "ContractRequest", + "counterPartyAddress": "http://dataprovider-controlplane.tx.test/api/v1/dsp", + "protocol": "dataspace-protocol-http", + "policy": { + "assigner": "BPNL00000003AYRE", + "target": "200", + + "@id": "MjAw:MjAw:Y2ZjMzdlNmUtODAwNi00NGJjLWJhMWYtNjJkOWIzZWM0ZTQ3", + "@type": "odrl:Offer", + "odrl:permission": { + "odrl:action": { + "odrl:type": "USE" + }, + "odrl:constraint": { + "odrl:or": { + "odrl:leftOperand": "BusinessPartnerNumber", + "odrl:operator": { + "@id": "odrl:eq" + }, + "odrl:rightOperand": "BPNL00000003AZQP" + } + } + }, + "odrl:prohibition": [], + "odrl:obligation": [] + + }, + "callbackAddresses": [] +}' | jq + + + +RESPONSE + +{ + "@type": "IdResponse", + "@id": "4b260501-ae2f-46f4-9efc-01ba5a0b3d96", + "createdAt": 1732726185609, + "@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/" + } +} + + + + + + +Query EDRs Cashed +Aus der response die contract negotiation ID in operandRight kopieren + + + +curl -L -X POST 'http://dataconsumer-1-controlplane.tx.test/management/v2/edrs/request' \ + -H 'Content-Type: application/json' \ + -H 'X-Api-Key: TEST1' \ + --data-raw '{ + "@context": [ + { + "@vocab": "https://w3id.org/edc/v0.0.1/ns/" + } + ], + "@type": "QuerySpec", + "filterExpression": [ + { + "operandLeft": "contractNegotiationId", + "operator": "=", + "operandRight": "4b260501-ae2f-46f4-9efc-01ba5a0b3d96" + } + ] +}' | jq + + +RESPONSE + + { + "@id": "bdd4af10-9e4a-4796-b4b7-7ecdf91a533a", + "@type": "EndpointDataReferenceEntry", + "providerId": "BPNL00000003AYRE", + "assetId": "200", + "agreementId": "2ece6f45-ff09-4417-b5a9-a92a1849f1d0", + "transferProcessId": "bdd4af10-9e4a-4796-b4b7-7ecdf91a533a", + "createdAt": 1732726189831, + "contractNegotiationId": "4b260501-ae2f-46f4-9efc-01ba5a0b3d96", + "@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/" + } + } + + + + + +Get Auth Code: Aus response die Transfer-Process ID kopieren und hinter EDRS in URL einfügen + + +curl -L -X GET 'http://dataconsumer-1-controlplane.tx.test/management/v2/edrs/bdd4af10-9e4a-4796-b4b7-7ecdf91a533a/dataaddress?auto_refresh=true' \ + -H 'Content-Type: application/json' \ + -H 'X-Api-Key: TEST1' | jq + + +RESPONSE: + +{ + "@type": "DataAddress", + "endpointType": "https://w3id.org/idsa/v4.1/HTTP", + "tx-auth:refreshEndpoint": "http://dataprovider-dataplane.tx.test/api/public/token", + "tx-auth:audience": "did:web:ssi-dim-wallet-stub.tx.test:BPNL00000003AZQP", + "type": "https://w3id.org/idsa/v4.1/HTTP", + "endpoint": "http://dataprovider-dataplane.tx.test/api/public", + "tx-auth:refreshToken": "eyJraWQiOiJ0b2tlblNpZ25lclB1YmxpY0tleSIsImFsZyI6IlJTMjU2In0.eyJleHAiOjE3MzI3MjY0ODksImlhdCI6MTczMjcyNjE4OSwianRpIjoiODA2OTAwYmQtNGY4MS00MzhmLTgyMjYtZDc2ZjkzMmY2MjI1In0.JpTIrOJv609vX86i-y-O8sQcKoTJcWvipC6jyBgWqcEIMWm4dmm4T72z-Z68l1X7QnVq1Ak8JB-fA05ONNL1JjU0W7j6rJK01M2Xo641RpecimxuFhlnld55CPks2wRbbbzHADn8kpqRf2dtNrnsiuRsnzAi6KAkFAEHLB7eLjceNbkk6df3hJrLfnn0DZ6M-OR0O05SgtEyHFsyMpf4OALQwVREIkC7LBTWn7nYCpmzK4ilrL3eM5ZRrbweQ96Tbwi-rfPfp-ptnelO_GGnqzyQef2DN5Eg4P5QZV4QX62Bw0eoYVncgCP6ZKibymnlASG0xHwgEJitu3ZSxBXt-w", + "tx-auth:expiresIn": "300", + "authorization": "eyJraWQiOiJ0b2tlblNpZ25lclB1YmxpY0tleSIsImFsZyI6IlJTMjU2In0.eyJpc3MiOiJCUE5MMDAwMDAwMDNBWVJFIiwiYXVkIjoiQlBOTDAwMDAwMDAzQVpRUCIsInN1YiI6IkJQTkwwMDAwMDAwM0FZUkUiLCJleHAiOjE3MzI3MjY0ODksImlhdCI6MTczMjcyNjE4OSwianRpIjoiODRkZDIxOGItMzk1ZC00YmExLTg2OWUtOWYzMjI3ZWM0NWFlIn0.jTKEv8Fh75W1JOwrFUo1wyLdUOyBn3g500dWNUbaEC_bgASPImXfXnY3rhIVr_hrFY-anJIB_a6SkpTWb7lycCh2dcMaOmUVgmdKTcEvTr2blAXD_WUZTQYxHDVsMuPXDbX-30tYM4KVPOyemfe7IreB38n104j_SLo2Dr1BrbN9xU7mUm6DeKv1oi0TFRxnmhwnRx4hK1eBYIO-FuA9h1RDvfLWXW5yF55KkkrRTjX2HKqVPAtHInMZBRDhqB298N_VLpwQMtg9nkElzNWIUqEV4zQ1YLSsGNLSxog7JwuL3Tvy1VCOkzDkr6K89Z4IWEF0GzPjXO6Z-li_Vv7DVw", + "tx-auth:refreshAudience": "did:web:ssi-dim-wallet-stub.tx.test:BPNL00000003AZQP", + "@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/" + } +} + + + +Get Data: +Aus vorheriger response: den Endpoint kopieren und die Autorization (Token) kopieren und einfügen + + + +curl -L -X GET 'http://dataprovider-dataplane.tx.test/api/public' \ + -H 'Authorization: eyJraWQiOiJ0b2tlblNpZ25lclB1YmxpY0tleSIsImFsZyI6IlJTMjU2In0.eyJpc3MiOiJCUE5MMDAwMDAwMDNBWVJFIiwiYXVkIjoiQlBOTDAwMDAwMDAzQVpRUCIsInN1YiI6IkJQTkwwMDAwMDAwM0FZUkUiLCJleHAiOjE3MzI3MjY0ODksImlhdCI6MTczMjcyNjE4OSwianRpIjoiODRkZDIxOGItMzk1ZC00YmExLTg2OWUtOWYzMjI3ZWM0NWFlIn0.jTKEv8Fh75W1JOwrFUo1wyLdUOyBn3g500dWNUbaEC_bgASPImXfXnY3rhIVr_hrFY-anJIB_a6SkpTWb7lycCh2dcMaOmUVgmdKTcEvTr2blAXD_WUZTQYxHDVsMuPXDbX-30tYM4KVPOyemfe7IreB38n104j_SLo2Dr1BrbN9xU7mUm6DeKv1oi0TFRxnmhwnRx4hK1eBYIO-FuA9h1RDvfLWXW5yF55KkkrRTjX2HKqVPAtHInMZBRDhqB298N_VLpwQMtg9nkElzNWIUqEV4zQ1YLSsGNLSxog7JwuL3Tvy1VCOkzDkr6K89Z4IWEF0GzPjXO6Z-li_Vv7DVw' + + +RESPONSE: + + { + "userId": 1, + "id": 3, + "title": "fugiat veniam minus", + "completed": false +} + + From bbe5afc8a3b6ff59881792f3503e5ee760d0d3b7 Mon Sep 17 00:00:00 2001 From: Stephan Bauer Date: Wed, 27 Nov 2024 22:36:16 +0100 Subject: [PATCH 07/14] adapt tutorial formatting and add structure --- docs/tutorials/e2e/boost/boost.md | 14 + docs/tutorials/e2e/boost/consumeData.md | 553 ++++++------------------ docs/tutorials/e2e/boost/provideData.md | 369 +++++++++------- 3 files changed, 343 insertions(+), 593 deletions(-) diff --git a/docs/tutorials/e2e/boost/boost.md b/docs/tutorials/e2e/boost/boost.md index bc0e2475113..c80b6527217 100644 --- a/docs/tutorials/e2e/boost/boost.md +++ b/docs/tutorials/e2e/boost/boost.md @@ -5,6 +5,20 @@ sidebar_position: 5 In the `Boost Chapter`, you will configure and register your components so that they are discoverable in your local data space deployment. You will then take on the role of a data provider, build your first data pipeline, add your first `assets`, `policies` and create a `contract offer` in the EDC. As a data consumer you will discover the data that you have previously created and initiate a data transfer. After completing this step, you have all the foundational knowledge you need to get started with active participation in a use-case. +In this **Boost Chapter**, you will create and request different assets and learn how the management-api works. The following steps will guide you through the process: + +1. **Data Provider Role**: + +- Build your first data pipeline. +- Add your first `assets`, `policies`, and create a `contract offer`. + +2. **Data Consumer Role**: + +- Discover the data you previously created. +- Initiate a data transfer. + +By the end of this chapter, you will have the foundational knowledge needed to share data within your data space. + ## Notice This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). diff --git a/docs/tutorials/e2e/boost/consumeData.md b/docs/tutorials/e2e/boost/consumeData.md index a14c5baafe3..7481aa91d78 100644 --- a/docs/tutorials/e2e/boost/consumeData.md +++ b/docs/tutorials/e2e/boost/consumeData.md @@ -7,416 +7,97 @@ This step continues the journey of our data consumer Alice. After the data provi We will use plain CLI tools (`curl`) for this, but feel free to use graphical tools such as Postman or Insomnia. -## Request the catalog +## Step 1: Request the catalog To see Bob's data offerings, Alice must request access to his catalog. The catalog shows all the assets that Alice can consume from Bob. -So Alice requests Bob's catalog using the following `curl` commands: +### Catalog request (Alice) ```shell - curl -L -X POST 'http://dataconsumer-1-controlplane.tx.test/management/v2/catalog/request' \ --H 'Content-Type: application/json' \ --H 'X-Api-Key: TEST1' \ ---data-raw '{ - "@context": { - "@vocab": "https://w3id.org/edc/v0.0.1/ns/" - }, - "@type": "CatalogRequest", - "counterPartyAddress": "http://dataprovider-controlplane.tx.test/api/v1/dsp", - "counterPartyId": "BPNL00000003AYRE", - "protocol": "dataspace-protocol-http", - "querySpec": { - "offset": 0, - "limit": 50 - } -}' | jq -``` - - -Ab hier überflüssig bis siehen unten - - -The response shows all available data offerings in Bob's catalog. Bob has already told Alice that he gave the Asset the ID 200, and added a simple description to make it easier for Alice to identify. - -Alice finds the Asset with the ID 200 and the description "Product EDC Demo Asset" in the catalog. Now that she is sure which Asset she wants to consume, she wants to start the data transfer. - -## Negotiate a contract - -:::info -Dont forget to change the `offerId`with the one you received in the previous step in your catalog request. The `offerId` could look like this: "@id": "MjAw:MjAw:ODliYzY2OWItYjkyYS00NmU2LWEzYjktNzI1MjdjM2U3MTY0" -::: - -But before she can transfer the data, she must negotiate the contract with Bob. To do this, she uses the following `curl` command: - -```shell - -curl -L -X POST 'http://dataconsumer-1-controlplane.tx.test/management/v2/contractnegotiations' \ --H 'Content-Type: application/json' \ --H 'X-Api-Key: TEST1' \ ---data-raw '{ - "@context": { - "@vocab": "https://w3id.org/edc/v0.0.1/ns/" - }, - "@type": "NegotiationInitiateRequestDto", - "counterPartyAddress": "http://dataprovider-controlplane.tx.test/api/v1/dsp", - "protocol": "dataspace-protocol-http", - "policy": { - "@context": "http://www.w3.org/ns/odrl.jsonld", - "@type": "odrl:Offer", - // highlight-next-line - "@id": "---Insert offer ID here---", - "assigner": "BPNL00000003AYRE", - "permission": { - "odrl:target": "200", - "odrl:action": { - "odrl:type": "USE" - }, - "odrl:constraint": { - "odrl:or": { - "odrl:leftOperand": "BusinessPartnerNumber", - "odrl:operator": { - "@id": "odrl:eq" - }, - "odrl:rightOperand": "BPNL00000003AZQP" - } - } - }, - "prohibition": [], - "obligation": [], - "target": "200" - } -}' | jq -``` - -The response should look like this: - -```json -{ - "@type": "IdResponse", - // highlight-next-line - "@id": "f42396cd-be8d-498b-b74d-8c0ead798ad5", - "createdAt": 1732699413292, - "@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/" - } -} - -``` - -In the response, Alice gets a UUID (attribute is `@id`). This is the ID of the created contract negotiation. Alice can now use this ID to see the current status of the negotiation and - if the negotiation was successful - the ID of the created contract agreement. - -:::tip -Make sure to replace `` in the URL with the UUID you just received. in the current case the UUID is `f42396cd-be8d-498b-b74d-8c0ead798ad5`. -::: - -```shell -curl -L -X GET 'http://dataconsumer-1-controlplane.tx.test/management/v2/contractnegotiations/' \ ---header 'X-Api-Key: TEST1' | jq -``` - -- If the negotiation was **successful**, Alice will see an ouput as shown below. -- If the negotiation was **unsuccessful**, the negotiation state (`edc:state`) will be `TERMINATED` and no contract agreement ID will be present. - -```json - -{ - "@type": "ContractNegotiation", - "@id": "f42396cd-be8d-498b-b74d-8c0ead798ad5", - "type": "CONSUMER", - "protocol": "dataspace-protocol-http", - "state": "FINALIZED", - "counterPartyId": "BPNL00000003AYRE", - "counterPartyAddress": "http://dataprovider-controlplane.tx.test/api/v1/dsp", - "callbackAddresses": [], - "createdAt": 1732699413292, - "contractAgreementId": "76e8435b-ddb9-4005-a6b1-4b6cfdd17306", - "@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/" - } -} - -``` - -Alice now has a contract with Bob and can begin transferring the asset's data. - -## Starting the data transfer - -Alice wants to send the data to her backend application (""). So she uses the following command to direct the data from Asset 200 to her desired data sink. - -:::warning - -For testing purposes, you should replace `` with your own test API or use [webhook.site](https://webhook.site/) as your backend system. -If you do not change this, you will not be able to view the received token, which is required for requesting the data! -If you are using webhook.site, please make sure that you use "Your unique URL" and that you do not transfer any sensitive information to webhook. - -Replace `` with the contract agreement ID you received in the previous step. -::: - -```shell - -curl -L -X POST 'http://dataconsumer-1-controlplane.tx.test/management/v2/transferprocesses' \ --H 'Content-Type: application/json' \ --H 'X-Api-Key: TEST1' \ ---data-raw '{ - "@context": { - "@vocab": "https://w3id.org/edc/v0.0.1/ns/" - }, - "@type": "TransferRequest", - "protocol": "dataspace-protocol-http", - "counterPartyAddress": "http://dataprovider-controlplane.tx.test/api/v1/dsp", - // highlight-next-line - "contractId": "", - "assetId": "200", - "transferType": "HttpData-PULL", - "dataDestination": { - "type": "HttpProxy" - }, - "connectorId": "BPNL00000003AZQP", - "privateProperties": { - "receiverHttpEndpoint": "" + -H 'Content-Type: application/json' \ + -H 'X-Api-Key: TEST1' \ + --data-raw '{ + "@context": { + "@vocab": "https://w3id.org/edc/v0.0.1/ns/" }, - "callbackAddresses": [ - { - "transactional": true, - "uri": "http://dataprovider-submodelserver.tx.test/api/v1/transfers" + "@type": "CatalogRequest", + "counterPartyAddress": "http://dataprovider-controlplane.tx.test/api/v1/dsp", + "counterPartyId": "BPNL00000003AYRE", + "protocol": "dataspace-protocol-http", + "querySpec": { + "offset": 0, + "limit": 50 } - ] -}' | jq - + }' | jq ``` -The response in this case looks like this: +### Catalog response -```json -{ - "@type": "IdResponse", - // highlight-next-line - "@id": "e547fbfc-8229-4366-9039-125a82b0ea43", - "createdAt": 1732713519152, - "@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/" - } - -``` - -Just to make sure everything worked, Alice uses another `curl` command to check if the transfer was successful. - -In the response, Alice gets a UUID. This is the ID of the created transfer. Alice can now use this ID to see the current status of the transfer. - -:::tip -Make sure to replace `` in the URL with the UUID you just received. In our case, the UUID is `e547fbfc-8229-4366-9039-125a82b0ea43`. -::: - -```shell - -curl -L -X GET 'http://dataconsumer-1-controlplane.tx.test/management/v2/transferprocesses/{{transfer_id}}' \ --H 'X-Api-Key: TEST1' | jq - -``` - -- If the transfer was **successful**, Alice will see an ouput as shown below. -- If the transfer was **unsuccessful**, the transfer state (`edc:state`) will be `TERMINATED`. +The highlighted line represents the offer id, which is important for later steps. ```json { - "@id": "9d6a0507-25f5-4a81-8885-a47bc3809451", - "@type": "edc:TransferProcess", - "edc:correlationId": "9d6a0507-25f5-4a81-8885-a47bc3809451", - "edc:state": "STARTED", - "edc:stateTimestamp": 1715669901450, - "edc:type": "CONSUMER", - "edc:assetId": "3", - "edc:contractId": "Mw==:Mw==:N2RhZGI3OGMtYzUxNC00OTkzLWI3MzktNDE3YmJhMDNkMDU4", - "edc:callbackAddresses": [], - "edc:dataDestination": { - "@type": "edc:DataAddress", - "edc:type": "HttpProxy" - }, - "edc:connectorId": "BPNL00000003AYRE", - "@context": { - "dct": "http://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/" + "@id": "200", + "@type": "dcat:Dataset", + "odrl:hasPolicy": { + // highlight-next-line + "@id": "MjAw:MjAw:Y2ZjMzdlNmUtODAwNi00NGJjLWJhMWYtNjJkOWIzZWM0ZTQ3", + "@type": "odrl:Offer", + "odrl:permission": { + "odrl:action": { + "odrl:type": "USE" + }, + "odrl:constraint": { + "odrl:or": { + "odrl:leftOperand": "BusinessPartnerNumber", + "odrl:operator": { + "@id": "odrl:eq" + }, + "odrl:rightOperand": "BPNL00000003AZQP" + } + } + } } } ``` -The response shows her that she has a `STARTED` transfer with the type `CONSUMER` of the asset with the ID `3`. -Note, that a consumer pull transfer will **not** advance to the `COMPLETED` state, but instead will stay in state `STARTED`. -This means, that Alice can now request the data using the information received by her backend. - -:::info - -If you used webhook.site as your backend system, you can now go to [webhook.site](https://webhook.site/) and see the received token. - -::: - -## Consume the data - -In her backend (as already mentioned [webhook.site](https://webhook.site/)) you will now find the following (as an example) entry - -![Consume data backend](/tutorials/e2e/consume_data_backend.png) - -```json -{ - "id": "9d6a0507-25f5-4a81-8885-a47bc3809451", - "endpoint": "http://dataprovider-dataplane.tx.test/api/public", - "authKey": "Authorization", - "authCode": "eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE3MTU2NzA1MDEsImRhZCI6IjFFQ29ReDRBTy9acmJ6dXEwUlpSY0tYd1hQeW81UmdPZndyRWtIWnpZSStQVGhIUmFuelczeGpXcU5vTzFJa3ZOWUV6SGpEWU5iVEJ5VDgzbzdtVlVsUWZhYUpKSm5CMVJGbFQ1SXM0NHpZQ0RJYWZKNHhmQzZTOFNKaWxjV0x1WURoc24xRjdha2xSZllnemRIMjR3WnJycS9JU0pPZjFzVHNQSHNtcE9PaWZ2S2ZyaElFemtJSEs3OFZUTFBMd0krWmNEK3VZc1FCQkt5NlEvZFBCSkZodWsyMXFiOVU1V3dZWWpPYkZSQjdzUmpZYkNsSlpyaTZzVWFXQU1WOXVsQ2JGS2NPM2xxMERPaWRuQjNqSXJ4blh4Y3JjVHl3MEkzV3JjN2k2ZG1nejlXMTFvYTR5VUpJWU92R1lkdWNXdk1pemk3b01mck5SdXE0SVJ1djR6ai9Cemcxb2NZalB5Y0RvK2I2M0RheWpyWmVNS1c4OGNRUnlvUDdpbExsMVNVVmFlRUxZQ3lieitCYUxpd2x1d0lpcWxFckJrTDNlOXptNGpJYz0iLCJjaWQiOiJNdz09Ok13PT06TjJSaFpHSTNPR010WXpVeE5DMDBPVGt6TFdJM016a3ROREUzWW1KaE1ETmtNRFU0In0.AOt6rXbcK44RD7XNCMN16zjvurzdkMNCki3HkvZ_VJ43eDkCDDbquDSvW0SmEnp9cqhjMbUqnO-iGJheI4TbkIc9dxFouJGtHvKFAjOG7LFSErwvH0yNXus1TPN41BCp_jP1tpH63s3PuRqgdzzn1axkJ57aGo9ibqnKRm7ZhM8pgkReWQpHwlFz3QuOMFWHNmPm_HMePPsUxZM7OpARwgShGMqATHEJmoIff2S1yLLeN0k97JT4BzL7xwM9VB-Yssq1rWxBp3GITcBta5R1EVjzaEZseYn_wxFFmVlXQtu_lkvbgihEsvCgtXI_c-EGZl_gTVe9DMfq4cM2XXfE8A", - "properties": {} -} -``` - -Alice can now request the data using the provided information as follows: +## Step 2: Initiate an edr -```shell -curl -X GET -H ': ' -``` - -:::warning -In this example, we can not use the endpoint URL as is, because we are working with a local Kubernetes cluster and can not use the cluster internal URL. Therefore, we have to use the ingress URL instead. -::: +To consume the data, Alice uses the offer ID from the catalog response (`MjAw:MjAw:Y2ZjMzdlNmUtODAwNi00NGJjLWJhMWYtNjJkOWIzZWM0ZTQ3`) and the target asset ID (`200`) to initiate an EDR. -In this example, this results in the following request: +### EDR request ```shell -curl -X GET -H 'Authorization: eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE3MTU2NzA1MDEsImRhZCI6IjFFQ29ReDRBTy9acmJ6dXEwUlpSY0tYd1hQeW81UmdPZndyRWtIWnpZSStQVGhIUmFuelczeGpXcU5vTzFJa3ZOWUV6SGpEWU5iVEJ5VDgzbzdtVlVsUWZhYUpKSm5CMVJGbFQ1SXM0NHpZQ0RJYWZKNHhmQzZTOFNKaWxjV0x1WURoc24xRjdha2xSZllnemRIMjR3WnJycS9JU0pPZjFzVHNQSHNtcE9PaWZ2S2ZyaElFemtJSEs3OFZUTFBMd0krWmNEK3VZc1FCQkt5NlEvZFBCSkZodWsyMXFiOVU1V3dZWWpPYkZSQjdzUmpZYkNsSlpyaTZzVWFXQU1WOXVsQ2JGS2NPM2xxMERPaWRuQjNqSXJ4blh4Y3JjVHl3MEkzV3JjN2k2ZG1nejlXMTFvYTR5VUpJWU92R1lkdWNXdk1pemk3b01mck5SdXE0SVJ1djR6ai9Cemcxb2NZalB5Y0RvK2I2M0RheWpyWmVNS1c4OGNRUnlvUDdpbExsMVNVVmFlRUxZQ3lieitCYUxpd2x1d0lpcWxFckJrTDNlOXptNGpJYz0iLCJjaWQiOiJNdz09Ok13PT06TjJSaFpHSTNPR010WXpVeE5DMDBPVGt6TFdJM016a3ROREUzWW1KaE1ETmtNRFU0In0.AOt6rXbcK44RD7XNCMN16zjvurzdkMNCki3HkvZ_VJ43eDkCDDbquDSvW0SmEnp9cqhjMbUqnO-iGJheI4TbkIc9dxFouJGtHvKFAjOG7LFSErwvH0yNXus1TPN41BCp_jP1tpH63s3PuRqgdzzn1axkJ57aGo9ibqnKRm7ZhM8pgkReWQpHwlFz3QuOMFWHNmPm_HMePPsUxZM7OpARwgShGMqATHEJmoIff2S1yLLeN0k97JT4BzL7xwM9VB-Yssq1rWxBp3GITcBta5R1EVjzaEZseYn_wxFFmVlXQtu_lkvbgihEsvCgtXI_c-EGZl_gTVe9DMfq4cM2XXfE8A' http://dataprovider-dataplane.tx.test/api/public | jq -``` - -:::info -Currently the response for this curl commoand is - -```json -{ - "userId": 1, - "id": 3, - "title": "fugiat veniam minus", - "completed": false -} -``` - -## Notice - -This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). - -- SPDX-License-Identifier: CC-BY-4.0 -- SPDX-FileCopyrightText: 2023 sovity GmbH -- SPDX-FileCopyrightText: 2023 SAP SE -- SPDX-FileCopyrightText: 2023 msg systems AG -- SPDX-FileCopyrightText: 2023 Materna Information & Communications SE -- Source URL: [https://github.com/eclipse-tractusx/eclipse-tractusx.github.io](https://github.com/eclipse-tractusx/eclipse-tractusx.github.io) - - - - - - -Hier gehts los - - - -Erster Schritt ist Catalog request. - - -RESPONSE -... - - { - "@id": "200", - "@type": "dcat:Dataset", - "odrl:hasPolicy": { - "@id": "MjAw:MjAw:Y2ZjMzdlNmUtODAwNi00NGJjLWJhMWYtNjJkOWIzZWM0ZTQ3", - "@type": "odrl:Offer", - "odrl:permission": { - "odrl:action": { - "odrl:type": "USE" - }, - "odrl:constraint": { - "odrl:or": { - "odrl:leftOperand": "BusinessPartnerNumber", - "odrl:operator": { - "@id": "odrl:eq" - }, - "odrl:rightOperand": "BPNL00000003AZQP" - } - } - }, -... - - - -Von da bekommen wir Policy offer ID. -Dann Initiate EDR -Am besten alles unter taget: 200 komplett aus Catalog response kopieren - - - curl -L -X POST 'http://dataconsumer-1-controlplane.tx.test/management/v2/edrs' \ -H 'Content-Type: application/json' \ -H 'X-Api-Key: TEST1' \ - --data-raw '{ + --data-raw '{ "@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/" - } + "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": "ContractRequest", "counterPartyAddress": "http://dataprovider-controlplane.tx.test/api/v1/dsp", "protocol": "dataspace-protocol-http", "policy": { - "assigner": "BPNL00000003AYRE", - "target": "200", - - "@id": "MjAw:MjAw:Y2ZjMzdlNmUtODAwNi00NGJjLWJhMWYtNjJkOWIzZWM0ZTQ3", - "@type": "odrl:Offer", - "odrl:permission": { - "odrl:action": { - "odrl:type": "USE" - }, - "odrl:constraint": { - "odrl:or": { - "odrl:leftOperand": "BusinessPartnerNumber", - "odrl:operator": { - "@id": "odrl:eq" - }, - "odrl:rightOperand": "BPNL00000003AZQP" - } - } - }, - "odrl:prohibition": [], - "odrl:obligation": [] - + "assigner": "BPNL00000003AYRE", + // highlight-next-line + "target": "200", + // highlight-next-line + "@id": "MjAw:MjAw:Y2ZjMzdlNmUtODAwNi00NGJjLWJhMWYtNjJkOWIzZWM0ZTQ3" }, "callbackAddresses": [] -}' | jq - - + }' | jq +``` -RESPONSE +### EDR response +```json { "@type": "IdResponse", + // highlight-next-line "@id": "4b260501-ae2f-46f4-9efc-01ba5a0b3d96", "createdAt": 1732726185609, "@context": { @@ -428,81 +109,82 @@ RESPONSE "odrl": "http://www.w3.org/ns/odrl/2/" } } +``` +## Step 3: Query cached edrs +Alice now queries cached EDRs using the contract negotiation ID (`4b260501-ae2f-46f4-9efc-01ba5a0b3d96`) from the previous response. +### Query edrs request - - -Query EDRs Cashed -Aus der response die contract negotiation ID in operandRight kopieren - - - -curl -L -X POST 'http://dataconsumer-1-controlplane.tx.test/management/v2/edrs/request' \ +```shell +curl -L -X POST 'http://dataconsumer-1-controlplane.tx.test/management/v2/edrs/request' \ -H 'Content-Type: application/json' \ -H 'X-Api-Key: TEST1' \ --data-raw '{ - "@context": [ - { - "@vocab": "https://w3id.org/edc/v0.0.1/ns/" - } - ], + "@context": { "@vocab": "https://w3id.org/edc/v0.0.1/ns/" }, "@type": "QuerySpec", "filterExpression": [ - { - "operandLeft": "contractNegotiationId", - "operator": "=", - "operandRight": "4b260501-ae2f-46f4-9efc-01ba5a0b3d96" - } + { + "operandLeft": "contractNegotiationId", + "operator": "=", + // highlight-next-line + "operandRight": "4b260501-ae2f-46f4-9efc-01ba5a0b3d96" + } ] -}' | jq - + }' | jq +``` -RESPONSE +### Query edrs response - { - "@id": "bdd4af10-9e4a-4796-b4b7-7ecdf91a533a", - "@type": "EndpointDataReferenceEntry", - "providerId": "BPNL00000003AYRE", - "assetId": "200", - "agreementId": "2ece6f45-ff09-4417-b5a9-a92a1849f1d0", - "transferProcessId": "bdd4af10-9e4a-4796-b4b7-7ecdf91a533a", - "createdAt": 1732726189831, - "contractNegotiationId": "4b260501-ae2f-46f4-9efc-01ba5a0b3d96", - "@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/" - } +```json +{ + "@id": "bdd4af10-9e4a-4796-b4b7-7ecdf91a533a", + "@type": "EndpointDataReferenceEntry", + "providerId": "BPNL00000003AYRE", + "assetId": "200", + "agreementId": "2ece6f45-ff09-4417-b5a9-a92a1849f1d0", + // highlight-next-line + "transferProcessId": "bdd4af10-9e4a-4796-b4b7-7ecdf91a533a", + "createdAt": 1732726189831, + "contractNegotiationId": "4b260501-ae2f-46f4-9efc-01ba5a0b3d96", + "@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/" } +} +``` +## Step 4: Get authorization details +Alice uses the transfer process ID (`bdd4af10-9e4a-4796-b4b7-7ecdf91a533a`) to get authorization details. +### Authorization request - -Get Auth Code: Aus response die Transfer-Process ID kopieren und hinter EDRS in URL einfügen - - +```bash curl -L -X GET 'http://dataconsumer-1-controlplane.tx.test/management/v2/edrs/bdd4af10-9e4a-4796-b4b7-7ecdf91a533a/dataaddress?auto_refresh=true' \ -H 'Content-Type: application/json' \ - -H 'X-Api-Key: TEST1' | jq - + -H 'X-Api-Key: TEST1' | jq +``` -RESPONSE: +### Authorization response +```json { "@type": "DataAddress", "endpointType": "https://w3id.org/idsa/v4.1/HTTP", "tx-auth:refreshEndpoint": "http://dataprovider-dataplane.tx.test/api/public/token", "tx-auth:audience": "did:web:ssi-dim-wallet-stub.tx.test:BPNL00000003AZQP", "type": "https://w3id.org/idsa/v4.1/HTTP", + // highlight-next-line "endpoint": "http://dataprovider-dataplane.tx.test/api/public", "tx-auth:refreshToken": "eyJraWQiOiJ0b2tlblNpZ25lclB1YmxpY0tleSIsImFsZyI6IlJTMjU2In0.eyJleHAiOjE3MzI3MjY0ODksImlhdCI6MTczMjcyNjE4OSwianRpIjoiODA2OTAwYmQtNGY4MS00MzhmLTgyMjYtZDc2ZjkzMmY2MjI1In0.JpTIrOJv609vX86i-y-O8sQcKoTJcWvipC6jyBgWqcEIMWm4dmm4T72z-Z68l1X7QnVq1Ak8JB-fA05ONNL1JjU0W7j6rJK01M2Xo641RpecimxuFhlnld55CPks2wRbbbzHADn8kpqRf2dtNrnsiuRsnzAi6KAkFAEHLB7eLjceNbkk6df3hJrLfnn0DZ6M-OR0O05SgtEyHFsyMpf4OALQwVREIkC7LBTWn7nYCpmzK4ilrL3eM5ZRrbweQ96Tbwi-rfPfp-ptnelO_GGnqzyQef2DN5Eg4P5QZV4QX62Bw0eoYVncgCP6ZKibymnlASG0xHwgEJitu3ZSxBXt-w", "tx-auth:expiresIn": "300", + // highlight-next-line "authorization": "eyJraWQiOiJ0b2tlblNpZ25lclB1YmxpY0tleSIsImFsZyI6IlJTMjU2In0.eyJpc3MiOiJCUE5MMDAwMDAwMDNBWVJFIiwiYXVkIjoiQlBOTDAwMDAwMDAzQVpRUCIsInN1YiI6IkJQTkwwMDAwMDAwM0FZUkUiLCJleHAiOjE3MzI3MjY0ODksImlhdCI6MTczMjcyNjE4OSwianRpIjoiODRkZDIxOGItMzk1ZC00YmExLTg2OWUtOWYzMjI3ZWM0NWFlIn0.jTKEv8Fh75W1JOwrFUo1wyLdUOyBn3g500dWNUbaEC_bgASPImXfXnY3rhIVr_hrFY-anJIB_a6SkpTWb7lycCh2dcMaOmUVgmdKTcEvTr2blAXD_WUZTQYxHDVsMuPXDbX-30tYM4KVPOyemfe7IreB38n104j_SLo2Dr1BrbN9xU7mUm6DeKv1oi0TFRxnmhwnRx4hK1eBYIO-FuA9h1RDvfLWXW5yF55KkkrRTjX2HKqVPAtHInMZBRDhqB298N_VLpwQMtg9nkElzNWIUqEV4zQ1YLSsGNLSxog7JwuL3Tvy1VCOkzDkr6K89Z4IWEF0GzPjXO6Z-li_Vv7DVw", "tx-auth:refreshAudience": "did:web:ssi-dim-wallet-stub.tx.test:BPNL00000003AZQP", "@context": { @@ -514,25 +196,42 @@ RESPONSE: "odrl": "http://www.w3.org/ns/odrl/2/" } } +``` +## Step 5: Fetch data +Using the endpoint and authorization token from the response, Alice fetches the data. -Get Data: -Aus vorheriger response: den Endpoint kopieren und die Autorization (Token) kopieren und einfügen - - +### Fetch data request +```bash curl -L -X GET 'http://dataprovider-dataplane.tx.test/api/public' \ - -H 'Authorization: eyJraWQiOiJ0b2tlblNpZ25lclB1YmxpY0tleSIsImFsZyI6IlJTMjU2In0.eyJpc3MiOiJCUE5MMDAwMDAwMDNBWVJFIiwiYXVkIjoiQlBOTDAwMDAwMDAzQVpRUCIsInN1YiI6IkJQTkwwMDAwMDAwM0FZUkUiLCJleHAiOjE3MzI3MjY0ODksImlhdCI6MTczMjcyNjE4OSwianRpIjoiODRkZDIxOGItMzk1ZC00YmExLTg2OWUtOWYzMjI3ZWM0NWFlIn0.jTKEv8Fh75W1JOwrFUo1wyLdUOyBn3g500dWNUbaEC_bgASPImXfXnY3rhIVr_hrFY-anJIB_a6SkpTWb7lycCh2dcMaOmUVgmdKTcEvTr2blAXD_WUZTQYxHDVsMuPXDbX-30tYM4KVPOyemfe7IreB38n104j_SLo2Dr1BrbN9xU7mUm6DeKv1oi0TFRxnmhwnRx4hK1eBYIO-FuA9h1RDvfLWXW5yF55KkkrRTjX2HKqVPAtHInMZBRDhqB298N_VLpwQMtg9nkElzNWIUqEV4zQ1YLSsGNLSxog7JwuL3Tvy1VCOkzDkr6K89Z4IWEF0GzPjXO6Z-li_Vv7DVw' + // highlight-next-line + -H 'Authorization: eyJraWQiOiJ0b2tlblNpZ25lclB1YmxpY0tleSIsImFsZyI6IlJTMjU2In0.eyJpc3MiOiJCUE5MMDAwMDAwMDNBWVJFIiwiYXVkIjoiQlBOTDAwMDAwMDAzQVpRUCIsInN1YiI6IkJQTkwwMDAwMDAwM0FZUkUiLCJleHAiOjE3MzI3MjY0ODksImlhdCI6MTczMjcyNjE4OSwianRpIjoiODRkZDIxOGItMzk1ZC00YmExLTg2OWUtOWYzMjI3ZWM0NWFlIn0.jTKEv8Fh75W1JOwrFUo1wyLdUOyBn3g500dWNUbaEC_bgASPImXfXnY3rhIVr_hrFY-anJIB_a6SkpTWb7lycCh2dcMaOmUVgmdKTcEvTr2blAXD_WUZTQYxHDVsMuPXDbX-30tYM4KVPOyemfe7IreB38n104j_SLo2Dr1BrbN9xU7mUm6DeKv1oi0TFRxnmhwnRx4hK1eBYIO-FuA9h1RDvfLWXW5yF55KkkrRTjX2HKqVPAtHInMZBRDhqB298N_VLpwQMtg9nkElzNWIUqEV4zQ1YLSsGNLSxog7JwuL3Tvy1VCOkzDkr6K89Z4IWEF0GzPjXO6Z-li_Vv7DVw' +``` - -RESPONSE: +### Fetch data response - { +```json +{ "userId": 1, "id": 3, "title": "fugiat veniam minus", "completed": false -} +} +``` + +:::tip congratulations +your data has been successfully transfered! +::: + +## Notice +This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). +- SPDX-License-Identifier: CC-BY-4.0 +- SPDX-FileCopyrightText: 2023 sovity GmbH +- SPDX-FileCopyrightText: 2023 SAP SE +- SPDX-FileCopyrightText: 2023 msg systems AG +- SPDX-FileCopyrightText: 2023 Materna Information & Communications SE +- Source URL: [https://github.com/eclipse-tractusx/eclipse-tractusx.github.io](https://github.com/eclipse-tractusx/eclipse-tractusx.github.io) diff --git a/docs/tutorials/e2e/boost/provideData.md b/docs/tutorials/e2e/boost/provideData.md index 87c2e025d40..d5443402550 100644 --- a/docs/tutorials/e2e/boost/provideData.md +++ b/docs/tutorials/e2e/boost/provideData.md @@ -3,58 +3,104 @@ title: Provide data sidebar_position: 2 --- -## Create first data asset +This tutorial guides you through the process of creating and providing data in a local dataspace using the Eclipse Dataspace Connector (EDC). You'll create an asset, +define policies, and set up a contract definition for data sharing. -In this step we will focus on inserting data into our provider connector using -the [Management API](https://app.swaggerhub.com/apis/eclipse-edc-bot/management-api). We will use plain -CLI tools (`curl`) for this, but feel free to use graphical tools such as Postman or Insomnia. +## Create your first data asset -:::note +We will start by creating an asset that represents the data to be shared. The data provider (Bob) uses the **[Management API](https://app.swaggerhub.com/apis/eclipse-edc-bot/management-api)** to define the asset. +For better understanding, the cURL commands are provided and explained in detail for every step. For nearly every request a response is expected. + +:::tip curl explanation + +1. **URL and Method**: + +- `-L`: Ensures redirections are followed if the URL returns a redirect response. +- `-X POST`: Specifies the HTTP method as `POST`. + +2. **Headers**: + +- `-H 'Content-Type: application/json'`: Indicates that the payload is in JSON format. +- `-H 'X-Api-Key: TEST2'`: Sends an API key for authentication. + +3. **Payload**: -Alice acts here as a data consumer and Bob as a data provider. +- `--data-raw`: Includes the JSON payload to be sent with the `POST` request. -- Bob -> -- Alice -> +4. **Piping into `jq`**: + +- The output is piped into `jq` to format and colorize the JSON response for easier reading. ::: +:::note +**Actors in this tutorial:** + +- **Bob**: data provider, is reachable via `http://dataprovider-controlplane.tx.test` +- **Alice**: data consumer, is reachable via `http://dataconsumer-1-controlplane.tx.test` + +::: + +### Step 1: Create the asset + Alice, as a data consumer, wants to consume data from Bob. Bob, as a data provider, needs to create an asset for Alice. -Action (Bob): Create this asset using the following `curl` command: +Run the following `curl` command to create the asset: ```shell - curl -L -X POST 'http://dataprovider-controlplane.tx.test/management/v3/assets' \ --H 'Content-Type: application/json' \ --H 'X-Api-Key: TEST2' \ ---data-raw '{ - "@context": {}, + -H 'Content-Type: application/json' \ + -H 'X-Api-Key: TEST2' \ + --data-raw '{ + "@context": {}, + "@id": "200", + "properties": { + "description": "Product EDC Demo Asset" + }, + "dataAddress": { + "@type": "DataAddress", + "type": "HttpData", + "baseUrl": "https://jsonplaceholder.typicode.com/todos/3" + } + }' | jq +``` + +#### Expected output + +If successful, the response should look like this: + +```json +{ "@id": "200", "properties": { "description": "Product EDC Demo Asset" }, "dataAddress": { - "@type": "DataAddress", "type": "HttpData", "baseUrl": "https://jsonplaceholder.typicode.com/todos/3" } -}'| jq +} ``` -Just to be sure, that the asset was created succesfully, Bob can check the asset using the following `curl` commands: +### Step 2: Validate the asset -```shell - -// get your asset by ID +Check that the asset was created successfully by running the following for requesting the specific asset with ID 200: +```bash curl -L -X GET 'http://dataprovider-controlplane.tx.test/management/v3/assets/200' \ -H 'X-Api-Key: TEST2' | jq +``` -// or get the whole catalog +Alternatively, retrieve all assets: -curl -L -X POST http://dataprovider-controlplane.tx.test/management/v3/assets/request -H "x-api-key: TEST2" -H "content-type: application/json" | jq +```bash +curl -L -X POST 'http://dataprovider-controlplane.tx.test/management/v3/assets/request' \ +-H "x-api-key: TEST2" \ +-H "content-type: application/json" | jq ``` -The result for the first command shows just the newly created asset. +#### Expected output + +The result for the first command shows just the newly created asset: ```json { @@ -81,35 +127,46 @@ The result for the first command shows just the newly created asset. ``` -## Request catalog +The second request will return all assets. It`s called request catalog and will be explained in the next step. -Bob tells Alice, that he created an asset, and she should now be able to request it. In the next step, Alice requests a contract offer catalog. In the catalog, all contract offers for Alice are listed. +## Request the catalog -Action (Alice): Execute a request using the following `curl` commands: +Once the asset is created, Alice (the data consumer) can try request a catalog of available (offered) data. -```shell +:::note +Alice can only see the offered data if a Access Policy was assigned. +::: -curl -L -X POST 'http://dataconsumer-1-controlplane.tx.test/management/v2/catalog/request' \ --H 'Content-Type: application/json' \ --H 'X-Api-Key: TEST1' \ ---data-raw '{ - "@context": { - "@vocab": "https://w3id.org/edc/v0.0.1/ns/" - }, - "@type": "CatalogRequest", - "counterPartyAddress": "http://dataprovider-controlplane.tx.test/api/v1/dsp", - "counterPartyId": "BPNL00000003AYRE", - "protocol": "dataspace-protocol-http", - "querySpec": { - "offset": 0, - "limit": 50 - } -}' | jq +### Step 1: Request contract offers +Alice sends a `CatalogRequest` to Bob's connector to discover available assets: +```shell +curl -L -X POST 'http://dataconsumer-1-controlplane.tx.test/management/v2/catalog/request' \ + -H 'Content-Type: application/json' \ + -H 'X-Api-Key: TEST1' \ + --data-raw '{ + "@context": { + "@vocab": "https://w3id.org/edc/v0.0.1/ns/" + }, + "@type": "CatalogRequest", + "counterPartyAddress": "http://dataprovider-controlplane.tx.test/api/v1/dsp", + "counterPartyId": "BPNL00000003AYRE", + "protocol": "dataspace-protocol-http", + "querySpec": { + "offset": 0, + "limit": 50 + } + }' | jq ``` -The requested catalog might look like this but the content may differ: +#### Expected Output + +Alice's catalog response will include available assets like this (but not the newly created asset with ID: 200): + +:::tip +If the asset is not visible, ensure the **Access Policy** and **Contract Definition** are created on Bob's side. +::: ```json { @@ -224,59 +281,57 @@ The requested catalog might look like this but the content may differ: } ``` -## Create first access policy - -Let´s see if Alice can see the Asset (ID: 200). +## Create a first access policy -:::info -As you can see in the response, the data offer "Product EDC Demo Asset" (asset ID: 200) does not appear. Unfortunately, Alice sees some contract offers but she cannot find the contract offer from Bob. -::: +Bob creates an **Access Policy** to determine who can view the data offer. -Alice calls Bob and says she can´t see the asset. Bob remembers that he did not create an access policy. An access policy defines who is allowed to see a data offering. +### Step 1: Create the policy -Action (Bob): Create the access policy using the following `curl` command: +Run this `curl` command: ```shell - curl -L -X POST 'http://dataprovider-controlplane.tx.test/management/v2/policydefinitions' \ --H 'Content-Type: application/json' \ --H 'X-Api-Key: TEST2' \ ---data-raw '{ - "@context": { - "odrl": "http://www.w3.org/ns/odrl/2/" - }, - "@type": "PolicyDefinitionRequestDto", - "@id": "200", - "policy": { - "@type": "odrl:Set", - "odrl:permission": [ - { - "odrl:action": "USE", - "odrl:constraint": { - "@type": "LogicalConstraint", - "odrl:or": [ - { - "@type": "Constraint", - "odrl:leftOperand": { - "@id": "BusinessPartnerNumber" - }, - "odrl:operator": { - "@id": "odrl:eq" - }, - "odrl:rightOperand": "BPNL00000003AZQP" - } - ] + -H 'Content-Type: application/json' \ + -H 'X-Api-Key: TEST2' \ + --data-raw '{ + "@context": { + "odrl": "http://www.w3.org/ns/odrl/2/" + }, + "@type": "PolicyDefinitionRequestDto", + "@id": "200", + "policy": { + "@type": "odrl:Set", + "odrl:permission": [ + { + "odrl:action": "USE", + "odrl:constraint": { + "@type": "LogicalConstraint", + "odrl:or": [ + { + "@type": "Constraint", + "odrl:leftOperand": { + "@id": "BusinessPartnerNumber" + }, + "odrl:operator": { + "@id": "odrl:eq" + }, + "odrl:rightOperand": "BPNL00000003AZQP" + } + ] + } } - } - ] - } -}' | jq + ] + } + }' | jq ``` +In this case a **Access Policy** is created. The assigned asset will only be visible as a data offer for the Business Partner Number `BPNL00000003AZQP`. + +#### Expected Output + The policy was successfully created, if the response is something like this ```json - { "@type": "IdResponse", "@id": "200", @@ -290,47 +345,38 @@ The policy was successfully created, if the response is something like this "odrl": "http://www.w3.org/ns/odrl/2/" } } - ``` -## Request catalog - second try +### Step 2: Request catalog - second try -Now that Bob created an access policy, Alice can once again try to access Bob's asset. - -Action (Alice): Execute the request again using the following `curl` command: +Now that Bob created an access policy, Alice can once again try to access Bob's offer by running this `curl`. ```shell - curl -L -X POST 'http://dataconsumer-1-controlplane.tx.test/management/v2/catalog/request' \ --H 'Content-Type: application/json' \ --H 'X-Api-Key: TEST1' \ ---data-raw '{ - "@context": { - "@vocab": "https://w3id.org/edc/v0.0.1/ns/" - }, - "@type": "CatalogRequest", - "counterPartyAddress": "http://dataprovider-controlplane.tx.test/api/v1/dsp", - "counterPartyId": "BPNL00000003AYRE", - "protocol": "dataspace-protocol-http", - "querySpec": { - "offset": 0, - "limit": 50 - } -}' | jq - + -H 'Content-Type: application/json' \ + -H 'X-Api-Key: TEST1' \ + --data-raw '{ + "@context": { + "@vocab": "https://w3id.org/edc/v0.0.1/ns/" + }, + "@type": "CatalogRequest", + "counterPartyAddress": "http://dataprovider-controlplane.tx.test/api/v1/dsp", + "counterPartyId": "BPNL00000003AYRE", + "protocol": "dataspace-protocol-http", + "querySpec": { + "offset": 0, + "limit": 50 + } + }' | jq ``` -## Create first contract definition +#### Expected Output -Let´s see if Alice can see the Asset. +Since the asset is still not visible, the response will be the same as before. This is expected, as the asset is not yet linked to the policy. +:::tip Once again Alice cannot find the data offer. This is by design and to be expected since Bob has only created an asset and a policy definition. An asset and a policy can not be displayed to Alice as a consumer without a contract definition. - -:::info - -This is the first lesson in this tutorial: For providing data, a contract definition must be created on the provider side. This must always contain an asset, an access policy, and a contract policy. - -::: +**For providing data, a contract definition must be created on the provider side. This must always contain an asset, an access policy, and a contract policy.** Contract definitions state how assets and policies are linked together. Contract definitions express under what conditions an asset is published in a data space. Those conditions are comprised of a contract policy and an access policy. Those policies are referenced by ID, that means they must already exist in the policy store before creating the contract definition. @@ -338,22 +384,24 @@ Contract definitions state how assets and policies are linked together. Contract - **Contract policy:** determines the conditions for initiating a contract negotiation for a particular asset. Note that this does not automatically guarantee the successful creation of a contract, it merely expresses the eligibility to start the negotiation. Find additional information on transferring data in the [Developer's Handbook](https://github.com/eclipse-edc/docs/blob/main/developer/handbook.md). +::: -An access policy has already been created and it can also be used as a contract policy. +## Define a contract definition -Let's check if the policy is created correctly: +Alice still cannot see the asset because Bob hasn't created a **Contract Definition**. Contract definitions link assets and policies to define usage terms. +### Step 1: Create the contract definition + +First of all run this `curl` command to check if the policy is created correctly: ```shell curl -L -X GET 'http://dataprovider-controlplane.tx.test/management/v2/policydefinitions/200' \ -H 'X-Api-Key: TEST2' | jq - ``` The policy with ID: 200 was successfully created, if the response is something like this ```json - { "@id": "200", "@type": "PolicyDefinition", @@ -389,36 +437,32 @@ The policy with ID: 200 was successfully created, if the response is something l "odrl": "http://www.w3.org/ns/odrl/2/" } } - ``` - -Action (Bob): Create a contract definition including the asset and the policies you have created. For this, use the following `curl` command: +Run this `curl` command to create a contract definition including the asset and the policies you have created: ```shell - curl -L -X POST 'http://dataprovider-controlplane.tx.test/management/v2/contractdefinitions' \ --H 'Content-Type: application/json' \ --H 'X-Api-Key: TEST2' \ ---data-raw '{ - "@context": {}, - "@id": "200", - "@type": "ContractDefinition", - "accessPolicyId": "200", - "contractPolicyId": "200", - "assetsSelector": { - "@type": "CriterionDto", - "operandLeft": "https://w3id.org/edc/v0.0.1/ns/id", - "operator": "=", - "operandRight": "200" - } -}' | jq + -H 'Content-Type: application/json' \ + -H 'X-Api-Key: TEST2' \ + --data-raw '{ + "@context": {}, + "@id": "200", + "@type": "ContractDefinition", + "accessPolicyId": "200", + "contractPolicyId": "200", + "assetsSelector": { + "@type": "CriterionDto", + "operandLeft": "https://w3id.org/edc/v0.0.1/ns/id", + "operator": "=", + "operandRight": "200" + } + }' | jq ``` -As a check, the result should look like this: +#### Expected Output ```json - { "@type": "IdResponse", "@id": "200", @@ -432,45 +476,40 @@ As a check, the result should look like this: "odrl": "http://www.w3.org/ns/odrl/2/" } } - ``` -## Request catalog - third try +## Verify data availability -Let´s see if Alice can finally see the Asset. -Action (Alice): Execute the request again using the following `curl` command: +Alice re-requests the catalog. This time, she should see Bob's asset in the catalog: ```shell - curl -L -X POST 'http://dataconsumer-1-controlplane.tx.test/management/v2/catalog/request' \ --H 'Content-Type: application/json' \ --H 'X-Api-Key: TEST1' \ ---data-raw '{ - "@context": { - "@vocab": "https://w3id.org/edc/v0.0.1/ns/" - }, - "@type": "CatalogRequest", - "counterPartyAddress": "http://dataprovider-controlplane.tx.test/api/v1/dsp", - "counterPartyId": "BPNL00000003AYRE", - "protocol": "dataspace-protocol-http", - "querySpec": { - "offset": 0, - "limit": 50 - } -}' | jq + -H 'Content-Type: application/json' \ + -H 'X-Api-Key: TEST1' \ + --data-raw '{ + "@context": { + "@vocab": "https://w3id.org/edc/v0.0.1/ns/" + }, + "@type": "CatalogRequest", + "counterPartyAddress": "http://dataprovider-controlplane.tx.test/api/v1/dsp", + "counterPartyId": "BPNL00000003AYRE", + "protocol": "dataspace-protocol-http", + "querySpec": { + "offset": 0, + "limit": 50 + } + }' | jq ``` -In the response an additional entry should appear: +#### Expected Output ```json - - { "@id": "a8bef433-83ac-4fe0-a2c1-3f988dc187d4", "@type": "dcat:Catalog", "dspace:participantId": "BPNL00000003AYRE", "dcat:dataset": [ - { + { "@id": "200", "@type": "dcat:Dataset", "odrl:hasPolicy": [ @@ -496,7 +535,6 @@ In the response an additional entry should appear: "odrl:prohibition": [], "odrl:obligation": [] } - ], "dcat:distribution": [ { @@ -609,7 +647,6 @@ In the response an additional entry should appear: "dspace": "https://w3id.org/dspace/v0.8/" } } - ``` :::info From 7174b43a7fc93d0acc25a8af19473874720c64f3 Mon Sep 17 00:00:00 2001 From: Stephan Bauer Date: Thu, 28 Nov 2024 11:00:27 +0100 Subject: [PATCH 08/14] fix linting issues --- docs/tutorials/e2e/boost/boost.md | 10 +++--- docs/tutorials/e2e/boost/provideData.md | 18 ++++------ .../tutorials/e2e/connect/deployComponents.md | 33 +++++++++---------- 3 files changed, 27 insertions(+), 34 deletions(-) diff --git a/docs/tutorials/e2e/boost/boost.md b/docs/tutorials/e2e/boost/boost.md index c80b6527217..1aba1377104 100644 --- a/docs/tutorials/e2e/boost/boost.md +++ b/docs/tutorials/e2e/boost/boost.md @@ -8,14 +8,12 @@ In the `Boost Chapter`, you will configure and register your components so that In this **Boost Chapter**, you will create and request different assets and learn how the management-api works. The following steps will guide you through the process: 1. **Data Provider Role**: - -- Build your first data pipeline. -- Add your first `assets`, `policies`, and create a `contract offer`. + - Build your first data pipeline. + - Add your first `assets`, `policies`, and create a `contract offer`. 2. **Data Consumer Role**: - -- Discover the data you previously created. -- Initiate a data transfer. + - Discover the data you previously created. + - Initiate a data transfer. By the end of this chapter, you will have the foundational knowledge needed to share data within your data space. diff --git a/docs/tutorials/e2e/boost/provideData.md b/docs/tutorials/e2e/boost/provideData.md index d5443402550..2dc14a907b4 100644 --- a/docs/tutorials/e2e/boost/provideData.md +++ b/docs/tutorials/e2e/boost/provideData.md @@ -14,22 +14,18 @@ For better understanding, the cURL commands are provided and explained in detail :::tip curl explanation 1. **URL and Method**: - -- `-L`: Ensures redirections are followed if the URL returns a redirect response. -- `-X POST`: Specifies the HTTP method as `POST`. + - `-L`: Ensures redirections are followed if the URL returns a redirect response. + - `-X POST`: Specifies the HTTP method as `POST`. 2. **Headers**: - -- `-H 'Content-Type: application/json'`: Indicates that the payload is in JSON format. -- `-H 'X-Api-Key: TEST2'`: Sends an API key for authentication. + - `-H 'Content-Type: application/json'`: Indicates that the payload is in JSON format. + - `-H 'X-Api-Key: TEST2'`: Sends an API key for authentication. 3. **Payload**: - -- `--data-raw`: Includes the JSON payload to be sent with the `POST` request. + - `--data-raw`: Includes the JSON payload to be sent with the `POST` request. 4. **Piping into `jq`**: - -- The output is piped into `jq` to format and colorize the JSON response for easier reading. + - The output is piped into `jq` to format and colorize the JSON response for easier reading. ::: @@ -501,7 +497,7 @@ curl -L -X POST 'http://dataconsumer-1-controlplane.tx.test/management/v2/catalo }' | jq ``` -#### Expected Output +### Expected Output ```json { diff --git a/docs/tutorials/e2e/connect/deployComponents.md b/docs/tutorials/e2e/connect/deployComponents.md index 8547ccdb0d2..1a64b4360e0 100644 --- a/docs/tutorials/e2e/connect/deployComponents.md +++ b/docs/tutorials/e2e/connect/deployComponents.md @@ -119,7 +119,7 @@ In the following steps, replace `192.168.49.2` with your `minikube ip` if it dif Create a file in /etc/resolver/minikube-test with the following contents. -```properties +```shell domain tx.test nameserver 192.168.49.2 search_order 1 @@ -128,7 +128,7 @@ timeout 5 If you still face DNS issues, add the hosts to your /etc/hosts file: -```properties +```shell 192.168.49.2 centralidp.tx.test 192.168.49.2 sharedidp.tx.test 192.168.49.2 portal.tx.test @@ -160,7 +160,7 @@ We also recommend to execute the usage example after install to check proper set For Windows edit the hosts file under `C:\Windows\System32\drivers\etc\hosts`: -```properties +```shell 192.168.49.2 centralidp.tx.test 192.168.49.2 sharedidp.tx.test 192.168.49.2 portal.tx.test @@ -211,24 +211,22 @@ helm dependency update ../tx-data-provider helm dependency update ``` -##### grey_question: Command explanation +:::note Command explanation + +`helm install` is used to install a Helm chart. + - `-f your-values.yaml` | `-f values-*.yaml` specifies the values file to use for configuration. + - `umbrella` is the release name for the Helm chart. + - `.` specifies the path to the chart directory. + - `--namespace umbrella` specifies the namespace in which to install the chart. + - `--create-namespace` create a namespace with the name `umbrella`. -> `helm install` is used to install a Helm chart. -> > `-f your-values.yaml` | `-f values-*.yaml` specifies the values file to use for configuration. -> --- -> > `umbrella` is the release name for the Helm chart. -> --- -> > `.` specifies the path to the chart directory. -> --- -> > `--namespace umbrella` specifies the namespace in which to install the chart. -> --- -> > `--create-namespace` create a namespace with the name `umbrella`. +::: ##### Option 1 Choose to install one of the predefined subsets (currently in focus of the **E2E Adopter Journey**): -:::note +:::note This will take a while. So please be patient. @@ -267,8 +265,9 @@ Install your chosen components by having them enabled in a `your-values.yaml` fi helm install -f your-values.yaml umbrella . --namespace umbrella --create-namespace ``` -> In general, all your specific configuration and secret values should be set by installing with an own values file. - +:::tip +In general, all your specific configuration and secret values should be set by installing with an own values file. +::: #### Get to know the Portal From fb1def09136e96f530e379923e6c5d0a56410068 Mon Sep 17 00:00:00 2001 From: Stephan Bauer Date: Thu, 28 Nov 2024 11:05:01 +0100 Subject: [PATCH 09/14] fix linting issues --- .../tutorials/e2e/connect/deployComponents.md | 57 ++++++++++--------- 1 file changed, 29 insertions(+), 28 deletions(-) diff --git a/docs/tutorials/e2e/connect/deployComponents.md b/docs/tutorials/e2e/connect/deployComponents.md index 1a64b4360e0..38f13e87d1f 100644 --- a/docs/tutorials/e2e/connect/deployComponents.md +++ b/docs/tutorials/e2e/connect/deployComponents.md @@ -214,11 +214,12 @@ helm dependency update :::note Command explanation `helm install` is used to install a Helm chart. - - `-f your-values.yaml` | `-f values-*.yaml` specifies the values file to use for configuration. - - `umbrella` is the release name for the Helm chart. - - `.` specifies the path to the chart directory. - - `--namespace umbrella` specifies the namespace in which to install the chart. - - `--create-namespace` create a namespace with the name `umbrella`. + +- `-f your-values.yaml` | `-f values-*.yaml` specifies the values file to use for configuration. +- `umbrella` is the release name for the Helm chart. +- `.` specifies the path to the chart directory. +- `--namespace umbrella` specifies the namespace in which to install the chart. +- `--create-namespace` create a namespace with the name `umbrella`. ::: @@ -342,29 +343,29 @@ If persistance for one or more components is enabled, the persistent volume clai Currently enabled ingresses: -- http://centralidp.tx.test/auth/ -- http://sharedidp.tx.test/auth/ -- http://portal-backend.tx.test - - http://portal-backend.tx.test/api/administration/swagger/index.html - - http://portal-backend.tx.test/api/registration/swagger/index.html - - http://portal-backend.tx.test/api/apps/swagger/index.html - - http://portal-backend.tx.test/api/services/swagger/index.html - - http://portal-backend.tx.test/api/notification/swagger/index.html -- http://portal.tx.test -- http://semantics.tx.test/discoveryfinder/swagger-ui/index.html -- http://ssi-credential-issuer.tx.test/api/issuer/swagger/index.html -- http://dataconsumer-1-controlplane.tx.test -- http://dataconsumer-1-dataplane.tx.test -- http://dataprovider-dataplane.tx.test -- http://dataconsumer-2-controlplane.tx.test -- http://dataconsumer-2-dataplane.tx.test -- http://business-partners.tx.test/pool -- http://business-partners.tx.test/orchestrator -- http://bdrs-server.tx.test -- http://iatpmock.tx.test -- http://pgadmin4.tx.test -- http://ssi-dim-wallet-stub.tx.test -- http://dataprovider-submodelserver.tx.test +- +- +- + - + - + - + - + - +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- ### Database Access From 7cb67a1f0dfc6f91132fd38ae032f29b7ce7d24a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?David=20G=C3=B6rzig?= <132340784+dvg36@users.noreply.github.com> Date: Mon, 2 Dec 2024 17:48:54 +0100 Subject: [PATCH 10/14] adapt provide data for community days --- docs/tutorials/e2e/boost/consumeData.md | 23 ++- docs/tutorials/e2e/boost/provideData.md | 235 +++++++++++------------- 2 files changed, 132 insertions(+), 126 deletions(-) diff --git a/docs/tutorials/e2e/boost/consumeData.md b/docs/tutorials/e2e/boost/consumeData.md index 7481aa91d78..e3c84e5203a 100644 --- a/docs/tutorials/e2e/boost/consumeData.md +++ b/docs/tutorials/e2e/boost/consumeData.md @@ -135,6 +135,28 @@ curl -L -X POST 'http://dataconsumer-1-controlplane.tx.test/management/v2/edrs/r }' | jq ``` +curl -L -X POST 'http://dataconsumer-1-controlplane.tx.test/management/v2/edrs/request' \ + -H 'Content-Type: application/json' \ + -H 'X-Api-Key: TEST1' \ + --data-raw '{ + "@context": { "@vocab": "https://w3id.org/edc/v0.0.1/ns/" }, + "@type": "QuerySpec", + "filterExpression": [ + { + "operandLeft": "contractNegotiationId", + "operator": "=", + "operandRight": "4b260501-ae2f-46f4-9efc-01ba5a0b3d96" + } + ] + }' | jq + + +basurl + +basurl/uuid1 + + + ### Query edrs response ```json @@ -144,7 +166,6 @@ curl -L -X POST 'http://dataconsumer-1-controlplane.tx.test/management/v2/edrs/r "providerId": "BPNL00000003AYRE", "assetId": "200", "agreementId": "2ece6f45-ff09-4417-b5a9-a92a1849f1d0", - // highlight-next-line "transferProcessId": "bdd4af10-9e4a-4796-b4b7-7ecdf91a533a", "createdAt": 1732726189831, "contractNegotiationId": "4b260501-ae2f-46f4-9efc-01ba5a0b3d96", diff --git a/docs/tutorials/e2e/boost/provideData.md b/docs/tutorials/e2e/boost/provideData.md index 2dc14a907b4..cf7535613a9 100644 --- a/docs/tutorials/e2e/boost/provideData.md +++ b/docs/tutorials/e2e/boost/provideData.md @@ -47,7 +47,14 @@ curl -L -X POST 'http://dataprovider-controlplane.tx.test/management/v3/assets' -H 'Content-Type: application/json' \ -H 'X-Api-Key: TEST2' \ --data-raw '{ - "@context": {}, + "@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/" + }, "@id": "200", "properties": { "description": "Product EDC Demo Asset" @@ -55,7 +62,12 @@ curl -L -X POST 'http://dataprovider-controlplane.tx.test/management/v3/assets' "dataAddress": { "@type": "DataAddress", "type": "HttpData", - "baseUrl": "https://jsonplaceholder.typicode.com/todos/3" + "proxyPath": "true", + "type": "HttpData", + "proxyMethod": "true", + "proxyQueryParams": "true", + "proxyBody": "true", + "baseUrl": "https://dataprovider-submodelserver.tx.test" } }' | jq ``` @@ -66,13 +78,16 @@ If successful, the response should look like this: ```json { + "@type": "IdResponse", "@id": "200", - "properties": { - "description": "Product EDC Demo Asset" - }, - "dataAddress": { - "type": "HttpData", - "baseUrl": "https://jsonplaceholder.typicode.com/todos/3" + "createdAt": 1733150672368, + "@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,7 +135,6 @@ The result for the first command shows just the newly created asset: "odrl": "http://www.w3.org/ns/odrl/2/" } } - ``` The second request will return all assets. It`s called request catalog and will be explained in the next step. @@ -490,9 +504,14 @@ curl -L -X POST 'http://dataconsumer-1-controlplane.tx.test/management/v2/catalo "counterPartyAddress": "http://dataprovider-controlplane.tx.test/api/v1/dsp", "counterPartyId": "BPNL00000003AYRE", "protocol": "dataspace-protocol-http", - "querySpec": { - "offset": 0, - "limit": 50 + "querySpec": { + "filterExpression": [ + { + "operandLeft": "https://w3id.org/edc/v0.0.1/ns/id", + "operator": "=", + "operandRight": "200" + } + ] } }' | jq ``` @@ -501,129 +520,95 @@ curl -L -X POST 'http://dataconsumer-1-controlplane.tx.test/management/v2/catalo ```json { - "@id": "a8bef433-83ac-4fe0-a2c1-3f988dc187d4", + "@id": "ad6b2272-a131-4d75-9efd-0c7529d1109f", "@type": "dcat:Catalog", "dspace:participantId": "BPNL00000003AYRE", - "dcat:dataset": [ - { - "@id": "200", - "@type": "dcat:Dataset", - "odrl:hasPolicy": [ - { - "@id": "MjAw:MjAw:ODliYzY2OWItYjkyYS00NmU2LWEzYjktNzI1MjdjM2U3MTY0", - "@type": "odrl:Offer", - "odrl:permission": { - "odrl:action": { - "@id": "USE" - }, - "odrl:constraint": { - "odrl:or": { - "odrl:leftOperand": { - "@id": "BusinessPartnerNumber" - }, - "odrl:operator": { - "@id": "odrl:eq" - }, - "odrl:rightOperand": "BPNL00000003AZQP" - } - } - }, - "odrl:prohibition": [], - "odrl:obligation": [] - } - ], - "dcat:distribution": [ - { - "@type": "dcat:Distribution", - "dct:format": { - "@id": "AzureStorage-PUSH" - }, - "dcat:accessService": { - "@id": "cf8a77da-dbe9-4d95-bd15-7a250706511e", - "@type": "dcat:DataService", - "dcat:endpointDescription": "dspace:connector", - "dcat:endpointUrl": "http://dataprovider-controlplane.tx.test/api/v1/dsp", - "dct:terms": "dspace:connector", - "dct:endpointUrl": "http://dataprovider-controlplane.tx.test/api/v1/dsp" - } + "dcat:dataset": { + "@id": "200", + "@type": "dcat:Dataset", + "odrl:hasPolicy": { + "@id": "MjAw:MjAw:YzNlOWVjYzEtMDcwNS00YWI1LThhM2UtOWNmYTA5NTg2ZWU4", + "@type": "odrl:Offer", + "odrl:permission": { + "odrl:action": { + "odrl:type": "USE" }, - { - "@type": "dcat:Distribution", - "dct:format": { - "@id": "HttpData-PULL" - }, - "dcat:accessService": { - "@id": "cf8a77da-dbe9-4d95-bd15-7a250706511e", - "@type": "dcat:DataService", - "dcat:endpointDescription": "dspace:connector", - "dcat:endpointUrl": "http://dataprovider-controlplane.tx.test/api/v1/dsp", - "dct:terms": "dspace:connector", - "dct:endpointUrl": "http://dataprovider-controlplane.tx.test/api/v1/dsp" + "odrl:constraint": { + "odrl:or": { + "odrl:leftOperand": "BusinessPartnerNumber", + "odrl:operator": { + "@id": "odrl:eq" + }, + "odrl:rightOperand": "BPNL00000003AZQP" } + } + }, + "odrl:prohibition": [], + "odrl:obligation": [] + }, + "dcat:distribution": [ + { + "@type": "dcat:Distribution", + "dct:format": { + "@id": "AzureStorage-PUSH" }, - { - "@type": "dcat:Distribution", - "dct:format": { - "@id": "HttpData-PUSH" - }, - "dcat:accessService": { - "@id": "cf8a77da-dbe9-4d95-bd15-7a250706511e", - "@type": "dcat:DataService", - "dcat:endpointDescription": "dspace:connector", - "dcat:endpointUrl": "http://dataprovider-controlplane.tx.test/api/v1/dsp", - "dct:terms": "dspace:connector", - "dct:endpointUrl": "http://dataprovider-controlplane.tx.test/api/v1/dsp" - } + "dcat:accessService": { + "@id": "ed228dd5-d1e6-45be-84be-20ba27829e50", + "@type": "dcat:DataService", + "dcat:endpointDescription": "dspace:connector", + "dcat:endpointUrl": "http://dataprovider-controlplane.tx.test/api/v1/dsp", + "dct:terms": "dspace:connector", + "dct:endpointUrl": "http://dataprovider-controlplane.tx.test/api/v1/dsp" + } + }, + { + "@type": "dcat:Distribution", + "dct:format": { + "@id": "HttpData-PULL" }, - { - "@type": "dcat:Distribution", - "dct:format": { - "@id": "AmazonS3-PULL" - }, - "dcat:accessService": { - "@id": "cf8a77da-dbe9-4d95-bd15-7a250706511e", - "@type": "dcat:DataService", - "dcat:endpointDescription": "dspace:connector", - "dcat:endpointUrl": "http://dataprovider-controlplane.tx.test/api/v1/dsp", - "dct:terms": "dspace:connector", - "dct:endpointUrl": "http://dataprovider-controlplane.tx.test/api/v1/dsp" - } + "dcat:accessService": { + "@id": "ed228dd5-d1e6-45be-84be-20ba27829e50", + "@type": "dcat:DataService", + "dcat:endpointDescription": "dspace:connector", + "dcat:endpointUrl": "http://dataprovider-controlplane.tx.test/api/v1/dsp", + "dct:terms": "dspace:connector", + "dct:endpointUrl": "http://dataprovider-controlplane.tx.test/api/v1/dsp" + } + }, + { + "@type": "dcat:Distribution", + "dct:format": { + "@id": "HttpData-PUSH" }, - { - "@type": "dcat:Distribution", - "dct:format": { - "@id": "AmazonS3-PUSH" - }, - "dcat:accessService": { - "@id": "cf8a77da-dbe9-4d95-bd15-7a250706511e", - "@type": "dcat:DataService", - "dcat:endpointDescription": "dspace:connector", - "dcat:endpointUrl": "http://dataprovider-controlplane.tx.test/api/v1/dsp", - "dct:terms": "dspace:connector", - "dct:endpointUrl": "http://dataprovider-controlplane.tx.test/api/v1/dsp" - } + "dcat:accessService": { + "@id": "ed228dd5-d1e6-45be-84be-20ba27829e50", + "@type": "dcat:DataService", + "dcat:endpointDescription": "dspace:connector", + "dcat:endpointUrl": "http://dataprovider-controlplane.tx.test/api/v1/dsp", + "dct:terms": "dspace:connector", + "dct:endpointUrl": "http://dataprovider-controlplane.tx.test/api/v1/dsp" + } + }, + { + "@type": "dcat:Distribution", + "dct:format": { + "@id": "AmazonS3-PUSH" }, - { - "@type": "dcat:Distribution", - "dct:format": { - "@id": "AzureStorage-PULL" - }, - "dcat:accessService": { - "@id": "cf8a77da-dbe9-4d95-bd15-7a250706511e", - "@type": "dcat:DataService", - "dcat:endpointDescription": "dspace:connector", - "dcat:endpointUrl": "http://dataprovider-controlplane.tx.test/api/v1/dsp", - "dct:terms": "dspace:connector", - "dct:endpointUrl": "http://dataprovider-controlplane.tx.test/api/v1/dsp" - } + "dcat:accessService": { + "@id": "ed228dd5-d1e6-45be-84be-20ba27829e50", + "@type": "dcat:DataService", + "dcat:endpointDescription": "dspace:connector", + "dcat:endpointUrl": "http://dataprovider-controlplane.tx.test/api/v1/dsp", + "dct:terms": "dspace:connector", + "dct:endpointUrl": "http://dataprovider-controlplane.tx.test/api/v1/dsp" } - ], - "description": "Product EDC Demo Asset", - "id": "200" - } - ], + } + ], + "description": "Product EDC Demo Asset", + "id": "200" + }, "dcat:service": { - "@id": "cf8a77da-dbe9-4d95-bd15-7a250706511e", + "@id": "ed228dd5-d1e6-45be-84be-20ba27829e50", "@type": "dcat:DataService", "dcat:endpointDescription": "dspace:connector", "dcat:endpointUrl": "http://dataprovider-controlplane.tx.test/api/v1/dsp", From ef2356d890c38485405cb9e34032265222bafbe0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?David=20G=C3=B6rzig?= <132340784+dvg36@users.noreply.github.com> Date: Mon, 2 Dec 2024 17:50:08 +0100 Subject: [PATCH 11/14] adapt consume data for community days --- docs/tutorials/e2e/boost/consumeData.md | 22 ---------------------- 1 file changed, 22 deletions(-) diff --git a/docs/tutorials/e2e/boost/consumeData.md b/docs/tutorials/e2e/boost/consumeData.md index e3c84e5203a..2678bc82384 100644 --- a/docs/tutorials/e2e/boost/consumeData.md +++ b/docs/tutorials/e2e/boost/consumeData.md @@ -135,28 +135,6 @@ curl -L -X POST 'http://dataconsumer-1-controlplane.tx.test/management/v2/edrs/r }' | jq ``` -curl -L -X POST 'http://dataconsumer-1-controlplane.tx.test/management/v2/edrs/request' \ - -H 'Content-Type: application/json' \ - -H 'X-Api-Key: TEST1' \ - --data-raw '{ - "@context": { "@vocab": "https://w3id.org/edc/v0.0.1/ns/" }, - "@type": "QuerySpec", - "filterExpression": [ - { - "operandLeft": "contractNegotiationId", - "operator": "=", - "operandRight": "4b260501-ae2f-46f4-9efc-01ba5a0b3d96" - } - ] - }' | jq - - -basurl - -basurl/uuid1 - - - ### Query edrs response ```json From 9eb62550b09fb6d747f968143982cd1133eda9a0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?David=20G=C3=B6rzig?= <132340784+dvg36@users.noreply.github.com> Date: Mon, 2 Dec 2024 18:46:45 +0100 Subject: [PATCH 12/14] adapt consumeData for community days --- docs/tutorials/e2e/boost/consumeData.md | 105 +++++++++++++++++++++--- docs/tutorials/e2e/boost/provideData.md | 3 +- 2 files changed, 95 insertions(+), 13 deletions(-) diff --git a/docs/tutorials/e2e/boost/consumeData.md b/docs/tutorials/e2e/boost/consumeData.md index 2678bc82384..d4a78167802 100644 --- a/docs/tutorials/e2e/boost/consumeData.md +++ b/docs/tutorials/e2e/boost/consumeData.md @@ -83,15 +83,76 @@ curl -L -X POST 'http://dataconsumer-1-controlplane.tx.test/management/v2/edrs' "protocol": "dataspace-protocol-http", "policy": { "assigner": "BPNL00000003AYRE", - // highlight-next-line "target": "200", - // highlight-next-line - "@id": "MjAw:MjAw:Y2ZjMzdlNmUtODAwNi00NGJjLWJhMWYtNjJkOWIzZWM0ZTQ3" + "@id": "MjAw:MjAw:Y2ZjMzdlNmUtODAwNi00NGJjLWJhMWYtNjJkOWIzZWM0ZTQ3", + "@type": "odrl:Offer", + "odrl:permission": { + "odrl:action": { + "odrl:type": "USE" + }, + "odrl:constraint": { + "odrl:or": { + "odrl:leftOperand": "BusinessPartnerNumber", + "odrl:operator": { + "@id": "odrl:eq" + }, + "odrl:rightOperand": "BPNL00000003AZQP" + } + } + }, + "odrl:prohibition": [], + "odrl:obligation": [] + + }, "callbackAddresses": [] }' | jq ``` + +curl -L -X POST 'http://dataconsumer-1-controlplane.tx.test/management/v2/edrs' \ + -H 'Content-Type: application/json' \ + -H 'X-Api-Key: TEST1' \ + --data-raw '{ + "@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": "ContractRequest", + "counterPartyAddress": "http://dataprovider-controlplane.tx.test/api/v1/dsp", + "protocol": "dataspace-protocol-http", + "policy": { + "assigner": "BPNL00000003AYRE", + "target": "700", + "@id": "MjIwMA==:NzAw:OGQ1MmZjOWQtYWE1Yy00NTc2LWI5NjYtZGNkODRmYmQzNGM3", + "@type": "odrl:Offer", + "odrl:permission": { + "odrl:action": { + "odrl:type": "USE" + }, + "odrl:constraint": { + "odrl:or": { + "odrl:leftOperand": "BusinessPartnerNumber", + "odrl:operator": { + "@id": "odrl:eq" + }, + "odrl:rightOperand": "BPNL00000003AZQP" + } + } + }, + "odrl:prohibition": [], + "odrl:obligation": [] + + + }, + "callbackAddresses": [] + }' | jq + + + + + ### EDR response ```json @@ -179,11 +240,9 @@ curl -L -X GET 'http://dataconsumer-1-controlplane.tx.test/management/v2/edrs/bd "tx-auth:refreshEndpoint": "http://dataprovider-dataplane.tx.test/api/public/token", "tx-auth:audience": "did:web:ssi-dim-wallet-stub.tx.test:BPNL00000003AZQP", "type": "https://w3id.org/idsa/v4.1/HTTP", - // highlight-next-line "endpoint": "http://dataprovider-dataplane.tx.test/api/public", "tx-auth:refreshToken": "eyJraWQiOiJ0b2tlblNpZ25lclB1YmxpY0tleSIsImFsZyI6IlJTMjU2In0.eyJleHAiOjE3MzI3MjY0ODksImlhdCI6MTczMjcyNjE4OSwianRpIjoiODA2OTAwYmQtNGY4MS00MzhmLTgyMjYtZDc2ZjkzMmY2MjI1In0.JpTIrOJv609vX86i-y-O8sQcKoTJcWvipC6jyBgWqcEIMWm4dmm4T72z-Z68l1X7QnVq1Ak8JB-fA05ONNL1JjU0W7j6rJK01M2Xo641RpecimxuFhlnld55CPks2wRbbbzHADn8kpqRf2dtNrnsiuRsnzAi6KAkFAEHLB7eLjceNbkk6df3hJrLfnn0DZ6M-OR0O05SgtEyHFsyMpf4OALQwVREIkC7LBTWn7nYCpmzK4ilrL3eM5ZRrbweQ96Tbwi-rfPfp-ptnelO_GGnqzyQef2DN5Eg4P5QZV4QX62Bw0eoYVncgCP6ZKibymnlASG0xHwgEJitu3ZSxBXt-w", "tx-auth:expiresIn": "300", - // highlight-next-line "authorization": "eyJraWQiOiJ0b2tlblNpZ25lclB1YmxpY0tleSIsImFsZyI6IlJTMjU2In0.eyJpc3MiOiJCUE5MMDAwMDAwMDNBWVJFIiwiYXVkIjoiQlBOTDAwMDAwMDAzQVpRUCIsInN1YiI6IkJQTkwwMDAwMDAwM0FZUkUiLCJleHAiOjE3MzI3MjY0ODksImlhdCI6MTczMjcyNjE4OSwianRpIjoiODRkZDIxOGItMzk1ZC00YmExLTg2OWUtOWYzMjI3ZWM0NWFlIn0.jTKEv8Fh75W1JOwrFUo1wyLdUOyBn3g500dWNUbaEC_bgASPImXfXnY3rhIVr_hrFY-anJIB_a6SkpTWb7lycCh2dcMaOmUVgmdKTcEvTr2blAXD_WUZTQYxHDVsMuPXDbX-30tYM4KVPOyemfe7IreB38n104j_SLo2Dr1BrbN9xU7mUm6DeKv1oi0TFRxnmhwnRx4hK1eBYIO-FuA9h1RDvfLWXW5yF55KkkrRTjX2HKqVPAtHInMZBRDhqB298N_VLpwQMtg9nkElzNWIUqEV4zQ1YLSsGNLSxog7JwuL3Tvy1VCOkzDkr6K89Z4IWEF0GzPjXO6Z-li_Vv7DVw", "tx-auth:refreshAudience": "did:web:ssi-dim-wallet-stub.tx.test:BPNL00000003AZQP", "@context": { @@ -204,8 +263,7 @@ Using the endpoint and authorization token from the response, Alice fetches the ### Fetch data request ```bash -curl -L -X GET 'http://dataprovider-dataplane.tx.test/api/public' \ - // highlight-next-line +curl -L -X GET 'http://dataprovider-dataplane.tx.test/api/public/urn:uuid:b77c6d51-cd1f-4c9d-b5d4-091b22dd306b' \ -H 'Authorization: eyJraWQiOiJ0b2tlblNpZ25lclB1YmxpY0tleSIsImFsZyI6IlJTMjU2In0.eyJpc3MiOiJCUE5MMDAwMDAwMDNBWVJFIiwiYXVkIjoiQlBOTDAwMDAwMDAzQVpRUCIsInN1YiI6IkJQTkwwMDAwMDAwM0FZUkUiLCJleHAiOjE3MzI3MjY0ODksImlhdCI6MTczMjcyNjE4OSwianRpIjoiODRkZDIxOGItMzk1ZC00YmExLTg2OWUtOWYzMjI3ZWM0NWFlIn0.jTKEv8Fh75W1JOwrFUo1wyLdUOyBn3g500dWNUbaEC_bgASPImXfXnY3rhIVr_hrFY-anJIB_a6SkpTWb7lycCh2dcMaOmUVgmdKTcEvTr2blAXD_WUZTQYxHDVsMuPXDbX-30tYM4KVPOyemfe7IreB38n104j_SLo2Dr1BrbN9xU7mUm6DeKv1oi0TFRxnmhwnRx4hK1eBYIO-FuA9h1RDvfLWXW5yF55KkkrRTjX2HKqVPAtHInMZBRDhqB298N_VLpwQMtg9nkElzNWIUqEV4zQ1YLSsGNLSxog7JwuL3Tvy1VCOkzDkr6K89Z4IWEF0GzPjXO6Z-li_Vv7DVw' ``` @@ -213,10 +271,35 @@ curl -L -X GET 'http://dataprovider-dataplane.tx.test/api/public' \ ```json { - "userId": 1, - "id": 3, - "title": "fugiat veniam minus", - "completed": false + "parentParts": [ + { + "validityPeriod": { + "validFrom": "2023-03-21T08:47:14.438+01:00", + "validTo": "2024-08-02T09:00:00.000+01:00" + }, + "parentCatenaXId": "urn:uuid:0733946c-59c6-41ae-9570-cb43a6e4c79e", + "quantity": { + "quantityNumber": 2.5, + "measurementUnit": "unit:litre" + }, + "createdOn": "2022-02-03T14:48:54.709Z", + "lastModifiedOn": "2022-02-03T14:48:54.709Z" + }, + { + "validityPeriod": { + "validFrom": "2023-03-21T08:47:14.438+01:00", + "validTo": "2024-08-02T09:00:00.000+01:00" + }, + "parentCatenaXId": "urn:uuid:68904173-ad59-4a77-8412-3e73fcafbd8b", + "quantity": { + "quantityNumber": 2.5, + "measurementUnit": "unit:litre" + }, + "createdOn": "2022-02-03T14:48:54.709Z", + "lastModifiedOn": "2022-02-03T14:48:54.709Z" + } + ], + "catenaXId": "urn:uuid:2c57b0e9-a653-411d-bdcd-64787e9fd3a7" } ``` diff --git a/docs/tutorials/e2e/boost/provideData.md b/docs/tutorials/e2e/boost/provideData.md index cf7535613a9..dcdf4493369 100644 --- a/docs/tutorials/e2e/boost/provideData.md +++ b/docs/tutorials/e2e/boost/provideData.md @@ -63,11 +63,10 @@ curl -L -X POST 'http://dataprovider-controlplane.tx.test/management/v3/assets' "@type": "DataAddress", "type": "HttpData", "proxyPath": "true", - "type": "HttpData", "proxyMethod": "true", "proxyQueryParams": "true", "proxyBody": "true", - "baseUrl": "https://dataprovider-submodelserver.tx.test" + "baseUrl": "http://dataprovider-submodelserver.tx.test" } }' | jq ``` From 6288d158cf0b0b4f7129092c5b21e7c95658cbef Mon Sep 17 00:00:00 2001 From: Stephan Bauer Date: Thu, 19 Dec 2024 08:24:15 +0100 Subject: [PATCH 13/14] delete redundante information forward to umbrella repository --- docs/tutorials/e2e/CHANGELOG.md | 10 + docs/tutorials/e2e/boost/boost.md | 11 + docs/tutorials/e2e/boost/consumeData.md | 319 --------- docs/tutorials/e2e/boost/dtrTutorial.md | 433 ------------ docs/tutorials/e2e/boost/provideData.md | 645 ------------------ docs/tutorials/e2e/boost/restrictData.md | 372 ---------- .../tutorials/e2e/connect/deployComponents.md | 589 +--------------- 7 files changed, 28 insertions(+), 2351 deletions(-) delete mode 100644 docs/tutorials/e2e/boost/consumeData.md delete mode 100644 docs/tutorials/e2e/boost/dtrTutorial.md delete mode 100644 docs/tutorials/e2e/boost/provideData.md delete mode 100644 docs/tutorials/e2e/boost/restrictData.md diff --git a/docs/tutorials/e2e/CHANGELOG.md b/docs/tutorials/e2e/CHANGELOG.md index 926309322df..e7eeddd92a4 100644 --- a/docs/tutorials/e2e/CHANGELOG.md +++ b/docs/tutorials/e2e/CHANGELOG.md @@ -4,6 +4,16 @@ All notable changes to this tutorial will be documented in this file. +## [1.1.0] - 2024-12-19 + +### Changed + +:::note +Most of the content is redundant to [umbrella repository](https://github.com/eclipse-tractusx/tractus-x-umbrella) and related [description](https://github.com/eclipse-tractusx/tractus-x-umbrella/blob/main/docs/README.md) +::: + +- Delete redundant content and forward to umbrella helm chart description + ## [1.0.0] - 2024-06-24 ### Added diff --git a/docs/tutorials/e2e/boost/boost.md b/docs/tutorials/e2e/boost/boost.md index 1aba1377104..a7987d8bd38 100644 --- a/docs/tutorials/e2e/boost/boost.md +++ b/docs/tutorials/e2e/boost/boost.md @@ -17,6 +17,17 @@ In this **Boost Chapter**, you will create and request different assets and lear By the end of this chapter, you will have the foundational knowledge needed to share data within your data space. +:::note + +This chapter is described within the guides for the Tractus-X umbrella charts following the [link](https://github.com/eclipse-tractusx/tractus-x-umbrella/blob/main/docs/README.md) + +Important chapters are: +- [Data Exchange](https://github.com/eclipse-tractusx/tractus-x-umbrella/blob/main/docs/user/guides/data-exchange.md) + - [Provide Data](https://github.com/eclipse-tractusx/tractus-x-umbrella/blob/main/docs/user/guides/data-exchange/provide-data.md) + - [Consume Data](https://github.com/eclipse-tractusx/tractus-x-umbrella/blob/main/docs/user/guides/data-exchange/consume-data.md) + +::: + ## Notice This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). diff --git a/docs/tutorials/e2e/boost/consumeData.md b/docs/tutorials/e2e/boost/consumeData.md deleted file mode 100644 index d4a78167802..00000000000 --- a/docs/tutorials/e2e/boost/consumeData.md +++ /dev/null @@ -1,319 +0,0 @@ ---- -title: Consume data -sidebar_position: 3 ---- - -This step continues the journey of our data consumer Alice. After the data provider Bob has successfully provided his data as a contract definition in his catalog. Alice will now consume the data. - -We will use plain CLI tools (`curl`) for this, but feel free to use graphical tools such as Postman or Insomnia. - -## Step 1: Request the catalog - -To see Bob's data offerings, Alice must request access to his catalog. The catalog shows all the assets that Alice can consume from Bob. - -### Catalog request (Alice) - -```shell -curl -L -X POST 'http://dataconsumer-1-controlplane.tx.test/management/v2/catalog/request' \ - -H 'Content-Type: application/json' \ - -H 'X-Api-Key: TEST1' \ - --data-raw '{ - "@context": { - "@vocab": "https://w3id.org/edc/v0.0.1/ns/" - }, - "@type": "CatalogRequest", - "counterPartyAddress": "http://dataprovider-controlplane.tx.test/api/v1/dsp", - "counterPartyId": "BPNL00000003AYRE", - "protocol": "dataspace-protocol-http", - "querySpec": { - "offset": 0, - "limit": 50 - } - }' | jq -``` - -### Catalog response - -The highlighted line represents the offer id, which is important for later steps. - -```json -{ - "@id": "200", - "@type": "dcat:Dataset", - "odrl:hasPolicy": { - // highlight-next-line - "@id": "MjAw:MjAw:Y2ZjMzdlNmUtODAwNi00NGJjLWJhMWYtNjJkOWIzZWM0ZTQ3", - "@type": "odrl:Offer", - "odrl:permission": { - "odrl:action": { - "odrl:type": "USE" - }, - "odrl:constraint": { - "odrl:or": { - "odrl:leftOperand": "BusinessPartnerNumber", - "odrl:operator": { - "@id": "odrl:eq" - }, - "odrl:rightOperand": "BPNL00000003AZQP" - } - } - } - } -} -``` - -## Step 2: Initiate an edr - -To consume the data, Alice uses the offer ID from the catalog response (`MjAw:MjAw:Y2ZjMzdlNmUtODAwNi00NGJjLWJhMWYtNjJkOWIzZWM0ZTQ3`) and the target asset ID (`200`) to initiate an EDR. - -### EDR request - -```shell -curl -L -X POST 'http://dataconsumer-1-controlplane.tx.test/management/v2/edrs' \ - -H 'Content-Type: application/json' \ - -H 'X-Api-Key: TEST1' \ - --data-raw '{ - "@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": "ContractRequest", - "counterPartyAddress": "http://dataprovider-controlplane.tx.test/api/v1/dsp", - "protocol": "dataspace-protocol-http", - "policy": { - "assigner": "BPNL00000003AYRE", - "target": "200", - "@id": "MjAw:MjAw:Y2ZjMzdlNmUtODAwNi00NGJjLWJhMWYtNjJkOWIzZWM0ZTQ3", - "@type": "odrl:Offer", - "odrl:permission": { - "odrl:action": { - "odrl:type": "USE" - }, - "odrl:constraint": { - "odrl:or": { - "odrl:leftOperand": "BusinessPartnerNumber", - "odrl:operator": { - "@id": "odrl:eq" - }, - "odrl:rightOperand": "BPNL00000003AZQP" - } - } - }, - "odrl:prohibition": [], - "odrl:obligation": [] - - - }, - "callbackAddresses": [] - }' | jq -``` - - -curl -L -X POST 'http://dataconsumer-1-controlplane.tx.test/management/v2/edrs' \ - -H 'Content-Type: application/json' \ - -H 'X-Api-Key: TEST1' \ - --data-raw '{ - "@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": "ContractRequest", - "counterPartyAddress": "http://dataprovider-controlplane.tx.test/api/v1/dsp", - "protocol": "dataspace-protocol-http", - "policy": { - "assigner": "BPNL00000003AYRE", - "target": "700", - "@id": "MjIwMA==:NzAw:OGQ1MmZjOWQtYWE1Yy00NTc2LWI5NjYtZGNkODRmYmQzNGM3", - "@type": "odrl:Offer", - "odrl:permission": { - "odrl:action": { - "odrl:type": "USE" - }, - "odrl:constraint": { - "odrl:or": { - "odrl:leftOperand": "BusinessPartnerNumber", - "odrl:operator": { - "@id": "odrl:eq" - }, - "odrl:rightOperand": "BPNL00000003AZQP" - } - } - }, - "odrl:prohibition": [], - "odrl:obligation": [] - - - }, - "callbackAddresses": [] - }' | jq - - - - - -### EDR response - -```json -{ - "@type": "IdResponse", - // highlight-next-line - "@id": "4b260501-ae2f-46f4-9efc-01ba5a0b3d96", - "createdAt": 1732726185609, - "@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/" - } -} -``` - -## Step 3: Query cached edrs - -Alice now queries cached EDRs using the contract negotiation ID (`4b260501-ae2f-46f4-9efc-01ba5a0b3d96`) from the previous response. - -### Query edrs request - -```shell -curl -L -X POST 'http://dataconsumer-1-controlplane.tx.test/management/v2/edrs/request' \ - -H 'Content-Type: application/json' \ - -H 'X-Api-Key: TEST1' \ - --data-raw '{ - "@context": { "@vocab": "https://w3id.org/edc/v0.0.1/ns/" }, - "@type": "QuerySpec", - "filterExpression": [ - { - "operandLeft": "contractNegotiationId", - "operator": "=", - // highlight-next-line - "operandRight": "4b260501-ae2f-46f4-9efc-01ba5a0b3d96" - } - ] - }' | jq -``` - -### Query edrs response - -```json -{ - "@id": "bdd4af10-9e4a-4796-b4b7-7ecdf91a533a", - "@type": "EndpointDataReferenceEntry", - "providerId": "BPNL00000003AYRE", - "assetId": "200", - "agreementId": "2ece6f45-ff09-4417-b5a9-a92a1849f1d0", - "transferProcessId": "bdd4af10-9e4a-4796-b4b7-7ecdf91a533a", - "createdAt": 1732726189831, - "contractNegotiationId": "4b260501-ae2f-46f4-9efc-01ba5a0b3d96", - "@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/" - } -} -``` - -## Step 4: Get authorization details - -Alice uses the transfer process ID (`bdd4af10-9e4a-4796-b4b7-7ecdf91a533a`) to get authorization details. - -### Authorization request - -```bash -curl -L -X GET 'http://dataconsumer-1-controlplane.tx.test/management/v2/edrs/bdd4af10-9e4a-4796-b4b7-7ecdf91a533a/dataaddress?auto_refresh=true' \ - -H 'Content-Type: application/json' \ - -H 'X-Api-Key: TEST1' | jq -``` - -### Authorization response - -```json -{ - "@type": "DataAddress", - "endpointType": "https://w3id.org/idsa/v4.1/HTTP", - "tx-auth:refreshEndpoint": "http://dataprovider-dataplane.tx.test/api/public/token", - "tx-auth:audience": "did:web:ssi-dim-wallet-stub.tx.test:BPNL00000003AZQP", - "type": "https://w3id.org/idsa/v4.1/HTTP", - "endpoint": "http://dataprovider-dataplane.tx.test/api/public", - "tx-auth:refreshToken": "eyJraWQiOiJ0b2tlblNpZ25lclB1YmxpY0tleSIsImFsZyI6IlJTMjU2In0.eyJleHAiOjE3MzI3MjY0ODksImlhdCI6MTczMjcyNjE4OSwianRpIjoiODA2OTAwYmQtNGY4MS00MzhmLTgyMjYtZDc2ZjkzMmY2MjI1In0.JpTIrOJv609vX86i-y-O8sQcKoTJcWvipC6jyBgWqcEIMWm4dmm4T72z-Z68l1X7QnVq1Ak8JB-fA05ONNL1JjU0W7j6rJK01M2Xo641RpecimxuFhlnld55CPks2wRbbbzHADn8kpqRf2dtNrnsiuRsnzAi6KAkFAEHLB7eLjceNbkk6df3hJrLfnn0DZ6M-OR0O05SgtEyHFsyMpf4OALQwVREIkC7LBTWn7nYCpmzK4ilrL3eM5ZRrbweQ96Tbwi-rfPfp-ptnelO_GGnqzyQef2DN5Eg4P5QZV4QX62Bw0eoYVncgCP6ZKibymnlASG0xHwgEJitu3ZSxBXt-w", - "tx-auth:expiresIn": "300", - "authorization": "eyJraWQiOiJ0b2tlblNpZ25lclB1YmxpY0tleSIsImFsZyI6IlJTMjU2In0.eyJpc3MiOiJCUE5MMDAwMDAwMDNBWVJFIiwiYXVkIjoiQlBOTDAwMDAwMDAzQVpRUCIsInN1YiI6IkJQTkwwMDAwMDAwM0FZUkUiLCJleHAiOjE3MzI3MjY0ODksImlhdCI6MTczMjcyNjE4OSwianRpIjoiODRkZDIxOGItMzk1ZC00YmExLTg2OWUtOWYzMjI3ZWM0NWFlIn0.jTKEv8Fh75W1JOwrFUo1wyLdUOyBn3g500dWNUbaEC_bgASPImXfXnY3rhIVr_hrFY-anJIB_a6SkpTWb7lycCh2dcMaOmUVgmdKTcEvTr2blAXD_WUZTQYxHDVsMuPXDbX-30tYM4KVPOyemfe7IreB38n104j_SLo2Dr1BrbN9xU7mUm6DeKv1oi0TFRxnmhwnRx4hK1eBYIO-FuA9h1RDvfLWXW5yF55KkkrRTjX2HKqVPAtHInMZBRDhqB298N_VLpwQMtg9nkElzNWIUqEV4zQ1YLSsGNLSxog7JwuL3Tvy1VCOkzDkr6K89Z4IWEF0GzPjXO6Z-li_Vv7DVw", - "tx-auth:refreshAudience": "did:web:ssi-dim-wallet-stub.tx.test:BPNL00000003AZQP", - "@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/" - } -} -``` - -## Step 5: Fetch data - -Using the endpoint and authorization token from the response, Alice fetches the data. - -### Fetch data request - -```bash -curl -L -X GET 'http://dataprovider-dataplane.tx.test/api/public/urn:uuid:b77c6d51-cd1f-4c9d-b5d4-091b22dd306b' \ - -H 'Authorization: eyJraWQiOiJ0b2tlblNpZ25lclB1YmxpY0tleSIsImFsZyI6IlJTMjU2In0.eyJpc3MiOiJCUE5MMDAwMDAwMDNBWVJFIiwiYXVkIjoiQlBOTDAwMDAwMDAzQVpRUCIsInN1YiI6IkJQTkwwMDAwMDAwM0FZUkUiLCJleHAiOjE3MzI3MjY0ODksImlhdCI6MTczMjcyNjE4OSwianRpIjoiODRkZDIxOGItMzk1ZC00YmExLTg2OWUtOWYzMjI3ZWM0NWFlIn0.jTKEv8Fh75W1JOwrFUo1wyLdUOyBn3g500dWNUbaEC_bgASPImXfXnY3rhIVr_hrFY-anJIB_a6SkpTWb7lycCh2dcMaOmUVgmdKTcEvTr2blAXD_WUZTQYxHDVsMuPXDbX-30tYM4KVPOyemfe7IreB38n104j_SLo2Dr1BrbN9xU7mUm6DeKv1oi0TFRxnmhwnRx4hK1eBYIO-FuA9h1RDvfLWXW5yF55KkkrRTjX2HKqVPAtHInMZBRDhqB298N_VLpwQMtg9nkElzNWIUqEV4zQ1YLSsGNLSxog7JwuL3Tvy1VCOkzDkr6K89Z4IWEF0GzPjXO6Z-li_Vv7DVw' -``` - -### Fetch data response - -```json -{ - "parentParts": [ - { - "validityPeriod": { - "validFrom": "2023-03-21T08:47:14.438+01:00", - "validTo": "2024-08-02T09:00:00.000+01:00" - }, - "parentCatenaXId": "urn:uuid:0733946c-59c6-41ae-9570-cb43a6e4c79e", - "quantity": { - "quantityNumber": 2.5, - "measurementUnit": "unit:litre" - }, - "createdOn": "2022-02-03T14:48:54.709Z", - "lastModifiedOn": "2022-02-03T14:48:54.709Z" - }, - { - "validityPeriod": { - "validFrom": "2023-03-21T08:47:14.438+01:00", - "validTo": "2024-08-02T09:00:00.000+01:00" - }, - "parentCatenaXId": "urn:uuid:68904173-ad59-4a77-8412-3e73fcafbd8b", - "quantity": { - "quantityNumber": 2.5, - "measurementUnit": "unit:litre" - }, - "createdOn": "2022-02-03T14:48:54.709Z", - "lastModifiedOn": "2022-02-03T14:48:54.709Z" - } - ], - "catenaXId": "urn:uuid:2c57b0e9-a653-411d-bdcd-64787e9fd3a7" -} -``` - -:::tip congratulations -your data has been successfully transfered! -::: - -## Notice - -This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). - -- SPDX-License-Identifier: CC-BY-4.0 -- SPDX-FileCopyrightText: 2023 sovity GmbH -- SPDX-FileCopyrightText: 2023 SAP SE -- SPDX-FileCopyrightText: 2023 msg systems AG -- SPDX-FileCopyrightText: 2023 Materna Information & Communications SE -- Source URL: [https://github.com/eclipse-tractusx/eclipse-tractusx.github.io](https://github.com/eclipse-tractusx/eclipse-tractusx.github.io) diff --git a/docs/tutorials/e2e/boost/dtrTutorial.md b/docs/tutorials/e2e/boost/dtrTutorial.md deleted file mode 100644 index 84fd0c782f2..00000000000 --- a/docs/tutorials/e2e/boost/dtrTutorial.md +++ /dev/null @@ -1,433 +0,0 @@ ---- -title: DTR Tutorial -sidebar_position: 5 ---- - -## Tutorial Goal - -Alongside the connector, the Digital Twin Registry (DTR) is an important decentral component deployed by each data provider exchanging digital twins in Catena-X. They must register them in a DTR so that consumers can find relevant data in the provider's data offers. - -This tutorial focuses on the working with the DTR. You will learn what the DTR is, how to deploy it and go through a complete use case scenario by depositing a DTR in the EDC, registering a digital twin in the DTR, and showing how external parties can find and consume the digital twin. - -## Introduction - -Catena-X uses the Asset Administration Shell (AAS) to represent digital twins. Such a digital twin is basically a shell with an ID (usually a UUID) that makes it uniquely identifiable. Also it contains IDs ("specificAssetIds") that connect the shell with the original asset it represents (e.g. the "manufacturerPartId"). The shell also contains SubmodelDescriptors which reference to submodels that contain the actual data of specific aspects of the asset. - -The Digital Twin Registry (DTR) contains a list of all registered digital twins of the owner and therefore acts as an address book for Digital Twins. With the DTR of a data provider, a data consumer can therefore find digital twin and also get directed to the desired submodels of the twin. - -Further details can be found in the [Digital Twin KIT][dt-kit] or the [sldt-digital-twin-registry][sldt-dtr] Github repository. - -In this tutorial, Bob will assume the role of an automotive supplier that manufactures gearboxes and acts as the data provider. Alice represents an OEM that uses these gearboxes. Alice's goal is to calculate the product carbon footprint (PCF) of a car, and she also needs the carbon footprints of the individual parts to calculate the total footprint. Therefore, Alice is the data consumer in this tutorial. - -The steps of the tutorial are as follows - -- Bob registers a DTR at his EDC -- Bob registers a Digital Twin at his DTR -- Alice finds and consumes the Digital Twin - -This tutorial will guide you through the steps outlined above. For a deeper understanding, more detailed documentation will be linked. - -### High Level Architecture - -## Exchange Digital Twins - -### Register a DTR in your EDC - -#### Create the DTR asset - -To ensure that Bob's DTR becomes visible for Alice and to start the data exchange between them, Bob has to create a data asset. - -Action (Bob): Create a data asset using the following command: - -(note: that the "asset:prop:type" is standardized with "data.core.digitalTwinRegistry" for the Digital Twin Registry.) - -```curl --location 'http://dataprovider-controlplane.tx.test/management/v3/assets' \ ---header 'Content-Type: application/json' \ ---header 'X-Api-Key: TEST2' \ ---data-raw '{ - "@context":{ - "edc":"https://w3id.org/edc/v0.0.1/ns/", - "cx-common":"https://w3id.org/catenax/ontology/common#", - "cx-taxo":"https://w3id.org/catenax/taxonomy#", - "dct":"http://purl.org/dc/terms/" - }, - "@id":"{{ASSET_ID}}", - "properties":{ - "dct:type":{ - "@id":"cx-taxo:DigitalTwinRegistry" - } - }, - "dataAddress":{ - "@type":"DataAddress", - "type":"HttpData", - "baseUrl":"{{BACKEND_SERVICE}}", - "proxyPath":"true", - "proxyBody":"true", - "proxyMethod":"false", - "proxyQueryParams":"true", - "oauth2:clientId":"satest02", - "oauth2:clientSecretKey":"{{REGISTRY_CLIENT_SECRET_KEY}}", - "oauth2:tokenUrl":"http://centralidp.tx.test/auth/realms/CX-Central/protocol/openid-connect/token", - "oauth2:scope":"{{REGISTRY_TOKEN_SCOPE}}" - } -}' -``` - -As per the current standards, there is no need to proxy the HTTP method. If there is (for instance due to a proprietary query endpoint), the data provider must ensure thatthat the technical user that the registered credentials abstract does NOT have the power to manipulate the DTR's data (for instance via the `PUT /shell-descriptors/{{aasId}}` API. - -#### Create a policy - -After Bob has created an data asset, he must define a BPN-restrictive policy in order to give Alice access to the asset. This policy is not standardized and can be chosen according to its needs. Bob wants to define the policy that only Alice can see the DTR Asset. - -Action (Bob): Defines the access policy using the following command: - -```curl -{ - "@context": { - "odrl": "http://www.w3.org/ns/odrl/2/" - }, - "@type": "PolicyDefinitionRequestDto", - "@id": "{{POLICY_ID}}", - "policy": { - "@type": "Policy", - "odrl:permission" : [{ - "odrl:action" : "USE", - "odrl:constraint" : { - "@type": "LogicalConstraint", - "odrl:or" : [{ - "@type" : "Constraint", - "odrl:leftOperand" : "BusinessPartnerNumber", - "odrl:operator" : { - "@id": "odrl:eq" - }, - "odrl:rightOperand" : "{{CONSUMER_BPN}}" - }] - } - }] - } -} -``` - -#### Contract Definition - -To offer the DTR in his EDC Catalog, Bob has to create a contract definition. This contains linking the data asset with the policy. - -Action (Bob): Create the contract policy using the following command: - -```curl -{ - "@context": {}, - "@id": "{{CONTRACT_DEFINITION_ID}}", - "@type": "ContractDefinition", - "accessPolicyId": "{{ACCESS_POLICY_ID}}", - "contractPolicyId": "{{CONTRACT_POLICY_ID}}", - "assetsSelector" : { - "@type" : "CriterionDto", - "operandLeft": "{{EDC_NAMESPACE}}id", - "operator": "=", - "operandRight": "{{ASSET_ID}}" - } -} -``` - -The DTR Asset from Bob is now available for Alice to request via contract negotiation. Currently it is still empty. Therefore Bob will register his first digital twin in the next step of this tutorial. - -Continue the tutorial in [Register a Digital](#register-a-digital-twin) Twin. - -### Register a Digital Twin - -The basic steps for providing digital twins with the DTR contain: - -- Create a compliant submodel -- Store the submodel on a submodel server -- Register/create a digital twin at the DTR -- Reference the Submodel in the digital twin - -#### Create a submodel - -Submodels needs to be compliant to the domain specified standards. Bob has already prepaired the submodel he wants to share with Alice. Thefore the first step is already taken care of. - -#### Host/store a submodel - -Bob also needs to store his submodels somewhere. Usually a submodel server is used for this task. For this tutorial a service called "backend-data-service" (short BDS) is provided. This service fulfills the role of the submodel server. It can store any text based data (e.g. JSON, XML, plain text) under a specific ID. This data can be received again, by using the same ID. Bob will use this service to host his data. - -Action (Bob): Store submodel on the BDS using the following command: - -```curl -id="bobs-data" -bdsBaseUrl="http://localhost/bobs-bds" -clusterInternalBdsBaseUrl="http://bobs-bds-bds" - -curl -i -X POST "${bdsBaseUrl}/data/${id}" -H "Content-Type: application/json" --data-raw '{ - "diameter": 380, - "length": 810, - "width": 590, - "weight": 85, - "height": 610 -}' -``` - -#### Create Contract Definition at EDC with the submodel - -Bob has now stored his submodel on the BDS. However, because he wants to preserve data sovereignty over his data, he cannot directly provide access to the BDS. Instead, the data exchange shall take place via the EDC. - -Therefore Bob needs to create an according contract definition. This follows the same three steps as explained in "Create DTR Asset" of creating an data asset, creating a policy and finally creating the contract definition. - -Info: - -edcManagementBaseUrl="" -edcApiKey="password" - -```bash -# Asset -# assetId="$(uuidgen)" -assetId="0bc6a8af-8682-4dba-86b1-0433f9762e42" -clusterInternalBdsBaseUrl="http://bobs-bds-bds:8080" -bdsDataId="bobs-data" -assetUrl="${clusterInternalBdsBaseUrl}/data/${bdsDataId}" - -# Policy -# policyId="$(uuidgen)" -policyId="1bc6a8af-8682-4dba-86b1-0433f9762e42" - -# Contract Definition -# contractDefinitionId="$(uuidgen)" -contractDefinitionId="2bc6a8af-8682-4dba-86b1-0433f9762e42" -``` - -Action (Bob): Create a data asset with the following commands: - -```curl -curl -i -X POST "${edcManagementBaseUrl}/v3/assets" -H "X-Api-Key: ${edcApiKey}" -H "Content-Type: application/json" --data-raw "{ - \"@context\": {}, - \"@id\": \"${assetId}\", - \"properties\": { - \"description\": \"Product EDC Demo Asset\" - }, - \"dataAddress\": { - \"@type\": \"DataAddress\", - \"baseUrl\": \"${assetUrl}\", - \"type\": \"HttpData\" - } -}" | jq -``` - -Action (Bob): Create a Policy with the following commands: - -```curl -curl -i -X POST "${edcManagementBaseUrl}/v2/policydefinitions" -H "X-Api-Key: ${edcApiKey}" -H "Content-Type: application/json" --data-raw "{ - \"@context\": { - \"odrl\": \"http://www.w3.org/ns/odrl/2/\" - }, - \"@type\": \"PolicyDefinitionRequestDto\", - \"@id\": \"${policyId}\", - \"policy\": { - \"@type\": \"Policy\", - \"odrl:permission\": [{ - \"odrl:action\": \"USE\", - \"odrl:constraint\": { - \"@type\": \"LogicalConstraint\", - \"odrl:or\": [] - } - }] - } -}" | jq -``` - -Action (Bob): Create a contract definition with the following commands: - -```curl -curl -i -X POST "${edcManagementBaseUrl}/v2/contractdefinitions" -H "X-Api-Key: ${edcApiKey}" -H "Content-Type: application/json" --data-raw "{ - \"@context\": {}, - \"@id\": \"${contractDefinitionId}\", - \"@type\": \"ContractDefinition\", - \"accessPolicyId\": \"${policyId}\", - \"contractPolicyId\": \"${policyId}\", - \"assetsSelector\" : { - \"@type\" : \"CriterionDto\", - \"operandLeft\": \"https://w3id.org/edc/v0.0.1/ns/id\", - \"operator\": \"=\", - \"operandRight\": \"${assetId}\" - } -}" | jq -``` - -The submodel is now stored at the BDS and made available through a contract definition at the EDC. - -### Access control to Digital Twins Based on the BPN (Business Partner Number)/ TenantId - -The digital twin registry offers two functionalities for managing access control to digital twins (Shells) based on the Business Partner Number (BPN). -On application start, the provider can configure which kind of access control will be activated. - -1. Classic implementation (default is true). This implementation is used for this tutorial: - 1. The visibility of `specificAssetIds` in the Digital Twin Registry based on the Business Partner Number (BPN) (Which is send via header Edc-Bpn) can be controlled with the attribute `externalSubjectId`. Hence, the `externalSubjectId` is identified with the BPN. - 2. The communication between consumer and provider is via EDC. Before the provider EDC sends the request to the DTR, the property Edc-Bpn with the BPN of the consumer will be set by the provider EDC. -2. Granular access control implementation: - 1. The granular access control implementation is provided as an alternative option to enforce visibility rules of the *Digital Twin* details. These can be: - 1. The visibility of the *Digital Twin* as a whole - 2. The visibility of certain `specificAssetId` names and values of the *Digital Twin* - 3. The visibility of certain `submodelDescriptors` of the *Digital Twin* - 4. Restricting access to *Digital Twin* details which are `"PUBLIC_READABLE"` - (only showing the `id`, the public readable `specificAssetId` names and values, the `createdDate` and the filtered `submodelDescriptors` ) - 5. To enable granular access control (instead of the classic implementation), the `registry.useGranularAccessControl` configuration HELM chart property must be set to `"true"`. - -For more details see: [DTR Access control to Digital Twins Based on the BPN (Business Partner Number)/ TenantId](https://github.com/eclipse-tractusx/sldt-digital-twin-registry/blob/main/docs/README.md#:~:text=dev%40eclipse.org-,Access,-control%20to%20Digital) - -#### Register/create a Digital Twin at the DTR - -Now that Bob has stored his submodel at the BDS and offered it at the EDC for sovereign data exchange, he wants to make it findable via the DTR. This contains two steps: - -- Register/create a Digital Twin at the DTR -- Reference the submodel in the Digital Twin - -The registration of a digital twin in Catena-X is equivalent to the creation of a new digital twin. Thus, Bob should always ensure that there is no digital twin created for the respective “specificAssetIds” yet to avoid duplicates. - -Action (Bob): Create a new digital twin at the DTR with the following command: - -```curl -POST /shell-descriptors -{ - "id": "urn:uuid:e5c96ab5-896a-1234-8761-efd74777ca97", - "idShort": "myAas", - "specificAssetIds": [ - { - "name": "manufacturerPartId", - "value": "123-345-567103", - "externalSubjectId": { - "type": "ExternalReference", - "keys": [ - { - "type": "GlobalReference", - "value": "{{BPN of the party privileged}}" - } - ] - } - } - ] -} - ``` - -Bob has now successfully created/registered a Digital Twin at his DTR. Right now the Digital Twin is pretty empty, except the AAS-ID and the specificAssetIds. -Thus, the next step for Bob is to reference his submodel in the Digital Twin to make it findable for consumers. - -#### Reference a Submodel in the Digital Twin - -In order to reference the submodel in the digital twin, submodel descriptors can be added to the digital twin. - -When adding a submodel to an existing digital twin, it is important to use the correct AAS-Id. This has to be added for the parameter "id", e.g. "id": "e5c96ab5-896a-482c-8761-efd74777ca97". - -To reference the endoint of the submodel we use the DSP protocol. Thus you have to provide the subprotocolBody with the Id of the asset as well as the dspEndpoint of the EDC. - -```curl -POST /shell-descriptors/{{aasId}} - -{ - "id": "e5c96ab5-896a-482c-8761-efd74777ca97", - "semanticId": { - "type": "ExternalReference", - "keys": [ - { - "type": "GlobalReference", - "value": "urn:bamm:io.catenax.material_for_recycling:1.1.0#MaterialForRecycling" - } - ] - }, - "endpoints": [ - { - "interface": "SUBMODEL-3.0", - "protocolInformation": { - "href": "https://edc.data.plane/mypath/submodel", - "endpointProtocol": "HTTP", - "endpointProtocolVersion": [ - "1.1" - ], - "subprotocol": "DSP", - "subprotocolBody": "id=123;dspEndpoint=http://edc.control.plane/api/v1/dsp", - "subprotocolBodyEncoding": "plain", - "securityAttributes": [ - { - "type": "NONE", - "key": "NONE", - "value": "NONE" - } - ] - } - } - ] -} -``` - -Bob has now successfully added a submodel descriptor to the digital twin and made the Submodel accessible for comsumption. In the next step of the tutorial Alice will find and consume the digital twin and its submodel. - -#### Registering new Submodels at existing Digital Twins - -If you want to add a submodel to an already existing digital twin, you just need to reference the ID (UUID )of the digital twin in the submodel to link the two. - -Lets also go through this process. … - -### Find and consume a Digital Twin - -Alice, the data consumer, now wants to fetch Bob's digital twin. Since she knows Bob, she knows his BPN. With this BPN, she can now determine Bob's EDC endpoint using the EDC Discovery Service. The Discovery Services are not part of this tutorial. So the tutorial starts with Alice already knowing Bob's EDC endpoint. - -In general, Alice's only responsibility is to deploy a connector, negotiate for access and terms of usage and finally fetch the data from the right offers. -A detailed interaction flow is detailed in the [Digital Twin KIT - Fetching a supplier's twin](https://eclipse-tractusx.github.io/docs-kits/kits/Digital%20Twin%20Kit/Software%20Development%20View/dt-kit-interaction-patterns#1-fetching-a-suppliers-twin). - -But step by step. First of all, Alice wants to see Bob's DTR. - -Action (Alice): Use the following API POST to find Bob's DTR Asset. - -`POST /catalog/request with filter looking for DTR` - -You will receive the `dcat:Dataset for Bob's DTR`. A negotiation for the DTR can now take place. You retrieve a token for this, which you get back in return if the negotiation is successful. - -![Step1](/tutorials/e2e/dtr-access-token.png) - -In the second step, Alice can use this access token to access Bob's DTR directly and perform a lookup there. As feedback, she receives the AAS IDs that she is authorised to see. - -Action (Alice): Use the following API GET to receive the provided AAS Ids: - -`GET /lookup/shells?assetIds=xyz` - -Alice receives a list of AAS Ids that she is allowed to see. This should include the digital twin created in the previous tutorial steps. - -![Step2](/tutorials/e2e/dtr-get-aas-ids.png) - -Now Alice can get the AAS descriptors because she now has the AAS IDs. - -Action (Alice): Use the following API GET to the shell descriptors for the AAS ID. - -`GET /shell-descriptors/{{aas-id}} with aas-id encoded base64url` - -In response, Alice receives the AAS descriptor she needs. This contains the submodel descriptors. These contain the location of the submodels. - -![Step3](/tutorials/e2e/dtr-get-descriptor.png) - -Now the process is repeating itself. Alice performs a catalog request again and can now use the dataset IDs as a filter. - -Action (Alice): Use the following API POST to receive Bob's catalog with the Dataset-ID as a filter: - -`POST /catalog/request with filter looking for Dataset-ID` - -A negotiation for the Submodel Server can now take place. Alice retrieves a token for this, which she gets back in return if the negotiation is successful. - -![Step4](/tutorials/e2e/dtr-get-token.png) - -The relevant endpoint on the submodel server can now be accessed directly, which returns the actual data in response. - -Action (Alice): Use the following API GET to receive the data: - -![Step5](/tutorials/e2e/dtr-get-data.png) - -**Congratulations, you've got a first digital twin from a customer!!!** - -## Notice - -This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). - -- SPDX-License-Identifier: CC-BY-4.0 -- SPDX-FileCopyrightText: 2024 sovity GmbH -- SPDX-FileCopyrightText: 2024 msg systems AG -- Source URL: - -[dt-kit]: https://eclipse-tractusx.github.io/docs-kits/kits/Digital%20Twin%20Kit/Software%20Development%20View/dt-kit-software-development-view/ -[sldt-dtr]: https://github.com/eclipse-tractusx/sldt-digital-twin-registry/tree/main/docs diff --git a/docs/tutorials/e2e/boost/provideData.md b/docs/tutorials/e2e/boost/provideData.md deleted file mode 100644 index dcdf4493369..00000000000 --- a/docs/tutorials/e2e/boost/provideData.md +++ /dev/null @@ -1,645 +0,0 @@ ---- -title: Provide data -sidebar_position: 2 ---- - -This tutorial guides you through the process of creating and providing data in a local dataspace using the Eclipse Dataspace Connector (EDC). You'll create an asset, -define policies, and set up a contract definition for data sharing. - -## Create your first data asset - -We will start by creating an asset that represents the data to be shared. The data provider (Bob) uses the **[Management API](https://app.swaggerhub.com/apis/eclipse-edc-bot/management-api)** to define the asset. -For better understanding, the cURL commands are provided and explained in detail for every step. For nearly every request a response is expected. - -:::tip curl explanation - -1. **URL and Method**: - - `-L`: Ensures redirections are followed if the URL returns a redirect response. - - `-X POST`: Specifies the HTTP method as `POST`. - -2. **Headers**: - - `-H 'Content-Type: application/json'`: Indicates that the payload is in JSON format. - - `-H 'X-Api-Key: TEST2'`: Sends an API key for authentication. - -3. **Payload**: - - `--data-raw`: Includes the JSON payload to be sent with the `POST` request. - -4. **Piping into `jq`**: - - The output is piped into `jq` to format and colorize the JSON response for easier reading. - -::: - -:::note -**Actors in this tutorial:** - -- **Bob**: data provider, is reachable via `http://dataprovider-controlplane.tx.test` -- **Alice**: data consumer, is reachable via `http://dataconsumer-1-controlplane.tx.test` - -::: - -### Step 1: Create the asset - -Alice, as a data consumer, wants to consume data from Bob. Bob, as a data provider, needs to create an asset for Alice. -Run the following `curl` command to create the asset: - -```shell -curl -L -X POST 'http://dataprovider-controlplane.tx.test/management/v3/assets' \ - -H 'Content-Type: application/json' \ - -H 'X-Api-Key: TEST2' \ - --data-raw '{ - "@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/" - }, - "@id": "200", - "properties": { - "description": "Product EDC Demo Asset" - }, - "dataAddress": { - "@type": "DataAddress", - "type": "HttpData", - "proxyPath": "true", - "proxyMethod": "true", - "proxyQueryParams": "true", - "proxyBody": "true", - "baseUrl": "http://dataprovider-submodelserver.tx.test" - } - }' | jq -``` - -#### Expected output - -If successful, the response should look like this: - -```json -{ - "@type": "IdResponse", - "@id": "200", - "createdAt": 1733150672368, - "@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/" - } -} -``` - -### Step 2: Validate the asset - -Check that the asset was created successfully by running the following for requesting the specific asset with ID 200: - -```bash -curl -L -X GET 'http://dataprovider-controlplane.tx.test/management/v3/assets/200' \ --H 'X-Api-Key: TEST2' | jq -``` - -Alternatively, retrieve all assets: - -```bash -curl -L -X POST 'http://dataprovider-controlplane.tx.test/management/v3/assets/request' \ --H "x-api-key: TEST2" \ --H "content-type: application/json" | jq -``` - -#### Expected output - -The result for the first command shows just the newly created asset: - -```json -{ - "@id": "200", - "@type": "Asset", - "properties": { - "description": "Product EDC Demo Asset", - "id": "200" - }, - "dataAddress": { - "@type": "DataAddress", - "type": "HttpData", - "baseUrl": "https://jsonplaceholder.typicode.com/todos/3" - }, - "@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/" - } -} -``` - -The second request will return all assets. It`s called request catalog and will be explained in the next step. - -## Request the catalog - -Once the asset is created, Alice (the data consumer) can try request a catalog of available (offered) data. - -:::note -Alice can only see the offered data if a Access Policy was assigned. -::: - -### Step 1: Request contract offers - -Alice sends a `CatalogRequest` to Bob's connector to discover available assets: - -```shell -curl -L -X POST 'http://dataconsumer-1-controlplane.tx.test/management/v2/catalog/request' \ - -H 'Content-Type: application/json' \ - -H 'X-Api-Key: TEST1' \ - --data-raw '{ - "@context": { - "@vocab": "https://w3id.org/edc/v0.0.1/ns/" - }, - "@type": "CatalogRequest", - "counterPartyAddress": "http://dataprovider-controlplane.tx.test/api/v1/dsp", - "counterPartyId": "BPNL00000003AYRE", - "protocol": "dataspace-protocol-http", - "querySpec": { - "offset": 0, - "limit": 50 - } - }' | jq -``` - -#### Expected Output - -Alice's catalog response will include available assets like this (but not the newly created asset with ID: 200): - -:::tip -If the asset is not visible, ensure the **Access Policy** and **Contract Definition** are created on Bob's side. -::: - -```json -{ - "@id": "be17c3e7-3156-46db-8934-f1ea92d1f2a3", - "@type": "dcat:Catalog", - "dcat:dataset": [ - { - "@id": "registry-asset", - "@type": "dcat:Dataset", - "odrl:hasPolicy": { - "@id": "MTcxODBlMTAtNmFjNS00NTYzLWE2MTUtNGM1MjQ5ZTUxMTU5:cmVnaXN0cnktYXNzZXQ=:NzE0ODk2YjMtY2VlYy00NmY5LWE5ZTgtY2NiMWI1NGUzOTgy", - "@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" - } - } - }, - "odrl:prohibition": [], - "odrl:obligation": [], - "odrl:target": "registry-asset" - }, - "dcat:distribution": [ - { - "@type": "dcat:Distribution", - "dct:format": { - "@id": "HttpProxy" - }, - "dcat:accessService": "49a693e0-835d-457a-99b4-e781f2bd643d" - }, - { - "@type": "dcat:Distribution", - "dct:format": { - "@id": "AmazonS3" - }, - "dcat:accessService": "49a693e0-835d-457a-99b4-e781f2bd643d" - } - ], - "edc:type": "data.core.digitalTwinRegistry", - "edc:description": "Digital Twin Registry Endpoint of IRS DEV", - "edc:id": "registry-asset" - }, - { - "@id": "urn:uuid:dc641d45-95e7-4284-a472-43f30255d0cb", - "@type": "dcat:Dataset", - "odrl:hasPolicy": { - "@id": "MTIzYjJlM2QtNTUxOC00ZWViLWFmMGItNTU5ZTYxZGY3Zjhk:dXJuOnV1aWQ6ZGM2NDFkNDUtOTVlNy00Mjg0LWE0NzItNDNmMzAyNTVkMGNi:YzBhOGFhOTQtNzg4OS00Y2MxLTkzNmMtMWYwMTNkODc3Nzk4", - "@type": "odrl:Set", - "odrl:permission": { - "odrl:target": "urn:uuid:dc641d45-95e7-4284-a472-43f30255d0cb", - "odrl:action": { - "odrl:type": "USE" - }, - "odrl:constraint": { - "odrl:or": { - "odrl:leftOperand": "PURPOSE", - "odrl:operator": { - "@id": "odrl:eq" - }, - "odrl:rightOperand": "ID 3.0 Trace" - } - } - }, - "odrl:prohibition": [], - "odrl:obligation": [], - "odrl:target": "urn:uuid:dc641d45-95e7-4284-a472-43f30255d0cb" - }, - "dcat:distribution": [ - { - "@type": "dcat:Distribution", - "dct:format": { - "@id": "HttpProxy" - }, - "dcat:accessService": "49a693e0-835d-457a-99b4-e781f2bd643d" - }, - { - "@type": "dcat:Distribution", - "dct:format": { - "@id": "AmazonS3" - }, - "dcat:accessService": "49a693e0-835d-457a-99b4-e781f2bd643d" - } - ], - "edc:description": "IRS EDC Test Asset", - "edc:id": "urn:uuid:dc641d45-95e7-4284-a472-43f30255d0cb" - } - ], - "dcat:service": { - "@id": "49a693e0-835d-457a-99b4-e781f2bd643d", - "@type": "dcat:DataService", - "dct:terms": "connector", - "dct:endpointUrl": "http://dataprovider-controlplane.tx.test/api/v1/dsp" - }, - "edc:participantId": "BPNL00000003AYRE", - "@context": { - "dct": "http://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/" - } -} -``` - -## Create a first access policy - -Bob creates an **Access Policy** to determine who can view the data offer. - -### Step 1: Create the policy - -Run this `curl` command: - -```shell -curl -L -X POST 'http://dataprovider-controlplane.tx.test/management/v2/policydefinitions' \ - -H 'Content-Type: application/json' \ - -H 'X-Api-Key: TEST2' \ - --data-raw '{ - "@context": { - "odrl": "http://www.w3.org/ns/odrl/2/" - }, - "@type": "PolicyDefinitionRequestDto", - "@id": "200", - "policy": { - "@type": "odrl:Set", - "odrl:permission": [ - { - "odrl:action": "USE", - "odrl:constraint": { - "@type": "LogicalConstraint", - "odrl:or": [ - { - "@type": "Constraint", - "odrl:leftOperand": { - "@id": "BusinessPartnerNumber" - }, - "odrl:operator": { - "@id": "odrl:eq" - }, - "odrl:rightOperand": "BPNL00000003AZQP" - } - ] - } - } - ] - } - }' | jq -``` - -In this case a **Access Policy** is created. The assigned asset will only be visible as a data offer for the Business Partner Number `BPNL00000003AZQP`. - -#### Expected Output - -The policy was successfully created, if the response is something like this - -```json -{ - "@type": "IdResponse", - "@id": "200", - "createdAt": 1732640748595, - "@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/" - } -} -``` - -### Step 2: Request catalog - second try - -Now that Bob created an access policy, Alice can once again try to access Bob's offer by running this `curl`. - -```shell -curl -L -X POST 'http://dataconsumer-1-controlplane.tx.test/management/v2/catalog/request' \ - -H 'Content-Type: application/json' \ - -H 'X-Api-Key: TEST1' \ - --data-raw '{ - "@context": { - "@vocab": "https://w3id.org/edc/v0.0.1/ns/" - }, - "@type": "CatalogRequest", - "counterPartyAddress": "http://dataprovider-controlplane.tx.test/api/v1/dsp", - "counterPartyId": "BPNL00000003AYRE", - "protocol": "dataspace-protocol-http", - "querySpec": { - "offset": 0, - "limit": 50 - } - }' | jq -``` - -#### Expected Output - -Since the asset is still not visible, the response will be the same as before. This is expected, as the asset is not yet linked to the policy. - -:::tip -Once again Alice cannot find the data offer. This is by design and to be expected since Bob has only created an asset and a policy definition. An asset and a policy can not be displayed to Alice as a consumer without a contract definition. -**For providing data, a contract definition must be created on the provider side. This must always contain an asset, an access policy, and a contract policy.** - -Contract definitions state how assets and policies are linked together. Contract definitions express under what conditions an asset is published in a data space. Those conditions are comprised of a contract policy and an access policy. Those policies are referenced by ID, that means they must already exist in the policy store before creating the contract definition. - -- **Access policy:** determines whether or not a particular consumer can see an asset in the provider's catalog. For example, we may want to restrict certain assets such that only selected consumers from a list of selected partners can access the asset. This can be done using a unique identifier such as the Business Partner Number (BPN). Other data space participants than those whose BPN is listed in the access policy wouldn't even be able to see the asset in the catalog. -- **Contract policy:** determines the conditions for initiating a contract negotiation for a particular asset. Note that this does not automatically guarantee the successful creation of a contract, it merely expresses the eligibility to start the negotiation. - -Find additional information on transferring data in the [Developer's Handbook](https://github.com/eclipse-edc/docs/blob/main/developer/handbook.md). -::: - -## Define a contract definition - -Alice still cannot see the asset because Bob hasn't created a **Contract Definition**. Contract definitions link assets and policies to define usage terms. - -### Step 1: Create the contract definition - -First of all run this `curl` command to check if the policy is created correctly: - -```shell -curl -L -X GET 'http://dataprovider-controlplane.tx.test/management/v2/policydefinitions/200' \ --H 'X-Api-Key: TEST2' | jq -``` - -The policy with ID: 200 was successfully created, if the response is something like this - -```json -{ - "@id": "200", - "@type": "PolicyDefinition", - "createdAt": 1732640748595, - "policy": { - "@id": "d7f2161b-1670-4461-ab36-e5aeefcab2e9", - "@type": "odrl:Set", - "odrl:permission": { - "odrl:action": { - "@id": "USE" - }, - "odrl:constraint": { - "odrl:or": { - "odrl:leftOperand": { - "@id": "BusinessPartnerNumber" - }, - "odrl:operator": { - "@id": "odrl:eq" - }, - "odrl:rightOperand": "BPNL00000003AZQP" - } - } - }, - "odrl:prohibition": [], - "odrl:obligation": [] - }, - "@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/" - } -} -``` - -Run this `curl` command to create a contract definition including the asset and the policies you have created: - -```shell -curl -L -X POST 'http://dataprovider-controlplane.tx.test/management/v2/contractdefinitions' \ - -H 'Content-Type: application/json' \ - -H 'X-Api-Key: TEST2' \ - --data-raw '{ - "@context": {}, - "@id": "200", - "@type": "ContractDefinition", - "accessPolicyId": "200", - "contractPolicyId": "200", - "assetsSelector": { - "@type": "CriterionDto", - "operandLeft": "https://w3id.org/edc/v0.0.1/ns/id", - "operator": "=", - "operandRight": "200" - } - }' | jq -``` - -#### Expected Output - -```json -{ - "@type": "IdResponse", - "@id": "200", - "createdAt": 1732698850793, - "@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/" - } -} -``` - -## Verify data availability - -Alice re-requests the catalog. This time, she should see Bob's asset in the catalog: - -```shell -curl -L -X POST 'http://dataconsumer-1-controlplane.tx.test/management/v2/catalog/request' \ - -H 'Content-Type: application/json' \ - -H 'X-Api-Key: TEST1' \ - --data-raw '{ - "@context": { - "@vocab": "https://w3id.org/edc/v0.0.1/ns/" - }, - "@type": "CatalogRequest", - "counterPartyAddress": "http://dataprovider-controlplane.tx.test/api/v1/dsp", - "counterPartyId": "BPNL00000003AYRE", - "protocol": "dataspace-protocol-http", - "querySpec": { - "filterExpression": [ - { - "operandLeft": "https://w3id.org/edc/v0.0.1/ns/id", - "operator": "=", - "operandRight": "200" - } - ] - } - }' | jq -``` - -### Expected Output - -```json -{ - "@id": "ad6b2272-a131-4d75-9efd-0c7529d1109f", - "@type": "dcat:Catalog", - "dspace:participantId": "BPNL00000003AYRE", - "dcat:dataset": { - "@id": "200", - "@type": "dcat:Dataset", - "odrl:hasPolicy": { - "@id": "MjAw:MjAw:YzNlOWVjYzEtMDcwNS00YWI1LThhM2UtOWNmYTA5NTg2ZWU4", - "@type": "odrl:Offer", - "odrl:permission": { - "odrl:action": { - "odrl:type": "USE" - }, - "odrl:constraint": { - "odrl:or": { - "odrl:leftOperand": "BusinessPartnerNumber", - "odrl:operator": { - "@id": "odrl:eq" - }, - "odrl:rightOperand": "BPNL00000003AZQP" - } - } - }, - "odrl:prohibition": [], - "odrl:obligation": [] - }, - "dcat:distribution": [ - { - "@type": "dcat:Distribution", - "dct:format": { - "@id": "AzureStorage-PUSH" - }, - "dcat:accessService": { - "@id": "ed228dd5-d1e6-45be-84be-20ba27829e50", - "@type": "dcat:DataService", - "dcat:endpointDescription": "dspace:connector", - "dcat:endpointUrl": "http://dataprovider-controlplane.tx.test/api/v1/dsp", - "dct:terms": "dspace:connector", - "dct:endpointUrl": "http://dataprovider-controlplane.tx.test/api/v1/dsp" - } - }, - { - "@type": "dcat:Distribution", - "dct:format": { - "@id": "HttpData-PULL" - }, - "dcat:accessService": { - "@id": "ed228dd5-d1e6-45be-84be-20ba27829e50", - "@type": "dcat:DataService", - "dcat:endpointDescription": "dspace:connector", - "dcat:endpointUrl": "http://dataprovider-controlplane.tx.test/api/v1/dsp", - "dct:terms": "dspace:connector", - "dct:endpointUrl": "http://dataprovider-controlplane.tx.test/api/v1/dsp" - } - }, - { - "@type": "dcat:Distribution", - "dct:format": { - "@id": "HttpData-PUSH" - }, - "dcat:accessService": { - "@id": "ed228dd5-d1e6-45be-84be-20ba27829e50", - "@type": "dcat:DataService", - "dcat:endpointDescription": "dspace:connector", - "dcat:endpointUrl": "http://dataprovider-controlplane.tx.test/api/v1/dsp", - "dct:terms": "dspace:connector", - "dct:endpointUrl": "http://dataprovider-controlplane.tx.test/api/v1/dsp" - } - }, - { - "@type": "dcat:Distribution", - "dct:format": { - "@id": "AmazonS3-PUSH" - }, - "dcat:accessService": { - "@id": "ed228dd5-d1e6-45be-84be-20ba27829e50", - "@type": "dcat:DataService", - "dcat:endpointDescription": "dspace:connector", - "dcat:endpointUrl": "http://dataprovider-controlplane.tx.test/api/v1/dsp", - "dct:terms": "dspace:connector", - "dct:endpointUrl": "http://dataprovider-controlplane.tx.test/api/v1/dsp" - } - } - ], - "description": "Product EDC Demo Asset", - "id": "200" - }, - "dcat:service": { - "@id": "ed228dd5-d1e6-45be-84be-20ba27829e50", - "@type": "dcat:DataService", - "dcat:endpointDescription": "dspace:connector", - "dcat:endpointUrl": "http://dataprovider-controlplane.tx.test/api/v1/dsp", - "dct:terms": "dspace:connector", - "dct:endpointUrl": "http://dataprovider-controlplane.tx.test/api/v1/dsp" - }, - "participantId": "BPNL00000003AYRE", - "@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/", - "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/" - } -} -``` - -:::info -Finally Alice can see the Contract Offer from Bob. Congratulations on yor first successful offering of data in your own data space! -::: - -## Notice - -This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). - -- SPDX-License-Identifier: CC-BY-4.0 -- SPDX-FileCopyrightText: 2024 ARENA2036 e.V. -- SPDX-FileCopyrightText: 2023 sovity GmbH -- SPDX-FileCopyrightText: 2023 SAP SE -- SPDX-FileCopyrightText: 2023 msg systems AG -- Source URL: [https://github.com/eclipse-tractusx/eclipse-tractusx.github.io](https://github.com/eclipse-tractusx/eclipse-tractusx.github.io) diff --git a/docs/tutorials/e2e/boost/restrictData.md b/docs/tutorials/e2e/boost/restrictData.md deleted file mode 100644 index 73349b7cee0..00000000000 --- a/docs/tutorials/e2e/boost/restrictData.md +++ /dev/null @@ -1,372 +0,0 @@ ---- -title: Restricting users from accessing an asset -sidebar_position: 4 ---- - -## Create an asset - -Bob will once again be the data provider. But this time Bob does not want Alice to see the asset. -The first step for Bob will again be to create an asset. - -Action (Bob): Create an asset using the following `curl` command: - -```shell -curl --location 'http://dataprovider-controlplane.tx.test/management/v3/assets' \ ---header 'Content-Type: application/json' \ ---header 'X-Api-Key: TEST2' \ ---data-raw '{ - "@context": {}, - "@type": "Asset", - "@id": "4", - "properties": { - "description": "Product EDC Demo Asset 4" - }, - "dataAddress": { - "@type": "DataAddress", - "type": "HttpData", - "baseUrl": "https://jsonplaceholder.typicode.com/todos/4" - } -}' | jq -``` - -## Create a permissive access policy - -Now that the asset has been created, Bob creates an access policy that defines who can see and therefore access the asset in his catalog. To specify this access, Bob uses the Business Partner Number (BPN). The BPN is a unique identifier for participants of a data space. Bob knows that his exchange partner for this asset has the BPN `BPNL00000003AVTH` and Alice BPN is `BPNL00000003AZQP` - -Action (Bob): Create the access policy using the following `curl` command: - -```shell -curl --location 'http://dataprovider-controlplane.tx.test/management/v2/policydefinitions' \ ---header 'Content-Type: application/json' \ ---header 'X-Api-Key: TEST2' \ ---data-raw '{ - "@context": { - "odrl": "http://www.w3.org/ns/odrl/2/" - }, - "@type": "PolicyDefinitionRequestDto", - "@id": "41", - "policy": { - "@type": "Policy", - "odrl:permission": [ - { - "odrl:action": "USE", - "odrl:constraint": { - "@type": "LogicalConstraint", - "odrl:or": [ - { - "@type": "Constraint", - "odrl:leftOperand": "BusinessPartnerNumber", - "odrl:operator": { - "@id": "odrl:eq" - }, - "odrl:rightOperand": "BPNL00000003AVTH" - } - ] - } - } - ] - } -}' | jq -``` - -The policydefinition is created with the ID `41` - -```json -{ - "@type": "edc:IdResponse", - "@id": "41", - "edc:createdAt": 1715674423858, - "@context": { - "dct": "http://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/" - } -} -``` - -Bob defined a policy which restricts access to connector(s) with the BusinessPartnerNumber `BPNL00000003AVTH`. As Alice does not own this BPN, she should not be able to access the asset. - -## Create a permissive contract policy - -Since an access policy has already been created, a contract policy must be created and linked in the contract definition. - -Action (Bob): Create the contract policy using the following `curl` command: - -```shell -curl --location 'http://dataprovider-controlplane.tx.test/management/v2/policydefinitions' \ ---header 'Content-Type: application/json' \ ---header 'X-Api-Key: TEST2' \ ---data-raw '{ - "@context": { - "odrl": "http://www.w3.org/ns/odrl/2/" - }, - "@type": "PolicyDefinitionRequestDto", - "@id": "42", - "policy": { - "@type": "Policy", - "odrl:permission": [ - { - "odrl:action": "USE", - "odrl:constraint": { - "@type": "LogicalConstraint", - "odrl:or": [ - { - "@type": "Constraint", - "odrl:leftOperand": "BpnCredential", - "odrl:operator": { - "@id": "odrl:eq" - }, - "odrl:rightOperand": "active" - } - ] - } - } - ] - } -}' | jq -``` - -The response should be something like this - -```json -{ - "@type": "edc:IdResponse", - "@id": "42", - "edc:createdAt": 1715674546763, - "@context": { - "dct": "http://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/" - } -} -``` - -## Create a contract definition - -Lastly, the asset and the access policy must be linked in a contract definition. -Action (Bob): Create a contract definition including the asset and the policies you have created. For this, use the following `curl` command: - -```shell -curl --location 'http://dataprovider-controlplane.tx.test/management/v2/contractdefinitions' \ ---header 'Content-Type: application/json' \ ---header 'X-Api-Key: TEST2' \ ---data-raw '{ - "@context": {}, - "@id": "4", - "@type": "ContractDefinition", - "accessPolicyId": "41", - "contractPolicyId": "42", - "assetsSelector" : { - "@type" : "CriterionDto", - "operandLeft": "https://w3id.org/edc/v0.0.1/ns/id", - "operator": "=", - "operandRight": "4" - } -}' | jq -``` - -A response should look like this - -```json -{ - "@type": "edc:IdResponse", - "@id": "4", - "edc:createdAt": 1715674670136, - "@context": { - "dct": "http://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/" - } -} -``` - -## Request catalog - -Let´s see if Alice can see the Asset. - -Action (Alice): Execute a request using the following `curl` command: - -```shell -curl --location 'http://dataconsumer-1-controlplane.tx.test/management/v2/catalog/request' \ ---header 'Content-Type: application/json' \ ---header 'X-Api-Key: TEST1' \ ---data-raw '{ - "@context": {}, - "protocol": "dataspace-protocol-http", - "counterPartyAddress": "http://dataprovider-controlplane.tx.test/api/v1/dsp", - "querySpec": { - "offset": 0, - "limit": 100 - } -}' | jq -``` - -The response doesnt include the cataolog entry for the asset/offer with id4 - -```json -{ - "@id": "3b276870-5cc5-4546-b793-e2c8d39e1010", - "@type": "dcat:Catalog", - "dcat:dataset": [ - { - "@id": "registry-asset", - "@type": "dcat:Dataset", - "odrl:hasPolicy": { - "@id": "ZGM3MjMyYTAtMDRjOC00MTVjLWI2NmQtOGJmNTQ1MWMyYmIy:cmVnaXN0cnktYXNzZXQ=:MjdiYWExMGItMTAzMC00MmY5LWI0YjMtMzJmY2UyODI5NThl", - "@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" - } - } - }, - "odrl:prohibition": [], - "odrl:obligation": [], - "odrl:target": "registry-asset" - }, - "dcat:distribution": [ - { - "@type": "dcat:Distribution", - "dct:format": { - "@id": "HttpProxy" - }, - "dcat:accessService": "7b76c9c5-d7f9-42c1-8784-a2820a60bb0f" - }, - { - "@type": "dcat:Distribution", - "dct:format": { - "@id": "AmazonS3" - }, - "dcat:accessService": "7b76c9c5-d7f9-42c1-8784-a2820a60bb0f" - } - ], - "edc:type": "data.core.digitalTwinRegistry", - "edc:description": "Digital Twin Registry Endpoint of IRS DEV", - "edc:id": "registry-asset" - }, - { - "@id": "urn:uuid:69653fc9-11b5-4321-98ca-e60d2dc35379", - "@type": "dcat:Dataset", - "odrl:hasPolicy": { - "@id": "MDkyNmVhMGUtZWVmMC00OTlmLTliZjktNmE1MGU3MGUzOGQy:dXJuOnV1aWQ6Njk2NTNmYzktMTFiNS00MzIxLTk4Y2EtZTYwZDJkYzM1Mzc5:YWUwOTFiOTYtNGM0Ni00YzE0LWEyZGYtY2Y5NDNlMzY1NDY4", - "@type": "odrl:Set", - "odrl:permission": { - "odrl:target": "urn:uuid:69653fc9-11b5-4321-98ca-e60d2dc35379", - "odrl:action": { - "odrl:type": "USE" - }, - "odrl:constraint": { - "odrl:or": { - "odrl:leftOperand": "PURPOSE", - "odrl:operator": { - "@id": "odrl:eq" - }, - "odrl:rightOperand": "ID 3.0 Trace" - } - } - }, - "odrl:prohibition": [], - "odrl:obligation": [], - "odrl:target": "urn:uuid:69653fc9-11b5-4321-98ca-e60d2dc35379" - }, - "dcat:distribution": [ - { - "@type": "dcat:Distribution", - "dct:format": { - "@id": "HttpProxy" - }, - "dcat:accessService": "7b76c9c5-d7f9-42c1-8784-a2820a60bb0f" - }, - { - "@type": "dcat:Distribution", - "dct:format": { - "@id": "AmazonS3" - }, - "dcat:accessService": "7b76c9c5-d7f9-42c1-8784-a2820a60bb0f" - } - ], - "edc:description": "IRS EDC Test Asset", - "edc:id": "urn:uuid:69653fc9-11b5-4321-98ca-e60d2dc35379" - }, - { - "@id": "3", - "@type": "dcat:Dataset", - "odrl:hasPolicy": { - "@id": "Mw==:Mw==:YjE0ODU2M2MtMWM5MC00NDg4LThmZmItZmJjZjc0NjQzZTE5", - "@type": "odrl:Set", - "odrl:permission": [], - "odrl:prohibition": [], - "odrl:obligation": [], - "odrl:target": "3" - }, - "dcat:distribution": [ - { - "@type": "dcat:Distribution", - "dct:format": { - "@id": "HttpProxy" - }, - "dcat:accessService": "7b76c9c5-d7f9-42c1-8784-a2820a60bb0f" - }, - { - "@type": "dcat:Distribution", - "dct:format": { - "@id": "AmazonS3" - }, - "dcat:accessService": "7b76c9c5-d7f9-42c1-8784-a2820a60bb0f" - } - ], - "edc:description": "Product EDC Demo Asset 3", - "edc:id": "3" - } - ], - "dcat:service": { - "@id": "7b76c9c5-d7f9-42c1-8784-a2820a60bb0f", - "@type": "dcat:DataService", - "dct:terms": "connector", - "dct:endpointUrl": "http://dataprovider-controlplane.tx.test/api/v1/dsp" - }, - "edc:participantId": "BPNL00000003AYRE", - "@context": { - "dct": "http://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/" - } -} -``` - -:::info - -Bob’s asset (ID: 4) should not be displayed. The access policy successfully restricts Alice from seeing and therefore obtaining Bob’s asset. Now Bob is able to manage who sees which of his sensitive data assets. If Bob decides to enable Alice to see his asset, he can simply adjust the access policy definition and add Alice BPN `BPNL00000003AZQP` to the list of BPNs. - -::: - -## Notice - -This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). - -- SPDX-License-Identifier: CC-BY-4.0 -- SPDX-FileCopyrightText: 2023 sovity GmbH -- SPDX-FileCopyrightText: 2023 SAP SE -- SPDX-FileCopyrightText: 2023 msg systems AG -- Source URL: [https://github.com/eclipse-tractusx/eclipse-tractusx.github.io](https://github.com/eclipse-tractusx/eclipse-tractusx.github.io) diff --git a/docs/tutorials/e2e/connect/deployComponents.md b/docs/tutorials/e2e/connect/deployComponents.md index 38f13e87d1f..84f141e88b7 100644 --- a/docs/tutorials/e2e/connect/deployComponents.md +++ b/docs/tutorials/e2e/connect/deployComponents.md @@ -29,595 +29,20 @@ Make sure that you have understood and carried out all the steps in the `Prerequ ### Using Umbrella Helm Charts -The components (listed in the table in the `Connect chapter`) are deployed using an umbrella chart. It consists of Tractus-X OSS components and provides a basis for running end-to-end tests or creating a sandbox environment of the Catena-X automotive dataspace network. The Chart aims for a completely automated setup of a fully functional network that requires no manual setup steps, as long as only one instance (minikube cluster) is running (see warning above). If several clusters are running, you will need to adjust so configuration files. +The components (listed in the table in the `Connect chapter`) are deployed using an umbrella chart. It consists of Tractus-X OSS components and provides a +basis for running end-to-end tests or creating a sandbox environment of the Catena-X automotive dataspace network. The Chart aims for a completely automated setup of a fully functional network that requires no manual setup steps, as long as only one instance (minikube cluster) is running (see warning above). If several clusters are running, you will need to adjust so configuration files. :::note -This chapter aligns with the README for the Tractus-X umbrella charts following the link: - +This chapter is described within the README for the Tractus-X umbrella charts following the [link](https://github.com/eclipse-tractusx/tractus-x-umbrella/blob/main/docs/README.md) -::: - -### Overview - -Perform the following steps to begin deploying the TXD: - -- Get the source -- Start `minikube` bringing up the cluster (profile) -- Enable `Ingress` for local access using the addon for Minikube -- Adjust the configuration files for the Umbrella Helm Chart (this is not required, if you are the only user on a system) -- Use the certifacation manager -- Use helm to deploy the ecosystem -- Check their liveness - -### Get the source from the Tractus-X Github - -For the most bare-bones installation of the dataspace, execute the following commands in a shell: - -```bash -# get the tutorial including the config file for the cluster by cloning the repository locally -git clone https://github.com/eclipse-tractusx/tractus-x-umbrella.git -``` - -Now we will find the directory [tractus-x-umbrella] under your current working directory. Change into this directory: - -```bash -cd tractus-x-umbrella -``` - -### Start the minikube cluster (profile) - -To start the cluster we just call **minikube start**. If we have more than one instance, we use -p option to set the profile name minikube-$USER. We use the other options to request the appropiate resources. - -```bash -minikube start --cpus=4 --memory 6gb -# Start the cluster, if -p option is used with the profile name minikube-$USER -``` - -You can check your minikube cluster any time by starting the Minikube dashboard: - -```bash -minikube dashboard -``` - -### Setting up the local internal netwok - -In order to enable the local access via ingress, use the according addon for Minikube: - -```bash -minikube addons enable ingress -``` - -Now add these hostnames to your /etc/hosts. You should ensure that you have access and the /etc/hosts file group entry should be assigend to the group **docker**. Check this with the following commands: - -```bash -ls -al /etc/hosts -# Output should be like: "-rw-r--r-- 1 root docker 414 Jun 16 14:34 /etc/hosts" -``` - -Alternatively configure the DNS Service to be enabled for Ingress. - -:::note - - This requires that you have a DNS on your system running and that you have **root accees** via **sudo** - -::: - -```bash -minikube addons enable ingress-dns -``` - -Find out the IP Address of your minikube cluster by entering: - -```bash -minikube ip -``` - -In the following steps, replace `192.168.49.2` with your `minikube ip` if it differs. - -#### Linux & Mac - -Create a file in /etc/resolver/minikube-test with the following contents. - -```shell -domain tx.test -nameserver 192.168.49.2 -search_order 1 -timeout 5 -``` - -If you still face DNS issues, add the hosts to your /etc/hosts file: - -```shell -192.168.49.2 centralidp.tx.test -192.168.49.2 sharedidp.tx.test -192.168.49.2 portal.tx.test -192.168.49.2 portal-backend.tx.test -192.168.49.2 semantics.tx.test -192.168.49.2 sdfactory.tx.test -192.168.49.2 ssi-credential-issuer.tx.test -192.168.49.2 dataconsumer-1-dataplane.tx.test -192.168.49.2 dataconsumer-1-controlplane.tx.test -192.168.49.2 dataprovider-dataplane.tx.test -192.168.49.2 dataprovider-controlplane.tx.test -192.168.49.2 dataconsumer-2-dataplane.tx.test -192.168.49.2 dataconsumer-2-controlplane.tx.test -192.168.49.2 bdrs-server.tx.test -192.168.49.2 iatpmock.tx.test -192.168.49.2 business-partners.tx.test -192.168.49.2 pgadmin4.tx.test -192.168.49.2 ssi-dim-wallet-stub.tx.test -192.168.49.2 dataprovider-submodelserver.tx.test -``` - -Additional network setup for Mac: - -- Install and start [Docker Mac Net Connect](https://github.com/chipmk/docker-mac-net-connect#installation). - -We also recommend to execute the usage example after install to check proper setup. - -#### Windows - -For Windows edit the hosts file under `C:\Windows\System32\drivers\etc\hosts`: - -```shell -192.168.49.2 centralidp.tx.test -192.168.49.2 sharedidp.tx.test -192.168.49.2 portal.tx.test -192.168.49.2 portal-backend.tx.test -192.168.49.2 semantics.tx.test -192.168.49.2 sdfactory.tx.test -192.168.49.2 ssi-credential-issuer.tx.test -192.168.49.2 dataconsumer-1-dataplane.tx.test -192.168.49.2 dataconsumer-1-controlplane.tx.test -192.168.49.2 dataprovider-dataplane.tx.test -192.168.49.2 dataprovider-controlplane.tx.test -192.168.49.2 dataconsumer-2-dataplane.tx.test -192.168.49.2 dataconsumer-2-controlplane.tx.test -192.168.49.2 bdrs-server.tx.test -192.168.49.2 iatpmock.tx.test -192.168.49.2 business-partners.tx.test -192.168.49.2 pgadmin4.tx.test -192.168.49.2 ssi-dim-wallet-stub.tx.test -192.168.49.2 dataprovider-submodelserver.tx.test -``` - -### Install Helm Charts - -:::warning - -- Due to resource restrictions, it's **not recommended** to install the helm chart with all components enabled. - -- It is to be expected that some pods - which run as post-install hooks, like for instance the **portal-migrations job - will run into errors until another component**, like for instance a database, is ready to take connections. -Those jobs will recreate pods until one run is successful. -- **Persistance is disabled by default** but can be configured in a custom values file. - -::: - -#### Use local repository - -Make sure you cloned the [tractus-x-umbrella](https://github.com/eclipse-tractusx/tractus-x-umbrella) repository beforehand. - -Then navigate to the chart directory: - -```bash -cd charts/umbrella/ -``` - -Download the chart dependencies: - -```bash -helm dependency update ../tx-data-provider -helm dependency update -``` - -:::note Command explanation - -`helm install` is used to install a Helm chart. - -- `-f your-values.yaml` | `-f values-*.yaml` specifies the values file to use for configuration. -- `umbrella` is the release name for the Helm chart. -- `.` specifies the path to the chart directory. -- `--namespace umbrella` specifies the namespace in which to install the chart. -- `--create-namespace` create a namespace with the name `umbrella`. - -::: - -##### Option 1 - -Choose to install one of the predefined subsets (currently in focus of the **E2E Adopter Journey**): - -:::note - -This will take a while. So please be patient. - -::: - -###### Data Exchange Subset - -```bash -helm install -f values-adopter-data-exchange.yaml umbrella . --namespace umbrella --create-namespace -``` - -**Optional:** - -Enable `dataconsumerTwo` by setting it true in `values-adopter-data-exchange.yaml` and then executing an upgrade: - -```bash -dataconsumerTwo: - enabled: true -``` - -```bash -helm upgrade -f values-adopter-data-exchange.yaml umbrella . --namespace umbrella -``` - -###### Portal Subset - -```bash -helm install -f values-adopter-portal.yaml umbrella . --namespace umbrella --create-namespace -``` - -##### Option 2 - -Install your chosen components by having them enabled in a `your-values.yaml` file: - -```bash -helm install -f your-values.yaml umbrella . --namespace umbrella --create-namespace -``` - -:::tip -In general, all your specific configuration and secret values should be set by installing with an own values file. -::: - -#### Get to know the Portal - -Perform first login and send out an invitation to a company to join the network (SMTP account required to be configured in custom values.yaml file). - -Proceed with the login to the to verify that everything is setup as expected. - -Credentials to log into the initial example realm (CX-Operator): - -```sh -cx-operator@arena.test -``` - -```sh -tractusx-umbr3lla! -``` - -```mermaid -%%{ - init: { - 'flowchart': { 'diagramPadding': '10', 'wrappingWidth': '', 'nodeSpacing': '', 'rankSpacing':'', 'titleTopMargin':'10', 'curve':'basis'}, - 'theme': 'base', - 'themeVariables': { - 'primaryColor': '#b3cb2d', - 'primaryBorderColor': '#ffa600', - 'lineColor': '#ffa600', - 'tertiaryColor': '#fff' - } - } -}%% - graph TD - classDef stroke stroke-width:2px - classDef addext fill:#4cb5f5,stroke:#b7b8b6,stroke-width:2px - iam1(IAM: centralidp Keycloak):::stroke - iam2(IAM: sharedidp Keycloak):::stroke - portal(Portal):::stroke - subgraph Login Flow - iam1 --- portal & iam2 - end - linkStyle 0,1 stroke:lightblue -``` - -The relevant hosts are the following: - -- -- -- -- - -In case that you have TLS enabled (see [Self-signed TLS setup (Optional)](#self-signed-tls-setup-optional)), make sure to accept the risk of the self-signed certificates for all the hosts before performing the first login: - -- -- -- -- - -### Uninstall Helm Charts - -To teardown your setup, run: - -```shell -helm delete umbrella --namespace umbrella -``` - -:::warning - -If persistance for one or more components is enabled, the persistent volume claims (PVCs) and connected persistent volumes (PVs) need to be removed manually even if you deleted the release from the cluster. - -::: - -### Ingresses - -Currently enabled ingresses: - -- -- -- - - - - - - - - - - -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- - -### Database Access - -This chart also contains a pgadmin4 instance for easy access to the deployed Postgres databases which are only available from within the Kubernetes cluster. - -pgadmin4 is by default enabled with in the predefined subsets for data exchange and portal. - -Address: [pgadmin4.tx.test](http://pgadmin4.tx.test) - -Credentials to login into pgadmin4: - -```sh -pgadmin4@txtest.org -``` - -```sh -tractusxpgdamin4 -``` - -:::info - -The database server connections need to be added manually to pgadmin4. +Important chapters are: +- [Cluster Setup](https://github.com/eclipse-tractusx/tractus-x-umbrella/blob/main/docs/user/setup) +- [Network Setup](https://github.com/eclipse-tractusx/tractus-x-umbrella/blob/main/docs/user/network) +- [Installation](https://github.com/eclipse-tractusx/tractus-x-umbrella/blob/main/docs/user/installation/README.md) ::: -Default username for all connections: - -```sh -postgres -``` - -Default user for all connections: - -```sh -5432 -``` - -In the following some of the available connections: - -- portal - -Host: - -```sh -portal-backend-postgresql -``` - -Password: - -```sh -dbpasswordportal -``` - -- centralidp - -Host: - -```sh -umbrella-centralidp-postgresql -``` - -Password: - -```sh -dbpasswordcentralidp -``` - -- sharedidp - -Host: - -```sh -umbrella-sharedidp-postgresql -``` - -Password: - -```sh -dbpasswordsharedidp -``` - -- miw - -Host: - -```sh -umbrella-miw-postgres -``` - -Password: - -```sh -dbpasswordmiw -``` - -- dataprovider - -Host: - -```sh -umbrella-dataprovider-db -``` - -Password: - -```sh -dbpasswordtxdataprovider -``` - -- dataconsumer-1 - -Host: - -```sh -umbrella-dataconsumer-1-db -``` - -Password: - -```sh -dbpassworddataconsumerone -``` - -- dataconsumer-2 - -Host: - -```sh -umbrella-dataconsumer-2-db -``` - -Password: - -```sh -dbpassworddataconsumertwo -``` - -### Keycloak Admin Console - -Access to admin consoles: - -- [http://centralidp.tx.test/auth/](http://sharedidp.tx.test/auth/) -- [http://sharedidp.tx.test/auth/](http://sharedidp.tx.test/auth/) - -Default username for centralidp and sharedidp: - -```sh -admin -``` - -Password centralidp: - -```sh -adminconsolepwcentralidp -``` - -Password sharedidp: - -```sh -adminconsolepwsharedidp -``` - -### Seeding - -See [Overall Seeding](https://github.com/eclipse-tractusx/tractus-x-umbrella/blob/main/concept/seeds-overall-data.md). - -### Self-signed TLS setup (Optional) - -Some of the components are prepared to be configured with TLS enabled (see "uncomment the following line for tls" comments in [values.yaml](./values.yaml)). - -If you'd like to make use of that, make sure to to execute this step beforehand. - -Install cert-manager chart in the same namespace where the umbrella chart will be located. - -```bash -helm repo add jetstack https://charts.jetstack.io -helm repo update -``` - -```bash -helm install \ - cert-manager jetstack/cert-manager \ - --namespace umbrella \ - --create-namespace \ - --version v1.14.4 \ - --set installCRDs=true -``` - -Configure the self-signed certificate and issuer to be used by the ingress resources. - -If you have the repository checked out you can run: - -```bash -kubectl apply -f ./charts/umbrella/cluster-issuer.yaml -``` - -or otherwise you can run: - -```bash -kubectl apply -f - < Date: Thu, 19 Dec 2024 08:28:35 +0100 Subject: [PATCH 14/14] fix markdown linter issues --- docs/tutorials/e2e/boost/boost.md | 1 + docs/tutorials/e2e/connect/deployComponents.md | 1 + 2 files changed, 2 insertions(+) diff --git a/docs/tutorials/e2e/boost/boost.md b/docs/tutorials/e2e/boost/boost.md index a7987d8bd38..b40838a891b 100644 --- a/docs/tutorials/e2e/boost/boost.md +++ b/docs/tutorials/e2e/boost/boost.md @@ -22,6 +22,7 @@ By the end of this chapter, you will have the foundational knowledge needed to s This chapter is described within the guides for the Tractus-X umbrella charts following the [link](https://github.com/eclipse-tractusx/tractus-x-umbrella/blob/main/docs/README.md) Important chapters are: + - [Data Exchange](https://github.com/eclipse-tractusx/tractus-x-umbrella/blob/main/docs/user/guides/data-exchange.md) - [Provide Data](https://github.com/eclipse-tractusx/tractus-x-umbrella/blob/main/docs/user/guides/data-exchange/provide-data.md) - [Consume Data](https://github.com/eclipse-tractusx/tractus-x-umbrella/blob/main/docs/user/guides/data-exchange/consume-data.md) diff --git a/docs/tutorials/e2e/connect/deployComponents.md b/docs/tutorials/e2e/connect/deployComponents.md index 84f141e88b7..d03b4b976c8 100644 --- a/docs/tutorials/e2e/connect/deployComponents.md +++ b/docs/tutorials/e2e/connect/deployComponents.md @@ -37,6 +37,7 @@ basis for running end-to-end tests or creating a sandbox environment of the Cate This chapter is described within the README for the Tractus-X umbrella charts following the [link](https://github.com/eclipse-tractusx/tractus-x-umbrella/blob/main/docs/README.md) Important chapters are: + - [Cluster Setup](https://github.com/eclipse-tractusx/tractus-x-umbrella/blob/main/docs/user/setup) - [Network Setup](https://github.com/eclipse-tractusx/tractus-x-umbrella/blob/main/docs/user/network) - [Installation](https://github.com/eclipse-tractusx/tractus-x-umbrella/blob/main/docs/user/installation/README.md)