=== Notifications ===

[[mail-notifications]]
==== Mail Notifications ====

Mail notifications will be delivered as HTML emails rendered using https://www.thymeleaf.org/[Thymeleaf] templates.
To enable Mail notifications, configure a `JavaMailSender` using `spring-boot-starter-mail` and set a recipient.

.Sample Mail Notification
image::mail-notification-sample.png[Sample Mail Notification]

NOTE: To prevent disclosure of sensitive information, the default mail template doesn't show any metadata of
the instance. If you want to you show some of the metadata you can use a custom template.

. Add spring-boot-starter-mail to your dependencies:
+
[source,xml]
.pom.xml
----
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-mail</artifactId>
</dependency>
----

. Configure a JavaMailSender
+
.application.properties
----
spring.mail.host=smtp.example.com
spring.boot.admin.notify.mail.to=admin@example.com
----

. Configure the mail with the options below
+
.Mail notifications configuration options
|===
| Property name |Description |Default value

| spring.boot.admin.notify.mail.enabled
| Enable mail notifications
| `true`

| spring.boot.admin.notify.mail.ignore-changes
| Comma-delimited list of status changes to be ignored. Format: "<from-status>:<to-status>". Wildcards allowed.
| `"UNKNOWN:UP"`

| spring.boot.admin.notify.mail.template
| Resource path to the Thymeleaf template used for rendering.
| `"classpath:/META-INF/spring-boot-admin-server/mail/status-changed.html"`

| spring.boot.admin.notify.mail.to
| Comma-delimited list of mail recipients
| `"root@localhost"`

| spring.boot.admin.notify.mail.cc
| Comma-delimited list of carbon-copy recipients
|

| spring.boot.admin.notify.mail.from
| Mail sender
| `"Spring Boot Admin <noreply@localhost>"`

| spring.boot.admin.notify.mail.additional-properties
| Additional properties which can be accessed from the template
|

|===

[[pagerduty-notifications]]
==== PagerDuty Notifications ====
To enable https://www.pagerduty.com/[PagerDuty] notifications you just have to add a generic service to your PagerDuty-account and set `spring.boot.admin.notify.pagerduty.service-key` to the service-key you received.

.PagerDuty notifications configuration options
|===
| Property name |Description |Default value

| spring.boot.admin.notify.pagerduty.enabled
| Enable mail notifications
| `true`

| spring.boot.admin.notify.pagerduty.ignore-changes
| Comma-delimited list of status changes to be ignored. Format: "<from-status>:<to-status>". Wildcards allowed.
| `"UNKNOWN:UP"`

| spring.boot.admin.notify.pagerduty.service-key
| Service-key to use for PagerDuty
|

| spring.boot.admin.notify.pagerduty.url
| The Pagerduty-rest-api url
| `+++"https://events.pagerduty.com/generic/2010-04-15/create_event.json"+++`

| spring.boot.admin.notify.pagerduty.description
| Description to use in the event. SpEL-expressions are supported
| `+++"#{instance.registration.name}/#{instance.id} is #{instance.statusInfo.status}"+++`

| spring.boot.admin.notify.pagerduty.client
| Client-name to use in the event
|

| spring.boot.admin.notify.pagerduty.client-url
| Client-url to use in the event
|
|===


[[opsgenie-notifications]]
==== OpsGenie Notifications ====
To enable https://www.opsgenie.com/[OpsGenie] notifications you just have to add a new JSON Rest API integration to your OpsGenie account and set `spring.boot.admin.notify.opsgenie.api-key` to the apiKey you received.

.OpsGenie notifications configuration options
|===
| Property name |Description |Default value

| spring.boot.admin.notify.opsgenie.enabled
| Enable OpsGenie notifications
| `true`

| spring.boot.admin.notify.opsgenie.ignore-changes
| Comma-delimited list of status changes to be ignored. Format: "<from-status>:<to-status>". Wildcards allowed.
| `"UNKNOWN:UP"`

| spring.boot.admin.notify.opsgenie.api-key
| apiKey you received when creating the integration
|

| spring.boot.admin.notify.opsgenie.url
| OpsGenie Alert API url
| `+++"https://api.opsgenie.com/v2/alerts"+++`

| spring.boot.admin.notify.opsgenie.description
| Description to use in the event. SpEL-expressions are supported
| `+++"#{instance.registration.name}/#{instance.id} is #{instance.statusInfo.status}"+++`

| spring.boot.admin.notify.opsgenie.actions
| Comma separated list of actions that can be executed.
|

| spring.boot.admin.notify.opsgenie.source
| Field to specify source of alert. By default, it will be assigned to IP address of incoming request.
|

| spring.boot.admin.notify.opsgenie.tags
| Comma separated list of labels attached to the alert.
|

