# Notifications API

The Notifications API enables the raising, actioning and centralised management of Signal K notifications and their associated alarms.

## Overview

Notifications are a special type Signal K update delta that convey the occurrence of an event or change in condition.

They contain a `path` value that starts with the text `notifications` and a payload with specific attributes to indicate:

- The severity of the event / condition (`state`)
- How the event / condition should be indicated to the operator (`method`)
- What actions can be / have been taken (`status`)

The Notifications API introduces the following components into the Signal K server's delta processing chain:

1. Notification Manager: Provides centralised management for all notifications including the emission of notification deltas
2. Input Handler: Inspects all incoming deltas and routes notification messages (i.e. path starts with `notifications`) to the Notification Manager.
3. Notification API: REST endpoints for raising and actioning notifications and their associated alarm.

### Terminology

> The Signal K specification uses the terms `notification` and `alarm` interchangably, whilst Signal K Server assigns notification deltas originating from NMEA2000 alarm PGNs with attributes with the term `alert`.

For consistency and clarity this document will use the the following terminology:

- `notification` - A Signal K update delta message with a path starting with the text notifications.
- `alarm` - The communication of the event / condition to the operator.

### Initial Release

The initial release of the Notifications API implements core functionality to attribute Signal K notifications to allow them to be actioned and managed, regardless of their source. It does this by:

- Placing notifications into their own `update` in the delta message
- Assigning them a unique identifier
- Adding a `status` property to the payload
- Making available HTTP endpoints at `/signalk/v2/api/notifications` to perform actions.

> Note: Actions are only available for notifications containing a payload containing `state` and `method` properties.

### Target State

Subsequent releases of Signal K server will contain enhancements to the Notification API to implement the remaining functionality including:

- Creating and clearing notifications
- Managing Alarm lifecycle
- Raising specified alarms i.e. MOB
- Plugin interface

## Notification Payload

The Notification API adds the following attributes to the notification payload:

- `id` - Unique identifier for use when taking action.
- `status` - An object detailing the actions that can be and have been taken.

Example

    {
     "state": "...",
     "method": [..],
     "message": "...",
     "id": "a987be59-d26f-46db-afeb-83987b837a8f",
     "status": {
          "silenced": true,
          "acknowledged": false,
          "canSilence": true,
          "canAcknowledge": true,
          "canClear": true
       }
    }

### Notification Status

The `status` attribute is added to all notifications that have a payload containing `state` and `method` attributes.

The following status properties indicate the actions that CAN be taken. Their values are determined by the notification's `state` attribute:

- `canSilence` - indicates whether the Alarm associated with this notification can be silenced
- `canAcknowledge` - indicates whether the Alarm associated with this notification can be acknowledged
- `canClear` - Indicates that the associated Alarm can be cleared (triggering condition has been resolved). The value is `false` when the notification is not originated by the Notifcations API.

The remaining properties indicate the actions that HAVE been taken:

- `silenced` - `true` when silence action has been taken
- `acknowledged` - `true` when acknowledge action has been taken

## Taking Action

To take action on the alarm associated with a notification, send an HTTP POST request to `/signalk/v2/api/notifications/{notificationId}/{action}`.

### Silencing an Alarm

> Note: The silence action is only available for alarms associated with notifications having `status.canSilence = true`.

To silence the alarm send an HTTP POST request to `/signalk/v2/api/notifications/{notificationId}/silence`.

The result of a successful silence request is that the:

- `sound` value is removed from the `method` attribute
- `status.silenced` is set to `true`

If the silence action is requested when the `status.canSilence` property is `false`, the alarm will not be silenced and an ERROR response is returned to the requestor.

> Note: Notifications with `state = emergency` cannot be silenced regardless of the value of `status.canSilence`.

Example: Notification payload prior to `silence` action request.

    {
       "message": "Engine temperature is high!",
       "method": ["sound", "visual"],
       "state": "alert",
       "id": "a987be59-d26f-46db-afeb-83987b837a8f",
       "status": {
          "silenced": false,
          "acknowledged": false,
          "canSilence": true,
          "canAcknowledge": true,
          "canClear": true
       }
    }

Silence action request

    HTTP POST "/signalk/v2/api/notifications/a987be59-d26f-46db-afeb-83987b837a8f/silence"

