diff --git a/docs/adminGuide/Admin_Guide.md b/docs/adminGuide/Admin_Guide.md index 72be65b2..e25e893f 100644 --- a/docs/adminGuide/Admin_Guide.md +++ b/docs/adminGuide/Admin_Guide.md @@ -21,17 +21,21 @@ respective deployment scenarios for further information. Mainly one needs to configure the Frontend to reach the Backend. Thus, the Backend must be exposed or at least reachable for the Frontend. -Mainly the environment variables with the prefixes `BACKEND_` and `ENDPOINT_` are needed for configuration. Please refer -to the respective deployments for exact information. +When not using the Helm deployment, mainly the environment variables with the prefixes `BACKEND_` and `ENDPOINT_` are +needed for configuration. Please refer to the respective local deployment for exact information. The Backend secures all APIs except for the swagger ui with a backend key. -This api key must be configured in the `application.properties` with the `puris.api.key` property. +This api key must be configured in the backend via `backend.puris.api.key` (docker `PURIS_API_KEY`). In Helm, it's +automatically set to the frontend. Additionally spring provides the context path that adds a path for the backend servlets. The Frontend therefore needs the following two variables: -- `BACKEND_BASE_URL` - used to assemble requests to the backend in format: `http:///` -- `BACKEND_API_KEY `- the api key used in the backend -- `ENDPOINT_XYZ` - endpoints of the backend used. But they are hardcoded in the backend. + +- `frontend.puris.baseUrl` (docker `BACKEND_BASE_URL`) - used to assemble requests to the backend in + format: `http:///` where context path is assembled automatically via template. Is + automatically assembled via helm. +- `frontend.puris.endpointXYZ` (docker `ENDPOINT_XYZ`) - endpoints of the backend used. But they are hardcoded in the + backend. _Note: The API key header is hard coded to `X-API-KEY`._ @@ -47,11 +51,13 @@ Configure EDC addresses in the Backend with prefix `edc.`. Refer to the respecti The Frontend provides a keycloak integration: It restricts the accessible views based on the client roles: + - `PURIS_USER` - Common views related to short-term information needs - `PURIS_ADMIN` - EDC related views (may be used for debugging) -All variables with the `IDP_` prefix are needed for configuration. `IDP_DISABLE` can be set to `true` to not use an idp -(only recommended for development purposes). Refer to the respective deployment specific files. +All variables with the `frontend.puris.keycloak.` (docker prefix is `IDP_`) prefix are needed for configuration. +The `disable` property (docker `IDP_DISABLE`) can be set to `true` to not use an idp (only recommended for development +purposes). Refer to the respective deployment specific files. Configuration and example: @@ -59,19 +65,35 @@ To host an example keycloak instance, configure the following: - `Realm` with name `Catena-X` - Create `Client` with name `Cl3-PURIS` - - `Client authentication` = false - - `Authentication flow `> `Standard flow` = `true` (rest `false`) - - `Access settings` - - `Valid redirect URIs` = `http:/*` - - `Valid post logout redirect URIs` = `http:` - - `Web origins` = `http://` - - `Roles`: Create `PURIS_ADMIN`, `PURIS_USER` + - `Client authentication` = false + - `Authentication flow `> `Standard flow` = `true` (rest `false`) + - `Access settings` + - `Valid redirect URIs` = `http:/*` + - `Valid post logout redirect URIs` = `http:` + - `Web origins` = `http://` + - `Roles`: Create `PURIS_ADMIN`, `PURIS_USER` - Create `users` as wanted - - puris_test with same password (see credentials tab) - - add roles in client + - puris_test with same password (see credentials tab) + - add roles in client _Note: The application does NOT make use of the `Client Authentication` (private) feature of Keycloak Clients._ +## Configure Framework Agreement Credential Usage + +To configure the usage of a framework agreement credential, that is automatically enforced by the EDC during contracting +(see further details in [ARC42 - Chapter 8](../arc42/08_concepts.md)), the following properties need to be configures: + +- `backend.frameworkagreement.use` (docker `PURIS_FRAMEWORKAGREEMENT_USE`) = true +- `backend.frameworkagreement.credential` (docker `PURIS_FRAMEWORKAGREEMENT_CREDENTIAL`) = 'puris' (NOTE: not available + for R24.03) + +_**ATTENTION**: If the credential is NOT listed in the Connector Standard (CX-0018) of the current release, then the +Tractus-X EDC will NOT technically enforce the credential by checking the availability in the Managed Identity Wallet. +Thus, it may seem that the Credential is available, but isn't. Same applies to typos._ + +_Note: Please refer to +the [Portal's documentation on how to sign use case agreements](https://github.com/eclipse-tractusx/portal-assets/blob/main/docs/user/06.%20Certificates/01.%20UseCase%20Participation.md)._ + ## Serving with HTTPS / SSL Serving with SSL is available for Docker and Helm Deployment. In local deployment directly with mvn (backend) and @@ -86,6 +108,7 @@ The Frontend uses a nginx-unprivileged image restricting access heavily. One can starting point. Let's assume the following structure: + ```shell ls >> / @@ -96,6 +119,7 @@ ls ``` For testing purposes, create self-signed certificates: + ``` sh mkdir ssl-certificates cd ssl-certificates @@ -105,9 +129,11 @@ openssl req -x509 -out localhost.crt -keyout localhost.key \ -subj '/CN=localhost' -extensions EXT -config <( \ printf "[dn]\nCN=localhost\n[req]\ndistinguished_name = dn\n[EXT]\nsubjectAltName=DNS:localhost\nkeyUsage=digitalSignature\nextendedKeyUsage=serverAuth") ``` + _NOTE: For productive use, you can use certificates provided by a Certificate Authority._ Create a nginx.conf to provide certificates for listening on 443 for tls. + ``` conf http { # other configurations @@ -130,6 +156,7 @@ http { ``` Start the docker image mounting the certificates and the nginx.conf as follows: + ``` sh docker run --rm --name frontend \ @@ -140,6 +167,7 @@ docker run --rm --name frontend \ ``` If you want to use of the dns alias for localhost:443, make sure to edit your /etc/hosts file: + ```sh docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' @@ -153,6 +181,7 @@ sudo vim /etc/hosts Spring provides the possibility to provide ssl certificates. Let's assume the following structure: + ```shell ls >> / @@ -163,16 +192,19 @@ ls For testing purposes, create self-signed certificates using java keytool and follow the prompts. Remember the password. They generated key file is a pkcs12 keystore. + ``` sh mkdir ssl-certificates cd ssl-certificates keytool -genkeypair -alias application -keyalg RSA -keysize 4096 -storetype PKCS12 -keystore application.p12 -validity 3650 ``` + _NOTE: For productive use, you can use certificates provided by a Certificate Authority._ Use your common application.properties and add the following section to the file. Name it e.g., application-with-ssl.properties. + ```application.properties server.ssl.enabled=false #server.port=8443 @@ -184,6 +216,7 @@ spring.ssl.bundle.jks.server.keystore.type=PKCS12 ``` Finally pass the created keystore and properties file via docker: + ```shell docker run --rm -d -p 8433:8433 --name backend \ -v $(pwd)/ssl-certificates/application.p12:/opt/app/ssl-certificates/application.p12 \ @@ -198,18 +231,18 @@ When using self-signed certificates, the frontend may result in a CORS error. Th problem. Please check if you created exceptions for both certificates, the frontend's and backend's certificates. You can see a related error in the Developer Tools (F12) > Network tab > select preflight header > tab security. - ## Onboarding Your Data The application, per solution strategy, tries to provide visualization and manipulation capabilities to exchange only production related information. -_Note: The routes in the following always need to be used based on your backend address configuration including the +_Note: The routes in the following always need to be used based on your backend address configuration including the context path._ ### Onboard Master Data -The application provides the following endpoints to update master data for your partner. This data may not be entered manually. +The application provides the following endpoints to update master data for your partner. This data may not be entered +manually. You can use this collection as an example for the REST API calls. @@ -232,6 +265,6 @@ overwrite the existing stocks. ## Postgres -The PURIS Backend uses a postgres Database. The helm installation already has a dependency that may be installed with -the chart. Optionally it may be disabled to use your own installation. Refer to the overall +The PURIS Backend uses a postgres Database. The helm installation already has a dependency that may be installed with +the chart. Optionally it may be disabled to use your own installation. Refer to the overall [INSTALL.md](../../INSTALL.md) for further information. diff --git a/docs/arc42/02_architecture_constraints.md b/docs/arc42/02_architecture_constraints.md index 6262413f..cb2b00ac 100644 --- a/docs/arc42/02_architecture_constraints.md +++ b/docs/arc42/02_architecture_constraints.md @@ -6,7 +6,7 @@ PURIS FOSS follows the following constraints: |--------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | IDS & GAIA-X Compliance | Data sharing, storing and processing must be in compliance to the standards provided by GAIA-X and IDS. | | Data Sharing between Companies | Companies must use IDS compliant and certified connectors along with an approved Catena-X information model for communication. This guarantees interoperability between certified participants. The Eclipse Dataspace Connector is highly recommended for this purpose. The data should stay inside the connector if full data sovereignty is necessary. | -| Data sovereignty | To ensure data sovereignty, data owners need to attach machine readable usage policies to their data before sharing. The data consumer has to accept the usage policies before processing the data. Connectors (+ the underlying/corresponding systems) must technically enforce those usage policy descriptions. | -| DAPS | DAPS Registration Service is a central Catena-X Service, which allows registering connectors remotely in Catena-X DAPS service. This Service can be used by all operators of connectors (on-premise, managed) | +| Data sovereignty | To ensure data sovereignty, data owners need to attach machine readable access policies and contract policies to their data before sharing. The data consumer has to accept the usage policies before processing the data. Connectors (+ the underlying / corresponding systems) must technically enforce those usage policy descriptions. | +| Managed Identity Wallet (MIW) | MIW is a central Catena-X Service, which allows storing credentials to prove claims in the Catena-X data space. | | Interoperability between Data Applications | Data exchange MUST follow standards so that different vendors applications may exchange data. This allows to reduce the risk of vendor-lock-ins. | -| Semantic Aspect Meta Model | Tooling used in Catena-X to semantically describe data. | +| Semantic Aspect Meta Model (SAMM) | Tooling used in Catena-X to semantically describe data. | diff --git a/docs/arc42/03_system_scope_and_context.md b/docs/arc42/03_system_scope_and_context.md index 8786a032..549153e1 100644 --- a/docs/arc42/03_system_scope_and_context.md +++ b/docs/arc42/03_system_scope_and_context.md @@ -1,6 +1,6 @@ # System Scope and Context -The first draft of this application only targets to provide a possibility to enter and exchange stock information +The first draft of this application only targets to provide a possibility to enter and exchange stock information related to partners. This application scope follows the following information. ## Business Context @@ -8,30 +8,44 @@ related to partners. This application scope follows the following information. PURIS FOSS may be operated in any supply network, but currently will likely be operated in the automotive supply network. -**\** +![Business Context](img/03-business-context.svg) **Disposition** -The disposition has a major information need to keep a material flow into and out of the production. The disposition steers the allocation of material within the production. PURIS supports the disposition to identify shortages by providing relevant information regarding the material flow. +The disposition has a major information need to keep a material flow into and out of the production. The disposition +steers the allocation of material within the production. PURIS supports the disposition to identify shortages by +providing relevant information regarding the material flow. **Production (Process)** -Production is the actually value-adding process of a manufacturer. It's demand is derived by outer factors such as orders. A lack of material in supply chains leads to shortages. The production process has to be seen as a consumer of data provided by PURIS (Catena-X data consumer) and as a provider of data to PURIS (Catena-X data provider). In that way PURIS is able to fulfill the disposition's information need. +Production is the actually value-adding process of a manufacturer. It's demand is derived by outer factors such as +orders. A lack of material in supply chains leads to shortages. The production process has to be seen as a consumer of +data provided by PURIS (Catena-X data consumer) and as a provider of data to PURIS (Catena-X data provider). In that way +PURIS is able to fulfill the disposition's information need. **Logistics** -For a production process it is necessary to fulfill its logistics requirements. That means that the material in demand is given in the necessary quantity at the right time at the right place (see seven Rs above). PURIS targets to support the information flow to overview this problem task. +For a production process it is necessary to fulfill its logistics requirements. That means that the material in demand +is given in the necessary quantity at the right time at the right place (see seven Rs above). PURIS targets to support +the information flow to overview this problem task. **(Automotive) Supply Chain** -Supply chains synchronize demands with the supply. They are networks and not linear, as each customer commonly has more than 1 supplier of services or physical goods. Supply chains are commonly supported by three flows: material flow, finance flow and information flow. For PURIS the information flow is the relevant one. +Supply chains synchronize demands with the supply. They are networks and not linear, as each customer commonly has more +than 1 supplier of services or physical goods. Supply chains are commonly supported by three flows: material flow, +finance flow and information flow. For PURIS the information flow is the relevant one. - Customers send (demand) forecasts and purchase Orders to their suppliers or manufacturers. - Suppliers and manufacturers send shipment information to their customers. -There are existing EDI formats describing this kind of information in a detailed way. Additionally, the VDA publishes recommendations on how to use the DELFOR (UN standard EDI message) in the automotive supply chain. While the VDA standards (delivery forecasts, delivery call-offs, orders, despatch advices, inventory reports, etc) only apply to the first tiers of the automotive supply chain, later tiers won't be following the VDA standards - either because of their size or because their operating their business in different domains. Those companies are likely to work with DELFOR message standards, too OR even don't do EDI. +There are existing EDI formats describing this kind of information in a detailed way. Additionally, the VDA publishes +recommendations on how to use the DELFOR (UN standard EDI message) in the automotive supply chain. While the VDA +standards (delivery forecasts, delivery call-offs, orders, despatch advices, inventory reports, etc) only apply to the +first tiers of the automotive supply chain, later tiers won't be following the VDA standards - either because of their +size or because their operating their business in different domains. Those companies are likely to work with DELFOR +message standards, too OR even don't do EDI. ## Technical Context The Technical Context has been derived from the architecture constraints: -**\** +![Technical Context](img/03-technical-context.svg) **PURIS FOSS** @@ -39,12 +53,21 @@ The PURIS FOSS is a system consuming short-term supply information supporting id **SAMM** -SAMM is a technology used to define submodel information for the Asset Administration Shell (AAS). SAMM is used to define the actual payload of the APIs used in PURIS FOSS. +SAMM is a technology used to define submodel information for the Asset Administration Shell (AAS). SAMM is used to +define the actual payload of the APIs used in PURIS FOSS. **Tractus-X Connector** -The [Tractus-X Connector](https://github.com/eclipse-tractusx/tractusx-edc) (abbreviated and simplified as EDC) is a Catena-X specific implementation of the [Eclipse Dataspace Components Connector (EDC)](https://github.com/eclipse-edc/Connector) is an open-source framework which can be used to participate within an International Data Space (IDS). +The [Tractus-X Connector](https://github.com/eclipse-tractusx/tractusx-edc) (abbreviated and simplified as EDC) is a +Catena-X specific implementation of +the [Eclipse Dataspace Components Connector (EDC)](https://github.com/eclipse-edc/Connector) is an open-source framework +which can be used to participate within an International Data Space (IDS). -*Sovereign data exchange* +*Sovereign Data exchange* -To ensure data sovereignty, access and usage policies (prohibitions, permissions, obligations) may be attached as a machine readable defintion by data owners before sharing their data. The data consumer has to accept the policies before processing the data (human readable, machine readable). Connectors (and the underlying/corresponding systems) must technically enforce usage policies while there is also legal governance. An access and usage contract can be negotiated beforehand along with access and usage policies to ensure parties agree upon. It is necessary that data apps are compliant to the usage policies, since the policies define data processing rules. +To ensure data sovereignty, access and usage policies (prohibitions, permissions, obligations) may be attached as a +machine readable defintion by data owners before sharing their data. The data consumer has to accept the policies before +processing the data (human readable, machine readable). Connectors (and the underlying/corresponding systems) must +technically enforce usage policies while there is also legal governance. An access and usage contract can be negotiated +beforehand along with access and usage policies to ensure parties agree upon. It is necessary that data apps are +compliant to the usage policies, since the policies define data processing rules. diff --git a/docs/arc42/05_building_block_view.md b/docs/arc42/05_building_block_view.md index 4f2f9581..d653a191 100644 --- a/docs/arc42/05_building_block_view.md +++ b/docs/arc42/05_building_block_view.md @@ -1,9 +1,9 @@ # Building Block View -The components or (sub-) systems do have the following capabilities. Please note that the authentication flows have +The components or (sub-) systems do have the following capabilities. Please note that the authentication flows have been omitted for readability. -![Level 0 - Blackbox View](puml/05-level-0.svg) +![Level 0 - Blackbox View](img/05-level-0.svg) | Component / system | Descriptions | |------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| @@ -18,7 +18,7 @@ been omitted for readability. **PURIS FOSS Frontend** -![Level 1 - Whitebox View - PURIS FOSS Frontend](puml/05-level-1-frontend.svg) +![Level 1 - Whitebox View - PURIS FOSS Frontend](img/05-level-1-frontend.svg) The Frontend only handles visualization logic. The remaining logic is handled in the backend. @@ -31,7 +31,7 @@ The Frontend only handles visualization logic. The remaining logic is handled in **PURIS FOSS Backend** -![Level 1 - Whitebox View - PURIS FOSS Backend](puml/05-level-1-backend.svg) +![Level 1 - Whitebox View - PURIS FOSS Backend](img/05-level-1-backend.svg) | Component / system | Descriptions | |--------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------| diff --git a/docs/arc42/06_runtime_view.md b/docs/arc42/06_runtime_view.md index e9b999c4..cab7426d 100644 --- a/docs/arc42/06_runtime_view.md +++ b/docs/arc42/06_runtime_view.md @@ -7,29 +7,32 @@ The runtime view mainly focuses on two separate scenarios. One can either intera The information exchange in PURIS follows a response and request pattern. Requests are directly answered based on existing data as soon as they arrive. The diagram does not integrate the EDC to explain the overall flow. -![Overview of request and response](puml/06-api-flow.svg) +![Overview of request and response](img/06-api-flow.svg) The request and response flow both implement a message header and a content section in the exchanged data. + - the message header contains information about the message. - the content contains either the request (material numbers) or the response (respective SAMM model as json payload). The API implementations are provided and consumed via the EDC. + 1. A data asset is created on Startup by the `AssetCreatedCommandLineRunner`. 1. To request new data 1. the partners' catalog is queried to search for the request api. 1. the contract is negotiated. - 1. the transfer is initialized using the [dynamic http receiver EDC extension](https://github.com/eclipse-edc/Connector/tree/main/extensions/control-plane/transfer/transfer-pull-http-dynamic-receiver). - 1. the "consumer pull" flow is used (see [sample](https://github.com/eclipse-edc/Samples/tree/main/transfer/transfer-06-consumer-pull-http)) + 1. the transfer is initialized using + the [dynamic http receiver EDC extension](https://github.com/eclipse-edc/Connector/tree/main/extensions/control-plane/transfer/transfer-pull-http-dynamic-receiver). + 1. the "consumer pull" flow is used ( + see [sample](https://github.com/eclipse-edc/Samples/tree/main/transfer/transfer-06-consumer-pull-http)) 1. Provider receives EDR token by `EndpointDataReferenceReceiver`. 1. Provider queries API for information of interest based on the standardized API description. 1. Consumer receives request, determines data for response and starts with step 2 for the response interface. The workflow with simplified EDC communication may be seen in the following sequence diagram. -EDC flow is the same to use the request and response api. Central Services, such as the Managed Identity Wallet are +EDC flow is the same to use the request and response api. Central Services, such as the Managed Identity Wallet are ommitted. -![Overview of request and response with EDC](puml/06-api-flow-detailed.svg) - +![Overview of request and response with EDC](img/06-api-flow-detailed.svg) ## Scenario: Interact with data in web-ui @@ -37,6 +40,7 @@ When reloading the UI, the latest data is pulled from the backend. Whenever an u then the frontend hands over the data to the backend to perform the action. The web-ui allows the following interactions: + - create or update stocks for a partner. - select a specific stock to see the related partner stocks. - Trigger an update for all partner's data for a specific material (see previous Scenario). diff --git a/docs/arc42/07_deployment_view.md b/docs/arc42/07_deployment_view.md index d0f9cee6..da8e65c0 100644 --- a/docs/arc42/07_deployment_view.md +++ b/docs/arc42/07_deployment_view.md @@ -2,21 +2,23 @@ ## Local Deployment -Overall the Deployment locally using the [INSTALL.md in local](../../local/INSTALL.md) looks similar to the following graphic. +Overall the Deployment locally using the [INSTALL.md in local](../../local/INSTALL.md) looks similar to the following +graphic. -![Local Deployment of two PURIS clients with MVD](./puml/07-deployment.svg) +![Local Deployment of two PURIS clients with MVD](img/07-deployment.svg) **Helm / Kubernetes** -One can configure the two local helm environments using the product helm chart and the [mxd tutorial](https://github.com/eclipse-tractusx/tutorial-resources/tree/main/mxd). +One can configure the two local helm environments using the product helm chart and +the [mxd tutorial](https://github.com/eclipse-tractusx/tutorial-resources/tree/main/mxd). ## ArgoCD Deployment (e.g. INT) The very basic deployment for one PURIS FOSS looks as follows: -![Argo CD Deployment of one PURIS client](./puml/07-deployment-argo.svg) +![Argo CD Deployment of one PURIS client](img/07-deployment-argo.svg) -The keycloak may be configured to be used. Also a decentral instance may be connected to the frontend. Refer to the +The keycloak may be configured to be used. Also a decentral instance may be connected to the frontend. Refer to the [helm docs](../../charts/puris/README.md) for further information. The chart allows also to either install the database as a dependency or bring your own. diff --git a/docs/arc42/08_concepts.md b/docs/arc42/08_concepts.md index 77754cd8..b67ae0da 100644 --- a/docs/arc42/08_concepts.md +++ b/docs/arc42/08_concepts.md @@ -3,7 +3,7 @@ ## Multi-Partner Information Within the supply network there may be materials / parts that are produced for multiple partners or customers that -share the same material number. +share the same material number. A partner asking for information may not receive any information that are not meant for him. Therefor the PURIS concept is, that exchanged information MUST be allocated to a partner to not leak any partner relationships in the vertical direction. @@ -12,13 +12,29 @@ direction. In the backend materials are commonly handled by the own material number. The partner material relationship then brings the respective material number of a partner leading to the following constellations: -- puris user acts as customer: - - own material number = material number customer - - material number partner = material number supplier -- puris user acts as supplier: + +- puris user acts as customer: + - own material number = material number customer + - material number partner = material number supplier +- puris user acts as supplier: - own material number = material number supplier - material number partner = material number customer +## Data Sovereignty + +The application only provides assets (API usage) based on a Business Partner Number Legal Entity (BPNL) based access +policy via the [Tractus-X EDC](https://github.com/eclipse-tractusx/tractusx-edc). All traffic to exchange +information is routed through the EDC data plane using the proxy pull mechanism. + +Whenever a partner is created, all exchanged information APIs that comply to a Catena-X standard are registered as +contract offer for the partner's BPNL. + +Additionally, the administrator may configure the application to use a framework agreement policy for data offers (see +[Administration Guide](../adminGuide/Admin_Guide.md)). When activated, + +- the application requires the respective credential to be active for the partner. +- the application requires the framework agreement credential as contract policy when contracting a partner's offer as a + consumer. ## Security diff --git a/docs/arc42/12_glossary.md b/docs/arc42/12_glossary.md index b1271ebd..d916afec 100644 --- a/docs/arc42/12_glossary.md +++ b/docs/arc42/12_glossary.md @@ -20,6 +20,7 @@ | Position | | A position within an order defines the material and the quantity the supplier has to manufacture / supply for a customer. A single order may contain multiple positions for different materials. | ## Technical Glossary + | Name | Abrv. | Description | |----------------------------------------------------------------------|-------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Master Data | MAD | Data which is commonly maintained once and them operationally used e.g., partners with adresses. | @@ -31,3 +32,4 @@ | Asset Administration Shell | AAS | Specification mainained by the International Digital Twin Association (IDTA) to manage and administrate digital representations of assets (concepts, physical device, process, etc.). Used synonymously with the term "Digital Twin". | | Semantic Aspect Meta Model | SAMM | A formal, machine-readable semantic description (expressed with RDF/turtle) of data accessible from an Aspect. Note 1 to entry: An Aspect Model must adhere to the Semantic Aspect Meta Model (SAMM), i.e., it utilizes elements and relations defined in the Semantic Aspect Meta Model and is compliant to the validity rules defined by the Semantic Aspect Meta Model. Note 2 to entry: Aspect model are logical data models which can be used to detail a conceptual model in order to describe the semantics of runtime data related to a concept. Further, elements of an Aspect model can/should refer to terms of a standardized Business Glossary (if existing). [Source: Catena-X, CX-0002](https://catena-x.net/de/standard-library) | | Digital Twin | DT | Digital representation of an asset (concept, physical device, process, etc.). Realized using the Asset Administration Shell. Used synonymously with the term "Asset Administration Shell". | +| Managed Identity Wallet | MIW | Service providing verifieable credentials to be proof claims. | diff --git a/docs/arc42/img/03-business-context.svg b/docs/arc42/img/03-business-context.svg new file mode 100644 index 00000000..37951beb --- /dev/null +++ b/docs/arc42/img/03-business-context.svg @@ -0,0 +1,74 @@ + + + + + + + + + + Disposition + + + + + + + + Production (Process) + + + + + + + + Logistics + + + + + + + + (Automotive) Supply Chain + + + + + + + + PURIS FOSS + + + + + + + + + + + + + + + + diff --git a/docs/arc42/img/03-technical-context.svg b/docs/arc42/img/03-technical-context.svg new file mode 100644 index 00000000..ac97a24f --- /dev/null +++ b/docs/arc42/img/03-technical-context.svg @@ -0,0 +1,60 @@ + + + + + + + + + + SAMM + + + + + + + + Tractus-X EDC + + + + + + + + Sovereign Data Exchange + + + + + + + + PURIS FOSS + + + + + + + + + + + + + diff --git a/docs/arc42/img/05-level-0.svg b/docs/arc42/img/05-level-0.svg new file mode 100644 index 00000000..3b638d95 --- /dev/null +++ b/docs/arc42/img/05-level-0.svg @@ -0,0 +1,134 @@ + + + + + + + + + «system» PURIS + + + + + + + + PURIS FOSS Backend + + + + + + + + PURIS FOSS Frontend + + + + + + + + Data Provisioning & Transformation + + + + + + + + Eclipse DataSpace Components Connector + + + + + + + + Postgresql DB + + + + + + + + Keycloak + + + + + Interface internal systems + + + + + EDC APIs + + + + + + + + + + + + + provide and pull data + + according to standards + + + + + + + + + + + + + + + + + + diff --git a/docs/arc42/img/05-level-1-backend.svg b/docs/arc42/img/05-level-1-backend.svg new file mode 100755 index 00000000..b5286216 --- /dev/null +++ b/docs/arc42/img/05-level-1-backend.svg @@ -0,0 +1,108 @@ + + + + + + + + «system» PURIS FOSS Backend + + + + + + + + EDC + + + + + EDC Client Interface + + + + + + + + Stock + + + + + Stock Interface + + + + + Stock Request & + + Response Interfaces + + (through EDC) + + + + + + + + MAD + + + + + MAD Interface + + + + + + + + + + + + + + query catalog & + + request data (via edc) + + + + + + + + + + diff --git a/docs/arc42/img/05-level-1-frontend.svg b/docs/arc42/img/05-level-1-frontend.svg new file mode 100644 index 00000000..a15499fe --- /dev/null +++ b/docs/arc42/img/05-level-1-frontend.svg @@ -0,0 +1,114 @@ + + + + + + + + «system» PURIS FOSS Frontend + + + + + + + + Stock View + + + + + + + + Dashboard + + + + + + + + Authentication Service + + + + + + + + Access Service + + + + + + + + Keycloak + + + + + Stock Interface + + + + + MAD interface + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/arc42/puml/06-api-flow-detailed.svg b/docs/arc42/img/06-api-flow-detailed.svg similarity index 100% rename from docs/arc42/puml/06-api-flow-detailed.svg rename to docs/arc42/img/06-api-flow-detailed.svg diff --git a/docs/arc42/img/06-api-flow.svg b/docs/arc42/img/06-api-flow.svg new file mode 100755 index 00000000..1cf39a34 --- /dev/null +++ b/docs/arc42/img/06-api-flow.svg @@ -0,0 +1,117 @@ + + + + + + Data Consumer + + + Data Provider + + + + + + Business + + Application + + + Business + + Application + + + Business + + Application + + + Business + + Application + + + + + 1 + + Request Information Object Exchange + + + + Request Endpoint + + + + 2 + + Accepted + + + + + + 3 + + Determine requested Information Object + + + + 4 + + Send requested Information Object + + + + Response Endpoint + + + + 5 + + Accepted + + + diff --git a/docs/arc42/puml/07-deployment-argo.svg b/docs/arc42/img/07-deployment-argo.svg similarity index 100% rename from docs/arc42/puml/07-deployment-argo.svg rename to docs/arc42/img/07-deployment-argo.svg diff --git a/docs/arc42/puml/07-deployment.svg b/docs/arc42/img/07-deployment.svg similarity index 100% rename from docs/arc42/puml/07-deployment.svg rename to docs/arc42/img/07-deployment.svg diff --git a/docs/arc42/puml/03-business-context.puml b/docs/arc42/puml/03-business-context.puml new file mode 100644 index 00000000..38b6ba57 --- /dev/null +++ b/docs/arc42/puml/03-business-context.puml @@ -0,0 +1,13 @@ +@startuml +[Disposition] as disposition +[Production (Process)] as production +[Logistics] as logistics +[(Automotive) Supply Chain] as sc +[PURIS FOSS] as puris + +disposition -- puris +production - puris +puris - logistics +puris -- sc + +@enduml diff --git a/docs/arc42/puml/03-technical-context.puml b/docs/arc42/puml/03-technical-context.puml new file mode 100644 index 00000000..b10e5367 --- /dev/null +++ b/docs/arc42/puml/03-technical-context.puml @@ -0,0 +1,11 @@ +@startuml +[SAMM] as samm +[Tractus-X EDC] as edc +[Sovereign Data Exchange] as sov +[PURIS FOSS] as puris + +samm -- puris +edc - puris +puris - sov + +@enduml diff --git a/docs/arc42/puml/05-level-0.puml b/docs/arc42/puml/05-level-0.puml index 3e53f252..760c0790 100644 --- a/docs/arc42/puml/05-level-0.puml +++ b/docs/arc42/puml/05-level-0.puml @@ -6,7 +6,7 @@ data_prov -( "Interface internal systems" edc -- "EDC APIs" -e + package "<> PURIS"{ [PURIS FOSS Backend] as puris_backend diff --git a/docs/arc42/puml/05-level-0.svg b/docs/arc42/puml/05-level-0.svg deleted file mode 100644 index 03fcdfc9..00000000 --- a/docs/arc42/puml/05-level-0.svg +++ /dev/null @@ -1,4 +0,0 @@ - -«system» PURISPURIS FOSS BackendPURIS FOSS FrontendData Provisioning & TransformationEclipse DataSpace Components ConnectorPostgresql DBKeycloakInterface internal systemsEDC APIsprovide and pull dataaccording to standards diff --git a/docs/arc42/puml/05-level-1-backend.svg b/docs/arc42/puml/05-level-1-backend.svg deleted file mode 100755 index 9e88797a..00000000 --- a/docs/arc42/puml/05-level-1-backend.svg +++ /dev/null @@ -1 +0,0 @@ -«system» PURIS FOSS BackendEDCEDC Client InterfaceStockStock InterfaceStock Request &Response Interfaces(through EDC)MADMAD Interfacequery catalog &request data (via edc) \ No newline at end of file diff --git a/docs/arc42/puml/05-level-1-frontend.svg b/docs/arc42/puml/05-level-1-frontend.svg deleted file mode 100644 index 54e947c1..00000000 --- a/docs/arc42/puml/05-level-1-frontend.svg +++ /dev/null @@ -1,4 +0,0 @@ - -«system» PURIS FOSS FrontendStock ViewDashboardAuthentication ServiceAccess ServiceKeycloakStock InterfaceMAD interface diff --git a/docs/arc42/puml/06-api-flow.svg b/docs/arc42/puml/06-api-flow.svg deleted file mode 100755 index 62510776..00000000 --- a/docs/arc42/puml/06-api-flow.svg +++ /dev/null @@ -1 +0,0 @@ -Data ConsumerData ProviderBusinessApplicationBusinessApplicationBusinessApplicationBusinessApplication1Request Information Object ExchangeRequest Endpoint2Accepted3Determine requested Information Object4Send requested Information ObjectResponse Endpoint5Accepted \ No newline at end of file diff --git a/docs/interfaceDoc/Interface_Doc.md b/docs/interfaceDoc/Interface_Doc.md index e894c2a0..d015f4cc 100644 --- a/docs/interfaceDoc/Interface_Doc.md +++ b/docs/interfaceDoc/Interface_Doc.md @@ -1,6 +1,6 @@ # Interface Documentation -This document provides information on the interfaces. It more or less links you to the relevant sections in other +This document provides information on the interfaces. It more or less links you to the relevant sections in other documentations. ## Overview of Data Exchange Interfaces @@ -8,7 +8,8 @@ documentations. The [arc42 documentation](../arc42/Index.md) provides an overview based on the following chapters: - [Building Block View](../arc42/05_building_block_view.md) shows which kind of interfaces are present -- [Runtime View](../arc42/06_runtime_view.md) shows how data with participants is exchanged +- [Runtime View](../arc42/06_runtime_view.md) shows how data with participants is exchanged (implementation of + standardization candidate) ## Swagger documentation @@ -18,7 +19,7 @@ You can refer to the INT environment application to view the swagger ui. http://puris-customer.int.demo.catena-x.net/swagger-ui/index.html ``` -If not reachable, you can also deploy the backend application according to the [Install.md](../../backend/INSTALL.md) in +If not reachable, you can also deploy the backend application according to the [Install.md](../../backend/INSTALL.md) in the backend and use the following path. ``` @@ -29,5 +30,5 @@ _Note: The port and the path depend on the configuration of the spring backend ( ## Postman -There is a [postman collection](../../local/postman/puris-integration-test.postman_collection.json) containing +There is a [postman collection](../../local/postman/README.md) containing information on how to provide master data and some basic data to test the application. diff --git a/docs/userGuide/User_Guide.md b/docs/userGuide/User_Guide.md index 500182c9..99dfd21c 100644 --- a/docs/userGuide/User_Guide.md +++ b/docs/userGuide/User_Guide.md @@ -1,6 +1,7 @@ # User Guide This guide explains the overall masks that may be used by different roles. + - A `PURIS_USER` may see use views "View and Manage Stocks" and "Supplier Dashboard". - A `PURIS_ADMIN` may _additionally_ use the views "Catalog", "Negotiations" and "Transfers". @@ -13,15 +14,19 @@ Note: A user may additionally log out or see license information of the applicat This view allows a user to either create material or product stocks and allocate them to a partner. Stocks always need to be allocated to a partner due to potential multi-sourcing scenarios. +![Stock View with a Material Stock](img/stock_view.png) + The view is divided horizontally into three parts: + 1. Create or Update Material / Product Stocks 2. Material Stocks 3. Product Stocks ### Create or update Material / Product Stocks -The view allows a user to either add a material (user selected radio button 'Material') or a product +The view allows a user to either add a material (user selected radio button 'Material') or a product (user selected radio button 'Product'). The user then + 1. Either selects a Material or Product. 2. Sets the partner who will receive (Product) or from whom one received (Material) the stock. 3. Sets a quantity that is on stock with a selected unit of measurement (UOM). @@ -31,37 +36,115 @@ The view allows a user to either add a material (user selected radio button 'Mat The updated or created stocks can be seen in the related section after triggering button "Add or Update". +![Stock View after adding a Material Stock](img/stock_view_added_material_stock.png) + ### Material Stocks The table shows the relevant information regarding all material stocks that are at your sites. The user may select one -stock to see which of the selected material are already allocated on supplier side. Using the button "Update Partner -Stocks", the user may request an update of this data for all partners who supply the material. +stock to see which of the selected material are already allocated to him on supplier side. All Stocks related to the +material of the selected line are shown. + +![Stock View after selecting a Material Stock](img/stock_view_selected_material_stock.png) + +Using the button "Update Partner Stocks", the user may request an update of this data for all partners who supply the +material. Note: Stock information is updated asynchronously. The user may reload the page later to see the updated data. ### Product Stocks The table shows the relevant information regarding all product stocks that are at your sites. The user may select one -stock to see which of the selected products have already arrived on customer side but not be used for production. Using -the button "Update Partner Stocks", the user may request an update of this data for all partners who buy the material. +stock to see which of the selected products have already arrived at customer side but not be used for production. All +Stocks related to the material of the selected line are shown. Using the button "Update Partner Stocks", the user may +request an update of this data for all partners who buy the material. Note: Stock information is updated asynchronously. The user may reload the page later to see the updated data. +Note 2: No images have been added, as the Product Stocks mechanics are the same as for material stocks. ## Supplier Dashboard +![Dashboard View after opening](img/dashboard_view.png) + The Supplier Dashboard is a preview. It allows a partner to select a customer, material and location information to -get insights regarding the current status of a customers' supply situation. Using the button "Update Customer Data", the -respective information for the partner get updated. -Note: information is updated asynchronously. The user may reload the page later to see the updated data. +get insights regarding the current status of a customers' supply situation. If address "All Addresses" is selected, then +all information of the different address is summed up. + +![Dashboard View after selection](img/dashboard_view_list.png) +A very easy overview is given by highlighting cells red in which the production is less than the total demand of that +day. Stocks, transit times and deliveries are ignored. + +After selecting a product the "Update Customer Data" button is enabled. When using the button, the respective +information for the partner get updated. +Note: information is updated asynchronously. The user may reload the page later to see the updated data. Currently only +Stock information of the partner is updated. ## Catalog An admin may use the page to query offers available at a partner to check if the partner set up the information exchange for this partner. +![Catalog View after opening](img/catalog_view.png) + +After entering a valid data space protocol (DSP) address of a partner and triggering the "Get Catalog" button, the user +may see a list of available assets. + +![Catalog View after requesting an EDC's catalog](img/catalog_view_list.png) + +Per Catalog Item the following information is listed: + +- Asset ID +- Asset Prop Type defining the asset type (close to CX Taxonomy) +- Permissions (Contracts) +- Prohibitions (Contracts) +- Obligations (Contracts) + +Note: Only catalog items / offers that can be accessed by you are listed. + ## Negotiations An admin may use the page to see all recent negotiations and their state. +![Negotiation View without any recent negotiations](img/negotiations_view.png) + +If no negotiation has been performed in the EDC yet, then this view is empty as in the picture above. + +![Negotiation View with a recent item stock negotiation](img/negotiations_view_list.png) + +Per Negotiation the following information is listed: + +- Negotiation ID +- Type (have I been acting as a Data `PROVIDER` or Data `CONSUMER`?) +- State of the negotiation +- Partner BPNL who either + - initiated the negotiation (Type = `PROVIDER`) or + - who I asked to negotiate with (Type = `CONSUMER`) +- Partner's EDC DSP endpoint +- TimeStamp when the state of the negotiation has been set + +_**Note**: Per data request per partner, there are two Negotiations as one contracts the partner's request asset and the +partner contracts your response asset._ + ## Transfers An admin may use the page to see all recent transfers and their state. + +![Transfer View without any recent transfers](img/transfers_view.png) + +If no transfer has been performed in the EDC yet, then this view is empty as in the picture above. + +![Transfer View with a recent item stock transfer](img/transfers_view_list.png) + +Per Transfer the following information is listed: + +- Transfer ID +- Correlation ID indicating the `Transfer ID` on partner site +- State of the negotiation +- TimeStamp when the state of the negotiation has been set +- Type (have I been acting as a Data `PROVIDER` or Data `CONSUMER`?) +- Asset ID that has been contracted +- Contract ID that has been the basis of the Transfer +- Partner BPNL who either + - initiated the negotiation (Type = `PROVIDER`) or + - who I asked to negotiate with (Type = `CONSUMER`) + +_**Note**: Per data request per partner, there are two Transfers as one contracts the partner's request asset and the +partner contracts your response asset._ diff --git a/docs/userGuide/img/catalog_view.png b/docs/userGuide/img/catalog_view.png new file mode 100644 index 00000000..7d8ca86e Binary files /dev/null and b/docs/userGuide/img/catalog_view.png differ diff --git a/docs/userGuide/img/catalog_view_list.png b/docs/userGuide/img/catalog_view_list.png new file mode 100644 index 00000000..10e5d45b Binary files /dev/null and b/docs/userGuide/img/catalog_view_list.png differ diff --git a/docs/userGuide/img/dashboard_view.png b/docs/userGuide/img/dashboard_view.png new file mode 100644 index 00000000..7df86858 Binary files /dev/null and b/docs/userGuide/img/dashboard_view.png differ diff --git a/docs/userGuide/img/dashboard_view_list.png b/docs/userGuide/img/dashboard_view_list.png new file mode 100644 index 00000000..069894c5 Binary files /dev/null and b/docs/userGuide/img/dashboard_view_list.png differ diff --git a/docs/userGuide/img/negotiations_view.png b/docs/userGuide/img/negotiations_view.png new file mode 100644 index 00000000..1d7a2444 Binary files /dev/null and b/docs/userGuide/img/negotiations_view.png differ diff --git a/docs/userGuide/img/negotiations_view_list.png b/docs/userGuide/img/negotiations_view_list.png new file mode 100644 index 00000000..39863c15 Binary files /dev/null and b/docs/userGuide/img/negotiations_view_list.png differ diff --git a/docs/userGuide/img/stock_view.png b/docs/userGuide/img/stock_view.png new file mode 100644 index 00000000..396362dd Binary files /dev/null and b/docs/userGuide/img/stock_view.png differ diff --git a/docs/userGuide/img/stock_view_added_material_stock.png b/docs/userGuide/img/stock_view_added_material_stock.png new file mode 100644 index 00000000..79c93b90 Binary files /dev/null and b/docs/userGuide/img/stock_view_added_material_stock.png differ diff --git a/docs/userGuide/img/stock_view_selected_material_stock.png b/docs/userGuide/img/stock_view_selected_material_stock.png new file mode 100644 index 00000000..9fec6a69 Binary files /dev/null and b/docs/userGuide/img/stock_view_selected_material_stock.png differ diff --git a/docs/userGuide/img/transfers_view.png b/docs/userGuide/img/transfers_view.png new file mode 100644 index 00000000..00a15b91 Binary files /dev/null and b/docs/userGuide/img/transfers_view.png differ diff --git a/docs/userGuide/img/transfers_view_list.png b/docs/userGuide/img/transfers_view_list.png new file mode 100644 index 00000000..a6edd53a Binary files /dev/null and b/docs/userGuide/img/transfers_view_list.png differ