chore(documentation): eclipse-tractusx#1007 data sovereignty document…

…ation

CHANGELOG.md

@@ -32,6 +32,7 @@ _**For better traceability add the corresponding GitHub issue number in each cha
 - #786 Added icons on part table to let admin reload registry / sync assets via IRS
 - #520 Added Attribute BPN to DetailView
 - #1112 Added association int-a/int-b environment to argo workflow
+- #1007 Added data-sovereignty/policy-management section in arc42 documentation
 
 ### Changed
 - XXX update legal notice for documents arc42, admin and user manual to years 2024

docs/src/docs/arc42/runtime-view/data-provisioning.adoc

@@ -1,4 +1,4 @@
-= Data Provisioning
+= Data provisioning
 
 This sequence diagrams describes the process of importing data from a Trace-X dataformat
 

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

@@ -1,3 +1,4 @@
 = Data sovereignty
 
-include::data-sovereignty/return_asset_contracts.adoc[leveloffset=+1]
+include::data-sovereignty/return-asset-contracts.adoc[leveloffset=+1]
+include::data-sovereignty/policy-management.adoc[leveloffset=+1]

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

@@ -0,0 +1,135 @@
+= Policy management
+
+To ensure data sovereignty within Trace-X, companies can create policies with constraints to ensure that their data is only shared with companies that match their requirements.
+
+Policies will be used by the EDC to initiate contract negotiations. During the negotiation the EDC will compare the policies of both companies. Only if both policies are valid and the included constraints match, the data will be shared. This applies for sending and receiving of notifications and parts.
+
+After deploying Trace-X, no policies are defined for any BPNs yet. Instead, Trace-X will set up default policies. This ensures that the basic functionality of Trace-X works.
+However, to be sure that data is shared only with companies that match one's requirements, an administrator must set up policies before sending and receiving data.
+
+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:
+
+== Policies for sending and receiving parts
+[plantuml, target=level-1, format=svg]
+....
+include::../../../../uml-diagrams/arc42/runtime-view/data-sovereignty/data-sovereignty-publishing-assets.puml[]
+....
+
+[cols="1,5"]
+|===
+|1, 2
+|Policies can be created by administrators at any time in the administration section of Trace-X.
+
+|3
+|Parts can be imported at any time in the parts section of Trace-X. They will be stored locally at first.
+
+|4
+|Before connected BPNs can access the imported parts, the parts must be published to the EDC and to the Digital Twin Registry (DTR).
+
+|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.
+
+|7
+|Each part is created as a shell in the DTR. This holds all the data of the part.
+
+|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.
+
+|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.
+
+|10
+|For part synchronization the Item Relationship Service (IRS) is requested.
+
+|11
+|First the IRS must know the policies that are used by Trace-X B, so it requests them directly.
+
+|12
+|Trace-X B returns a list of the configured policies depending on the configuration done by the administrator in step 2.
+
+|13
+|The IRS requests the catalog from Trace-X A. In the catalog, all policies of Trace-X A are stored.
+
+|14
+|The EDC of Trace-X A provides the catalog.
+
+|15
+|The IRS checks the catalog for the required policies and extracts them.
+
+|16
+|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.
+
+|19
+|Now that the contract negotiation was successful, the data consumption process can take place for that part.
+|===
+
+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.
+
+**[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
+[plantuml, target=level-1, format=svg]
+....
+include::../../../../uml-diagrams/arc42/runtime-view/data-sovereignty/data-sovereignty-notifications.puml[]
+....
+
+[cols="1,5"]
+|===
+|1
+|Policies can be created by administrators at any time in the administration section of Trace-X. In order for policies to be used for notifications the administrator must pay attention to the BPN selection of the policies, as Trace-X will choose notification policies based on that.
+
+|2
+|The user sends a notification to a connected BPN.
+
+|3
+|First Trace-X checks the configured policies for any valid (not expired) policies that have the BPN of the receiver in their BPN selection. **There can only be one valid policy for each BPN.**
+
+|4
+|Trace-X takes the appropriate policyDefinition.
+
+|5
+|Trace-X requests the catalog of the receiver BPN from their EDC. The catalog contains all policies of the BPN including the policies they use for sending and receiving policies.
+
+|6
+|The receiver EDC returns the catalog.
+
+|7
+|Trace-X extracts the required policy definition for receiving notifications from the catalog. If the receiving BPN has multiple valid ones, they all will be extracted in a list.
+
+|8
+|Trace-X compares the extracted policies with its own policy definition. This works by comparing the included constraints logically.
+
+|9, 10
+|If any of the policies match, a contract agreement is created and shared with the receiving EDC and the EDC of the sender. It can be viewed in the administration section of Trace-X.
+
+|11
+|Finally, the notification will be sent to the receiving EDC.
+
+|12
+|If no policies match, an error will be returned to the user.
+|===
+
+=== No policies when sending notifications
+[plantuml, target=level-1, format=svg]
+....
+include::../../../../uml-diagrams/arc42/runtime-view/data-sovereignty/data-sovereignty-notifications-policy-change.puml[]
+....
+
+If no policies are configured for the receiving BPN and a notification is sent to that BPN, the default policy of Trace-X is used as a backup. If the default policy is accepted by the receiving BPN, the process can continue as normally and the notification can be sent. When the policy does not match and the notification can't be sent, an administrator can create policies for the receiving BPN. Then the notification can be resent and will use the new policy.
+
+
+
+=== Expired policy when sending notifications
+[plantuml, target=level-1, format=svg]
+....
+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.

docs/src/uml-diagrams/arc42/runtime-view/data-sovereignty/data-sovereignty-notifications-policy-change.puml

@@ -0,0 +1,34 @@
+@startuml
+'https://plantuml.com/sequence-diagram
+autonumber
+title Policies: Sending notifications without policies
+
+actor Admin
+actor User
+participant "Trace-X" as TraceX
+participant "Receiver EDC" as EDC
+
+Admin -> TraceX: create policies
+...
+User -> TraceX: send notification to receiver BPN
+activate TraceX
+TraceX -> TraceX: get own policy definition for receiver BPN
+activate TraceX
+TraceX --> TraceX: no policyDefinition for receiver BPN -> use default policy
+deactivate TraceX
+TraceX -> EDC: get catalog of receiver BPN
+activate EDC
+EDC --> TraceX: catalog
+deactivate EDC
+TraceX -> TraceX: extract required policy definition from catalog
+TraceX -> TraceX: compare policy definition with own default policy
+alt policies don't match
+TraceX --> User: error: policies don't match
+deactivate TraceX
+...
+Admin -> TraceX: add policy for receiver BPN
+...
+User -> TraceX: resend notification to receiver BPN
+ref over User, Admin, TraceX, EDC: send notification
+end
+@enduml

docs/src/uml-diagrams/arc42/runtime-view/data-sovereignty/data-sovereignty-notifications-policy-expired.puml

@@ -0,0 +1,27 @@
+@startuml
+'https://plantuml.com/sequence-diagram
+autonumber
+title: Policies: Sending notifications with expired policy
+
+actor Admin
+actor User
+participant "Trace-X" as TraceX
+participant "Receiver EDC" as EDC
+
+Admin -> TraceX: create policies
+...
+User -> TraceX: send notification to receiver BPN
+activate TraceX
+TraceX -> TraceX: get own policy definition for receiver BPN
+activate TraceX
+TraceX --> TraceX: expired policyDefinition
+deactivate TraceX
+TraceX --> User: error: policy expired
+deactivate TraceX
+...
+Admin -> TraceX: update policy
+...
+User -> TraceX: resend notification to receiver BPN
+ref over User, Admin, TraceX, EDC: send notification
+deactivate TraceX
+@enduml

docs/src/uml-diagrams/arc42/runtime-view/data-sovereignty/data-sovereignty-notifications.puml

@@ -0,0 +1,33 @@
+@startuml
+'https://plantuml.com/sequence-diagram
+autonumber
+title Policies: Send notification
+
+actor Admin
+actor User
+participant "Trace-X A" as TXA
+participant "EDC A" as EDCA
+participant "EDC B" as EDCB
+
+Admin -> TXA: create policies
+...
+User -> TXA: send notification to receiver BPN
+activate TXA
+TXA -> TXA: get own policy definition for receiver BPN
+activate TXA
+TXA --> TXA: valid policyDefinition
+deactivate TXA
+TXA -> EDCB: get catalog of receiver BPN
+activate EDCB
+EDCB --> TXA: catalog
+deactivate EDCB
+TXA -> TXA: extract required policy definition from catalog
+TXA -> TXA: compare policy definitions
+alt policies match
+TXA --> EDCB: contract agreement
+TXA --> EDCA: contract agreement
+TXA -> EDCB: send notification
+else
+TXA --> User: error: policies don't match
+end
+@enduml

docs/src/uml-diagrams/arc42/runtime-view/data-sovereignty/data-sovereignty-publishing-assets.puml

@@ -0,0 +1,52 @@
+@startuml
+'https://plantuml.com/sequence-diagram
+autonumber
+title Policies: Send and receive parts
+
+actor "Admin A" as AA
+actor User
+participant "Trace-X A" as TXA
+participant "DTR A" as DTRA
+participant "EDC A" as EDCA
+participant "IRS B" as IRSB
+participant "EDC B" as EDCB
+participant "Trace-X B" as TXB
+actor "Admin B" as AB
+
+AA -> TXA: create policies
+AB -> TXB: create policies
+...
+User -> TXA: import parts
+...
+User -> TXA: publish selected parts
+activate TXA
+User --> TXA: select policy to be used
+TXA -> EDCA: create policy
+loop selected parts
+TXA -> DTRA: create part
+TXA -> DTRA: link part and policy
+end
+deactivate TXA
+...
+TXB -> TXB: synchronize parts
+activate TXB
+TXB -> IRSB: start contract negotiation
+activate IRSB
+IRSB -> TXB: get configured policies
+activate TXB
+TXB --> IRSB: policies
+deactivate TXB
+IRSB -> EDCA: get catalog of Trace-X A
+activate EDCA
+EDCA --> IRSB: catalog
+deactivate EDCA
+IRSB -> IRSB: extract policy definitions from catalog
+loop each part
+IRSB -> IRSB: compare linked policy definition with own policy list
+alt policies match
+IRSB --> EDCA: contract agreement
+IRSB --> EDCB: contract agreement
+ref over IRSB, TXB: data consumption
+end
+end
+@enduml