Merge pull request #67 from homeylab/61-notification

61 notification

Author: pchang388

README.md

@@ -262,6 +262,8 @@ notifications:
     storage_path: ""
     custom_title: ""
     custom_attachment_path: ""
+    on_success: false
+    on_failure: true
 ```
 
 #### Options and Descriptions
@@ -290,6 +292,7 @@ More descriptions can be found for each section below:
 | `keep_last` | `int` | `false` | Optional (default: `0`), if exporter can delete older archives. valid values are:<br>- set to `-1` if you want to delete all archives after each run (useful if you only want to upload to object storage)<br>- set to `1+` if you want to retain a certain number of archives<br>- `0` will result in no action done. |
 | `run_interval` | `int` | `false` | Optional (default: `0`). If specified, exporter will run as an application and pause for `{run_interval}` seconds before subsequent runs. Example: `86400` seconds = `24` hours or run once a day. Setting this property to `0` will invoke a single run and exit. Used for basic scheduling of backups. |
 | `minio` | `object` | `false` | Optional [Minio](#minio-backups) configuration options. |
+| `notifications` | `object` | `false` | Optional [notification](#notifications) configuration options. |
 
 #### Valid Environment Variables
 General
@@ -492,10 +495,32 @@ minio:
 | `keep_last` | `int` | `false` | Optional (default: `0`), if exporter can delete older archives in minio.<br>- set to `1+` if you want to retain a certain number of archives<br>-  `0` will result in no action done |
 
 ## Notifications
-It is possible to send notifications when an export run fails. Currently, the only supported notification service is [apprise](https://github.com/caronc/apprise). Apprise is a general purpose notification service and has a variety of integrations and includes generic HTTP POST.
+It is possible to send notifications when an export run succeeds orfails. Currently, the only supported notification service is [apprise](https://github.com/caronc/apprise). Apprise is a general purpose notification service and has a variety of integrations and includes generic HTTP POST.
+
+Notifications are optional and the `notification` section can be omitted/removed/commented out entirely to keep a smaller configuration if not required.
+
+The title for notifications is configurable but not if not specified, a default will be used. Example:
+```
+##### Failure Message #####
+{TITLE}: Bookstack File Exporter Failed
+{BODY}:
+Bookstack File Exporter encountered an unrecoverable error.
+
+Occurred At: 2025-09-06 01:02:47
+
+Error: 401 Client Error: Unauthorized for url: https://test.bookstack/api/shelve
+
+
+##### Success Message #####
+{TITLE}: Bookstack File Exporter Success
+{BODY}:
+Bookstack File Exporter completed successfully.
+
+Completed At: 2025-09-06 01:05:27
+```
 
 ### apprise
-The apprise configuration is a part of the configuration yaml file and can be modified under `notifications.apprise`.
+The apprise configuration is a part of the configuration yaml file under the notifications section and can be modified under `notifications.apprise`.
 
 | Item | Type | Description |
 | ---- | ---- | ----------- |
@@ -505,6 +530,8 @@ The apprise configuration is a part of the configuration yaml file and can be mo
 | `apprise.storage_path` | `str` | For persistent storage, specify a path for apprise to use |
 | `apprise.custom_title` | `str` | Replace the default message title for apprise notifications |
 | `apprise.custom_attachment_path` | `str` | To include a custom attachment to the apprise notification, specify the path to a file | 
+| `apprise.on_success` | `bool` | Default: `false`, set to `true` if notifications should be sent on successful export runs |
+| `apprise.on_failure` | `bool` | Default: `true`, send notifications if run fails |
 
 `apprise.service_urls` can contain sensitive information and can be specified as an environment variable instead as a string list, example: `export APPRISE_URLS='["json://localhost:8080/notify"]'`.
 

bookstack_file_exporter/config_helper/models.py

@@ -44,6 +44,8 @@ class AppRiseNotifyConfig(BaseModel):
     storage_path: Optional[str] = ""
     custom_title: Optional[str] = ""
     custom_attachment_path: Optional[str] = ""
+    on_success: Optional[bool] = False
+    on_failure: Optional[bool] = True
 
 class Notifications(BaseModel):
     """YAML schema for user provided notification settings"""

bookstack_file_exporter/config_helper/notifications.py

@@ -15,9 +15,7 @@
     # "storage_path": "APPRISE_STORAGE_PATH"
 }
 
-_DEFAULT_TITLE = "Bookstack File Exporter Failed"
-
-# pylint: disable=too-few-public-methods
+# pylint: disable=too-few-public-methods, too-many-instance-attributes
 class AppRiseNotifyConfig:
     """
     Convenience class to hold apprise notification configuration
@@ -36,6 +34,8 @@ def __init__(self, config: models.AppRiseNotifyConfig):
         self.storage_path = config.storage_path
         self.custom_title = config.custom_title
         self.custom_attachment = config.custom_attachment_path
+        self.on_success = config.on_success
+        self.on_failure = config.on_failure
 
     def validate(self) -> None:
         """validate apprise configuration"""
@@ -56,7 +56,3 @@ def validate(self) -> None:
                     log.Error("Failed to parse env var for apprise urls. \
                             Ensure proper json string format")
                     raise url_err
-
-        # set default custom_title if not provided
-        if not self.custom_title:
-            self.custom_title = _DEFAULT_TITLE

bookstack_file_exporter/notify/handler.py

@@ -1,4 +1,5 @@
 import logging
+from typing import Union
 
 from bookstack_file_exporter.config_helper import models, notifications
 from bookstack_file_exporter.notify import notifiers
@@ -31,7 +32,7 @@ def _get_targets(self, config: models.Notifications):
 
         return targets
 
-    def do_notify(self, excep: Exception) -> None:
+    def do_notify(self, excep: Union[None, Exception] = None) -> None:
         """handle notification sending for all configured targets"""
         if len(self.targets) == 0:
             log.debug("No notification targets found")
@@ -40,9 +41,11 @@ def do_notify(self, excep: Exception) -> None:
             log.debug("Starting notification handling for: %s", target)
             self._supported_notifiers[target](config, excep)
 
-
     def _handle_apprise(self, config: models.AppRiseNotifyConfig, excep: Exception):
         a_config = notifications.AppRiseNotifyConfig(config)
         a_config.validate()
         apprise = notifiers.AppRiseNotify(a_config)
-        apprise.notify(excep)
+        # only send notification if on_success or on_failure is set
+        if (not excep and a_config.on_success) or (excep and a_config.on_failure):
+            log.info("Sending notification for run status")
+            apprise.notify(excep)

bookstack_file_exporter/notify/notifiers.py

@@ -1,8 +1,11 @@
 from datetime import datetime
+from typing import Union
 from apprise import Apprise, AppriseAsset, AppriseConfig
 
 from bookstack_file_exporter.config_helper import notifications
 
+_DEFAULT_TITLE_PREFIX = "Bookstack File Exporter "
+
 # pylint: disable=too-few-public-methods
 class AppRiseNotify:
     """
@@ -39,28 +42,44 @@ def _create_client(self):
         client.asset=asset
         return client
 
-    def _get_message_body(self, error_msg: str) -> str:
+    def _get_title(self, excep: Union[None, Exception]) -> str:
+        if self.config.custom_title:
+            return self.config.custom_title
+        if excep:
+            return _DEFAULT_TITLE_PREFIX + "Failed"
+        return _DEFAULT_TITLE_PREFIX + "Success"
+
+    def _get_message_text(self, error_msg: Union[None, Exception]) -> str:
         timestamp = datetime.today().strftime('%Y-%m-%d %H:%M:%S')
-        body = f"""
-        Bookstack File Exporter encountered an unrecoverable error.
-        
-        Occurred At: {timestamp}
-        
-        Error message: {error_msg}
-        """
+        if error_msg:
+            error_str = str(error_msg)
+            body = f"""
+            Bookstack File Exporter encountered an unrecoverable error.
+            
+            Occurred At: {timestamp}
+            
+            Error message: {error_str}
+            """
+        else:
+            body = f"""
+            Bookstack File Exporter completed successfully.
+            
+            Completed At: {timestamp}
+            """
         return body
 
     def notify(self, excep: Exception):
         """send notification with exception message"""
-        custom_body = self._get_message_body(str(excep))
+        custom_body = self._get_message_text(excep)
+        title_ = self._get_title(excep)
         if self.config.custom_attachment:
             self._client.notify(
-                title=self.config.custom_title,
+                title=title_,
                 body=custom_body,
                 attach=self.config.custom_attachment
             )
         else:
             self._client.notify(
-                title=self.config.custom_title,
+                title=title_,
                 body=custom_body
             )

bookstack_file_exporter/run.py

@@ -29,12 +29,13 @@ def run(config: ConfigNode):
     """run export process with error handling and notification support"""
     try:
         exporter(config)
+        if config.user_inputs.notifications:
+            notif = NotifyHandler(config.user_inputs.notifications)
+            notif.do_notify()
     except Exception as run_err: # general catch all for notifications
-        log.error("Run failed: %s", str(run_err))
         if not config.user_inputs.notifications:
             raise run_err
         try:
-            log.info("Sending failure notification(s)")
             notif = NotifyHandler(config.user_inputs.notifications)
             notif.do_notify(run_err)
         except Exception as notif_err:

examples/config.yml

@@ -88,4 +88,6 @@ notifications:
     plugin_paths: []
     storage_path: ""
     custom_title: ""
-    custom_attachment_path: ""
+    custom_attachment_path: ""
+    on_success: false
+    on_failure: true

examples/minio_config.yml

@@ -112,4 +112,6 @@ notifications:
     plugin_paths: []
     storage_path: ""
     custom_title: ""
-    custom_attachment_path: ""
+    custom_attachment_path: ""
+    on_success: false
+    on_failure: true