diff --git a/TODO-documentation.md b/TODO-documentation.md index b173ca4..305f103 100644 --- a/TODO-documentation.md +++ b/TODO-documentation.md @@ -3,7 +3,7 @@ **Branch:** `v20260207-02-wiki-documentation` **Date Started:** 2026-02-07 **Date Updated:** 2026-02-08 -**Status:** In Progress - 10 of 33 pages complete +**Status:** In Progress - 14 of 33 pages complete --- @@ -36,6 +36,12 @@ - ✅ Approved Jobs (with job-details.png) - ✅ Job Schedules (with schedule-indicators.png) +**Phase 3: Mail & Import (4/4 pages - COMPLETE)** +- ✅ Mail Import Setup +- ✅ Inbox Management +- ✅ Mail Parsing +- ✅ Auto-Import Configuration + ### Screenshots Added (10 total) 1. user-management.png - User role checkboxes 2. user-settings.png - Password change form @@ -47,12 +53,6 @@ ### Remaining Work 🚧 -**Phase 3: Mail & Import (0/4 pages - PLACEHOLDER)** -- ⏳ Mail Import Setup -- ⏳ Inbox Management -- ⏳ Mail Parsing -- ⏳ Auto-Import Configuration - **Phase 3: Backup Review (0/5 pages - PLACEHOLDER)** - ⏳ Approving Backups - ⏳ Daily Jobs View @@ -67,10 +67,10 @@ - Troubleshooting (0/3 pages) **Progress Summary:** -- ✅ 10 of 33 pages complete (30%) +- ✅ 14 of 33 pages complete (42%) - ✅ 10 screenshots added - ✅ All completed pages reviewed and corrected based on actual UI -- ⏳ 23 pages remaining (placeholders created) +- ⏳ 19 pages remaining (placeholders created) --- @@ -998,7 +998,7 @@ Add to navigation menu (after existing items): **Status:** COMPLETE **Time Spent:** ~6 hours -### Phase 3: Content Pages - Core Features 🚧 IN PROGRESS (7 of 16 complete) +### Phase 3: Content Pages - Core Features 🚧 IN PROGRESS (11 of 16 complete) - [x] User Management (3 pages) ✅ - [x] Users & Roles - [x] Login & Authentication @@ -1008,11 +1008,11 @@ Add to navigation menu (after existing items): - [x] Configuring Jobs - [x] Approved Jobs - [x] Job Schedules -- [ ] Mail & Import (4 pages) ⏳ - - [ ] Mail Import Setup - - [ ] Inbox Management - - [ ] Mail Parsing - - [ ] Auto-Import Configuration +- [x] Mail & Import (4 pages) ✅ + - [x] Mail Import Setup + - [x] Inbox Management + - [x] Mail Parsing + - [x] Auto-Import Configuration - [ ] Backup Review (5 pages) ⏳ - [ ] Approving Backups - [ ] Daily Jobs View @@ -1021,9 +1021,9 @@ Add to navigation menu (after existing items): - [ ] Remarks & Tickets - [x] Take screenshots for core features (10 screenshots added) -**Status:** 43% complete (7/16 pages) -**Time Spent:** ~12 hours -**Remaining:** ~8 hours +**Status:** 69% complete (11/16 pages) +**Time Spent:** ~16 hours +**Remaining:** ~4 hours ### Phase 4: Content Pages - Advanced Features - [ ] Reports (4 pages) diff --git a/containers/backupchecks/src/templates/documentation/mail-import/auto-import.html b/containers/backupchecks/src/templates/documentation/mail-import/auto-import.html index ab3b4b3..1b87df2 100644 --- a/containers/backupchecks/src/templates/documentation/mail-import/auto-import.html +++ b/containers/backupchecks/src/templates/documentation/mail-import/auto-import.html @@ -4,16 +4,362 @@

Auto-Import Configuration

- Configure automatic mail import. + Configure automatic email import from your Microsoft Graph mailbox to run on a schedule.

+

Overview

+ +

BackupChecks can automatically import backup report emails from your mailbox at regular intervals. This eliminates the need to manually trigger imports and ensures new backup reports are processed promptly.

+ +

Auto-import features:

+ + + +

Automatic Import

+ +

Automatic import runs continuously in the background and fetches new emails based on a configured interval.

+ +

Enabling Auto-Import

+ +

To enable automatic import:

+ +
    +
  1. Navigate to Settings → Imports tab
    2. +
  2. Locate the Automatic mail import section
    3. +
  3. Check the Enable automatic import checkbox
    4. +
  4. Set the Import interval in minutes (default: 15 minutes)
    5. +
  5. Click Save settings at the bottom of the page
    6. +
