[cds^8.2] Event Broker: S/4HANA Cloud to CAP

about/features.md

@@ -181,10 +181,13 @@ Following is an index of the features currently covered by CAP, with status and
 | [Declared Events in CDS](../cds/cdl#events)                                                                                                                            | <X/>  |  <X/>   | <X/> |
 | Mock Broker (to speed up local dev) [[Node.js](../node.js/messaging#file-based)\|[Java](../java/messaging#local-testing)]                                   | <Na/> |  <X/>   | <X/> |
 | SAP Event Mesh (Singletenancy) [[Node.js](../node.js/messaging#event-mesh-shared)\|[Java](../java/messaging#configuring-sap-event-mesh-support)]            | <Na/> |  <X/>   | <X/> |
+| SAP Event Broker (Singletenancy) [[Node.js](../node.js/messaging#event-broker)]            | <Na/> |  <X/><br>beta<sup>1</sup>   | <D/> |
 | Composite Messaging (routing by configuration) [[Node.js](../node.js/messaging#composite-messaging)\|[Java](../java/messaging#composite-messaging-service)] | <Na/> |  <X/>   | <X/> |
 | Import AsyncAPI                                                                                                                                                        | <O/>  |         |      |
 | Export AsyncAPI                                                                                                                                                        | <X/>  |         |      |
 
+> <sup>1</sup> May be outsourced into a plugin, hence the status _beta_. <br>
+
 <span id="events-messaging-more" />
 
 ### Database Support

about/index.md

@@ -103,7 +103,7 @@ Keeping pace with a rapidly changing world of cloud technologies and platforms i
 - Platform-specific identity providers and authentication strategies
 - On-/Offboarding of tenants in SaaS solutions and tenant isolation
 - Synchronous protocols like *REST*, *OData*, or *GraphQL*
-- Asynchronous channels and brokers like *SAP Event Mesh*, *MQ*, or *Kafka*
+- Asynchronous channels and brokers like *SAP Event Broker*, *MQ*, or *Kafka*
 - Different database technologies including *SQL* and *NoSQL*
 
 

guides/messaging/event-broker.md

@@ -0,0 +1,196 @@
+# Using SAP Event Broker in Cloud Foundry
+
+[SAP Event Broker](https://help.sap.com/docs/event-broker) is the new default offering for messaging in SAP Business Technology Platform (SAP BTP).
+CAP provides growing out-of-the-box support for SAP Event Broker, and automatically handles many things behind the scenes, so that application coding stays agnostic and focused on conceptual messaging.
+
+::: warning
+Only available for Node.js. Java to follow soon.
+:::
+
+::: warning
+The following guide is based on a productive (paid) account on SAP BTP.
+:::
+
+[[toc]]
+
+<span id="eventbrokerfeaturematrix" />
+
+
+
+## Consuming Events in a Stand-alone App
+
+This guide describes the end-to-end process of developing a stand-alone (or "single tenant") CAP application that consumes messages via SAP Event Broker.
+The guide uses SAP S/4HANA as the event emitter, but this is a stand-in for any system that is able to publish cloud events via SAP Event Broker.
+
+Sample app: [@capire/incidents with Customers based on S/4's Business Partners](https://github.com/cap-js/incidents-app/tree/event-broker)
+
+
+### Prerequisite: Events & Messaging in CAP
+
+From the perspective of a CAP developer, SAP Event Broker is yet another messaging broker.
+That is to say, CAP developers focus on [modeling their domain](../domain-modeling) and [implementing their domain-specific custom logic](../providing-services#custom-logic).
+Differences between the various event transporting technologies are held as transparent as possible.
+
+Hence, before diving into this development guide, you should be familiar with the general guide for [Events & Messaging in CAP](../messaging/), as it already covers the majority of the content.
+
+
+### Prerequisite: Setup SAP Event Broker
+
+// TODO: the guide is not yet published!!!
+
+Follow guide _SAP Event Broker Service Guide_ &rarr; _Integration Scenarios_ &rarr; [CAP Application as a Subscriber](https://help.sap.com/docs/event-broker/event-broker-draft-service/integration-example-using-cap-application?state=DRAFT) to prepare your SAP BTP account for event consumption.
+
+
+### Add Events and Handlers
+
+There are three options for adding the events that shall be consumed to your model, and subsequently registering event handlers for the same.
+
+#### 1. Import and Augment
+
+This approach is described in [Events from SAP S/4HANA](../messaging/#events-from-sap-s-4hana), [Receiving Events from SAP S/4HANA Cloud Systems](../messaging/s4), and specifically [Consume Events Agnostically](../messaging/s4#consume-events-agnostically) regarding handler registration.
+
+#### 2. Decoupled
+
+In the second option, you define the event manually in any service, but link it to the respective cloud event type via `@topic`.
+
+```cds
+service Foo {
+  event Bar @(topic:'my.name.space.myentity.myoperation.v1') {
+    baz: String;
+  }
+}
+```
+```js
+Foo.on('Bar', msg => { ... })
+```
+
+#### 3. Using Low-Level Messaging
+
+As a third option, you can skip the modeling part and simply use [Low-Level Messaging](../messaging/s4#using-low-level-messaging).
+However, please note that future [Open Resource Discovery (ORD)](https://sap.github.io/open-resource-discovery/) integration will most likely benefit from modeled approaches.
+
+
+### Use `event-broker`
+
+Add the following to your _package.json_ to use SAP Event Broker:
+
+```jsonc
+"cds": {
+  "requires": {
+    "messaging": {
+      "[production]": {
+        "kind": "event-broker"
+      }
+    }
+  }
+}
+```
+
+[Learn more about `cds.env` profiles](../../node.js/cds-env#profiles){.learn-more}
+
+For more details on how to configure using SAP Event Broker, see _Node.js_ &rarr; _Messaging_ &rarr; _Message Brokers_ &rarr; [SAP Event Broker](../../node.js/messaging#sap-event-broker).
+
+
+### Deploy to the Cloud (with MTA)
+
+Please see [Deploy to Cloud Foundry](../deployment/to-cf) regarding deployment with MTA.
+
+The following mta.yaml snippet ensures the sequential creation of the SAP Event Broker and IAS service instances, as well as binds the application to both service instances with the respectively necessary configuration.
+
+```yaml
+ID: cap.incidents
+
+modules:
+  - name: incidents-srv
+    provides:
+      - name: incidents-srv-api
+        properties:
+          url: ${default-url} #> needed in webhookUrl and home-url below
+    requires:
+      - name: incidents-event-broker
+        parameters:
+          config:
+            authentication-type: X509_IAS
+      - name: incidents-ias
+        parameters:
+          config:
+            credential-type: X509_GENERATED
+            app-identifier: cap.incidents #> any value, e.g., reuse MTA ID
+
+resources:
+  - name: incidents-event-broker
+    type: org.cloudfoundry.managed-service
+    parameters:
+      service: event-broker
+      service-plan: event-connectivity
+      config:
+        # unique identifier for this event broker instance
+        # should start with own namespace (i.e., "foo.bar") and may not be longer than 15 characters
+        systemNamespace: cap.incidents
+        webhookUrl: ~{incidents-srv-api/url}/-/cds/event-broker/webhook
+    requires:
+      - name: incidents-srv-api
+  - name: incidents-ias
+    type: org.cloudfoundry.managed-service
+    requires:
+      - name: incidents-srv-api
+    processed-after:
+      # for consumed-services (cf. below), incidents-event-broker must already exist
+      # -> ensure incidents-ias is created after incidents-event-broker
+      - incidents-event-broker
+    parameters:
+      service: identity
+      service-plan: application
+      config:
+        consumed-services:
+          - service-instance-name: incidents-event-broker
+        display-name: cap.incidents #> any value, e.g., reuse MTA ID
+        home-url: ~{incidents-srv-api/url}
+```
+
+Please note that the mta.yaml snippet above is based on the sample app [@capire/incidents](https://github.com/cap-js/incidents-app/tree/event-broker), i.e., ID, module, and resource names are taken from this context and need to be adjusted.
+
+The full `mta.yaml` of the sample application can be found [here](https://github.com/cap-js/incidents-app/blob/event-broker/mta.yaml).
+
+
+### End-to-End Test
+
+You can conduct an end-to-end test of your finalized setup by executing the following steps.
+
+#### 1. Add Integration Dependency
+
+In BTP Cockpit &rarr; System Landscape, navigate to the system that represents your CAP application.
+Add an _Integration Dependency_ using the _Simplified Business Eventing Template_ for _Event Type_ `sap.eee.iwxbe.testproducer.v1.Event.Created.v1` and _Publishing System Namespace_ `sap.s4` as shown in the following screenshot.
+
+![Integration Dependency for Test Event](assets/event-broker-test-integraion-dependency.png)
+
+#### 2. Activate Event Subscription
+
+In SAP Event Broker Application, activate the subscription for the added integration dependency (cf. [Enabling SAP Event Subscriptions](https://help.sap.com/docs/event-broker/event-broker-service-guide/enable-subscriptions)).
+
+#### 3. Trigger Test Event
+
+In S/4HANA Cloud, navigate to application _Enterprise Event Enablement - Event Monitor_ and navigate into the channel you created during setup.
+On the top right, press button _Produce Test Event_.
+This will add an entry in the list of _Outbound Events_ with topic `na/na/na/ce/sap/eee/iwxbe/testproducer/v1/Event/Created/v1` and, eventually, status _Acknowledged_.
+
+#### 4. Check Application Logs
+
+In the application logs of your CAP application, check for a log entry noting the successful the event reception as shown in the following screenshot.
+
+![Log Entry for Test Event](assets/event-broker-test-log-entry.png)
+
+
+<!-- TODO
+
+### Hybrid Testing
+
+Possible? If yes, how?
+
+-->
+
+
+
+<span id="eventbrokersaasconsuming" />
+
+<span id="eventbrokersaaspublishing" />

guides/messaging/event-mesh.md

@@ -6,7 +6,7 @@ status: released
 
 # Using SAP Event Mesh in Cloud Foundry
 
-[SAP Event Mesh](https://help.sap.com/docs/SAP_EM) is the default offering for messaging in SAP Business Technology Platform (SAP BTP). CAP provides out-of-the-box support for SAP Event Mesh, and automatically handles many things behind the scenes, so that application coding stays agnostic and focused on conceptual messaging.
+CAP provides out-of-the-box support for [SAP Event Mesh](https://help.sap.com/docs/event-mesh), and automatically handles many things behind the scenes, so that application coding stays agnostic and focused on conceptual messaging.
 
 ::: warning
 The following guide is based on a productive (paid) account on SAP BTP. It's not supported to use the trial offering of SAP Event Mesh.

guides/messaging/index.md

@@ -578,11 +578,38 @@ Find additional information about deploying SAP Event Mesh on SAP BTP in this gu
 
 
 
+## [Using SAP Event Broker](./event-broker) {#sap-event-broker}
+
+CAP has growing out-of-the-box support for SAP Event Broker.
+As an application developer, all you need to do is configuring CAP to use `event-broker`, as in this excerpt from a _package.json_:
+
+```jsonc
+"cds": {
+  "requires": {
+    "messaging": {
+      "[production]": {
+        "kind": "event-broker"
+      }
+    }
+  }
+}
+```
+
+[Learn more about `cds.env` profiles](../../node.js/cds-env#profiles){.learn-more}
+
+
+::: tip Read the guide
+Find additional information about deploying SAP Event Broper on SAP BTP in this guide:
+[→ **_Using SAP Event Broker in BTP_**](./event-broker)
+:::
+
+
+
 ## [Events from SAP S/4HANA](./s4)
 <!-- {.toc-redirect} -->
 
-SAP S/4HANA integrates SAP Event Mesh for messaging. That makes it relatively easy
-for CAP-based applications to receive events from SAP S/4HANA systems.
+SAP S/4HANA integrates SAP Event Mesh as well as SAP Event Broker for messaging.
+That makes it relatively easy for CAP-based applications to receive events from SAP S/4HANA systems.
 
 In contrast to CAP, the asynchronous APIs of SAP S/4HANA are separate from the synchronous ones (OData, REST).
 So, the effort on the CAP side is to fill this gap.

guides/messaging/s4.md

@@ -5,8 +5,8 @@ status: released
 
 # Receiving Events from SAP S/4HANA Cloud Systems
 
-SAP S/4HANA integrates SAP Event Mesh for messaging, hence it's relatively easy
-for CAP-based application to receive events from SAP S/4HANA systems.
+SAP S/4HANA integrates SAP Event Mesh as well as SAP Event Broker for messaging.
+Hence, it is relatively easy for CAP-based application to receive events from SAP S/4HANA systems.
 This guide provides detailed information on that.
 
 ::: tip See also:
@@ -81,9 +81,12 @@ S4bupa.on ('BusinessPartner.Changed', msg => {...})
 ```
 
 
-## Configure SAP Event Mesh
+## Configure CAP
 
-To ease the pain of the afore-mentioned topic rewriting effects, CAP has built-in support for [SAP Event Mesh](./event-mesh). Configure the messaging service as follows, to let it automatically create correct technical topics to subscribe to SAP S/4HANA events:
+To ease the pain of the afore-mentioned topic rewriting effects, CAP has built-in support for [SAP Event Mesh](./event-mesh) as well as [SAP Event Broker](./event-broker).
+Configure the messaging service as follows, to let it automatically create correct technical topics to subscribe to SAP S/4HANA events:
+
+For SAP Event Mesh:
 
 ```json
 "cds": {
@@ -101,6 +104,18 @@ To ease the pain of the afore-mentioned topic rewriting effects, CAP has built-i
 
 **Note:** In contrast to the default configuration recommended in the [SAP Event Mesh documentation](https://help.sap.com/docs/SAP_EM/bf82e6b26456494cbdd197057c09979f/5499e2e74e674c69b057072272c80d4f.html), ensure you configure your service instance to allow the pattern `+/+/+/ce/*` for subscriptions. That is, **do not** restrict `subscribeFilter`s to `${namespace}`!
 
+For SAP Event Broker:
+
+```json
+"cds": {
+  "requires": {
+    "messaging": {
+      "kind": "event-broker"
+    }
+  }
+}
+```
+
 With that, your developers can enter event names as they're found on SAP Business Accelerator Hub. And our CDS extensions, as previously described, simplify to that definition:
 
 ```cds
@@ -117,17 +132,19 @@ extend service S4 with {
 ```
 
 
-
-
 ## Configure SAP S/4HANA
 
-As a prerequisite for consuming SAP S/4HANA events, the SAP S/4HANA system itself needs to be configured to send out specific event messages to a specific SAP Event Mesh service instance. How to create an SAP Event Mesh service instance and use it with a CAP application was already described in the previous sections. A description of how to configure an SAP S/4HANA system to send out specific events is out of scope of this documentation here. See [this documentation](https://help.sap.com/docs/BTP/65de2977205c403bbc107264b8eccf4b/d476ff058bf1413a9505c5c25cfce86b.html) for more details.
+As a prerequisite for consuming SAP S/4HANA events, the SAP S/4HANA system itself needs to be configured to send out specific event messages to a specific SAP Event Mesh or SAP Event Broker service instance.
+How to create the necessary service instances and use them with a CAP application was already described in the previous sections [SAP Event Mesh](./event-mesh) and [SAP Event Broker](./event-broker), respectively.
+A description of how to configure an SAP S/4HANA system to send out specific events is out of scope of this documentation here.
+See [this documentation](https://help.sap.com/docs/SAP_S4HANA_CLOUD/0f69f8fb28ac4bf48d2b57b9637e81fa/82e97d5329044732af1efd996bfdc2ab.html) for more details.
+
 
 ## Using Low-Level Messaging
 
 Instead of adding events found on [SAP Business Accelerator Hub](https://api.sap.com/content-type/Events/events/packages) to a CDS service model, it's also possible to use a messaging service directly to consume events from SAP S/4HANA.
 
-You have to bind the `messaging` service directly to the SAP Event Mesh service instance that the SAP S/4HANA system sends the event messages to. Then you can consume the event by registering a handler on the `type` of the event that should be received (`sap.s4.beh.businesspartner.v1.BusinessPartner.Changed.v1` in the example):
+You have to bind the `messaging` service directly to the SAP Event Mesh or SAP Event Broker service instance that the SAP S/4HANA system sends the event messages to. Then you can consume the event by registering a handler on the `type` of the event that should be received (`sap.s4.beh.businesspartner.v1.BusinessPartner.Changed.v1` in the example):
 
 ```js
 const messaging = await cds.connect.to ('messaging')

menu.md

@@ -43,8 +43,9 @@
 
 - [Events & Messaging](guides/messaging/)
 
-  - [Events from S/4](guides/messaging/s4)
   - [SAP Event Mesh](guides/messaging/event-mesh)
+  - [SAP Event Broker](guides/messaging/event-broker)
+  - [Events from S/4](guides/messaging/s4)
 
 - [Protocols/APIs](advanced/publishing-apis/)
 

node.js/messaging.md

@@ -399,12 +399,43 @@ If you enable the [cors middleware](https://www.npmjs.com/package/cors), [handsh
 
 <span id="aftereventmesh" />
 
+### SAP Event Broker <Beta/>
+
+`kind`: `event-broker`
+
+Use this if you want to communicate using [SAP Event Broker](https://help.sap.com/docs/event-broker).
+
+```jsonc
+"cds": {
+  "requires": {
+    "messaging": {
+      "kind": "event-broker"
+    }
+  }
+}
+```
+
+Authentication in the SAP Event Broker integration is based on the [Identity Authentication service (IAS)](https://help.sap.com/docs/cloud-identity-services/cloud-identity-services/getting-started-with-identity-service-of-sap-btp) of [SAP Cloud Identity Services](https://help.sap.com/docs/cloud-identity-services).
+If you are not using [IAS-based Authentication](./authentication#ias), you will need to trigger the loading of the IAS credentials into your app's `cds.env` via an additional `requires` entry:
+
+```jsonc
+"cds": {
+  "requires": {
+    "ias": { //> any name
+      "vcap": {
+        "label": "identity"
+      }
+    }
+  }
+}
+```
+
+<div id="aftereventbroker" />
+
 <div id="queuing-sap" />
 
 <div id="kafka-sap" />
 
-<div id="event-broker-sap" />
-
 ### Redis PubSub <Beta />
 ::: warning
 This is a beta feature. Beta features aren't part of the officially delivered scope that SAP guarantees for future releases.