From 59fce6234cb832276234e9b6582eeab649ad1469 Mon Sep 17 00:00:00 2001 From: bnechyporenko Date: Tue, 30 Apr 2024 12:51:15 +0200 Subject: [PATCH 1/4] Request to modify a notification payload. Signed-off-by: bnechyporenko --- beps/0001-notifications-system/README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/beps/0001-notifications-system/README.md b/beps/0001-notifications-system/README.md index 4b4f3b0532..fb3e36f624 100644 --- a/beps/0001-notifications-system/README.md +++ b/beps/0001-notifications-system/README.md @@ -110,6 +110,7 @@ The notification backend stores notification using the [database service](https: - Topic (optional) - Scope (optional) - Icon (optional) + - Extra (optional) The recipients is **not** a list of users, but rather a filter that describes who should receive the notification. It must be possible to evaluate this filter in a database query, so that we can efficiently fetch all notifications for a given user. The same filter will also be used by the signal backend to determine which users should receive a signal. @@ -147,6 +148,8 @@ The link is a relative or absolute URL. As an example, it can be used: - by an external system to request an action within an asynchronous task - by a BE plugin to provide link to other part of the Backstage UI (i.e. to the Catalog) +The extra is a flexible JSON like field, where an additional payload can be stored. + The additional links are an array of title-URL pairs. They can represent immediate actions on the notification (i.e. yes-no) or lead the user to additional details. The `notification-backend` does not provide any new permissions, since creating notifications can only be done by other backend plugins, while reading notifications can only be done by the authenticated user. It is possible that we want to add a permissions for reading notifications, in particular for admin and impersonation use cases, but that is not part of this proposal or the initial implementation. From 110665bbd559a1fa22b27f3b7c68cbf71994f4c6 Mon Sep 17 00:00:00 2001 From: bnechyporenko Date: Fri, 3 May 2024 10:49:35 +0200 Subject: [PATCH 2/4] wip Signed-off-by: bnechyporenko --- beps/0001-notifications-system/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/beps/0001-notifications-system/README.md b/beps/0001-notifications-system/README.md index fb3e36f624..bde54208eb 100644 --- a/beps/0001-notifications-system/README.md +++ b/beps/0001-notifications-system/README.md @@ -110,7 +110,7 @@ The notification backend stores notification using the [database service](https: - Topic (optional) - Scope (optional) - Icon (optional) - - Extra (optional) + - Metadata (optional) The recipients is **not** a list of users, but rather a filter that describes who should receive the notification. It must be possible to evaluate this filter in a database query, so that we can efficiently fetch all notifications for a given user. The same filter will also be used by the signal backend to determine which users should receive a signal. @@ -148,7 +148,7 @@ The link is a relative or absolute URL. As an example, it can be used: - by an external system to request an action within an asynchronous task - by a BE plugin to provide link to other part of the Backstage UI (i.e. to the Catalog) -The extra is a flexible JSON like field, where an additional payload can be stored. +The metadata is a flexible JSON like field, where an additional payload can be stored. The additional links are an array of title-URL pairs. They can represent immediate actions on the notification (i.e. yes-no) or lead the user to additional details. From 07bcf8c1f77f53bb474b175975b17cbdcdce5add Mon Sep 17 00:00:00 2001 From: bnechyporenko Date: Thu, 16 May 2024 07:50:24 +0200 Subject: [PATCH 3/4] wip Signed-off-by: bnechyporenko --- beps/0001-notifications-system/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/beps/0001-notifications-system/README.md b/beps/0001-notifications-system/README.md index 06587f9e12..86b299387c 100644 --- a/beps/0001-notifications-system/README.md +++ b/beps/0001-notifications-system/README.md @@ -148,7 +148,7 @@ The link is a relative or absolute URL. As an example, it can be used: - by an external system to request an action within an asynchronous task - by a BE plugin to provide link to other part of the Backstage UI (i.e. to the Catalog) -The metadata is a flexible JSON like field, where an additional payload can be stored. +The metadata is an opaque JSON field, where an additional payload can be stored. The format of this data is owned by the notification sender and is tied to the notification topic, i.e. notifications sent from the source on the same topic should use a compatible metadata format. The primary purpose of this field is to allow for custom processing and rendering based on the additional metadata. The additional links are an array of title-URL pairs. They can represent immediate actions on the notification (i.e. yes-no) or lead the user to additional details. From 71123dc3ef0220fa0986d7f899fc1a95a9a74875 Mon Sep 17 00:00:00 2001 From: bnechyporenko Date: Thu, 16 May 2024 13:04:28 +0200 Subject: [PATCH 4/4] Incorporated the feedback Signed-off-by: bnechyporenko --- beps/0001-notifications-system/README.md | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/beps/0001-notifications-system/README.md b/beps/0001-notifications-system/README.md index 86b299387c..80751179dd 100644 --- a/beps/0001-notifications-system/README.md +++ b/beps/0001-notifications-system/README.md @@ -92,7 +92,7 @@ If the notification status is updated, the signal service shall emit a signal wi The role of the notifications plugin is to manage the lifecycle of notifications. The backend plugin provides an API for other backends to send notifications, as well as an accompanying [backend service](https://backstage.io/docs/backend-system/architecture/services). It also provides a separate API for the frontend plugin to read notifications for an individual user and manage the read status of notifications. -The notification backend stores notification using the [database service](https://backstage.io/docs/backend-system/core-services/index#database). In particular it needs to store the following information for each notification: +The notification backend stores notification using the [database service](https://backstage.io/docs/backend-system/core-services/index#database). In particular, it needs to store the following information for each notification: - ID - Recipients @@ -112,7 +112,7 @@ The notification backend stores notification using the [database service](https: - Icon (optional) - Metadata (optional) -The recipients is **not** a list of users, but rather a filter that describes who should receive the notification. It must be possible to evaluate this filter in a database query, so that we can efficiently fetch all notifications for a given user. The same filter will also be used by the signal backend to determine which users should receive a signal. +The recipients are **not** a list of users, but rather a filter that describes who should receive the notification. It must be possible to evaluate this filter in a database query, so that we can efficiently fetch all notifications for a given user. The same filter will also be used by the signal backend to determine which users should receive a signal. The read date is a timestamp of marking the notifications as read by the user. If missing, the notification is still unread. @@ -209,12 +209,16 @@ export type NotificationSeverity = 'critical' | 'high' | 'normal' | 'low'; export type NotificationPayload = { title: string; description?: string; - link: string; + link?: string; additionalLinks?: string[]; - severity: NotificationSeverity; + severity?: NotificationSeverity; topic?: string; scope?: string; icon?: string; + metadata?: Array<{ + type: string; + value: JsonValue; + }>; }; export type Notification = { @@ -239,7 +243,8 @@ interface NotificationService { } ``` -Each notification contains a human readable `title`, `origin` and optionally `link` for additional details. The `created`, `id`, `read` and `saved` properties are handled by the backend based and cannot be passed during the notification creation. +Each notification contains a human-readable `title`, `origin` and optionally `link` for additional details. The `created`, `id`, `read` and `saved` properties are handled by the backend based and cannot be passed during the notification creation. +Any optional additional details could be stored in `metadata`. We advise to provide the name to the type which contains the information about the context and the version, for example: 'core.icon.v1'. Calling `sendNotification` should never throw an error so that it doesn't block the current processing. Notifications should be considered as second-level citizens that are not critical if not delivered.