From d61b0e1695b8220c853af2ea9f948e56c58940c0 Mon Sep 17 00:00:00 2001 From: Heikki Hellgren Date: Mon, 18 Dec 2023 09:18:17 +0200 Subject: [PATCH] docs: add installation documentation for notifications Signed-off-by: Heikki Hellgren --- plugins/notifications-backend/README.md | 39 ++++++++++++++---- plugins/notifications-node/README.md | 55 ++++++++++++++++++++++++- plugins/notifications/README.md | 36 ++++++++++++++-- 3 files changed, 118 insertions(+), 12 deletions(-) diff --git a/plugins/notifications-backend/README.md b/plugins/notifications-backend/README.md index e90d287049..bb965b6695 100644 --- a/plugins/notifications-backend/README.md +++ b/plugins/notifications-backend/README.md @@ -2,13 +2,38 @@ Welcome to the notifications backend plugin! -_This plugin was created through the Backstage CLI_ - ## Getting started -Your plugin has been added to the example app in this repository, meaning you'll be able to access it by running `yarn -start` in the root directory, and then navigating to [/notifications](http://localhost:3000/notifications). +First you have to install the `@backstage/plugin-notifications-node` package. -You can also serve the plugin in isolation by running `yarn start` in the plugin directory. -This method of serving the plugin provides quicker iteration speed and a faster startup and hot reloads. -It is only meant for local development, and the setup for it can be found inside the [/dev](/dev) directory. +Then create a new file to `packages/backend/src/plugins/notifications.ts`: + +```ts +import { createRouter } from '@backstage/plugin-notifications-backend'; +import { Router } from 'express'; +import { PluginEnvironment } from '../types'; + +export default async function createPlugin( + env: PluginEnvironment, +): Promise { + return await createRouter({ + logger: env.logger, + identity: env.identity, + notificationService: env.notificationService, + }); +} +``` + +and add it to `packages/backend/src/index.ts`: + +```ts +async function main() { + //... + const notificationsEnv = useHotMemoize(module, () => + createEnv('notifications'), + ); + + // ... + apiRouter.use('/notifications', await notifications(notificationsEnv)); +} +``` diff --git a/plugins/notifications-node/README.md b/plugins/notifications-node/README.md index 4cf460c3fe..2a1e61638d 100644 --- a/plugins/notifications-node/README.md +++ b/plugins/notifications-node/README.md @@ -2,4 +2,57 @@ Welcome to the Node.js library package for the notifications plugin! -_This plugin was created through the Backstage CLI_ +## 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`: + +```ts +import { NotificationService } from '@backstage/plugin-notifications-node'; + +function makeCreateEnv(config: Config) { + // ... + const notificationService = NotificationService.create({ + database: databaseManager.forPlugin('notifications'), + discovery, + }); + // ... + return (plugin: string): PluginEnvironment => { + // ... + return { + // ... + notificationService, + }; + }; +} +``` + +`types.ts`: + +```ts +import { NotificationService } from '@backstage/plugin-notifications-node'; +export type PluginEnvironment = { + // ... + notificationService: NotificationService; +}; +``` + +You also need to set up the `@backstage/plugin-notifications-backend` and `@backstage/plugin-notifications` +to be able to show notifications in the UI. + +## Sending notifications + +To send notifications from backend plugin, use the `NotificationService::send` functionality. This function will +save the notification and optionally signal the frontend to show the latest status for users. + +When sending notifications, you can specify the entity reference of the notification. If the entity reference is +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. + +## Extending Notification Service + +The `NotificationService` can be extended with `NotificationProcessor`. These processors allow to decorate notifications +before they are sent or/and send the notifications to external services. diff --git a/plugins/notifications/README.md b/plugins/notifications/README.md index 3eeac7a647..63212d2c16 100644 --- a/plugins/notifications/README.md +++ b/plugins/notifications/README.md @@ -6,8 +6,36 @@ _This plugin was created through the Backstage CLI_ ## Getting started -Your plugin has been added to the example app in this repository, meaning you'll be able to access it by running `yarn start` in the root directory, and then navigating to [/notifications](http://localhost:3000/notifications). +First, install the `@backstage/plugin-notifications-backend` and `@backstage/plugin-notifications-node` packages. +See the documentation for installation instructions. -You can also serve the plugin in isolation by running `yarn start` in the plugin directory. -This method of serving the plugin provides quicker iteration speed and a faster startup and hot reloads. -It is only meant for local development, and the setup for it can be found inside the [/dev](./dev) directory. +To add the notifications main menu, add the following to your `packages/app/src/components/Root/Root.tsx`: + +```tsx +import { NotificationsSidebarItem } from '@backstage/plugin-notifications'; + + + + + // ... + + + +; +``` + +Also add the route to notifications to `packages/app/src/App.tsx`: + +```tsx +import { NotificationsPage } from '@backstage/plugin-notifications'; + + + // ... + } /> +; +``` + +## Real-time notifications + +To be able to get real-time notifications to the UI without need for the user to refresh the page, you also need to +add `@backstage/plugin-signals` package to your installation.