Merge pull request eclipse-tractusx#669 from catenax-ng/feature/eclip…

…se-tractusx#206-update-ess-documentation

Feature/eclipse-tractusx#206 update ess documentation

DataChainKit.md

@@ -16,14 +16,14 @@ The Item Relationship Service (IRS) is the first reference application of the Da
 
 ### Requirements
 The IRS needs to be deployed with the following components in the same environment: 
-- [Eclipse Dataspace Connector](https://github.com/eclipse-dataspaceconnector/DataSpaceConnector)
+- [Eclipse Dataspace Connector](https://github.com/eclipse-tractusx/tractusx-edc)
 
-The Service interacts with the Catena-X [Digital Twin Registry](https://catena-x.net/en/angebote/digitaler-zwilling) and is built upon the Catena-X Semantic Models which are stored in the [Semantic Hub](https://catena-x.net/en/angebote/digitaler-zwilling). 
+The Service interacts with the Catena-X [Digital Twin Registry](https://github.com/eclipse-tractusx/sldt-digital-twin-registry) and is built upon the Catena-X Semantic Models which are stored in the [Semantic Hub](https://github.com/eclipse-tractusx/sldt-semantic-hub). 
 
 ### Tools and documentation
 
 - 🖥 Item Relationship Service Video
-- 📄 [Item Relationship Service Product Page](https://catena-x.net/en/angebote/item-relationship-service)
+- 📄 [Item Relationship Service Product Page](https://catena-x.net/en/offers-standards/item-relationship-service)
 - 📄 [Item Relationship Service Documentation](https://github.com/eclipse-tractusx/item-relationship-service/blob/main/README.md)
 - 📄 [IRS REST API Documentation](https://eclipse-tractusx.github.io/item-relationship-service/docs/api-specification/api-specification.html)
 - 📄 Catena-X Kit's

INSTALL.md

@@ -10,11 +10,11 @@ Everything else needs to be provided externally.
 ## Data Chain Kit
 
 You can use the Data Chain Kit to deploy the whole demo scenario with all participating components.  
-Instructions can be found here: [Data Chain Kit](https://eclipse-tractusx.github.io/docs/kits/Data%20Chain%20Kit/Operation%20View/).
+Instructions can be found here: [Data Chain Kit](https://eclipse-tractusx.github.io/docs-kits/kits/Data%20Chain%20Kit/Operation%20View).
 
 ## Installation
 
-The IRS Helm repository can be found here: [https://eclipse-tractusx.github.io/item-relationship-service/index.yaml](https://eclipse-tractusx.github.io/docs/kits/Data%20Chain%20Kit/Operation%20View/)
+The IRS Helm repository can be found here: [index.yaml](https://eclipse-tractusx.github.io/item-relationship-service/index.yaml)
 
 Use the latest release of the "irs-helm" chart.
 It contains all required dependencies.
@@ -44,10 +44,10 @@ Or create a new Helm chart and use the IRS as a dependency.
     dependencies:
       - name: irs-helm
         repository: https://eclipse-tractusx.github.io/item-relationship-service
-        version: 3.x.x
-      - name: irs-edc-consumer # optional
-        repository: https://eclipse-tractusx.github.io/item-relationship-service
-        version: 1.x.x
+        version: 6.x.x
+      - name: tractusx-connector
+        repository: https://eclipse-tractusx.github.io/tractusx-edc
+        version: 0.5.x
 ```
 
 Then provide your configuration as the values.yaml of that chart.
@@ -62,4 +62,4 @@ A detailed instruction on how to configure the IRS and EDC can be found here: [A
 IRS provides a local setup which can be deployed to kubernetes.
 This setup includes all third-party services which IRS uses and interacts with.
 
-Instructions can be found here [README.md](https://github.com/eclipse-tractusx/item-relationship-service/blob/main/local/deployment/full-irs/README.md).
+Instructions can be found here [README.md](README.md).

README.md

@@ -12,26 +12,28 @@
 [![OWASP Dependency Check](https://github.com/eclipse-tractusx/item-relationship-service/actions/workflows/owasp.yml/badge.svg)](https://github.com/eclipse-tractusx/item-relationship-service/actions/workflows/owasp.yml)
 [![Spotbugs](https://github.com/eclipse-tractusx/item-relationship-service/actions/workflows/spotbugs.yml/badge.svg)](https://github.com/eclipse-tractusx/item-relationship-service/actions/workflows/spotbugs.yml)
 [![Eclipse-dash](https://github.com/eclipse-tractusx/item-relationship-service/actions/workflows/eclipse-dash.yml/badge.svg)](https://github.com/eclipse-tractusx/item-relationship-service/actions/workflows/eclipse-dash.yml)
-[![Tavern IRS API test](https://github.com/eclipse-tractusx/item-relationship-service/actions/workflows/tavern.yml/badge.svg)](https://github.com/eclipse-tractusx/item-relationship-service/actions/workflows/tavern.yml)   
+[![Tavern IRS API test](https://github.com/eclipse-tractusx/item-relationship-service/actions/workflows/tavern.yml/badge.svg)](https://github.com/eclipse-tractusx/item-relationship-service/actions/workflows/tavern.yml)
 
 ## What is the IRS?
 
-Within the [Catena-X network](https://catena-x.net/), the so-called Item Relationship Service (IRS) forms an essential 
+Within the [Catena-X network](https://catena-x.net/), the so-called Item Relationship Service (IRS) forms an essential
 foundation for various services and products. Within the Catena-X use cases, the IRS serves to increase business value.
-For example, the IRS provides functionalities to serve requirements, such as occasion-based Traceability, 
-from the Supply Chain Act. In doing so, IDSA and Gaia-X principles, such as data interoperability and sovereignty, are 
-maintained on the Catena-X network and access to dispersed data is enabled. Data chains are established as a common asset.
-
-With the help of the IRS, data chains are to be provided ad-hoc across n-tiers within the Catena-X network. 
-To realize these data chains, the IRS relies on data models of the Traceability use case and provides the federated 
-data chains to customers or applications. Furthermore, the target picture of the IRS includes the enablement of new 
+For example, the IRS provides functionalities to serve requirements, such as occasion-based Traceability,
+from the Supply Chain Act. In doing so, IDSA and Gaia-X principles, such as data interoperability and sovereignty, are
+maintained on the Catena-X network and access to dispersed data is enabled. Data chains are established as a common
+asset.
+
+With the help of the IRS, data chains are to be provided ad-hoc across n-tiers within the Catena-X network.
+To realize these data chains, the IRS relies on data models of the Traceability use case and provides the federated
+data chains to customers or applications. Furthermore, the target picture of the IRS includes the enablement of new
 business areas by means of data chains along the value chain in the automotive industry.
 
 ## Usage
 
 ### Local deployment
 
-The following subsection provides instructions for running the infrastructure on docker-compose and the application in the IDE.
+The following subsection provides instructions for running the infrastructure on docker-compose and the application in
+the IDE.
 
 #### Docker-compose + IDE
 
@@ -47,10 +49,12 @@ The following subsection provides instructions for running the infrastructure on
 
 ### Helm deployment
 
-see [INSTALL.md](https://github.com/eclipse-tractusx/item-relationship-service/blob/main/INSTALL.md)
+see [INSTALL.md](INSTALL.md)
 
 ### Sample calls
 
+#### IRS
+
 Start a job for a globalAssetId:
 
 ```bash
@@ -71,17 +75,47 @@ curl -X 'POST' \
 ```
 
 Retrieve the job results by using the jobId returned by the previous call:
+
 ```bash
 curl -X 'GET' 'http://localhost:8080/irs/jobs/<jobID>' -H 'accept: application/json' -H 'Authorization: Bearer <token_value>'
 ```
 
+#### Environmental and Social Standards (ESS)
+
+Start an ESS investigation for a globalAssetId and Incident BPNS.
+
+```bash
+curl -X 'POST' \
+  'http://localhost:8080/ess/bpn/investigations' \
+  -H 'accept: application/json' \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: Bearer <token_value>' \
+  -d '{
+	"key": {
+		"globalAssetId": "urn:uuid:3d61ada2-1a50-42a0-b411-40a932dd56cc",
+		"bpn": "BPNL00ARBITRARY6"
+	},
+	"incidentBPNSs": [
+		"BPNS00ARBITRARY7"
+	],
+	"bomLifecycle": "asPlanned"
+    }'
+```
+
+Retrieve the investigation results by using the jobId returned by the previous call:
+
+```bash
+curl -X 'GET' 'http://localhost:8080/ess/bpn/investigations/<jobID>' -H 'accept: application/json' -H 'Authorization: Bearer <token_value>'
+```
+
 ## Documentation
 
 - [Item Relationship Service Documentation](https://eclipse-tractusx.github.io/item-relationship-service/docs/)
 
 ## Licenses
 
-For used licenses, please see the [NOTICE](https://github.com/eclipse-tractusx/item-relationship-service/blob/main/NOTICE.md).
+For used licenses, please see
+the [NOTICE](https://github.com/eclipse-tractusx/item-relationship-service/blob/main/NOTICE.md).
 
 ## Notice for Docker image
 
@@ -94,14 +128,19 @@ Eclipse Tractus-X product(s) installed within the image:
 - GitHub: https://github.com/eclipse-tractusx/item-relationship-service
 - Project home: https://projects.eclipse.org/projects/automotive.tractusx
 - Dockerfile: https://github.com/eclipse-tractusx/item-relationship-service/blob/main/Dockerfile
-- Project license: [Apache License, Version 2.0](https://github.com/eclipse-tractusx/item-relationship-service/blob/main/LICENSE)
+- Project
+  license: [Apache License, Version 2.0](https://github.com/eclipse-tractusx/item-relationship-service/blob/main/LICENSE)
 
 **Used base image**
+
 - [eclipse-temurin:20-jre-alpine](https://github.com/adoptium/containers)
-- Official Eclipse Temurin DockerHub page: https://hub.docker.com/_/eclipse-temurin  
-- Eclipse Temurin Project: https://projects.eclipse.org/projects/adoptium.temurin  
-- Additional information about the Eclipse Temurin images: https://github.com/docker-library/repo-info/tree/master/repos/eclipse-temurin
+- Official Eclipse Temurin DockerHub page: https://hub.docker.com/_/eclipse-temurin
+- Eclipse Temurin Project: https://projects.eclipse.org/projects/adoptium.temurin
+- Additional information about the Eclipse Temurin
+  images: https://github.com/docker-library/repo-info/tree/master/repos/eclipse-temurin
 
-As with all Docker images, these likely also contain other software which may be under other licenses (such as Bash, etc from the base distribution, along with any direct or indirect dependencies of the primary software being contained).
+As with all Docker images, these likely also contain other software which may be under other licenses (such as Bash, etc
+from the base distribution, along with any direct or indirect dependencies of the primary software being contained).
 
-As for any pre-built image usage, it is the image user's responsibility to ensure that any use of this image complies with any relevant licenses for all software contained within.
+As for any pre-built image usage, it is the image user's responsibility to ensure that any use of this image complies
+with any relevant licenses for all software contained within.

charts/irs-helm/CHANGELOG.md

@@ -7,6 +7,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 ### Changed 
 - Changed configuration from `ess.managementPath` to options for each endpoint `ess.assetsPath` `ess.policydefinitionsPath` `ess.contractdefinitionsPath`. E.g. `ess.assetsPath: /management/v3/assets`
+- Rename property `edc.provider.host` to `ess.edc.host`
 
 ## [6.11.0] - 2023-11-28
 ### Fixed

charts/irs-helm/templates/configmap-spring-app-config.yaml

@@ -118,7 +118,7 @@ data:
         cacheTTL: {{ .Values.edc.connectorEndpointService.cacheTTL | quote }}
     ess:
       localBpn: {{ tpl (.Values.bpn | default "") . | quote }}
-      localEdcEndpoint: {{ tpl (.Values.edc.provider.host | default "") . | quote }}
+      localEdcEndpoint: {{ tpl (.Values.ess.edc.host | default "") . | quote }}
       assetsPath: {{ tpl (.Values.ess.assetsPath | default "/management/v3/assets") . | quote }}
       policydefinitionsPath: {{ tpl (.Values.ess.policydefinitionsPath | default "/management/v2/policydefinitions") . | quote }}
       contractdefinitionsPath: {{ tpl (.Values.ess.contractdefinitionsPath | default "/management/v2/contractdefinitions") . | quote }}

charts/irs-helm/values.yaml

@@ -159,8 +159,6 @@ portal:
     clientId:  # <portal-client-id>
     clientSecret:  # <portal-client-secret>
 edc:
-  provider:
-    host:  # EDC Provider Host URL
   controlplane:
     endpoint:
       data: ""  # <edc-controlplane-endpoint-data>
@@ -208,6 +206,8 @@ discovery:
   oAuthClientId: portal  # ID of the OAuth2 client registration to use, see config spring.security.oauth2.client
 
 ess:
+  edc:
+    host:  # EDC base URL - used for creation of EDC assets for ESS notifications and as sender EDC for sent notifications
   mockEdcResult:  # Map of BPNs and YES/NO strings - this configures the ESS mock response in case it called to investigate a BPN
   mockRecursiveEdcAsset:  # List of BPNs for which the special, mocked notification asset should be used
   assetsPath: /management/v3/assets  # EDC management API "assets" path - used for notification asset creation

docs/src/docs/administration/administration-guide.adoc

@@ -7,9 +7,9 @@ include::installation.adoc[leveloffset=+1]
 include::configuration.adoc[leveloffset=+1]
 include::troubleshooting.adoc[leveloffset=+1]
 
-## NOTICE
+== NOTICE
 
-This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0).
+This work is licensed under the https://www.apache.org/licenses/LICENSE-2.0[Apache-2.0].
 
 - SPDX-License-Identifier: Apache-2.0
 - SPDX-FileCopyrightText: 2021, 2023 Bayerische Motoren Werke Aktiengesellschaft (BMW AG)

docs/src/docs/administration/installation.adoc

@@ -6,7 +6,7 @@ https://eclipse-tractusx.github.io/item-relationship-service/index.yaml
 Use the latest release of the "irs-helm" chart.
 It contains all required dependencies.
 
-If you also want to set up your own EDC consumer, use the "irs-edc-consumer" chart.
+If you also want to set up your own EDC consumer, use the https://github.com/eclipse-tractusx/tractusx-edc/tree/main/charts/tractusx-connector[tractusx-connector] chart.
 
 Supply the required configuration properties (see chapter xref:configuration.adoc#_configuration[Configuration]) in a values.yaml file or override the settings directly.
 
@@ -31,10 +31,10 @@ Create a new Helm chart and use the IRS as a dependency.
 dependencies:
   - name: irs-helm
     repository: https://eclipse-tractusx.github.io/item-relationship-service
-    version: 5.x.x
-  - name: irs-edc-consumer # optional
-    repository: https://eclipse-tractusx.github.io/item-relationship-service
-    version: 1.x.x
+    version: 6.x.x
+  - name: tractusx-connector # optional
+    repository: https://eclipse-tractusx.github.io/tractusx-edc
+    version: 0.5.x
 
 ----
 

docs/src/docs/arc42/building-block-view/level-2.adoc

@@ -35,7 +35,7 @@ include::../../../uml-diagrams/building-block-view/level-2-int.puml[]
 
 == RecursiveJobHandler
 
-The *RecursiveJobHandler* component provide the logic to build jobs with recursive logic to retrieve items over the complete C-X network and assembles the partial results into a single item graph result.
+The *RecursiveJobHandler* component provide the logic to build jobs recursively to retrieve items over the complete C-X network and assembles the partial results into a single item graph result.
 
 === Component diagram
 

docs/src/docs/arc42/building-block-view/whitebox-overall.adoc

@@ -96,6 +96,9 @@ include::../../../uml-diagrams/building-block-view/whitebox_overall_decentral.pu
 
 | 16
 | *IRS* accessing the *decentral DigitalTwinRegistry* on Tier Level using the *EDC*
+
+| 17
+| In case of the use-case Environmental and Social Standards, *IRS* sends notifications to the *IRS-ESS* instance running at the data provider using the *EDC*.
 |===
 
 

docs/src/docs/arc42/full.adoc

@@ -12,9 +12,9 @@ include::cross-cutting/full.adoc[leveloffset=+1]
 include::quality/index.adoc[leveloffset=+1]
 include::glossary.adoc[leveloffset=+1]
 
-## NOTICE
+== NOTICE
 
-This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0).
+This work is licensed under the https://www.apache.org/licenses/LICENSE-2.0[Apache-2.0].
 
 - SPDX-License-Identifier: Apache-2.0
 - SPDX-FileCopyrightText: 2021, 2023 Bayerische Motoren Werke Aktiengesellschaft (BMW AG)

docs/src/docs/arc42/index.adoc

@@ -11,9 +11,9 @@
 - xref:quality/index.adoc[Quality requirements]
 - xref:glossary.adoc[Glossary]
 
-## NOTICE
+== NOTICE
 
-This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0).
+This work is licensed under the https://www.apache.org/licenses/LICENSE-2.0[Apache-2.0].
 
 - SPDX-License-Identifier: Apache-2.0
 - SPDX-FileCopyrightText: 2021, 2023 Bayerische Motoren Werke Aktiengesellschaft (BMW AG)

docs/src/docs/arc42/introduction-goals/requirements.adoc

@@ -14,4 +14,5 @@ The IRS is a:
 - functionality of IRS provider will be handled by providers submodel servers
 - federated IRS service
 - 'asBuild' BoM of serialized components
-- provides endpoints for submodel-descriptors
+- provides endpoints for submodel-descriptors
+- start recursive Environmental and Social Standard investigations throughout the network based on the "asPlanned" lifecycle

docs/src/docs/arc42/runtime-view/ess-top-down/ess-top-down-scenario-1.adoc

@@ -4,7 +4,7 @@ This section describes what happens when user creates an ess order.
 
 == Register an Ess-Investigation-Order
 
-[plantuml,target=submodel-processing,format=svg]
+[plantuml, target=ess-topdown-order, format=svg]
 ....
 include::../../../../uml-diagrams/runtime-view/use-case-ess-top-down/3_ess_top_down_sequence-RegisterEssInvestigationOrder.puml[]
 ....

docs/src/docs/arc42/runtime-view/ess-top-down/ess-top-down-scenario-2.adoc

@@ -1,10 +1,10 @@
-= Scenario 1: Register an Ess-Investigation-Job
+= Scenario 2: 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]
+[plantuml, target=ess-topdown-order-job, format=svg]
 ....
 include::../../../../uml-diagrams/runtime-view/use-case-ess-top-down/4_ess_top_down_sequence_RegisterEssInvestigationJob.puml[]
 ....

docs/src/docs/arc42/runtime-view/ess-top-down/ess-top-down.adoc

@@ -14,7 +14,7 @@ The BoM as planned aspect models consists of three aspect models:
 
 == Overall flow
 
-[plantuml,target=submodel-processing,format=svg]
+[plantuml, target=ess-top-down, format=svg]
 ....
 include::../../../../uml-diagrams/runtime-view/use-case-ess-top-down/0-ess-top-down-sequence.puml[]
 ....
@@ -49,7 +49,7 @@ Note: ESS supplier responses are involved in each step of the process.
 
 == Flow on company level
 
-[plantuml,target=submodel-processing,format=svg]
+[plantuml, target=ess-top-down-highlevel, format=svg]
 ....
 include::../../../../uml-diagrams/runtime-view/use-case-ess-top-down/1_ess-top-down-sequence-highlevel.puml[]
 ....
@@ -92,11 +92,35 @@ The response of each direct supplier may contain the following results;
 
 In case at least one "YES" is received, the process step 3 ends
 
+[cols="6,1,1,1"]
+|===
+|Case |YES |NO |UNKNOWN
+|All assets on all nodes does not contain assets with incidentBPNs |x | |
+|At least one node contains assets with  incidentBPNs | |x |
+|At least one node does not contain PartSiteInformationAsPlanned aspect OR for at least one node PartSiteInformationAsPlanned  aspect  is not accessible | | |x
+|At least one node contains PartSiteInformationAsPlanned  with missing BPNS | | |x
+|At least one child node does not exist or is not accessible | | |x
+|===
+
+[cols="1,1,1,2,5"]
+|===
+| State 1 | State 2 | State n | Result State | Description
+| YES     | NO      | UNKOWN  | YES          | If any part is impacted then whole Supply is impactes
+| YES     | NO      | NO      | YES          | Yes if any BPN is impacted even if all are not impacted.
+| NO      | UNKNOW  | NO      | UNKNOW       | Unknown if no Yes and at leat one bpn is unknown state.
+| NO      | NO      | NO      | NO           | No if complete SupplyChain is not impacted
+|===
+
+[plantuml, target=ess_top_down_sequence-result, format=svg]
+....
+include::../../../../uml-diagrams/runtime-view/use-case-ess-top-down/5_ess_top_down_sequence_determine_result.puml[]
+....
+
 == Application Functionality Overview
 
 === Register an Ess-Investigation-Order
 
-[plantuml,target=submodel-processing,format=svg]
+[plantuml, target=ess-top-down-highlevel, format=svg]
 ....
 include::../../../../uml-diagrams/runtime-view/use-case-ess-top-down/1_ess-top-down-sequence-highlevel.puml[]
 ....