| spring.boot.admin.notify.opsgenie.entity
| The entity the alert is related to.
|

| spring.boot.admin.notify.opsgenie.user
| Default owner of the execution. If user is not specified, the system becomes owner of the execution.
|
|===


[[hipchat-notifications]]
==== Hipchat Notifications ====
To enable https://www.hipchat.com/[Hipchat] notifications you need to create an API token on your Hipchat account and set the appropriate configuration properties.

.Hipchat notifications configuration options
|===
| Property name |Description |Default value

| spring.boot.admin.notify.hipchat.enabled
| Enable Hipchat notifications
| `true`

| spring.boot.admin.notify.hipchat.ignore-changes
| Comma-delimited list of status changes to be ignored. Format: "<from-status>:<to-status>". Wildcards allowed.
| `"UNKNOWN:UP"`

| spring.boot.admin.notify.hipchat.url
| The HipChat REST API (V2) URL
|

| spring.boot.admin.notify.hipchat.auth-token
| The API token with access to the notification room
|

| spring.boot.admin.notify.hipchat.room-id
| The ID or url-encoded name of the room to send notifications to
|

| spring.boot.admin.notify.hipchat.notify
| Whether the message should trigger a user notification
| `false`

| spring.boot.admin.notify.hipchat.description
| Description to use in the event. SpEL-expressions are supported
| `+++"&lt;strong&gt;#{instance.registration.name}&lt;/strong&gt;/#{instance.id} is &lt;strong&gt;#{event.statusInfo.status}&lt;/strong&gt;"+++`
|
|===


[[slack-notifications]]
==== Slack Notifications ====
To enable https://slack.com/[Slack] notifications you need to add a incoming Webhook under custom integrations on your Slack
account and configure it appropriately.

.Slack notifications configuration options
|===
| Property name |Description |Default value

| spring.boot.admin.notify.slack.enabled
| Enable Slack notifications
| `true`

| spring.boot.admin.notify.slack.ignore-changes
| Comma-delimited list of status changes to be ignored. Format: "<from-status>:<to-status>". Wildcards allowed.
| `"UNKNOWN:UP"`

| spring.boot.admin.notify.slack.webhook-url
| The Slack Webhook URL to send notifications to.
|

