Skip to content

Setting up System Notifications

This guide explains how to set up the notification system for DocuElevate, which allows you to receive alerts about important system events.

Required Configuration Parameters

Variable Description
NOTIFICATION_URLS Comma-separated list of Apprise notification URLs
NOTIFY_ON_TASK_FAILURE Send notifications on task failures (True/False)
NOTIFY_ON_CREDENTIAL_FAILURE Send notifications on credential failures (True/False)
NOTIFY_ON_STARTUP Send notification when system starts (True/False)
NOTIFY_ON_SHUTDOWN Send notification when system shuts down (True/False)
NOTIFY_ON_FILE_PROCESSED Send notifications when files are processed (True/False)

For a complete list of configuration options, see the Configuration Guide.

Overview

DocuElevate uses the Apprise library to provide a flexible notification system that supports over 70 different notification services, including:

  • Email
  • SMS
  • Messaging apps (Telegram, Discord, Slack, Matrix, etc.)
  • Push notification services (Pushover, Pushbullet, etc.)
  • Web hooks
  • And many more

Setting up Notifications

1. Choose Your Notification Services

First, decide which notification services you want to use. The Apprise library supports a wide range of services, each with its own URL format. Here are some common examples:

  • Discord: discord://webhook_id/webhook_token
  • Telegram: tgram://bot_token/chat_id
  • Email: mailto://user:pass@example.com
  • Pushover: pover://user_key/app_token
  • Slack: slack://tokenA/tokenB/tokenC
  • Matrix: matrix://username:password@domain/#room
  • Microsoft Teams: msteams://token_a/token_b/token_c
  • Gotify: gotify://hostname/token

For a complete list of supported services and their URL formats, see the Apprise Wiki.

2. Configure Your Notification URLs

Set the NOTIFICATION_URLS environment variable with a comma-separated list of your notification service URLs:

NOTIFICATION_URLS=discord://webhook_id/webhook_token,mailto://user:pass@gmail.com,tgram://bot_token/chat_id

You can specify as many notification services as you need.

3. Configure Notification Triggers

DocuElevate can send notifications for various system events. Configure which events should trigger notifications:

NOTIFY_ON_TASK_FAILURE=True        # Notify when background tasks fail
NOTIFY_ON_CREDENTIAL_FAILURE=True  # Notify when service credentials fail (e.g. API token expired)
NOTIFY_ON_STARTUP=True             # Notify when the system starts
NOTIFY_ON_SHUTDOWN=False           # Notify when the system shuts down
NOTIFY_ON_FILE_PROCESSED=True      # Notify when files are successfully processed

File Processing Notifications

DocuElevate can notify you whenever a document is successfully processed and uploaded to your configured destinations. When enabled, you'll receive a notification containing:

  • File name: The name of the processed document
  • File size: Size of the processed file
  • Document type: The type of document detected by AI (invoice, receipt, contract, etc.)
  • Tags: Any tags extracted from the document
  • Destinations: List of destinations where the file was uploaded

This feature is particularly useful for: - Tracking document processing in real-time - Confirming important documents have been processed - Monitoring the document processing workflow - Receiving immediate feedback when uploading documents via email or API

To enable file processing notifications:

NOTIFY_ON_FILE_PROCESSED=True

Example notification:

Subject: File Processed: Invoice_2024-01-15.pdf

File: Invoice_2024-01-15.pdf
Size: 1.23 MB
Document Type: Invoice
Tags: financial, vendor-acme, urgent
Destinations: Dropbox, Google Drive, Paperless-ngx

The file has been successfully processed and is being uploaded to all configured destinations.

Automated Credential Checking

DocuElevate includes a powerful credential monitoring system that regularly checks the validity of your configured service credentials. This helps you proactively address authentication issues before they affect your document processing workflows.

How Credential Checking Works

  1. Regular Monitoring: The system automatically checks all configured service credentials at regular intervals (every 5 minutes) and at startup.

  2. Smart Notifications: When credential failures are detected, the system sends notifications through your configured notification channels.

  3. Notification Rate Limiting: To prevent notification spam, alerts follow a progressive notification strategy:

  4. First 3 failures: Notification sent for each failure
  5. Subsequent failures: Notifications suppressed until credential is restored

  6. Recovery: Notification sent when credentials are working again

  7. Services Monitored:

  8. OpenAI API
  9. Azure Document Intelligence
  10. Dropbox
  11. Google Drive
  12. OneDrive/Microsoft Graph
  13. Other configured storage providers

