diff --git a/about/features.md b/about/features.md index 29e9c0b9cf..ac3a30d637 100644 --- a/about/features.md +++ b/about/features.md @@ -178,15 +178,15 @@ Following is an index of the features currently covered by CAP, with status and ### Events / Messaging -| | CDS | Node.js | Java | -|-------------------------------------------------------------------------------------------------------------------------------------------------------------|:-----:|:------------:|:----:| -| [Declared Events in CDS](../cds/cdl#events) | | | | -| Mock Broker (to speed up local dev) [[Node.js](../node.js/messaging#file-based)\|[Java](../java/messaging#local-testing)] | | | | -| SAP Event Mesh (For single-tenant apps) [[Node.js](../node.js/messaging#event-mesh-shared)\|[Java](../java/messaging#configuring-sap-event-mesh-support)] | | | | -| SAP Cloud Application Event Hub (For single-tenant apps) [[Node.js](../node.js/messaging#event-broker)] | |
beta | | -| Composite Messaging (routing by configuration) [[Node.js](../node.js/messaging#composite-messaging)\|[Java](../java/messaging#composite-messaging-service)] | | | | -| Import AsyncAPI | | | | -| Export AsyncAPI | | | | +| | CDS | Node.js | Java | +|-------------------------------------------------------------------------------------------------------------------------------------------------------------|:-----:|:-------------------------:|:-------------------------:| +| [Declared Events in CDS](../cds/cdl#events) | | | | +| Mock Broker (to speed up local dev) [[Node.js](../node.js/messaging#file-based)\|[Java](../java/messaging#local-testing)] | | | | +| [SAP Cloud Application Event Hub](../guides/messaging/event-broker) | |
plugin |
plugin | +| [SAP Event Mesh](../guides/messaging/event-mesh) | | | | +| Composite Messaging (routing by configuration) [[Node.js](../node.js/messaging#composite-messaging)\|[Java](../java/messaging#composite-messaging-service)] | | | | +| Import AsyncAPI | | | | +| Export AsyncAPI | | | | diff --git a/about/index.md b/about/index.md index c014d019e3..3a0e9f5254 100644 --- a/about/index.md +++ b/about/index.md @@ -85,7 +85,7 @@ CAP provides mocked variants for several platform services out of the box, which | Database | SQLite, H2 in-memory | SAP HANA, PostgreSQL | | Authentication | Mocked Auth | SAP Identity Services | | App Gateway | None | SAP App Router | -| Messaging | File-based Queues | SAP Event Hub, Kafka, Redis, ... | +| Messaging | File-based Queues | SAP Cloud Appl. Event Hub, Kafka, Redis, ... | > [!tip] > @@ -223,7 +223,7 @@ That initiative happened to be successful, and gave a boost to a steadily **grow - [Open Telemetry → SAP Cloud Logging, Dynatrace, ...](../plugins/#telemetry) - [Attachments → SAP Object Store /S3](../plugins/#attachments) - [Attachments → SAP Document Management Service](../plugins/#@cap-js/sdm) -- [Messaging → SAP Cloud Application Event Hub](../plugins/#event-broker-plugin) +- [Messaging → SAP Cloud Application Event Hub](../plugins/#event-hub) - [Change Tracking](../plugins/#change-tracking) - [Notifications](../plugins/#notifications) - [Audit Logging → SAP Audit Logging](../plugins/#audit-logging) diff --git a/guides/messaging/event-broker.md b/guides/messaging/event-broker.md index 4f567632a5..36aa7def26 100644 --- a/guides/messaging/event-broker.md +++ b/guides/messaging/event-broker.md @@ -4,22 +4,6 @@ shorty: SAP Cloud Application Event Hub status: released --- - - - - - # Using SAP Cloud Application Event Hub in Cloud Foundry [SAP Cloud Application Event Hub](https://help.sap.com/docs/event-broker) is the new default offering for messaging in SAP Business Technology Platform (SAP BTP). @@ -31,175 +15,195 @@ The following guide is based on a productive (paid) account on SAP BTP. [[toc]] - - -## Consuming Events in a Stand-alone App { #consume-standalone } +## Prerequisite: Set up SAP Cloud Application Event Hub -This guide describes the end-to-end process of developing a stand-alone (or "single tenant") CAP application that consumes messages via SAP Cloud Application Event Hub. -The guide uses SAP S/4HANA as the event emitter, but this is a stand-in for any system that is able to publish CloudEvents via SAP Cloud Application Event Hub. +Follow guides [Initial Setup](https://help.sap.com/docs/sap-cloud-application-event-hub/sap-cloud-application-event-hub-service-guide/initial-setup) as well as [Integration Scenarios → CAP Application as a Consumer](https://help.sap.com/docs/sap-cloud-application-event-hub/sap-cloud-application-event-hub-service-guide/cap-application-as-subscriber) to set up SAP Cloud Application Event Hub in your account. -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 +## Configuration -From the perspective of a CAP developer, SAP Cloud Application Event Hub 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 guide, you should be familiar with the general guide for [Events & Messaging in CAP](../messaging/), as it already covers the majority of the content. +### Use `event-broker` in Node.js -Since SAP Cloud Application Event Hub is based on the [CloudEvents](https://cloudevents.io/) standard, the `@topic` annotation for events in your CDS model is interpreted as the CloudEvents `type` attribute. +Install plugin [`@cap-js/event-broker`](../../plugins/#event-hub): +```sh +npm add @cap-js/event-broker +``` -### Add Events and Handlers +And add the following to your _package.json_ to use SAP Cloud Application Event Hub: -There are two options for adding the events that shall be consumed to your model, and subsequently registering event handlers for the same. +```jsonc +"cds": { + "requires": { + "messaging": { + // kind "event-broker" is derived from the service's technical name + "[production]": { "kind": "event-broker" } + } + } +} +``` -#### 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. +[Learn more about configuring SAP Cloud Application Event Hub in CAP Node.js.](../../node.js/messaging#event-broker){.learn-more} -#### 2. Using Low-Level Messaging +[Learn more about `cds.env` profiles.](../../node.js/cds-env#profiles){.learn-more} -As a second 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-hub` in Java -### Use `event-broker` +Install plugin [`com.sap.cds:cds-feature-event-hub`](../../plugins/#event-hub) and add the following to your _application.yaml_ to use SAP Cloud Application Event Hub: -Configure your application to use the messaging service kind `event-broker` (derived from SAP Cloud Application Event Hub's technical name). +::: code-group +```xml [srv/pom.xml] + + com.sap.cds + cds-feature-event-hub + ${latest-version} + +``` -[Learn more about configuring SAP Cloud Application Event Hub in CAP Node.js](../../node.js/messaging#event-broker){.learn-more} - -[Learn more about `cds.env` profiles](../../node.js/cds-env#profiles){.learn-more} - -::: tip Local Testing -Since SAP Cloud Application Event Hub sends events via HTTP, you won't be able to receive events on your local machine unless you use a tunneling service. Therefore we recommend to use a messaging service of kind [`local-messaging`](../../node.js/messaging#local-messaging) for local testing. +```yaml [srv/src/main/resources/application.yaml] +cds: + messaging.services: + - name: "messaging-name" + kind: "event-hub" +``` ::: +[Find the latest version on Maven central.](https://central.sonatype.com/artifact/com.sap.cds/cds-feature-event-hub/versions){.learn-more} +[Learn more about configuring SAP Cloud Application Event Hub in CAP Java.](../../java/messaging#using-real-brokers){.learn-more} -### Deploy to the Cloud (with MTA) - -Please see [Deploy to Cloud Foundry](../deployment/to-cf) regarding deployment with MTA as well as the deployment section from [SAP Cloud Application Event Hub in CAP Node.js](../../node.js/messaging#event-broker). - - -### Connecting it All Together - -In SAP BTP System Landscape, add a new system of type `SAP BTP Application` for your CAP application including its integration dependencies, connect all involved systems (incl. SAP Cloud Application Event Hub) into a formation and enable the event subscription. - -For more details, please refer to guide [CAP Application as a Consumer](https://help.sap.com/docs/event-broker/event-broker-service-guide/cap-application-as-subscriber) in the official documentation of SAP Cloud Application Event Hub. - -::: tip Test Events -For testing purposes, SAP S/4HANA can send technical test events of type `sap.eee.iwxbe.testproducer.v1.Event.Created.v1` which your app can subscribe to. You can trigger such events with _Enterprise Event Enablement - Event Monitor_. -::: - +## Hybrid Testing - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +Since SAP Cloud Application Event Hub sends events via HTTP, you won't be able to receive events on your local machine unless you use a tunneling service. +Therefore we recommend to use a messaging service of kind [`local-messaging`](../../node.js/messaging#local-messaging) for local testing. - +::: code-group +```yaml [mta.yaml] +modules: + - name: incidents-srv + provides: + - name: incidents-srv-api + properties: + url: ${default-url} #> needed in references below +``` +::: - +### Bind the Service Instances + +Finally, we can bring it all together by binding the two service instances to the application. +The bindings must both be parameterized with `credential-type: X509_GENERATED` and `authentication-type: X509_IAS`, respectively, to enable Identity Authentication service-based authentication. + +::: code-group +```yaml {1-3} [mta.yaml] +modules: + - name: incidents-srv + provides: + - name: incidents-srv-api + properties: + url: ${default-url} + requires: #[!code focus:10] + - name: incidents-ias #[!code ++] + parameters: #[!code ++] + config: #[!code ++] + credential-type: X509_GENERATED #[!code ++] + app-identifier: cap.incidents #> any value, e.g., reuse MTA ID [!code ++] + - name: incidents-event-broker #[!code ++] + parameters: #[!code ++] + config: #[!code ++] + authentication-type: X509_IAS #[!code ++] +``` +::: - - - + diff --git a/guides/messaging/index.md b/guides/messaging/index.md index cf2a9a0fea..f55a3a4d14 100644 --- a/guides/messaging/index.md +++ b/guides/messaging/index.md @@ -554,18 +554,17 @@ Application developers shouldn't have to care for such technical details. CAP en -## [Using SAP Event Mesh](./event-mesh) {#sap-event-mesh} +## [Using SAP Cloud Application Event Hub](./event-broker) {#sap-event-broker} -CAP has out-of-the-box support for SAP Event Mesh. -As an application developer, all you need to do is configuring CAP to use `enterprise-messaging`, usually in combination with `cloudevents` format, as in this excerpt from a _package.json_: +CAP has growing out-of-the-box support for SAP Cloud Application Event Hub. +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": "enterprise-messaging", - "format": "cloudevents" + "kind": "event-broker" } } } @@ -576,23 +575,24 @@ As an application developer, all you need to do is configuring CAP to use `enter ::: tip Read the guide -Find additional information about deploying SAP Event Mesh on SAP BTP in this guide: -[→ **_Using SAP Event Mesh in BTP_**](./event-mesh) +Find additional information about deploying SAP Cloud Application Event Hub on SAP BTP in this guide: +[→ **_Using SAP Cloud Application Event Hub in BTP_**](./event-broker) ::: -## [Using SAP Cloud Application Event Hub](./event-broker) {#sap-event-broker} +## [Using SAP Event Mesh](./event-mesh) {#sap-event-mesh} -CAP has growing out-of-the-box support for SAP Cloud Application Event Hub. -As an application developer, all you need to do is configuring CAP to use `event-broker`, as in this excerpt from a _package.json_: +CAP has out-of-the-box support for SAP Event Mesh. +As an application developer, all you need to do is configuring CAP to use `enterprise-messaging`, usually in combination with `cloudevents` format, as in this excerpt from a _package.json_: ```jsonc "cds": { "requires": { "messaging": { "[production]": { - "kind": "event-broker" + "kind": "enterprise-messaging", + "format": "cloudevents" } } } @@ -603,8 +603,8 @@ As an application developer, all you need to do is configuring CAP to use `event ::: tip Read the guide -Find additional information about deploying SAP Event Broper on SAP BTP in this guide: -[→ **_Using SAP Cloud Application Event Hub in BTP_**](./event-broker) +Find additional information about deploying SAP Event Mesh on SAP BTP in this guide: +[→ **_Using SAP Event Mesh in BTP_**](./event-mesh) ::: diff --git a/java/messaging.md b/java/messaging.md index 05e8cab5f5..0893f3954b 100644 --- a/java/messaging.md +++ b/java/messaging.md @@ -285,6 +285,26 @@ cds: ``` ::: +#### Configuring SAP Cloud Application Event Hub Support: { #configuring-sap-event-hub-support} + +::: code-group +```xml [srv/pom.xml] + + com.sap.cds + cds-feature-event-hub + ${version} + +``` +```yaml [srv/src/main/resources/application.yaml] +cds: + messaging.services: + - name: "messaging-name" + kind: "event-hub" +``` +::: + +Support for SAP Cloud Application Event Hub is provided via [plugin](../plugins/#event-hub). + #### Configuring Redis PubSub Support : { #configuring-redis-pubsub-support-beta} diff --git a/menu.md b/menu.md index 3547a3ddb8..e373bfe69b 100644 --- a/menu.md +++ b/menu.md @@ -42,8 +42,8 @@ ## [Events & Messaging](guides/messaging/) + ### [SAP Cloud Appl. Event Hub](guides/messaging/event-broker) ### [SAP Event Mesh](guides/messaging/event-mesh) - ### [SAP Event Hub](guides/messaging/event-broker) ### [Apache Kafka](../guides/messaging/apache-kafka) ### [Events from S/4](guides/messaging/s4) @@ -164,4 +164,4 @@ ## [Telemetry](plugins/#telemetry) ## [Open Resource Discovery](plugins/#ord-open-resource-discovery) ## [CAP Operator for K8s](plugins/#cap-operator-plugin) -## [SAP Cloud Appl. Event Hub](plugins/#event-broker-plugin) +## [SAP Cloud Appl. Event Hub](plugins/#event-hub) diff --git a/node.js/messaging.md b/node.js/messaging.md index 4ad793faf9..5580a8a6e3 100644 --- a/node.js/messaging.md +++ b/node.js/messaging.md @@ -401,110 +401,14 @@ If you enable the [cors middleware](https://www.npmjs.com/package/cors), [handsh -### SAP Cloud Application Event Hub { #event-broker } +### SAP Cloud Application Event Hub { #event-broker } `kind`: `event-broker` Use this if you want to communicate using [SAP Cloud Application Event Hub](https://help.sap.com/docs/event-broker). The integration with SAP Cloud Application Event Hub is provided using the plugin [`@cap-js/event-broker`](https://github.com/cap-js/event-broker). -Hence, you first need to install the plugin: - -```bash -npm add @cap-js/event-broker -``` - -Then, set the `kind` of your messaging service to `event-broker`: - -```jsonc -"cds": { - "requires": { - "messaging": { - "kind": "event-broker" - } - } -} -``` - -The [CloudEvents](https://cloudevents.io/) format is enforced since it's required by SAP Cloud Application Event Hub. - -Authentication in the SAP Cloud Application Event Hub 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" - } - } - } -} -``` - -#### Deployment - -Your SAP Cloud Application Event Hub configuration must include your system namespace as well as the webhook URL. The binding parameters must set `"authentication-type": "X509_GENERATED"` to allow IAS-based authentication. -Your IAS instance must be configured to include your SAP Cloud Application Event Hub instance under `consumed-services` in order for your application to accept requests from SAP Cloud Application Event Hub. -Here's an example configuration based on the _mta.yaml_ file of the [@capire/incidents](https://github.com/cap-js/incidents-app/tree/event-broker) application, bringing it all together: - -::: code-group -```yaml [mta.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-ias - parameters: - config: - credential-type: X509_GENERATED - app-identifier: cap.incidents #> any value, e.g., reuse MTA ID - - name: incidents-event-broker - parameters: - config: - authentication-type: X509_IAS - -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 - xsuaa-cross-consumption: true #> if token exchange from IAS token to XSUAA token is needed - display-name: cap.incidents #> any value, e.g., reuse MTA ID - home-url: ~{incidents-srv-api/url} -``` -::: - - -
+Please see the plugin's [setup guide](https://github.com/cap-js/event-broker/blob/main/README.md#setup) for more details.
diff --git a/plugins/index.md b/plugins/index.md index 77a92deb1f..d19f5e3989 100644 --- a/plugins/index.md +++ b/plugins/index.md @@ -375,7 +375,7 @@ Available for: ![Java logo](../assets/logos/java.svg){style="height:3em; display:inline; margin:0 0.2em;"} -## SAP Cloud Application Event Hub {#event-broker-plugin} +## SAP Cloud Application Event Hub {#event-hub} The plugin provides out-of-the-box support for consuming events from [SAP Cloud Application Event Hub](https://discovery-center.cloud.sap/serviceCatalog/sap-event-hub) -- for example emitted by SAP S/4HANA Cloud -- in stand-alone CAP applications. @@ -384,11 +384,14 @@ const S4Bupa = await cds.connect.to ('API_BUSINESS_PARTNER') S4bupa.on ('BusinessPartner.Changed', msg => {...}) ``` +
+ For more details, please see [Events and Messaging → Using SAP Cloud Application Event Hub](../guides/messaging/#sap-event-broker). Available for: -[![Node.js](../assets/logos/nodejs.svg 'Link to the plugins repository.'){style="height:2.5em; display:inline; margin:0 0.2em;"}](https://github.com/cap-js/event-broker#readme) +[![Node.js logo](../assets/logos/nodejs.svg){style="height:2.5em; display:inline; margin:0 0.2em;"}](https://github.com/cap-js/event-broker#readme) +[![Java logo](../assets/logos/java.svg){style="height:3em; display:inline; margin:0 0.2em;"}](https://github.com/cap-java/cds-feature-event-hub#readme) ## ABAP RFC diff --git a/project-words.txt b/project-words.txt index c1ffb1a010..bc81821858 100644 --- a/project-words.txt +++ b/project-words.txt @@ -1,4 +1,5 @@ aggregatable +Appl Catweazle CMIS creat