streamline with @cap-js/advanced-event-mesh

Author: sjvans

README.md

@@ -12,35 +12,89 @@ CDS plugin providing integration with SAP Integration Suite, advanced event mesh
 
 
 
-## Requirements and Setup
+## Table of Contents
 
-See [Getting Started](https://cap.cloud.sap/docs/get-started/in-a-nutshell?impl-variant=java) on how to jumpstart your development and grow as you go with SAP Cloud Application Programming Model.
+- [About this project](#about-this-project)
+- [Requirements](#requirements)
+- [Setup](#setup)
+  - [Setting Up the Broker](#setting-up-the-broker)
+  - [Broker Validation](#broker-validation)
+- [Support, Feedback, Contributing](#support-feedback-contributing)
+- [Security / Disclosure](#security--disclosure)
+- [Code of Conduct](#code-of-conduct)
+- [Licensing](#licensing)
 
 
-### CDS Plugin
 
-The usage of CAP Java plugins is described in the [CAP Java Documentation](https://cap.cloud.sap/docs/java/building-plugins#reference-the-new-cds-model-in-an-existing-cap-java-project). Following this documentation this plugin needs to be referenced in the `srv/pom.xml` of a CAP Java project:
+## Requirements
+
+See [Getting Started](https://cap.cloud.sap/docs/get-started/in-a-nutshell?impl-variant=java) on how to jumpstart your development and grow as you go with SAP Cloud Application Programming Model (CAP).
+To learn about messaging in CAP, please consult the guide on [Events & Messaging](https://cap.cloud.sap/docs/guides/messaging/).
+
+
+
+## Setup
+
+Install the plugin by adding it to the dependencies of your CAP Java project:
 
 ```xml
+<!-- srv/pom.xml -->
 <dependency>
-    <groupId>com.sap.cds</groupId>
-    <artifactId>cds-feature-advanced-event-mesh</artifactId>
-    <version>${latest-version}</version>
+  <groupId>com.sap.cds</groupId>
+  <artifactId>cds-feature-advanced-event-mesh</artifactId>
+  <version>${latest-version}</version>
 </dependency>
 ```
 
 The latest version can be found in the [changelog](./CHANGELOG.md) or in the [Maven Central Repository](https://central.sonatype.com/artifact/com.sap.cds/cds-feature-advanced-event-mesh/versions).
+The usage of CAP Java plugins is described in the [CAP Java Documentation](https://cap.cloud.sap/docs/java/building-plugins#reference-the-new-cds-model-in-an-existing-cap-java-project).
+
+Then, set the `kind` of your messaging service to `aem`:
 
+```yaml
+# srv/src/main/resources/application.yaml
+cds:
+  messaging.services:
+  - name: "messaging-name"
+    kind: "aem"
+```
+
+
+### Setting Up the Broker
 
-### WHAT ABOUT THE MESSAGING KIND?
+The broker itself must be created manually in SAP Integration Suite, advanced event mesh and trust must be established to the respective application in [SAP Cloud Identity Services](https://help.sap.com/docs/cloud-identity-services/cloud-identity-services), both for the Solace broker and the [SEMP API](https://docs.solace.com/Admin/SEMP/Using-SEMP.htm).
+For details, please consult SAP Integration Suite, advanced event mesh's documentation at [help.pubsub.em.services.cloud.sap](https://help.pubsub.em.services.cloud.sap/Get-Started/get-started-lp.htm).
 
+// TODO: where to put?
+You need to manually configure SAP Integration Suite, advanced event mesh to allow your application to connect to the broker by following the [steps in the documentation](https://help.sap.com/docs/sap-integration-suite/advanced-event-mesh/cap-plugin-for-sap-integration-suite-advanced-event-mesh).
+
+The broker's credentials must be provided via a [user-provided service instance](https://docs.cloudfoundry.org/devguide/services/user-provided.html) with the name `advanced-event-mesh` and credentials in the following format:
+
+```jsonc
+{
+  "authentication-service": {
+    "tokenendpoint": "https://<ias host>/oauth2/token",
+    "clientid": "<client id>",
+    "clientsecret": "<client secret>"
+  },
+  "endpoints": {
+    "advanced-event-mesh": {
+      "uri": "https://<broker host>:<port>",
+      "smf_uri": "wss://<broker host>:<port>"
+    }
+  },
+  "vpn": "<vpn>"
+}
+```
 
-### COPY OUTCOME OF https://github.com/cap-js/advanced-event-mesh/pull/32
+To troubleshoot connection issues, set log level for component `messaging` to `DEBUG`.
+Check [`cds.log()`](https://cap.cloud.sap/docs/node.js/cds-log) for how to maintain log levels.
 
 
-### SAP Integration Suite, Advanced Event Mesh
+### Broker Validation
 
-For details on how to use SAP Integration Suite, advanced event mesh, please see the [SAP Integration Suite, advanced event mesh documentation](https://help.sap.com/docs/sap-integration-suite/advanced-event-mesh/cap-plugin-for-sap-integration-suite-advanced-event-mesh).
+Your app must be bound to an instance of service `SAP Integration Suite, advanced event mesh` with plan `aem-validation-service`.
+Please see [Validation of VMR Provisioning](https://help.sap.com/docs/sap-integration-suite/advanced-event-mesh/validation-of-vmr-provisioning) for more information.