Skip to content

Commit

Permalink
chore(documentation):[#1108] add description for diagram
Browse files Browse the repository at this point in the history
  • Loading branch information
@mkanal
mkanal committed Jul 24, 2024
1 parent 57ffa4f commit d09b4a6
Show file tree
Hide file tree
Showing 2 changed files with 77 additions and 47 deletions.
79 changes: 51 additions & 28 deletions docs/src/docs/arc42/runtime-view/data-sovereignty/policy-management.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,56 +29,80 @@ 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).

|5
|The user must choose the policy that is used for contract negotiation of the selected parts.
|User with role 'Admin' receives feedback that creation of policy was successful.

|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
|Trace-X [A] BE checks if PolicyDefinition for selected policy already exists.

|11
|First the IRS must know the policies that are used by Trace-X B, so it requests them directly.
|12,13
|In case PolicyDefinition does not exist. New PolicyDefinition is created in EDC [A]. The PolicyDefinition is created in the EDC.

|12
|Trace-X B returns a list of the configured policies depending on the configuration done by the administrator in step 2.
|14,15
|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).

|16, 17
|Assets are created in the EDC. (POST /v3/assets)

|13
|The IRS requests the catalog from Trace-X A. In the catalog, all policies of Trace-X A are stored.
|18,19
|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.
|20,21
|User with role 'Admin' in Trace-X [B] creates policy for consuming assets of Trace-X [A].

|15
|The IRS checks the catalog for the required policies and extracts them.
|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.

|16
|23,24
|Trace-X [B] requests for digital twins (Asset Administration Shell) in decentral Digital Twin registry.

|25
|For part synchronization the Item Relationship Service (IRS) is requested.

|26,27
|IRS requests for CatalogOffer for assets of Trace-X [A]

|28
|Trace-X [B] 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
|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.

|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.
|===

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.
Expand All @@ -87,7 +111,6 @@ It's possible to publish parts with different policies. For this, the user must
**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
Expand Down
45 changes: 26 additions & 19 deletions .../uml-diagrams/arc42/runtime-view/data-sovereignty/data-sovereignty-publishing-assets.puml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ skinparam shadowing false
skinparam defaultFontName "Architects daughter"
skinparam linetype ortho

title Policies: Send and receive parts
title Policies: Send and receive assets

actor "Admin \n [A]" as AA
actor User
Expand All @@ -24,33 +24,25 @@ actor "Admin B" as AB
AA -> TXA: create policy
note left
create policy used for publishing
company parts [POLICY_TRACEX-PUBLISH_ASSETS]
company assets [POLICY_TRACEX-PUBLISH_ASSETS]
end note
activate TXA
TXA -> PSA: create policy for BPNL
activate PSA
TXA <-- PSA: 201 policy created
deactivate PSA
AA <-- TXA: policy created
deactivate TXA

AB -> TXB: create policy
activate TXB


note right
create policy for
BPNL of Trace-X [A]
[POLICY_BPNL_TRACEX_A]
end note
AB <-- TXB: policy created
deactivate TXB

...
User -> TXA: import parts (POST /assets/import)
User -> TXA: import assets (POST /assets/import)
activate TXA
User <-- TXA: ok
...

User -> TXA: publish selected parts in transient state
User -> TXA: publish selected assets in transient state

note left
POST /assets/publish
Expand All @@ -61,22 +53,24 @@ User <-- TXA: request for policy
User --> TXA: select policy to be used

TXA -> EDCA: PolicyDefinition exists
activate EDCA
TXA <-- EDCA: return PolicyDefinition exists
opt PolicyDefinition exists
opt PolicyDefinition not exists
TXA -> EDCA: create PolicyDefinition (/management/v2/policydefinitions)
TXA <-- EDCA: PolicyDefinition created
else

end opt

loop selected parts
loop selected assets

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 -> EDCA: create asset (POST /v3/assets)
note left
create CatalogOffer in EDC
Expand All @@ -88,13 +82,26 @@ note left
create ContractDefinition in EDC
end note
TXA <-- EDCA: ContractDefinition created

deactivate EDCA
end


deactivate TXA

AB -> TXB: create policy
activate TXB


note right
create policy for
BPNL of Trace-X [A]
[POLICY_BPNL_TRACEX_A]
end note
AB <-- TXB: policy created
deactivate TXB

...
TXB -> TXB: synchronize parts (assets/as-$/sync)
TXB -> TXB: synchronize assets (assets/as-$/sync)
note left
different endpoints for sync as-built and as-planned assets
end note
Expand Down

0 comments on commit d09b4a6

Please sign in to comment.