+
- 📝 Coming Soon: - This page is under construction. Full content will be added in a future update. + 💡 First Run:
+ After enabling auto-import, the first import runs immediately. Subsequent imports run at the configured interval.
-

Content

+

Import Interval

-

Detailed content will be added here in a future update.

+

The import interval determines how often BackupChecks checks for new emails:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
IntervalUse CaseRecommendation
5 minutesHigh-frequency backups, real-time monitoringMay increase server load, use only if necessary
15 minutesStandard setup (default)Recommended for most organizations
30 minutesLow-priority backups, small teamsGood balance between timeliness and load
60 minutesBatch processing, overnight backups onlySuitable for organizations with scheduled backup windows
+ +
+ 💡 Performance Consideration:
+ Shorter intervals provide faster email processing but increase server load and Microsoft Graph API usage. 15 minutes is recommended as a good balance for most organizations. +
+ +

Batch Size

+ +

Auto-import fetches a fixed number of emails per run to prevent overwhelming the system:

+ + + +

How Auto-Import Works

+ +

Here's what happens during each automatic import cycle:

+ +
    +
  1. Timer triggers: The configured interval elapses (e.g., 15 minutes)
    2. +
  2. Check settings: Verify that auto-import is still enabled
    3. +
  3. Authenticate: Obtain access token from Microsoft Graph
    4. +
  4. Fetch emails: Retrieve up to 10 new emails from the incoming folder
    5. +
  5. Parse emails: Run parsers to extract backup information
    6. +
  6. Auto-approve: If the email matches an existing approved job, automatically approve it
    7. +
  7. Move emails: Move processed emails to the processed folder (if configured)
    8. +
  8. Log results: Record import statistics in the audit log
    9. +
  9. Persist objects: Store backup objects for auto-approved runs
    10. +
  10. Wait: Sleep until the next interval
    11. +
+ +

Auto-Approval

+ +

During automatic import, BackupChecks can automatically approve emails that match previously approved jobs. This eliminates the need to manually approve recurring backup reports.

+ +

How Auto-Approval Works

+ +

An email is automatically approved if:

+ +
    +
  1. The email is successfully parsed (backup software, type, and job name extracted)
    2. +
  2. A matching job already exists in the database (based on sender, job name, backup software)
    3. +
  3. The job was previously approved by a user
    4. +
  4. The match is unique across all customers (no ambiguity)
    5. +
+ +

When auto-approved:

+ + + +
+ 💡 First Approval is Manual:
+ The first email for a new backup job must always be manually approved from the inbox. After that, future emails for the same job are automatically approved. +
+ +

When Auto-Approval Fails

+ +

If auto-approval fails, the email remains in the inbox and requires manual approval:

+ + + +

Manual Import

+ +

You can manually trigger an import at any time without waiting for the automatic import interval.

+ +

Triggering Manual Import

+ +
    +
  1. Navigate to Settings → Imports tab
    2. +
  2. Scroll to the Manual mail import section
    3. +
  3. Optionally adjust the Number of items (default: 50)
    4. +
  4. Click the Import now button
    5. +
  5. BackupChecks will immediately fetch emails from the mailbox
    6. +
  6. You'll see a success message showing how many emails were imported
    7. +
+ +

Manual Import Batch Size

+ +

Manual import allows you to configure how many emails to fetch:

+ + + +

The default batch size can be changed in Settings → Imports → Manual import batch size.

+ +
+ 💡 When to Use Manual Import:
+ Manual import is useful when: + +
+ +

Import Settings Summary

+ +

Here's a complete reference of all mail import settings:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
SettingLocationDefaultDescription
Enable automatic importSettings → ImportsDisabledTurn automatic email import on or off
Import intervalSettings → Imports15 minutesHow often to check for new emails (automatic import only)
Manual import batch sizeSettings → Imports50 messagesDefault number of emails to fetch during manual import
EML retention periodSettings → Imports7 daysHow long to store raw .eml files (0, 7, or 14 days)
+ +

Monitoring Import Activity

+ +

You can monitor import activity through several interfaces:

+ +

Audit Log

+ +

Every import operation is logged in the audit log:

+ +
    +
  1. Navigate to Settings → Maintenance → Admin events
    2. +
  2. Look for events like: + +
    3. +
  3. Event messages show statistics: fetched=10, new=3, auto_approved=7, errors=0
    4. +
+ +

Inbox Page

+ +

The inbox shows all imported emails:

