<commit_before>---
layout: page
title: Notifications
permalink: /:path/
sort_idx: 70
---
{% include variables.md %}

* TOC
{:toc}


The Kaa **Notification subsystem** is used to deliver messages from [Kaa cluster]({{root_url}}Glossary/#kaa-cluster) to [endpoints]({{root_url}}Glossary/#endpoint-ep).
Unlike configuration data that represents the desired endpoint state, notifications are used as calls for a dynamic endpoint action.
For example, a notification can cause a [Kaa client]({{root_url}}/#kaa-client) to display a UI message (a user notification).

## Prerequisites

To use the examples below, you need to first set up either a [Kaa Sandbox]({{root_url}}Glossary/#kaa-sandbox) or a full-blown [Kaa cluster]({{root_url}}Glossary/#kaa-cluster).
After that, you need to create a tenant and an application.
To do this, you can use the [tenant]({{root_url}}Programming-guide/Server-REST-APIs/#/Tenant) and [application]({{root_url}}Programming-guide/Server-REST-APIs/#/Application) APIs or the [Administration UI]({{root_url}}Administration-guide/Users-management/#managing-tenant-admins).

It is strongly recommended that you first read the [Data collection]({{root_url}}Programming-guide/Key-platform-features/Data-collection) and [Endpoint groups]({{root_url}}Programming-guide/Key-platform-features/Endpoint-groups) sections before you proceed.

## Notification management

The following diagram illustrates the basic entities and data flows in scope of the notification management:

* Notifications are generated based on the [notification schema](#notification-schema) configured by the application developer.
* The user or administrator sends a notification using the [server REST API]({{root_url}}Programming-guide/Server-REST-APIs/#!/Notifications/sendNotification) call or the Administration UI (see [Send notifications](#send-notifications)).

![Basic architecture](images/basic_architecture_notification.png)

### Notification schema

The Kaa notifications functionality allows transferring any data to endpoints.
The structure of the notification data is defined by the notification schema selected and configured on the [Kaa server]({{root_url}}Glossary/#kaa-server).
The notification schema is defined similarly to the [endpoint profile]({{root_url}}/Programming-guide/Key-platform-features/Endpoint-profiles) schema.
For more information about using schemas in Kaa, see [Common type library]({{root_url}}Programming-guide/Key-platform-features/Common-Type-Library).

In addition to the [common type]({{root_url}}Glossary/#common-type-ct) schema and its version, notifications are characterized by type that can be either **system** or **user**.
System notifications are processed by the prepackaged endpoint functions, while user notifications are sent to the Kaa client using the the endpoint API.

Since the data structure requirements may evolve throughout the Kaa-based system lifetime, the Kaa server can be configured to simultaneously handle notification schemas of multiple versions.
In this case, a notification will have multiple schema versions associated with it, as well as multiple sets of notification data so that each schema version is covered.
To deliver such a notification to an endpoint, the server chooses the schema version supported by the endpoint.

The default notification schema installed for [Kaa applications]({{root_url}}Glossary/#kaa-application) is empty.

For the purpose of this guide, a simple notification schema is shown in the example below.

```json
{ 
    "type":"record",
    "name":"ExampleNotification",
    "namespace":"org.kaaproject.kaa.schema.sample.notification",
    "fields":[ 
        { 
            "name":"message",
            "type":"string"
        }
    ]
}
```

To configure your own notification schema, use the [server REST API]({{root_url}}Programming-guide/Server-REST-APIs/#!/Notifications/saveNotificationSchema) or select it from the **Notification** page under the **Schemas** section of the application.

![Add Notification Schema 1](images/add_notification_schema_1.png)

As a tenant developer, you can create new notification schemas for an application.
To do this, open the **Notification** page of the application and follow the same steps as described in [Setting client-side EP profile schema]({{root_url}}Programming-guide/Key-platform-features/Endpoint-profiles/#setting-client-side-ep-profile-schema).

### Notification topics

Notifications in Kaa are organized into topics.
Every topic can be associated with one or more endpoint groups.
To receive a notification, the endpoint must belong to one or more groups that are associated with the corresponding notification topic.
<commit_msg>KAA-1167: Notifications - fixed upon developer review.<commit_after>---
layout: page
title: Notifications
permalink: /:path/
sort_idx: 70
---
{% include variables.md %}

* TOC
{:toc}


The Kaa **Notification subsystem** is used to deliver messages from [Kaa cluster]({{root_url}}Glossary/#kaa-cluster) to [endpoints]({{root_url}}Glossary/#endpoint-ep).
Unlike configuration data that represents the desired endpoint state, notifications are used as calls for a dynamic endpoint action.
For example, a notification can cause a [Kaa client]({{root_url}}/#kaa-client) to display a UI message (a user notification).

## Prerequisites

To use the examples below, you need to first set up either a [Kaa Sandbox]({{root_url}}Glossary/#kaa-sandbox) or a full-blown [Kaa cluster]({{root_url}}Glossary/#kaa-cluster).
After that, you need to create a tenant and an application.
To do this, you can use the [tenant]({{root_url}}Programming-guide/Server-REST-APIs/#/Tenant) and [application]({{root_url}}Programming-guide/Server-REST-APIs/#/Application) APIs or the [Administration UI]({{root_url}}Administration-guide/Users-management/#managing-tenant-admins).

It is strongly recommended that you first read the [Data collection]({{root_url}}Programming-guide/Key-platform-features/Data-collection) and [Endpoint groups]({{root_url}}Programming-guide/Key-platform-features/Endpoint-groups) sections before you proceed.

## Notification management

The following diagram illustrates the basic entities and data flows in scope of the notification management:

* Notifications are generated based on the [notification schema](#notification-schema) configured by the application developer.
* The user or administrator sends a notification using the [server REST API]({{root_url}}Programming-guide/Server-REST-APIs/#!/Notifications/sendNotification) call or the Administration UI (see [Send notifications](#send-notifications)).

![Basic architecture](images/basic_architecture_notification.png)

### Notification schema

The Kaa notifications functionality allows transferring any data to endpoints.
The structure of the notification data is defined by the notification schema selected and configured on the [Kaa server]({{root_url}}Glossary/#kaa-server).
The notification schema is defined similarly to the [endpoint profile]({{root_url}}/Programming-guide/Key-platform-features/Endpoint-profiles) schema.
For more information about using schemas in Kaa, see [Common type library]({{root_url}}Programming-guide/Key-platform-features/Common-Type-Library).

In addition to the [common type]({{root_url}}Glossary/#common-type-ct) schema and its version, notifications are characterized by type that can be either **system** or **user**.
System notifications are processed by the prepackaged endpoint functions, while user notifications are sent to the Kaa client using the the endpoint API.

Since the data structure requirements may evolve throughout the Kaa-based system lifetime, the Kaa server can be configured to simultaneously handle notification schemas of multiple versions.
In this case, a notification will have multiple schema versions associated with it, as well as multiple sets of notification data so that each schema version is covered.
To deliver such a notification to an endpoint, the server chooses the schema version supported by the endpoint.

The default notification schema installed for [Kaa applications]({{root_url}}Glossary/#kaa-application) is empty.

For the purpose of this guide, a simple notification schema is shown in the example below.

```json
{ 
    "type":"record",
    "name":"ExampleNotification",
    "namespace":"org.kaaproject.kaa.schema.sample.notification",
    "fields":[ 
        { 
            "name":"message",
            "type":"string"
        }
    ]
}
```

As a tenant developer, you can create new notification schemas for an application.
To do this, use the [server REST API]({{root_url}}Programming-guide/Server-REST-APIs/#!/Notifications/saveNotificationSchema) or open the **Notification** page of the application and follow the same steps as described in [Setting client-side EP profile schema]({{root_url}}Programming-guide/Key-platform-features/Endpoint-profiles/#setting-client-side-ep-profile-schema).

![Add Notification Schema 1](images/add_notification_schema_1.png)

### Notification topics

Notifications in Kaa are organized into topics.
Every topic can be associated with one or more endpoint groups.
To receive a notification, the endpoint must belong to one or more groups that are associated with the corresponding notification topic.

{'fraction_non_alphanumeric': 0.09286791639732817, 'fraction_numerical': 0.001292824822236587, 'mean_word_length': 5.424221453287197, 'pattern_counts': {'":': 12, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6346114', 'n_tokens_mistral': 2447, 'n_tokens_neox': 2292, 'n_words': 968}