docs: add api collection and update readme for data exchange tutorial

charts/umbrella/Chart.yaml

@@ -28,7 +28,7 @@ sources:
   - https://github.com/eclipse-tractusx/tractus-x-umbrella
 
 type: application
-version: 2.0.2
+version: 2.0.3
 
 # when adding or updating versions of dependencies, also update list under README.md#Install
 dependencies:

charts/umbrella/README.md

@@ -42,7 +42,9 @@ The Chart aims for a completely automated setup of a fully functional network, t
 
 The versions of integrated components correspond to the **overarching [Release 24.05](https://github.com/eclipse-tractusx/tractus-x-release/blob/24.05/CHANGELOG.md#2405---2024-05-29)**.
 
-:warning: The 24.05 Release does not include a Managed Identity Wallet (MIW) - aka the FOSS Wallet of Tractus-X - as it was not yet able to cover functionalities required for the Self-Sovereign Identity Flow introduced with R24.05. To test and ship R24.05, a commercial solution was used: the Decentralized Identity Management (DIM) Wallet. To cover the wallet functionalities in the [E2E Adopter Journey Data exchange](#data-exchange) the [iatp-mock](https://github.com/eclipse-tractusx/tractus-x-umbrella/tree/main/charts/umbrella/charts/iatpmock/Chart.yaml) was added to the umbrella helm chart, please also see [Precondition for IATP Mock](#precondition-for-iatp-mock). For the [E2E Adopter Journey Portal](#portal), there isn't a mock available yet to cover the wallet functionalities.
+:warning: The 24.05 Release does not include a Managed Identity Wallet (MIW) - aka the FOSS Wallet of Eclipse Tractus-X - as it was not - yet - able to cover functionalities required for the Self-Sovereign Identity Flow introduced with R24.05. To test and ship R24.05, a commercial solution was used: the Decentralized Identity Management (DIM) Wallet. To cover the wallet functionalities in the [E2E Adopter Journey Data exchange](#data-exchange) and [E2E Adopter Journey Portal](#portal), the [SSI DIM Wallet Stub](https://github.com/eclipse-tractusx/ssi-dim-wallet-stub) was added to the umbrella helm chart.
+
+As an intermediate solution - before the SSI DIM Wallet Stub - the [iatp-mock](https://github.com/eclipse-tractusx/tractus-x-umbrella/tree/main/charts/umbrella/charts/iatpmock/Chart.yaml) was added, please see [Precondition for IATP Mock](#precondition-for-iatp-mock) if you'd still like to use it. Please be aware that it doesn't cover the wallet functionalities needed for the [E2E Adopter Journey Portal](#portal) for instance during the onboarding process of a company.
 
 ## Usage
 
@@ -467,16 +469,33 @@ helm install -f values-adopter-portal.yaml umbrella . --namespace umbrella --cre
 
 #### Data exchange
 
-:warning: Please be aware of [Note for R24.05](#note-for-r2405)
+To start the Data Exchange, it is necessary to execute the [Data Exchange Subset](https://github.com/eclipse-tractusx/tractus-x-umbrella/blob/umbrella-2.0.0/charts/umbrella/README.md#option-2-1)
 
-Involved components:
+There are two ways to test and execute the Data Exchange tutorial:
+
+**1. Postman**
+
+You can import the Umbrella [Postman Collection](../../docs/api/postman/UmbrellaConnectorData-Exchange.postman_collection.json)
 
-EDC, MIW, DTR, Vault (data provider and consumer in tx-data-provider), CentralIdP.
+**2. Curl**
+
+You can follow the [Curl Steps](../../docs/api/curl/UmbrellaConectorDataExchange.md)
+
+Involved components:
 
-TBD.
+- Data Provider
+- Data Consumer 1
+- Data Consumer 2 (Optional)
+- BDRS Server Memory
+- BPN-DID-Resolution-Service (BDRS)
+- SSI DIM Wallet Stub
+- SSI Credential Issuer
+- pgadmin4
 
 #### Get to know the Portal
 
+To start the Portal, it is necessary to execute the [Portal Subset](https://github.com/eclipse-tractusx/tractus-x-umbrella/blob/umbrella-2.0.0/charts/umbrella/README.md#option-2-1)
+
 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 <http://portal.tx.test> to verify that everything is setup as expected.
@@ -516,6 +535,23 @@ tractusx-umbr3lla!
           linkStyle 0,1 stroke:lightblue
 ```
 
+Involved components:
+
+- Portal
+- CentralIdP (Keycloak)
+- SharedIdP (Keycloak)
+- pgadmin4 
+
+Some components are disabled, as they are not necessary for the exclusive use of the portal. If you want to perform the onboarding of a participant, it would be necessary to enable the following components:
+
+- BPDM
+- SSI DIM Wallet Stub
+- BPN-DID-Resolution-Service (BDRS)
+- SSI-Credential-Issuer
+- Self Description Factory
+- Discovery Finder
+- BPN Discovery
+
 The relevant hosts are the following:
 
 - <http://centralidp.tx.test/auth/>
@@ -530,8 +566,6 @@ In case that you have TLS enabled (see [Self-signed TLS setup (Optional)](#self-
 - <https://portal-backend.tx.test>
 - <https://portal.tx.test>
 
-:warning: Please be aware of [Note for R24.05](#note-for-r2405)
-
 ##### Note for onboarding process
 
  Since the onboarding process requires the [Clearinghouse](https://github.com/eclipse-tractusx/portal-assets/blob/v2.1.0/docs/developer/Technical%20Documentation/Interface%20Contracts/Clearinghouse.md) to work properly, but ClearingHouse currently isn't available as a FOSS application you can skip the step with the following SQL Script which must be executed against the portal database.

charts/umbrella/values-adopter-data-exchange.yaml

@@ -64,4 +64,4 @@ ssi-credential-issuer:
   enabled: false
 
 ssi-dim-wallet-stub:
-  enabled: true
+  enabled: true

charts/umbrella/values-adopter-portal.yaml

@@ -56,6 +56,11 @@ pgadmin4:
 bpdm:
   enabled: false
 
+# Set 'enabled' to true if onboarding is required
+bdrs-server-memory:
+  enabled: true
+
+# Set 'enabled' to true if onboarding is required
 selfdescription:
   enabled: false
 

charts/umbrella/values.yaml

@@ -1164,7 +1164,13 @@ tx-data-provider:
   simple-data-backend:
     nameOverride: dataprovider-submodelserver
     ingress:
-      enabled: false
+      enabled: true
+      className: "nginx"
+      hosts:
+        - host: "dataprovider-submodelserver.tx.test"
+          paths:
+            - path: "/"
+              pathType: "Prefix"
 
 semantic-hub:
   enabled: false

docs/README.md

@@ -0,0 +1,17 @@
+# Introduction
+
+This repository provides the API requests to provide a tutorial for the Data Exchange.
+
+The following table links you to the respective documentations.
+
+| Documentation                                                    | Purpose                                                                                 |
+|------------------------------------------------------------------|-----------------------------------------------------------------------------------------|
+| [API Requests](api/API_Doc.md)                              | API Requests for Data Exchange.                                                        |
+
+## NOTICE
+
+This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0).
+
+- SPDX-License-Identifier: Apache-2.0
+- SPDX-FileCopyrightText: 2024 Contributors to the Eclipse Foundation
+- Source URL: <https://github.com/eclipse-tractusx/tractus-x-umbrella>

docs/api/API_Doc.md

@@ -0,0 +1,21 @@
+# API Requests for Data Exchange
+
+This document provides about API requests for the Data Exchange.
+
+## Postman
+
+There is a [postman collection](./postman) containing information on how to exchange data between provider and consumer.
+
+⚠️ _Change de webhook.site variable value to your respective one._
+
+## Curl
+
+There is a [curl tutorial](./curl) containing step by step tutorial on how to exchange data between provider and consumer, using the console.
+
+## NOTICE
+
+This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0).
+
+* SPDX-License-Identifier: Apache-2.0
+* SPDX-FileCopyrightText: 2024 Contributors to the Eclipse Foundation
+* Source URL: <https://github.com/eclipse-tractusx/tractus-x-umbrella>

docs/api/curl/UmbrellaConnectorDataExchange.md

@@ -0,0 +1,215 @@
+## Data Exchange Tutorial
+
+In order to start exchanging data, it will be necessary to install the subset with the necessary components for data exchange with the [Data Exchange Subset](https://github.com/eclipse-tractusx/tractus-x-umbrella/blob/umbrella-2.0.0/charts/umbrella/README.md#option-2-1):
+
+### Steps
+
+Once the data space has been launched, we will execute the following calls to perform the communication between the components
+
+> Variables enclosed in {{ }} mean that they are whose content has been obtained from the answers of previous calls.
+
+1. Create Asset
+```
+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": {},
+  "@id": "200",
+  "properties": {
+    "description": "Product EDC Demo Asset"
+  },
+  "dataAddress": {
+    "@type": "DataAddress",
+    "type": "HttpData",
+    "baseUrl": "http://dataprovider-submodelserver.tx.test/200"
+  }
+}'
+```
+
+2. Get Asset by ID
+To check if the asset is correctly created.
+```
+curl -L -X GET 'http://dataprovider-controlplane.tx.test/management/v3/assets/200' \
+-H 'X-Api-Key: TEST2'
+```
+
+3. Create Policy
+```
+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": "BusinessPartnerNumber",
+              "odrl:operator": {
+                "@id": "odrl:eq"
+              },
+              "odrl:rightOperand": "BPNL00000003AZQP"
+            }
+          ]
+        }
+      }
+    ]
+  }
+}'
+```
+
+4. Get Policies by ID
+To check if the Policies are correctly created.
+```
+curl -L -X GET 'http://dataprovider-controlplane.tx.test/management/v2/policydefinitions/200' \
+-H 'X-Api-Key: TEST2'
+```
+
+5. Create Contract Definition
+```
+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"
+  }
+}'
+```
+
+6. Get Contract Definition by ID
+To check if the Contract Definition is correctly executed
+```
+curl -L -X GET 'http://dataprovider-controlplane.tx.test/management/v2/contractdefinitions/200' \
+-H 'X-Api-Key: TEST2'
+```
+
+7. Query Catalog
+```
+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
+  }
+}'
+```
+We get the {{offer_id}} from the response.
+
+8. Initiate Negotiation
+```
+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",
+		"@id": "",
+         "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"
+	}
+}'
+```
+We get {{negotiation_id}} from the response.
+
+9. Get Negotiation By ID
+```
+curl -L -X GET 'http://dataconsumer-1-controlplane.tx.test/management/v2/contractnegotiations/' \
+-H 'X-Api-Key: TEST1'
+```
+You should be able to see in the response, that the _state_ value is equal to _FINALIZED_.
+
+We get {{contractagreement_id}} from the response.
+
+10. Initiate Transfer
+```
+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",
+  "contractId": "",
+  "assetId": "200",
+  "transferType": "HttpData-PULL",
+  "dataDestination":  {
+    "type": "HttpProxy"
+  },
+  "connectorId": "BPNL00000003AZQP",
+  "callbackAddresses": [
+    {
+      "transactional": true,
+      "uri": "http://dataprovider-submodelserver.tx.test/api/v1/transfers"
+    }
+  ]
+}'
+```
+We get {{transfer_id}} from the response
+
+11. Get Transfer by ID
+```
+curl -L -X GET 'http://dataconsumer-1-controlplane.tx.test/management/v2/transferprocesses/{{transfer_id}}' \
+-H 'X-Api-Key: TEST1'
+```
+You should be able to see in the response that the _state_ value is equal to _STARTED_.
+
+12. Validate Transfer
+```
+curl -L -X GET 'http://dataprovider-submodelserver.tx.test/api/v1/transfers/TEST1/contents'
+```