Notification: post `silence` request

    {
       "message": "Engine temperature is high!",
       "method": ["visual"],
       "state": "alert",
       "id": "a987be59-d26f-46db-afeb-83987b837a8f",
       "status": {
          "silenced": true,
          "acknowledged": false,
          "canSilence": true,
          "canAcknow;edge": true,
          "canClear": true
       }
    }

### Acknowledging an Alarm

> Note: The acknowledge action is only available for alarms associated with notifications having `status.canAcknowledge` = `true`.

To acknowledge the alarm send an HTTP POST request to `/signalk/v2/api/notifications/{notificationId}/acknowledge`.

The result of a successful acknowledge request is that the:

- Both `sound` & `visual` values are removed from the `method` attribute
- `status.acknowledged` is set to `true`

If the acknowledge action is requested when the `status.canAcknowledge` property is `false`, the alarm will not be acknowledged and an ERROR response is returned to the requestor.

> Note: Notifications with `state = emergency` will only have the `sound` value removed from `method`.

Example: Notification prior to `acknowledge` request.

    {
       "message": "Engine temperature is high!",
       "method": ["sound", "visual"],
       "state": "alert",
       "id": "a987be59-d26f-46db-afeb-83987b837a8f",
       "status": {
          "silenced": true,
          "acknowledged": false,
          "canSilence": true,
          "canAcknow;edge": true,
          "canClear": true
       }
    }

Acknowledge action request

    HTTP POST "/signalk/v2/api/notifications/a987be59-d26f-46db-afeb-83987b837a8f/acknowledge"

Notification: post `acknowledge` request

    {
       "message": "Engine temperature is high!",
       "method": [],
       "state": "alert",
       "id": "a987be59-d26f-46db-afeb-83987b837a8f",
       "status": {
          "silenced": true,
          "acknowledged": true,
          "canSilence": true,
          "canAcknow;edge": true,
          "canClear": true
       }
    }

## NMEA2000 Alert Handling

NMEA2000 alarm PGNs are processed by `n2k-signalk` which generates Signal K notification deltas as follows:

- Path value starting with `notifications.nmea.*`
- PGN fields mapped to the `state`, `method` and `message` attributes
- Additional attributes capturing PGN field values added to the notification payload.

The Notification API uses these additional PGN attributes to populate the notification `status` to align the available actions and any action taken.

Example: Signal K notification from NMEA2000 Alarm PGN

    {
       "path": "notifications.nmea.alarm.navigational.20.8196" //
       "value": {
          "state": "alarm",
          "method": [
             "visual",
             "sound"
          ],
          "message": "Highwater",
          "alertType": "Alarm",
          "alertCategory": "Navigational",
          "alertSystem": 20,
          "alertId": 8196,
          "dataSourceNetworkIDNAME": 1240095849160158000,
          "dataSourceInstance": 215,
          "dataSourceIndex-Source": 1,
          "occurrence": 2,
          "temporarySilenceStatus": "No",
          "acknowledgeStatus": "No",
          "escalationStatus": "No",
          "temporarySilenceSupport": "No",
          "acknowledgeSupport": "Yes",
          "escalationSupport": "No",
          "acknowledgeSourceNetworkIDNAME": 1233993293343261200,
          "triggerCondition": "Auto",
          "thresholdStatus": "Threshold Exceeded",
          "alertPriority": 0,
          "alertState": "Active"
          }
    }

### NMEA2000 -> Signal K `state` Mapping

NMEA2000 alarm states are mapped to Signal K notification `state` as follows:

NMEA2000 State | Signal K State | Description
--- | --- | ---
Emergency Alarm | `emergency` | A life-threatening condition
Alarm | `alarm` | Immediate action is required to prevent loss of life or equipment damage
Warning | `warn` | Indicates a condition that requires immediate attention but not immediate action
Caution | `alert` | Indicates a safe or normal condition which is brought to the operators attention to impart information for routine action purposes
-- | `normal` | Indicates normal operation.
-- | `nominal` | This is can be used to indicate value has entered a range within the normal zone

Reference: Signal K Specification

### NMEA2000 alarm `method` Mapping

The `n2k-signalk` plugin will set a notification's `method = []` when the NMEA2000 `acknowledgeStatus` OR `temporarySilenceStatus` attributes are set to "Yes".

The Notifications API will re-write the `method` attribute value, as outlined above in Silencing a Notification and Acknowledging a Notification, to ensure alignment across all notifications regardless of source.