Merge pull request #1279 from eclipse-tractusx/chore/#1108-data-sover…

…eignty_rework

Chore/#1108 data sovereignty rework

CHANGELOG.md

@@ -28,6 +28,7 @@ _**For better traceability add the corresponding GitHub issue number in each cha
 - XXXX added workflow to import testdata
 
 ### Changed
+- #1108 Rework of data sov documentation
 - #1070 Correct semantic model in dev/README.md
 - #1070 Update documentation artefacts according to TRG 1 - Documentation
 - #1070 Convert png to svg according to TRG 1.04 - Diagrams as code / Editable static files

docs/concept/#638-contractagreement-admin-view/get-contract-sequenceflow.puml

@@ -1,47 +1,54 @@
 @startuml
 title
-    ==GET api/contracts/{tx-assetId}
+    == Request ContractResponse (Contract Agreements)
 end title
 
 autonumber "<B>[00]"
-
-participant "Trace-X Frontend" as FE order 0
-participant "Trace-X Backend" as BE order 1
-participant "Trace-X Database" as DB order 2
-participant "EDC" as TXEDC order 3
-
-FE -> BE: GET api/contracts/{tx-assetId}
-
-activate BE
-BE -> DB: Take contractAgreementId for tx-assetId
-activate DB
-autonumber stop
-DB --> BE: contractAgreementId
-autonumber resume
-deactivate DB
-
-BE -> TXEDC: GET tx-edc/management/v2/contractagreements/{contractAgreementId}
-activate TXEDC
-autonumber stop
-TXEDC --> BE: JSON response
-autonumber resume
-deactivate TXEDC
-BE -> BE: Extract contractSigningDate, policy
-activate BE
+skinparam monochrome true
+skinparam shadowing false
+skinparam defaultFontName "Architects daughter"
+skinparam linetype ortho
+
+participant "Trace-X \n Frontend" as FE order 0
+participant "Trace-X \n Backend" as BE order 1
+participant "Trace-X \n Database" as DB order 2
+participant "EDC \n ManagementAPI" as TXEDC order 3
+
+FE -> BE: Request for ContractResponse
+note left
+    GET /contracts by filterExpression
+end note
+
+loop for each contract agreement
+    activate BE
+        BE -> DB: Query contractAgreementId for assetId
+    activate DB
+        DB --> BE: result contractAgreementId
+    deactivate DB
+
+    BE -> TXEDC: GET contractagreements
+    note left
+        GET edc/management/v2/contractagreements/{contractAgreementId}
+    end note
+    activate TXEDC
+    TXEDC --> BE: return contract agreements
+    deactivate TXEDC
+    BE -> BE: Extract contractSigningDate, policy
+    activate BE
+    deactivate BE
+
+    BE -> TXEDC: GET edc/management/v2/contractagreements/{contractAgreementId}/negotiation
+    activate TXEDC
+    TXEDC --> BE: Gets a contract negotiation with the given contract agreement ID
+    deactivate TXEDC
+    BE -> BE: Extract id, counterPartyAddress, state
+    activate BE
+    BE -> BE : Create ContractResponse
+    deactivate BE
+
+end loop
+
+BE --> FE: List of ContractResponses for filterExpression
 deactivate BE
-
-BE -> TXEDC: GET tx-edc/management/v2/contractagreements/{contractAgreementId}/negotiation
-activate TXEDC
-autonumber stop
-TXEDC --> BE: JSON response
-autonumber resume
-deactivate TXEDC
-BE -> BE: Extract id, counterPartyAddress, state
-activate BE
-deactivate BE
-
 autonumber stop
-BE --> FE: JSON response
-deactivate BE
-
 @enduml

docs/src/docs/arc42/runtime-view/data-sovereignty/policy-management.adoc

@@ -10,6 +10,17 @@ However, to be sure that data is shared only with companies that match one's req
 The policies used for sending and receiving notifications and parts have an identical data format, so they can be used for each process interchangeably.
 The processes itself are different and will be explained here:
 
