Merge pull request eclipse-tractusx#559 from catenax-ng/TRI-1417-ess-…

…bottom-up-approach

Tri 1417 ess bottom up approach

docs/src/uml-diagrams/irs-recursive/ess-bottom-up/activity/1_incident_scenario_ess-bottom_up-activity.puml

@@ -0,0 +1,64 @@
+@startuml
+skinparam monochrome true
+skinparam shadowing false
+skinparam defaultFontName "Architects daughter"
+title "ESS Bottom-Up from Incident Level"
+
+
+| OEM  - IRS Incident Tier Level |
+start
+:Incident BPNS is identified;
+:Get all AAS for from dDTR;
+note left
+   Requesting all AAS  from dDTR
+end note
+if(aas.isEmpty?) then (yes)
+    stop
+endif
+
+: Filter for asPlanned twins (aas);
+note left
+               semanticId/
+                    ["type"="ExternalReference"]/
+                        keys["type"="GlobalReference"]/
+                            ["value".contains("SingleLevelBomAsPlanned")]
+               SingleLevelBomAsPlanned (only downwards supported!!)
+end note
+if(twinsAsPlanned.isEmpty?) then (yes)
+    stop
+endif
+
+: Extract and collect globalAssetIds for own twins (AsPlanned);
+: Request batch call for globalAssetIds
+POST /ess/customers/investigations/orders;
+
+: Filter for incident BPNS
+in PartSiteInformationAsPlanned;
+
+if(!twin.contains(incidentBpns)) then (no)
+    : skip twin;
+else (yes)
+    : add twin;
+endif
+
+: ValidityPeriodChecker in own aas;
+if(timestamp is in validity period) then (yes)
+note left
+    PartAsPlanned.validityPeriod.validFrom
+               >= validityTimestamp
+               >= PartAsPlanned.validityPeriod.validTo
+end note
+    : add twin;
+else (no)
+    : skip twin;
+endif
+
+
+: Determining relationships one
+ tier level upwards;
+
+: aggregateBPNLs Aggregate bpns numbers for each bpnl;
+: increment hops count for each twin ;
+stop
+
+@enduml

docs/src/uml-diagrams/irs-recursive/ess-bottom-up/ess-customer-notifications-submodel.puml

@@ -0,0 +1,20 @@
+@startuml
+skinparam monochrome true
+skinparam shadowing false
+skinparam defaultFontName "Architects daughter"
+
+entity  Customers {
+     businessPartnerNumberLegalEntity : string
+}
+entity  CustomerParts{
+    globalAssetId : string
+}
+entity  Sites{
+    businessPartnerNumberSite : string
+}
+
+Customers "0..*" - "1..*" CustomerParts
+
+CustomerParts "0..*" - "1..*" Sites
+
+@enduml

docs/src/uml-diagrams/irs-recursive/ess-bottom-up/ess_bottom_upnumber_of_hops.puml

@@ -0,0 +1,36 @@
+@startuml
+skinparam defaultFontName "Architects daughter"
+skinparam monochrome true
+skinparam shadowing false
+skinparam spacing 100
+skinparam linetype ortho
+skinparam nodesep 250
+skinparam ranksep 250
+
+
+Incident_Tier3 : hop 0
+Customer_Tier2 : hop 1
+Customer_Tier1 : hop 2
+OEM: hop 3
+
+Incident_Tier3 :
+Customer_Tier2 :
+Customer_Tier1 :
+OEM :
+Incident_Tier3 :
+Customer_Tier2 :
+Customer_Tier1 :
+OEM :
+Incident_Tier3 :
+Customer_Tier2 :
+Customer_Tier1 :
+OEM :
+
+
+[*] -r-> Incident_Tier3
+Incident_Tier3 -r-> Customer_Tier2  : increment hop++ (hop=0+1)
+Customer_Tier2 -r-> Customer_Tier1  : increment hop++ (hop=1+1)
+Customer_Tier1 -r-> OEM : increment hop++ (hop=2+1)
+
+
+@enduml

docs/src/uml-diagrams/irs-recursive/ess-bottom-up/sequence/3_ValidityChecker.puml