| spring.boot.admin.notify.slack.channel
| Optional channel name (without # at the beginning). If different than channel in Slack Webhooks settings
|

| spring.boot.admin.notify.slack.icon
| Optional icon name (without surrounding colons). If different than icon in Slack Webhooks settings
|

| spring.boot.admin.notify.slack.username
| Optional username to send notification if different than in Slack Webhooks settings
| `Spring Boot Admin`

| spring.boot.admin.notify.slack.message
| Message to use in the event. SpEL-expressions and Slack markups are supported
| `+++"*#{instance.registration.name}* (#{instance.id}) is *#{event.statusInfo.status}*"+++`
|
|===


[[letschat-notifications]]
==== Let's Chat Notifications ====
To enable https://sdelements.github.io/lets-chat/[Let's Chat] notifications you need to add the host url and add the API token and username from Let's Chat

.Let's Chat notifications configuration options
|===
| Property name |Description |Default value

| spring.boot.admin.notify.letschat.enabled
| Enable let´s Chat notifications
| `true`

| spring.boot.admin.notify.letschat.ignore-changes
| Comma-delimited list of status changes to be ignored. Format: "<from-status>:<to-status>". Wildcards allowed.
| `"UNKNOWN:UP"`

| spring.boot.admin.notify.letschat.url
| The let´s Chat Host URL to send notifications
|

| spring.boot.admin.notify.letschat.room
| the room where to send the messages
|

| spring.boot.admin.notify.letschat.token
| the token to access the let´s Chat API
|

| spring.boot.admin.notify.letschat.username
| The username for which the token was created
| `Spring Boot Admin`

| spring.boot.admin.notify.letschat.message
| Message to use in the event. SpEL-expressions are supported
| `+++"*#{instance.registration.name}* (#{instance.id}) is *#{event.statusInfo.status}*"+++`
|
|===


[[ms-teams-notifications]]
==== Microsoft Teams Notifications ====
To enable Microsoft Teams notifications you need to setup a connector webhook url and set the appropriate configuration property.

.Microsoft Teams notifications configuration options
|===
| Property name |Description |Default value

| spring.boot.admin.notify.ms-teams.enabled
| Enable Microsoft Teams notifications
| `true`

| spring.boot.admin.notify.ms-teams.webhook-url
| The Microsoft Teams webhook url to send the notifications to.
|

| spring.boot.admin.notify.ms-teams.*
| There are several options to customize the message title and color
|
|===


[[telegram-notifications]]
==== Telegram Notifications ====
To enable https://telegram.org/[Telegram] notifications you need to create and authorize a telegram bot and set the appropriate configuration properties for auth-token and chat-id.

.Telegram notifications configuration options
|===
| Property name |Description |Default value

| spring.boot.admin.notify.telegram.enabled
| Enable Telegram notifications
| `true`

| spring.boot.admin.notify.telegram.auth-token
| The token identifying und authorizing your Telegram bot (e.g. `123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11`).
|

| spring.boot.admin.notify.telegram.chat-id
| Unique identifier for the target chat or username of the target channel
|

| spring.boot.admin.notify.telegram.disable-notify
| If true users will receive a notification with no sound.
| `false`

| spring.boot.admin.notify.telegram.parse_mode
| The parsing mode for the sent message. Currently ``HTML'` and `'Markdown'` are supported.
| `'HTML'`

| spring.boot.admin.notify.telegram.message
| Text to send. SpEL-expressions are supported.
| `+++"&lt;strong&gt;#{instance.registration.name}&lt;/strong&gt;/#{instance.id} is &lt;strong&gt;#{event.statusInfo.status}&lt;/strong&gt;"+++`
|===


[[discord-notifications]]
==== Discord Notifications ====
To enable Discord notifications you need to create a webhook and set the appropriate configuration property.

.Discord notifications configuration options
|===
| Property name |Description |Default value

| spring.boot.admin.notify.discord.enabled
| Enable Discord notifications
| `true`

| spring.boot.admin.notify.discord.webhook-url
| The Discord webhook url to send the notifications to.
|

| spring.boot.admin.notify.discord.username
| Optional username.
| __Default set in Discord__

| spring.boot.admin.notify.discord.avatar-url
| Optional URL to avatar.
| __Default set in Discord__

| spring.boot.admin.notify.discord.tts
| If the message is a text to speech message.
| `false`

| spring.boot.admin.notify.discord.message
| Text to send. SpEL-expressions are supported.
| `+++"*#{instance.registration.name}* (#{instance.id}) is *#{event.statusInfo.status}*"+++`
|===


[[notification-proxy]]
==== Notification Proxy Settings ====
All Notifiers which are using a `RestTemplate` can be configured to use a proxy.

.Notification Proxy configuration options
|===
| Property name |Description |Default value

| spring.boot.admin.notify.proxy.host
| The proxy host
|

| spring.boot.admin.notify.proxy.port
| The proxy port
|
|===


[[reminder-notifications]]
==== Notification Reminder ====
The `RemindingNotifier` sends reminders for down/offline applications, it delegates the sending of notifications to another notifier.

By default a reminder is triggered when a registered application changes to `DOWN` or `OFFLINE`. You can alter this behaviour via `setReminderStatuses()`. The reminder ends when either the status changes to a non-triggering status or the regarding application gets deregistered.

By default the reminders are sent every 10 minutes, to change this use `setReminderPeriod()`. The `RemindingNotifier` itself doesn't start the background thread to send the reminders, you need to take care of this as shown in the given example below;

.How to configure reminders
[source,java]
----
@Configuration
public class NotifierConfiguration {
    @Autowired
    private Notifier notifier;

    @Primary
    @Bean(initMethod = "start", destroyMethod = "stop")
    public RemindingNotifier remindingNotifier() {
        RemindingNotifier notifier = new RemindingNotifier(notifier, repository);
        notifier.setReminderPeriod(Duration.ofMinutes(10)); // <1>
        notifier.setCheckReminderInverval(Duration.ofSeconds(10)); //<2>
        return notifier;
    }
}
----
<1> The reminders will be sent every 10 minutes.
<2> Schedules sending of due reminders every 10 seconds.


[[filtering-notifications]]
==== Filtering Notifications ====
The `FilteringNotifier` allows you to filter certain notification based on rules you can add/remove at runtime. It delegates the sending of notifications to another notifier.

If you add a `FilteringNotifier` to your `ApplicationContext` a RESTful interface on `notifications/filter` gets available.

This notifier is useful if you don't want receive notifications when deploying your applications. Before stopping the application you can add an (expiring) filter either via a `POST` request.

.How to configure filtering
[source,java,indent=0]
----
include::{samples-dir}/spring-boot-admin-sample-servlet/src/main/java/de/codecentric/boot/admin/NotifierConfig.java[tags=configuration-filtering-notifier]
----
<1> Add the `FilteringNotifier` bean using a delegate (e.g. `MailNotifier` when configured)
<2> Add the `RemindingNotifier` as primary bean using the `FilteringNotifier` as delegate.

TIP: This example combines the reminding and filtering notifiers. This allows you to get notifications after the deployed application hasn't restarted in a certain amount of time (until the filter expires).
