From 326b15d40408aab3e660ae52fc9f5a48ae60ffdc Mon Sep 17 00:00:00 2001 From: ReneSchroederLJ Date: Wed, 13 Aug 2025 16:49:13 +0200 Subject: [PATCH 1/4] chore: update arc42 documentation --- CHANGELOG.md | 1 + .../architecture/01_introduction_and_goals.md | 7 ++- .../02_architecture_constraints.md | 2 +- .../03_system_scope_and_context.md | 28 ++++++---- docs/architecture/04_solution_strategy.md | 24 ++++---- docs/architecture/05_building_block_view.md | 31 +++++----- docs/architecture/06_runtime_view.md | 9 ++- docs/architecture/07_deployment_view.md | 13 ++--- docs/architecture/08_concepts.md | 56 +++++-------------- docs/architecture/12_glossary.md | 52 ++++++++--------- docs/architecture/Index.md | 1 + docs/architecture/img/05-level-1-backend.svg | 5 +- docs/architecture/img/05-level-1-frontend.svg | 5 +- .../architecture/puml/05-level-1-backend.puml | 11 +--- .../puml/05-level-1-frontend.puml | 56 +++++++++---------- 15 files changed, 128 insertions(+), 173 deletions(-) mode change 100755 => 100644 docs/architecture/img/05-level-1-backend.svg diff --git a/CHANGELOG.md b/CHANGELOG.md index e1026f659..e0a6ea980 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -27,6 +27,7 @@ The **need for configuration updates** is **marked bold**. * Updated open API ([#929](https://github.com/eclipse-tractusx/puris/pull/929)) * Updated dependencies to resolve high and critical security vulnerabilities ([#932](https://github.com/eclipse-tractusx/puris/pull/932)) +* Updated Arc42 documentation ([#936](https://github.com/eclipse-tractusx/puris/pull/936)) ## v3.2.0 diff --git a/docs/architecture/01_introduction_and_goals.md b/docs/architecture/01_introduction_and_goals.md index 2d2777fda..4cc6e30cd 100644 --- a/docs/architecture/01_introduction_and_goals.md +++ b/docs/architecture/01_introduction_and_goals.md @@ -1,14 +1,14 @@ # Introduction and Goals Supply networks are complex. Supply or demand shortages affect multiple partners along the -supply network. In case a shortage occurs, partners need to collect and exchange manually +supply network. In case a shortage occurs, partners need to collect and exchange data manually while discussing the potential actions to take. PURIS FOSS tries to address this manual collection of data. The application tries to facilitate this information exchange by implementing the respective information exchange. PURIS FOSS tries to solve short-term information needs within a given business relationship. -The information are production and supply chain related. The full-fledged vision is a dashboard +The information is production and supply chain related. The full-fledged vision is a dashboard allowing partners to make their situation transparent exchanging production-related demands, planned production quantities and stocks. This information is visualized and exchanged on a day granularity and shall be enhanced by delivery information. @@ -24,6 +24,7 @@ providing data sovereignty. ## Requirements Overview The following requirements shall be fulfilled: + - Exchange material flow related data (demand, production outputs, stocks and delivery information) - Visualize the exchanged information. @@ -32,7 +33,7 @@ The following requirements shall be fulfilled: | Quality Goal | Motivation and Description | |---------------------------|---------------------------------------------------------------------------------------------| | Compatibility to Catena-X | PURIS FOSS follows similar patterns as use cases in resiliency topics and overall Catena-X. | -| Fast usage | PURIS FOSS allows partners to exchange data with as less onboarding effort as needed | +| Fast usage | PURIS FOSS allows partners to exchange data with as little onboarding effort as needed | | Data sovereignty | PURIS FOSS follows Catena-X and GAIA-X requirements for data sovereignty | ## Stakeholders diff --git a/docs/architecture/02_architecture_constraints.md b/docs/architecture/02_architecture_constraints.md index 7cc31074c..5d3b0229e 100644 --- a/docs/architecture/02_architecture_constraints.md +++ b/docs/architecture/02_architecture_constraints.md @@ -10,7 +10,7 @@ PURIS FOSS follows the following constraints: | 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 (SAMM) | Tooling used in Catena-X to semantically describe data. | -| Digital Twins in Catena-X & Industry Core | Standards CX-0002 and CX-0126 describe how Digital Twins following with the Asset Administration Shell shall be used. PURIS standards are built on these foundations. | +| Digital Twins in Catena-X & Industry Core | Standards CX-0002 and CX-0126 describe how Digital Twins following the Asset Administration Shell shall be used. PURIS standards are built on these foundations. | ## NOTICE diff --git a/docs/architecture/03_system_scope_and_context.md b/docs/architecture/03_system_scope_and_context.md index c9b1b3f10..8eeb05539 100644 --- a/docs/architecture/03_system_scope_and_context.md +++ b/docs/architecture/03_system_scope_and_context.md @@ -1,34 +1,37 @@ # System Scope and Context -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. +The application's scope is to enable the creation, update and exchange of demand, production, delivery, stock and days of supply information related to the partners. In addition the application enbles sending, updating, forwarding and resolving of supply chain disruption notifications. This application scope follows the following information. ## Business Context PURIS FOSS may be operated in any supply network, but currently will likely be operated in the automotive supply network. Different functions within a company operate supply chain functions. They can either work on long-term functions (such as demand and capacity management - not handled by this application) or short-term functions -(like supply reliability - supported by this application). +(like supply reliability - supported by this application). ![Business Context](img/03-business-context.svg) -**Disposition** +### 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. -**Production (Process)** +### Production (Process) + Production is the actually value-adding process of a manufacturer. Its 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** +### 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. -**(Automotive) Supply Chain** +### (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. @@ -49,23 +52,23 @@ The Technical Context has been derived from the architecture constraints: ![Technical Context](img/03-technical-context.svg) -**PURIS FOSS** +### PURIS FOSS The PURIS FOSS is a system consuming short-term supply information supporting identification and mitigating shortages. -**SAMM** +### 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. -**Tractus-X Connector** +### 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). -*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 @@ -76,7 +79,8 @@ compliant to the usage policies, since the policies define data processing rules Within Catena-X an odrl policy profile has been defined. The implementation of sovereign data exchange is explained in the [concepts section](./08_concepts.md). -**Digital Twins & Industry Core** +### Digital Twins & Industry Core + The Industry Core defines a layer on top of the combination of IDS and Digital Twin platform capabilities. It defines the Part Type Twin as a "catalog item" representing a material that has not yet been built (serialized) but sourced. The [Digital Twin KIT](https://eclipse-tractusx.github.io/docs-kits/kits/Digital%20Twin%20Kit/Adoption%20View%20Digital%20Twin%20Kit) diff --git a/docs/architecture/04_solution_strategy.md b/docs/architecture/04_solution_strategy.md index 84e196e93..733a3bea2 100644 --- a/docs/architecture/04_solution_strategy.md +++ b/docs/architecture/04_solution_strategy.md @@ -1,24 +1,24 @@ # Solution Strategy -**Organization** +## Organization -PURIS FOSS +### PURIS FOSS -- follows the related standardization candidates or even published standards (see below). +- follows the related published standards (see below). - is developed parallel to the consortial SAFe project. -**Up-to-dateness / real-time** +### Up-to-dateness / real-time - Stock information has always the latest amount. E.g. at 6 a.m. there is a stock of 60 parts of material and at 8 a.m. there is a stock of 80 parts of material. - Demand and Production Output are measured "per day" e.g., today's demand and next thursday's demand. -**Interoperable Data Exchange and Pattern** +### Interoperable Data Exchange and Pattern - Use SAMM aspect models to exchange PURIS data (see domain model). - Use the EDC to participate in Catena-X. - - Data Providers can offer their data or data providing API as a _Data Asset_. - - Data Consumers can consume a Data Provider's _Data Asset_. + - Data Providers can offer their data or data providing API as a _Data Asset_. + - Data Consumers can consume a Data Provider's _Data Asset_. - Data is exchanged using an asynchronous pull and push mechanism. Thus, the application follows the following Catena-X standards (business-wise) to the following degree: @@ -26,13 +26,13 @@ Thus, the application follows the following Catena-X standards (business-wise) t | Standard | Level of implementation | |----------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------| | [CX-0118 Delivery Information Exchange 2.0.0](https://catenax-ev.github.io/docs/next/standards/CX-0118-ActualDeliveryInformationExchange) | Compliant. | -| [CX-0120 Short-Term Material Demand Exchange 2.0.0](https://catenax-ev.github.io/docs/next/standards/CX-0120-ShortTermMaterialDemandExchange) | Compliant. | +| [CX-0120 Short-Term Material Demand Exchange 2.0.0](https://catenax-ev.github.io/docs/next/standards/CX-0120-ShortTermMaterialDemandExchange) | Compliant. | | [CX-0121 Planned Production Output Exchange 1.0.0](https://catenax-ev.github.io/docs/next/standards/CX-0121-PlannedProductionOutputExchange) | Compliant. | -| [CX-0122 Item Stock Exchange 2.0.0](https://catenax-ev.github.io/docs/next/standards/CX-0122-ItemStockExchange) | Compliant. | -| [CX-0145 Days of Supply Exchange 1.0.0](https://catenax-ev.github.io/docs/next/standards/CX-0145-DaysofsupplyExchange) | Missing EDC and Frontend integration. | -| [CX-0146 Supply Chain Disruption Notifications 1.0.0](https://catenax-ev.github.io/docs/next/standards/CX-0146-SupplyChainDisruptionNotifications) | Missing functionality to react and close. | +| [CX-0122 Item Stock Exchange 2.0.0](https://catenax-ev.github.io/docs/next/standards/CX-0122-ItemStockExchange) | Compliant. | +| [CX-0145 Days of Supply Exchange 1.0.0](https://catenax-ev.github.io/docs/next/standards/CX-0145-DaysofsupplyExchange) | Compliant. | +| [CX-0146 Supply Chain Disruption Notifications 1.0.0](https://catenax-ev.github.io/docs/next/standards/CX-0146-SupplyChainDisruptionNotifications) | Compliant. | -**Management of EDC and Digital Twins** +### Management of EDC and Digital Twins PURIS FOSS diff --git a/docs/architecture/05_building_block_view.md b/docs/architecture/05_building_block_view.md index b90ff46f8..04f04f139 100644 --- a/docs/architecture/05_building_block_view.md +++ b/docs/architecture/05_building_block_view.md @@ -5,19 +5,19 @@ been omitted for readability. ![Level 0 - Blackbox View](img/05-level-0.svg) -| Component / system | Descriptions | -|------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Data Provisioning & Transformation | The Data Provisioning & Transformation Building Block handles the upload of data from internal systems into PURIS and provides capabilities for data transformation. **This component is not part of this repository**. | -| PURIS FOSS Backend | This system represents the PURIS FOSS application's logic. It handles the data exchange. | -| PURIS FOSS Frontend | This system represents the PURIS FOSS user interface. It handles the data visualization. | -| EDC | The Eclipse Dataspace Components Connector (EDC) is the component allowing PURIS FOSS to participate in the IDS. It is used to provide and consume data assets following policy information. Any data transfer is routed through the EDC. | -| Keycloak | Keycloak is an identity provider that can manage multiple clients (applications). Catena-X allows the usage of a shared identity provider. Also the DTR can use a keycloak that allows manage access to the PURIS backend and Read access through the EDC | -| Postgresql DB | Database used by Backend to persist data | +| Component / system | Descriptions | +|------------------------------------|------------------------------------------------------------------------------------------| +| Data Provisioning & Transformation | The Data Provisioning & Transformation Building Block handles the upload of data from internal systems into PURIS and provides capabilities for data transformation. **This component is not part of this repository**.| +| PURIS FOSS Backend | This system represents the PURIS FOSS application's logic. It handles the data exchange. | +| PURIS FOSS Frontend | This system represents the PURIS FOSS user interface. It handles the data visualization. | +| EDC | The Eclipse Dataspace Components Connector (EDC) is the component allowing PURIS FOSS to participate in the IDS. It is used to provide and consume data assets following policy information. Any data transfer is routed through the EDC.| +| Keycloak | Keycloak is an identity provider that can manage multiple clients (applications). Catena-X allows the usage of a shared identity provider. Also the DTR can use a keycloak that allows manage access to the PURIS backend and Read access through the EDC | +| Postgresql DB | Database used by Backend to persist | | Digital Twin Registry | Software Service that implements the AAS Discovery and Registry Interfaces. PURIS FOSS registers materials as ShellDescriptors with the respective information as Submodels. These SubmodelDescriptors do have a DSP endpoint linking to the EDC to contract the usage and how to get the submodel. | ## Level 1 White Boxes -**PURIS FOSS Frontend** +### PURIS FOSS Frontend For readability reasons, the building block view shows summarized interfaces. @@ -27,16 +27,16 @@ The Frontend only handles visualization logic. The remaining logic is handled in | Component / system | Descriptions | |------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Stock View | Allows to manually add or update stock information that is allocated to partners. Also latest stock information for partners may be requested (via backend). | -| Dashboard | The dashboard allows to compare material-related demands, production outputs and stocks in a mocked way. Only Stock information is currently implements. | -| Authentication Service | Encapsulates keycloak authentication and session management to be used by the main app. | -| ERP Service | Encapsulates Logic to schedule an erp update for data. | -| Notification View | Allows to send and read notifications. | +| Material List View | Displays a filterable list of all materials in table form | +| Material Details View | The Material Details View allows to create, view and delete own material demands, productions, stocks and deliveries for a given Material. It also shows the Days of Supply for the given material. In addition it allows requesting and displaying corresponding data from partners | +| Notification View | Allows to read, send, update, forward and resolve notifications. | +| Import View | Allows an ADMIN to import demand, production, delivery or stock data using `.xlsx` files. Imported data overwrites existing data | | Catalog View | Allows an ADMIN to lookup a catalog of a registered partner. | | Negotiation View | Allows an ADMIN to check past negotiations. | | Transfer View | Allows an ADMIN to check past transfers. | +| Authentication Service | Encapsulates keycloak authentication and session management to be used by the main app. | -**PURIS FOSS Backend** +### PURIS FOSS Backend For readability reasons, the building block view shows only the stock related information. The strucutre for the other information objects is the same: @@ -56,7 +56,6 @@ The building block view describes only the responsibilities of the components/ p | MAD | Stores the partner and material related information. They may only be added via REST interfaces. | | Stock | Stores and handles stock related data. It provides interfaces to create and read stock data. Also it allows to exchange stock information via the EDC. | | DTR | The DTR component provides the DTR implementations to manage ShellDescriptors. May first need to get a OAuth 2 token for authentication. | -| ERP Adapter | Allows to ask the SAMM Adapter to get stock information from your ERP / internal system. | | Notifications | Allows to send and receive demand and capacity notifications. | ## NOTICE diff --git a/docs/architecture/06_runtime_view.md b/docs/architecture/06_runtime_view.md index 73a4c5121..ec1d3711f 100644 --- a/docs/architecture/06_runtime_view.md +++ b/docs/architecture/06_runtime_view.md @@ -33,14 +33,14 @@ Roughly said the following steps need to be achieved to lookup a Submodel Y for 1. Determine the `SubmodelDescriptor` by Semantic ID of the Submodel Type in question. 2. Determine the endpoint of that `SubmodelDescriptor` of type `DSP` 3. Extract href, assetId (`Submodel Asset`), dspUrl -7. Contract `Submodel Asset` same as `DTR` but with following differences +4. Contract `Submodel Asset` same as `DTR` but with following differences 1. For communication, use the dspUrl extracted from `SubmodelDescriptor` 2. Catalog query filters by `assetId` extracted from `SubmodelDescriptor` 3. Prior to usage the catalog offers are filtered for an offer your application supports: PURIS FOSS only allows policies with Exactly one `FrameworkAgreement` and one `UsagePurpose`. It only accepts the same Policy it offers (see [Admin Guide](../admin/Admin_Guide.md)) -4. Query `Submodel Y` trough `EDC` -5. Terminate Transfer for `Submodel Y` +5. Query `Submodel Y` trough `EDC` +6. Terminate Transfer for `Submodel Y` The workflow with simplified EDC and DTR communication may be seen in the following sequence diagram. Central Services, such as the `Credential Service` and `Secure Token Service` are ommitted as these are handled by the @@ -65,8 +65,7 @@ as soon as a MaterialPartnerRelation is changed. The Digital Twin is always recr ## Scenario: Exchange Notifications -The notification feature allows users to inform partners about demand and capacity disruptions. The terms -`Data Provider` and `Data Consumer` are in this scenario somewhat misleading because: +The notification feature allows users to inform partners about demand and capacity disruptions. The terms `Data Provider` and `Data Consumer` are in this scenario somewhat misleading because: - The Data Consumer is the message sending party - The Data Provider is the message receiving party (providing the endpoint consuming the data) diff --git a/docs/architecture/07_deployment_view.md b/docs/architecture/07_deployment_view.md index 7ea460c06..3f39440a0 100644 --- a/docs/architecture/07_deployment_view.md +++ b/docs/architecture/07_deployment_view.md @@ -10,21 +10,16 @@ graphic. The local deployment includes a mock of the dim service acting as a Central Wallet following IATP flow. Please refer to [Mock IAM documentation](../../local/iam-mock/README.md) for further information. -It uses one `Keycloak` (IDP) for everything except the PURIS Frontend (needs an external keycloak, not included in local -deployment). It has three realms (Customer, Supplier, MIW). +It uses two `Keycloak` (IDP) instances. One Keycloak handles the authentication for the `DTR` and `EDC`. It has three realms (Customer, Supplier, MIW). The other Keycloak instance handles the authentication for the PURIS frontend and backend applications. -_Note: MIW is currently commented out and the mock iam is used instead. With R24.08 hopefully the MIW can be used again. -_ +_Note: MIW is currently commented out and the mock iam is used instead._ It uses one DBMS (`Postgres DB MIW`) for the MIW and one for the rest (`Postgresql DB` for both `DTR`, `EDC`, `PURIS Backend`) with each a separate Database. -**Helm / Kubernetes** +### 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). - -_Note: For Release R24.05 currently not possible._ +Local helm deployments are currently limited to the PURIS application core and don't include the EDC or IDP components. For instructions see [DEVELOPMENT.md](../../DEVELOPMENT.md) ## ArgoCD Deployment (e.g. INT) diff --git a/docs/architecture/08_concepts.md b/docs/architecture/08_concepts.md index 07373b35c..7fe9a4526 100644 --- a/docs/architecture/08_concepts.md +++ b/docs/architecture/08_concepts.md @@ -14,11 +14,11 @@ In the backend materials are commonly handled by the own material number. The pa 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 + - 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 + - own material number = material number supplier + - material number partner = material number customer Furthermore, as of ItemStockSAMM v2.0.0 the supplier CX ID is the sole identifier for a material of a respective partner. @@ -33,8 +33,8 @@ Within PURIS this results in the following steps: - when creating a material (independent of the role) a global asset id (Catena-X ID) is defined on the material, which is used for the supplier twin. - when creating a mpr, the global asset id (Catena-X ID), initially left null - - is usually not set (acting as supplier) - - is set to the supplier's material's catena-X id (acting as customer) + - is usually not set (acting as supplier) + - is set to the supplier's material's catena-X id (acting as customer) ## Data Sovereignty @@ -56,7 +56,7 @@ is created using the following constraints: Example Access Policy creation request used: -```json +```json { "@context": [ "http://www.w3.org/ns/odrl.jsonld", @@ -95,7 +95,7 @@ Example Access Policy creation request used: } ``` -**Digital Twin Registry Configuration** +### Digital Twin Registry Configuration Additionally, when creating the Digital Twins in the Digital Twin Registry, the `ShellDescriptors` are restricted in access using @@ -170,7 +170,7 @@ _Note: see configuration of usage policies in [AdminGuide](../admin/Admin_Guide. ### Consumer Side Validation Following -the [Digital Twin KIT R24.05](https://eclipse-tractusx.github.io/docs-kits/kits/Digital%20Twin%20Kit/Software%20Development%20View/dt-kit-software-development-view#usage-policies) +the [Digital Twin KIT](https://eclipse-tractusx.github.io/docs-kits/kits/Digital%20Twin%20Kit/Software%20Development%20View/dt-kit-software-development-view#usage-policies) an empty contract policy shall be used for the DRR. This application does **NOT** check the contract policy of the Digital Twin Registry, and uses an Access Policy on its own. @@ -187,8 +187,8 @@ The Contract Policy definition can be found above. Following the Digital Twin KIT, assets in the EDC can be cut as follows: 1. one asset per material and submodel -1. one asset per submodel (implicitly emphasized by R24.05 standards) -1. one asset per material (excluded by R24.05 standards) +2. one asset per submodel (implicitly emphasized by standards) +3. one asset per material (excluded by standards) **NOTE: the PURIS FOSS assumes the second and can only optimize and cache the information for the second case.** @@ -206,10 +206,10 @@ When contracting, the following information (`ContractMapping`) is stored per pa When a new transfer is needed, the system checks if a `ContractMapping` for the resource in question exists. - If yes, - - use this information to get the data directly via the EDC by initializing a transfer. - - if anything fails, go the whole way to get the data (contract DTR, contract submodel, save ContractMapping) + - use this information to get the data directly via the EDC by initializing a transfer. + - if anything fails, go the whole way to get the data (contract DTR, contract submodel, save ContractMapping) - if no, - - go the whole way to get the data (contract DTR, contract submodel, save ContractMapping) + - go the whole way to get the data (contract DTR, contract submodel, save ContractMapping) Sidenote: Edc information and hrefs for submodels are always taken from the `ShellDescriptor`. That means that whenever a submodel is requested, the DTR of a partner is queried. @@ -217,34 +217,6 @@ a submodel is requested, the DTR of a partner is queried. 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. -## ERP Integration - -A first version of the erp integration for item stock is in preparation. It allows the application to schedule a -periodic update of the specific information. It uses an asynchronous request & response flow in which the request should -look like the semantic model of interest in which the `materialGlobalAssetId` is ignored. - -Currently, the following SAMM information is allowed: - -| response-type | samm-version | -|---------------|--------------| -| ItemStock | 2.0 | - -The update is always triggered for the following information: - -- partner -- material -- SAMM / response type -- direction (sometimes needed) - -An update is scheduled whenever: - -- a partner requested the data -- the user requested the data in the dashboard - -In case no update has been scheduled, the information is not updated. The update will then be performed periodically -until it has not been updated for a defined time. Please refer to the Admin Guide for more information to configure the -erp adapter. - ## Security Backend APIs are secured by an API Key. The Frontend may be configured to be accessed based on keycloak authentication. diff --git a/docs/architecture/12_glossary.md b/docs/architecture/12_glossary.md index 0c7946632..b9c12e64b 100644 --- a/docs/architecture/12_glossary.md +++ b/docs/architecture/12_glossary.md @@ -2,37 +2,37 @@ ## Business Glossary -| Name | Abrv. | Description | -|-----------------------------------------------|-------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Catena-X | CX | Data ecosystem / data space for the automotive industry. | -| Predictive Unit Real-Time Information Service | PURIS | Use Case in Catena-X that defines information exchange to cover short-term information needs. | -| Business Partner Number | BPN | A BPN is the unique identifier of a partner within Catena-X as defined in [CX-0010](https://catena-x.net/de/standard-library). | -| Supplier | | The supplier / manufacturer of a material. | -| Customer | | The recipient of material ordered from / manufactured by a supplier. | -| Provider | | The party providing the stock data. | -| Consumer | | The party requesting and consuming the stock data provided by the Provider. | -| Stock related information | -| Stock | | Two way direction of material on stock: One can have a stock of material which is ready for delivery to customers. One can have a stock of material which can be used for the own production. | +| Name | Abrv. | Description | +|-----------------------------------------------|-------|---------------------------------------------------------------------------------------------------------------------------------| +| Catena-X | CX | Data ecosystem / data space for the automotive industry. | +| Predictive Unit Real-Time Information Service | PURIS | Use Case in Catena-X that defines information exchange to cover short-term information needs. | +| Business Partner Number | BPN | A BPN is the unique identifier of a partner within Catena-X as defined in [CX-0010](https://catena-x.net/de/standard-library). | +| Supplier | | The supplier / manufacturer of a material. | +| Customer | | The recipient of material ordered from / manufactured by a supplier. | +| Provider | | The party providing the stock data. | +| Consumer | | The party requesting and consuming the stock data provided by the Provider. | +| Stock related information | | | +| Stock | | Two way direction of material on stock: One can have a stock of material which is ready for delivery to customers. One can have a stock of material which can be used for the own production. | | Allocated Stock | | The already manufactured and ready to be shipped material available at a supplier's facility. They are allocated to a specific customer based on the orders made by the latter. Same concept applies to material delivered by a supplier. | -| Stock Location | | The physical location of a stock specified by its type (BPNS or BPNA) and the corresponding BPN number. More information on BPN/S/A is provided in [CX-0010](https://catena-x.net/de/standard-library). | -| Order related information | -| Order | | Request from a customer towards a supplier to manufacture / supply a given quantity of a specific material in a predefined time frame. | -| 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. | +| Stock Location | | The physical location of a stock specified by its type (BPNS or BPNA) and the corresponding BPN number. More information on BPN/S/A is provided in [CX-0010](https://catena-x.net/de/standard-library).| +| Order related information | | | +| Order | | Request from a customer towards a supplier to manufacture / supply a given quantity of a specific material in a predefined time frame.| +| 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. | -| Operational Data / Movement Data | | Data representing the life cycle of relevant information of a given system or data that changes frequently e.g., orders. | -| IDS related terms | -| International Data Space | IDS | International Data Space and its protocol for data exchange foresees an compliant connector handling contract negotiation before each data transfer and defines a general architecture for data exchange. | -| Eclipse Dataspace Connector (Eclipse Dataspace Components Connector) | EDC | The EDC is a reference implementation for an IDS compliant connector currently acting as a de-facto standard and/or reference implementation within Catena-X. The [Tractus-X Connector](https://github.com/eclipse-tractusx/tractusx-edc) is a customized version for Catena-X. | -| Industry 4.0 related terms | -| 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". | +| Name | Abrv. | Description | +|----------------------------------------------------------------------|-------|-------------------------------------------------------------------------------------------------| +| Master Data | MAD | Data which is commonly maintained once and them operationally used e.g., partners with adresses.| +| Operational Data / Movement Data | | Data representing the life cycle of relevant information of a given system or data that changes frequently e.g., orders.| +| IDS related terms | | | +| International Data Space | IDS | International Data Space and its protocol for data exchange foresees an compliant connector handling contract negotiation before each data transfer and defines a general architecture for data | +| Eclipse Dataspace Connector (Eclipse Dataspace Components Connector) | EDC | The EDC is a reference implementation for an IDS compliant connector currently acting as a de-facto standard and/or reference implementation within Catena-X. The [Tractus-X Connector](https://github.com/eclipse-tractusx/tractusx-edc) is a customized version for Catena-X. | +| Industry 4.0 related terms | | | +| 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. | +| 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. | ## NOTICE diff --git a/docs/architecture/Index.md b/docs/architecture/Index.md index 7352fc501..729bea76f 100644 --- a/docs/architecture/Index.md +++ b/docs/architecture/Index.md @@ -1,6 +1,7 @@ # Arc42 ## Table of Content + - [01. Introduction and Goals](01_introduction_and_goals.md) - [02. Architecture Constraints](02_architecture_constraints.md) - [03. System Scope and Context](03_system_scope_and_context.md) diff --git a/docs/architecture/img/05-level-1-backend.svg b/docs/architecture/img/05-level-1-backend.svg old mode 100755 new mode 100644 index be8694c80..10d868a4e --- a/docs/architecture/img/05-level-1-backend.svg +++ b/docs/architecture/img/05-level-1-backend.svg @@ -1,4 +1 @@ - -«system» PURIS FOSS BackendDTRERP AdapterStock, Production, Demand,Delivery, Days of SupplyInformationEDCNotificationsMADMAD InterfaceRegistry & Discovery InterfacesOAuth2ERP SAMMAdapter InterfaceEDC Management APINotification InterfaceFrontend Trigger InterfaceSubmodel& internal interfaceuse for authentication of DTRuse edc for communicationRegister and discover twins& submodelsquery catalog &get data (via edc) +«system» PURIS FOSS BackendDTRStock, Production, Demand,Delivery, Days of SupplyInformationEDCNotificationsMADMAD InterfaceRegistry & Discovery InterfacesOAuth2EDC Management APINotification InterfaceSubmodel & internal interfaceuse edc for communicationRegister and discover twins& submodelsquery catalog &get data (via edc) \ No newline at end of file diff --git a/docs/architecture/img/05-level-1-frontend.svg b/docs/architecture/img/05-level-1-frontend.svg index 4805a65c0..f38036fe4 100644 --- a/docs/architecture/img/05-level-1-frontend.svg +++ b/docs/architecture/img/05-level-1-frontend.svg @@ -1,4 +1 @@ - -«system» PURIS FOSS FrontendERP ServiceStock ViewNotification ViewDashboardAuthentication ServiceCatalog ViewNegotiations ViewTransfer ViewFrontend Trigger InterfaceEDC InterfaceMAD InterfaceNotification InterfaceInterfaces for- Planned Production Output- Short-Term Material Demand- Delivery InformationKeycloakStock Interface +«system» PURIS FOSS FrontendUser ViewsAdmin ViewsAuthentication ServiceMaterial List ViewMaterial Details ViewNotification ViewImport ViewCatalog ViewNegotiations ViewTransfer ViewKeycloakEDC InterfaceMAD InterfacePURIS Information Interface \ No newline at end of file diff --git a/docs/architecture/puml/05-level-1-backend.puml b/docs/architecture/puml/05-level-1-backend.puml index 71adb2558..668c1d2be 100644 --- a/docs/architecture/puml/05-level-1-backend.puml +++ b/docs/architecture/puml/05-level-1-backend.puml @@ -6,39 +6,32 @@ skinparam ranksep 50 () mad_interface as "MAD Interface" () dtr_interface as "Registry & Discovery Interfaces" () oauth as "OAuth2" -() erp_interface as "ERP SAMM\nAdapter Interface" () edc_interface as "EDC Management API" () not_interface as "Notification Interface" -() erp_frontend_interface as "Frontend Trigger Interface" -() data_interface as "Submodel \n& internal interface" +() data_interface as "Submodel & internal interface" package "<> PURIS FOSS Backend"{ [DTR] as dtr - [ERP Adapter] as erp [Stock, Production, Demand,\nDelivery, Days of Supply\nInformation] as stock [EDC] as edc [Notifications] as not [MAD] as mad } -erp -left- erp_interface -erp -left- erp_frontend_interface dtr_interface -down- dtr -oauth )-down- "use for authentication of DTR" dtr +oauth )-down- dtr not -up- "use edc for communication" edc dtr -down- "Register and discover twins\n& submodels" stock data_interface -down- stock -stock -left- erp stock -right- "query catalog &\nget data (via edc)" edc stock -down- mad edc -right-( edc_interface mad -- mad_interface mad -right- not -erp -- mad not -right- not_interface diff --git a/docs/architecture/puml/05-level-1-frontend.puml b/docs/architecture/puml/05-level-1-frontend.puml index 296d06787..95f612c0f 100644 --- a/docs/architecture/puml/05-level-1-frontend.puml +++ b/docs/architecture/puml/05-level-1-frontend.puml @@ -3,49 +3,45 @@ skinparam linetype polyline skinparam nodesep 20 skinparam ranksep 50 -() erp_frontend_interface as "Frontend Trigger Interface" -() edc_interface as "EDC Interface" -() mad_interface as "MAD Interface" -() edc_interface as "EDC Interface" -() notifications_interface as "Notification Interface" - package "<> PURIS FOSS Frontend"{ + [Authentication Service] as auth_service - [ERP Service] as erp_service - together { - [Stock View] as stock_view + package "User Views" as user_views { + [Material List View] as material_list_view + [Material Details View] as material_details_view [Notification View] as notifications_view - [Dashboard] as dashboard - [Authentication Service] as auth_service } - together { + package "Admin Views" as admin_views { + [Import View] as import_view [Catalog View] as catalog_view [Negotiations View] as negotiations_view [Transfer View] as transfer_view } } -"Interfaces for\n- Planned Production Output\n- Short-Term Material Demand\n- Delivery Information" -- dashboard [Keycloak] as idp -idp - auth_service +idp -down- auth_service -stock_view ---( "Stock Interface" -stock_view ---( mad_interface +auth_service -down--> user_views +auth_service -down--> admin_views -dashboard ---( "Stock Interface" -dashboard ---( mad_interface -notifications_view ---( mad_interface -notifications_interface )-- notifications_view -catalog_view ---( edc_interface -catalog_view ---( mad_interface -negotiations_view ---( edc_interface -transfer_view ---( edc_interface - -erp_service - dashboard -erp_frontend_interface -up- erp_service -dashboard -[hidden]right- stock_view - -auth_service -[hidden]down- erp_service +() edc_interface as "EDC Interface" +() mad_interface as "MAD Interface" +() information_interface as "PURIS Information Interface" + +material_list_view <--- information_interface +material_details_view <--- information_interface +notifications_view <--- information_interface +material_list_view <--- mad_interface +material_details_view <--- mad_interface +notifications_view <--- mad_interface +import_view <--- mad_interface +import_view <--- information_interface + +catalog_view <--- edc_interface +catalog_view <--- mad_interface +negotiations_view <--- edc_interface +transfer_view <--- edc_interface @enduml From 9ea0da5c82de8c7731638d1843dae9103f31d75b Mon Sep 17 00:00:00 2001 From: ReneSchroederLJ Date: Mon, 18 Aug 2025 09:00:39 +0200 Subject: [PATCH 2/4] chore: auto format markdown files --- .editorconfig | 3 + CHANGELOG.md | 2 +- README.md | 20 +-- .../architecture/01_introduction_and_goals.md | 4 +- .../02_architecture_constraints.md | 4 +- docs/architecture/04_solution_strategy.md | 16 +-- docs/architecture/05_building_block_view.md | 36 ++--- docs/architecture/06_runtime_view.md | 32 ++--- docs/architecture/08_concepts.md | 132 +++++++++--------- docs/architecture/12_glossary.md | 52 +++---- 10 files changed, 152 insertions(+), 149 deletions(-) diff --git a/.editorconfig b/.editorconfig index 23398286a..8a4ac3339 100644 --- a/.editorconfig +++ b/.editorconfig @@ -28,3 +28,6 @@ insert_final_newline = true [*.yaml] indent_size = 2 + +[*.md] +indent_size = 2 diff --git a/CHANGELOG.md b/CHANGELOG.md index e0a6ea980..205ddcd90 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -27,7 +27,7 @@ The **need for configuration updates** is **marked bold**. * Updated open API ([#929](https://github.com/eclipse-tractusx/puris/pull/929)) * Updated dependencies to resolve high and critical security vulnerabilities ([#932](https://github.com/eclipse-tractusx/puris/pull/932)) -* Updated Arc42 documentation ([#936](https://github.com/eclipse-tractusx/puris/pull/936)) +* Updated Arc42 documentation ([#937](https://github.com/eclipse-tractusx/puris/pull/937)) ## v3.2.0 diff --git a/README.md b/README.md index 95b391ee9..025907d03 100644 --- a/README.md +++ b/README.md @@ -13,22 +13,22 @@ information about prerequirements and getting started guides. Beside the dependencies provided in the Helm Chart, the following dependencies have been tested for R24.05 to run PURIS: | Application | App Version | Chart Version | -|-------------------------------------------------------------------------------------------------------------------|-------------|---------------| -| [Tractus-X Connector](https://github.com/eclipse-tractusx/tractusx-edc/tree/main/charts/tractusx-connector) | 0.10.0 | 0.10.0 | +| ----------------------------------------------------------------------------------------------------------------- | ----------- | ------------- | +| [Tractus-X Connector](https://github.com/eclipse-tractusx/tractusx-edc/tree/main/charts/tractusx-connector) | 0.10.0 | 0.10.0 | | [Digital Twin Registry](https://github.com/eclipse-tractusx/sldt-digital-twin-registry/tree/main/charts/registry) | 0.8.0 | 0.8.0 | ## Overview of Implemented Standards The application follows the following Catena-X standards (business-wise) to the following degree: -| Standard | Level of implementation | -|----------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------| -| [CX-0118 Delivery Information Exchange 2.0.0](https://catenax-ev.github.io/docs/next/standards/CX-0118-ActualDeliveryInformationExchange) | Compliant. | -| [CX-0120 Short-Term Material Demand Exchange 2.0.0](https://catenax-ev.github.io/docs/next/standards/CX-0120-ShortTermMaterialDemandExchange) | Compliant. | -| [CX-0121 Planned Production Output Exchange 1.0.0](https://catenax-ev.github.io/docs/next/standards/CX-0121-PlannedProductionOutputExchange) | Compliant. | -| [CX-0122 Item Stock Exchange 2.0.0](https://catenax-ev.github.io/docs/next/standards/CX-0122-ItemStockExchange) | Compliant. | -| [CX-0145 Days of Supply Exchange 1.0.0](https://catenax-ev.github.io/docs/next/standards/CX-0145-DaysofsupplyExchange) | Compliant. | -| [CX-0146 Supply Chain Disruption Notifications 1.0.0](https://catenax-ev.github.io/docs/next/standards/CX-0146-SupplyChainDisruptionNotifications) | Missing functionality to react and close. | +| Standard | Level of implementation | +| -------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | +| [CX-0118 Delivery Information Exchange 2.0.0](https://catenax-ev.github.io/docs/next/standards/CX-0118-ActualDeliveryInformationExchange) | Compliant. | +| [CX-0120 Short-Term Material Demand Exchange 2.0.0](https://catenax-ev.github.io/docs/next/standards/CX-0120-ShortTermMaterialDemandExchange) | Compliant. | +| [CX-0121 Planned Production Output Exchange 1.0.0](https://catenax-ev.github.io/docs/next/standards/CX-0121-PlannedProductionOutputExchange) | Compliant. | +| [CX-0122 Item Stock Exchange 2.0.0](https://catenax-ev.github.io/docs/next/standards/CX-0122-ItemStockExchange) | Compliant. | +| [CX-0145 Days of Supply Exchange 1.0.0](https://catenax-ev.github.io/docs/next/standards/CX-0145-DaysofsupplyExchange) | Compliant. | +| [CX-0146 Supply Chain Disruption Notifications 1.0.0](https://catenax-ev.github.io/docs/next/standards/CX-0146-SupplyChainDisruptionNotifications) | Compliant. | ## Known Knows diff --git a/docs/architecture/01_introduction_and_goals.md b/docs/architecture/01_introduction_and_goals.md index 4cc6e30cd..836165b94 100644 --- a/docs/architecture/01_introduction_and_goals.md +++ b/docs/architecture/01_introduction_and_goals.md @@ -31,7 +31,7 @@ The following requirements shall be fulfilled: ## Quality Goals | Quality Goal | Motivation and Description | -|---------------------------|---------------------------------------------------------------------------------------------| +| ------------------------- | ------------------------------------------------------------------------------------------- | | Compatibility to Catena-X | PURIS FOSS follows similar patterns as use cases in resiliency topics and overall Catena-X. | | Fast usage | PURIS FOSS allows partners to exchange data with as little onboarding effort as needed | | Data sovereignty | PURIS FOSS follows Catena-X and GAIA-X requirements for data sovereignty | @@ -41,7 +41,7 @@ The following requirements shall be fulfilled: Key stakehoders for puris are: | Stakeholder | Goal or Interest | -|------------------------|---------------------------------------------| +| ---------------------- | ------------------------------------------- | | Catena-X Ecosystem | Integration of the Ecosystem concepts | | Politics and Companies | more resilient supply networks | | SME | less efforts for integration | diff --git a/docs/architecture/02_architecture_constraints.md b/docs/architecture/02_architecture_constraints.md index 5d3b0229e..1a75afcc1 100644 --- a/docs/architecture/02_architecture_constraints.md +++ b/docs/architecture/02_architecture_constraints.md @@ -3,14 +3,14 @@ PURIS FOSS follows the following constraints: | Constraint | Background or motivation | -|--------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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 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 (SAMM) | Tooling used in Catena-X to semantically describe data. | -| Digital Twins in Catena-X & Industry Core | Standards CX-0002 and CX-0126 describe how Digital Twins following the Asset Administration Shell shall be used. PURIS standards are built on these foundations. | +| Digital Twins in Catena-X & Industry Core | Standards CX-0002 and CX-0126 describe how Digital Twins following the Asset Administration Shell shall be used. PURIS standards are built on these foundations. | ## NOTICE diff --git a/docs/architecture/04_solution_strategy.md b/docs/architecture/04_solution_strategy.md index 733a3bea2..bb7eb8010 100644 --- a/docs/architecture/04_solution_strategy.md +++ b/docs/architecture/04_solution_strategy.md @@ -23,14 +23,14 @@ Thus, the application follows the following Catena-X standards (business-wise) to the following degree: -| Standard | Level of implementation | -|----------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------| -| [CX-0118 Delivery Information Exchange 2.0.0](https://catenax-ev.github.io/docs/next/standards/CX-0118-ActualDeliveryInformationExchange) | Compliant. | -| [CX-0120 Short-Term Material Demand Exchange 2.0.0](https://catenax-ev.github.io/docs/next/standards/CX-0120-ShortTermMaterialDemandExchange) | Compliant. | -| [CX-0121 Planned Production Output Exchange 1.0.0](https://catenax-ev.github.io/docs/next/standards/CX-0121-PlannedProductionOutputExchange) | Compliant. | -| [CX-0122 Item Stock Exchange 2.0.0](https://catenax-ev.github.io/docs/next/standards/CX-0122-ItemStockExchange) | Compliant. | -| [CX-0145 Days of Supply Exchange 1.0.0](https://catenax-ev.github.io/docs/next/standards/CX-0145-DaysofsupplyExchange) | Compliant. | -| [CX-0146 Supply Chain Disruption Notifications 1.0.0](https://catenax-ev.github.io/docs/next/standards/CX-0146-SupplyChainDisruptionNotifications) | Compliant. | +| Standard | Level of implementation | +| -------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | +| [CX-0118 Delivery Information Exchange 2.0.0](https://catenax-ev.github.io/docs/next/standards/CX-0118-ActualDeliveryInformationExchange) | Compliant. | +| [CX-0120 Short-Term Material Demand Exchange 2.0.0](https://catenax-ev.github.io/docs/next/standards/CX-0120-ShortTermMaterialDemandExchange) | Compliant. | +| [CX-0121 Planned Production Output Exchange 1.0.0](https://catenax-ev.github.io/docs/next/standards/CX-0121-PlannedProductionOutputExchange) | Compliant. | +| [CX-0122 Item Stock Exchange 2.0.0](https://catenax-ev.github.io/docs/next/standards/CX-0122-ItemStockExchange) | Compliant. | +| [CX-0145 Days of Supply Exchange 1.0.0](https://catenax-ev.github.io/docs/next/standards/CX-0145-DaysofsupplyExchange) | Compliant. | +| [CX-0146 Supply Chain Disruption Notifications 1.0.0](https://catenax-ev.github.io/docs/next/standards/CX-0146-SupplyChainDisruptionNotifications) | Compliant. | ### Management of EDC and Digital Twins diff --git a/docs/architecture/05_building_block_view.md b/docs/architecture/05_building_block_view.md index 04f04f139..7def875b5 100644 --- a/docs/architecture/05_building_block_view.md +++ b/docs/architecture/05_building_block_view.md @@ -5,14 +5,14 @@ been omitted for readability. ![Level 0 - Blackbox View](img/05-level-0.svg) -| Component / system | Descriptions | -|------------------------------------|------------------------------------------------------------------------------------------| -| Data Provisioning & Transformation | The Data Provisioning & Transformation Building Block handles the upload of data from internal systems into PURIS and provides capabilities for data transformation. **This component is not part of this repository**.| -| PURIS FOSS Backend | This system represents the PURIS FOSS application's logic. It handles the data exchange. | -| PURIS FOSS Frontend | This system represents the PURIS FOSS user interface. It handles the data visualization. | -| EDC | The Eclipse Dataspace Components Connector (EDC) is the component allowing PURIS FOSS to participate in the IDS. It is used to provide and consume data assets following policy information. Any data transfer is routed through the EDC.| -| Keycloak | Keycloak is an identity provider that can manage multiple clients (applications). Catena-X allows the usage of a shared identity provider. Also the DTR can use a keycloak that allows manage access to the PURIS backend and Read access through the EDC | -| Postgresql DB | Database used by Backend to persist | +| Component / system | Descriptions | +| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Data Provisioning & Transformation | The Data Provisioning & Transformation Building Block handles the upload of data from internal systems into PURIS and provides capabilities for data transformation. **This component is not part of this repository**. | +| PURIS FOSS Backend | This system represents the PURIS FOSS application's logic. It handles the data exchange. | +| PURIS FOSS Frontend | This system represents the PURIS FOSS user interface. It handles the data visualization. | +| EDC | The Eclipse Dataspace Components Connector (EDC) is the component allowing PURIS FOSS to participate in the IDS. It is used to provide and consume data assets following policy information. Any data transfer is routed through the EDC. | +| Keycloak | Keycloak is an identity provider that can manage multiple clients (applications). Catena-X allows the usage of a shared identity provider. Also the DTR can use a keycloak that allows manage access to the PURIS backend and Read access through the EDC | +| Postgresql DB | Database used by Backend to persist | | Digital Twin Registry | Software Service that implements the AAS Discovery and Registry Interfaces. PURIS FOSS registers materials as ShellDescriptors with the respective information as Submodels. These SubmodelDescriptors do have a DSP endpoint linking to the EDC to contract the usage and how to get the submodel. | ## Level 1 White Boxes @@ -25,16 +25,16 @@ For readability reasons, the building block view shows summarized interfaces. The Frontend only handles visualization logic. The remaining logic is handled in the backend. -| Component / system | Descriptions | -|------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Material List View | Displays a filterable list of all materials in table form | +| Component / system | Descriptions | +| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Material List View | Displays a filterable list of all materials in table form | | Material Details View | The Material Details View allows to create, view and delete own material demands, productions, stocks and deliveries for a given Material. It also shows the Days of Supply for the given material. In addition it allows requesting and displaying corresponding data from partners | -| Notification View | Allows to read, send, update, forward and resolve notifications. | -| Import View | Allows an ADMIN to import demand, production, delivery or stock data using `.xlsx` files. Imported data overwrites existing data | -| Catalog View | Allows an ADMIN to lookup a catalog of a registered partner. | -| Negotiation View | Allows an ADMIN to check past negotiations. | -| Transfer View | Allows an ADMIN to check past transfers. | -| Authentication Service | Encapsulates keycloak authentication and session management to be used by the main app. | +| Notification View | Allows to read, send, update, forward and resolve notifications. | +| Import View | Allows an ADMIN to import demand, production, delivery or stock data using `.xlsx` files. Imported data overwrites existing data | +| Catalog View | Allows an ADMIN to lookup a catalog of a registered partner. | +| Negotiation View | Allows an ADMIN to check past negotiations. | +| Transfer View | Allows an ADMIN to check past transfers. | +| Authentication Service | Encapsulates keycloak authentication and session management to be used by the main app. | ### PURIS FOSS Backend @@ -51,7 +51,7 @@ The building block view describes only the responsibilities of the components/ p ![Level 1 - Whitebox View - PURIS FOSS Backend](img/05-level-1-backend.svg) | Component / system | Descriptions | -|--------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | EDC | The EDC component provides the EDC implementations to create assets, negotiate contracts and intialize transfers. query partners' DTR and consume Submodel data. | | MAD | Stores the partner and material related information. They may only be added via REST interfaces. | | Stock | Stores and handles stock related data. It provides interfaces to create and read stock data. Also it allows to exchange stock information via the EDC. | diff --git a/docs/architecture/06_runtime_view.md b/docs/architecture/06_runtime_view.md index ec1d3711f..bf265ea42 100644 --- a/docs/architecture/06_runtime_view.md +++ b/docs/architecture/06_runtime_view.md @@ -20,25 +20,25 @@ Following the PURIS standards, currently one asset per Submodel Type is wanted. Roughly said the following steps need to be achieved to lookup a Submodel Y for a Material X of a Partner Z: 1. Contract `Digital Twin Registry (DTR)` of Partner Z at `EDC` - 1. Query Catalog of `EDC` of Partner Z (filter by `dcat:type` and `cx-common:version`) - 2. Contract usage of `DTR` of Partner Z (no consumer-side check of policy) - 3. Initialize Transfer to query `DTR` - 4. Get Endpoint Data Reference (EDR, auth token for Data Plane request for `DTR` of Partner Z) + 1. Query Catalog of `EDC` of Partner Z (filter by `dcat:type` and `cx-common:version`) + 2. Contract usage of `DTR` of Partner Z (no consumer-side check of policy) + 3. Initialize Transfer to query `DTR` + 4. Get Endpoint Data Reference (EDR, auth token for Data Plane request for `DTR` of Partner Z) 2. Determine Twin of Partner Z for Material X via proxy call through `EDC`: - 1. Lookup Material Twin by specificAssetIds (`manufacturerId`, `manufacturerPartId`, `digialTwinType`) which returns - ShellDescriptor ID - 2. Get ShellDescriptor by ID (base 64 encoded ID) - 3. Terminate Transfer for `DTR` + 1. Lookup Material Twin by specificAssetIds (`manufacturerId`, `manufacturerPartId`, `digialTwinType`) which returns + ShellDescriptor ID + 2. Get ShellDescriptor by ID (base 64 encoded ID) + 3. Terminate Transfer for `DTR` 3. From result, extract needed information to get `Submodel Y` - 1. Determine the `SubmodelDescriptor` by Semantic ID of the Submodel Type in question. - 2. Determine the endpoint of that `SubmodelDescriptor` of type `DSP` - 3. Extract href, assetId (`Submodel Asset`), dspUrl + 1. Determine the `SubmodelDescriptor` by Semantic ID of the Submodel Type in question. + 2. Determine the endpoint of that `SubmodelDescriptor` of type `DSP` + 3. Extract href, assetId (`Submodel Asset`), dspUrl 4. Contract `Submodel Asset` same as `DTR` but with following differences - 1. For communication, use the dspUrl extracted from `SubmodelDescriptor` - 2. Catalog query filters by `assetId` extracted from `SubmodelDescriptor` - 3. Prior to usage the catalog offers are filtered for an offer your application supports: - PURIS FOSS only allows policies with Exactly one `FrameworkAgreement` and one `UsagePurpose`. It only accepts the - same Policy it offers (see [Admin Guide](../admin/Admin_Guide.md)) + 1. For communication, use the dspUrl extracted from `SubmodelDescriptor` + 2. Catalog query filters by `assetId` extracted from `SubmodelDescriptor` + 3. Prior to usage the catalog offers are filtered for an offer your application supports: + PURIS FOSS only allows policies with Exactly one `FrameworkAgreement` and one `UsagePurpose`. It only accepts the + same Policy it offers (see [Admin Guide](../admin/Admin_Guide.md)) 5. Query `Submodel Y` trough `EDC` 6. Terminate Transfer for `Submodel Y` diff --git a/docs/architecture/08_concepts.md b/docs/architecture/08_concepts.md index 7fe9a4526..3d2aa29db 100644 --- a/docs/architecture/08_concepts.md +++ b/docs/architecture/08_concepts.md @@ -58,40 +58,40 @@ Example Access Policy creation request used: ```json { - "@context": [ - "http://www.w3.org/ns/odrl.jsonld", - { - "edc": "https://w3id.org/edc/v0.0.1/ns/", - "cx-policy": "https://w3id.org/catenax/policy/" - } - ], - "@type": "PolicyDefinitionRequestDto", - "@id": "BPNL1234567890ZZ_policy", - "edc:policy": { - "@type": "Set", - "permission": [ + "@context": [ + "http://www.w3.org/ns/odrl.jsonld", + { + "edc": "https://w3id.org/edc/v0.0.1/ns/", + "cx-policy": "https://w3id.org/catenax/policy/" + } + ], + "@type": "PolicyDefinitionRequestDto", + "@id": "BPNL1234567890ZZ_policy", + "edc:policy": { + "@type": "Set", + "permission": [ + { + "action": "use", + "constraint": { + "@type": "LogicalConstraint", + "and": [ + { + "@type": "LogicalConstraint", + "leftOperand": "BusinessPartnerNumber", + "operator": "eq", + "rightOperand": "BPNL1234567890ZZ" + }, { - "action": "use", - "constraint": { - "@type": "LogicalConstraint", - "and": [ - { - "@type": "LogicalConstraint", - "leftOperand": "BusinessPartnerNumber", - "operator": "eq", - "rightOperand": "BPNL1234567890ZZ" - }, - { - "@type": "LogicalConstraint", - "leftOperand": "Membership", - "operator": "eq", - "rightOperand": "active" - } - ] - } + "@type": "LogicalConstraint", + "leftOperand": "Membership", + "operator": "eq", + "rightOperand": "active" } - ] - } + ] + } + } + ] + } } ``` @@ -119,7 +119,7 @@ The Constraints used for the Submodel Contract Policies are the following: Example for Submodels based on following configurations: | Property (helm) | Value | -|---------------------------------------------|---------------| +| ------------------------------------------- | ------------- | | backend.puris.frameworkagreement.credential | Puris | | backend.puris.frameworkagreement.version | 1.0 | | backend.puris.purpose.name | cx.puris.base | @@ -127,41 +127,41 @@ Example for Submodels based on following configurations: ```json { - "@context": [ - "http://www.w3.org/ns/odrl.jsonld", - { - "edc": "https://w3id.org/edc/v0.0.1/ns/", - "cx-policy": "https://w3id.org/catenax/policy/" - } - ], - "@type": "PolicyDefinitionRequestDto", - "@id": "Contract_Policy", - "edc:policy": { - "@type": "Set", - "profile": "cx-policy:profile2405", - "permission": [ + "@context": [ + "http://www.w3.org/ns/odrl.jsonld", + { + "edc": "https://w3id.org/edc/v0.0.1/ns/", + "cx-policy": "https://w3id.org/catenax/policy/" + } + ], + "@type": "PolicyDefinitionRequestDto", + "@id": "Contract_Policy", + "edc:policy": { + "@type": "Set", + "profile": "cx-policy:profile2405", + "permission": [ + { + "action": "use", + "constraint": { + "@type": "LogicalConstraint", + "and": [ + { + "@type": "LogicalConstraint", + "leftOperand": "https://w3id.org/catenax/policy/FrameworkAgreement", + "operator": "eq", + "rightOperand": "Puris:1.0" + }, { - "action": "use", - "constraint": { - "@type": "LogicalConstraint", - "and": [ - { - "@type": "LogicalConstraint", - "leftOperand": "https://w3id.org/catenax/policy/FrameworkAgreement", - "operator": "eq", - "rightOperand": "Puris:1.0" - }, - { - "@type": "LogicalConstraint", - "leftOperand": "https://w3id.org/catenax/policy/UsagePurpose", - "operator": "eq", - "rightOperand": "cx.puris.base:1" - } - ] - } + "@type": "LogicalConstraint", + "leftOperand": "https://w3id.org/catenax/policy/UsagePurpose", + "operator": "eq", + "rightOperand": "cx.puris.base:1" } - ] - } + ] + } + } + ] + } } ``` diff --git a/docs/architecture/12_glossary.md b/docs/architecture/12_glossary.md index b9c12e64b..dc88b4ccc 100644 --- a/docs/architecture/12_glossary.md +++ b/docs/architecture/12_glossary.md @@ -2,37 +2,37 @@ ## Business Glossary -| Name | Abrv. | Description | -|-----------------------------------------------|-------|---------------------------------------------------------------------------------------------------------------------------------| -| Catena-X | CX | Data ecosystem / data space for the automotive industry. | -| Predictive Unit Real-Time Information Service | PURIS | Use Case in Catena-X that defines information exchange to cover short-term information needs. | -| Business Partner Number | BPN | A BPN is the unique identifier of a partner within Catena-X as defined in [CX-0010](https://catena-x.net/de/standard-library). | -| Supplier | | The supplier / manufacturer of a material. | -| Customer | | The recipient of material ordered from / manufactured by a supplier. | -| Provider | | The party providing the stock data. | -| Consumer | | The party requesting and consuming the stock data provided by the Provider. | -| Stock related information | | | -| Stock | | Two way direction of material on stock: One can have a stock of material which is ready for delivery to customers. One can have a stock of material which can be used for the own production. | +| Name | Abrv. | Description | +| --------------------------------------------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Catena-X | CX | Data ecosystem / data space for the automotive industry. | +| Predictive Unit Real-Time Information Service | PURIS | Use Case in Catena-X that defines information exchange to cover short-term information needs. | +| Business Partner Number | BPN | A BPN is the unique identifier of a partner within Catena-X as defined in [CX-0010](https://catena-x.net/de/standard-library). | +| Supplier | | The supplier / manufacturer of a material. | +| Customer | | The recipient of material ordered from / manufactured by a supplier. | +| Provider | | The party providing the stock data. | +| Consumer | | The party requesting and consuming the stock data provided by the Provider. | +| Stock related information | | | +| Stock | | Two way direction of material on stock: One can have a stock of material which is ready for delivery to customers. One can have a stock of material which can be used for the own production. | | Allocated Stock | | The already manufactured and ready to be shipped material available at a supplier's facility. They are allocated to a specific customer based on the orders made by the latter. Same concept applies to material delivered by a supplier. | -| Stock Location | | The physical location of a stock specified by its type (BPNS or BPNA) and the corresponding BPN number. More information on BPN/S/A is provided in [CX-0010](https://catena-x.net/de/standard-library).| -| Order related information | | | -| Order | | Request from a customer towards a supplier to manufacture / supply a given quantity of a specific material in a predefined time frame.| -| 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.| +| Stock Location | | The physical location of a stock specified by its type (BPNS or BPNA) and the corresponding BPN number. More information on BPN/S/A is provided in [CX-0010](https://catena-x.net/de/standard-library). | +| Order related information | | | +| Order | | Request from a customer towards a supplier to manufacture / supply a given quantity of a specific material in a predefined time frame. | +| 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.| -| Operational Data / Movement Data | | Data representing the life cycle of relevant information of a given system or data that changes frequently e.g., orders.| -| IDS related terms | | | -| International Data Space | IDS | International Data Space and its protocol for data exchange foresees an compliant connector handling contract negotiation before each data transfer and defines a general architecture for data | -| Eclipse Dataspace Connector (Eclipse Dataspace Components Connector) | EDC | The EDC is a reference implementation for an IDS compliant connector currently acting as a de-facto standard and/or reference implementation within Catena-X. The [Tractus-X Connector](https://github.com/eclipse-tractusx/tractusx-edc) is a customized version for Catena-X. | -| Industry 4.0 related terms | | | -| 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".| +| Name | Abrv. | Description | +| -------------------------------------------------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Master Data | MAD | Data which is commonly maintained once and them operationally used e.g., partners with adresses. | +| Operational Data / Movement Data | | Data representing the life cycle of relevant information of a given system or data that changes frequently e.g., orders. | +| IDS related terms | | | +| International Data Space | IDS | International Data Space and its protocol for data exchange foresees an compliant connector handling contract negotiation before each data transfer and defines a general architecture for data | +| Eclipse Dataspace Connector (Eclipse Dataspace Components Connector) | EDC | The EDC is a reference implementation for an IDS compliant connector currently acting as a de-facto standard and/or reference implementation within Catena-X. The [Tractus-X Connector](https://github.com/eclipse-tractusx/tractusx-edc) is a customized version for Catena-X. | +| Industry 4.0 related terms | | | +| 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. | +| 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. | ## NOTICE From 7fb6da0cdc02907e5000e33d201768df2a13fde6 Mon Sep 17 00:00:00 2001 From: ReneSchroederLJ Date: Mon, 18 Aug 2025 10:28:20 +0200 Subject: [PATCH 3/4] fix: update scdn version in documentation --- docs/architecture/04_solution_strategy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/architecture/04_solution_strategy.md b/docs/architecture/04_solution_strategy.md index bb7eb8010..0849c0d61 100644 --- a/docs/architecture/04_solution_strategy.md +++ b/docs/architecture/04_solution_strategy.md @@ -30,7 +30,7 @@ Thus, the application follows the following Catena-X standards (business-wise) t | [CX-0121 Planned Production Output Exchange 1.0.0](https://catenax-ev.github.io/docs/next/standards/CX-0121-PlannedProductionOutputExchange) | Compliant. | | [CX-0122 Item Stock Exchange 2.0.0](https://catenax-ev.github.io/docs/next/standards/CX-0122-ItemStockExchange) | Compliant. | | [CX-0145 Days of Supply Exchange 1.0.0](https://catenax-ev.github.io/docs/next/standards/CX-0145-DaysofsupplyExchange) | Compliant. | -| [CX-0146 Supply Chain Disruption Notifications 1.0.0](https://catenax-ev.github.io/docs/next/standards/CX-0146-SupplyChainDisruptionNotifications) | Compliant. | +| [CX-0146 Supply Chain Disruption Notifications 2.0.0](https://catenax-ev.github.io/docs/next/standards/CX-0146-SupplyChainDisruptionNotifications) | Compliant. | ### Management of EDC and Digital Twins From 36c07710b8827147f445d697599b7deefc3ed96a Mon Sep 17 00:00:00 2001 From: ReneSchroederLJ Date: Mon, 18 Aug 2025 10:41:52 +0200 Subject: [PATCH 4/4] fix: scdn version number in readme --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 025907d03..8d667eee2 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,7 @@ The application follows the following Catena-X standards (business-wise) to the | [CX-0121 Planned Production Output Exchange 1.0.0](https://catenax-ev.github.io/docs/next/standards/CX-0121-PlannedProductionOutputExchange) | Compliant. | | [CX-0122 Item Stock Exchange 2.0.0](https://catenax-ev.github.io/docs/next/standards/CX-0122-ItemStockExchange) | Compliant. | | [CX-0145 Days of Supply Exchange 1.0.0](https://catenax-ev.github.io/docs/next/standards/CX-0145-DaysofsupplyExchange) | Compliant. | -| [CX-0146 Supply Chain Disruption Notifications 1.0.0](https://catenax-ev.github.io/docs/next/standards/CX-0146-SupplyChainDisruptionNotifications) | Compliant. | +| [CX-0146 Supply Chain Disruption Notifications 2.0.0](https://catenax-ev.github.io/docs/next/standards/CX-0146-SupplyChainDisruptionNotifications) | Compliant. | ## Known Knows