+ + + +

Jobs and Daily Jobs

+ +

Auto-approved emails appear as new runs in:

+ + + +

Troubleshooting

+ +

Auto-Import Not Running

+ +

If auto-import is enabled but emails are not being imported:

+ +
    +
  1. Verify that Enable automatic import is checked in Settings → Imports
    2. +
  2. Check the audit log for mail_import_auto_error events
    3. +
  3. Verify Microsoft Graph credentials are still valid (client secret may have expired)
    4. +
  4. Ensure the BackupChecks application server is running (the background thread starts on app startup)
    5. +
  5. Check system logs for thread errors or crashes
    6. +
+ +

Emails Not Auto-Approved

+ +

If emails are imported but not auto-approved:

+ +
    +
  1. Check the Inbox - emails may be parsed but not matched to existing jobs
    2. +
  2. Verify the first email for this job was manually approved (auto-approval only works for subsequent emails)
    3. +
  3. Ensure the job name, backup software, and sender match exactly between emails
    4. +
  4. Check for duplicate jobs across different customers (auto-approval requires a unique match)
    5. +
+ +

Import Errors

+ +

If imports fail with errors:

+ + + +

Best Practices

+ + + +

Advanced Configuration

+ +

Disabling Auto-Import Temporarily

+ +

To temporarily stop automatic imports without losing configuration:

+ +
    +
  1. Navigate to Settings → Imports
    2. +
  2. Uncheck Enable automatic import
    3. +
  3. Click Save settings
    4. +
  4. The background thread will stop fetching emails but settings are preserved
    5. +
  5. Re-enable later by checking the box again
    6. +
+ +

EML Storage Retention

+ +

Control how long raw .eml files are stored in the database:

+ + + +

Older .eml files are automatically purged based on this retention period.

+ +

High-Volume Environments

+ +

For organizations with hundreds of backup jobs:

+ + + +

Next Steps

+ + {% endblock %} diff --git a/containers/backupchecks/src/templates/documentation/mail-import/inbox-management.html b/containers/backupchecks/src/templates/documentation/mail-import/inbox-management.html index 735a704..8b721da 100644 --- a/containers/backupchecks/src/templates/documentation/mail-import/inbox-management.html +++ b/containers/backupchecks/src/templates/documentation/mail-import/inbox-management.html @@ -4,16 +4,354 @@

Inbox Management

- Manage incoming backup report emails. + Review incoming backup report emails, examine parsed results, and approve jobs for monitoring.

+

Overview

+ +

The Inbox is the central location where all imported backup report emails appear before being approved and linked to jobs. Think of it as a staging area where you review and validate incoming backup reports.

+ +

The inbox workflow:

+ +
    +
  1. Import: Emails are automatically imported from your mailbox
    2. +
  2. Parse: BackupChecks automatically parses email content to extract backup information
    3. +
  3. Review: You review the parsed results in the inbox
    4. +
  4. Approve: You approve emails to create backup jobs and link future reports
    5. +
  5. Monitor: Approved jobs appear in Daily Jobs and other operational views
    6. +
+ +

Accessing the Inbox

+ +

To access the inbox:

+ +
    +
  1. Navigate to Inbox in the main navigation menu
    2. +
  2. Available to Admin, Operator, and Viewer roles
    3. +
  3. Viewers can see emails but cannot approve or delete them
    4. +
+ +

Inbox Page Layout

+ +

The Inbox page displays a table with all imported emails. Each row represents one email message.

+ +

Table Columns

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ColumnDescription
FromSender email address (e.g., backups@veeam.com)
SubjectEmail subject line
Date / timeWhen the email was received (in configured timezone)
BackupDetected backup software (e.g., Veeam, Synology, NAKIVO)
TypeBackup job type (e.g., Backup Job, Replication Job)
Job nameExtracted backup job name from email content
OverallOverall status extracted from email (Success, Warning, Failed)
ParsedTimestamp when the email was parsed
EMLCheckmark (✓) if raw .eml file is stored
+ +

Pagination

+ +

The inbox displays 50 emails per page. Use the pagination controls at the top and bottom of the table:

+ + + +

Viewing Email Details

+ +

To view the full content and parsed details of an email:

+ +
    +
  1. Click anywhere on the email row in the inbox table
    2. +
  2. A large modal dialog opens showing the email details
    3. +
+ +

Email Detail Modal

+ +

The email detail modal contains three main sections:

+ +

1. Metadata Section (Top)

+ +

Displays email header information:

+ + + +

2. Email Body (Middle)

+ +