@@ -0,0 +1,32 @@
+@startuml
+skinparam monochrome true
+skinparam shadowing false
+skinparam defaultFontName "Architects daughter"
+
+autonumber "<b>[000]"
+
+participant IRS
+participant ValidityPeriodChecker
+
+
+IRS --> IRS: Request for Submodel PartAsPlanned
+IRS --> IRS: Get attributes PartAsPlanned.validityPeriod.validFrom
+IRS --> IRS: Get attributes PartAsPlanned.validityPeriod.validT
+IRS --> ValidityPeriodChecker: check validity of twin
+opt (isNullOrEmpty(validFrom) || isNullOrEmpty(validFrom) ) then
+    ValidityPeriodChecker --> ValidityPeriodChecker :  log warning and create Tombstone (Warning)
+    note left
+        twin is not skipped because of missing attributes
+    end note
+end opt
+
+opt (isValid) then
+    IRS <-- ValidityPeriodChecker : false
+    IRS --> IRS : skip twin;
+else
+    IRS <-- ValidityPeriodChecker : true
+    IRS --> IRS: process twin.
+end opt;
+
+
+@enduml

docs/src/uml-diagrams/irs-recursive/ess-bottom-up/sequence/ess-bottom-up-sequence-customer-highlevel.puml

@@ -0,0 +1,67 @@
+@startuml
+skinparam monochrome true
+skinparam shadowing false
+skinparam defaultFontName "Architects daughter"
+
+autonumber "<b>[000]"
+
+box Incident Originator Company (Tier 4)
+    participant "Incident App" as BusinessApp_Tier_4
+end box
+
+participant EDC
+
+box Customer Company (Tier 3)
+participant "Incident App" as BusinessApp_Tier_3
+
+
+BusinessApp_Tier_4 -> BusinessApp_Tier_3 : notification
+BusinessApp_Tier_4 <-- BusinessApp_Tier_3 : 200 ack
+note left
+{
+    "header": {
+        "notificationId": "e0f8c1b9-ba5a-4b7e-a431-b2d03d129705",
+         ...
+    },
+    "content": {
+        "incidentBPNSs" : ["BPNS123456"]
+        "concernedCatenaXIds" : [ {
+            globalAssetId : <globalAssetId>,
+            hopsCount: <hopsCount>,
+            bpns: [
+                <bpns>
+            ]
+         }
+    }
+}
+end note
+
+    BusinessApp_Tier_3 --> IRS_Tier_3 :  POST /irs/orders/
+    note left
+        {
+          "aspects": [
+            "PartAsPlanned"
+          ],
+          "bomLifecycle": "asPlannned",
+          "collectAspects": true,
+          "depth": 1,
+          "direction": "upwards",
+          "keys": [
+            {
+              "bpn": "BPNL0123456789XX",
+              "globalAssetId": "urn:uuid:6c311d29-5753-46d4-b32c-19b918ea93b0"
+            }
+          ],
+          "timeout": 43200
+        }
+
+    end note
+    BusinessApp_Tier_3 --> IRS_Tier_3 :  GET /irs/orders/{orderId}
+    ref over IRS_Tier_3
+        process batch order request
+    end ref
+    BusinessApp_Tier_3 <-- IRS_Tier_3 : Return job with item graph for the requested id.
+
+
+
+@enduml

docs/src/uml-diagrams/irs-recursive/ess-bottom-up/sequence/ess-bottom-up-sequence-originator-highlevel.puml

@@ -0,0 +1,145 @@
+@startuml
+skinparam monochrome true
+skinparam shadowing false
+skinparam defaultFontName "Architects daughter"
+
+autonumber "<b>[000]"
+
+actor "Client" as User
+
+participant "Client App (Script)" as ClientApp
+
+box Incident Company (Tier 4)
+participant "Digital Twin Registry" as dDTR_Tier_N
+participant "IRS Incident" as IRS_Tier_N
+end box
+
+participant EDC
+
+box Tier3 Company
+participant "Digital Twin Registry" as dDTR_Tier_3
+participant "SubmodelServer" as SubmodelServer_Tier_3
+participant "IRS Customer Tier 3" as IRS_Tier_3
+end box
+
+
+User -> ClientApp : Incident notification (incidentID)
+activate ClientApp
+
+ClientApp -> dDTR_Tier_N : getAAShells ()
+ref over dDTR_Tier_N
+    GET AAShells from dDTR for own BPNL
+end ref
+ClientApp <-- dDTR_Tier_N : Array [{AAS shells}]
+
+ClientApp -> ClientApp : Extract globalAssetId
+
+
+ClientApp <-- dDTR_Tier_N : return array of {aasIdentifier}
+
+ClientApp -> ClientApp :  filter aas for submodelDescriptor  (asPlanned)
+        note left
+               semanticId/
+                    ["type"="ExternalReference"]/
+                        keys["type"="GlobalReference"]/
+                            ["value".contains("SingleLevelBomAsPlanned")]
+               SingleLevelBomAsPlanned (only downwards supported!!)
+        end note
+
+opt aas is asPlanned
+
+     ClientApp -> ClientApp : add aas to aasResultSet
+     note right
+                 Requesting all twins for a given "bomLifecycle"
+     end note
+
+end opt
+
+ClientApp <-- ClientApp : aasResultSet
+
+
+ClientApp -> IRS_Tier_N : /ess/customers/investigations/orders
+    note left
+        Investigation of customers who must be notified about an incident.
+        parameters:
+            {
+            keys [
+                bpn : <bpnl>
+                globalAssetIds : <globalAssetIds>
+            ]
+            bomLifecycle : asPlanned,
+            direction : upwards (SingleLevelUsageAsPlanned),
+            depth : 1,
+            incidentBPNSs [<bpns>,..],
+            filterExpressions :  [
+                        {
+                          validityTimestamp : <validityTimestamp>
+                        },
+                     ]
+            }
+    end note
+
+    IRS_Tier_N -> IRS_Tier_N : Check PartSiteInformationAsPlanned if BPNS matches
+    note left
+        Check if bpns contains any catenaXsiteId  in PartSiteInformationAsPlanned
+    end note
+    opt "!bpns.containsAny(catenaXsiteIds) then"
+        IRS_Tier_N -> IRS_Tier_N : skip twin;
+    end
+
+    ref over dDTR_Tier_N, dDTR_Tier_3, SubmodelServer_Tier_3
+        Determining relationships 1 tier level upwards
+    end ref
+
+    IRS_Tier_N -> IRS_Tier_N : validityPeriodChecker
+    note left
+        validityPeriodCheck: Checks if passed timestamp is in validity period defined with
+        validityPeriod.validFrom and  PartAsPlanned.validityPeriod.validTo
+
+        PartAsPlanned.validityPeriod.validFrom
+        >= validityTimestamp
+        >= PartAsPlanned.validityPeriod.validTo
+    end note
+
+    IRS_Tier_N -> IRS_Tier_N : aggregateBPNLs
+    note left
+        Aggregate bpns numbers for each bpnl
+    end note
+    IRS_Tier_N -> IRS_Tier_N : incrementHopsCount
+        note left
+            increment hopsCount on twin level
+        end note
+
+
+    IRS_Tier_N <-- IRS_Tier_N : [{globalAssetId,businessPartnerNumberLegalEntity, [businessPartnerNumberSite]}]
+
+
+
+
+    ClientApp --> IRS_Tier_N : GET /irs/orders/{orderId}
+    ClientApp <-- IRS_Tier_N : Get a batch order for a given orderId.
+    ClientApp --> IRS_Tier_N : GET /irs/orders/{orderId}/batches/{batchId}
+    ClientApp <-- IRS_Tier_N : Get a batch with a given batchId for a given orderId.
+    ClientApp --> IRS_Tier_N : GET /irs/jobs/{id}
+    ClientApp <-- IRS_Tier_N : Return job with item graph for the requested id.
+    User <-- ClientApp : Return job with item graph for the requested id.
+      note left
+            {
+                customers : [
+                    {
+                        businessPartnerNumberLegalEntity : <bpnl>,
+                        "customerParts" [
+                            {
+                                globalAssetId:   <globalAssetId>,
+                                hopsCount: <hopsCount>,
+                                sites : [
+                                    {<bpns>},
+                                ],
+                             }, ...
+                        ]
+                    },
+                ]
+            }
+        end note
+
+@enduml