+== Policy Types
+The EDC Connector MUST provide a possibility to restrict the access of a Data Asset to specific business partners by attribute(s), e.g., represented as a VC.
+The Connector MUST restrict the data usage to partners and purposes for a specific use case.
+
+There are two policy types used.
+* Access
+* Usage
+
+As specified by the https://github.com/International-Data-Spaces-Association/ids-specification[Dataspace Protocol], one Data Asset MUST refer to at least one Usage Policy, expressed in ODRL.
+For additional information refer to https://eclipse-tractusx.github.io/docs-kits/kits/Connector%20Kit/Adoption%20View/connector_kit_adoption_view[Connector KIT]
+
 == Policies for sending and receiving parts
 [plantuml, target=data-sovereignty-publish-assets, format=svg]
 ....
@@ -18,60 +29,88 @@ include::../../../../uml-diagrams/arc42/runtime-view/data-sovereignty/data-sover
 
 [cols="1,5"]
 |===
-|1, 2
-|Policies can be created by administrators at any time in the administration section of Trace-X.
+|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] app and IRS for storing usage and access policies.
 
 |3
-|Parts can be imported at any time in the parts section of Trace-X. They will be stored locally at first.
+|Policy is created in the policy store.
 
 |4
-|Before connected BPNs can access the imported parts, the parts must be published to the EDC and to the Digital Twin Registry (DTR).
+|User with role 'Admin' receives feedback that creation of policy was successful.
 
-|5
-|The user must choose the policy that is used for contract negotiation of the selected parts.
-
-|6
-|The policy is created in the EDC.
+|5, 6
+|User with role 'Admin' imports assets in Admin 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
-|Each part is created as a shell in the DTR. This holds all the data of the part.
+|User with role 'Admin' selects assets in transient state in application.
 
 |8
-|The created part is linked to the policy 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.
+|User with role 'Admin' is requested to define a policy for assets publishing.
 
 |9
-|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.
+|User with role 'Admin' selects policy under which assets are published. The user must choose the policy that is used for contract negotiation of the selected parts.
 
-|10
-|For part synchronization the Item Relationship Service (IRS) is requested.
+|10, 11
+|Assets are created in the EDC. (POST /v3/assets)
 
-|11
-|First the IRS must know the policies that are used by Trace-X B, so it requests them directly.
+|12,13
+|Trace-X [A] BE checks if PolicyDefinition for selected policy already exists.
 
-|12
-|Trace-X B returns a list of the configured policies depending on the configuration done by the administrator in step 2.
+|14,15
+|In case PolicyDefinition does not exist. New PolicyDefinition is created in EDC [A]. The PolicyDefinition is created in the EDC.
 
-|13
-|The IRS requests the catalog from Trace-X A. In the catalog, all policies of Trace-X A are stored.
+|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.
 
-|14
-|The EDC of Trace-X A provides the catalog.
+|18,19
+|Each part is created as a shell in the 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 Digital Twin Registry (DTR).
 
-|15
-|The IRS checks the catalog for the required policies and extracts them.
+|20,21
+|User with role 'Admin' in Trace-X [B] creates policy for consuming assets of Trace-X [A].
 
-|16
+|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 decentral Digital Twin registry.
+
+|25
+|For part synchronization a synchronization job is started in the Item Relationship Service (IRS) .
+
+|26,27
+|IRS requests for CatalogOffer for globalAssetsIds passed by Trace-X [A]
+
+|28
+|IRS extracts policies from CatalogOffer
+
+|29,30
+|IRS requests for policies defined for BPNL of Trace-X [A] in 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.
 
-|17, 18
-|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.
+|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 an submodel of IRS. The contracts can be seen after IRS responded to Trace-X initial sync call with the submodels including the contractAgreementId.
 
-|19
+|35
 |Now that the contract negotiation was successful, the data consumption process can take place for that part.
+
+|36
+|In case policy does not match IRS created tombstone.
+
+|37
+|IRS callbacks Trace-X [B] Instance after completing job processing. ContractAgreementId for asset is available in Trace-X passed in IRS JobResponse.
 |===
 
 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 the parts that must be published with different policies, the user can repeat the process.
 
+
+**Note**:
+For more detailed information concerning the functionality of IRS please refer to https://eclipse-tractusx.github.io/item-relationship-service/docs/[IRS documentation]
+
 **[Work-in-progress]** The user may also choose parts that have already been published - they can be republished with a different policy. The process for this is identical to the regular publishing process.
 
 == Policies for sending and receiving notifications
@@ -116,7 +155,7 @@ include::../../../../uml-diagrams/arc42/runtime-view/data-sovereignty/data-sover
 |If no policies match, an error will be returned to the user.
 |===
 
