wip: Improve messaging docs #2265

vkozyura · 2025-12-10T16:01:47Z

No description provided.

David-Kunz · 2025-12-11T08:28:20Z

node.js/messaging.md


+## Overview
+
+In SAP Cloud Application Programming Model (CAP), messaging enables decoupled communication between services using events. 


Suggested change

In SAP Cloud Application Programming Model (CAP), messaging enables decoupled communication between services using events.

Messaging enables decoupled communication between services using events.

David-Kunz · 2025-12-11T08:29:23Z

node.js/messaging.md

+## Overview
+
+In SAP Cloud Application Programming Model (CAP), messaging enables decoupled communication between services using events. 
+CAP distinguishes between the logical and technical messaging layers, separating business concerns from technical infrastructure and enabling both flexibility and scalability.


Suggested change

CAP distinguishes between the logical and technical messaging layers, separating business concerns from technical infrastructure and enabling both flexibility and scalability.

CAP distinguishes between the logical and technical messaging layers, separating business concerns from technical infrastructure.

Don't add AI slop ;)

David-Kunz · 2025-12-11T08:30:22Z

node.js/messaging.md

+
+**Modeled Events**: Events are defined in CDS models with typed schemas, providing compile-time validation and IDE support. These events represent business occurrences like `'orderProcessed'`, or `'stockUpdated'`.
+
+**Event Topics**: Topics organize events into logical channels, allowing for structured event categorization and routing. Topics can be explicitly defined or derived from service and event names.


"structured event categorization"? What is that?

David-Kunz · 2025-12-11T08:33:39Z

node.js/messaging.md

+
+The **technical layer** handles the actual message transport and delivery:
+
+**CAP Messaging Service**: Acts as the translation layer between logical events and technical infrastructure. It converts service-level event names to fully qualified names (e.g., `'OrderSrv.reviewed'`), manages topic resolution, message serialization, and routing logic.


Seems weird. Maybe "Logical events are delegated to the messaging service, the corresponding event name on the technical service is either the fully qualified event name or the value of the @topic annotation if given."

David-Kunz · 2025-12-11T11:58:12Z

node.js/messaging.md

+
+**Event Topics**: Topics organize events into logical channels, allowing for structured event categorization and routing. Topics can be explicitly defined or derived from service and event names.
+
+**CAP Services**: Services act as event producers and consumers, using simple APIs like `srv.emit('reviewed', data)` and `srv.on('orderProcessed', handler)`. Services communicate using friendly event names without needing to know the underlying infrastructure details.


Suggested change

**CAP Services**: Services act as event producers and consumers, using simple APIs like `srv.emit('reviewed', data)` and `srv.on('orderProcessed', handler)`. Services communicate using friendly event names without needing to know the underlying infrastructure details.

**CAP Services**: Services act as event producers or consumers, using simple APIs like `srv.emit('reviewed', data)` or `srv.on('orderProcessed', handler)`. Services communicate using friendly event names without needing to know the underlying infrastructure details.

David-Kunz · 2025-12-11T11:58:57Z

node.js/messaging.md

+
+The message flow follows a clear path through both layers:
+
+**Outbound Flow (Publisher)**: A service calls `srv.emit('reviewed', data)` → CAP Messaging Service resolves the event name to a fully qualified topic (e.g., `OrderSrv.reviewed`) → Message is serialized and sent to the Event Broker → Broker stores and distributes the message to all subscribers.


Maybe mention that A service is an own service (not an external one).

David-Kunz · 2025-12-11T11:59:53Z

node.js/messaging.md

+
+**Outbound Flow (Publisher)**: A service calls `srv.emit('reviewed', data)` → CAP Messaging Service resolves the event name to a fully qualified topic (e.g., `OrderSrv.reviewed`) → Message is serialized and sent to the Event Broker → Broker stores and distributes the message to all subscribers.
+
+**Inbound Flow (Subscriber)**: Event Broker delivers message from subscribed topic → CAP Messaging Service receives the message → Service name and event name are resolved from the topic → Message is routed to the appropriate service handler via `srv.on('reviewed', handler)`.


Maybe also mention that the existence of a srv.on event handler for moedelled event will cause the broker to listen to those (e.g. subscriptions for Event Mesh).

David-Kunz · 2025-12-11T12:00:47Z

node.js/messaging.md

+// Send messages directly with full topic control
+await messaging.emit('custom.topic', data);
+
+// Receive messages directly from any topic


Sounds a bit misleading, not any topic, but a particular topic.

David-Kunz · 2025-12-11T12:02:12Z

node.js/messaging.md

