From 3a3e2fde588a09e7061cfe4c2788f0418db95019 Mon Sep 17 00:00:00 2001 From: Ivo Oskamp Date: Sun, 8 Feb 2026 16:16:04 +0100 Subject: [PATCH] Clarify two-step workflow for Mail Import folder configuration Enhanced Mail Import Setup documentation to clarify configuration workflow: Step 2.1 (Enter Graph Credentials): - Added warning callout: Must save credentials FIRST before folder configuration - Credentials must be saved and page refreshed before Step 2.2 works Step 2.2 (Configure Mail Folders): - Added prerequisite: Ensure credentials saved and page refreshed - Clarified folder browser popup AUTOMATICALLY loads folder structure - Emphasized: Don't type paths manually - click folders in popup - Folder browser connects to Microsoft Graph and retrieves folders - Added callout: Folder browser auto-generates correct path format - Added note about planned UI improvement for clearer workflow Step 2.3 (Save Final Configuration): - Renamed from "Save Settings" to "Save Final Configuration" - Clarified this is the SECOND save (first was in 2.1) - Added tip callout explaining two-step save process - Enhanced error checking list (credentials, folders, access policy) This clarifies the actual user workflow where credentials enable folder browsing. Co-Authored-By: Claude Sonnet 4.5 --- .../documentation/mail-import/setup.html | 62 +++++++++++++++---- docs/changelog-claude.md | 2 +- 2 files changed, 51 insertions(+), 13 deletions(-) diff --git a/containers/backupchecks/src/templates/documentation/mail-import/setup.html b/containers/backupchecks/src/templates/documentation/mail-import/setup.html index 3c85e5b..4608943 100644 --- a/containers/backupchecks/src/templates/documentation/mail-import/setup.html +++ b/containers/backupchecks/src/templates/documentation/mail-import/setup.html @@ -220,6 +220,11 @@ 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. +
+ ⚠️ Important - Save Before Folder Configuration:
+ You must save the credentials first (click "Save settings" at the bottom) and refresh the page before you can configure folders in Step 2.2. The folder browser requires valid credentials to connect to your mailbox and retrieve the folder list. +
+

2.2 Configure Mail Folders

BackupChecks uses two folders in the mailbox:

@@ -249,29 +254,62 @@

To configure folders:

    +
  1. Prerequisites: Ensure you've saved the credentials in Step 2.1 and refreshed the page
  2. Click the Browse... button next to the Incoming folder field
    3. -
  3. A folder browser dialog will open showing your mailbox folder structure
    4. -
  4. Select the folder where backup reports arrive (e.g., Inbox)
    5. -
  5. Click Select
    6. -
  6. Repeat for the Processed folder (e.g., Archive or create a subfolder like Inbox/Processed)
    7. +
  7. A folder browser popup will open and automatically load your mailbox folder structure +
      +
    • The popup connects to Microsoft Graph and retrieves all available folders
      • +
    • You will see a hierarchical list of folders (Inbox, Archive, Sent Items, etc.)
      • +
    +
    8. +
  8. Click on the folder where backup reports arrive (e.g., Inbox) +
      +
    • Don't type the path manually - select it from the list
      • +
    • You can expand subfolders by clicking on them
      • +
    +
    9. +
  9. Click Select to confirm your choice
    10. +
  10. The folder path will be automatically filled in the field (e.g., Inbox or Inbox/Backup Reports)
    11. +
  11. Repeat the same process for the Processed folder field +
      +
    • Click Browse... next to "Processed folder"
      • +
    • Select a folder like Archive or create a subfolder like Inbox/Processed
      • +
    +
-
- ⚠️ 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. +
+ 💡 Folder Browser:
+ The folder browser automatically loads all available folders from your mailbox. You don't need to manually type folder paths - simply click on the folder you want to use. The correct path format (e.g., Inbox/Backup Reports) is automatically generated.
-

2.3 Save Settings

+
+ 📝 Future Improvement:
+ The current UI requires saving credentials separately before folder browsing is available. A UI improvement is planned to make this workflow clearer, possibly combining these steps or providing better visual feedback about the required order. +
-

After entering all credentials and folder paths:

+

2.3 Save Final Configuration

+ +

After configuring the folder paths:

    -
  1. Click Save settings at the bottom of the page
    2. -
  2. BackupChecks will validate the configuration
    3. +
  3. Click Save settings at the bottom of the page again
    4. +
  4. BackupChecks will validate the complete configuration (credentials + folders)
  5. If successful, you'll see a confirmation message
    6. -
  6. If there's an error, check your credentials and folder paths
    7. +
  7. If there's an error, verify: +
      +
    • Credentials are correct (tenant ID, client ID, client secret, mailbox address)
      • +
    • Folders exist in the mailbox and paths are correct
      • +
    • Application Access Policy (if configured) allows access to the mailbox
      • +
    +
+
+ 💡 Two Save Steps:
+ You'll save settings twice: first after entering credentials (Step 2.1), then again after selecting folders (Step 2.3). This ensures credentials are available for the folder browser to connect to your mailbox. +
+

Step 3: Test the Configuration

After saving settings, verify that mail import is working:

diff --git a/docs/changelog-claude.md b/docs/changelog-claude.md index 9e96372..d486540 100644 --- a/docs/changelog-claude.md +++ b/docs/changelog-claude.md @@ -6,7 +6,7 @@ This file documents all changes made to this project via Claude Code. ### Added - Completed Mail & Import documentation section (4 pages): - - **Mail Import Setup**: Microsoft Graph API configuration with enhanced security (Azure AD app registration, start with Mail.Read only, Application Access Policy to restrict access to one mailbox via Exchange PowerShell, add Mail.ReadWrite after testing), folder configuration (incoming/processed), test configuration, troubleshooting (authentication errors, folder not found, no emails imported), advanced configuration (email retention, multiple mailboxes), comprehensive security best practices including principle of least privilege + - **Mail Import Setup**: Microsoft Graph API configuration with enhanced security (Azure AD app registration, start with Mail.Read only, Application Access Policy to restrict access to one mailbox via Exchange PowerShell, add Mail.ReadWrite after testing), two-step folder configuration workflow (save credentials first, then use automatic folder browser popup - no manual path entry), test configuration, troubleshooting (authentication errors, folder not found, no emails imported), advanced configuration (email retention, multiple mailboxes), comprehensive security best practices including principle of least privilege, note about planned UI improvement for clearer workflow - **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)