From 17bc77170a7fec0f3517d985d9476ed413ced9cc Mon Sep 17 00:00:00 2001 From: Christian Rehm Date: Thu, 28 Mar 2024 12:09:03 +0100 Subject: [PATCH 1/2] chore(docs): #596 rework policy store documentation --- .../src/docs/arc42/runtime-view/policies.adoc | 25 +++--- .../runtime-view/policies/policy-assets.puml | 18 +++-- .../policies/policy-notifications.puml | 80 ++++++++++++------- .../policy-startup-configuration.puml | 72 ++++++++++------- .../policy-startup-notification-contract.puml | 40 +++++++--- 5 files changed, 149 insertions(+), 86 deletions(-) diff --git a/docs/src/docs/arc42/runtime-view/policies.adoc b/docs/src/docs/arc42/runtime-view/policies.adoc index a6536379a9..d1fc5171b8 100644 --- a/docs/src/docs/arc42/runtime-view/policies.adoc +++ b/docs/src/docs/arc42/runtime-view/policies.adoc @@ -1,23 +1,24 @@ = Policies == Overview -=== Scenario 1: Start Up interaction with IRS Policy Store -Trace-X instance define a constraint which is required for data consumption and provisioning. + +=== Scenario 1: Startup interaction with IRS Policy Store +The Trace-X instance defines a constraint which is required for data consumption and provisioning. Trace-X retrieves all policies by IRS and validates if one of the policies contains the required constraint given by Trace-X. -If a policy with the constraint exists and is valid process ends. If the policy is not valid it will create one with the given constraint. +If a policy with the constraint exists and is valid, the process ends. If the policy is not valid, it will create one with the given constraint. -This sequence diagram describes the process of retrieving or creating policies within the IRS Policy Store based on Trace-X given constraint. +This sequence diagram describes the process of retrieving or creating policies within the IRS Policy Store based on the constraint given by Trace-X. [plantuml, target=policy-startup-configuration, format=svg] .... include::../../../uml-diagrams/arc42/runtime-view/policies/policy-startup-configuration.puml[] .... -=== Scenario 2: Start Up interaction with EDC -Trace-X instance uses the policy which includes the defined constraint and transforms it into a valid EDC Policy Request. -The EDC Policy Request will be used for creating a policy for the required notification contracts. +=== Scenario 2: Startup interaction with EDC +The Trace-X instance uses the policy which includes the defined constraint and transforms it into a valid EDC policy request. +The EDC policy request will be used for creating a policy for the required notification contracts. -This sequence diagram describes the process of retrieving the correct policy by IRS Policy Store based on Trace-X given constraint and reuses it for creating an EDC Policy. +This sequence diagram describes the process of retrieving the correct policy by IRS Policy Store based on the constraint given by Trace-X and reuses it for creating an EDC policy. [plantuml, target=policy-startup-notification-contract, format=svg] .... @@ -25,9 +26,9 @@ include::../../../uml-diagrams/arc42/runtime-view/policies/policy-startup-notifi .... === Scenario 3: Provisioning of notifications -Trace-X instance uses the policy which includes the defined constraint and reuses it for validation of catalog offers by the receiver edc. +The Trace-X instance uses the policy which includes the defined constraint and reuses it for validation of catalog offers by the receiver EDC. -This sequence diagram describes the process of how the policy with the defined constraint will be used for validation of catalog offers by the receiver edc, to validate if sending is valid. +This sequence diagram describes the process of how the policy with the defined constraint will be used for validation of the catalog offers from the receiver EDC. [plantuml, target=policy-notifications, format=svg] .... @@ -35,9 +36,9 @@ include::../../../uml-diagrams/arc42/runtime-view/policies/policy-notifications. .... === Scenario 4: Provisioning of assets -Trace-X instance uses the policy which includes the defined constraint and reuses it for creating edc assets . +The Trace-X instance uses the policy which includes the defined constraint and reuses it for creating EDC assets. -This sequence diagram describes the process of how the policy with the defined constraint will be reused for registering edc data assets. +This sequence diagram describes the process of how the policy with the defined constraint will be reused for registering EDC data assets. [plantuml, target=policy-assets, format=svg] .... diff --git a/docs/src/uml-diagrams/arc42/runtime-view/policies/policy-assets.puml b/docs/src/uml-diagrams/arc42/runtime-view/policies/policy-assets.puml index e30c6d343e..b6557b5287 100644 --- a/docs/src/uml-diagrams/arc42/runtime-view/policies/policy-assets.puml +++ b/docs/src/uml-diagrams/arc42/runtime-view/policies/policy-assets.puml @@ -3,16 +3,20 @@ skinparam monochrome true skinparam shadowing false skinparam defaultFontName "Architects daughter" -title Sequence Diagram: Policy Handling on asset provisioning flow -participant "TraceX" as TraceX +title Sequence Diagram: Policy handling on asset provisioning flow +participant "Trace-X" as TraceX participant "EDC Consumer" as EdcConsumer -participant "EDC Provider (other) " as EdcProvider +participant "EDC Provider (other)" as EdcProvider -TraceX -> TraceX: Publish Asset to Core Services +activate TraceX +TraceX -> TraceX: Publish asset to core services TraceX -> EdcConsumer: Register policy +activate EdcConsumer EdcConsumer -> EdcProvider: Register policy -EdcProvider -> EdcConsumer: Return ok -EdcConsumer -> TraceX: Return ok +activate EdcProvider +EdcProvider --> EdcConsumer: Ok +deactivate EdcProvider +EdcConsumer --> TraceX: Ok +deactivate EdcConsumer TraceX -> TraceX: Reuse policy for contract definition creation - @enduml diff --git a/docs/src/uml-diagrams/arc42/runtime-view/policies/policy-notifications.puml b/docs/src/uml-diagrams/arc42/runtime-view/policies/policy-notifications.puml index ea8d38ae70..3a19bb88f4 100644 --- a/docs/src/uml-diagrams/arc42/runtime-view/policies/policy-notifications.puml +++ b/docs/src/uml-diagrams/arc42/runtime-view/policies/policy-notifications.puml @@ -3,47 +3,73 @@ skinparam monochrome true skinparam shadowing false skinparam defaultFontName "Architects daughter" -title Sequence Diagram: Policy Handling on notification flow -participant "TraceX" as TraceX -participant "IRS " as IRS +title Sequence diagram: Policy handling on notification flow +participant "Trace-X" as TraceX +participant "Trace-X IRS Lib" as TraceXIRSLib participant "EDC Consumer" as EdcConsumer participant "EDC Provider (other) " as EdcProvider -TraceX -> TraceX: Approve, Acknowledge, Accept, Decline or Close Notification +activate TraceX +TraceX -> TraceX: Approve, acknowledge, accept, decline or close notification TraceX -> EdcConsumer: Get catalog of receiver +activate EdcConsumer EdcConsumer -> EdcProvider: Get catalog of receiver -EdcProvider -> EdcConsumer: Return catalog -EdcConsumer -> TraceX: Return catalog -TraceX -> TraceX: Validate Contract Type, Method and Policy +activate EdcProvider +EdcProvider --> EdcConsumer: Return catalog +deactivate EdcProvider +EdcConsumer --> TraceX: Return catalog +deactivate EdcConsumer +TraceX -> TraceX: Validate contract type, method and policy -alt Notification Type: Alert +alt Notification type: Alert TraceX -> TraceX: Filter for method (update, receive) - TraceX -> TraceX: Validate if catalog policy matches the configured policies in IRS Lib (3 Default Policies) + TraceX -> TraceXIRSLib: Validate if catalog policy matches the configured policies in IRS Lib (3 default policies) + activate TraceXIRSLib + TraceXIRSLib --> TraceX: Valid + deactivate TraceXIRSLib alt Method: Update - TraceX -> EdcConsumer: Send out alert notification (update method) - EdcConsumer -> EdcProvider: Send out alert notification (update method) - EdcProvider -> EdcConsumer: ok - EdcConsumer -> TraceX: .. + TraceX -> EdcConsumer: Send alert notification (update method) + activate EdcConsumer + EdcConsumer -> EdcProvider: Send alert notification (update method) + activate EdcProvider + EdcProvider --> EdcConsumer: Ok + deactivate EdcProvider + EdcConsumer -> TraceX: Ok + deactivate EdcConsumer else Method: Receive - TraceX -> EdcConsumer: Send out alert notification (receive method) - EdcConsumer -> EdcProvider: Send out alert notification (receive method) - EdcProvider -> EdcConsumer: ok - EdcConsumer -> TraceX: .. + TraceX -> EdcConsumer: Send alert notification (receive method) + activate EdcConsumer + EdcConsumer -> EdcProvider: Send alert notification (receive method) + activate EdcProvider + EdcProvider -> EdcConsumer: Ok + deactivate EdcProvider + EdcConsumer -> TraceX: Ok + deactivate EdcConsumer end else Notification Type: Investigation TraceX -> TraceX: Filter for method (update, receive) - TraceX -> TraceX: Validate if catalog policy matches the configured policies in IRS Lib (3 Default Policies) + TraceX -> TraceXIRSLib: Validate if catalog policy matches the configured policies in IRS Lib (3 default policies) + activate TraceXIRSLib + TraceXIRSLib --> TraceX: Valid + deactivate TraceXIRSLib alt Method: Update - TraceX -> EdcConsumer: Send out Investigation notification (update method) - EdcConsumer -> EdcProvider: Send out Investigation notification (update method) - EdcProvider -> EdcConsumer: ok - EdcConsumer -> TraceX: .. + TraceX -> EdcConsumer: Send investigation notification (update method) + activate EdcConsumer + EdcConsumer -> EdcProvider: Send investigation notification (update method) + activate EdcProvider + EdcProvider --> EdcConsumer: Ok + deactivate EdcProvider + EdcConsumer -> TraceX: Ok + deactivate EdcConsumer else Method: Receive - TraceX -> EdcConsumer: Send out Investigation notification (receive method) - EdcConsumer -> EdcProvider: Send out Investigation notification (receive method) - EdcProvider -> EdcConsumer: ok - EdcConsumer -> TraceX: .. + TraceX -> EdcConsumer: Send investigation notification (receive method) + activate EdcConsumer + EdcConsumer -> EdcProvider: Send investigation notification (receive method) + activate EdcProvider + EdcProvider -> EdcConsumer: Ok + deactivate EdcProvider + EdcConsumer -> TraceX: Ok + deactivate EdcConsumer end end - @enduml diff --git a/docs/src/uml-diagrams/arc42/runtime-view/policies/policy-startup-configuration.puml b/docs/src/uml-diagrams/arc42/runtime-view/policies/policy-startup-configuration.puml index 6792d50a28..bbd3031356 100644 --- a/docs/src/uml-diagrams/arc42/runtime-view/policies/policy-startup-configuration.puml +++ b/docs/src/uml-diagrams/arc42/runtime-view/policies/policy-startup-configuration.puml @@ -2,32 +2,40 @@ skinparam monochrome true skinparam shadowing false skinparam defaultFontName "Architects daughter" -title Sequence Diagram: TraceX Interaction with IRS on startup -participant "TraceXConfig" as Config -participant "TraceX" as TraceX +title Sequence diagram: Trace-X interaction with IRS on startup +participant "Trace-X Config" as Config +participant "Trace-X" as TraceX participant "IRS " as IRS -Config -> TraceX : Constraint -TraceX -> IRS : Get Policies -IRS -> TraceX: Return policies -TraceX -> TraceX: Check if a policy matches own constraint - -TraceX -> IRS : Create(not exists) or update(exists) +Config --> TraceX: Constraint +activate TraceX +TraceX -> IRS: Get policies +activate IRS +IRS --> TraceX: Return policies +deactivate IRS +TraceX -> TraceX: Find any policy which matches own constraint +activate TraceX +deactivate TraceX +alt Policy found +TraceX -> IRS: Update policy +else Policy not found +TraceX -> IRS: Create policy +end +deactivate TraceX @enduml - @startuml skinparam monochrome true skinparam shadowing false skinparam defaultFontName "Architects daughter" -title Sequence Diagram: TraceX Interaction with EDC on startup (As is) -participant "TraceXConfig" as Config -participant "TraceX" as TraceX +title Sequence diagram: Trace-X interaction with EDC on startup (as is) +participant "Trace-X Config" as Config +participant "Trace-X" as TraceX participant "EDC " as EDC -Config -> TraceX : ID 3.0 Trace -TraceX -> EDC : Create notification asset, policy, definition +Config --> TraceX: ID 3.0 Trace +TraceX -> EDC: Create notification asset, policy, definition @enduml @startuml @@ -35,13 +43,16 @@ skinparam monochrome true skinparam shadowing false skinparam defaultFontName "Architects daughter" -title Sequence Diagram: TraceX Interaction with EDC on startup (To be) +title Sequence diagram: Trace-X interaction with EDC on startup (To be) participant "IRS" as IRS participant "TraceX" as TraceX participant "EDC " as EDC -TraceX -> IRS: Get Policies -IRS -> TraceX : return policy(c1,c2,c3,c4) -TraceX -> EDC : Create notification asset, policy, definition +activate TraceX +TraceX -> IRS: Get policies +activate IRS +IRS --> TraceX: Return policy(c1,c2,c3,c4) +deactivate IRS +TraceX -> EDC: Create notification asset, policy, definition @enduml @startuml @@ -49,19 +60,26 @@ skinparam monochrome true skinparam shadowing false skinparam defaultFontName "Architects daughter" -title Sequence Diagram: Sending notifications -participant "TraceX" as TraceX -participant "TraceXIRSLib" as TraceXIRSLib +title Sequence diagram: Sending notifications +participant "Trace-X" as TraceX +participant "Trace-X IRS Lib" as TraceXIRSLib participant "IRS " as IRS participant "EDC " as EDC +activate TraceX TraceX -> TraceX: ... TraceX -> EDC: Get catalog -EDC -> TraceX: -> Return catalog -TraceX -> TraceX: Filter for notification type (alert / investigation) / method(update, receive) -TraceX -> TraceXIRSLib: Validate if catalog policy matches the configured policies in IRS Lib (3 Default Policies) -TraceXIRSLib -> TraceX: Valid -TraceX -> EDC: Send out notification +activate EDC +EDC --> TraceX: Return catalog +deactivate EDC +TraceX -> TraceX: Filter for notification type (alert/investigation) & method (update/receive) +activate TraceX +deactivate TraceX +TraceX -> TraceXIRSLib: Validate if catalog policy matches the configured policies in IRS Lib (3 default policies) +activate TraceXIRSLib +TraceXIRSLib --> TraceX: Valid +deactivate TraceXIRSLib +TraceX -> EDC: Send notification @enduml diff --git a/docs/src/uml-diagrams/arc42/runtime-view/policies/policy-startup-notification-contract.puml b/docs/src/uml-diagrams/arc42/runtime-view/policies/policy-startup-notification-contract.puml index 3f56d4cb80..8fbc46c1a0 100644 --- a/docs/src/uml-diagrams/arc42/runtime-view/policies/policy-startup-notification-contract.puml +++ b/docs/src/uml-diagrams/arc42/runtime-view/policies/policy-startup-notification-contract.puml @@ -3,22 +3,28 @@ skinparam monochrome true skinparam shadowing false skinparam defaultFontName "Architects daughter" -title Sequence Diagram: TraceX Interaction with EDC on startup +title Sequence diagram: Trace-X interaction with EDC on startup participant "TraceX" as TraceX participant "IRS" as IRS participant "EDC " as EDC -TraceX -> IRS: Get Policies -IRS -> TraceX : return Policies +activate TraceX +TraceX -> IRS: Get policies +activate IRS +IRS --> TraceX : Return policies +deactivate IRS TraceX -> TraceX: Find any policy which matches own constraint +activate TraceX +deactivate TraceX alt Policy found - TraceX -> TraceX: Use found policy for EdcPolicy creation. + TraceX -> TraceX: Use found policy for EDC policy creation. + activate TraceX TraceX -> EDC : Create notification asset, policy, definition + deactivate TraceX else Policy not found TraceX -> TraceX: Corrupt state of application end - @enduml @startuml @@ -26,19 +32,27 @@ skinparam monochrome true skinparam shadowing false skinparam defaultFontName "Architects daughter" -title Sequence Diagram: Sending notifications -participant "TraceX" as TraceX -participant "TraceXIRSLib" as TraceXIRSLib +title Sequence diagram: Sending notifications +participant "Trace-X" as TraceX +participant "Trace-X IRS Lib" as TraceXIRSLib participant "IRS " as IRS participant "EDC " as EDC +activate TraceX TraceX -> TraceX: ... TraceX -> EDC: Get catalog -EDC -> TraceX: -> Return catalog -TraceX -> TraceX: Filter for notification type (alert / investigation) / method(update, receive) -TraceX -> TraceXIRSLib: Validate if catalog policy matches the configured policies in IRS Lib (3 Default Policies) -TraceXIRSLib -> TraceX: Valid -TraceX -> EDC: Send out notification +activate EDC +EDC --> TraceX: Return catalog +deactivate EDC +TraceX -> TraceX: Filter for notification type (alert/investigation) & method (update/receive) +activate TraceX +deactivate TraceX +TraceX -> TraceXIRSLib: Validate if catalog policy matches the configured policies in IRS Lib (3 default policies) +activate TraceXIRSLib +TraceXIRSLib --> TraceX: Valid +deactivate TraceXIRSLib +TraceX -> EDC: Send notification @enduml + From 73b2ec5bbe04aad8767f18bd912b848e1089c557 Mon Sep 17 00:00:00 2001 From: Christian Rehm Date: Thu, 28 Mar 2024 12:12:01 +0100 Subject: [PATCH 2/2] chore(docs): #596 rework policy store documentation --- .../uml-diagrams/arc42/runtime-view/policies/policy-assets.puml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/uml-diagrams/arc42/runtime-view/policies/policy-assets.puml b/docs/src/uml-diagrams/arc42/runtime-view/policies/policy-assets.puml index b6557b5287..ab6f6b49d2 100644 --- a/docs/src/uml-diagrams/arc42/runtime-view/policies/policy-assets.puml +++ b/docs/src/uml-diagrams/arc42/runtime-view/policies/policy-assets.puml @@ -3,7 +3,7 @@ skinparam monochrome true skinparam shadowing false skinparam defaultFontName "Architects daughter" -title Sequence Diagram: Policy handling on asset provisioning flow +title Sequence diagram: Policy handling on asset provisioning flow participant "Trace-X" as TraceX participant "EDC Consumer" as EdcConsumer participant "EDC Provider (other)" as EdcProvider