Notifications

Information Model

A Notification object contains all data required to compose one message for one specific User. This includes a reference to one of the Type objects, which provide templates for the title and body text fields of a specific type of notification.

The Notification Service also stores a Settings object for each User. This object holds the user’s preferences regarding the types of messages for which they wish to receive push notifications.

Objects and Attributes

Notifications

The Notification object is uniquely identified by its id. The object contains the identifier of the intended receiver (user_id), the elements to generate the message (type and fields), and a boolean that indicates whether the message has been viewed by the user. The latter can be set to true via the Mark your notification(s) as viewed request.

To generate the title and body texts of the (push) notification, the key-value pairs provided in the fields attribute are used to replace the variables in the template of the specified notification type.

The Notification object also contains a deprecated attribute: important. It was originally developed for FibriCheck but will not be included in V2 of the service.

Types

The Notification Service offers a couple of default notification Types that can be used by the customer’s application. These Type objects are uniquely identified by their name (“message” and “link”) and define templates for the title and body text fields of a notification. The templates can include variables for which the value must be provided in the Create a Notification request. The required_fields and optional_fields attributes specify which parameters are to be included in the request.

In the current version of the Notification Service, Type objects cannot be created by the customer, nor can the default Type objects be customized.

Push notification-specific attributes

When set up correctly (see Sending Push Notifications), push notifications can be send to a user’s mobile device when a new Notification object is created. However, a user can choose which types of push notifications they will receive by adjusting their preferences in the Settings object. The default preferences are derived from the push_by_default attribute in each of the Type objects.

Before sending the push notification, the service will check if there are other Notifications of the same type (and for the same User) for which the viewed attribute is set to false. If so, the push notification that is sent out will contain the combined_body text instead of the text specified in the body attribute.

Example

body: "A new rapport is available: {{ rapport_name }}

combined_body: "Multiple new rapports are available."

For internal developers: the FibriCheck Prescription Service includes a counter in this attribute.

combined_body: "{{ keyX, $counter }}"

