-
-
Notifications
You must be signed in to change notification settings - Fork 154
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
[WIP] feature: Notifications API #1560
base: master
Are you sure you want to change the base?
Conversation
For raising and clearing Signal K standard alarm types with predefined (overridable) message text and methods.
Sorry - I have a bunch of gripes that I would like to see fixed in V2 notifications:
I like having @sbender9 you've dealt a lot more with notifications - thoughts on this? |
I don't disagree with your comments, while the intent of the PR was just to address the current alarms detailed in the spec, more than happy to evolve the discussion and the PR here. |
In response to the comments above I have updated the inital PR comment to reflect the change in focus from v1 standard alarms to the establishment of a Notifications API that aims to start addressing the concerns raised in @tkurki 's comments e.g. assigning an id which can be used for subsequent actions. In it's current form it can be considered a skeleton API profile (for interactive / client use) and interface method(s) (for plugins and data stream handlers) to raise, update and clear notifications in a consistent way. There is still much to do and also scenarios that have not yet been addressed, e.g. the handling of notifications originating from within Signal K deltas generated by external devices / sensors. |
I’ve been doing some work with Notifications recently which has prompted some thoughts...
P |
At this time, the working position is based on a fairly common notification / alarm lifecycle (well in my experience at least) where there are sources which can raise different types of alarms and there are "many eyes on glass" to take action as required.
Silencing the alarm is an "Action" but may not apply globally to the alarm but just to the console where the silence action was taken. There may be other actions that fall into a similar basket. There is clearly a need to agree the alarm / notification lifecycle to ensure the API and operation is fit for purpose and not unnecessarily complex. |
Absolutely the scope is all notifications to be actionable regardless of the source. |
This aligns with the current format of how of entries are returned in Signal K. |
The current approach is a rudimentary way to add notification ids and be backwards compatable with current operation. I expect that the underlying notification system will need to re-engineered as it will need to function quite differently to the way it does today (where they are effectively just another path). |
@panaaj - thank you for explaining current thinking on this. On the alarm life cycle front I worry about conflating the semantics of It even jars when I see the expression "Standard Alarms" which in my In my head the only Notification lifecycle events are create and destroy. I acknowledge, of course, that the obvious place to capture some alarm Thus, I remain concerned about reifying these somewhat-notification-related
when, debatably, they have nothing to do with a Notifcation per-se. Conditions like ACK and SILENCE are (to me) alarm related concepts. I have a plugin that forwards Notifications to the WAN by email and web-push and it is You will see how I got to the more general proposal of a tag for flagging things that, P |
This PR has been REFACTORED from the original scope which was:
"Introduce an API under
/signalk/v2/api/notifications
to provide support for raising and clearing alarms for the standard alarm types defined in the Signal K specification."to now addressing the comments regarding Signal K Notifications more generally and now provides the following capabilities:
Linked Issue #655
Features
To Do:
Overview
The Notifications API manages the raising, actioning and clearing of notifications.
It does this by providing:
In this way, notifications triggered by both stream data and client interactions are consistently represented in the Signal K data model and that actions (e.g. acknowledge, silence, etc) and their resulting status is preseved and available to all connected devices.
Additionally, the Notifications API applies a unique
id
to each notification which can be used in as an alternative to thepath
and$source
to identify a notification entry.Using the API Plugin Interface
The Notifications API exposes the
notify()
method for use by plugins for raising, updating and clearing notifications.app.notify(path, value, sourceId)
path
: Signal K path of the notificationvalue
: A validNotification
object ornull
if clearing a notification.sourceId
The source identifier associated with the notification.To raise (create) a new notification or update and existing notification call the method with a valid
Notification
object as thevalue
.string
value containing theid
of the new / updated notification.Example: Raise notification
To clear (cancel) a notification call the method with
null
as thevalue
.void
.Example: Clear notification
Using HTTP Endpoints
Raising a Notification
To create (or raise) a notification you submit a HTTP
PUT
request to the specifiedpath
under/signalk/v2/api/notifications
.Example: Raise notification
You can also provide additional data values associated with the alarm.
Example: Raise notification with temperature values
If the action is successful, a response containing the
id
of the notification is generated.Example response:
This
id
can be used to perform actions on the notification.Updating notification content
To update the information contained in a notification, you need to replace it by submitting another
HTTP PUT
request containing a the new values.You can either use the notification
path
orid
to update it.Example: Update notification by path
Example: Update notification by id
Clear a notification
To clear or cancel a notification submit a
HTTP DELETE
request to either the notificationpath
orid
.Example: Clear notification by path
Example: Clear notification by id
Additionally, you can clear a notification with a specific
$source
by providing the source value as a query parameter.Example: Clear notification by path created by
zone-watch
Acknowledge a notification
To acknowledge a notification, submit a
HTTP PUT
request tohttp://hostname:3000/signalk/v2/api/notifications/ack/<notification_path_or_id>
.This adds the
actions
property to the notification which holds a list of actions taken on the notification. "ACK" will be added to the list of actions when a notificationis acknowledged.Example: Acknowledge notification using a path
Example: Acknowledge notification using an id
Acknowledged notification response.
Standard Alarms
Standard alarms, such as Man Overboard, can be raised submitting a HTTP
POST
request to the specifiedalarm path
.These alarms will be raised by the server with pre-defined content.
Example: Raise Man Overboard Alarm
Notification content.
View / List notifications
View a specified notification
To view a specific notification submit a
HTTP GET
request to either the notificationpath
orid
.Example: Retrieve notification by path
Example: Retrieve notification by id
Response: Includes
path
attribute associated with the notification.Example: Retrieve notification by path with the specified $source
View a list notifications
A list of notifications generated using the Notifications API and be retrieved by submitting a
HTTP GET
request tohttp://hostname:3000/signalk/v2/api/notifications
.By default the list of notification objects will be keyed by their
path
.Example: Notification list keyed by path (default)
To view a list of notifications keyed by their identifier, add
key=id
to the request.