Merge pull request #24071 from drodil/notification_processor_improvement

feat: notification processor improvements

plugins/notifications-node/api-report.md

@@ -20,10 +20,20 @@ export class DefaultNotificationService implements NotificationService {
   send(notification: NotificationSendOptions): Promise<void>;
 }
 
-// @public (undocumented)
+// @public
 export interface NotificationProcessor {
-  decorate?(notification: Notification_2): Promise<Notification_2>;
-  send?(notification: Notification_2): Promise<void>;
+  getName(): string;
+  postProcess?(
+    notification: Notification_2,
+    options: NotificationSendOptions,
+  ): Promise<void>;
+  preProcess?(
+    notification: Notification_2,
+    options: NotificationSendOptions,
+  ): Promise<Notification_2>;
+  processOptions?(
+    options: NotificationSendOptions,
+  ): Promise<NotificationSendOptions>;
 }
 
 // @public (undocumented)

plugins/notifications-node/src/extensions.ts

@@ -15,25 +15,81 @@
  */
 import { createExtensionPoint } from '@backstage/backend-plugin-api';
 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 {
   /**
-   * Decorate notification before sending it
-   *
-   * @param notification - The notification to decorate
-   * @returns The same notification or a modified version of it
+   * Human-readable name of this processor like Email, Slack, etc.
    */
-  decorate?(notification: Notification): Promise<Notification>;
+  getName(): string;
 
   /**
-   * Send notification using this processor.
+   * Process the notification options.
+   *
+   * 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
+   */
+  processOptions?(
+    options: NotificationSendOptions,
+  ): Promise<NotificationSendOptions>;
+
+  /**
+   * 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. 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.
+   *
+   * 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
    */
-  send?(notification: Notification): Promise<void>;
+  preProcess?(
+    notification: Notification,
+    options: NotificationSendOptions,
+  ): Promise<Notification>;
+
+  /**
+   * Post process notification after sending it to Backstage UI.
+   *
+   * 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
+   */
+  postProcess?(
+    notification: Notification,
+    options: NotificationSendOptions,
+  ): Promise<void>;
 }
 
 /**