docs: improve readability of documentation

advanced/advanced-01-open-telemetry/README.md

@@ -26,7 +26,7 @@ is configured to expose a Prometheus metrics endpoint.
 To run the consumer, the provider, and Jaeger execute the following commands in the project root folder:
 
 ```bash
-docker-compose -f advanced/advanced-01-open-telemetry/docker-compose.yaml up --abort-on-container-exit
+docker compose -f advanced/advanced-01-open-telemetry/docker-compose.yaml up --abort-on-container-exit
 ```
 
 Open a new terminal.
@@ -54,7 +54,7 @@ Create an asset:
 ```bash
 curl -H "X-Api-Key: password" \
   -d @transfer/transfer-01-negotiation/resources/create-asset.json \
-  -H 'content-type: application/json' http://localhost:19193/management/v2/assets \
+  -H 'content-type: application/json' http://localhost:19193/management/v3/assets \
   -s | jq
 ```
 
@@ -76,7 +76,63 @@ curl -H "X-Api-Key: password" \
   -s | jq
 ```
 
-Start a contract negotiation:
+The typical flow requires fetching the catalog from the consumer side and using the contract offer to negotiate a
+contract. However, in this sample case, we already have the provider asset `assetId` so we can get the related dataset
+directly with this call:
+
+```shell
+curl -H "X-Api-Key: password" \
+  -H "Content-Type: application/json" \
+  -d @advanced/advanced-01-open-telemetry/resources/get-dataset.json \
+  -X POST "http://localhost:29193/management/v2/catalog/dataset/request" \
+  -s | jq
+```
+
+The output will be something like:
+
+```json
+{
+  "@id": "assetId",
+  "@type": "dcat:Dataset",
+  "odrl:hasPolicy": {
+    "@id": "MQ==:YXNzZXRJZA==:YjI5ZDVkZDUtZWU0Mi00NWRiLWE2OTktYjNmMjlmMWNjODk3",
+    "@type": "odrl:Set",
+    "odrl:permission": [],
+    "odrl:prohibition": [],
+    "odrl:obligation": [],
+    "odrl:target": "assetId"
+  },
+  "dcat:distribution": [
+    {
+      "@type": "dcat:Distribution",
+      "dct:format": {
+        "@id": "HttpProxy"
+      },
+      "dcat:accessService": "06348bca-6bf0-47fe-8bb5-6741cff7a955"
+    },
+    {
+      "@type": "dcat:Distribution",
+      "dct:format": {
+        "@id": "HttpData"
+      },
+      "dcat:accessService": "06348bca-6bf0-47fe-8bb5-6741cff7a955"
+    }
+  ],
+  "edc:name": "product description",
+  "edc:id": "assetId",
+  "edc:contenttype": "application/json",
+  "@context": {
+    "dct": "https://purl.org/dc/terms/",
+    "edc": "https://w3id.org/edc/v0.0.1/ns/",
+    "dcat": "https://www.w3.org/ns/dcat/",
+    "odrl": "http://www.w3.org/ns/odrl/2/",
+    "dspace": "https://w3id.org/dspace/v0.8/"
+  }
+}
+```
+
+With the `odrl:hasPolicy/@id` we can now replace it in the [negotiate-contract.json](resources/negotiate-contract.json) file
+and request the contract negotiation:
 
 ```bash
 curl -H "X-Api-Key: password" \
@@ -86,20 +142,23 @@ curl -H "X-Api-Key: password" \
   -s | jq
 ```
 
-Wait until the negotiation is in `FINALIZED` state and call
+At this point the contract agreement should already been issued, to verify that, please check the contract negotiation
+state with this call, replacing `{{contract-negotiation-id}}` with the id returned by the negotiate contract call.
 
-```bash
-curl -X GET -H 'X-Api-Key: password' "http://localhost:29193/management/v2/contractnegotiations/{UUID}"
+```shell
+curl -H 'X-Api-Key: password' \
+  -X GET "http://localhost:29193/management/v2/contractnegotiations/{{contract-negotiation-id}}" \
+  -s | jq
 ```
