Chore/tri 1519 ess top down use case

docs/src/uml-diagrams/irs-recursive/ess-top-down/activity/1_scenario_ess-top-down-activity.puml

@@ -0,0 +1,155 @@
+@startuml
+skinparam monochrome true
+skinparam shadowing false
+skinparam defaultFontName "Architects daughter"
+title "Scenario 1 : (Investigation for ONE globalAssetId)"
+
+
+| OEM  - IRS |
+start
+:Incident BPNS is identified;
+:Start investigation job in IRS via api call
+**POST /ess/bpn/investigations**;
+note left
+  "bomLifecycle": "asPlanned",
+  "incidentBPNSs": [
+    "BPNS111111111XX"
+  ],
+  "key": {
+    "bpn": "BPNL0123456789XX",
+    "globalAssetId": "urn:uuid:6c311d29-5753-46d4-b32c-19b918ea93b0"
+  }
+}
+end note
+: Request AAS in DT Registry
+ for **globalAssetId**;
+    :Lookup EDC Url for given BPNL in EDC DiscoveryService
+    discoveryServiceLookup getEDCBaseUrl(BPN);
+
+|DTR_Registry|
+    partition "lookup AAS" {
+        : return AAS for globalAssetId;
+    }
+
+| OEM  - IRS |
+: Request submodel for
+**SingleLevelBoMAsPlanned** for AAS;
+note left
+        Traverse PartChain OneLevelDown over
+        **SingleLevelBoMAsPlanned**
+end note
+    :Extract [childItems] from **SingleLevelBoMAsPlanned**;
+    :Extract attributes **businessPartner** for each [childItems];
+    : Request AAS in DT Registry
+        for **childItems CX-ID**
+        lookup/shells/${Identifier};
+|DTR_Registry|
+    partition "lookup AAS" {
+        : return AAS for childCXId;
+    }
+
+| OEM  - IRS |
+    : Request for submodel **PartSiteInformationAsPlanned** referenced in AAS;
+    : Extract **catenaXSiteId** from **PartSiteInformationAsPlanned** ;
+
+    if(incidentBPNSs.contains(**catenaXSiteId**))  then (true)
+        :Prepare response
+        Create Job and ess submodel;
+        note left
+            job {
+             //details
+            }
+            submodels: [
+             {
+                  supplychain_impacted: yes|no|unknown
+                }
+             ]
+        end note
+
+
+    else (false)
+        :Prepare notification
+        **create ess supplier-request**;
+        :Collect and add all childCX_IDs
+        with equals BPN number
+        the notification will be sent to all concernedCatenaXIds;
+        :send notification;
+
+| Tier 1  IRS |
+         partition "Process BPNS incestigtion on tier level" {
+            :receive notification;
+            note left
+                {
+                    "header": {
+                        "notificationId": "e0f8c1b9-ba5a-4b7e-a431-b2d03d129705",
+                        "senderBpn": "BPNL00000003BW3S",
+                        "recipientBpn": "BPNL00000003BV4H",
+                        "senderEdc": "https://edc.company-xyz.io/BPNL00000003BW3S",
+                        "replyAssetId": "ess-response-asset",
+                        "replyAssetSubPath" : "optionalSubPath",
+                        "notificationType": "ess-supplier-request"
+
+                    },
+                    "content": {
+                        "incidentBpn" : "BPNS123456"
+                        "concernedCatenaXIds" : ["CxUUID"]
+                    }
+                }
+             end note
+            :Start investigation job in IRS via api call for each **concernedCatenaXIds**
+             **POST /ess/bpn/investigations**;
+
+            : Request Child assets in **SingleLevelBoMAsPlanned**;
+            : Request Child AAS for [childItems] in **SingleLevelBoMAsPlanned**;
+            : Check if submodel **PartSiteInformationAsPlanned** contains incidentBpn;
+            : Send notification for all [childItems] for each BPNL
+                      **create ess supplier-request**;
+                note left
+                 1. Send notification over EDC Consumer
+                 2. EDC Consumer forwards notification to EDC Provider
+                 3. EDC Provider to SubmodelServer
+
+                end note
+
+            :send notification;
+         }
+|#AntiqueWhite| Tier 2  IRS |
+         partition "Process BPNS incestigtion on next tier level" {
+            :receive notification;
+            :BPNS incident check on 1 level down structure;
+            :send response notification;
+        }
+| Tier 1  IRS |
+        : Receive results;
+
+        :Prepare response
+        Create Job and ess submodel;
+
+         : Send reponse notification
+            **create ess supplier-response**;  ;
+    endif;
+
+| OEM  - IRS |
+    : receive notification;
+ note right
+        {
+            "header": {
+                "notificationId": "e0f8c1b9-ba5a-4b7e-a431-b2d03d129705",
+                ...
+            },
+            "content": {
+                "result" : "yes",
+                "hops" : "<numberOfHopsIntheSupplyChain>"
+            }
+        }
+    end note
+note right
+    job with ess submodel is returned to api caller
+end note
+:create Job and ess submodel
+
+send response to requestor;
+
+stop
+
+@enduml