With `keyX referring to a LocalizationSet with the English text snippet:

"{{ count }} new comments on measurements are available"

Settings objects

Each Settings object is uniquely identified by the id of the User it represents. The object contains a preferences attribute which defines whether the sending of a specific type of push notifications is enabled for the user. The Settings object is created when a new User is registered. At that moment, the key-value pairs in the preferences attribute are set to the push_by_default value of all available notification Types. Afterwards, a Create/update the Settings for a User request can be made to update these preferences.

The Notification Service can only send push notifications to a user’s mobile device when the Settings object includes an active key. This attribute holds a secret value set by the customer’s (mobile) application that enables the identification of the associated device.

Example

{
    "id": "58074804b2148f3b28ad759a",
    "key": "string",
    "preferences": {
        "message": true,
        "link": true,
        "activated": true,
        "password_change": false
    },
    "creation_timestamp": 1550577829354,
    "update_timestamp": 1550577829354
}

Common timestamp attributes

All Extra Horizon Services keep track of the time of creation (creation_Timestamp) and of the most recent update (update_Timestamp) of their stored objects. This does not apply for the default Type objects since they are fixed components.

The timestamp attributes in the Notification Service have a number format, whereas other Services use a string($date-time) format.

Sending Push Notifications

Push notifications are short messages that are displayed outside the user interface of a (mobile) application. To receive push notifications on a mobile device, a link with the Notification Service is required. This link is set up as follows:

1. The user installs the customer’s application on its mobile device and gives permission to receive push notifications.

2. The mobile app registers the user’s device on Firebase and receives a secret code, called a "push key”.

3. The mobile app stores the push key in the key attribute of the User’s Settings object in the Notification Service.

4. When new Notifications are created, the service sends the required data to Firebase, which uses the key to identify the user’s mobile device and to trigger a push notification.

Important: The customer must implement Firebase in its mobile application.

Tip: To disable the sending of push notifications of a specific type to a user, set the value of the corresponding field in the preferences attribute of the Settings object to false.

Default Types

Free text-Types: messages and link

There are two non-specific Type objects available that enable the customer’s application to create notifications with a custom title and body text. Both strings are required parameters in the request. The message Type additionally requires the identifier of the (system) User creating the Notification (sender_id), whereas the link Type expects a URL. By default, clicking a push notification of the link Type opens this URL.

Tip: Push notification can contain action buttons, for example to accept a friend request without opening the app. These customized actions must be set up for the customer’s mobile application in Firebase. Subsequently, the action name can be assigned to the click_action parameter in the request to the Notification Service.

Note: Currently, the title of Notifications of the message and link Types is fixed to “FibriCheck”.

Note: The JSON syntax in the Type objects is different from other services. The double brackets do not refer to a localization key (as used in the Template Service) but to the values provided in the Create a Notification request. To include text snippets stored in the Localization Service, the client application must first retrieve the snippets in the required language and subsequently include them as plain text in the request title or body parameter.

Note for internal developers: Originally, the purpose of the message Type was to enable a functionality in which a User (sender_id), e.g. a physician, could send a user-written message to another User. However, this functionality was never applied, and the message Type is currently used to automatically create messages with the Data Service (e.g. measurement rapports). The sender_id attribute has been recycled to store the system User that is responsible for creating the Notifications.

Application Specific Types

Application-specific Types

For the above non-specific Types, the title and body text fields must be completely provided during the Create a Notification request. For more specific Types, these text fields are usually predefined and only some variables are required.

Two notification Types are used to create Notifications in response to successful actions at the User Service: email address activation (activated) and password_change. By default, only the first type of notification will result in a push notification.

For internal developers: The User Service-specific Types will not be included in V2.

For internal developers: The V1 Notification Service also provides notification Types for FibriCheck’s Prescription Service that will not be included in V2.

• A comment on a measurement is available (Measurement_comment),

• A review of a measurement is available (Measurement_reviewed),

• A prescription is expiring soon (Prescription_expiry).

Push notifications for the prescription_expiry and measurement_comment Types are by default enabled, whereas they are disabled for the measurement_reviewed notification Type.

The FibriCheck-specific Types make use of localization keys to provide notifications in multiple languages. However, these keys are hard-coded in the respective notification Type templates; they are not provided via the request.

Actions

This section gives an overview of the available Notification Service endpoints. The full descriptions, including the required permissions and/or scopes, can be found in the API reference documentation.

Viewing Types

All available notification Types can be viewed by any User.

List all Types

GET /types

Managing Notifications

In general, Notifications are managed by (a) system User(s) with the required permissions. Once created, Notifications cannot be updated. However, they can be deleted. The latter action will not affect any sent-out push notifications since there is no direct link with the Notification object.

Create a Notification

POST /

Delete a notification

DELETE /notifications

List all Notifications

GET /notifications

Info: Users can retrieve their Notifications via two endpoints. The more recent List all Notifications endpoint also enables administrators to access another User’s Notifications. However, it makes the original List your own Notifications endpoint redundant. The latter will be excluded in V2.

Note: The V1 Notification Service does not support localization keys in the request parameters. The customer’s application must fetch the snippet(s) in a specific language and use these resolved strings in the Create a Notification request. The same applies when using data from other services (e.g. first_name).

For internal developers: The variables in the title and body template of the specified notification Type are processed after resolving localization keys. Therefore, these keys can be used in the attributes of the Type object but not in the Create a Notification request parameters.

Keeping track of viewed Notifications

When the user interacts with a notification in the UI (e.g. by clicking it), the customer’s application can set the viewed attribute in the associated Notification object to true. This information enables the application to stylize previously viewed notifications differently in the UI or to omit them from the displayed list.

Mark your Notification(s) as viewed

POST /viewed