Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add diagrams to e2e consumer and provider tests #180

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add diagrams to e2e consumer and provider tests #180

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 39 additions & 1 deletion docs/user/guides/data-exchange/consume-data.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,44 @@ In order to be able to consume data, it is necessary to have previously [provide
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.

```mermaid
sequenceDiagram
participant Alice as Alice (Consumer)
participant EDC_C as EDC Consumer
participant EDC_P as EDC Provider
participant Bob as Bob (Provider)

Alice->>EDC_C: 1. Query Catalog
EDC_C->>EDC_P: 2. Request Catalog
EDC_P-->>EDC_C: 3. Return Available Assets
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wouldn't it make sense to add the validation of the access policies here?

EDC_C-->>Alice: 4. Display Assets

Alice->>EDC_C: 5. Negotiate Contract
EDC_C->>EDC_P: 6. Contract Offer
EDC_P-->>EDC_C: 7. Contract Agreement
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wouldn't it make sense to add the validation of the policies here, especially the credentials?


Alice->>EDC_C: 8. Request Data
EDC_C->>EDC_P: 9. EDR Request
Note over EDC_C,EDC_P: Include auth token & endpoint
EDC_P->>Bob: 10. Validate EDR
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is Bob here doing? Imho, Bob is not concerned with EDR creation

Bob-->>EDC_P: 11. EDR Authorization
EDC_P-->>EDC_C: 12. EDR Response
Note over EDC_P,EDC_C: Contains data endpoint & token

EDC_C->>EDC_P: 13. Data Transfer Request
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Alice initiates the transfer, right?

Note over EDC_C,EDC_P: With EDR token
EDC_P->>Bob: 14. Fetch Data
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That is a bit ambiguous, as Bob is here the participant, not the participants backend system which stores some data. I would prefer to have Bob as an active person and the backend system as an own entitiy.

Bob-->>EDC_P: 15. Return Data
EDC_P-->>EDC_C: 16. Transfer Data
EDC_C-->>Alice: 17. Deliver Data
```
This diagram illustrates the three main phases of data consumption:
1. **Catalog Query**: Alice discovers available assets
2. **Contract Negotiation**: Alice negotiates access terms
3. **Data Transfer**: Alice receives the requested data

The default life time of the EDR token is 300s, its recommended for manual tests to extend the expiration time.

## 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.
Expand Down Expand Up @@ -66,7 +104,7 @@ that Alice needs to reference in the negotiation.

## Step 2: Initiate an edr

To consume the data, Alice uses the `OFFER_ID` `MjAw:MjAw:Y2ZjMzdlNmUtODAwNi00NGJjLWJhMWYtNjJkOWIzZWM0ZTQ3` from the previous catalog response and the target `ASSET_ID` `200` to initiate an [EDR](https://github.com/eclipse-tractusx/tractusx-edc/blob/main/docs/usage/management-api-walkthrough/07_edrs.md).
To consume the data, Alice uses the `OFFER_ID` `MjAw:MjAw:Y2ZjMzdlNmUtODAwNi00NGJjLWJhMWYtNjJkOWIzZWM0ZTQ3` from the previous catalog response and the target `ASSET_ID` `200` to initiate an Endpoint Data Reference ([EDR](https://github.com/eclipse-tractusx/tractusx-edc/blob/main/docs/usage/management-api-walkthrough/07_edrs.md)).

### EDR request

Expand Down
22 changes: 22 additions & 0 deletions docs/user/guides/data-exchange/provide-data.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,28 @@ You'll create an asset, define policies, and set up a contract definition for da
> - **Bob**: data provider, is reachable via `http://dataprovider-controlplane.tx.test`
> - **Alice**: data consumer, is reachable via `http://dataconsumer-1-controlplane.tx.test`

```mermaid
sequenceDiagram
participant Bob as Data Provider
participant EDC as connector
participant Alice as Data Consumer

Bob->>EDC: 1. Register Asset
Note over Bob,EDC: for data sharing
Bob->>EDC: 2. Create Policy
Note over Bob,EDC: Access & usage constrains
Bob->>EDC: 3. Create Contract Definition
Note over Bob,EDC: To link asset & policy
EDC->>Alice: 4. Asset Discovery
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is not favorable. With only the provider EDC in the game, you cannot describe Alice to retrieve the catalog, at least you should use ports here, to show, that Bob is using the management api to do his stuff and Alice is using the DSP api to retrieve the catalog. As is is decribed here, I would think that Alice is using the management api as well and we talk about a shared api-key scenario. This should not be indicated in any documentation.

Note over EDC,Alice: Asset catalog available
```

This diagram shows the data provision flow where:
1. Bob, as the Data Provider, registers his data asset with the EDC
2. Bob defines the access policy for his data
3. Bob creates a contract definition connecting his asset and policy
4. Alice, as the Data Consumer, can discover Bob’s asset through the catalog

## 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.
Expand Down
Loading