-to get the contract agreement id.
 
-Finally, update the contract agreement id in the [request body](resources/start-transfer.json) and execute a file transfer with the following command:
+Finally, update the contract agreement id in the [start-transfer.json](resources/start-transfer.json) and execute a file transfer with the following command:
 
 ```bash
 curl -H "X-Api-Key: password" \
   -H "Content-Type: application/json" \
   -d @advanced/advanced-01-open-telemetry/resources/start-transfer.json \
-  -X POST "http://localhost:29193/management/v2/transferprocesses"
+  -X POST "http://localhost:29193/management/v2/transferprocesses" \
+  -s | jq
 ```
 
 You can access the Jaeger UI on your browser at `http://localhost:16686`. In the search tool, we can select the service

advanced/advanced-01-open-telemetry/resources/get-dataset.json

@@ -0,0 +1,7 @@
+{
+  "@context": { "@vocab": "https://w3id.org/edc/v0.0.1/ns/" },
+  "@type": "DatasetRequest",
+  "@id": "assetId",
+  "counterPartyAddress": "http://provider:19194/protocol",
+  "protocol": "dataspace-protocol-http"
+}

advanced/advanced-01-open-telemetry/resources/negotiate-contract.json

@@ -11,7 +11,7 @@
   "protocol": "dataspace-protocol-http",
   "policy": {
     "@context": "http://www.w3.org/ns/odrl.jsonld",
-    "@id": "MQ==:YXNzZXRJZA==:YTc4OGEwYjMtODRlZi00NWYwLTgwOWQtMGZjZTMwMGM3Y2Ey",
+    "@id": "{{contract-negotiation-id}}",
     "@type": "Set",
     "permission": [],
     "prohibition": [],

advanced/advanced-01-open-telemetry/resources/start-transfer.json

@@ -5,7 +5,7 @@
   "@type": "TransferRequestDto",
   "connectorId": "provider",
   "counterPartyAddress": "http://provider:19194/protocol",
-  "contractId": "<contract agreement id>",
+  "contractId": "{{contract-agreement-id}}",
   "assetId": "assetId",
   "protocol": "dataspace-protocol-http",
   "dataDestination": {

basic/basic-02-health-endpoint/README.md

@@ -7,7 +7,7 @@ An _extension_ typically consists of two things:
 
 1. a class implementing the `ServiceExtension` interface.
 2. a plugin file in the `src/main/resources/META-INF/services` directory. This file **must** be named exactly as the
-   interface's fully qualified class-name and it **must** contain the fully-qualified name of the implementing class (
+   interface's fully qualified class name, and it **must** contain the fully-qualified name of the implementing class (
    =plugin class).
 
 Therefore, we require an extension class, which we'll name `HealthEndpointExtension`:
@@ -66,8 +66,7 @@ and can be configured using the `web.http.port` property (more on that in the ne
 this whenever you have two connectors running on the same machine.
 
 Also, the default path is `/api/*`, which is defined in
-[`JettyConfiguration.java`](https://github.com/eclipse-edc/Connector/blob/releases/extensions/common/http/jetty-core/src/main/java/org/eclipse/edc/web/jetty/JettyConfiguration.java)
-.
+[`JettyConfiguration.java`](https://github.com/eclipse-edc/Connector/blob/releases/extensions/common/http/jetty-core/src/main/java/org/eclipse/edc/web/jetty/JettyConfiguration.java).
 
 ---
 

system-tests/src/test/java/org/eclipse/edc/samples/advanced/Advanced01openTelemetryTest.java

@@ -9,6 +9,7 @@
  *
  *  Contributors:
  *       Mercedes-Benz Tech Innovation GmbH - Sample workflow test
+ *       Fraunhofer Institute for Software and Systems Engineering - use current ids instead of placeholder
  *
  */
 
@@ -19,7 +20,7 @@
 import org.eclipse.edc.junit.annotations.EndToEndTest;
 import org.junit.jupiter.api.BeforeAll;
 import org.junit.jupiter.api.Test;
-import org.testcontainers.containers.DockerComposeContainer;
+import org.testcontainers.containers.ComposeContainer;
 import org.testcontainers.containers.wait.strategy.Wait;
 import org.testcontainers.junit.jupiter.Container;
 import org.testcontainers.junit.jupiter.Testcontainers;
@@ -35,6 +36,7 @@
 import static org.eclipse.edc.samples.common.NegotiationCommon.createAsset;
 import static org.eclipse.edc.samples.common.NegotiationCommon.createContractDefinition;
 import static org.eclipse.edc.samples.common.NegotiationCommon.createPolicy;
+import static org.eclipse.edc.samples.common.NegotiationCommon.fetchDatasetFromCatalog;
 import static org.eclipse.edc.samples.common.NegotiationCommon.getContractAgreementId;
 import static org.eclipse.edc.samples.common.NegotiationCommon.negotiateContract;
 import static org.eclipse.edc.samples.common.PrerequisitesCommon.runPrerequisites;
@@ -46,13 +48,14 @@
 public class Advanced01openTelemetryTest {
 
     private static final String DOCKER_COMPOSE_YAML = "advanced/advanced-01-open-telemetry/docker-compose.yaml";
+    private static final String FETCH_DATASET_FROM_CATALOG_FILE_PATH = "advanced/advanced-01-open-telemetry/resources/get-dataset.json";
     private static final String NEGOTIATE_CONTRACT_FILE_PATH = "advanced/advanced-01-open-telemetry/resources/negotiate-contract.json";
     private static final String START_TRANSFER_FILE_PATH = "advanced/advanced-01-open-telemetry/resources/start-transfer.json";
     private static final String JAEGER_URL = "http://localhost:16686";
 
     @Container
-    public static DockerComposeContainer<?> environment =
-            new DockerComposeContainer<>(getFileFromRelativePath(DOCKER_COMPOSE_YAML))
+    public static ComposeContainer environment =
+            new ComposeContainer(getFileFromRelativePath(DOCKER_COMPOSE_YAML))
                     .withLocalCompose(true)
                     .waitingFor("consumer", Wait.forLogMessage(".*ready.*", 1));
 
@@ -67,7 +70,8 @@ void runSampleSteps()  {
         createAsset();
         createPolicy();
         createContractDefinition();
-        var contractNegotiationId = negotiateContract(NEGOTIATE_CONTRACT_FILE_PATH);
+        var catalogDatasetId = fetchDatasetFromCatalog(FETCH_DATASET_FROM_CATALOG_FILE_PATH);
+        var contractNegotiationId = negotiateContract(NEGOTIATE_CONTRACT_FILE_PATH, catalogDatasetId);
         var contractAgreementId = getContractAgreementId(contractNegotiationId);
         var transferProcessId = startTransfer(getFileContentFromRelativePath(START_TRANSFER_FILE_PATH), contractAgreementId);
         checkTransferStatus(transferProcessId, TransferProcessStates.STARTED);

system-tests/src/test/java/org/eclipse/edc/samples/common/NegotiationCommon.java

@@ -9,6 +9,7 @@
  *
  *  Contributors:
  *       Mercedes-Benz Tech Innovation GmbH - Initial implementation
+ *       Fraunhofer Institute for Software and Systems Engineering - use current ids instead of placeholder
  *
  */
 
@@ -33,12 +34,14 @@ public class NegotiationCommon {
     private static final String V2_POLICY_DEFINITIONS_PATH = "/v2/policydefinitions";
     private static final String CREATE_CONTRACT_DEFINITION_FILE_PATH = "transfer/transfer-01-negotiation/resources/create-contract-definition.json";
     private static final String V2_CONTRACT_DEFINITIONS_PATH = "/v2/contractdefinitions";
-    private static final String FETCH_CATALOG_FILE_PATH = "transfer/transfer-01-negotiation/resources/fetch-catalog.json";
-    private static final String V2_CATALOG_REQUEST_PATH = "/v2/catalog/request";
+    private static final String V2_CATALOG_DATASET_REQUEST_PATH = "/v2/catalog/dataset/request";
+    private static final String FETCH_DATASET_FROM_CATALOG_FILE_PATH = "transfer/transfer-01-negotiation/resources/get-dataset.json";
+    private static final String CATALOG_DATASET_ID = "\"odrl:hasPolicy\".'@id'";
     private static final String NEGOTIATE_CONTRACT_FILE_PATH = "transfer/transfer-01-negotiation/resources/negotiate-contract.json";
     private static final String V2_CONTRACT_NEGOTIATIONS_PATH = "/v2/contractnegotiations/";
     private static final String CONTRACT_NEGOTIATION_ID = "@id";
     private static final String CONTRACT_AGREEMENT_ID = "contractAgreementId";
+    private static final String CONTRACT_NEGOTIATION_ID_KEY = "\\{\\{contract-negotiation-id\\}\\}";
 
     public static void createAsset() {
         post(PrerequisitesCommon.PROVIDER_MANAGEMENT_URL + V3_ASSETS_PATH, getFileContentFromRelativePath(CREATE_ASSET_FILE_PATH));
@@ -52,20 +55,28 @@ public static void createContractDefinition() {
         post(PrerequisitesCommon.PROVIDER_MANAGEMENT_URL + V2_CONTRACT_DEFINITIONS_PATH, getFileContentFromRelativePath(CREATE_CONTRACT_DEFINITION_FILE_PATH));
     }
 
-    public static void fetchCatalog() {
-        post(PrerequisitesCommon.CONSUMER_MANAGEMENT_URL + V2_CATALOG_REQUEST_PATH, getFileContentFromRelativePath(FETCH_CATALOG_FILE_PATH));
+    public static String fetchDatasetFromCatalog(String fetchDatasetFromCatalogFilePath) {
+        var catalogDatasetId = post(
+                PrerequisitesCommon.CONSUMER_MANAGEMENT_URL + V2_CATALOG_DATASET_REQUEST_PATH,
+                getFileContentFromRelativePath(fetchDatasetFromCatalogFilePath),
+                CATALOG_DATASET_ID
+        );
+        assertThat(catalogDatasetId).isNotEmpty();
+        return catalogDatasetId;
     }
 
-    public static String negotiateContract(String negotiateContractFilePath) {
-        var contractNegotiationId = post(PrerequisitesCommon.CONSUMER_MANAGEMENT_URL + V2_CONTRACT_NEGOTIATIONS_PATH, getFileContentFromRelativePath(negotiateContractFilePath), CONTRACT_NEGOTIATION_ID);
+    public static String negotiateContract(String negotiateContractFilePath, String catalogDatasetId) {
+        var requestBody = getFileContentFromRelativePath(negotiateContractFilePath)
+                .replaceAll(CONTRACT_NEGOTIATION_ID_KEY, catalogDatasetId);
+        var contractNegotiationId = post(
+                PrerequisitesCommon.CONSUMER_MANAGEMENT_URL + V2_CONTRACT_NEGOTIATIONS_PATH,
+                requestBody,
+                CONTRACT_NEGOTIATION_ID
+        );
         assertThat(contractNegotiationId).isNotEmpty();
         return contractNegotiationId;
     }
 
-    public static String negotiateContract() {
-        return negotiateContract(NEGOTIATE_CONTRACT_FILE_PATH);
-    }
-
     public static String getContractAgreementId(String contractNegotiationId) {
         String url = PrerequisitesCommon.CONSUMER_MANAGEMENT_URL + V2_CONTRACT_NEGOTIATIONS_PATH + contractNegotiationId;
         return await()
@@ -78,8 +89,8 @@ public static String runNegotiation() {
         createAsset();
         createPolicy();
         createContractDefinition();
-        fetchCatalog();
-        var contractNegotiationId = negotiateContract();
+        var catalogDatasetId = fetchDatasetFromCatalog(FETCH_DATASET_FROM_CATALOG_FILE_PATH);
+        var contractNegotiationId = negotiateContract(NEGOTIATE_CONTRACT_FILE_PATH, catalogDatasetId);
         return getContractAgreementId(contractNegotiationId);
     }
 }

system-tests/src/test/java/org/eclipse/edc/samples/transfer/Transfer01negotiationTest.java

@@ -9,6 +9,7 @@
  *
  *  Contributors:
  *       Mercedes-Benz Tech Innovation GmbH - Sample workflow test
+ *       Fraunhofer Institute for Software and Systems Engineering - use current ids instead of placeholder
  *
  */
 
@@ -23,7 +24,7 @@
 import static org.eclipse.edc.samples.common.NegotiationCommon.createAsset;
 import static org.eclipse.edc.samples.common.NegotiationCommon.createContractDefinition;
 import static org.eclipse.edc.samples.common.NegotiationCommon.createPolicy;
-import static org.eclipse.edc.samples.common.NegotiationCommon.fetchCatalog;
+import static org.eclipse.edc.samples.common.NegotiationCommon.fetchDatasetFromCatalog;
 import static org.eclipse.edc.samples.common.NegotiationCommon.getContractAgreementId;
 import static org.eclipse.edc.samples.common.NegotiationCommon.negotiateContract;
 import static org.eclipse.edc.samples.common.PrerequisitesCommon.getConsumer;
@@ -39,14 +40,17 @@ public class Transfer01negotiationTest {
     @RegisterExtension
     static EdcRuntimeExtension consumer = getConsumer();
 
+    private static final String NEGOTIATE_CONTRACT_FILE_PATH = "transfer/transfer-01-negotiation/resources/negotiate-contract.json";
+    private static final String FETCH_DATASET_FROM_CATALOG_FILE_PATH = "transfer/transfer-01-negotiation/resources/get-dataset.json";
+
     @Test
     void runSampleSteps() {
         runPrerequisites();
         createAsset();
         createPolicy();
         createContractDefinition();
-        fetchCatalog();
-        var contractNegotiationId = negotiateContract();
+        var catalogDatasetId = fetchDatasetFromCatalog(FETCH_DATASET_FROM_CATALOG_FILE_PATH);
+        var contractNegotiationId = negotiateContract(NEGOTIATE_CONTRACT_FILE_PATH, catalogDatasetId);
         var contractAgreementId = getContractAgreementId(contractNegotiationId);
         assertThat(contractAgreementId).isNotEmpty();
     }

system-tests/src/test/java/org/eclipse/edc/samples/util/TransferUtil.java

@@ -9,6 +9,7 @@
  *
  *  Contributors:
  *       Mercedes-Benz Tech Innovation GmbH - Initial implementation
+ *       Fraunhofer Institute for Software and Systems Engineering - use current ids instead of placeholder
  *
  */
 
@@ -35,7 +36,7 @@ public class TransferUtil {
     public static final Duration POLL_INTERVAL = Duration.ofMillis(500);
 
     private static final String TRANSFER_PROCESS_ID = "@id";
-    private static final String CONTRACT_AGREEMENT_ID_KEY = "<contract agreement id>";
+    private static final String CONTRACT_AGREEMENT_ID_KEY = "\\{\\{contract-agreement-id\\}\\}";
     private static final String V2_TRANSFER_PROCESSES_PATH = "/v2/transferprocesses/";
     private static final String EDC_STATE = "state";