diff --git a/plugins/notifications-backend/README.md b/plugins/notifications-backend/README.md index e12f540aa5..38f8720f17 100644 --- a/plugins/notifications-backend/README.md +++ b/plugins/notifications-backend/README.md @@ -4,9 +4,6 @@ Welcome to the notifications backend plugin! ## Getting started -First you have to install `@backstage/plugin-notifications-node` and `@backstage/plugin-signals-node` -packages. - Add the notifications to your backend: ```ts @@ -15,7 +12,68 @@ const backend = createBackend(); backend.add(import('@backstage/plugin-notifications-backend')); ``` +For users to be able to see notifications in real-time, you have to install also +the signals plugin (`@backstage/plugin-signals-node`, `@backstage/plugin-signals-backend`, and +`@backstage/plugin-signals`). + ## Extending Notifications The notifications can be extended with `NotificationProcessor`. These processors allow to decorate notifications before they are sent or/and send the notifications to external services. + +Start off by creating a notification processor: + +```ts +import { Notification } from '@backstage/plugin-notifications-common'; +import { NotificationProcessor } from '@backstage/plugin-notifications-node'; + +class MyNotificationProcessor implements NotificationProcessor { + async decorate(notification: Notification): Promise { + if (notification.origin === 'plugin-my-plugin') { + notification.payload.icon = 'my-icon'; + } + return notification; + } + + async send(notification: Notification): Promise { + nodemailer.sendEmail({ + from: 'backstage', + to: 'user', + subject: notification.payload.title, + text: notification.payload.description, + }); + } +} +``` + +Both of the processing functions are optional, and you can implement only one of them. + +Add the notification processor to the notification system by: + +```ts +import { notificationsProcessingExtensionPoint } from '@backstage/plugin-notifications-node'; +import { Notification } from '@backstage/plugin-notifications-common'; + +export const myPlugin = createBackendPlugin({ + pluginId: 'myPlugin', + register(env) { + env.registerInit({ + deps: { + notifications: notificationsProcessingExtensionPoint, + // ... + }, + async init({ notifications }) { + // ... + notifications.addProcessor(new MyNotificationProcessor()); + }, + }); + }, +}); +``` + +## Sending notifications + +To be able to send notifications to users, you have to integrate the `@backstage/plugin-notifications-node` +to your application and plugins. +See [README](https://github.com/backstage/backstage/blob/master/plugins/plugin-notifications-node/README.md) +for more information. diff --git a/plugins/notifications-node/README.md b/plugins/notifications-node/README.md index 60d1e35c24..13475ab209 100644 --- a/plugins/notifications-node/README.md +++ b/plugins/notifications-node/README.md @@ -5,44 +5,34 @@ Welcome to the Node.js library package for the notifications plugin! ## Getting Started To be able to send notifications from other backend plugins, the `NotificationService` must be initialized for the -environment. This can be done by adding the following changes to `packages/backend/src/index.ts` and -`packages/backend/src/types.ts`: - -`index.ts`: +environment. Add notification service to your `plugin.ts` as a dependency for init ```ts -import { NotificationService } from '@backstage/plugin-notifications-node'; +import { notificationService } from '@backstage/plugin-notifications-node'; -function makeCreateEnv(config: Config) { - // ... - const defaultNotificationService = DefaultNotificationService.create({ - logger: root.child({ type: 'plugin' }), - discovery, - tokenManager, - signalService, - }); - - // ... - return (plugin: string): PluginEnvironment => { - // ... - const notificationService = defaultNotificationService.forPlugin(plugin); - - return { - // ... - notificationService, - }; - }; -} -``` - -`types.ts`: - -```ts -import { NotificationService } from '@backstage/plugin-notifications-node'; -export type PluginEnvironment = { - // ... - notificationService: NotificationService; -}; +export const myPlugin = createBackendPlugin({ + pluginId: 'myPlugin', + register(env) { + env.registerInit({ + deps: { + config: coreServices.rootConfig, + logger: coreServices.logger, + httpRouter: coreServices.httpRouter, + notificationService: notificationService, + }, + async init({ config, logger, httpRouter, notificationService }) { + httpRouter.use( + await createRouter({ + config, + logger, + permissions, + notificationService, + }), + ); + }, + }); + }, +}); ``` You also need to set up the `@backstage/plugin-notifications-backend` and `@backstage/plugin-notifications` @@ -57,5 +47,5 @@ When sending notifications, you can specify the entity reference of the notifica a user, the notification will be sent to only that user. If it's a group, the notification will be sent to all members of the group. If it's some other entity, the notification will be sent to the owner of that entity. -If the notification has `topic` set and user already has notification with that topic, the existing notification +If the notification has `scope` set and user already has notification with that scope, the existing notification will be updated with the new notification values and moved to inbox as unread.