The email body is displayed in an embedded iframe:

+ + +
- 📝 Coming Soon: - This page is under construction. Full content will be added in a future update. + 💡 HTML Rendering:
+ The email body is sandboxed in an iframe for security. This prevents malicious scripts from executing while still allowing you to see the formatted email content.
-

Content

+

3. Parsed Objects (Bottom)

-

Detailed content will be added here in a future update.

+

If the email was successfully parsed, this section shows the backup objects extracted from the email:

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
ColumnDescription
NameObject name (VM name, server name, etc.)
Object typeType of object (e.g., VM, Server, Repository)
StatusStatus of this object (Success, Warning, Failed)
MessageAny error or warning message for this object
+ +

For example, a Veeam backup job email might show:

+ + + +

Approving Emails

+ +

Approving an email creates a backup job in BackupChecks and links it to a customer. Future emails matching the same job will be automatically linked.

+ +

How to Approve

+ +
    +
  1. Open the email detail modal by clicking on an inbox row
    2. +
  2. Review the email content and parsed objects
    3. +
  3. Click the Approve button at the top of the modal
    4. +
  4. An approval dialog opens with two fields: + +
    5. +
  5. Select the customer from the dropdown (or start typing to search)
    6. +
  6. Verify or adjust the job name
    7. +
  7. Click Confirm to approve
    8. +
+ +
+ 💡 Customer Selection:
+ Always create the customer account before approving emails. This allows you to immediately link the job to the correct customer. See Managing Customers for details. +
+ +

What Happens After Approval

+ +

When you approve an email:

