> ## 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 to the Atoti Sign-Off UI, including creating and publishing notifications, restricting them to specific users or roles, and configuring notification service properties.

Atoti Sign-Off uses the Notification Service to send notifications to the UI. Out of the box, Atoti Sign-Off will send notifications:

* to users with the role `ROLE_ADMIN` when the initial data load completes. This is configurable in the `application.yml` file using the  `sign-off.notification.server-started-notification-user-role` property.
* to users specified as `Approvers` when 4-eyes tasks require approval
* to all users involved in the task when an export succeeds or fails

In order to send custom notifications, follow these steps:

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

The `INotificationService` is a convenience service that helps publish the events that the notification service listens for. To use it, inject it 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 [Notification actions](#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 Atoti Sign-Off 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
    .status("To do")                                            // Initial status of the notification, can be updated later
    .sourceId(sourceObject.getId())                             // Links the notification to an object in the application. This can be used to look up the notification later
    .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 Sign-Off 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. The following default actions 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:

| Property                                         | Default Value | Description                                                                                                                                                                                                                                                                                                                                              |
| ------------------------------------------------ | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `notification-service.emitter-timeout`           | 8h            | The maximum time to keep the connection to the UI open.                                                                                                                                                                                                                                                                                                  |
| `notification-service.initial-notification-mode` | `SEND_ALL`    | Controls the notifications that are sent in the initial event after a subscription is created. Available modes: - `SEND_ALL` - 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. - `DONT_SEND` - no notifications will be sent in the initial event. |