diff --git a/plugins/index.md b/plugins/index.md index 251b3d857..1f2d28d81 100644 --- a/plugins/index.md +++ b/plugins/index.md @@ -312,29 +312,91 @@ Available for: ## Notifications -The Notifications plugin provides support for publishing business notifications in SAP Build WorkZone. The client is implemented as a CAP service, which gives us a very simple programmatic API: +The Notifications plugin provides support for publishing business notifications in SAP Build Work Zone. Notification types are defined by annotating CDS events, which the plugin then intercepts and forwards automatically: -```js -let alert = await cds.connect.to ('notifications') -await alert.notify({ - recipients: [ ...supporters ], - title: `New incident created by ${customer.info}`, - description: incident.title +```cds +@notification: { + template: { + title : 'New incident: {{title}}', + publicTitle : 'New Incident', + subtitle : 'Created by {{customer}}', + groupedTitle : 'Incident Updates' + } +} +event IncidentCreated { + title : String; + customer : String; + recipients : String; +} +``` + +::: code-group + +```js [Node.js] +this.on('CREATE', 'Incidents', async req => { + await this.emit('IncidentCreated', { + title: req.data.title, + customer: customer.info, + recipients: [ ...supporters ], + }) }) ``` +```java [Java] +@Autowired +private NotificationService notificationService; + +@After(event = CqnService.EVENT_CREATE, entity = Incidents_.CDS_NAME) +public void afterIncidentCreated(Incidents incident) { + IncidentCreated data = IncidentCreated.create(); + data.setTitle(incident.getTitle()); + data.setCustomer(incident.getCustomer()); + data.setRecipients("supporter@example.com"); + + IncidentCreatedContext ctx = IncidentCreatedContext.create(); + ctx.setData(data); + notificationService.emit(ctx); +} +``` + +::: + +Alternatively, for Java you can use declarative `@notifications` on entities to trigger notifications automatically without writing handler code: + +```cds [Java] +service IncidentService { + @notifications : [{ + type : 'IncidentCreated', + on : ['CREATE'], + recipients : $self.createdBy, + parameters : { + title : $self.title, + customer : $self.customer + } + }] + entity Incidents as projection on my.Incidents; +} +``` + Features: -- CAP Services-based programmatic client API → simple, backend-agnostic -- Logging to console in development → fast turnarounds, minimized costs -- Transactional Outbox → maximised scalability and resilience -- Notification templates with i18n support -- Automatic lifecycle management of notification templates +- CAP service-based API — simple, backend-agnostic +- Notification types defined via CDS @notification annotations +- Notification types defined via JSON (Node.js only) +- Auto-emit: annotated CDS events are forwarded to ANS automatically +- Email delivery via configurable delivery channels +- Email HTML templates for rich email notifications +- Batch notifications — emit multiple notifications in a single call +- i18n support and dynamic priority for notification types +- Console logging in development — no external service needed +- Transactional outbox — maximised scalability and resilience +- Automatic registration and lifecycle management of notification types on startup Available for: [![Node.js](/logos/nodejs.svg 'Link to the plugins repository.'){style="height:2.5em; display:inline; margin:0 0.2em;"}](https://github.com/cap-js/notifications#readme) +[![Java](/logos/java.svg 'Link to the plugins repository.'){style="height:3em; display:inline; margin:0 0.2em;"}](https://github.com/cap-java/cds-feature-notifications#readme) ## Telemetry