Notification Content

When a credential failure is detected, the notification includes: - The affected service name - The specific error message - A reminder to check and update credentials

Example notification:

Subject: Credential Failure: Dropbox

The credentials for Dropbox have failed:
Invalid refresh token: Token has been revoked or expired.

Please check and update the credentials in the system settings.

Configuration Options

To control credential check notifications:

# Enable/disable credential failure notifications
NOTIFY_ON_CREDENTIAL_FAILURE=True

When set to False, the system will still perform the checks but won't send notifications about failures.

Troubleshooting Credential Issues

If you receive credential failure notifications:

  1. Check token expiration: For OAuth-based services (Google Drive, OneDrive, Dropbox), refresh tokens may have expired.

  2. Verify API keys: Ensure your API keys for services like OpenAI and Azure Document Intelligence are still valid.

  3. Check service status: The service itself might be experiencing downtime.

  4. Review quota limits: Some services have usage quotas that might have been exceeded.

  5. Regenerate credentials: Use the built-in auth wizards to generate new tokens:

  6. Go to Settings > [Service Name] Setup
  7. Click "Refresh Token" or "Start Authentication Flow"
  8. Complete the authentication process to generate new credentials

Viewing Credential Status

You can view the current status of your service credentials in the system dashboard:

  1. Navigate to the Status page in the DocuElevate interface
  2. Check the Service Status section
  3. Each service will show its current status (Valid, Invalid, or Not Configured)

Service-Specific Setup Instructions

Discord Notifications

  1. Go to your Discord server
  2. Select a channel or create a new one for notifications
  3. Go to Server Settings > Integrations > Webhooks
  4. Click "New Webhook" and set up a webhook for your channel
  5. Copy the webhook URL (it will look like https://discord.com/api/webhooks/123456789/abcdefg)
  6. Extract the webhook ID and token (the parts after webhooks/)
  7. Format your Apprise URL as: discord://123456789/abcdefg

Telegram Notifications

  1. Start a chat with @BotFather on Telegram
  2. Create a new bot using the /newbot command
  3. Note the bot token provided by BotFather
  4. Start a chat with your new bot or add it to a group
  5. Get the chat ID:
  6. For direct messages: send a message to the bot, then visit https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates
  7. For group chats: add the bot to the group, send a message mentioning the bot, then check the same URL
  8. Format your Apprise URL as: tgram://bot_token/chat_id

Email Notifications

To send notifications via email, configure the Apprise URL with your SMTP server details:

# Gmail example
mailto://your-email@gmail.com:password@smtp.gmail.com?smtp=587

For Gmail, you'll need to use an app password if you have 2FA enabled.

Task Failure Notifications

In addition to credential monitoring, DocuElevate can notify you about background task failures. When enabled, the system will send notifications whenever a background processing task encounters an error.

To configure task failure notifications:

# Enable/disable task failure notifications
NOTIFY_ON_TASK_FAILURE=True

Task failure notifications include: - Task name and ID - Error type and message - Task arguments (for debugging)

Testing Your Notification Setup

To test your notification setup once configured:

  1. Start the DocuElevate application
  2. If NOTIFY_ON_STARTUP=True, you should receive a notification when the system starts
  3. Check the application logs for any errors related to notifications

Security Considerations

When setting up notifications:

  1. Protect your credentials: Keep your notification URLs secure, as they often contain access tokens or passwords.
  2. Use environment variables: Store notification URLs in environment variables rather than hard-coding them.
  3. Limit notification content: Be mindful of sending sensitive information in notifications.
  4. Consider encryption: For highly sensitive environments, consider using encrypted notification channels.

Troubleshooting

If you're not receiving notifications:

  1. Check service connectivity: Ensure the DocuElevate server can access the notification services.
  2. Verify URL format: Double-check the format of your notification URLs.
  3. Check application logs: Look for errors related to the notification system in logs.
  4. Test services individually: Try configuring one notification service at a time to isolate issues.
  5. Check service-specific limits: Some services have rate limits on notifications.

For more general configuration issues, see the Configuration Troubleshooting Guide.