diff --git a/docs/src/docs/arc42/runtime-view/data-sovereignty/policy-management.adoc b/docs/src/docs/arc42/runtime-view/data-sovereignty/policy-management.adoc index 29ed99555e..56c43e4553 100644 --- a/docs/src/docs/arc42/runtime-view/data-sovereignty/policy-management.adoc +++ b/docs/src/docs/arc42/runtime-view/data-sovereignty/policy-management.adoc @@ -31,80 +31,62 @@ include::../../../../uml-diagrams/arc42/runtime-view/data-sovereignty/data-sover [cols="1,5"] |=== -|1 -|Policies can be created by User with role 'Admin' at any time in the administration section of Trace-X. The policy is created to later used for publishing assets in the current company context. - -|2 -|Policies are stored in the PolicyStore which is a shared component used by Trace-X [A] and Item Relationship Service (IRS) for storing usage and access policies. - -|3 -|The policy is created in the policy store. - -|4 -|User with role 'Admin' receives feedback that the creation of policy was successful. +|1,2,3,4 +|Policies can be created by user with role 'Admin' at any time in the administration section of Trace-X. The policy is created to later used for publishing parts in the current company context. Policies are stored in the PolicyStore which is a shared component used by Trace-X [A] and Item Relationship Service (IRS) for storing usage and access policies. -|5, 6 +|5,6 |User with role 'Admin' imports assets in the administration section of Trace-X [A]. Parts can be imported at any time in the parts section of Trace-X. They will be stored locally at first. https://github.com/eclipse-tractusx/traceability-foss/tree/main/tx-backend/testdata[Testdata for asset import] -|7 -|User with role 'Admin' selects assets in transient state in application. - -|8 -|User with role 'Admin' is requested to define a policy for assets publishing. - -|9 -|User with role 'Admin' selects policy under which assets are published. The user must choose the policy that is used for the contract negotiation of the selected parts. +|7,8,9 +|User with role 'Admin' selects parts in transient state in application and publishes them. The user must choose the policy that is used for the contract negotiation of the selected parts. -|10, 11 -|Assets are created in the EDC. (POST /v3/assets) +|10,11 +|The parts are created in the EDC. (POST /v3/assets) |12,13 -|Trace-X [A] BE checks if a PolicyDefinition for the selected policy already exists. +|In case the PolicyDefinition does not exist yet, a new PolicyDefinition is created in the EDC [A]. |14,15 -|In case PolicyDefinition does not exist, a new PolicyDefinition is created in the EDC [A]. +|A contractDefinition is created using the provided policyDefinition. |16,17 -|The created part is linked in the PolicyDefinition from the EDC. This is the last step of data provisioning. Trace-X [A] has done everything to ensure that companies that have a matching policy can access its published parts. - -|18,19 -|Each part is created as a shell in the Digital Twin Registry (DTR). This holds all the data of the part. Before connected BPNs can access the imported parts, the parts must be published to the EDC and to the DTR. +|Each part is created as a Asset Administration Shell Descriptor in the Digital Twin Registry (DTR). This holds all the data of the part including the globalAssetId. -|20,21 -|User with role 'Admin' in Trace-X [B] creates policy for consuming assets of Trace-X [A]. +|18,19,20,21 +|Policies can be created by user with role 'Admin' at any time in the administration section of Trace-X. When synchronizing parts, the respective policies for connected BPNLs will be used. |22 |Trace-X [B] wants to synchronize parts and retrieve available ones from connected BPNs. In this case Trace-X [A] and Trace-X [B] have an established connection. |23,24 -|Trace-X [B] requests for globalAssetIds (unique identifier of digital twins (Asset Administration Shell)) in the DTR. +|Trace-X [B] requests all Asset Administration Shell Descriptors in the DTR of Trace-X [A]. |25 -|For part synchronization a job is started in the IRS. +|The globalAssetIds are extracted from the Shell Descriptors. -|26,27 -|IRS requests the CatalogOffer for globalAssetsIds passed by Trace-X [A]. +|26 +|For part synchronization a job is started in the IRS using the globalAssetIds from the previous step. -|28 -|IRS extracts the policies from the CatalogOffer. +|27,28 +|IRS requests the catalogOffer for all globalAssetsIds. |29,30 |IRS requests policies defined for the BPNL of Trace-X [A] in the PolicyStore of Trace-X [B]. |31 -|Now that the IRS has all the relevant policies of both companies, it can start comparing the linked policy of each part to the policy list of Trace-X [B]. This works by comparing the included constraints logically. If no policy matches for a part, it will not be imported. +|Now that the IRS has all the relevant policies of both companies, it can start comparing the linked policy in the catalogOffer of each part to the policy list of Trace-X [B]. This works by comparing the included constraints logically. -|32,33,34 -|If the policy of the part matches with any policy of Trace-X [A], a contract agreement is created for both Trace-X [A] and Trace-X [B]. It can be viewed in the administration section of Trace-X and documents the data exchange. Since the contractAgreementId will be mapped to a submodel of IRS, the contracts can be seen after IRS responded to Trace-X' initial sync call with the submodels including the contractAgreementId. +|32,33,34,35 +|If the policy of the part matches with any policy of Trace-X [A], a contract agreement is created for both Trace-X [A] and Trace-X [B]. It can be viewed in the administration section of Trace-X and documents the data exchange. -|35 -|Now that the contract negotiation was successful, the data consumption process can take place for that part. +|ref import part data +|Now that the contract negotiation was successful, the part data can be imported. This process is documented in the data consumption section. -|36 -|In case the policy does not match, IRS creates a tombstone. +|36,37 +|In case the policy does not match, IRS creates a tombstone and sends a job response to Trace-X [B]. -|37 -|IRS responds to the Trace-X [B] instance after completing job processing. The contractAgreementId for the asset is available in Trace-X from the IRS JobResponse. +|38 +|IRS responds to the Trace-X [B] instance after completing job processing. The contractAgreementId for the asset is available in the job response. |=== It's possible to publish parts with different policies. For this, the user must only publish a limited selection of parts for which he can select a policy. For parts that must be published with different policies, the user can repeat the process. diff --git a/docs/src/uml-diagrams/arc42/runtime-view/data-sovereignty/data-sovereignty-publishing-assets.puml b/docs/src/uml-diagrams/arc42/runtime-view/data-sovereignty/data-sovereignty-publishing-assets.puml index 981eedf0e6..f11e644c8e 100644 --- a/docs/src/uml-diagrams/arc42/runtime-view/data-sovereignty/data-sovereignty-publishing-assets.puml +++ b/docs/src/uml-diagrams/arc42/runtime-view/data-sovereignty/data-sovereignty-publishing-assets.puml @@ -6,7 +6,7 @@ skinparam shadowing false skinparam defaultFontName "Architects daughter" skinparam linetype ortho -title Policies: Send and receive assets +title Policies: Send and receive parts actor "Admin \n [A]" as AA actor User @@ -14,154 +14,110 @@ participant "Trace-X \n [A]" as TXA participant "PolicyStore \n [A]" as PSA participant "Digital Twin Registry \n [A]" as DTRA participant "EDC \n [A]" as EDCA -participant "SubmodelServer \n [A]" as SSA -participant "Digital Twin Registry \n [B]" as DTRB participant "EDC \n [B]" as EDCB participant "IRS \n [B]" as IRSB participant "PolicyStore \n [B]" as PSB participant "Trace-X \n [B]" as TXB -actor "Admin B" as AB AA -> TXA: create policy -note left - create policy used for publishing - company assets [POLICY_TRACEX-PUBLISH_ASSETS] -end note activate TXA -TXA -> PSA: create policy for BPNL +TXA -> PSA: create policy activate PSA TXA <-- PSA: 201 policy created deactivate PSA AA <-- TXA: policy created deactivate TXA - - -... -User -> TXA: import assets (POST /assets/import) -activate TXA -User <-- TXA: ok ... -User -> TXA: publish selected assets in transient state +User -> TXA: import parts (POST /assets/import) +activate TXA +User <-- TXA: 200 success +deactivate TXA -note left - POST /assets/publish -end note +... +User -> TXA: publish selected parts in transient state (POST /assets/publish) +activate TXA User <-- TXA: request for policy - User --> TXA: select policy to be used -loop selected assets - -TXA -> EDCA: create asset (POST /v3/assets) -note left - create assets and CatalogOffer in EDC -end note -TXA <-- EDCA: 200 Asset was created successfully. - -TXA -> EDCA: PolicyDefinition exists -activate EDCA -TXA <-- EDCA: return PolicyDefinition exists -opt PolicyDefinition not exists -TXA -> EDCA: create PolicyDefinition (/management/v2/policydefinitions) -TXA <-- EDCA: PolicyDefinition created -else - -end opt - -TXA -> EDCA: create ContractDefinition (/management/v2/contractdefinitions) with policy -note left - create ContractDefinition in EDC -end note -TXA <-- EDCA: ContractDefinition created - -TXA -> DTRA: create asset /shell-descriptors -activate DTRA -note left - create asset in DTR -end note -TXA <-- DTRA: 201 : Asset Administration Shell Descriptor created successfully -deactivate DTRA - -TXA -> SSA: create submodels for twin -activate SSA -note left - create submodels in SubmodelServer -end note -TXA <-- SSA: submodels created -deactivate SSA - -deactivate EDCA +loop selected parts + TXA -> EDCA: create part (POST /v3/assets) + activate EDCA + TXA <-- EDCA: 200 part created + deactivate EDCA + + opt policyDefintion does not exist + TXA -> EDCA: create policyDefintion (/management/v2/policyDefintions) + activate EDCA + TXA <-- EDCA: policyDefintion created + deactivate EDCA + end opt + + TXA -> EDCA: create contractDefinition with policy (/management/v2/contractDefinitions) + activate EDCA + TXA <-- EDCA: contractDefinition created + deactivate EDCA + + TXA -> DTRA: create Asset Administration Shell Descriptor + activate DTRA + TXA <-- DTRA: 201 Asset Administration Shell Descriptor created + deactivate DTRA + + deactivate TXA end +... -deactivate TXA - -AB -> TXB: create policy +AB -> TXB: create policy for BPNL of Trace-X [A] activate TXB - - -note right - create policy for - BPNL of Trace-X [A] - [POLICY_BPNL_TRACEX_A] -end note +TXB -> PSB: create policy +activate PSB +TXB <-- PSB: 201 policy created +deactivate PSB AB <-- TXB: policy created deactivate TXB +... -ref over TXB - Trace-X [B] publish own assets +TXB -> TXB: synchronize parts +activate TXB -end ref +TXB -> DTRA: get Asset Administration Shell Descriptors +activate DTRA +TXB <-- DTRA: Asset Administration Shell Descriptors +deactivate DTRA -note right - Prerequisite is that Trace-X has published own assets. - dDTR of Trace-X B is requested for globalAssetIds of company own assets. -end note +TXB -> TXB: Extract globalAssetIds -... -TXB -> TXB: synchronize assets (assets/as-$/sync) -note left - different endpoints for sync as-built and as-planned assets -end note -activate TXB -TXB -> DTRB: GET Asset Administration Shell Descriptors -activate DTRB -TXB <-- DTRB: 200 Requested Asset Administration Shell Descriptors -deactivate DTRB - -TXB -> IRSB: Register job (GET /irs/jobs) - initiate Sync of assets +TXB -> IRSB: Register sync job for all globalAssetIds activate IRSB IRSB -> EDCA: GET /v2/catalog/request of Trace-X A note left (/v2/catalog/request/querySpec/filterExpression[id:digitalTwinRegistry]) end note activate EDCA -EDCA --> IRSB: return CatalogOffer +EDCA --> IRSB: return catalogOffer deactivate EDCA -IRSB -> IRSB: extract policy definitions from CatalogOffer -IRSB -> PSB: get policies for BPNL - +IRSB -> PSB: get policy for BPNL activate PSB IRSB <-- PSB: policy for BPNL deactivate PSB loop each part -IRSB -> IRSB: compare ContractOffer policy with Company policy for BPNL -alt policies match - IRSB -> EDCB: start contract negotiation - EDCB -> EDCA: contract negotiation - EDCB <-- EDCA: ok contractAgreement - IRSB <-- EDCB: ok contractAgreement - ref over IRSB, TXB: data consumption -else policies does not match - IRSB -> IRSB: create Tombstone with policy (JobResponse) -end + IRSB -> IRSB: compare catalogOffer policy with company policy for BPNL + alt policies match + IRSB -> EDCB: start contract negotiation + EDCB -> EDCA: contract negotiation + EDCB <-- EDCA: contractAgreement + IRSB <-- EDCB: contractAgreement + ref over IRSB, TXB: import part data -> data consumption + else policies does not match + IRSB -> IRSB: create tombstone with policy + TXB <-- IRSB: job response + end end - -TXB <-- IRSB : calback job response +TXB <-- IRSB: job response @enduml