diff --git a/docs/files/figs/diagrams-components-tech.png b/docs/files/figs/diagrams-components-tech.png new file mode 100644 index 0000000..00ff3fd Binary files /dev/null and b/docs/files/figs/diagrams-components-tech.png differ diff --git a/docs/files/figs/diagrams.drawio b/docs/files/figs/diagrams.drawio index 6627b5f..62cb88e 100644 --- a/docs/files/figs/diagrams.drawio +++ b/docs/files/figs/diagrams.drawio @@ -1,6 +1,6 @@ - + - + @@ -324,10 +324,10 @@ - + - + @@ -893,10 +893,18 @@ - + + + + + + + + + @@ -1122,17 +1130,351 @@ - + - + - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/implementation.md b/docs/implementation.md index 8017073..504d61d 100644 --- a/docs/implementation.md +++ b/docs/implementation.md @@ -1,76 +1,114 @@ -# Backend Integration +# Technical components -## Sequences +We divide the implementation into two features: (1) onboarding and (2) data provisioning. -[//]: # (Do we need to implement the same flow as Catena-X? Their use case implementation includes two offers.) +![Component diagram](files/figs/diagrams-components-tech.png) +_Figure 1. Component diagram_ -![Push sequence](files/figs/diagrams-scenario-push-detail.png) +## Interactions -_Figure 1. Technical push sequence_ +### Onboarding + +After entering the company data and requesting access to the dataspace, the participant is technically onboarded. + +See [CFM interactions](https://github.com/Metaform/jad?tab=readme-ov-file#5-prepare-the-data-space). + +### Data Provisioning + +This use case implements the [pull sequence](use-case.md#pull). The SME acts as the data provider and another party acts as the data consumer, that downloads the provided certificate data. Figure 1 depicts a high-level interaction flow. ![Pull sequence](files/figs/diagrams-scenario-pull-detail.png) -_Figure 2. Technical pull sequence_ - -## APIs - -### Consumed Endpoints - -#### Integration of Connector API - -[//]: # (Integration of EDC MVD) - -#### Integration of Onboarding API - -[//]: # (Integration of MSP API) -[//]: # (Who implements this?) - -### Provided Endpoints - -#### Notification - -The application must be notified about onboarding status updates. A push approach provides the following advantages: -- Lower bandwidth consumption -- Real-time user experience / responsiveness -- Scalability and resource-efficiency - -Therefore, the application implements the following endpoint: - -POST `/api/notifications` - -Request body: -```json -{ - "@type": "OnboardingProcess", - "dataspaceId": {{DATASPACE_ID}}, -"status": {{STATUS}} -} -``` -Schema: - -```json -{ - "$schema": "http://json-schema.org/draft/2019-09/schema", - "$id": "https://example.com/schemas/onboarding-process.json", - "title": "OnboardingProcess", - "type": "object", - "properties": { - "@type": { - "type": "string", - "const": "OnboardingProcess" - }, - "dataspaceId": { - "type": "string" - }, - "status": { - "type": "string", - "enum": ["APPROVED", "DECLINED"] - } - }, - "required": ["@type", "dataspaceId", "status"], - "additionalProperties": false -} -``` - -Notes: The dataspace registration steps that require manual checks and approvals are mocked for the on-stage demo. +_Figure 1. Representative pull sequence_ + +| # | What | Who | +|---|------------------------------------------------|----------------| +| 1 | Prepare & publish data offering | Provider (SME) | +| 2 | Establish connection _(negotiate agreement)_ | Consumer | +| 3 | Approve access request _(negotiate agreement)_ | Provider (SME) | +| 4 | Download certificate data | Consumer | + +_Table 1. Steps for providing certificate data. Step 3 is not part of the demonstrator._ + +See [EDC-V interactions](https://github.com/Metaform/jad?tab=readme-ov-file#seeding-the-provider). + + + +### APIs + +In the following, we only list the APIs that are required to onboard the participant and provide a data offering. The demonstration requires to implement all endpoints of EDC-V and Connector Fabric Manager (CFM). + +#### Backend + +_Note: These interfaces must be implemented._ + +| # | Steps | Comment | Endpoint | +|---|-------------------------|-------------------------------------------------------------------------------|----------| +| 1 | Get list of dataspaces | names, agreements | | +| 2 | Create registration | company data, files, agreements | | +| 3 | Get registration data | incl. membership status | | +| 4 | Get list of partners | name, VAT, country, sector | | +| 5 | Create file | name, description, file, access (use case, partner)) | | +| 6 | Get list of files | name, description, tag, filetype, filesize, last modified, access information | | +| 7 | Get file details | incl. agreement and transaction history | | +| 8 | Get registration status | active, pending, inactive | | + +_Table 2. Endpoints for GUI interactions_ + +#### CFM + +See [Bruno collection](https://github.com/Metaform/jad/tree/main/requests/EDC-V%20Onboarding/CFM%20-%20Provision%20Provider). + +| # | Steps | Endpoint | +|---|----------------------------|-----------------------------------------------------------------------| +| 1 | Create tenant | {{tmBaseUrl}}/api/v1alpha1/tenants | +| 2 | Deploy participant profile | {{tmBaseUrl}}/api/v1alpha1/tenants/{{tenant_id}}/participant-profiles | + +_Table 3. Endpoints for connector management with CFM_ + +#### EDC-V + +The End-User API's backend implements the provider API of the EDC-V. See [Bruno collection](https://github.com/Metaform/jad/tree/main/requests/EDC-V%20Onboarding/EDC-V%20Management/Prepare%20Provider%20Participant). + +| # | Steps | Endpoint | +|---|----------------------------|----------------------------------------------------------------------------------| +| 1 | Upload certificate | {{baseURL}}/app/internal/api/control/certs | +| 2 | Create asset | {{baseURL}}/cp/api/mgmt/v4alpha/participants/{{provider_id}}/assets | +| 3 | Create policy definition | {{baseURL}}/cp/api/mgmt/v4alpha/participants/{{provider_id}}/policydefinitions | +| 4 | Create contract definition | {{baseURL}}/cp/api/mgmt/v4alpha/participants/{{provider_id}}/contractdefinitions | + +_Table 4. Endpoints for connector interactions_ + +#### JAD + +Other endpoints are implemented. See [Bruno collection](https://github.com/Metaform/jad/tree/main/requests/EDC-V%20Onboarding/EDC-V%20Management/Data%20Transfer/Http%20Certs/Provider). + +| # | Steps | Endpoint | +|---|------------------------------------|----------------------------------------------------| +| 1 | Querying uploaded certificate data | {{baseURL}}/app/internal/api/control/certs/request | + +_Table 5. Endpoints for certificate management with JAD_ + +## Transformers + +The backend must transform user input into backend requests (to CFM and EDC-V). + +- registration data must be mapped to CFM requests +- file upload data must be mapped to EDC-V requests + +## Persistence + +Required repositories for persistency, provided by the JAD database server (see [here](https://github.com/Metaform/jad?tab=readme-ov-file#components)). + +- tenants _(CFM database)_ +- credentials _(IdentityHub database, IssuerService database)_ +- assets _(? JAD)_ +- policy definitions _(? JAD)_ +- contract definitions _(? JAD)_ +- vault data _(Hashicorp Vault)_ +- certificate files (incl. metadata) _(? JAD)_ +- participants _(backend)_ +- registration data _(? backend)_ + - company data + - dataspace data \ No newline at end of file