Merge pull request eclipse-tractusx#626 from catenax-ng/chore/eclipse…

…-tractusx#204-Runtime-view-adaptions-for-ESS-UseCase

Chore/eclipse-tractusx#204 runtime view adaptions for ess use case

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

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

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.

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]

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]
+
+
+
+