-=== No policies when sending notifications
+=== No policies defined for Receiver BPNL when sending notifications
 [plantuml, target=data-sovereignty-notifications-policy-change, format=svg]
 ....
 include::../../../../uml-diagrams/arc42/runtime-view/data-sovereignty/data-sovereignty-notifications-policy-change.puml[]
@@ -130,7 +169,7 @@ If no policies are configured for the receiving BPN and a notification is sent t
 include::../../../../uml-diagrams/arc42/runtime-view/data-sovereignty/data-sovereignty-notifications-policy-expired.puml[]
 ....
 
-Policies always have an expiration time. When a notification is sent and there are policies configured for the selected BPN with an expiration time in the past, Trace-X will throw an error. In that case, an administrator must either update the policy. Then the policy can be resent.
+Policies always have an expiration time defined by the 'validUntil' timestamp. When a notification is sent and there are policies configured for the selected BPN with an expiration time in the past, Trace-X will throw an error. In that case, an administrator must either update the policy. Then the policy can be resent.
 
 === Testing policies
 In order to test the functionality of policies, an administrator can create a policy with test constraints for connected BPNs. When sending notifications to that BPN, the process should be blocked.

docs/src/docs/arc42/runtime-view/data-sovereignty/return-asset-contracts.adoc

@@ -16,3 +16,8 @@ These contract agreement ids will be then requested on EDC side via POST (/manag
 The contract information is then returned by the endpoint as a pageable result.
 
 If no asset ids are provided in the request, 50 contract agreement ids are handled by default.
+
+
+
+
+

docs/src/uml-diagrams/arc42/runtime-view/data-provisioning/import-report-receive.puml

@@ -1,7 +1,9 @@
 @startuml
+autonumber "<B>[00]"
 skinparam monochrome true
 skinparam shadowing false
-autonumber "<b>[000]"
+skinparam defaultFontName "Architects daughter"
+skinparam linetype ortho
 
 actor TraceXApiConsumer
 activate TraceXApiConsumer

docs/src/uml-diagrams/arc42/runtime-view/data-provisioning/publish-assets-error.puml

@@ -1,7 +1,9 @@
 @startuml
+autonumber "<B>[00]"
 skinparam monochrome true
 skinparam shadowing false
-autonumber "<b>[000]"
+skinparam defaultFontName "Architects daughter"
+skinparam linetype ortho
 
 actor TraceXApiConsumer
 activate TraceXApiConsumer

docs/src/uml-diagrams/arc42/runtime-view/data-provisioning/publish-assets.puml

@@ -1,7 +1,9 @@
 @startuml
+autonumber "<B>[00]"
 skinparam monochrome true
 skinparam shadowing false
-autonumber "<b>[000]"
+skinparam defaultFontName "Architects daughter"
+skinparam linetype ortho
 
 actor TraceXApiConsumer
 activate TraceXApiConsumer

docs/src/uml-diagrams/arc42/runtime-view/data-provisioning/trace-x-data-import-interface-modul1-sequence.puml

@@ -1,4 +1,10 @@
 @startuml
+autonumber "<B>[00]"
+skinparam monochrome true
+skinparam shadowing false
+skinparam defaultFontName "Architects daughter"
+skinparam linetype ortho
+
 participant FE
 participant BE
 participant Database

docs/src/uml-diagrams/arc42/runtime-view/data-provisioning/trace-x-data-import-interface-modul2-sequence.puml

@@ -1,7 +1,12 @@
 @startuml
+autonumber "<B>[00]"
+skinparam monochrome true
+skinparam shadowing false
+skinparam defaultFontName "Architects daughter"
+skinparam linetype ortho
+
 participant FE
 participant BE
-autonumber "<b>[000]"
 
 FE -> BE: request assets: GET/assetsAsxxx
 BE --> FE: return assets_as_built OR assets_as_planned

docs/src/uml-diagrams/arc42/runtime-view/data-provisioning/trace-x-data-import-interface-modul3-sequence.puml

@@ -1,10 +1,16 @@
 @startuml
+autonumber "<B>[00]"
+skinparam monochrome true
+skinparam shadowing false
+skinparam defaultFontName "Architects daughter"
+skinparam linetype ortho
+
 participant BE
 participant EDC
 participant Registry
 participant Submodels
 participant Irs
-autonumber "<b>[000]"
+
 
 BE ->> BE: scheduler job
 BE ->> BE: receive list of IN_SYNC assets