diff --git a/docs/src/docs/arc42/runtime-view/ess-top-down/ess-top-down-scenario-1.adoc b/docs/src/docs/arc42/runtime-view/ess-top-down/ess-top-down-scenario-1.adoc new file mode 100644 index 0000000000..2ee41c83f2 --- /dev/null +++ b/docs/src/docs/arc42/runtime-view/ess-top-down/ess-top-down-scenario-1.adoc @@ -0,0 +1,66 @@ += Scenario 1: Register an Ess-Investigation-Order + +This section describes what happens when user creates an ess order. + +== Register an Ess-Investigation-Order + +[plantuml,target=submodel-processing,format=svg] +.... +include::../../../../uml-diagrams/runtime-view/use-case-ess-top-down/3_ess_top_down_sequence-RegisterEssInvestigationOrder.puml[] +.... + +|=== +| Step | Actor | Action | Details + +| [000] +| Client +| Sends a POST request to `/ess/bpn/investigation/orders` +| Includes JSON payload with parameters like "bomLifecycle," "batchSize," "callbackUrl," "incidentBPNSs," "keys," and "timeout." + +| [001] +| IRS +| Initiates initial order processing +| Begins asynchronous processing of ESS process for "incidentBPNSs" and tuples of "globalAssetId" and "BPN." + +| [002] +| IRS +| Registers callback +| Establishes a callback mechanism with the provided callback URL. + +| [003] +| Client +| Receives 201 success response +| Indicates successful registration of the order. + +| [004] +| Client +| Sends a GET request to `/irs/orders/{orderId}` +| Requests information for a specific orderId. + +| [005] +| IRS +| Processes GET request +| Initiates processing of the requested orderId. + +| [006] +| IRS +| Sends a 200 response with order payload +| Returns the details of the processed order. + +| [007] +| Client +| Optionally initiates batch completion +| Completes the batch processing if required. + +| [008] +| Client +| Sends a POST request to `/irs/orders/{orderId}/batches/'{batchId}'` +| Initiates batch processing for a specific orderId and batchId. + +| [009] +| IRS +| Sends BatchShell with jobs +| Returns details of the batch with associated jobs. + +|=== + diff --git a/docs/src/docs/arc42/runtime-view/ess-top-down/ess-top-down-scenario-2.adoc b/docs/src/docs/arc42/runtime-view/ess-top-down/ess-top-down-scenario-2.adoc new file mode 100644 index 0000000000..7f469ac102 --- /dev/null +++ b/docs/src/docs/arc42/runtime-view/ess-top-down/ess-top-down-scenario-2.adoc @@ -0,0 +1,106 @@ += Scenario 1: Register an Ess-Investigation-Job + +This section describes what happens when user creates an ess job. + +== Register an Ess-Investigation Job + +[plantuml,target=submodel-processing,format=svg] +.... +include::../../../../uml-diagrams/runtime-view/use-case-ess-top-down/4_ess_top_down_sequence_RegisterEssInvestigationJob.puml[] +.... + +|=== +| Step | Actor | Action | Details + +| [000] +| Requestor +| Sends a POST request to `/ess/bpn/investigations` +| Includes JSON payload with parameters such as "bomLifecycle," "callbackUrl," "incidentBpns," and "key" containing "bpn" and "globalAssetId." + +| [001] +| IRS +| Registers an IRS ess incident job +| Initiates the registration of an IRS ess incident job based on the received request. + +| [002] +| IRS, DiscoveryFinder, EDCDiscoveryService, EDC, dDTR +| Look up shells for the given globalAssetId +| Conducts a lookup and retrieves AAS (Asset Administration Shell) for the specified globalAssetId. + +| [003] +| IRS -> SubmodelServer +| Sends a GET request for SingleLevelBomAsPlanned +| Initiates a request to the SubmodelServer for the SingleLevelBomAsPlanned. + +| [004] +| SubmodelServer -> IRS +| Receives SingleLevelBomAsPlanned +| Sends back the SingleLevelBomAsPlanned data to the IRS. + +| [005] +| IRS +| Extracts childCXIds from SingleLevelBomAsPlanned +| Processes and extracts childCXIds from the received SingleLevelBomAsPlanned. + +| [006] +| Loop (for each childCXId) +| IRS, DiscoveryFinder, EDCDiscoveryService +| Get EDC endpoint for Tier1, Retrieves the EDC endpoint for Tier1 based on the childCXId. + +| [007] +| IRS, EDCTier1, dDTRTier1 +| Look up shells for the given globalAssetId +| Conducts a lookup and retrieves AAS for the specified globalAssetId in Tier1. + +| [008] +| IRS -> SubmodelServer +| Sends a request to get PartAsPlanned +| Initiates a request to the SubmodelServer to get PartAsPlanned. + +| [009] +| SubmodelServer <- IRS +| Receives PartAsPlanned +| Gets PartAsPlanned data from the SubmodelServer. + +| [010] +| IRS +| Validity Check on PartAsPlanned validityPeriod +| Checks the validity period of PartAsPlanned. + +| [011] +| IRS -> SubmodelServer +| Sends a GET request for PartSiteInformationAsPlanned +| Requests PartSiteInformationAsPlanned from the SubmodelServer. + +| [012] +| IRS -> IRS +| Extracts catenaXsiteId from PartSiteInformationAsPlanned +| Processes and extracts catenaXsiteId from PartSiteInformationAsPlanned. + +| [013] +| IRS +| Matches "incidentBpns" and catenaXsiteId +| Checks for a match between "incidentBpns" and catenaXsiteId. + +| [014] +| IRS +| Detects the supplyChainImpacted on the first tier level +| Identifies the supply chain impacted on the first tier level and provides information. + +| [015] +| Requestor <- IRS +| Responds part-chain infected +| Receives the response indicating the part-chain infection. + +| [016] +| IRS +| Continues the loop +| Continues the loop for the remaining childCXIds. + +| [017] +| Loop (end) +| IRS +| Loop completion +| Completes the loop for all childCXIds. + +|=== diff --git a/docs/src/docs/arc42/runtime-view/ess-top-down/ess-top-down.adoc b/docs/src/docs/arc42/runtime-view/ess-top-down/ess-top-down.adoc new file mode 100644 index 0000000000..b7929f23bf --- /dev/null +++ b/docs/src/docs/arc42/runtime-view/ess-top-down/ess-top-down.adoc @@ -0,0 +1,138 @@ += Use Case: ESS (Environmental and Social Standards) Top-Down Approach + +With the entry into force of the German Supply Chain Due Diligence Act as from January 1st, 2023, German companies are obliged to implement the corresponding requirements of this law. +In addition, the following European directives on this subject have also been adopted: EU regulation 2018/858. This regulation is legally binding to all EU member states. + +== Specification + +This component enables data providers to provide the BoM as planned aspect models via the Catena-X defined solution stack (i.e. EDC). +The BoM as planned aspect models consists of three aspect models: + +- PartAsPlanned - Masterdata of a Part Type incl. location related data (e.g. production sites) +- SingleLevelBomAsPlanned - The relation to child part types provided by the supplier of the given company +- PartSiteInformationAsPlanned - Relation to Sites in order to resemble the flow of the specific part/material + +== Overall flow + +[plantuml,target=submodel-processing,format=svg] +.... +include::../../../../uml-diagrams/runtime-view/use-case-ess-top-down/0-ess-top-down-sequence.puml[] +.... + +|=== +| Step | Actor | Action | Details + +| *[000]* | IncidentManager | Request ESS Incident investigation | - + +| *[001]* | Inquiring OEM Company | Check direct suppliers | - +| | Inquiring OEM Company | Check BPNS in direct suppliers | - + +| *[002]* | Inquiring OEM Company | Forward incident to Tier N+1 Supplier | - +| *[003]* | Tier N+1 Supplier | Check direct suppliers | - +| | Tier N+1 Supplier | Check BPNS in direct suppliers | - +| | Tier N+1 Supplier | Forward incident to Tier N+n Supplier | - + +| *[004]* | Tier N+n Supplier | Check direct suppliers | - +| | Tier N+n Supplier | Check BPNS in direct suppliers | - +| | Tier N+n Supplier | Return responses (including hops) to Tier N+1 Supplier | ESS supplier response + +| *[005]* | Tier N+1 Supplier | Aggregate results | - +| | Tier N+1 Supplier | Return responses (including hops) to Inquiring OEM Company | ESS supplier response + +| *[006]* | Inquiring OEM Company | Aggregate results | - +| | Inquiring OEM Company | Check subgraph infection on first tier level | - + +| *[007]* | IncidentManager | Receive incident report from Inquiring OEM Company | - +|=== + +Note: ESS supplier responses are involved in each step of the process. + +== Flow on company level + +[plantuml,target=submodel-processing,format=svg] +.... +include::../../../../uml-diagrams/runtime-view/use-case-ess-top-down/1_ess-top-down-sequence-highlevel.puml[] +.... + +=== Step 0: Process initiation: + +The process is initiated by an ESS incident, that is received by (or created within) the inquiring company. +This ESS incident acts as the root incident for the overall process The incident contains a company name (incl. address) and a valid BPN exists for that company. +The BPN (a BPNL or BPNS) can be looked up in BPDM. + +=== Step 1: Check direct suppliers + +The inquiring company checks, if the company of the incident is a direct supplier of them. +In order to perform this check, the following data must be available in the inquiring company: + +- Full list of direct suppliers +- Full list of parts supplied by those direct suppliers + +In case the company of the incident is a direct supplier of the inquiring company, the process ends. +In case the company of the incident is not a direct supplier of the inquiring company, Step 2 is executed. + +=== Step 2: Forward Incident + +The incident is forwarded to all direct suppliers. +Each direct supplier is sent a "personalized" request to evaluate, if the inquiring company is impacted by the incident. +The incident is enhanced with additional data by the inquiring company: + +- List of parts, that are supplied to the inquiring company by their direct supplier. + +Each direct supplier executes Step 1. + +=== Step 3: Gather Responses + +The inquiring company collects the (asynchronous) responses. +The response of each direct supplier may contain the following results; + +- YES → The company of the incident was found in the supply chain of the given list of parts +- NO → The company of the incident was not found in the supply chain of the given list of parts +- UNKNOWN → The query timed out or some other error occurred + +In case at least one "YES" is received, the process step 3 ends + +== Application Functionality Overview + +== Register an Ess-Investigation-Order + +[plantuml,target=submodel-processing,format=svg] +.... +include::../../../../uml-diagrams/runtime-view/use-case-ess-top-down/1_ess-top-down-sequence-highlevel.puml[] +.... + +== 1. Client Request + +The _Client App (Script)_ initiates a request to the IRS (Item Relationship Service) by sending a GET request for shell lookup based on a specific BPN (Business Partner Number). + +== 2. Shell Lookup + +IRS, along with other services like DiscoveryFinder, EDCDiscoveryService, and Digital Twin Registry, collaborates to look up shells for the given BPN, returning an array of AAS identifiers. + +== 3. AAS Descriptor Retrieval + +For each AAS identifier, the client requests the IRS for the corresponding shell descriptors, adding them to a collection. + +== 4. Filtering AAS + +The _Client App (Script)_ filters the AAS collection for SubmodelDescriptors marked _asPlanned_, based on certain criteria. + +== 5. Incident Registration + +The client then initiates an IRS incident registration by sending a POST request with specific parameters, including bomLifecycle and callback URL. + +== 6. Incident Handling Loop + +IRS proceeds to handle the incident by iterating through AAS identifiers, extracting child CXIds, and performing checks on associated data. + +== 7. Data Validation + +The system checks the validity period of the received data and, if valid, proceeds to extract additional information. + +== 8. Incident Response + +If certain conditions are met (e.g., incidentBpns contain catenaXsiteId), the system responds to the client indicating a part-chain infection. + +== 9. Notification Handling + +Otherwise, the system sends an ess-request notification to the next tier level IRS, and after processing the request on the next tier level, receives an ess-response notification. diff --git a/docs/src/docs/arc42/runtime-view/full.adoc b/docs/src/docs/arc42/runtime-view/full.adoc index 44ffbc1d9a..678450e74d 100644 --- a/docs/src/docs/arc42/runtime-view/full.adoc +++ b/docs/src/docs/arc42/runtime-view/full.adoc @@ -1,10 +1,25 @@ = Runtime view -This section covers the main processes of the IRS and explains how data is transfered and processed when a job is executed. -include::overall.adoc[leveloffset=+1] -include::scenario-1.adoc[leveloffset=+1] -include::scenario-2.adoc[leveloffset=+1] -include::scenario-3.adoc[leveloffset=+1] -include::scenario-4.adoc[leveloffset=+1] +== IRS Iterative + +This section covers the main processes of the IRS and explains how data is transferred and processed when a job is executed. + +include::irs-iterative/irs-iterative.adoc[leveloffset=+1] +include::irs-iterative/scenario-1.adoc[leveloffset=+1] +include::irs-iterative/scenario-2.adoc[leveloffset=+1] +include::irs-iterative/scenario-3.adoc[leveloffset=+1] +include::irs-iterative/scenario-4.adoc[leveloffset=+1] + +== IRS Recursive + +This section covers the main processes of the IRS in a recursive scenario in a network. +This recursive scenario is illustrated using the various use cases realized in the scenario. + +=== Use Case: ESS (Environmental and Social Standards) Top-Down approach + +include::ess-top-down/ess-top-down.adoc[leveloffset=+1] +include::ess-top-down/ess-top-down-scenario-1.adoc[leveloffset=+1] +include::ess-top-down/ess-top-down-scenario-2.adoc[leveloffset=+1] +include::ess-top-down/ess-top-down-scenario-3.adoc[leveloffset=+1] diff --git a/docs/src/docs/arc42/runtime-view/index.adoc b/docs/src/docs/arc42/runtime-view/index.adoc index a6a26010dd..09f232725a 100644 --- a/docs/src/docs/arc42/runtime-view/index.adoc +++ b/docs/src/docs/arc42/runtime-view/index.adoc @@ -4,8 +4,25 @@ This section covers the main processes of the IRS and explains how data is trans Please see the subpages for the relevant scenarios: -- xref:overall.adoc[Overall] -- xref:scenario-1.adoc[Scenario 1: Create Job] -- xref:scenario-2.adoc[Scenario 2: Job Execution] -- xref:scenario-3.adoc[Scenario 3: Request for JobResponse] -- xref:scenario-4.adoc[Scenario 4: Cancel job execution] +== IRS Iterative + +- xref:irs-iterative/irs-iterative.adoc[Overall] +- xref:irs-iterative/scenario-1.adoc[Scenario 1: Create Job] +- xref:irs-iterative/scenario-2.adoc[Scenario 2: Job Execution] +- xref:irs-iterative/scenario-3.adoc[Scenario 3: Request for JobResponse] +- xref:irs-iterative/scenario-4.adoc[Scenario 4: Cancel job execution] + + + +== IRS Recursive + +This section covers the main processes of the IRS in a recursive scenario in a network. +This recursive scenario is illustrated using the various use cases realized in the scenario. + +=== Use Case: ESS (Environmental and Social Standards) Top-Down approach + +include::ess-top-down/ess-top-down.adoc[leveloffset=+1] + + + + diff --git a/docs/src/docs/arc42/runtime-view/overall.adoc b/docs/src/docs/arc42/runtime-view/irs-iterative/irs-iterative.adoc similarity index 57% rename from docs/src/docs/arc42/runtime-view/overall.adoc rename to docs/src/docs/arc42/runtime-view/irs-iterative/irs-iterative.adoc index 1b2ac47691..5b21ab0bb7 100644 --- a/docs/src/docs/arc42/runtime-view/overall.adoc +++ b/docs/src/docs/arc42/runtime-view/irs-iterative/irs-iterative.adoc @@ -1,10 +1,10 @@ -= Overall += IRS iterative -This section describes the overall flow of the IRS +This section describes the iterative flow of the IRS [plantuml, target=overall, format=svg] .... -include::../../../uml-diagrams/runtime-view/api-call-asynchrous-sequence.puml[] +include::../../../../uml-diagrams/runtime-view/api-call-asynchrous-sequence.puml[] .... == Submodel @@ -13,7 +13,7 @@ This section describes how the IRS fetches submodel payload. [plantuml, target=submodel-processing, format=svg] .... -include::../../../uml-diagrams/runtime-view/aas-shell-and submodel-processing.puml[] +include::../../../../uml-diagrams/runtime-view/aas-shell-and submodel-processing.puml[] .... == Job orchestration flow @@ -22,7 +22,7 @@ This section describes the job orchestration in IRS. [plantuml, target=job-orchestration, format=svg] .... -include::../../../uml-diagrams/runtime-view/job-orchestration-sequence.puml[] +include::../../../../uml-diagrams/runtime-view/job-orchestration-sequence.puml[] .... == Policy store flow @@ -31,7 +31,7 @@ This section describes the policy store in IRS. [plantuml, target=policy-store, format=svg] .... -include::../../../uml-diagrams/policy-store/policy-storage-processing.puml[] +include::../../../../uml-diagrams/policy-store/policy-storage-processing.puml[] .... == Policy check procedure @@ -40,5 +40,5 @@ This section describes the way IRS is validating policies found in assets. [plantuml, target=policy-check, format=svg] .... -include::../../../uml-diagrams/policy-store/policy-validation-processing.puml[] +include::../../../../uml-diagrams/policy-store/policy-validation-processing.puml[] .... diff --git a/docs/src/docs/arc42/runtime-view/scenario-1.adoc b/docs/src/docs/arc42/runtime-view/irs-iterative/scenario-1.adoc similarity index 92% rename from docs/src/docs/arc42/runtime-view/scenario-1.adoc rename to docs/src/docs/arc42/runtime-view/irs-iterative/scenario-1.adoc index eedb62615b..5a485717e6 100644 --- a/docs/src/docs/arc42/runtime-view/scenario-1.adoc +++ b/docs/src/docs/arc42/runtime-view/irs-iterative/scenario-1.adoc @@ -4,7 +4,7 @@ This section describes what happens when user creates a new job. [plantuml, target=create-job, format=svg] .... -include::../../../uml-diagrams/runtime-view/create-job.puml[] +include::../../../../uml-diagrams/runtime-view/create-job.puml[] .... == Overview diff --git a/docs/src/docs/arc42/runtime-view/scenario-2.adoc b/docs/src/docs/arc42/runtime-view/irs-iterative/scenario-2.adoc similarity index 94% rename from docs/src/docs/arc42/runtime-view/scenario-2.adoc rename to docs/src/docs/arc42/runtime-view/irs-iterative/scenario-2.adoc index a6e5e30688..07164adb6a 100644 --- a/docs/src/docs/arc42/runtime-view/scenario-2.adoc +++ b/docs/src/docs/arc42/runtime-view/irs-iterative/scenario-2.adoc @@ -4,7 +4,7 @@ This section describes how a job is asynchronously executed inside the IRS. [plantuml, target=execute-job, format=svg] .... -include::../../../uml-diagrams/runtime-view/job-execution.puml[] +include::../../../../uml-diagrams/runtime-view/job-execution.puml[] .... diff --git a/docs/src/docs/arc42/runtime-view/scenario-3.adoc b/docs/src/docs/arc42/runtime-view/irs-iterative/scenario-3.adoc similarity index 88% rename from docs/src/docs/arc42/runtime-view/scenario-3.adoc rename to docs/src/docs/arc42/runtime-view/irs-iterative/scenario-3.adoc index 35a226f811..54214945b7 100644 --- a/docs/src/docs/arc42/runtime-view/scenario-3.adoc +++ b/docs/src/docs/arc42/runtime-view/irs-iterative/scenario-3.adoc @@ -2,7 +2,7 @@ [plantuml, target=request-job, format=svg] .... -include::../../../uml-diagrams/runtime-view/request-job-details.puml[] +include::../../../../uml-diagrams/runtime-view/request-job-details.puml[] .... == Overview diff --git a/docs/src/docs/arc42/runtime-view/scenario-4.adoc b/docs/src/docs/arc42/runtime-view/irs-iterative/scenario-4.adoc similarity index 86% rename from docs/src/docs/arc42/runtime-view/scenario-4.adoc rename to docs/src/docs/arc42/runtime-view/irs-iterative/scenario-4.adoc index 055a2626bc..6a30ab6d2a 100644 --- a/docs/src/docs/arc42/runtime-view/scenario-4.adoc +++ b/docs/src/docs/arc42/runtime-view/irs-iterative/scenario-4.adoc @@ -2,7 +2,7 @@ [plantuml, target=cancel-job, format=svg] .... -include::../../../uml-diagrams/runtime-view/cancel-job.puml[] +include::../../../../uml-diagrams/runtime-view/cancel-job.puml[] .... == Overview diff --git a/docs/src/uml-diagrams/api-specification/irs-api-interaction.puml b/docs/src/uml-diagrams/api-specification/irs-api-interaction.puml index bfa206d199..3784408199 100644 --- a/docs/src/uml-diagrams/api-specification/irs-api-interaction.puml +++ b/docs/src/uml-diagrams/api-specification/irs-api-interaction.puml @@ -1,6 +1,8 @@ @startuml skinparam monochrome true skinparam shadowing false +skinparam linetype ortho +skinparam defaultFontName "Architects daughter" actor APIConsumer activate APIConsumer diff --git a/docs/src/uml-diagrams/building-block-view/building-block-view.puml b/docs/src/uml-diagrams/building-block-view/building-block-view.puml index 3122db1eb0..2016ccfe8b 100644 --- a/docs/src/uml-diagrams/building-block-view/building-block-view.puml +++ b/docs/src/uml-diagrams/building-block-view/building-block-view.puml @@ -33,14 +33,14 @@ component [**Digital Twin Registry**] <> as DTR component [**EDC**] <> as EDC actor IrsApiConsumer IrsController -up- API_PORT -PolicyStoreController -up- API_PORT +PolicyStoreController -down- API_PORT IrsApiConsumer -(0- API_PORT TransferProcessManagement --- AAS_PORT TransferProcessManagement --- EDC_PORT -AAS_PORT -(0 DTR -EDC_PORT -(0 EDC +AAS_PORT --right-(0 DTR +EDC_PORT --right-(0 EDC database "BlobStore" as BlobStore StoreInterface -down- BlobStore diff --git a/docs/src/uml-diagrams/irs-recursive/ess-top-down/sequence/1_ess-top-down-sequence-Get_AAS_Assets_by_BPN.puml b/docs/src/uml-diagrams/irs-recursive/ess-top-down/sequence/1_ess-top-down-sequence-Get_AAS_Assets_by_BPN.puml index 239fbb1f54..50252a7000 100644 --- a/docs/src/uml-diagrams/irs-recursive/ess-top-down/sequence/1_ess-top-down-sequence-Get_AAS_Assets_by_BPN.puml +++ b/docs/src/uml-diagrams/irs-recursive/ess-top-down/sequence/1_ess-top-down-sequence-Get_AAS_Assets_by_BPN.puml @@ -8,7 +8,6 @@ autonumber "[000]" participant "Client App (Script)" as Client box "OEM" #LightGrey - participant IRS as IRS participant decentralDigitalTwinRegistry as dDTR end box diff --git a/docs/src/uml-diagrams/irs-recursive/ess-top-down/sequence/ess-top-down-sequence-highlevel.puml b/docs/src/uml-diagrams/irs-recursive/ess-top-down/sequence/ess-top-down-sequence-highlevel.puml deleted file mode 100644 index b9625c906f..0000000000 --- a/docs/src/uml-diagrams/irs-recursive/ess-top-down/sequence/ess-top-down-sequence-highlevel.puml +++ /dev/null @@ -1,138 +0,0 @@ -@startuml -skinparam monochrome true -skinparam shadowing false -skinparam defaultFontName "Architects daughter" - -autonumber "[000]" - -actor "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 : [hidden] GET /irs/proxy/registry/lookup/shells{bpn} {bpnl="BPNL0123456789XX"} - - ref over IRS, DiscoveryFinder, EDCDiscoveryService, EDC, dDTR - lookup/shells for given BPN - :return array of {aasIdentifier} - end - Client <-- IRS :return array of aasIdentifier - - - loop array of aasIdentifier - Client -> IRS : [hidden] GET /irs/proxy/registry/shell-descriptors/{aasIdentifier} - ref over IRS, DiscoveryFinder, EDCDiscoveryService, EDC, dDTR - registry/shell-descriptors/{aasIdentifier} for given BPN - :add {aasIdentifier} to collection - end - IRS -> IRS : :return array of {aasIdentifier} -end loop - - Client <-- IRS : return array of {aasIdentifier} - - Client -> Client : filter aas for **SubmodelDescriptor** (asPlanned) - - opt aas is asPlanned - note left - semanticId/ - ["type"="ExternalReference"]/ - keys["type"="GlobalReference"]/ - ["value".contains("SingleLevelBomAsPlanned")] - SingleLevelBomAsPlanned (only downwards) - end note - Client -> Client : add aas to aasResultSet - note left - Requesting all twins for a given "bomLifecycle" - end note - else - break - end opt - - Client <-- Client : aasResultSet - -Client -> IRS : POST /ess/bpn/investigations -note left - { - "bomLifecycle": "asPlanned", - "callbackUrl": "https://hostname.com/callback?jobId={jobId}", - "incidentBpns": [], - "key": {"bpn", "globalAssetId"} - } -end note -IRS -> IRS : register an IRS ess incident job - -ref over IRS, DiscoveryFinder, EDCDiscoveryService, EDC, dDTR - lookup/shells for given globalAssetId - :return aasIdentifier - /registry/shell-descriptors/{aasIdentifier} - :return AAS for aasIdentifier -end -IRS -> SubmodelServer : GET SingleLevelBomAsPlanned -IRS <-- SubmodelServer : Receiver SingleLevelBomAsPlanned -IRS --> IRS : Extract childCXIds from SingleLevelBomAsPlanned - -loop childCXIds - - ref over IRS, DiscoveryFinder, EDCDiscoveryService - get EDC endpoint for Tier1 - end - ref over IRS, EDCTier1, dDTRTier1 - lookup/shells for given globalAssetId - :return AAS for globalAssetId - end - IRS -> SubmodelServer : Get PartAsPlanned - IRS <-- SubmodelServer : Receive PartAsPlanned - IRS -> IRS: Validity Check on PartAsPlanned validityPeriod - - opt validFrom >= Timstamp.UTC.now <= validTo - IRS -> SubmodelServer : GET PartSiteInformationAsPlanned - IRS -> IRS : Extract **catenaXsiteId** from PartSiteInformationAsPlanned - - alt "incidentBpns".contains(catenaXsiteId) - Client <-- IRS: Respond part-chain infected - note right - { - "header": { - "notificationId": "e0f8...", - "senderBpn": "BPNL0..S", - "recipientBpn": "BPNL..H", - ... - }, - "content": { - "result" : "yes" - } - } - end note - else - ref over IRS, IRSTier1 - : Send ess-request notification - end ref - IRSTier1 -> IRSTier1 : Receiver ess-request notification - - IRS <-- IRSTier1: Response ess-response notification - end - else - - IRS -> IRS: continue loop - end -end loop - -@enduml \ No newline at end of file diff --git a/docs/src/uml-diagrams/irs-recursive/esr-certificate-sequence-irs.puml b/docs/src/uml-diagrams/irs-recursive/use-case-esr-certificate/esr-certificate-sequence-irs.puml similarity index 100% rename from docs/src/uml-diagrams/irs-recursive/esr-certificate-sequence-irs.puml rename to docs/src/uml-diagrams/irs-recursive/use-case-esr-certificate/esr-certificate-sequence-irs.puml diff --git a/docs/src/uml-diagrams/irs-recursive/esr-certificate-sequence-supplyon.puml b/docs/src/uml-diagrams/irs-recursive/use-case-esr-certificate/esr-certificate-sequence-supplyon.puml similarity index 100% rename from docs/src/uml-diagrams/irs-recursive/esr-certificate-sequence-supplyon.puml rename to docs/src/uml-diagrams/irs-recursive/use-case-esr-certificate/esr-certificate-sequence-supplyon.puml diff --git a/docs/src/uml-diagrams/irs-recursive/esr-certificate-sequence-traverse_childs.puml b/docs/src/uml-diagrams/irs-recursive/use-case-esr-certificate/esr-certificate-sequence-traverse_childs.puml similarity index 100% rename from docs/src/uml-diagrams/irs-recursive/esr-certificate-sequence-traverse_childs.puml rename to docs/src/uml-diagrams/irs-recursive/use-case-esr-certificate/esr-certificate-sequence-traverse_childs.puml diff --git a/docs/src/uml-diagrams/irs-recursive/esr-certificate-sequence.puml b/docs/src/uml-diagrams/irs-recursive/use-case-esr-certificate/esr-certificate-sequence.puml similarity index 100% rename from docs/src/uml-diagrams/irs-recursive/esr-certificate-sequence.puml rename to docs/src/uml-diagrams/irs-recursive/use-case-esr-certificate/esr-certificate-sequence.puml diff --git a/docs/src/uml-diagrams/irs-recursive/esr-certificate-state-machine.puml b/docs/src/uml-diagrams/irs-recursive/use-case-esr-certificate/esr-certificate-state-machine.puml similarity index 100% rename from docs/src/uml-diagrams/irs-recursive/esr-certificate-state-machine.puml rename to docs/src/uml-diagrams/irs-recursive/use-case-esr-certificate/esr-certificate-state-machine.puml diff --git a/docs/src/uml-diagrams/irs-recursive/esr-certificates-activity.puml b/docs/src/uml-diagrams/irs-recursive/use-case-esr-certificate/esr-certificates-activity.puml similarity index 100% rename from docs/src/uml-diagrams/irs-recursive/esr-certificates-activity.puml rename to docs/src/uml-diagrams/irs-recursive/use-case-esr-certificate/esr-certificates-activity.puml diff --git a/docs/src/uml-diagrams/runtime-view/use-case-ess-top-down/0-ess-top-down-sequence.puml b/docs/src/uml-diagrams/runtime-view/use-case-ess-top-down/0-ess-top-down-sequence.puml new file mode 100644 index 0000000000..ceee36e15a --- /dev/null +++ b/docs/src/uml-diagrams/runtime-view/use-case-ess-top-down/0-ess-top-down-sequence.puml @@ -0,0 +1,57 @@ +@startuml +skinparam monochrome true +skinparam shadowing false +skinparam defaultFontName "Architects daughter" + +autonumber "[000]" + +actor IncidentManager +participant "Inquiring OEM Company" as OEM +participant "Tier N+1 Supplier" as Tier_1 +participant "Tier N+n Supplier" as Tier_2 + +IncidentManager -> OEM: request ESS Incident investigation + + + activate OEM + OEM -> OEM: check direct suppliers + OEM -> OEM: check BPNS in direct suppliers + OEM -> Tier_1: forward incident + deactivate OEM + activate Tier_1 + + + + activate Tier_1 + Tier_1 -> Tier_1: check direct suppliers + Tier_1 -> Tier_1: check BPNS in direct suppliers + Tier_1 --> Tier_2: forward incident + deactivate Tier_1 + + activate Tier_2 + Tier_2 -> Tier_2: check direct suppliers + Tier_2 -> Tier_2: Check BPNS in direct suppliers + Tier_2 --> Tier_1: return responses (inc. hops) + note left + ESS supplier response + end note + deactivate Tier_2 + + + activate Tier_1 + Tier_1 -> Tier_1 : aggregate results + + + Tier_1 --> OEM: return responses (inc. hops) + note left + ESS supplier response + end note + deactivate Tier_1 + + activate OEM + OEM -> OEM : aggregate results + OEM -> OEM : check subgraph infected on first tier level + +IncidentManager <- OEM: return incident report + +@enduml diff --git a/docs/src/uml-diagrams/runtime-view/use-case-ess-top-down/1_ess-top-down-sequence-highlevel.puml b/docs/src/uml-diagrams/runtime-view/use-case-ess-top-down/1_ess-top-down-sequence-highlevel.puml new file mode 100644 index 0000000000..8749a6c149 --- /dev/null +++ b/docs/src/uml-diagrams/runtime-view/use-case-ess-top-down/1_ess-top-down-sequence-highlevel.puml @@ -0,0 +1,134 @@ +@startuml +skinparam monochrome true +skinparam shadowing false +skinparam defaultFontName "Architects daughter" + +autonumber "[000]" + +actor "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 : GET /irs/proxy/registry/lookup/shells{bpn} {bpnl="BPNL0123456789XX"} + +ref over IRS, DiscoveryFinder, EDCDiscoveryService, EDC, dDTR + lookup/shells for given BPN + :return array of {aasIdentifier} +end +Client <-- IRS :return array of aasIdentifier + +loop array of aasIdentifier + Client -> IRS : GET /irs/proxy/registry/shell-descriptors/{aasIdentifier} + ref over IRS, DiscoveryFinder, EDCDiscoveryService, EDC, dDTR + registry/shell-descriptors/{aasIdentifier} for given BPN + :add {aasIdentifier} to collection + end + IRS -> IRS : :return array of {aasIdentifier} +end loop + +Client <-- IRS : return array of {aasIdentifier} + +Client -> Client : filter aas for **SubmodelDescriptor** (asPlanned) + +opt aas is asPlanned + note left + semanticId/ + ["type"="ExternalReference"]/ + keys["type"="GlobalReference"]/ + ["value".contains("SingleLevelBomAsPlanned")] + SingleLevelBomAsPlanned (only downwards) + end note + Client -> Client : add aas to aasResultSet + note left + Requesting all twins for a given "bomLifecycle" + end note + +end opt + +Client <-- Client : aasResultSet + +Client -> IRS : POST /ess/bpn/investigations +note left + { + "bomLifecycle": "asPlanned", + "callbackUrl": "https://hostname.com/callback?jobId={jobId}", + "incidentBpns": [], + "key": {"bpn", "globalAssetId"} + } +end note +IRS -> IRS : register an IRS ess incident job + +ref over IRS, DiscoveryFinder, EDCDiscoveryService, EDC, dDTR + lookup/shells for given globalAssetId + :return aasIdentifier + /registry/shell-descriptors/{aasIdentifier} + :return AAS for aasIdentifier +end +IRS -> SubmodelServer : GET SingleLevelBomAsPlanned +IRS <-- SubmodelServer : Receiver SingleLevelBomAsPlanned +IRS --> IRS : Extract childCXIds from SingleLevelBomAsPlanned + +loop childCXIds + +ref over IRS, DiscoveryFinder, EDCDiscoveryService + get EDC endpoint for Tier1 +end +ref over IRS, EDCTier1, dDTRTier1 + lookup/shells for given globalAssetId + :return AAS for globalAssetId +end +IRS -> SubmodelServer : Get PartAsPlanned +IRS <-- SubmodelServer : Receive PartAsPlanned +IRS -> IRS: Validity Check on PartAsPlanned validityPeriod + +opt validFrom >= Timstamp.UTC.now <= validTo + IRS -> SubmodelServer : GET PartSiteInformationAsPlanned + IRS -> IRS : Extract **catenaXsiteId** from PartSiteInformationAsPlanned + + alt "incidentBpns".contains(catenaXsiteId) + Client <-- IRS: Respond part-chain infected + note right + { + "header": { + "notificationId": "e0f8...", + "senderBpn": "BPNL0..S", + "recipientBpn": "BPNL..H", + ... + }, + "content": { + "result" : "yes" + } + } + end note + else + ref over IRS, IRSTier1 + : Send ess-request notification + end ref + IRS <-- IRSTier1: Return ess-response notification + IRS --> IRS : Aggregates + end +else + IRS -> IRS: continue loop +end +end loop + +@enduml diff --git a/docs/src/uml-diagrams/irs-recursive/ess-top-down/sequence/3_ess_top_down_sequence-RegisterEssInvestigationOrder.puml b/docs/src/uml-diagrams/runtime-view/use-case-ess-top-down/3_ess_top_down_sequence-RegisterEssInvestigationOrder.puml similarity index 52% rename from docs/src/uml-diagrams/irs-recursive/ess-top-down/sequence/3_ess_top_down_sequence-RegisterEssInvestigationOrder.puml rename to docs/src/uml-diagrams/runtime-view/use-case-ess-top-down/3_ess_top_down_sequence-RegisterEssInvestigationOrder.puml index 94abdb8eff..293fb9aa23 100644 --- a/docs/src/uml-diagrams/irs-recursive/ess-top-down/sequence/3_ess_top_down_sequence-RegisterEssInvestigationOrder.puml +++ b/docs/src/uml-diagrams/runtime-view/use-case-ess-top-down/3_ess_top_down_sequence-RegisterEssInvestigationOrder.puml @@ -14,14 +14,13 @@ box "OEM" #LightGrey 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 + participant IRS as IRSTier1 + participant SubmodelServer as SubmodelServerTier1 + participant dDTR as dDTRTier1 + participant EDC as EDCConsumerTier1 #99FF99 end box box SharedServices @@ -32,12 +31,10 @@ 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" - ], + "bomLifecycle": "asPlanned", + "batchSize": 20, + "callbackUrl": "https://hostname.com/callback?orderId={orderId}&batchId={batchId}", + "incidentBPNSs": ["BPNS666666666666","BPNS666666666667"], "keys": [ { "bpn": "BPNL0123456789XX", @@ -51,20 +48,21 @@ note left "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 : initial order processing +ref over IRS, EDC, EDCTier1, SubmodelServerTier1, dDTRTier1, EDCConsumerTier1, DiscoveryFinder, EDCDiscoveryService + asynchronous 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"} +IRS <-- Client : 201 success +IRS <-- Client : GET /irs/orders/{orderId} +note left + orderId {"6c311d29-5753-46d4-b32c-19b918ea93b0"} +end note +Client <-- IRS : 200 order payload opt batch complete Client <-- IRS : Callback order with orderId completed end opt - Client --> IRS : /irs/orders/{orderId}/batches/{batchId} - Client <-- IRS : BatchShell with jobs - +Client --> IRS : /irs/orders/{orderId}/batches/{batchId} +Client <-- IRS : BatchShell with jobs @enduml diff --git a/docs/src/uml-diagrams/irs-recursive/ess-top-down/sequence/ess-top-down-sequence.puml b/docs/src/uml-diagrams/runtime-view/use-case-ess-top-down/4_ess_top_down_sequence_RegisterEssInvestigationJob.puml similarity index 72% rename from docs/src/uml-diagrams/irs-recursive/ess-top-down/sequence/ess-top-down-sequence.puml rename to docs/src/uml-diagrams/runtime-view/use-case-ess-top-down/4_ess_top_down_sequence_RegisterEssInvestigationJob.puml index c75a61573c..0e394f67d8 100644 --- a/docs/src/uml-diagrams/irs-recursive/ess-top-down/sequence/ess-top-down-sequence.puml +++ b/docs/src/uml-diagrams/runtime-view/use-case-ess-top-down/4_ess_top_down_sequence_RegisterEssInvestigationJob.puml @@ -83,30 +83,39 @@ loop childCXIds IRS -> IRS : Extract **catenaXsiteId** from PartSiteInformationAsPlanned alt Match of "incidentBpns" and catenaXsiteId - IRS -> IRS: + IRS --> IRS: detect the supplyChainImpacted on first tier level + note left + detect which subtree identified by BPN is infected on first tier level. + This information is only present on first tier level. + end note Requestor <-- IRS: Respond part-chain infected note left - { - "header": { - "notificationId": "e0f8c1b9-ba5a-4b7e-a431-b2d03d129705", - "senderBpn": "BPNL00000003BW3S", - "recipientBpn": "BPNL00000003BV4H", - ... - }, - "content": { - "result" : "yes" - } - } + job { + "jobId": "b516599a-9565-45d3-b1e1-792591471aba", + "globalAssetId": "urn:uuid:88f51be1-3771-4335-8b5c-4c5050123123", + "jobState": "COMPLETED", + "exception": null, + "createdOn": "2023-01-19T09:38:58.154121732Z", + "startedOn": "2023-01-19T09:38:58.154307233Z", + } + submodels: [ + { + "supplyChainImpacted": "YES", + "impactedSuppliersOnFirstTier": [ + {, hops}, + ], + } + ] end note else ref over IRS, IRSTier1 - : Send ess-request notification + : Send ess-request notification to next tier level end ref IRSTier1 -> IRSTier1 : Receiver ess-request notification - IRS <-- IRSTier1: Response ess-response notification + IRS <-- IRSTier1: Return ess-response notification end - else - + else IRS -> IRS: continue loop end end loop