From c030a5788946031e938c32d735796e7bb329e76a Mon Sep 17 00:00:00 2001 From: Heikki Hellgren Date: Wed, 10 Apr 2024 10:05:39 +0300 Subject: [PATCH] docs: improve explanation of notification processors Signed-off-by: Heikki Hellgren --- plugins/notifications-common/src/types.ts | 54 ++++++++++++++++++++ plugins/notifications-node/api-report.md | 2 +- plugins/notifications-node/src/extensions.ts | 37 +++++++++++--- 3 files changed, 85 insertions(+), 8 deletions(-) diff --git a/plugins/notifications-common/src/types.ts b/plugins/notifications-common/src/types.ts index 30bb00b727..b9c9f63489 100644 --- a/plugins/notifications-common/src/types.ts +++ b/plugins/notifications-common/src/types.ts @@ -19,32 +19,86 @@ export type NotificationSeverity = 'critical' | 'high' | 'normal' | 'low'; /** @public */ export type NotificationPayload = { + /** + * Notification title + */ title: string; + /** + * Optional longer description for the notification + */ description?: string; + /** + * Optional link where the notification is pointing to + */ link?: string; // TODO: Add support for additional links // additionalLinks?: string[]; + /** + * Notification severity, defaults to 'normal' + */ severity?: NotificationSeverity; + /** + * Optional notification topic + */ topic?: string; + /** + * Notification scope, can be used to re-send same notifications in case + * the scope and origin matches. + */ scope?: string; + /** + * Optional notification icon + */ icon?: string; }; /** @public */ export type Notification = { + /** + * Unique identifier for the notification + */ id: string; + /** + * The user entity reference that the notification is targeted to or null + * for broadcast notifications + */ user: string | null; + /** + * Notification creation date + */ created: Date; + /** + * If user has saved the notification, the date when it was saved + */ saved?: Date; + /** + * If user has read the notification, the date when it was read + */ read?: Date; + /** + * If the notification has been updated due to it being in the same scope + * and from same origin as previous notification, the date when it was updated + */ updated?: Date; + /** + * Origin of the notification as in the reference to sender + */ origin: string; + /** + * Actual notification payload + */ payload: NotificationPayload; }; /** @public */ export type NotificationStatus = { + /** + * Total number of unread notifications for the user + */ unread: number; + /** + * Total number of read notifications for the user + */ read: number; }; diff --git a/plugins/notifications-node/api-report.md b/plugins/notifications-node/api-report.md index ff995e9258..a16c141c41 100644 --- a/plugins/notifications-node/api-report.md +++ b/plugins/notifications-node/api-report.md @@ -20,7 +20,7 @@ export class DefaultNotificationService implements NotificationService { send(notification: NotificationSendOptions): Promise; } -// @public (undocumented) +// @public export interface NotificationProcessor { getName(): string; postProcess?( diff --git a/plugins/notifications-node/src/extensions.ts b/plugins/notifications-node/src/extensions.ts index 0a7aa0b932..6461c3dc89 100644 --- a/plugins/notifications-node/src/extensions.ts +++ b/plugins/notifications-node/src/extensions.ts @@ -18,6 +18,21 @@ import { Notification } from '@backstage/plugin-notifications-common'; import { NotificationSendOptions } from './service'; /** + * Notification processors are used to modify the notification parameters or sending the notifications + * to external systems. + * + * Notification modules should utilize the `notificationsProcessingExtensionPoint` to add new processors + * to the system. + * + * Notification processing flow: + * + * 1. New notification send request is received + * 2. For all notification processors registered, processOptions function is called to process the notification options + * 3. Notification recipients are resolved from the options + * 4. For each recipient, preProcess function is called to pre-process the notification + * 5. Notification is saved to the database and sent to the Backstage UI + * 6. For each recipient, postProcess function is called to post-process the notification + * * @public */ export interface NotificationProcessor { @@ -29,8 +44,11 @@ export interface NotificationProcessor { /** * Process the notification options. * - * This can be used to modify the options before sending the notification or even sending the notification to - * external services. This function is called only once for each notification before processing it. + * Can be used to override the default recipient resolving, sending the notification to an + * external service or modify other notification options necessary. + * + * processOptions functions are called only once for each notification before the recipient resolving, + * pre-process, sending and post-process of the notification. * * @param options - The original options to send the notification */ @@ -42,10 +60,13 @@ export interface NotificationProcessor { * Pre-process notification before sending it to Backstage UI. * * Can be used to send the notification to external services or to decorate the notification with additional - * information. This function is called for each notification recipient individually or once for broadcast - * notification. + * information. The notification is saved to database and sent to Backstage UI after all pre-process functions + * have run. The notification options passed here are already processed by processOptions functionality. * - * @param notification - The notification to decorate + * preProcess functions are called for each notification recipient individually or once for broadcast + * notification BEFORE the notification has been sent to the Backstage UI. + * + * @param notification - The notification to send * @param options - The options to send the notification * @returns The same notification or a modified version of it */ @@ -57,8 +78,10 @@ export interface NotificationProcessor { /** * Post process notification after sending it to Backstage UI. * - * Can be used to send the notification to external services. This function is called for each notification - * recipient individually or once for broadcast notification. + * Can be used to send the notification to external services. + * + * postProcess functions are called for each notification recipient individually or once for + * broadcast notification AFTER the notification has been sent to the Backstage UI. * * @param notification - The notification to send * @param options - The options to send the notification