docs/src/uml-diagrams/irs-recursive/ess-top-down/ess_number_of_hops.puml

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

docs/src/uml-diagrams/irs-recursive/ess-top-down/sequence/1_ess-top-down-sequence-Get_AAS_Assets_by_BPN.puml

@@ -0,0 +1,48 @@
+@startuml
+skinparam monochrome true
+skinparam shadowing false
+skinparam defaultFontName "Architects daughter"
+
+autonumber "<b>[000]"
+
+participant "Client App (Script)" as Client
+
+box "OEM" #LightGrey
+    participant IRS as IRS
+    participant EDC as EDC
+    participant decentralDigitalTwinRegistry as dDTR
+end box
+
+
+box SharedServices #DarkGrey
+    participant DiscoveryFinder as DiscoveryFinder
+    participant EDCDiscoveryService as EDCDiscoveryService
+end box
+
+    Client -> IRS : [hidden] GET /irs/proxy/registry/lookup/shells/{searchBpn}
+    note left
+        request body
+             {providerBpnl="BPNL0123456789XX"};
+             {limit=50}
+    end note
+    IRS -> DiscoveryFinder : POST /api/administration/connectors/discovery/search { "types": [ "bpn" ] }
+    IRS <-- DiscoveryFinder: 200 [array of EDCDiscoveryService urls]
+    loop for each $endpoints
+        IRS -> EDCDiscoveryService : POST /api/administration/connectors/discovery [ "BPNL..." ]
+        IRS <-- EDCDiscoveryService : 200 [array of EDC urls]
+        ref over IRS, EDC
+            1. Request Contract Offer Catalog
+            2. Negotiate Contract negotiation
+            3. Transfer Data
+        end ref
+        IRS -> EDC : GET lookup/shells for given BPN
+        EDC -> dDTR: GET lookup/shells for given BPN
+        EDC <-- dDTR: return 200 [array of {aasIdentifier}
+        IRS <-- dDTR: return 200 [array of {aasIdentifier}
+    end
+     Client <-- IRS : 201 return array[limit] of aasIdentifier
+     note left
+        number of aasIdentifier is limited by given limit
+     end note
+
+@enduml

docs/src/uml-diagrams/irs-recursive/ess-top-down/sequence/2_ess-top-down-sequence-Get_AAS_by_AasIdentifier_Filter_AsPlanned.puml

@@ -0,0 +1,58 @@
+@startuml
+skinparam monochrome true
+skinparam shadowing false
+skinparam defaultFontName "Architects daughter"
+
+autonumber "<b>[000]"
+
+participant "Client App (Script)" as Client
+
+box "OEM" #LightGrey
+    participant IRS as IRS
+    participant SubmodelServer as SubmodelServer
+    participant dDTR as dDTR
+    participant EDC as EDC #99FF99
+end box
+
+
+box SharedServices
+    participant DiscoveryFinder as DiscoveryFinder
+    participant EDCDiscoveryService as EDCDiscoveryService
+end box
+
+
+loop array of aasIdentifier
+    Client -> IRS : [hidden] GET /irs/proxy/registry/shell-descriptors/{aasIdentifier}/{bpn}
+    ref over IRS, DiscoveryFinder, EDCDiscoveryService, EDC, dDTR
+        create collection of {aasIdentifier}
+
+        registry/shell-descriptors/{aasIdentifier} for given BPN
+        collection.add({aasIdentifier})
+    end
+end loop
+
+
+Client <-- IRS : return array of {aasIdentifier}
+
+Client -> Client :  filter aas for submodelDescriptor  (asPlanned)
+        note right
+               semanticId/
+                    ["type"="ExternalReference"]/
+                        keys["type"="GlobalReference"]/
+                            ["value".contains("SingleLevelBomAsPlanned")]
+               SingleLevelBomAsPlanned (only downwards supported!!)
+        end note
+
+opt aas is asPlanned
+
+     Client -> Client : add aas to aasResultSet
+     note right
+                 Requesting all twins for a given "bomLifecycle"
+     end note
+
+end opt
+
+Client <-- Client : aasResultSet
+
+
+@enduml

docs/src/uml-diagrams/irs-recursive/ess-top-down/sequence/3_ess_top_down_sequence-RegisterEssInvestigationOrder.puml

@@ -0,0 +1,70 @@
+@startuml
+skinparam monochrome true
+skinparam shadowing false
+skinparam defaultFontName "Architects daughter"
+
+autonumber "<b>[000]"
+
+participant "Client App (Script)" as Client
+
+box "OEM" #LightGrey
+    participant IRS as IRS
+    participant SubmodelServer as SubmodelServer
+    participant dDTR as dDTR
+    participant EDC as EDC #99FF99
+end box
+
+
+participant EDC as EDCTier1
+
+box "Tier 1"
+     participant IRS as IRSTier1
+     participant SubmodelServer as SubmodelServerTier1
+     participant dDTR as dDTRTier1
+     participant EDC as EDCConsumerTier1 #99FF99
+end box
+
+box SharedServices
+    participant DiscoveryFinder as DiscoveryFinder
+    participant EDCDiscoveryService as EDCDiscoveryService
+end box
+
+Client -> IRS : /ess/bpn/investigation/orders
+note left
+    {
+      "bomLifecycle": "asPlanned","batchSize": 20,
+        "callbackUrl": "https://hostname.com/callback?orderId={orderId}&batchId={batchId}",
+      ...
+      "incidentBPNSs": [
+        "BPNS666666666666","BPNS666666666667"
+      ],
+      "keys": [
+        {
+          "bpn": "BPNL0123456789XX",
+          "globalAssetId": "urn:uuid:6c311d29-5753-46d4-b32c-19b918ea93b0"
+        },
+        {
+          "bpn": "BPNL9876543210XX",
+          "globalAssetId": "urn:uuid:6c311d29-5753-46d4-b32c-19b918ea9333"
+        }
+      ],
+      "timeout": 43200
+    }
+end note
+IRS --> IRS : initale order processing
+    ref over EDC, EDCTier1, SubmodelServerTier1, dDTRTier1, EDCConsumerTier1, DiscoveryFinder, EDCDiscoveryService
+        asyn processing of ess process for incidentBPNSs
+        and tuples of globalAssetid and BPN
+    end ref
+IRS --> IRS : register callback
+IRS <-- IRS : 201 success
+IRS <-- IRS : orderId {"6c311d29-5753-46d4-b32c-19b918ea93b0"}
+Client <-- IRS : 201 orderId {"6c311d29-5753-46d4-b32c-19b918ea93b0"}
+
+opt batch complete
+    Client <-- IRS : Callback order with orderId completed
+end opt
+    Client --> IRS : /irs/orders/{orderId}/batches/{batchId}
+    Client <-- IRS : BatchShell with jobs
+
+@enduml