Getting Started
The Backstage Notifications System provides a way for plugins and external services to send notifications to Backstage users. These notifications are displayed in the dedicated page of the Backstage frontend UI or by frontend plugins per specific scenarios. Additionally, notifications can be sent to external channels (like email) via "processors" implemented within plugins.
Notifications can be optionally extended with the signals plugin, which provides a push mechanism to ensure users receive notifications immediately.
Upgrade to the latest version of Backstage
To ensure your version of Backstage has all the latest notifications and signals related functionality, it’s important to upgrade to the latest version. The Backstage upgrade helper is a great tool to help ensure that you’ve made all the necessary changes during the upgrade!
About notifications
Notifications are messages sent to either individual users or groups. They are not intended for inter-process communication of any kind.
There are two basic types of notifications:
- Broadcast: Messages sent to all users of Backstage.
- Entity: Messages delivered to specific listed entities, such as Users or Groups.
Example of use-cases:
- System-wide announcements or alerts
- Notifications for component owners, e.g. build failures, successful deployments, new vulnerabilities
- Notifications for individuals, e.g. updates you have subscribed to, new required training courses
- Notifications pertaining to a particular entity in the catalog: A notification might apply to an entity and the owning team.
Installation
As of the 1.42.0
release of Backstage, Notifications and Signals are installed as part of the default @backstage/create-app
instance which means you won't need to follow the installations steps outlined here. The only exception to this is adding the Notifications tab to User Settings to allow managing these settings.
The following sections will walk you through the installation of the various parts of the Backstage Notification System.
Add Notifications Backend
First we need to add the backend package:
yarn --cwd packages/backend add @backstage/plugin-notifications-backend
Then we need to add it to our backend:
const backend = createBackend();
// ...
backend.add(import('@backstage/plugin-notifications-backend'));
Add Notifications Frontend
First we need to add the frontend package:
yarn --cwd packages/app add @backstage/plugin-notifications
To add the notifications main menu, add the following:
import { NotificationsSidebarItem } from '@backstage/plugin-notifications';
<SidebarPage>
<Sidebar>
<SidebarGroup>
// ...
<NotificationsSidebarItem />
</SidebarGroup>
</Sidebar>
</SidebarPage>;
Also add the route to notifications:
import { NotificationsPage } from '@backstage/plugin-notifications';
<FlatRoutes>
// ...
<Route path="/notifications" element={<NotificationsPage />} />
</FlatRoutes>;
Optional: Add Signals
The use of signals is optional but improves the user experience.