> ## Documentation Index
> Fetch the complete documentation index at: https://docs.activeviam.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Send custom notifications

> How to send custom notifications in Atoti Limits using INotificationService, covering user and technical notification types, the Notification class, notification actions, and restricting notifications to specific users or roles

## User notifications

Atoti Limits uses the Notification Service to send notifications to the UI. Out of the box,
Atoti Limits sends notifications:

* to users with the role `ROLE_ADMIN` when the initial data load completes. This is configurable in the `application.yml`
  file using the `limits.notification.server-started-notification-user-role` property.
* to all users when limit evaluations complete. This is configurable in the `application.yml` file using the
  `limits.notification.evaluation-completed-notification-user-role` property.
* to users specified as `Approvers` when a FourEyes limit is created or updated

## Technical notifications

Atoti Limits also sends technical notifications. These are notifications that are used to communicate information
to the UI and are not shown to users. See the [Notification Service documentation](https://docs.activeviam.com/products/modules/notification-service/latest/online-help/managing-notifications/create-publish-notifications)
for more information on technical notifications.

The following technical notifications are included out of the box:

* When Limits KPIs are updated, a technical notification with classifier `refresh-datamodel` is sent to the user who
  triggered the update. This notification will also have classifiers that contain the names of application servers which
  contain the KPIs that were updated. Upon receiving this technical notification, the UI will refresh the data models of
  these application servers.

## Send a custom notification

To send custom notifications, follow these steps.

### 1. Inject the `INotificationService` bean into your class

The `INotificationService` is responsible for all management of notifications, including publishing, retrieving, and
executing actions. To use it, inject the service into the component that needs to send notifications:

```java theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
@Autowired private INotificationService notificationService;
```

OR

```java theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
@Component
@RequiredArgsConstructor
public class MyComponent {
    private final INotificationService notificationService;
}
```

### 2. Create and publish your notifications

With the service wired up, you can now create and publish notifications.

The `Notification` class is a simple POJO that represents a notification.
Use one of the class’s builder methods to create `Notification` objects:

* `Notification.notificationWithDefaultActionsBuilder()`: Creates a notification with the default actions. For more
  information see the [actions section](#notification-actions). This is the recommended builder to use in most scenarios.
* `Notification.builder()`: Creates a bare notification with no actions.

Once you have chosen the builder method to use, create the notification:

```java theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
Notification notification = Notification.notificationWithDefaultActionsBuilder()
    .title("My Custom Limits Notification")                     // This will be the headline for the notification in the UI
    .description("This is a sample notification")               // This will be the body of the notification in the UI
    .severity(NotificationSeverity.MEDIUM)                      // Determines the color of the severity indicator for the notification (LOW - green, MEDIUM - yellow, HIGH - red)
    .classifiers(List.of("category 1", "custom-classifier"))    // Classifiers that can be used to filter notifications in the UI
    .build();
```

With your notification created, you can now publish it using the `INotificationService`:

```java theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
notificationService.publishNotification(notification);
```

That’s it - your notification has been published and will be visible in the Atoti Limits UI.

## Notification actions

Notifications can have actions that users can take when they receive them. Instances of the `NotificationAction` class
represent one of these actions that can be taken on a notification. There are three default actions that are provided
when using the `Notification.notificationWithDefaultActionsBuilder()` method:

* `MARK_READ`: Marks the notification as read. Only enabled if the notification is unread (`isRead=false`).
* `MARK_UNREAD`: Marks the notification as unread. Only enabled if the notification is read (`isRead=true`).
* `DELETE`: Deletes the notification.

## Restrict notifications to specific users

By default, notifications are sent to all users. If you want to restrict a notification to only be sent to specific
users, you can do so by setting the `users` or `userRoles` fields:

```java theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
Notification notification = Notification.notificationWithDefaultActionsBuilder()
    ...
    .users(List.of("user1", "user2"))    // Only these users will receive the notification
    .userRoles(List.of("ROLE_MANAGERS")) // Only users with this role will receive the notification
    .build();
```

Most use cases should only use one of these fields. If both are set, the notification will only be sent to users who
are in the `users` list AND have one of the roles in `userRoles`.

## Notification Service properties

The Notification Service contains the following properties that can be configured in your `application.yml` file:

<table><thead><tr><th>Property</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><code>notification-service.emitter-timeout</code></td><td>8h</td><td>The maximum time to keep the connection to the UI open.</td></tr><tr><td><code>notification-service.initial-notification-mode</code></td><td><code>SEND\_ALL</code></td><td>Controls the notifications that are sent in the initial event after a subscription is created. Available modes:<br /><ul><li><code>SEND\_ALL</code> - all notifications applicable to the user that were created since the application started will be sent in the initial event. This is the default mode.</li><li><code>DONT\_SEND</code> - no notifications will be sent in the initial event.</li></ul></td></tr></tbody></table>