Complete Mail & Import documentation section (4 pages)
Added comprehensive documentation for the Mail & Import section: - Mail Import Setup: Microsoft Graph API configuration, Azure AD app registration, folder setup, troubleshooting, and security best practices - Inbox Management: Email review workflow, approval process, re-parsing, deletion, and common workflows - Mail Parsing: Parser system explanation, supported backup software, match criteria, execution order, and troubleshooting - Auto-Import Configuration: Automatic import scheduling, intervals, batch sizes, auto-approval logic, manual import, and monitoring Updated TODO-documentation.md to reflect progress (14 of 33 pages, 42% complete) Updated changelog-claude.md with detailed content descriptions Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
parent
b9f463d048
commit
24cca64824
@ -3,7 +3,7 @@
|
|||||||
**Branch:** `v20260207-02-wiki-documentation`
|
**Branch:** `v20260207-02-wiki-documentation`
|
||||||
**Date Started:** 2026-02-07
|
**Date Started:** 2026-02-07
|
||||||
**Date Updated:** 2026-02-08
|
**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)
|
- ✅ Approved Jobs (with job-details.png)
|
||||||
- ✅ Job Schedules (with schedule-indicators.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)
|
### Screenshots Added (10 total)
|
||||||
1. user-management.png - User role checkboxes
|
1. user-management.png - User role checkboxes
|
||||||
2. user-settings.png - Password change form
|
2. user-settings.png - Password change form
|
||||||
@ -47,12 +53,6 @@
|
|||||||
|
|
||||||
### Remaining Work 🚧
|
### 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)**
|
**Phase 3: Backup Review (0/5 pages - PLACEHOLDER)**
|
||||||
- ⏳ Approving Backups
|
- ⏳ Approving Backups
|
||||||
- ⏳ Daily Jobs View
|
- ⏳ Daily Jobs View
|
||||||
@ -67,10 +67,10 @@
|
|||||||
- Troubleshooting (0/3 pages)
|
- Troubleshooting (0/3 pages)
|
||||||
|
|
||||||
**Progress Summary:**
|
**Progress Summary:**
|
||||||
- ✅ 10 of 33 pages complete (30%)
|
- ✅ 14 of 33 pages complete (42%)
|
||||||
- ✅ 10 screenshots added
|
- ✅ 10 screenshots added
|
||||||
- ✅ All completed pages reviewed and corrected based on actual UI
|
- ✅ 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
|
**Status:** COMPLETE
|
||||||
**Time Spent:** ~6 hours
|
**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] User Management (3 pages) ✅
|
||||||
- [x] Users & Roles
|
- [x] Users & Roles
|
||||||
- [x] Login & Authentication
|
- [x] Login & Authentication
|
||||||
@ -1008,11 +1008,11 @@ Add to navigation menu (after existing items):
|
|||||||
- [x] Configuring Jobs
|
- [x] Configuring Jobs
|
||||||
- [x] Approved Jobs
|
- [x] Approved Jobs
|
||||||
- [x] Job Schedules
|
- [x] Job Schedules
|
||||||
- [ ] Mail & Import (4 pages) ⏳
|
- [x] Mail & Import (4 pages) ✅
|
||||||
- [ ] Mail Import Setup
|
- [x] Mail Import Setup
|
||||||
- [ ] Inbox Management
|
- [x] Inbox Management
|
||||||
- [ ] Mail Parsing
|
- [x] Mail Parsing
|
||||||
- [ ] Auto-Import Configuration
|
- [x] Auto-Import Configuration
|
||||||
- [ ] Backup Review (5 pages) ⏳
|
- [ ] Backup Review (5 pages) ⏳
|
||||||
- [ ] Approving Backups
|
- [ ] Approving Backups
|
||||||
- [ ] Daily Jobs View
|
- [ ] Daily Jobs View
|
||||||
@ -1021,9 +1021,9 @@ Add to navigation menu (after existing items):
|
|||||||
- [ ] Remarks & Tickets
|
- [ ] Remarks & Tickets
|
||||||
- [x] Take screenshots for core features (10 screenshots added)
|
- [x] Take screenshots for core features (10 screenshots added)
|
||||||
|
|
||||||
**Status:** 43% complete (7/16 pages)
|
**Status:** 69% complete (11/16 pages)
|
||||||
**Time Spent:** ~12 hours
|
**Time Spent:** ~16 hours
|
||||||
**Remaining:** ~8 hours
|
**Remaining:** ~4 hours
|
||||||
|
|
||||||
### Phase 4: Content Pages - Advanced Features
|
### Phase 4: Content Pages - Advanced Features
|
||||||
- [ ] Reports (4 pages)
|
- [ ] Reports (4 pages)
|
||||||
|
|||||||
@ -4,16 +4,362 @@
|
|||||||
<h1>Auto-Import Configuration</h1>
|
<h1>Auto-Import Configuration</h1>
|
||||||
|
|
||||||
<p class="lead">
|
<p class="lead">
|
||||||
Configure automatic mail import.
|
Configure automatic email import from your Microsoft Graph mailbox to run on a schedule.
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
|
<h2>Overview</h2>
|
||||||
|
|
||||||
|
<p>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.</p>
|
||||||
|
|
||||||
|
<p>Auto-import features:</p>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
<li><strong>Scheduled imports:</strong> Automatically fetch new emails at configured intervals</li>
|
||||||
|
<li><strong>Auto-approval:</strong> Emails matching existing jobs are automatically approved</li>
|
||||||
|
<li><strong>Background processing:</strong> Runs in a background thread without blocking the application</li>
|
||||||
|
<li><strong>Error handling:</strong> Logs failures and retries on the next interval</li>
|
||||||
|
<li><strong>Manual override:</strong> Trigger imports manually when needed</li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
<h2>Automatic Import</h2>
|
||||||
|
|
||||||
|
<p>Automatic import runs continuously in the background and fetches new emails based on a configured interval.</p>
|
||||||
|
|
||||||
|
<h3>Enabling Auto-Import</h3>
|
||||||
|
|
||||||
|
<p>To enable automatic import:</p>
|
||||||
|
|
||||||
|
<ol>
|
||||||
|
<li>Navigate to <strong>Settings</strong> → <strong>Imports</strong> tab</li>
|
||||||
|
<li>Locate the <strong>Automatic mail import</strong> section</li>
|
||||||
|
<li>Check the <strong>Enable automatic import</strong> checkbox</li>
|
||||||
|
<li>Set the <strong>Import interval</strong> in minutes (default: 15 minutes)</li>
|
||||||
|
<li>Click <strong>Save settings</strong> at the bottom of the page</li>
|
||||||
|
</ol>
|
||||||
|
|
||||||
<div class="doc-callout doc-callout-info">
|
<div class="doc-callout doc-callout-info">
|
||||||
<strong>📝 Coming Soon:</strong>
|
<strong>💡 First Run:</strong><br>
|
||||||
This page is under construction. Full content will be added in a future update.
|
After enabling auto-import, the first import runs immediately. Subsequent imports run at the configured interval.
|
||||||
</div>
|
</div>
|
||||||
|
|
||||||
<h2>Content</h2>
|
<h3>Import Interval</h3>
|
||||||
|
|
||||||
<p>Detailed content will be added here in a future update.</p>
|
<p>The import interval determines how often BackupChecks checks for new emails:</p>
|
||||||
|
|
||||||
|
<table>
|
||||||
|
<thead>
|
||||||
|
<tr>
|
||||||
|
<th>Interval</th>
|
||||||
|
<th>Use Case</th>
|
||||||
|
<th>Recommendation</th>
|
||||||
|
</tr>
|
||||||
|
</thead>
|
||||||
|
<tbody>
|
||||||
|
<tr>
|
||||||
|
<td>5 minutes</td>
|
||||||
|
<td>High-frequency backups, real-time monitoring</td>
|
||||||
|
<td>May increase server load, use only if necessary</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>15 minutes</td>
|
||||||
|
<td>Standard setup (default)</td>
|
||||||
|
<td><strong>Recommended</strong> for most organizations</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>30 minutes</td>
|
||||||
|
<td>Low-priority backups, small teams</td>
|
||||||
|
<td>Good balance between timeliness and load</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>60 minutes</td>
|
||||||
|
<td>Batch processing, overnight backups only</td>
|
||||||
|
<td>Suitable for organizations with scheduled backup windows</td>
|
||||||
|
</tr>
|
||||||
|
</tbody>
|
||||||
|
</table>
|
||||||
|
|
||||||
|
<div class="doc-callout doc-callout-tip">
|
||||||
|
<strong>💡 Performance Consideration:</strong><br>
|
||||||
|
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.
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<h3>Batch Size</h3>
|
||||||
|
|
||||||
|
<p>Auto-import fetches a fixed number of emails per run to prevent overwhelming the system:</p>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
<li><strong>Automatic import:</strong> Always fetches <strong>10 messages</strong> per run</li>
|
||||||
|
<li>If more than 10 new emails exist, they will be fetched on subsequent runs</li>
|
||||||
|
<li>This prevents long-running imports that could block other operations</li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
<h3>How Auto-Import Works</h3>
|
||||||
|
|
||||||
|
<p>Here's what happens during each automatic import cycle:</p>
|
||||||
|
|
||||||
|
<ol>
|
||||||
|
<li><strong>Timer triggers:</strong> The configured interval elapses (e.g., 15 minutes)</li>
|
||||||
|
<li><strong>Check settings:</strong> Verify that auto-import is still enabled</li>
|
||||||
|
<li><strong>Authenticate:</strong> Obtain access token from Microsoft Graph</li>
|
||||||
|
<li><strong>Fetch emails:</strong> Retrieve up to 10 new emails from the incoming folder</li>
|
||||||
|
<li><strong>Parse emails:</strong> Run parsers to extract backup information</li>
|
||||||
|
<li><strong>Auto-approve:</strong> If the email matches an existing approved job, automatically approve it</li>
|
||||||
|
<li><strong>Move emails:</strong> Move processed emails to the processed folder (if configured)</li>
|
||||||
|
<li><strong>Log results:</strong> Record import statistics in the audit log</li>
|
||||||
|
<li><strong>Persist objects:</strong> Store backup objects for auto-approved runs</li>
|
||||||
|
<li><strong>Wait:</strong> Sleep until the next interval</li>
|
||||||
|
</ol>
|
||||||
|
|
||||||
|
<h3>Auto-Approval</h3>
|
||||||
|
|
||||||
|
<p>During automatic import, BackupChecks can automatically approve emails that match previously approved jobs. This eliminates the need to manually approve recurring backup reports.</p>
|
||||||
|
|
||||||
|
<h4>How Auto-Approval Works</h4>
|
||||||
|
|
||||||
|
<p>An email is automatically approved if:</p>
|
||||||
|
|
||||||
|
<ol>
|
||||||
|
<li>The email is <strong>successfully parsed</strong> (backup software, type, and job name extracted)</li>
|
||||||
|
<li>A <strong>matching job</strong> already exists in the database (based on sender, job name, backup software)</li>
|
||||||
|
<li>The job was <strong>previously approved</strong> by a user</li>
|
||||||
|
<li>The match is <strong>unique</strong> across all customers (no ambiguity)</li>
|
||||||
|
</ol>
|
||||||
|
|
||||||
|
<p>When auto-approved:</p>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
<li>A new <code>JobRun</code> is created and linked to the existing job</li>
|
||||||
|
<li>Backup objects are extracted and stored</li>
|
||||||
|
<li>The email is marked as approved and moved out of the inbox</li>
|
||||||
|
<li>The run appears in Daily Jobs, Run Checks, and job history</li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
<div class="doc-callout doc-callout-info">
|
||||||
|
<strong>💡 First Approval is Manual:</strong><br>
|
||||||
|
The <strong>first email</strong> for a new backup job must always be manually approved from the inbox. After that, future emails for the same job are automatically approved.
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<h4>When Auto-Approval Fails</h4>
|
||||||
|
|
||||||
|
<p>If auto-approval fails, the email remains in the inbox and requires manual approval:</p>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
<li><strong>Parsing failed:</strong> Email format not recognized by any parser</li>
|
||||||
|
<li><strong>No matching job:</strong> This is the first email for this backup job</li>
|
||||||
|
<li><strong>Ambiguous match:</strong> Multiple jobs match the same criteria (different customers with identical job names)</li>
|
||||||
|
<li><strong>Job renamed:</strong> The backup software renamed the job, breaking the match</li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
<h2>Manual Import</h2>
|
||||||
|
|
||||||
|
<p>You can manually trigger an import at any time without waiting for the automatic import interval.</p>
|
||||||
|
|
||||||
|
<h3>Triggering Manual Import</h3>
|
||||||
|
|
||||||
|
<ol>
|
||||||
|
<li>Navigate to <strong>Settings</strong> → <strong>Imports</strong> tab</li>
|
||||||
|
<li>Scroll to the <strong>Manual mail import</strong> section</li>
|
||||||
|
<li>Optionally adjust the <strong>Number of items</strong> (default: 50)</li>
|
||||||
|
<li>Click the <strong>Import now</strong> button</li>
|
||||||
|
<li>BackupChecks will immediately fetch emails from the mailbox</li>
|
||||||
|
<li>You'll see a success message showing how many emails were imported</li>
|
||||||
|
</ol>
|
||||||
|
|
||||||
|
<h3>Manual Import Batch Size</h3>
|
||||||
|
|
||||||
|
<p>Manual import allows you to configure how many emails to fetch:</p>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
<li><strong>Default:</strong> 50 emails per manual import</li>
|
||||||
|
<li><strong>Range:</strong> 1 to 50 emails</li>
|
||||||
|
<li><strong>Use case:</strong> Fetch a large batch when setting up a new customer or after a long period without imports</li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
<p>The default batch size can be changed in <strong>Settings</strong> → <strong>Imports</strong> → <strong>Manual import batch size</strong>.</p>
|
||||||
|
|
||||||
|
<div class="doc-callout doc-callout-tip">
|
||||||
|
<strong>💡 When to Use Manual Import:</strong><br>
|
||||||
|
Manual import is useful when:
|
||||||
|
<ul>
|
||||||
|
<li>Testing mail configuration for the first time</li>
|
||||||
|
<li>Setting up a new customer and you need their emails imported immediately</li>
|
||||||
|
<li>Auto-import is disabled but you need to import specific emails</li>
|
||||||
|
<li>You want to fetch a larger batch than the automatic 10-message limit</li>
|
||||||
|
</ul>
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<h2>Import Settings Summary</h2>
|
||||||
|
|
||||||
|
<p>Here's a complete reference of all mail import settings:</p>
|
||||||
|
|
||||||
|
<table>
|
||||||
|
<thead>
|
||||||
|
<tr>
|
||||||
|
<th>Setting</th>
|
||||||
|
<th>Location</th>
|
||||||
|
<th>Default</th>
|
||||||
|
<th>Description</th>
|
||||||
|
</tr>
|
||||||
|
</thead>
|
||||||
|
<tbody>
|
||||||
|
<tr>
|
||||||
|
<td><strong>Enable automatic import</strong></td>
|
||||||
|
<td>Settings → Imports</td>
|
||||||
|
<td>Disabled</td>
|
||||||
|
<td>Turn automatic email import on or off</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td><strong>Import interval</strong></td>
|
||||||
|
<td>Settings → Imports</td>
|
||||||
|
<td>15 minutes</td>
|
||||||
|
<td>How often to check for new emails (automatic import only)</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td><strong>Manual import batch size</strong></td>
|
||||||
|
<td>Settings → Imports</td>
|
||||||
|
<td>50 messages</td>
|
||||||
|
<td>Default number of emails to fetch during manual import</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td><strong>EML retention period</strong></td>
|
||||||
|
<td>Settings → Imports</td>
|
||||||
|
<td>7 days</td>
|
||||||
|
<td>How long to store raw .eml files (0, 7, or 14 days)</td>
|
||||||
|
</tr>
|
||||||
|
</tbody>
|
||||||
|
</table>
|
||||||
|
|
||||||
|
<h2>Monitoring Import Activity</h2>
|
||||||
|
|
||||||
|
<p>You can monitor import activity through several interfaces:</p>
|
||||||
|
|
||||||
|
<h3>Audit Log</h3>
|
||||||
|
|
||||||
|
<p>Every import operation is logged in the audit log:</p>
|
||||||
|
|
||||||
|
<ol>
|
||||||
|
<li>Navigate to <strong>Settings</strong> → <strong>Maintenance</strong> → <strong>Admin events</strong></li>
|
||||||
|
<li>Look for events like:
|
||||||
|
<ul>
|
||||||
|
<li><code>mail_import_auto</code> - Automatic import completed</li>
|
||||||
|
<li><code>mail_import_manual</code> - Manual import completed</li>
|
||||||
|
<li><code>mail_import_auto_error</code> - Automatic import failed</li>
|
||||||
|
</ul>
|
||||||
|
</li>
|
||||||
|
<li>Event messages show statistics: <code>fetched=10, new=3, auto_approved=7, errors=0</code></li>
|
||||||
|
</ol>
|
||||||
|
|
||||||
|
<h3>Inbox Page</h3>
|
||||||
|
|
||||||
|
<p>The inbox shows all imported emails:</p>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
<li>Check the <strong>Parsed</strong> column to see when emails were imported and parsed</li>
|
||||||
|
<li>Emails with blank <strong>Backup</strong> or <strong>Job name</strong> were not successfully parsed</li>
|
||||||
|
<li>Approved emails move out of the inbox automatically</li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
<h3>Jobs and Daily Jobs</h3>
|
||||||
|
|
||||||
|
<p>Auto-approved emails appear as new runs in:</p>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
<li><strong>Jobs</strong> page - Shows all backup jobs with their latest run status</li>
|
||||||
|
<li><strong>Daily Jobs</strong> page - Shows backup runs for today, grouped by customer</li>
|
||||||
|
<li><strong>Run Checks</strong> page - Shows all runs awaiting review</li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
<h2>Troubleshooting</h2>
|
||||||
|
|
||||||
|
<h3>Auto-Import Not Running</h3>
|
||||||
|
|
||||||
|
<p>If auto-import is enabled but emails are not being imported:</p>
|
||||||
|
|
||||||
|
<ol>
|
||||||
|
<li>Verify that <strong>Enable automatic import</strong> is checked in Settings → Imports</li>
|
||||||
|
<li>Check the audit log for <code>mail_import_auto_error</code> events</li>
|
||||||
|
<li>Verify Microsoft Graph credentials are still valid (client secret may have expired)</li>
|
||||||
|
<li>Ensure the BackupChecks application server is running (the background thread starts on app startup)</li>
|
||||||
|
<li>Check system logs for thread errors or crashes</li>
|
||||||
|
</ol>
|
||||||
|
|
||||||
|
<h3>Emails Not Auto-Approved</h3>
|
||||||
|
|
||||||
|
<p>If emails are imported but not auto-approved:</p>
|
||||||
|
|
||||||
|
<ol>
|
||||||
|
<li>Check the <strong>Inbox</strong> - emails may be parsed but not matched to existing jobs</li>
|
||||||
|
<li>Verify the <strong>first email</strong> for this job was manually approved (auto-approval only works for subsequent emails)</li>
|
||||||
|
<li>Ensure the job name, backup software, and sender match exactly between emails</li>
|
||||||
|
<li>Check for duplicate jobs across different customers (auto-approval requires a unique match)</li>
|
||||||
|
</ol>
|
||||||
|
|
||||||
|
<h3>Import Errors</h3>
|
||||||
|
|
||||||
|
<p>If imports fail with errors:</p>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
<li><strong>Authentication error:</strong> Verify Microsoft Graph credentials (tenant ID, client ID, client secret)</li>
|
||||||
|
<li><strong>Folder not found:</strong> Check that incoming/processed folder paths are correct</li>
|
||||||
|
<li><strong>Timeout error:</strong> Network issues or Microsoft Graph API unavailability - will retry on next interval</li>
|
||||||
|
<li><strong>Disk space error:</strong> Free disk space below 2 GB - mail import is blocked until space is freed</li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
<h2>Best Practices</h2>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
<li><strong>Enable auto-import:</strong> Use automatic import for hands-off email processing</li>
|
||||||
|
<li><strong>Use 15-minute interval:</strong> Recommended for most setups (balances timeliness and load)</li>
|
||||||
|
<li><strong>Monitor audit logs:</strong> Regularly check for import errors</li>
|
||||||
|
<li><strong>Approve first emails manually:</strong> Always manually approve the first email for a new job to enable auto-approval</li>
|
||||||
|
<li><strong>Keep credentials fresh:</strong> Set calendar reminders to renew Microsoft Graph client secrets before expiration</li>
|
||||||
|
<li><strong>Test manual import first:</strong> Before enabling auto-import, test manual import to verify configuration</li>
|
||||||
|
<li><strong>Use dedicated mailbox:</strong> Don't mix backup reports with personal email</li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
<h2>Advanced Configuration</h2>
|
||||||
|
|
||||||
|
<h3>Disabling Auto-Import Temporarily</h3>
|
||||||
|
|
||||||
|
<p>To temporarily stop automatic imports without losing configuration:</p>
|
||||||
|
|
||||||
|
<ol>
|
||||||
|
<li>Navigate to <strong>Settings</strong> → <strong>Imports</strong></li>
|
||||||
|
<li>Uncheck <strong>Enable automatic import</strong></li>
|
||||||
|
<li>Click <strong>Save settings</strong></li>
|
||||||
|
<li>The background thread will stop fetching emails but settings are preserved</li>
|
||||||
|
<li>Re-enable later by checking the box again</li>
|
||||||
|
</ol>
|
||||||
|
|
||||||
|
<h3>EML Storage Retention</h3>
|
||||||
|
|
||||||
|
<p>Control how long raw .eml files are stored in the database:</p>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
<li><strong>0 days:</strong> Don't store .eml files (saves database space, but troubleshooting is harder)</li>
|
||||||
|
<li><strong>7 days:</strong> Default - good balance between troubleshooting capability and storage</li>
|
||||||
|
<li><strong>14 days:</strong> Extended retention for environments with complex parsing issues</li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
<p>Older .eml files are automatically purged based on this retention period.</p>
|
||||||
|
|
||||||
|
<h3>High-Volume Environments</h3>
|
||||||
|
|
||||||
|
<p>For organizations with hundreds of backup jobs:</p>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
<li>Consider <strong>5-minute intervals</strong> to process emails more quickly</li>
|
||||||
|
<li>Ensure server resources (CPU, RAM, disk) are sufficient for frequent imports</li>
|
||||||
|
<li>Monitor database size growth - consider reducing EML retention to 0 days</li>
|
||||||
|
<li>Use multiple BackupChecks instances with separate mailboxes to distribute load</li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
<h2>Next Steps</h2>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
<li><a href="{{ url_for('documentation.page', section='mail-import', page='setup') }}">Mail Import Setup</a> - Configure Microsoft Graph API integration</li>
|
||||||
|
<li><a href="{{ url_for('documentation.page', section='mail-import', page='inbox-management') }}">Inbox Management</a> - Review and approve imported emails</li>
|
||||||
|
<li><a href="{{ url_for('documentation.page', section='backup-review', page='daily-jobs') }}">Daily Jobs View</a> - Monitor auto-approved backup runs</li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
{% endblock %}
|
{% endblock %}
|
||||||
|
|||||||
@ -4,16 +4,354 @@
|
|||||||
<h1>Inbox Management</h1>
|
<h1>Inbox Management</h1>
|
||||||
|
|
||||||
<p class="lead">
|
<p class="lead">
|
||||||
Manage incoming backup report emails.
|
Review incoming backup report emails, examine parsed results, and approve jobs for monitoring.
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
|
<h2>Overview</h2>
|
||||||
|
|
||||||
|
<p>The <strong>Inbox</strong> 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.</p>
|
||||||
|
|
||||||
|
<p>The inbox workflow:</p>
|
||||||
|
|
||||||
|
<ol>
|
||||||
|
<li><strong>Import:</strong> Emails are automatically imported from your mailbox</li>
|
||||||
|
<li><strong>Parse:</strong> BackupChecks automatically parses email content to extract backup information</li>
|
||||||
|
<li><strong>Review:</strong> You review the parsed results in the inbox</li>
|
||||||
|
<li><strong>Approve:</strong> You approve emails to create backup jobs and link future reports</li>
|
||||||
|
<li><strong>Monitor:</strong> Approved jobs appear in Daily Jobs and other operational views</li>
|
||||||
|
</ol>
|
||||||
|
|
||||||
|
<h2>Accessing the Inbox</h2>
|
||||||
|
|
||||||
|
<p>To access the inbox:</p>
|
||||||
|
|
||||||
|
<ol>
|
||||||
|
<li>Navigate to <strong>Inbox</strong> in the main navigation menu</li>
|
||||||
|
<li>Available to <strong>Admin</strong>, <strong>Operator</strong>, and <strong>Viewer</strong> roles</li>
|
||||||
|
<li>Viewers can see emails but cannot approve or delete them</li>
|
||||||
|
</ol>
|
||||||
|
|
||||||
|
<h2>Inbox Page Layout</h2>
|
||||||
|
|
||||||
|
<p>The Inbox page displays a table with all imported emails. Each row represents one email message.</p>
|
||||||
|
|
||||||
|
<h3>Table Columns</h3>
|
||||||
|
|
||||||
|
<table>
|
||||||
|
<thead>
|
||||||
|
<tr>
|
||||||
|
<th>Column</th>
|
||||||
|
<th>Description</th>
|
||||||
|
</tr>
|
||||||
|
</thead>
|
||||||
|
<tbody>
|
||||||
|
<tr>
|
||||||
|
<td><strong>From</strong></td>
|
||||||
|
<td>Sender email address (e.g., <code>backups@veeam.com</code>)</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td><strong>Subject</strong></td>
|
||||||
|
<td>Email subject line</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td><strong>Date / time</strong></td>
|
||||||
|
<td>When the email was received (in configured timezone)</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td><strong>Backup</strong></td>
|
||||||
|
<td>Detected backup software (e.g., Veeam, Synology, NAKIVO)</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td><strong>Type</strong></td>
|
||||||
|
<td>Backup job type (e.g., Backup Job, Replication Job)</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td><strong>Job name</strong></td>
|
||||||
|
<td>Extracted backup job name from email content</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td><strong>Overall</strong></td>
|
||||||
|
<td>Overall status extracted from email (Success, Warning, Failed)</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td><strong>Parsed</strong></td>
|
||||||
|
<td>Timestamp when the email was parsed</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td><strong>EML</strong></td>
|
||||||
|
<td>Checkmark (✓) if raw .eml file is stored</td>
|
||||||
|
</tr>
|
||||||
|
</tbody>
|
||||||
|
</table>
|
||||||
|
|
||||||
|
<h3>Pagination</h3>
|
||||||
|
|
||||||
|
<p>The inbox displays 50 emails per page. Use the pagination controls at the top and bottom of the table:</p>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
<li><strong>Previous / Next buttons:</strong> Navigate between pages</li>
|
||||||
|
<li><strong>Page X of Y:</strong> Shows current page and total pages</li>
|
||||||
|
<li><strong>Go to:</strong> Jump directly to a specific page number</li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
<h2>Viewing Email Details</h2>
|
||||||
|
|
||||||
|
<p>To view the full content and parsed details of an email:</p>
|
||||||
|
|
||||||
|
<ol>
|
||||||
|
<li>Click anywhere on the email row in the inbox table</li>
|
||||||
|
<li>A large modal dialog opens showing the email details</li>
|
||||||
|
</ol>
|
||||||
|
|
||||||
|
<h3>Email Detail Modal</h3>
|
||||||
|
|
||||||
|
<p>The email detail modal contains three main sections:</p>
|
||||||
|
|
||||||
|
<h4>1. Metadata Section (Top)</h4>
|
||||||
|
|
||||||
|
<p>Displays email header information:</p>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
<li><strong>From:</strong> Sender address</li>
|
||||||
|
<li><strong>Subject:</strong> Email subject</li>
|
||||||
|
<li><strong>Received:</strong> Timestamp</li>
|
||||||
|
<li><strong>Backup software / Type / Job name:</strong> Parsed values</li>
|
||||||
|
<li><strong>Overall status:</strong> Success/Warning/Failed indicator</li>
|
||||||
|
<li><strong>Customer:</strong> If already approved and linked to a customer</li>
|
||||||
|
<li><strong>Approved:</strong> Checkmark if this email has been approved</li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
<h4>2. Email Body (Middle)</h4>
|
||||||
|
|
||||||
|
<p>The email body is displayed in an embedded iframe:</p>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
<li>HTML emails are rendered in their original formatting</li>
|
||||||
|
<li>Plain text emails are displayed as preformatted text</li>
|
||||||
|
<li>Styling and images are preserved when possible</li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
<div class="doc-callout doc-callout-info">
|
<div class="doc-callout doc-callout-info">
|
||||||
<strong>📝 Coming Soon:</strong>
|
<strong>💡 HTML Rendering:</strong><br>
|
||||||
This page is under construction. Full content will be added in a future update.
|
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.
|
||||||
</div>
|
</div>
|
||||||
|
|
||||||
<h2>Content</h2>
|
<h4>3. Parsed Objects (Bottom)</h4>
|
||||||
|
|
||||||
<p>Detailed content will be added here in a future update.</p>
|
<p>If the email was successfully parsed, this section shows the <strong>backup objects</strong> extracted from the email:</p>
|
||||||
|
|
||||||
|
<table>
|
||||||
|
<thead>
|
||||||
|
<tr>
|
||||||
|
<th>Column</th>
|
||||||
|
<th>Description</th>
|
||||||
|
</tr>
|
||||||
|
</thead>
|
||||||
|
<tbody>
|
||||||
|
<tr>
|
||||||
|
<td><strong>Name</strong></td>
|
||||||
|
<td>Object name (VM name, server name, etc.)</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td><strong>Object type</strong></td>
|
||||||
|
<td>Type of object (e.g., VM, Server, Repository)</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td><strong>Status</strong></td>
|
||||||
|
<td>Status of this object (Success, Warning, Failed)</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td><strong>Message</strong></td>
|
||||||
|
<td>Any error or warning message for this object</td>
|
||||||
|
</tr>
|
||||||
|
</tbody>
|
||||||
|
</table>
|
||||||
|
|
||||||
|
<p>For example, a Veeam backup job email might show:</p>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
<li>Object: <code>DC01</code>, Type: VM, Status: Success</li>
|
||||||
|
<li>Object: <code>FILESERVER</code>, Type: VM, Status: Success</li>
|
||||||
|
<li>Object: <code>EXCHANGE01</code>, Type: VM, Status: Warning, Message: "Retry attempt succeeded"</li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
<h2>Approving Emails</h2>
|
||||||
|
|
||||||
|
<p>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.</p>
|
||||||
|
|
||||||
|
<h3>How to Approve</h3>
|
||||||
|
|
||||||
|
<ol>
|
||||||
|
<li>Open the email detail modal by clicking on an inbox row</li>
|
||||||
|
<li>Review the email content and parsed objects</li>
|
||||||
|
<li>Click the <strong>Approve</strong> button at the top of the modal</li>
|
||||||
|
<li>An approval dialog opens with two fields:
|
||||||
|
<ul>
|
||||||
|
<li><strong>Select customer:</strong> Choose which customer this backup job belongs to</li>
|
||||||
|
<li><strong>Job name:</strong> Pre-filled with the parsed job name (you can edit if needed)</li>
|
||||||
|
</ul>
|
||||||
|
</li>
|
||||||
|
<li>Select the <strong>customer</strong> from the dropdown (or start typing to search)</li>
|
||||||
|
<li>Verify or adjust the <strong>job name</strong></li>
|
||||||
|
<li>Click <strong>Confirm</strong> to approve</li>
|
||||||
|
</ol>
|
||||||
|
|
||||||
|
<div class="doc-callout doc-callout-tip">
|
||||||
|
<strong>💡 Customer Selection:</strong><br>
|
||||||
|
Always create the customer account <strong>before</strong> approving emails. This allows you to immediately link the job to the correct customer. See <a href="{{ url_for('documentation.page', section='customers-jobs', page='managing-customers') }}">Managing Customers</a> for details.
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<h3>What Happens After Approval</h3>
|
||||||
|
|
||||||
|
<p>When you approve an email:</p>
|
||||||
|
|
||||||
|
<ol>
|
||||||
|
<li>A <strong>Job</strong> record is created in the database (if it doesn't already exist)</li>
|
||||||
|
<li>A <strong>JobRun</strong> record is created, representing this specific backup run</li>
|
||||||
|
<li><strong>JobObject</strong> records are created for each parsed object (VMs, servers, etc.)</li>
|
||||||
|
<li>The email is marked as <strong>approved</strong> and moved out of the inbox</li>
|
||||||
|
<li>The job immediately appears in <strong>Jobs</strong>, <strong>Daily Jobs</strong>, and <strong>Run Checks</strong> pages</li>
|
||||||
|
<li>Future emails matching the same job are <strong>automatically linked</strong> without manual approval</li>
|
||||||
|
</ol>
|
||||||
|
|
||||||
|
<div class="doc-callout doc-callout-warning">
|
||||||
|
<strong>⚠️ Job Matching:</strong><br>
|
||||||
|
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.
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<h2>Re-parsing Emails</h2>
|
||||||
|
|
||||||
|
<p>If an email was not parsed correctly, you can re-parse it after updating parser configuration.</p>
|
||||||
|
|
||||||
|
<h3>Re-parse Single Email</h3>
|
||||||
|
|
||||||
|
<p>To re-parse a single email:</p>
|
||||||
|
|
||||||
|
<ol>
|
||||||
|
<li>Open the email detail modal</li>
|
||||||
|
<li>Click the <strong>Re-parse</strong> button</li>
|
||||||
|
<li>BackupChecks will re-run all parsers on this email</li>
|
||||||
|
<li>The modal will refresh with updated parsed results</li>
|
||||||
|
</ol>
|
||||||
|
|
||||||
|
<h3>Re-parse All Emails</h3>
|
||||||
|
|
||||||
|
<p>To re-parse all emails in the inbox at once:</p>
|
||||||
|
|
||||||
|
<ol>
|
||||||
|
<li>At the top of the inbox page, click the <strong>Re-parse all</strong> button</li>
|
||||||
|
<li>This re-runs parsers on <strong>all inbox emails</strong></li>
|
||||||
|
<li>Useful after adding new parsers or fixing parser bugs</li>
|
||||||
|
</ol>
|
||||||
|
|
||||||
|
<div class="doc-callout doc-callout-info">
|
||||||
|
<strong>💡 When to Re-parse:</strong><br>
|
||||||
|
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.
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<h2>Deleting Emails</h2>
|
||||||
|
|
||||||
|
<p>Admins and Operators can delete emails from the inbox.</p>
|
||||||
|
|
||||||
|
<h3>Delete Single Email</h3>
|
||||||
|
|
||||||
|
<ol>
|
||||||
|
<li>Open the email detail modal</li>
|
||||||
|
<li>Click the <strong>Delete</strong> button</li>
|
||||||
|
<li>Confirm the deletion</li>
|
||||||
|
<li>The email is marked as deleted and moved out of the inbox</li>
|
||||||
|
</ol>
|
||||||
|
|
||||||
|
<h3>Bulk Delete Emails</h3>
|
||||||
|
|
||||||
|
<ol>
|
||||||
|
<li>Check the checkboxes next to emails you want to delete</li>
|
||||||
|
<li>Click the <strong>Delete selected</strong> button at the top of the inbox</li>
|
||||||
|
<li>Confirm the bulk deletion</li>
|
||||||
|
</ol>
|
||||||
|
|
||||||
|
<div class="doc-callout doc-callout-warning">
|
||||||
|
<strong>⚠️ Soft Delete:</strong><br>
|
||||||
|
Emails are <strong>soft-deleted</strong>, not permanently removed. Deleted emails are hidden from the inbox but remain in the database. Admins can view deleted emails in <strong>Settings</strong> → <strong>Maintenance</strong> → <strong>Deleted mails</strong>.
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<h2>Downloading .EML Files</h2>
|
||||||
|
|
||||||
|
<p>If EML storage is enabled, you can download the original .eml file for any email:</p>
|
||||||
|
|
||||||
|
<ol>
|
||||||
|
<li>Open the email detail modal</li>
|
||||||
|
<li>Click the <strong>Download .eml</strong> button</li>
|
||||||
|
<li>The raw .eml file is downloaded to your browser</li>
|
||||||
|
<li>You can open this file in Outlook, Thunderbird, or any email client</li>
|
||||||
|
</ol>
|
||||||
|
|
||||||
|
<p>This is useful for:</p>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
<li>Troubleshooting parsing issues</li>
|
||||||
|
<li>Forwarding the email to a vendor for support</li>
|
||||||
|
<li>Archiving backup reports outside BackupChecks</li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
<h2>Inbox Filters and Search</h2>
|
||||||
|
|
||||||
|
<p>The inbox currently displays all imported emails in chronological order (newest first). Filtering and search features are planned for a future update.</p>
|
||||||
|
|
||||||
|
<div class="doc-callout doc-callout-info">
|
||||||
|
<strong>📝 Future Feature:</strong><br>
|
||||||
|
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.
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<h2>Common Workflows</h2>
|
||||||
|
|
||||||
|
<h3>Setting Up a New Customer</h3>
|
||||||
|
|
||||||
|
<ol>
|
||||||
|
<li>Create the customer in <strong>Customers</strong> page</li>
|
||||||
|
<li>Wait for backup reports to arrive in the inbox (or trigger a manual import)</li>
|
||||||
|
<li>Review each email for the customer in the inbox</li>
|
||||||
|
<li>Approve each email, selecting the new customer from the dropdown</li>
|
||||||
|
<li>Jobs are now created and linked to the customer</li>
|
||||||
|
<li>Future reports are automatically linked without approval</li>
|
||||||
|
</ol>
|
||||||
|
|
||||||
|
<h3>Troubleshooting Unparsed Emails</h3>
|
||||||
|
|
||||||
|
<ol>
|
||||||
|
<li>Find emails with empty <strong>Backup</strong> or <strong>Job name</strong> columns</li>
|
||||||
|
<li>Open the email detail modal</li>
|
||||||
|
<li>Review the email body to understand its format</li>
|
||||||
|
<li>Check if a parser exists for this backup software in <strong>Settings</strong> → <strong>Parsers</strong></li>
|
||||||
|
<li>If no parser exists, request one or create a custom parser</li>
|
||||||
|
<li>After adding a parser, use <strong>Re-parse</strong> to process the email again</li>
|
||||||
|
</ol>
|
||||||
|
|
||||||
|
<h3>Cleaning Up Spam or Test Emails</h3>
|
||||||
|
|
||||||
|
<ol>
|
||||||
|
<li>Identify unwanted emails in the inbox (e.g., spam, test messages)</li>
|
||||||
|
<li>Select them using checkboxes</li>
|
||||||
|
<li>Click <strong>Delete selected</strong></li>
|
||||||
|
<li>Configure mail rules in your mailbox to prevent future spam</li>
|
||||||
|
</ol>
|
||||||
|
|
||||||
|
<h2>Best Practices</h2>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
<li><strong>Review new emails daily:</strong> Check the inbox regularly to approve new jobs promptly</li>
|
||||||
|
<li><strong>Create customers first:</strong> Always create customer accounts before approving their jobs</li>
|
||||||
|
<li><strong>Use descriptive job names:</strong> Edit job names during approval if the parsed name is unclear</li>
|
||||||
|
<li><strong>Clean up the inbox:</strong> Delete or approve emails to keep the inbox manageable</li>
|
||||||
|
<li><strong>Monitor parsing success:</strong> Check for emails with missing backup software - these may need parser configuration</li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
<h2>Next Steps</h2>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
<li><a href="{{ url_for('documentation.page', section='mail-import', page='mail-parsing') }}">Mail Parsing</a> - Understand how BackupChecks parses different backup software emails</li>
|
||||||
|
<li><a href="{{ url_for('documentation.page', section='customers-jobs', page='configuring-jobs') }}">Configuring Jobs</a> - Learn about job approval and configuration</li>
|
||||||
|
<li><a href="{{ url_for('documentation.page', section='backup-review', page='daily-jobs') }}">Daily Jobs View</a> - Monitor approved jobs daily</li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
{% endblock %}
|
{% endblock %}
|
||||||
|
|||||||
@ -4,16 +4,370 @@
|
|||||||
<h1>Mail Parsing</h1>
|
<h1>Mail Parsing</h1>
|
||||||
|
|
||||||
<p class="lead">
|
<p class="lead">
|
||||||
Learn how email parsing works.
|
Understand how BackupChecks automatically extracts backup information from email reports using parsers.
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
|
<h2>Overview</h2>
|
||||||
|
|
||||||
|
<p>When emails are imported from your mailbox, BackupChecks automatically <strong>parses</strong> (analyzes) the email content to extract structured backup information. This eliminates the need to manually read each email and enter data.</p>
|
||||||
|
|
||||||
|
<p>Parsing extracts:</p>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
<li><strong>Backup software:</strong> The product that generated the email (e.g., Veeam, Synology, NAKIVO)</li>
|
||||||
|
<li><strong>Backup type:</strong> The type of backup job (e.g., Backup Job, Replication Job)</li>
|
||||||
|
<li><strong>Job name:</strong> The name of the backup job</li>
|
||||||
|
<li><strong>Overall status:</strong> Success, Warning, or Failed</li>
|
||||||
|
<li><strong>Backup objects:</strong> Individual items backed up (VMs, servers, files) with their statuses</li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
<h2>How Parsing Works</h2>
|
||||||
|
|
||||||
|
<p>The mail parsing process follows these steps:</p>
|
||||||
|
|
||||||
|
<ol>
|
||||||
|
<li><strong>Retrieval:</strong> Email is imported from Microsoft Graph and stored as a <code>MailMessage</code> record</li>
|
||||||
|
<li><strong>Preprocessing:</strong> Email body is normalized (line endings, character encoding) for consistent parsing</li>
|
||||||
|
<li><strong>Parser selection:</strong> All active parsers are evaluated in order to find a match</li>
|
||||||
|
<li><strong>Matching:</strong> Each parser checks if the email matches its criteria (sender, subject, body patterns)</li>
|
||||||
|
<li><strong>Parsing:</strong> When a match is found, the parser extracts backup information from the email</li>
|
||||||
|
<li><strong>Storage:</strong> Parsed data is stored in the database and linked to the email</li>
|
||||||
|
</ol>
|
||||||
|
|
||||||
|
<h2>Parsers</h2>
|
||||||
|
|
||||||
|
<p>A <strong>parser</strong> is a piece of code that knows how to extract backup information from a specific backup software's email format.</p>
|
||||||
|
|
||||||
|
<h3>Viewing Available Parsers</h3>
|
||||||
|
|
||||||
|
<p>To see all available parsers:</p>
|
||||||
|
|
||||||
|
<ol>
|
||||||
|
<li>Navigate to <strong>Settings</strong> → <strong>Parsers</strong> (Admin only)</li>
|
||||||
|
<li>The parsers page shows a table with all parsers and their configuration</li>
|
||||||
|
</ol>
|
||||||
|
|
||||||
|
<h3>Parser Information</h3>
|
||||||
|
|
||||||
|
<p>Each parser entry shows:</p>
|
||||||
|
|
||||||
|
<table>
|
||||||
|
<thead>
|
||||||
|
<tr>
|
||||||
|
<th>Column</th>
|
||||||
|
<th>Description</th>
|
||||||
|
</tr>
|
||||||
|
</thead>
|
||||||
|
<tbody>
|
||||||
|
<tr>
|
||||||
|
<td><strong>Name</strong></td>
|
||||||
|
<td>Unique identifier for the parser (e.g., <code>veeam_backup_job</code>)</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td><strong>Backup software</strong></td>
|
||||||
|
<td>The product this parser handles (e.g., Veeam, NAKIVO)</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td><strong>Backup type(s)</strong></td>
|
||||||
|
<td>Types of jobs this parser supports (e.g., Backup Job, Replication Job)</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td><strong>Match criteria</strong></td>
|
||||||
|
<td>Rules used to identify matching emails (sender, subject, body patterns)</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td><strong>Order</strong></td>
|
||||||
|
<td>Evaluation order (lower numbers are checked first)</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td><strong>Enabled</strong></td>
|
||||||
|
<td>Checkbox to enable/disable this parser</td>
|
||||||
|
</tr>
|
||||||
|
</tbody>
|
||||||
|
</table>
|
||||||
|
|
||||||
|
<h2>Match Criteria</h2>
|
||||||
|
|
||||||
|
<p>Parsers use <strong>match criteria</strong> to determine if an email matches their expected format. Common criteria include:</p>
|
||||||
|
|
||||||
|
<h3>Sender Match</h3>
|
||||||
|
|
||||||
|
<p>Match based on the sender's email address:</p>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
<li><strong>from contains:</strong> Sender address must contain a specific string
|
||||||
|
<ul>
|
||||||
|
<li>Example: <code>from contains 'veeam.com'</code> matches <code>backups@veeam.com</code></li>
|
||||||
|
</ul>
|
||||||
|
</li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
<h3>Subject Match</h3>
|
||||||
|
|
||||||
|
<p>Match based on the email subject line:</p>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
<li><strong>subject contains:</strong> Subject must contain specific text
|
||||||
|
<ul>
|
||||||
|
<li>Example: <code>subject contains '[Backup]'</code></li>
|
||||||
|
</ul>
|
||||||
|
</li>
|
||||||
|
<li><strong>subject matches:</strong> Subject must match a regular expression pattern
|
||||||
|
<ul>
|
||||||
|
<li>Example: <code>subject matches /Backup.*Success/</code></li>
|
||||||
|
</ul>
|
||||||
|
</li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
<h3>Body Match</h3>
|
||||||
|
|
||||||
|
<p>Match based on email body content (not shown in table but used internally):</p>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
<li>Specific phrases or patterns in the email HTML or text body</li>
|
||||||
|
<li>Table structures, HTML tags, or formatting patterns</li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
<h2>Supported Backup Software</h2>
|
||||||
|
|
||||||
|
<p>BackupChecks includes built-in parsers for popular backup solutions:</p>
|
||||||
|
|
||||||
|
<h3>Veeam Backup & Replication</h3>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
<li>Backup jobs</li>
|
||||||
|
<li>Backup Copy jobs</li>
|
||||||
|
<li>Replication jobs</li>
|
||||||
|
<li>VM-level and object-level details</li>
|
||||||
|
<li>Warning and error messages</li>
|
||||||
|
<li>VSPC (Veeam Service Provider Console) active alarms</li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
<h3>Synology Active Backup</h3>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
<li>Task result notifications</li>
|
||||||
|
<li>PC backup, VM backup, file server backup</li>
|
||||||
|
<li>Success/failure status per device</li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
<h3>NAKIVO Backup & Replication</h3>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
<li>Job completion emails</li>
|
||||||
|
<li>VM-level status and warnings</li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
<h3>Other Supported Software</h3>
|
||||||
|
|
||||||
|
<p>Additional parsers exist for:</p>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
<li><strong>Boxafe:</strong> Cloud backup for Microsoft 365</li>
|
||||||
|
<li><strong>Panel3:</strong> Backup monitoring platform</li>
|
||||||
|
<li><strong>QNAP:</strong> NAS backup notifications</li>
|
||||||
|
<li><strong>Syncovery:</strong> File synchronization and backup</li>
|
||||||
|
<li><strong>3CX:</strong> VoIP system backup notifications</li>
|
||||||
|
<li><strong>RDrive Image:</strong> Disk imaging backups</li>
|
||||||
|
<li><strong>NTFS Auditing:</strong> File access audit reports</li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
<div class="doc-callout doc-callout-info">
|
<div class="doc-callout doc-callout-info">
|
||||||
<strong>📝 Coming Soon:</strong>
|
<strong>💡 Custom Parsers:</strong><br>
|
||||||
This page is under construction. Full content will be added in a future update.
|
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 <code>backend/app/parsers/</code>.
|
||||||
</div>
|
</div>
|
||||||
|
|
||||||
<h2>Content</h2>
|
<h2>Parser Execution Order</h2>
|
||||||
|
|
||||||
<p>Detailed content will be added here in a future update.</p>
|
<p>When an email is parsed, BackupChecks evaluates parsers in a specific order based on their <strong>Order</strong> value. This is important because:</p>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
<li>The <strong>first matching parser</strong> is used - no other parsers are evaluated after a match</li>
|
||||||
|
<li>More specific parsers should have <strong>lower order numbers</strong> (checked first)</li>
|
||||||
|
<li>Generic parsers should have <strong>higher order numbers</strong> (checked last)</li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
<p>For example:</p>
|
||||||
|
|
||||||
|
<table>
|
||||||
|
<thead>
|
||||||
|
<tr>
|
||||||
|
<th>Order</th>
|
||||||
|
<th>Parser</th>
|
||||||
|
<th>Rationale</th>
|
||||||
|
</tr>
|
||||||
|
</thead>
|
||||||
|
<tbody>
|
||||||
|
<tr>
|
||||||
|
<td>1</td>
|
||||||
|
<td>veeam_replication_job</td>
|
||||||
|
<td>Specific Veeam job type - check before generic Veeam parser</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>2</td>
|
||||||
|
<td>veeam_backup_job</td>
|
||||||
|
<td>Generic Veeam parser - fallback for other Veeam emails</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>10</td>
|
||||||
|
<td>synology_active_backup</td>
|
||||||
|
<td>Unrelated to Veeam - order doesn't matter relative to Veeam</td>
|
||||||
|
</tr>
|
||||||
|
</tbody>
|
||||||
|
</table>
|
||||||
|
|
||||||
|
<h2>Enabling and Disabling Parsers</h2>
|
||||||
|
|
||||||
|
<p>You can enable or disable individual parsers without deleting them. This is useful when:</p>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
<li>You temporarily don't need emails from a specific backup software</li>
|
||||||
|
<li>A parser is matching emails incorrectly (disable it while troubleshooting)</li>
|
||||||
|
<li>You're testing a new parser (disable the old one to force the new one to match)</li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
<h3>How to Disable a Parser</h3>
|
||||||
|
|
||||||
|
<ol>
|
||||||
|
<li>Navigate to <strong>Settings</strong> → <strong>Parsers</strong></li>
|
||||||
|
<li>Find the parser you want to disable</li>
|
||||||
|
<li>Uncheck the <strong>Enabled</strong> checkbox</li>
|
||||||
|
<li>The parser will no longer be evaluated for new emails</li>
|
||||||
|
</ol>
|
||||||
|
|
||||||
|
<div class="doc-callout doc-callout-warning">
|
||||||
|
<strong>⚠️ Impact of Disabling:</strong><br>
|
||||||
|
Disabling a parser affects <strong>future email parsing</strong> 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).
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<h2>Re-parsing Emails</h2>
|
||||||
|
|
||||||
|
<p>If parsing fails or produces incorrect results, you can re-parse emails after fixing the issue.</p>
|
||||||
|
|
||||||
|
<h3>When to Re-parse</h3>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
<li>A parser was disabled when the email was imported</li>
|
||||||
|
<li>A new parser was added for previously unsupported software</li>
|
||||||
|
<li>Parser code was updated to fix a bug</li>
|
||||||
|
<li>Match criteria were adjusted</li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
<h3>How to Re-parse</h3>
|
||||||
|
|
||||||
|
<ol>
|
||||||
|
<li><strong>Single email:</strong> Open the email detail modal in the inbox and click <strong>Re-parse</strong></li>
|
||||||
|
<li><strong>All inbox emails:</strong> Click <strong>Re-parse all</strong> at the top of the inbox page</li>
|
||||||
|
</ol>
|
||||||
|
|
||||||
|
<div class="doc-callout doc-callout-tip">
|
||||||
|
<strong>💡 Re-parsing is Safe:</strong><br>
|
||||||
|
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.
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<h2>Parsing Workflow Example</h2>
|
||||||
|
|
||||||
|
<p>Here's how a typical Veeam backup email is parsed:</p>
|
||||||
|
|
||||||
|
<h3>Example Email</h3>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
<li><strong>From:</strong> <code>backups@veeam.com</code></li>
|
||||||
|
<li><strong>Subject:</strong> <code>[Veeam] Backup Job 'Daily VM Backup' completed with Warning</code></li>
|
||||||
|
<li><strong>Body:</strong> HTML table showing:
|
||||||
|
<ul>
|
||||||
|
<li>VM: DC01 - Success</li>
|
||||||
|
<li>VM: FILESERVER - Success</li>
|
||||||
|
<li>VM: EXCHANGE01 - Warning: "Retry succeeded"</li>
|
||||||
|
</ul>
|
||||||
|
</li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
<h3>Parsing Steps</h3>
|
||||||
|
|
||||||
|
<ol>
|
||||||
|
<li><strong>Import:</strong> Email is fetched from Graph API and stored</li>
|
||||||
|
<li><strong>Match:</strong> Veeam backup job parser matches (sender contains 'veeam.com', subject contains '[Veeam]')</li>
|
||||||
|
<li><strong>Extract:</strong> Parser extracts:
|
||||||
|
<ul>
|
||||||
|
<li>Backup software: <code>Veeam</code></li>
|
||||||
|
<li>Backup type: <code>Backup Job</code></li>
|
||||||
|
<li>Job name: <code>Daily VM Backup</code></li>
|
||||||
|
<li>Overall status: <code>Warning</code> (from subject)</li>
|
||||||
|
<li>Objects: 3 VMs with their individual statuses</li>
|
||||||
|
</ul>
|
||||||
|
</li>
|
||||||
|
<li><strong>Store:</strong> Data is saved to the database</li>
|
||||||
|
<li><strong>Display:</strong> Email appears in inbox with parsed fields populated</li>
|
||||||
|
</ol>
|
||||||
|
|
||||||
|
<h2>Troubleshooting Parsing Issues</h2>
|
||||||
|
|
||||||
|
<h3>Email Not Parsed (Blank Fields)</h3>
|
||||||
|
|
||||||
|
<p>If an email shows blank <strong>Backup software</strong> or <strong>Job name</strong>:</p>
|
||||||
|
|
||||||
|
<ol>
|
||||||
|
<li>Check if a parser exists for this backup software in <strong>Settings</strong> → <strong>Parsers</strong></li>
|
||||||
|
<li>If no parser exists, you'll need to create or request one</li>
|
||||||
|
<li>If a parser exists, check that it's <strong>enabled</strong></li>
|
||||||
|
<li>Verify the email format matches the parser's expected format (sender, subject, body structure)</li>
|
||||||
|
<li>Check parser order - a different parser may be matching first</li>
|
||||||
|
</ol>
|
||||||
|
|
||||||
|
<h3>Incorrect Parsing Results</h3>
|
||||||
|
|
||||||
|
<p>If parsing produces wrong job names or objects:</p>
|
||||||
|
|
||||||
|
<ol>
|
||||||
|
<li>Verify the email format hasn't changed (backup software update may change email templates)</li>
|
||||||
|
<li>Check if the wrong parser is matching (disable it temporarily to test)</li>
|
||||||
|
<li>Review parser match criteria - may be too broad and matching unintended emails</li>
|
||||||
|
<li>Contact support or review parser code to identify the issue</li>
|
||||||
|
</ol>
|
||||||
|
|
||||||
|
<h3>Partial Parsing</h3>
|
||||||
|
|
||||||
|
<p>If some fields parse correctly but others don't:</p>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
<li>The parser may not support all fields in this email format</li>
|
||||||
|
<li>Email structure may vary slightly from what the parser expects</li>
|
||||||
|
<li>Parser may need updates to handle new email formats</li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
<h2>Parser Limitations</h2>
|
||||||
|
|
||||||
|
<p>Parsers have some inherent limitations:</p>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
<li><strong>Format dependency:</strong> Parsers rely on consistent email formats. If your backup software changes its email template, the parser may break</li>
|
||||||
|
<li><strong>Language dependency:</strong> Most parsers expect English-language emails. Non-English emails may not parse correctly</li>
|
||||||
|
<li><strong>First match only:</strong> Only the first matching parser is used. An email cannot be parsed by multiple parsers</li>
|
||||||
|
<li><strong>No AI inference:</strong> Parsers use pattern matching, not AI. They cannot interpret freeform text or adapt to unexpected formats</li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
<div class="doc-callout doc-callout-info">
|
||||||
|
<strong>💡 Future Enhancement:</strong><br>
|
||||||
|
AI-powered parsing (using LLMs to interpret backup emails) is being considered for future versions to handle more diverse email formats without custom parsers.
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<h2>Best Practices</h2>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
<li><strong>Don't customize backup email templates:</strong> Use default email formats from your backup software for best parsing results</li>
|
||||||
|
<li><strong>Test new parsers:</strong> When adding a custom parser, test it on multiple sample emails before enabling it</li>
|
||||||
|
<li><strong>Monitor unparsed emails:</strong> Regularly check for emails with blank backup software fields</li>
|
||||||
|
<li><strong>Keep parsers enabled:</strong> Only disable parsers when necessary - it's better to have too many than too few</li>
|
||||||
|
<li><strong>Re-parse after updates:</strong> If you update parser code or add new parsers, re-parse existing inbox emails</li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
<h2>Next Steps</h2>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
<li><a href="{{ url_for('documentation.page', section='mail-import', page='auto-import') }}">Auto-Import Configuration</a> - Configure automatic email import schedules</li>
|
||||||
|
<li><a href="{{ url_for('documentation.page', section='mail-import', page='inbox-management') }}">Inbox Management</a> - Review and approve parsed emails</li>
|
||||||
|
<li><a href="{{ url_for('documentation.page', section='customers-jobs', page='configuring-jobs') }}">Configuring Jobs</a> - Approve and configure backup jobs</li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
{% endblock %}
|
{% endblock %}
|
||||||
|
|||||||
@ -4,16 +4,306 @@
|
|||||||
<h1>Mail Import Setup</h1>
|
<h1>Mail Import Setup</h1>
|
||||||
|
|
||||||
<p class="lead">
|
<p class="lead">
|
||||||
Configure Microsoft Graph API integration.
|
Configure Microsoft Graph API integration to automatically retrieve backup report emails from an Exchange Online mailbox.
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
|
<h2>Overview</h2>
|
||||||
|
|
||||||
|
<p>BackupChecks uses the <strong>Microsoft Graph API</strong> to retrieve emails from an Exchange Online (Microsoft 365) mailbox. This allows the system to automatically import backup reports sent to a dedicated mailbox.</p>
|
||||||
|
|
||||||
|
<p>The mail import process involves:</p>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
<li>Authenticating with Microsoft Graph using an Azure AD app registration</li>
|
||||||
|
<li>Retrieving emails from a specified folder in the mailbox</li>
|
||||||
|
<li>Parsing email content to extract backup job information</li>
|
||||||
|
<li>Moving processed emails to a separate folder</li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
<div class="doc-callout doc-callout-info">
|
<div class="doc-callout doc-callout-info">
|
||||||
<strong>📝 Coming Soon:</strong>
|
<strong>💡 Why Microsoft Graph?</strong><br>
|
||||||
This page is under construction. Full content will be added in a future update.
|
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.
|
||||||
</div>
|
</div>
|
||||||
|
|
||||||
<h2>Content</h2>
|
<h2>Prerequisites</h2>
|
||||||
|
|
||||||
<p>Detailed content will be added here in a future update.</p>
|
<p>Before configuring mail import in BackupChecks, you need:</p>
|
||||||
|
|
||||||
|
<ol>
|
||||||
|
<li><strong>Microsoft 365 subscription</strong> with Exchange Online</li>
|
||||||
|
<li><strong>Dedicated mailbox</strong> for receiving backup reports (e.g., backupreports@yourdomain.com)</li>
|
||||||
|
<li><strong>Azure AD application registration</strong> with Mail.Read and Mail.ReadWrite permissions</li>
|
||||||
|
<li><strong>Admin access</strong> to BackupChecks to configure settings</li>
|
||||||
|
</ol>
|
||||||
|
|
||||||
|
<h2>Step 1: Create Azure AD App Registration</h2>
|
||||||
|
|
||||||
|
<p>To allow BackupChecks to access your mailbox, you must create an Azure AD app registration and grant it the necessary permissions.</p>
|
||||||
|
|
||||||
|
<h3>1.1 Register the Application</h3>
|
||||||
|
|
||||||
|
<ol>
|
||||||
|
<li>Sign in to the <a href="https://portal.azure.com" target="_blank">Azure Portal</a></li>
|
||||||
|
<li>Navigate to <strong>Azure Active Directory</strong> → <strong>App registrations</strong></li>
|
||||||
|
<li>Click <strong>New registration</strong></li>
|
||||||
|
<li>Enter a name (e.g., "BackupChecks Mail Importer")</li>
|
||||||
|
<li>Select <strong>Accounts in this organizational directory only</strong></li>
|
||||||
|
<li>Leave <strong>Redirect URI</strong> blank</li>
|
||||||
|
<li>Click <strong>Register</strong></li>
|
||||||
|
</ol>
|
||||||
|
|
||||||
|
<p>After registration, note the following values from the <strong>Overview</strong> page:</p>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
<li><strong>Application (client) ID</strong> - you'll enter this as <em>Client ID</em> in BackupChecks</li>
|
||||||
|
<li><strong>Directory (tenant) ID</strong> - you'll enter this as <em>Tenant ID</em> in BackupChecks</li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
<h3>1.2 Create a Client Secret</h3>
|
||||||
|
|
||||||
|
<ol>
|
||||||
|
<li>In your app registration, go to <strong>Certificates & secrets</strong></li>
|
||||||
|
<li>Click <strong>New client secret</strong></li>
|
||||||
|
<li>Enter a description (e.g., "BackupChecks access")</li>
|
||||||
|
<li>Select an expiration period (recommended: 24 months)</li>
|
||||||
|
<li>Click <strong>Add</strong></li>
|
||||||
|
<li><strong>Important:</strong> Copy the secret <strong>Value</strong> immediately - you cannot view it again later</li>
|
||||||
|
</ol>
|
||||||
|
|
||||||
|
<div class="doc-callout doc-callout-warning">
|
||||||
|
<strong>⚠️ Secret Expiration:</strong><br>
|
||||||
|
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.
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<h3>1.3 Grant API Permissions</h3>
|
||||||
|
|
||||||
|
<p>BackupChecks requires <strong>application permissions</strong> (not delegated) to access the mailbox:</p>
|
||||||
|
|
||||||
|
<ol>
|
||||||
|
<li>In your app registration, go to <strong>API permissions</strong></li>
|
||||||
|
<li>Click <strong>Add a permission</strong></li>
|
||||||
|
<li>Select <strong>Microsoft Graph</strong></li>
|
||||||
|
<li>Select <strong>Application permissions</strong> (not Delegated)</li>
|
||||||
|
<li>Search for and add the following permissions:
|
||||||
|
<ul>
|
||||||
|
<li><code>Mail.Read</code> - Read mail in all mailboxes</li>
|
||||||
|
<li><code>Mail.ReadWrite</code> - Read and write mail in all mailboxes</li>
|
||||||
|
</ul>
|
||||||
|
</li>
|
||||||
|
<li>Click <strong>Add permissions</strong></li>
|
||||||
|
<li><strong>Important:</strong> Click <strong>Grant admin consent for [your organization]</strong></li>
|
||||||
|
<li>Confirm the consent</li>
|
||||||
|
</ol>
|
||||||
|
|
||||||
|
<div class="doc-callout doc-callout-info">
|
||||||
|
<strong>💡 Why ReadWrite?</strong><br>
|
||||||
|
The <code>Mail.ReadWrite</code> permission is required to move processed emails from the incoming folder to the processed folder. If you only grant <code>Mail.Read</code>, BackupChecks can import emails but cannot move them after processing.
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<h2>Step 2: Configure Mail Settings in BackupChecks</h2>
|
||||||
|
|
||||||
|
<p>After creating the Azure AD app registration, configure BackupChecks to use it:</p>
|
||||||
|
|
||||||
|
<ol>
|
||||||
|
<li>Log in to BackupChecks as an <strong>Admin</strong></li>
|
||||||
|
<li>Navigate to <strong>Settings</strong> → <strong>General</strong> tab</li>
|
||||||
|
<li>Scroll to the <strong>Mail (Microsoft Graph)</strong> section</li>
|
||||||
|
</ol>
|
||||||
|
|
||||||
|
<h3>2.1 Enter Graph Credentials</h3>
|
||||||
|
|
||||||
|
<p>Fill in the following fields with values from your Azure AD app registration:</p>
|
||||||
|
|
||||||
|
<table>
|
||||||
|
<thead>
|
||||||
|
<tr>
|
||||||
|
<th>Field</th>
|
||||||
|
<th>Description</th>
|
||||||
|
<th>Example</th>
|
||||||
|
</tr>
|
||||||
|
</thead>
|
||||||
|
<tbody>
|
||||||
|
<tr>
|
||||||
|
<td><strong>Tenant ID</strong></td>
|
||||||
|
<td>Azure AD Directory (tenant) ID</td>
|
||||||
|
<td><code>12345678-1234-1234-1234-123456789abc</code></td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td><strong>Client ID</strong></td>
|
||||||
|
<td>Azure AD Application (client) ID</td>
|
||||||
|
<td><code>87654321-4321-4321-4321-abcdef123456</code></td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td><strong>Client secret</strong></td>
|
||||||
|
<td>The secret value you copied in Step 1.2</td>
|
||||||
|
<td><code>abc123...xyz789</code></td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td><strong>Mailbox address</strong></td>
|
||||||
|
<td>Email address of the mailbox to import from</td>
|
||||||
|
<td><code>backupreports@yourdomain.com</code></td>
|
||||||
|
</tr>
|
||||||
|
</tbody>
|
||||||
|
</table>
|
||||||
|
|
||||||
|
<div class="doc-callout doc-callout-tip">
|
||||||
|
<strong>💡 Security Note:</strong><br>
|
||||||
|
The client secret field shows <code>******** (stored)</code> when a secret is already saved. Leave this field empty to keep the existing secret, or enter a new secret to replace it.
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<h3>2.2 Configure Mail Folders</h3>
|
||||||
|
|
||||||
|
<p>BackupChecks uses two folders in the mailbox:</p>
|
||||||
|
|
||||||
|
<table>
|
||||||
|
<thead>
|
||||||
|
<tr>
|
||||||
|
<th>Folder</th>
|
||||||
|
<th>Purpose</th>
|
||||||
|
<th>Example Path</th>
|
||||||
|
</tr>
|
||||||
|
</thead>
|
||||||
|
<tbody>
|
||||||
|
<tr>
|
||||||
|
<td><strong>Incoming folder</strong></td>
|
||||||
|
<td>Where backup reports arrive and are fetched from</td>
|
||||||
|
<td><code>Inbox</code> or <code>Inbox/Backup Reports</code></td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td><strong>Processed folder</strong></td>
|
||||||
|
<td>Where emails are moved after processing</td>
|
||||||
|
<td><code>Archive</code> or <code>Inbox/Processed</code></td>
|
||||||
|
</tr>
|
||||||
|
</tbody>
|
||||||
|
</table>
|
||||||
|
|
||||||
|
<p>To configure folders:</p>
|
||||||
|
|
||||||
|
<ol>
|
||||||
|
<li>Click the <strong>Browse...</strong> button next to the <strong>Incoming folder</strong> field</li>
|
||||||
|
<li>A folder browser dialog will open showing your mailbox folder structure</li>
|
||||||
|
<li>Select the folder where backup reports arrive (e.g., <code>Inbox</code>)</li>
|
||||||
|
<li>Click <strong>Select</strong></li>
|
||||||
|
<li>Repeat for the <strong>Processed folder</strong> (e.g., <code>Archive</code> or create a subfolder like <code>Inbox/Processed</code>)</li>
|
||||||
|
</ol>
|
||||||
|
|
||||||
|
<div class="doc-callout doc-callout-warning">
|
||||||
|
<strong>⚠️ Folder Structure:</strong><br>
|
||||||
|
Folder paths are case-sensitive and use forward slashes (<code>/</code>) to separate levels. For example: <code>Inbox/Backup Reports</code> refers to a subfolder named "Backup Reports" inside the Inbox folder.
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<h3>2.3 Save Settings</h3>
|
||||||
|
|
||||||
|
<p>After entering all credentials and folder paths:</p>
|
||||||
|
|
||||||
|
<ol>
|
||||||
|
<li>Click <strong>Save settings</strong> at the bottom of the page</li>
|
||||||
|
<li>BackupChecks will validate the configuration</li>
|
||||||
|
<li>If successful, you'll see a confirmation message</li>
|
||||||
|
<li>If there's an error, check your credentials and folder paths</li>
|
||||||
|
</ol>
|
||||||
|
|
||||||
|
<h2>Step 3: Test the Configuration</h2>
|
||||||
|
|
||||||
|
<p>After saving settings, verify that mail import is working:</p>
|
||||||
|
|
||||||
|
<ol>
|
||||||
|
<li>Send a test backup report email to your configured mailbox address</li>
|
||||||
|
<li>Wait a few minutes for the scheduled import to run (or trigger a manual import - see below)</li>
|
||||||
|
<li>Navigate to <strong>Inbox</strong> in BackupChecks</li>
|
||||||
|
<li>Verify that the test email appears in the inbox</li>
|
||||||
|
</ol>
|
||||||
|
|
||||||
|
<h3>Manual Import</h3>
|
||||||
|
|
||||||
|
<p>To manually trigger a mail import without waiting for the scheduled task:</p>
|
||||||
|
|
||||||
|
<ol>
|
||||||
|
<li>Navigate to <strong>Settings</strong> → <strong>Imports</strong> tab</li>
|
||||||
|
<li>Click the <strong>Import now</strong> button in the "Mail import" section</li>
|
||||||
|
<li>BackupChecks will immediately fetch new emails from the incoming folder</li>
|
||||||
|
<li>Check the <strong>Inbox</strong> page to see imported emails</li>
|
||||||
|
</ol>
|
||||||
|
|
||||||
|
<div class="doc-callout doc-callout-tip">
|
||||||
|
<strong>💡 Import Schedule:</strong><br>
|
||||||
|
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.
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<h2>Troubleshooting</h2>
|
||||||
|
|
||||||
|
<h3>Authentication Errors</h3>
|
||||||
|
|
||||||
|
<p>If you see "Failed to obtain access token" errors:</p>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
<li>Verify that <strong>Tenant ID</strong>, <strong>Client ID</strong>, and <strong>Client secret</strong> are correct</li>
|
||||||
|
<li>Check that the client secret has not expired in Azure AD</li>
|
||||||
|
<li>Ensure <strong>admin consent</strong> was granted for the API permissions</li>
|
||||||
|
<li>Verify the app registration is in the same tenant as the mailbox</li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
<h3>Folder Not Found Errors</h3>
|
||||||
|
|
||||||
|
<p>If folder configuration fails:</p>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
<li>Use the <strong>Browse...</strong> button to select folders (don't type paths manually)</li>
|
||||||
|
<li>Ensure the folders exist in the mailbox (create them if needed)</li>
|
||||||
|
<li>Check that folder names are spelled exactly as they appear in Outlook</li>
|
||||||
|
<li>Folder paths are case-sensitive</li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
<h3>No Emails Imported</h3>
|
||||||
|
|
||||||
|
<p>If manual import succeeds but no emails appear:</p>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
<li>Verify that emails exist in the <strong>incoming folder</strong></li>
|
||||||
|
<li>Check that emails have not already been moved to the <strong>processed folder</strong></li>
|
||||||
|
<li>Ensure the mailbox has emails dated within the retention period (default: 7 days)</li>
|
||||||
|
<li>Check system logs for parsing errors</li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
<h2>Advanced Configuration</h2>
|
||||||
|
|
||||||
|
<h3>Email Retention</h3>
|
||||||
|
|
||||||
|
<p>BackupChecks stores email content in the database but can also retain the original .eml file for a specified period:</p>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
<li><strong>0 days:</strong> EML files are not stored (saves database space)</li>
|
||||||
|
<li><strong>7 days:</strong> Default retention period</li>
|
||||||
|
<li><strong>14 days:</strong> Extended retention for troubleshooting</li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
<p>This setting is configured in <strong>Settings</strong> → <strong>Imports</strong> tab.</p>
|
||||||
|
|
||||||
|
<h3>Multiple Mailboxes</h3>
|
||||||
|
|
||||||
|
<p>BackupChecks currently supports importing from <strong>one mailbox</strong> at a time. If you need to monitor multiple mailboxes:</p>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
<li>Use <strong>mail forwarding rules</strong> in Exchange to forward backup reports to the configured mailbox</li>
|
||||||
|
<li>Create <strong>shared mailboxes</strong> and configure all backup software to send to the shared mailbox</li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
<h2>Security Best Practices</h2>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
<li><strong>Use a dedicated mailbox:</strong> Don't use a personal mailbox for backup reports</li>
|
||||||
|
<li><strong>Restrict app permissions:</strong> Only grant the minimum required permissions (Mail.Read and Mail.ReadWrite)</li>
|
||||||
|
<li><strong>Rotate secrets regularly:</strong> Set calendar reminders to renew client secrets before expiration</li>
|
||||||
|
<li><strong>Limit admin access:</strong> Only BackupChecks admins should have access to Settings</li>
|
||||||
|
<li><strong>Monitor import logs:</strong> Check audit logs regularly for failed authentication attempts</li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
<h2>Next Steps</h2>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
<li><a href="{{ url_for('documentation.page', section='mail-import', page='inbox-management') }}">Inbox Management</a> - Learn how to review and approve incoming emails</li>
|
||||||
|
<li><a href="{{ url_for('documentation.page', section='mail-import', page='mail-parsing') }}">Mail Parsing</a> - Understand how BackupChecks parses backup reports</li>
|
||||||
|
<li><a href="{{ url_for('documentation.page', section='mail-import', page='auto-import') }}">Auto-Import Configuration</a> - Configure automatic import schedules</li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
{% endblock %}
|
{% endblock %}
|
||||||
|
|||||||
@ -4,6 +4,13 @@ This file documents all changes made to this project via Claude Code.
|
|||||||
|
|
||||||
## [2026-02-08]
|
## [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
|
||||||
- Added comprehensive documentation system for user onboarding and reference:
|
- Added comprehensive documentation system for user onboarding and reference:
|
||||||
- **Documentation Blueprint**: New `/documentation` route with dedicated blueprint (doc_bp)
|
- **Documentation Blueprint**: New `/documentation` route with dedicated blueprint (doc_bp)
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user