+When a CDS event is declared without an @topic annotation in a service (for example, an event called 'reviewed' in the OrderSrv service), the messaging behavior follows this pattern:
+
+**Emitting Events:**
+• Using the logical service API, you emit the event with just the event name ('reviewed')
+• Using the technical messaging API, you emit using the fully qualified name ('OrderSrv.reviewed')
+
+**Broker Handling:**
+• The message broker receives and routes the message using the topic 'OrderSrv.reviewed'
+
+**Receiving Events:**
+• Using the logical service API, you listen for the event with just the event name ('reviewed')
+• Using the technical messaging API, you listen using the fully qualified name ('OrderSrv.reviewed')
+
+#### Scenario 2: With @topic Annotation
+
+When a CDS event is declared with a custom @topic annotation (for example, an event called 'reviewed' with @topic: 'foo.bar' in the OrderSrv service), the messaging behavior follows this pattern:
+
+**Emitting Events:**
+• Using the logical service API, you still emit the event with the event name ('reviewed')
+• Using the technical messaging API, you emit using the custom topic name ('foo.bar')
+
+**Broker Handling:**
+• The message broker receives and routes the message using the custom topic 'foo.bar'
+
+**Receiving Events:**
+• Using the logical service API, you listen for the event with the event name ('reviewed')
+• Using the technical messaging API, you listen using the custom topic name ('foo.bar')


That's a lot of explanation for the topic mapping -> should be condensed

David-Kunz · 2025-12-11T12:03:09Z

node.js/messaging.md

+  await messaging.emit('cap/msg/system/my/custom/topic',
+   { ID, rating })

  // alternative if you want to send custom headers


headers can also be the 3rd argument, i.e. messaging.emit('topic', data, headers)

wip: Improve messaging docs

69ac1c2

vkozyura requested a review from smahati as a code owner December 10, 2025 16:01

vkozyura marked this pull request as draft December 10, 2025 16:01

small changes

63a1b15

David-Kunz reviewed Dec 11, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

wip: Improve messaging docs #2265

wip: Improve messaging docs #2265

Uh oh!

vkozyura commented Dec 10, 2025

Uh oh!

David-Kunz Dec 11, 2025

Uh oh!

David-Kunz Dec 11, 2025

Uh oh!

David-Kunz Dec 11, 2025

Uh oh!

David-Kunz Dec 11, 2025

Uh oh!

David-Kunz Dec 11, 2025 •

edited

Loading

Uh oh!

David-Kunz Dec 11, 2025

Uh oh!

David-Kunz Dec 11, 2025

Uh oh!

David-Kunz Dec 11, 2025

Uh oh!

David-Kunz Dec 11, 2025

Uh oh!

David-Kunz Dec 11, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants


		## Overview

		In SAP Cloud Application Programming Model (CAP), messaging enables decoupled communication between services using events.

	In SAP Cloud Application Programming Model (CAP), messaging enables decoupled communication between services using events.
	Messaging enables decoupled communication between services using events.

	CAP distinguishes between the logical and technical messaging layers, separating business concerns from technical infrastructure and enabling both flexibility and scalability.
	CAP distinguishes between the logical and technical messaging layers, separating business concerns from technical infrastructure.


		Modeled Events: Events are defined in CDS models with typed schemas, providing compile-time validation and IDE support. These events represent business occurrences like `'orderProcessed'`, or `'stockUpdated'`.

		Event Topics: Topics organize events into logical channels, allowing for structured event categorization and routing. Topics can be explicitly defined or derived from service and event names.


		The technical layer handles the actual message transport and delivery:

		CAP Messaging Service: Acts as the translation layer between logical events and technical infrastructure. It converts service-level event names to fully qualified names (e.g., `'OrderSrv.reviewed'`), manages topic resolution, message serialization, and routing logic.


		Event Topics: Topics organize events into logical channels, allowing for structured event categorization and routing. Topics can be explicitly defined or derived from service and event names.

		CAP Services: Services act as event producers and consumers, using simple APIs like `srv.emit('reviewed', data)` and `srv.on('orderProcessed', handler)`. Services communicate using friendly event names without needing to know the underlying infrastructure details.


		The message flow follows a clear path through both layers:

		Outbound Flow (Publisher): A service calls `srv.emit('reviewed', data)` → CAP Messaging Service resolves the event name to a fully qualified topic (e.g., `OrderSrv.reviewed`) → Message is serialized and sent to the Event Broker → Broker stores and distributes the message to all subscribers.


		Outbound Flow (Publisher): A service calls `srv.emit('reviewed', data)` → CAP Messaging Service resolves the event name to a fully qualified topic (e.g., `OrderSrv.reviewed`) → Message is serialized and sent to the Event Broker → Broker stores and distributes the message to all subscribers.

		Inbound Flow (Subscriber): Event Broker delivers message from subscribed topic → CAP Messaging Service receives the message → Service name and event name are resolved from the topic → Message is routed to the appropriate service handler via `srv.on('reviewed', handler)`.

wip: Improve messaging docs #2265

Are you sure you want to change the base?

wip: Improve messaging docs #2265

Uh oh!

Conversation

vkozyura commented Dec 10, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

David-Kunz Dec 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

David-Kunz Dec 11, 2025 •

edited

Loading