paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 35 Packages Projects Releases Wiki Activity

docs: improve explanation of notification processors

Browse Source 
Signed-off-by: Heikki Hellgren <heikki.hellgren@op.fi>
This commit is contained in:
Heikki Hellgren
2024-04-10 10:05:39 +03:00
parent 0d99528300
commit c030a57889
3 changed files with 85 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files
plugins/notifications-node/src/extensions.ts
+30 -7
View File
@@ -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