+ +
    +
  1. A Job record is created in the database (if it doesn't already exist)
    2. +
  2. A JobRun record is created, representing this specific backup run
    3. +
  3. JobObject records are created for each parsed object (VMs, servers, etc.)
    4. +
  4. The email is marked as approved and moved out of the inbox
    5. +
  5. The job immediately appears in Jobs, Daily Jobs, and Run Checks pages
    6. +
  6. Future emails matching the same job are automatically linked without manual approval
    7. +
+ +
+ ⚠️ Job Matching:
+ After approval, future emails are matched to this job based on sender address, job name, and backup software. If these change (e.g., job is renamed), you may need to approve a new email to create a new job record. +
+ +

Re-parsing Emails

+ +

If an email was not parsed correctly, you can re-parse it after updating parser configuration.

+ +

Re-parse Single Email

+ +

To re-parse a single email:

+ +
    +
  1. Open the email detail modal
    2. +
  2. Click the Re-parse button
    3. +
  3. BackupChecks will re-run all parsers on this email
    4. +
  4. The modal will refresh with updated parsed results
    5. +
+ +

Re-parse All Emails

+ +

To re-parse all emails in the inbox at once:

+ +
    +
  1. At the top of the inbox page, click the Re-parse all button
    2. +
  2. This re-runs parsers on all inbox emails
    3. +
  3. Useful after adding new parsers or fixing parser bugs
    4. +
+ +
+ 💡 When to Re-parse:
+ Re-parsing is useful when emails were imported before a parser was configured, or when parser logic has been updated. Re-parsing does not re-fetch emails from the mailbox - it only re-processes emails already in the database. +
+ +

Deleting Emails

+ +

Admins and Operators can delete emails from the inbox.

+ +

Delete Single Email

+ +
    +
  1. Open the email detail modal
    2. +
  2. Click the Delete button
    3. +
  3. Confirm the deletion
    4. +
  4. The email is marked as deleted and moved out of the inbox
    5. +
+ +

Bulk Delete Emails

+ +
    +
  1. Check the checkboxes next to emails you want to delete
    2. +
  2. Click the Delete selected button at the top of the inbox
    3. +
  3. Confirm the bulk deletion
    4. +
+ +
+ ⚠️ Soft Delete:
+ Emails are soft-deleted, not permanently removed. Deleted emails are hidden from the inbox but remain in the database. Admins can view deleted emails in Settings → Maintenance → Deleted mails. +
+ +

Downloading .EML Files

+ +

If EML storage is enabled, you can download the original .eml file for any email:

+ +
    +
  1. Open the email detail modal
    2. +
  2. Click the Download .eml button
    3. +
  3. The raw .eml file is downloaded to your browser
    4. +
  4. You can open this file in Outlook, Thunderbird, or any email client
    5. +
+ +

This is useful for:

+ + + +

Inbox Filters and Search

+ +

The inbox currently displays all imported emails in chronological order (newest first). Filtering and search features are planned for a future update.

+ +
+ 📝 Future Feature:
+ Search and filter capabilities (by sender, subject, backup software, status) are planned to help manage large inboxes. For now, use the pagination controls to browse emails. +
+ +

Common Workflows

+ +

Setting Up a New Customer

+ +
    +
  1. Create the customer in Customers page
    2. +
  2. Wait for backup reports to arrive in the inbox (or trigger a manual import)
    3. +
  3. Review each email for the customer in the inbox
    4. +
  4. Approve each email, selecting the new customer from the dropdown
    5. +
  5. Jobs are now created and linked to the customer
    6. +
  6. Future reports are automatically linked without approval
    7. +
+ +

Troubleshooting Unparsed Emails

+ +
    +
  1. Find emails with empty Backup or Job name columns
    2. +
  2. Open the email detail modal
    3. +
  3. Review the email body to understand its format
    4. +
  4. Check if a parser exists for this backup software in Settings → Parsers
    5. +
  5. If no parser exists, request one or create a custom parser
    6. +
  6. After adding a parser, use Re-parse to process the email again
    7. +
+ +

Cleaning Up Spam or Test Emails

+ +
    +
  1. Identify unwanted emails in the inbox (e.g., spam, test messages)
    2. +
  2. Select them using checkboxes
    3. +
  3. Click Delete selected
    4. +
  4. Configure mail rules in your mailbox to prevent future spam
    5. +
+ +

Best Practices

+ + + +

Next Steps

+ + {% endblock %} diff --git a/containers/backupchecks/src/templates/documentation/mail-import/mail-parsing.html b/containers/backupchecks/src/templates/documentation/mail-import/mail-parsing.html index 500c157..134cba9 100644 --- a/containers/backupchecks/src/templates/documentation/mail-import/mail-parsing.html +++ b/containers/backupchecks/src/templates/documentation/mail-import/mail-parsing.html @@ -4,16 +4,370 @@

Mail Parsing

- Learn how email parsing works. + Understand how BackupChecks automatically extracts backup information from email reports using parsers.

+

Overview

+ +

When emails are imported from your mailbox, BackupChecks automatically parses (analyzes) the email content to extract structured backup information. This eliminates the need to manually read each email and enter data.

+ +

Parsing extracts:

+ + + +

How Parsing Works

+ +

The mail parsing process follows these steps:

+ +
    +
  1. Retrieval: Email is imported from Microsoft Graph and stored as a MailMessage record
    2. +
  2. Preprocessing: Email body is normalized (line endings, character encoding) for consistent parsing
    3. +
  3. Parser selection: All active parsers are evaluated in order to find a match
    4. +
  4. Matching: Each parser checks if the email matches its criteria (sender, subject, body patterns)
    5. +
  5. Parsing: When a match is found, the parser extracts backup information from the email
    6. +
  6. Storage: Parsed data is stored in the database and linked to the email
    7. +
+ +

Parsers

+ +

A parser is a piece of code that knows how to extract backup information from a specific backup software's email format.

+ +

Viewing Available Parsers

+ +

To see all available parsers:

+ +
    +
  1. Navigate to Settings → Parsers (Admin only)
    2. +
  2. The parsers page shows a table with all parsers and their configuration
    3. +
+ +

Parser Information

+ +

Each parser entry shows:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ColumnDescription
NameUnique identifier for the parser (e.g., veeam_backup_job)
Backup softwareThe product this parser handles (e.g., Veeam, NAKIVO)
Backup type(s)Types of jobs this parser supports (e.g., Backup Job, Replication Job)
Match criteriaRules used to identify matching emails (sender, subject, body patterns)
OrderEvaluation order (lower numbers are checked first)
EnabledCheckbox to enable/disable this parser
+ +

Match Criteria

+ +

Parsers use match criteria to determine if an email matches their expected format. Common criteria include:

+ +

Sender Match

+ +

Match based on the sender's email address:

+ + + +

Subject Match

+ +

Match based on the email subject line:

+ + + +

Body Match

+ +

Match based on email body content (not shown in table but used internally):

+ + + +

Supported Backup Software

+ +

BackupChecks includes built-in parsers for popular backup solutions:

+ +

Veeam Backup & Replication

+ + + +

Synology Active Backup

+ + + +

NAKIVO Backup & Replication

+ + + +

Other Supported Software

+ +

Additional parsers exist for:

+ + +
- 📝 Coming Soon: - This page is under construction. Full content will be added in a future update. + 💡 Custom Parsers:
+ If your backup software is not listed, you can request a custom parser or create one yourself if you have Python development skills. Parser code is located in backend/app/parsers/.
-

Content

+

Parser Execution Order

-

Detailed content will be added here in a future update.

+

When an email is parsed, BackupChecks evaluates parsers in a specific order based on their Order value. This is important because:

+ + + +

For example:

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
OrderParserRationale
1veeam_replication_jobSpecific Veeam job type - check before generic Veeam parser
2veeam_backup_jobGeneric Veeam parser - fallback for other Veeam emails
10synology_active_backupUnrelated to Veeam - order doesn't matter relative to Veeam
+ +

Enabling and Disabling Parsers

+ +

You can enable or disable individual parsers without deleting them. This is useful when:

+ + + +

How to Disable a Parser

+ +
    +
  1. Navigate to Settings → Parsers
    2. +
  2. Find the parser you want to disable
    3. +
  3. Uncheck the Enabled checkbox
    4. +
  4. The parser will no longer be evaluated for new emails
    5. +
+ +
+ ⚠️ Impact of Disabling:
+ Disabling a parser affects future email parsing only. Already-parsed emails are not affected. If you disable a parser, emails that would have matched it will remain unparsed (blank backup software and job name). +
+ +

Re-parsing Emails

+ +

If parsing fails or produces incorrect results, you can re-parse emails after fixing the issue.

+ +

When to Re-parse

+ + + +

How to Re-parse

+ +
    +
  1. Single email: Open the email detail modal in the inbox and click Re-parse
    2. +
  2. All inbox emails: Click Re-parse all at the top of the inbox page
    3. +
+ +
+ 💡 Re-parsing is Safe:
+ Re-parsing only updates parsed fields (backup software, job name, objects, etc.). It does not re-fetch the email from the mailbox or modify the original email content stored in the database. +
+ +

Parsing Workflow Example

+ +

Here's how a typical Veeam backup email is parsed:

+ +

Example Email

+ + + +

Parsing Steps

+ +
    +
  1. Import: Email is fetched from Graph API and stored
    2. +
  2. Match: Veeam backup job parser matches (sender contains 'veeam.com', subject contains '[Veeam]')
    3. +
  3. Extract: Parser extracts: + +
    4. +
  4. Store: Data is saved to the database
    5. +
  5. Display: Email appears in inbox with parsed fields populated
    6. +
+ +

Troubleshooting Parsing Issues

+ +

Email Not Parsed (Blank Fields)

+ +

If an email shows blank Backup software or Job name:

+ +
    +
  1. Check if a parser exists for this backup software in Settings → Parsers
    2. +
  2. If no parser exists, you'll need to create or request one
    3. +
  3. If a parser exists, check that it's enabled
    4. +
  4. Verify the email format matches the parser's expected format (sender, subject, body structure)
    5. +
  5. Check parser order - a different parser may be matching first
    6. +
+ +

Incorrect Parsing Results

+ +

If parsing produces wrong job names or objects:

+ +
    +
  1. Verify the email format hasn't changed (backup software update may change email templates)
    2. +
  2. Check if the wrong parser is matching (disable it temporarily to test)
    3. +
  3. Review parser match criteria - may be too broad and matching unintended emails
    4. +
  4. Contact support or review parser code to identify the issue
    5. +
+ +

Partial Parsing

+ +

If some fields parse correctly but others don't:

+ + + +

Parser Limitations

+ +

Parsers have some inherent limitations:

+ + + +
+ 💡 Future Enhancement:
+ AI-powered parsing (using LLMs to interpret backup emails) is being considered for future versions to handle more diverse email formats without custom parsers. +
+ +

Best Practices

+ + + +

Next Steps

+ + {% endblock %} diff --git a/containers/backupchecks/src/templates/documentation/mail-import/setup.html b/containers/backupchecks/src/templates/documentation/mail-import/setup.html index 5bfbedd..50e5bf8 100644 --- a/containers/backupchecks/src/templates/documentation/mail-import/setup.html +++ b/containers/backupchecks/src/templates/documentation/mail-import/setup.html @@ -4,16 +4,306 @@

Mail Import Setup

- Configure Microsoft Graph API integration. + Configure Microsoft Graph API integration to automatically retrieve backup report emails from an Exchange Online mailbox.

+

Overview

+ +

BackupChecks uses the Microsoft Graph API to retrieve emails from an Exchange Online (Microsoft 365) mailbox. This allows the system to automatically import backup reports sent to a dedicated mailbox.

+ +

The mail import process involves:

+ + +
- 📝 Coming Soon: - This page is under construction. Full content will be added in a future update. + 💡 Why Microsoft Graph?
+ BackupChecks uses Microsoft Graph API instead of traditional IMAP/POP3 because it provides better security (OAuth2), reliability, and integration with Microsoft 365 environments. Most organizations already use Microsoft 365 for email, making this the most convenient option.
-

Content

+

Prerequisites

-

Detailed content will be added here in a future update.

+

Before configuring mail import in BackupChecks, you need:

+ +
    +
  1. Microsoft 365 subscription with Exchange Online
    2. +
  2. Dedicated mailbox for receiving backup reports (e.g., backupreports@yourdomain.com)
    3. +
  3. Azure AD application registration with Mail.Read and Mail.ReadWrite permissions
    4. +
  4. Admin access to BackupChecks to configure settings
    5. +
+ +

Step 1: Create Azure AD App Registration

+ +

To allow BackupChecks to access your mailbox, you must create an Azure AD app registration and grant it the necessary permissions.

+ +

1.1 Register the Application

+ +
    +
  1. Sign in to the Azure Portal
    2. +
  2. Navigate to Azure Active Directory → App registrations
    3. +
  3. Click New registration
    4. +
  4. Enter a name (e.g., "BackupChecks Mail Importer")
    5. +
  5. Select Accounts in this organizational directory only
    6. +
  6. Leave Redirect URI blank
    7. +
  7. Click Register
    8. +
+ +

After registration, note the following values from the Overview page:

+ + + +

1.2 Create a Client Secret

+ +
    +
  1. In your app registration, go to Certificates & secrets
    2. +
  2. Click New client secret
    3. +
  3. Enter a description (e.g., "BackupChecks access")
    4. +
  4. Select an expiration period (recommended: 24 months)
    5. +
  5. Click Add
    6. +
  6. Important: Copy the secret Value immediately - you cannot view it again later
    7. +
+ +
+ ⚠️ Secret Expiration:
+ Client secrets expire after the selected period. Set a calendar reminder to renew the secret before expiration, or mail import will stop working. When renewing, create a new secret, update BackupChecks settings, then delete the old secret. +
+ +

1.3 Grant API Permissions

+ +

BackupChecks requires application permissions (not delegated) to access the mailbox:

+ +
    +
  1. In your app registration, go to API permissions
    2. +
  2. Click Add a permission
    3. +
  3. Select Microsoft Graph
    4. +
  4. Select Application permissions (not Delegated)
    5. +
  5. Search for and add the following permissions: + +
    6. +
  6. Click Add permissions
    7. +
  7. Important: Click Grant admin consent for [your organization]
    8. +
  8. Confirm the consent
    9. +
+ +
+ 💡 Why ReadWrite?
+ The Mail.ReadWrite permission is required to move processed emails from the incoming folder to the processed folder. If you only grant Mail.Read, BackupChecks can import emails but cannot move them after processing. +
+ +

Step 2: Configure Mail Settings in BackupChecks

+ +

After creating the Azure AD app registration, configure BackupChecks to use it:

+ +
    +
  1. Log in to BackupChecks as an Admin
    2. +
  2. Navigate to Settings → General tab
    3. +
  3. Scroll to the Mail (Microsoft Graph) section
    4. +
+ +

2.1 Enter Graph Credentials

+ +

Fill in the following fields with values from your Azure AD app registration:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescriptionExample
Tenant IDAzure AD Directory (tenant) ID12345678-1234-1234-1234-123456789abc
Client IDAzure AD Application (client) ID87654321-4321-4321-4321-abcdef123456
Client secretThe secret value you copied in Step 1.2abc123...xyz789
Mailbox addressEmail address of the mailbox to import frombackupreports@yourdomain.com
+ +
+ 💡 Security Note:
+ The client secret field shows ******** (stored) when a secret is already saved. Leave this field empty to keep the existing secret, or enter a new secret to replace it. +
+ +

2.2 Configure Mail Folders

+ +

BackupChecks uses two folders in the mailbox:

+ + + + + + + + + + + + + + + + + + + + + +
FolderPurposeExample Path
Incoming folderWhere backup reports arrive and are fetched fromInbox or Inbox/Backup Reports
Processed folderWhere emails are moved after processingArchive or Inbox/Processed
+ +

To configure folders:

+ +
    +
  1. Click the Browse... button next to the Incoming folder field
    2. +
  2. A folder browser dialog will open showing your mailbox folder structure
    3. +
  3. Select the folder where backup reports arrive (e.g., Inbox)
    4. +
  4. Click Select
    5. +
  5. Repeat for the Processed folder (e.g., Archive or create a subfolder like Inbox/Processed)
    6. +
+ +
+ ⚠️ Folder Structure:
+ Folder paths are case-sensitive and use forward slashes (/) to separate levels. For example: Inbox/Backup Reports refers to a subfolder named "Backup Reports" inside the Inbox folder. +
+ +

2.3 Save Settings

+ +

After entering all credentials and folder paths:

+ +
    +
  1. Click Save settings at the bottom of the page
    2. +
  2. BackupChecks will validate the configuration
    3. +
  3. If successful, you'll see a confirmation message
    4. +
  4. If there's an error, check your credentials and folder paths
    5. +
+ +

Step 3: Test the Configuration

+ +

After saving settings, verify that mail import is working:

+ +
    +
  1. Send a test backup report email to your configured mailbox address
    2. +
  2. Wait a few minutes for the scheduled import to run (or trigger a manual import - see below)
    3. +
  3. Navigate to Inbox in BackupChecks
    4. +
  4. Verify that the test email appears in the inbox
    5. +
+ +

Manual Import

+ +

To manually trigger a mail import without waiting for the scheduled task:

+ +
    +
  1. Navigate to Settings → Imports tab
    2. +
  2. Click the Import now button in the "Mail import" section
    3. +
  3. BackupChecks will immediately fetch new emails from the incoming folder
    4. +
  4. Check the Inbox page to see imported emails
    5. +
+ +
+ 💡 Import Schedule:
+ By default, BackupChecks automatically imports new emails every 15 minutes. Manual import is useful for testing or when you need immediate import of a new email. +
+ +

Troubleshooting

+ +

Authentication Errors

+ +

If you see "Failed to obtain access token" errors:

+ + + +

Folder Not Found Errors

+ +

If folder configuration fails:

+ + + +

No Emails Imported

+ +

If manual import succeeds but no emails appear:

+ + + +

Advanced Configuration

+ +

Email Retention

+ +

BackupChecks stores email content in the database but can also retain the original .eml file for a specified period:

+ + + +

This setting is configured in Settings → Imports tab.

+ +

Multiple Mailboxes

+ +

BackupChecks currently supports importing from one mailbox at a time. If you need to monitor multiple mailboxes:

+ + + +

Security Best Practices

+ + + +

Next Steps

+ + {% endblock %} diff --git a/docs/changelog-claude.md b/docs/changelog-claude.md index a0486eb..609464a 100644 --- a/docs/changelog-claude.md +++ b/docs/changelog-claude.md @@ -4,6 +4,13 @@ This file documents all changes made to this project via Claude Code. ## [2026-02-08] +### Added +- Completed Mail & Import documentation section (4 pages): + - **Mail Import Setup**: Microsoft Graph API configuration (Azure AD app registration, permissions, credentials), folder configuration (incoming/processed), test configuration, troubleshooting (authentication errors, folder not found, no emails imported), advanced configuration (email retention, multiple mailboxes), security best practices + - **Inbox Management**: Inbox overview and workflow, table columns explanation, viewing email details (metadata, body iframe, parsed objects), approving emails (customer selection, job name), what happens after approval, re-parsing emails (single and bulk), deleting emails (single and bulk delete, soft delete behavior), downloading .eml files, common workflows (new customer setup, troubleshooting unparsed emails, cleaning spam), best practices + - **Mail Parsing**: Parsing overview and workflow (retrieval, preprocessing, parser selection, matching, parsing, storage), parsers (viewing available parsers, parser information), match criteria (sender, subject, body match), supported backup software (Veeam, Synology, NAKIVO, Boxafe, Panel3, QNAP, Syncovery, 3CX, RDrive, NTFS Auditing), parser execution order, enabling/disabling parsers, re-parsing emails, parsing workflow example, troubleshooting parsing issues, parser limitations, best practices + - **Auto-Import Configuration**: Auto-import overview and features, enabling auto-import, import interval configuration (5/15/30/60 minutes), batch size explanation, how auto-import works (timer, check settings, authenticate, fetch, parse, auto-approve, move, log, persist, wait), auto-approval logic and conditions, when auto-approval fails, manual import (triggering, batch size 1-50), import settings summary table, monitoring import activity (audit log, inbox page, jobs/daily jobs), troubleshooting (auto-import not running, emails not auto-approved, import errors), best practices, advanced configuration (disabling temporarily, EML retention, high-volume environments) + ### Added - Added comprehensive documentation system for user onboarding and reference: - **Documentation Blueprint**: New `/documentation` route with dedicated blueprint (doc_bp)