From c0fe9e2d4d1a23cb55cec7faca108d360f1ea055 Mon Sep 17 00:00:00 2001 From: Ivo Oskamp Date: Sun, 8 Feb 2026 19:37:53 +0100 Subject: [PATCH] Fix critical inaccuracies in Backup Review documentation Corrected workflow based on user feedback: - ALL runs must be marked as reviewed (including successes with overrides/tickets) - Run Checks is THE primary daily tool (not Daily Jobs) - Added blue badge for override-applied runs (not green) - Goal: completely empty Run Checks page - Added bulk review functionality for efficiency - Rewrote Complete Workflow Example to focus on Run Checks - Daily Jobs may be deprecated (only for viewing schedules) Changed files: - approving-backups.html: Stage 6/7 corrections, new workflow example - daily-jobs.html: Added blue override badge, clarified secondary role - run-checks-modal.html: Emphasized primary role, added bulk review - overrides.html: Blue badge instead of green for overrides Co-Authored-By: Claude Sonnet 4.5 --- .../backup-review/approving-backups.html | 151 ++++++++++++------ .../backup-review/daily-jobs.html | 16 +- .../backup-review/overrides.html | 13 +- .../backup-review/run-checks-modal.html | 97 ++++++----- docs/changelog-claude.md | 8 + 5 files changed, 192 insertions(+), 93 deletions(-) diff --git a/containers/backupchecks/src/templates/documentation/backup-review/approving-backups.html b/containers/backupchecks/src/templates/documentation/backup-review/approving-backups.html index 7bfa1b6..1d0564f 100644 --- a/containers/backupchecks/src/templates/documentation/backup-review/approving-backups.html +++ b/containers/backupchecks/src/templates/documentation/backup-review/approving-backups.html @@ -154,9 +154,10 @@
  • False alarms (email parsing issue, cosmetic warning)
  • One-time glitches (temporary network hiccup, already resolved)
  • Acceptable warnings (retry succeeded, minor performance issue)
    • +
  • Successful backups (no issues detected)
    • -

    Action: Click "Mark as reviewed" in the Run Checks modal.

    +

    Action: Click "Mark as reviewed" in the Run Checks modal, then the run disappears from the Run Checks page.

    Option 2: Create an Override

    @@ -168,7 +169,7 @@
  • Object-specific exceptions (one VM always has warnings due to configuration)
    • -

    Action: Create an override on the Overrides page. Future matching runs will automatically show as success with an override indicator.

    +

    Action: Create an override on the Overrides page. Future matching runs will automatically show as success with a blue override indicator. Then mark the current run as reviewed in the Run Checks modal.

    See Overrides & Exceptions for details.

    @@ -182,7 +183,7 @@
  • Investigation notes (checked with customer, not actually an issue)
    • -

    Action: Click "Create Remark" in the Run Checks modal. The remark is linked to the job and shows 💬 in Daily Jobs.

    +

    Action: Click "Create Remark" in the Run Checks modal. The remark is linked to the job and shows 💬 in Run Checks. Then mark the run as reviewed - otherwise it will remain visible and can appear incorrectly as failed/warning the next day.

    Option 4: Create a Ticket

    @@ -194,32 +195,49 @@
  • Vendor support needed (backup software bug, licensing issue)
    • -

    Action: Click "Create Ticket" in the Run Checks modal. The ticket is linked to the job and shows 🎫 in Daily Jobs.

    +

    Action: Click "Create Ticket" in the Run Checks modal. The ticket is linked to the job and shows 🎫 in Run Checks. Then mark the run as reviewed - this is required even when creating a ticket, otherwise the run stays visible.

    See Remarks & Tickets for tracking issues.

    +
    + ⚠️ Always Mark as Reviewed:
    + Regardless of which action you take (override, remark, or ticket), you must always mark the run as reviewed afterwards. If you don't, the run will remain in the Run Checks list and can show the wrong status the next day (only the first unreviewed status is displayed). +
    +

    Stage 7: Mark as Reviewed

    -

    After handling the issue (or determining no action is needed), mark the run as reviewed:

    +

    After handling the issue (or determining no action is needed), mark the run as reviewed. This is required for ALL runs, including successful ones.

    What Happens

    - 💡 Success Runs Don't Need Review:
    - Successful backup runs (green badges) are automatically considered reviewed. You only need to manually review warnings and failures. + 💡 Goal: Empty Run Checks Page:
    + The objective is to have the Run Checks page completely empty - this means all runs have been reviewed. Even successful backups must be marked as reviewed, because they haven't been looked at, but they still need to be marked to clear the Run Checks page. You can select multiple runs and mark them all as reviewed at once for efficiency.
    +

    Bulk Review

    + +

    For efficiency, you can mark multiple runs as reviewed simultaneously:

    + +
      +
    1. Open the Run Checks page
      2. +
    2. Select multiple run checkboxes
      3. +
    3. Click Mark selected as reviewed
      4. +
    4. All selected runs disappear from the list
      5. +
    + +

    This is especially useful for successful backups where no investigation is needed - you can quickly clear them to keep the Run Checks page empty.

    +

    Complete Workflow Example

    -

    Here's how a typical backup review scenario unfolds:

    +

    Here's how a typical backup review scenario unfolds using the Run Checks page (the primary daily workflow):

    Day 1: New Customer Onboarding

    @@ -230,39 +248,42 @@
  • 09:31: Click on email, verify it's legitimate, click "Approve"
  • 09:31: Select customer from dropdown, confirm
  • 09:31: Email disappears from Inbox, job is now active
    • -
  • 09:32: Job appears in Jobs page and Daily Jobs for today
    • +
  • 09:32: Job run appears in Run Checks page (unreviewed)

    • Day 2: First Daily Review

      -
    1. 08:00: Open Daily Jobs (defaults to today)
      2. -
    2. 08:01: Customer's job shows green "Success" - no action needed
      3. -
    3. 08:01: Continue reviewing other customers
      4. +
    4. 08:00: Open Run Checks page (your daily starting point)
      5. +
    5. 08:01: Customer's job shows with green "Success" badge
      6. +
    6. 08:02: Click on the run to review details (or select multiple successful runs)
      7. +
    7. 08:03: Everything looks good - click "Mark as reviewed"
      8. +
    8. 08:03: Run disappears from Run Checks page
      9. +
    9. 08:04: Continue reviewing other runs until Run Checks page is empty

    Day 5: Warning Appears

      -
    1. 08:00: Open Daily Jobs
      2. -
    2. 08:01: Customer's job shows yellow "Warning"
      3. -
    3. 08:02: Click on job to open Run Checks modal
      4. +
    4. 08:00: Open Run Checks page
      5. +
    5. 08:01: Customer's job shows yellow "Warning" badge
      6. +
    6. 08:02: Click on the warning run to investigate
    7. 08:03: Review backup objects - one VM shows "Retry succeeded"
    8. 08:04: Read email body - retry was successful, backup completed
    9. 08:05: Determine: This warning is acceptable
    10. 08:05: Click "Mark as reviewed"
      11. -
    11. 08:05: Job disappears from unreviewed list
      12. +
    12. 08:05: Run disappears from Run Checks page
    -

    Day 8: Warning Repeats

    +

    Day 8: Warning Repeats - Create Override

      -
    1. 08:00: Open Daily Jobs
      2. +
    2. 08:00: Open Run Checks page
    3. 08:01: Same customer job shows yellow "Warning" again
      4. -
    4. 08:02: Open Run Checks modal - same "Retry succeeded" warning
      5. +
    5. 08:02: Click on the warning run - same "Retry succeeded" warning
    6. 08:03: Decide: This will keep happening, create an override
      7. -
    7. 08:05: Go to Overrides page
      8. -
    8. 08:06: Create object-level override: +
    9. 08:04: Go to Overrides page
      10. +
    10. 08:05: Create object-level override:
      • Job: Select this customer's job
      • Status: Warning
        • @@ -271,54 +292,80 @@
      • Comment: "Retry warnings acceptable - backup completes successfully"
      11. -
    11. 08:07: Return to Daily Jobs - job now shows green with small override badge
      12. -
    12. 08:08: Mark the run as reviewed (still need to review once after override created)
      13. +
    13. 08:06: Override created - return to Run Checks
      14. +
    14. 08:07: The run now shows with a blue override indicator
      15. +
    15. 08:08: Mark the run as reviewed (still required even with override!)
      16. +
    16. 08:08: Run disappears from Run Checks page
      17. +
    17. Future "Retry succeeded" warnings will show with blue badge and can be quickly marked as reviewed
    -

    Day 12: Failure Occurs

    +

    Day 12: Failure Occurs - Create Ticket

      -
    1. 08:00: Open Daily Jobs
      2. -
    2. 08:01: Customer job shows red "Failed"
      3. -
    3. 08:02: Open Run Checks modal
      4. +
    4. 08:00: Open Run Checks page
      5. +
    5. 08:01: Customer job shows red "Failed" badge
      6. +
    6. 08:02: Click on the failed run to investigate
    7. 08:03: Review objects - one VM shows "Disk full"
    8. 08:04: Determine: Customer needs to free up space
      9. -
    9. 08:05: Click "Create Ticket"
      10. +
    10. 08:05: Click "Create Ticket" in the Run Checks modal
    11. 08:06: Fill in ticket:
      • Ticket code: CUST-789 (from PSA)
      • Description: "Backup fails - server disk full"
      12. -
    12. 08:07: Create PSA ticket externally (or use Autotask integration)
      13. -
    13. 08:08: Mark run as reviewed
      14. -
    14. 08:08: Job now shows 🎫 in Daily Jobs, indicating tracked issue
      15. +
    15. 08:07: Ticket created - now shows 🎫 indicator on this run
      16. +
    16. 08:08: Mark run as reviewed (required even after creating ticket!)
      17. +
    17. 08:08: Run disappears from Run Checks page
      18. +
    18. 08:09: Create PSA ticket externally (or use Autotask integration)
      19. +
    + +

    Day 13-14: Issue Still Present

    + +
      +
    1. 08:00: Open Run Checks page
      2. +
    2. 08:01: Same customer job shows red "Failed" with 🎫 indicator
      3. +
    3. 08:02: Click on run - still "Disk full" error, ticket CUST-789 visible
      4. +
    4. 08:03: No new action needed - ticket already created
      5. +
    5. 08:03: Mark as reviewed (must review each day even with active ticket!)
      6. +
    6. 08:03: Run disappears from Run Checks page

    Day 15: Issue Resolved

      -
    1. 08:00: Open Daily Jobs
      2. +
    2. 08:00: Open Run Checks page
    3. 08:01: Customer job shows green "Success" with 🎫 indicator
      4. -
    4. 08:02: Open Run Checks modal - confirm success for 2+ days
      5. -
    5. 08:03: Go to Tickets page
      6. -
    6. 08:04: Find ticket CUST-789, click "Resolve"
      7. -
    7. 08:05: 🎫 indicator disappears from Daily Jobs
      8. +
    8. 08:02: Click on run - backup succeeded, disk space resolved
      9. +
    9. 08:03: Check previous runs - success for 2+ days
      10. +
    10. 08:04: Go to Tickets page
      11. +
    11. 08:05: Find ticket CUST-789, click "Resolve"
      12. +
    12. 08:06: Return to Run Checks - 🎫 indicator now removed
      13. +
    13. 08:07: Mark run as reviewed
      14. +
    14. 08:07: Run disappears - Run Checks page empty again ✅
    +
    + 💡 Run Checks is Your Daily Workflow:
    + The Run Checks page is your primary daily tool - start here every morning. Daily Jobs is mainly for viewing which jobs exist and their schedules, but Run Checks is where all daily review work happens. Your goal is to have the Run Checks page completely empty by the end of your review session. +
    +

    Best Practices

    Role-Based Review Workflow

    @@ -326,10 +373,11 @@

    Operator Workflow

      -
    1. Review Daily Jobs for warnings and failures
      2. -
    2. Open Run Checks modal for each issue
      3. -
    3. Create tickets, remarks, or overrides as needed
      4. -
    4. Mark runs as reviewed after handling
      5. +
    5. Open Run Checks page every morning
      6. +
    6. Review each run in the list (click to see details)
      7. +
    7. For issues: create tickets, remarks, or overrides as needed
      8. +
    8. Mark ALL runs as reviewed (including successes and runs with tickets/overrides)
      9. +
    9. Goal: End with completely empty Run Checks page
    10. Cannot unmark reviewed runs or delete overrides
    @@ -341,13 +389,14 @@
  • Can unmark reviewed runs if re-investigation is needed
  • Can delete overrides and tickets
  • Monitors overall system health and team review performance
    • +
  • Can verify Run Checks page is empty (all reviews completed)

    • Viewer Workflow

    1. View Daily Jobs to see backup status
      2. -
    2. Cannot open Run Checks modal
      3. +
    3. Cannot access Run Checks page
    4. Cannot create tickets, remarks, or overrides
    5. Cannot mark runs as reviewed
    6. Read-only access for reporting and visibility
      7. @@ -356,12 +405,14 @@

      Performance Tips

        -
      • Use filters in Daily Jobs: Filter by customer or backup software to focus on specific areas
        • +
      • Use bulk review for successes: Select multiple green success runs and mark them all as reviewed at once
      • Review by exception: Use overrides to reduce noise, then focus on genuine issues
      • Batch approve inbox emails: Set aside time weekly to approve new customer jobs
      • Create global overrides for common warnings: Handle widespread acceptable warnings once
      • Use tickets for tracking workload: Helps identify which customers have recurring issues
      • Archive resolved tickets: Filter to "Active" only to reduce clutter
        • +
      • Focus on Run Checks only: Don't spend time in Daily Jobs unless you need to check schedules - Run Checks is your daily tool
        • +
      • Process runs in order: Work through the Run Checks list from top to bottom systematically

      Next Steps

      diff --git a/containers/backupchecks/src/templates/documentation/backup-review/daily-jobs.html b/containers/backupchecks/src/templates/documentation/backup-review/daily-jobs.html index 783d158..ae4b034 100644 --- a/containers/backupchecks/src/templates/documentation/backup-review/daily-jobs.html +++ b/containers/backupchecks/src/templates/documentation/backup-review/daily-jobs.html @@ -9,7 +9,12 @@

      Overview

      -

      The Daily Jobs view is the primary operational dashboard for monitoring backup operations. It displays all backup jobs expected to run on a selected date, based on intelligent schedule inference from historical run patterns.

      +

      The Daily Jobs view displays all backup jobs expected to run on a selected date, based on intelligent schedule inference from historical run patterns. It provides an overview of which jobs exist and their schedules.

      + +
      + 💡 Daily Jobs vs Run Checks:
      + Daily Jobs is primarily for viewing which jobs exist and their schedules. For daily operational review work, use the Run Checks page instead - that's where you review and mark runs as complete. Daily Jobs may be deprecated in a future version. +

      Key features:

      @@ -17,7 +22,7 @@
    7. Schedule inference: Automatically detects weekly and monthly backup schedules from historical runs
    8. Status tracking: Shows which jobs succeeded, failed, have warnings, or haven't run yet
    9. Missing job detection: Identifies jobs that should have run but didn't
      10. -
    10. Override indicators: Displays badges for jobs with active overrides
      11. +
    11. Override indicators: Displays blue badges for jobs with active overrides
    12. Ticket and remark indicators: Shows 🎫 and 💬 icons for jobs with linked tickets or remarks
      13. @@ -116,6 +121,11 @@ Green Job completed successfully with no warnings or errors + + Success (Override) + Blue + Job had warning/failure but is treated as success due to an active override rule + Warning Yellow @@ -133,7 +143,7 @@ Expected - Blue + Light Blue Job is expected to run later today (for future dates or today before the job runs) diff --git a/containers/backupchecks/src/templates/documentation/backup-review/overrides.html b/containers/backupchecks/src/templates/documentation/backup-review/overrides.html index 6d040cb..01044f4 100644 --- a/containers/backupchecks/src/templates/documentation/backup-review/overrides.html +++ b/containers/backupchecks/src/templates/documentation/backup-review/overrides.html @@ -122,12 +122,17 @@

      The primary action for overrides is Treat as success (enabled by default):

        -
      • When checked, matching runs are displayed with a green "Success" badge instead of their original status
        • -
      • A small override indicator badge appears next to the job showing the override is active
        • -
      • The run still needs to be reviewed, but operators know the warning/failure is expected
        • +
      • When checked, matching runs are displayed with a blue "Success (Override)" badge instead of their original warning/failed status
        • +
      • The blue badge visually indicates this run had an issue but is being treated as acceptable
        • +
      • The run still needs to be reviewed and marked as reviewed, but operators know the warning/failure is expected
      -

      This allows you to visually differentiate between unexpected problems (red/yellow) and known issues (green with override badge).

      +

      This allows you to visually differentiate between:

      +
        +
      • Green badge: Genuinely successful backups with no issues
        • +
      • Blue badge: Known issues that are acceptable (override applied)
        • +
      • Yellow/Red badge: Unexpected problems requiring investigation
        • +

      Override Time Windows

      diff --git a/containers/backupchecks/src/templates/documentation/backup-review/run-checks-modal.html b/containers/backupchecks/src/templates/documentation/backup-review/run-checks-modal.html index a059dae..9c2c5eb 100644 --- a/containers/backupchecks/src/templates/documentation/backup-review/run-checks-modal.html +++ b/containers/backupchecks/src/templates/documentation/backup-review/run-checks-modal.html @@ -9,32 +9,38 @@

      Overview

      -

      The Run Checks modal is the detailed review interface for investigating backup job runs. It opens when you click on a job in the Daily Jobs view or Job History page.

      - -

      The modal provides:

      - -
        -
      • Job run history: List of recent runs for the selected job, showing status and timestamps
        • -
      • Backup objects: Individual items backed up (VMs, servers, files) with their statuses
        • -
      • Email content: Original email body from the backup software
        • -
      • Override information: Details about applied overrides for known issues
        • -
      • Autotask ticket info: Linked PSA ticket details (if Autotask integration is enabled)
        • -
      • Review actions: Mark runs as reviewed or unmark reviewed runs (Admin only)
        • -
      - -

      Opening the Run Checks Modal

      - -

      The Run Checks modal can be opened from several locations:

      - -
        -
      • Daily Jobs view: Click on any job row
        • -
      • Job History page: Click on a specific job run
        • -
      • Tickets page: Click "Job page" button for a ticket with a linked job
        • -
      +

      The Run Checks page is the primary daily operational tool for reviewing backup job runs. This is where you spend most of your time during daily backup review.

      - 💡 Role Access:
      - The Run Checks modal is available to Admin and Operator roles only. Viewers cannot open the Run Checks modal. + 💡 Your Daily Starting Point:
      + Start here every morning. The goal is to have this page completely empty - meaning all runs have been reviewed. Even successful backups must be marked as reviewed to clear the page. +
      + +

      The page provides:

      + +
        +
      • Job run list: All unreviewed runs across all customers, showing status and timestamps
        • +
      • Backup objects: Individual items backed up (VMs, servers, files) with their statuses
        • +
      • Email content: Original email body from the backup software
        • +
      • Override information: Details about applied overrides (shown with blue badge)
        • +
      • Autotask ticket info: Linked PSA ticket details (if Autotask integration is enabled)
        • +
      • Review actions: Mark runs as reviewed (single or bulk), unmark reviewed runs (Admin only)
        • +
      + +

      Accessing Run Checks

      + +

      To access the Run Checks page:

      + +
        +
      1. Navigate to Run Checks in the main navigation menu
        2. +
      2. Available to Admin and Operator roles only
        3. +
      3. Viewers cannot access the Run Checks page
        4. +
      4. The page shows all unreviewed runs by default
        5. +
      + +
      + 💡 Start Here Every Day:
      + This is your primary daily workflow page. Open it first thing in the morning and work through all runs until the page is empty.

      Modal Layout

      @@ -79,9 +85,17 @@

      At the top of the run details:

        -
      • Status badge: Overall run status (Success, Warning, Failed, Missed)
        • +
      • Status badge: Overall run status with color coding: +
          +
        • Green = Success (no issues)
          • +
        • Blue = Success (override applied - originally warning/failed)
          • +
        • Yellow = Warning
          • +
        • Red = Failed
          • +
        • Gray = Missed
          • +
        +
      • Run timestamp: When the backup job executed
        • -
      • Override indicator: If an override is applied, shows the override reason
        • +
      • Override indicator: If an override is applied, shows blue badge with override reason

      Backup Objects

      @@ -163,22 +177,33 @@

      Review Actions

      -

      Mark as Reviewed

      +

      Mark as Reviewed (Single)

      -

      For runs with warnings or failures:

      +

      For any run (success, warning, or failure):

        -
      1. Review the run details, backup objects, and error messages
        2. -
      2. Investigate the issue and determine if action is needed
        3. -
      3. Click the Mark as reviewed button at the top or bottom of the run details
        4. -
      4. The run is immediately marked as reviewed and disappears from the unreviewed list
        5. +
      5. Click on a run in the list to view details
        6. +
      6. Review the run details, backup objects, and any error messages
        7. +
      7. Take action if needed (create ticket, remark, or override)
        8. +
      8. Click the Mark as reviewed button
        9. +
      9. The run is immediately marked as reviewed and disappears from the Run Checks page
      -

      Marking a run as reviewed indicates that you have acknowledged the issue and taken appropriate action (or determined no action is needed).

      +

      Mark as Reviewed (Bulk)

      -
      - 💡 Review Purpose:
      - The review workflow helps ensure all warnings and failures are seen by a human operator. Success runs do not need to be reviewed - they are automatically considered reviewed. +

      For efficiency, especially with successful backups:

      + +
        +
      1. Select multiple run checkboxes in the Run Checks list
        2. +
      2. Click Mark selected as reviewed button
        3. +
      3. All selected runs disappear from the Run Checks page
        4. +
      + +

      This is particularly useful for quickly clearing successful backups that don't require investigation.

      + +
      + ⚠️ All Runs Must Be Reviewed:
      + Even successful backup runs must be marked as reviewed to clear the Run Checks page. They're not individually investigated, but they still need to be marked so the page becomes empty. Use bulk review to quickly clear multiple successful runs at once.

      Unmark Reviewed (Admin Only)

      diff --git a/docs/changelog-claude.md b/docs/changelog-claude.md index a7c78ff..1c0502f 100644 --- a/docs/changelog-claude.md +++ b/docs/changelog-claude.md @@ -4,6 +4,14 @@ This file documents all changes made to this project via Claude Code. ## [2026-02-08] +### Changed +- Fixed critical inaccuracies in Backup Review documentation based on user feedback: + - **Approving Backups page**: Corrected Stage 6 to emphasize ALL runs must be marked as reviewed regardless of action taken (override/ticket/remark created), added warning callout that failing to mark as reviewed leaves runs visible with wrong status next day, corrected Stage 7 to clarify successful runs MUST also be reviewed (goal is empty Run Checks page), added bulk review functionality for efficiency, completely rewrote Complete Workflow Example to focus on Run Checks page (primary daily tool) instead of Daily Jobs, updated best practices and role-based workflows to prioritize Run Checks over Daily Jobs, added performance tips for bulk review + - **Daily Jobs page**: Added blue "Success (Override)" status indicator to table showing runs treated as success due to active override, added callout clarifying Daily Jobs is for viewing schedules only and Run Checks is the primary operational tool (Daily Jobs may be deprecated in future), corrected page purpose from "primary operational dashboard" to schedule viewing tool + - **Run Checks Modal page**: Corrected overview to emphasize this is THE primary daily operational tool (not just detail modal), added callout that goal is completely empty page, corrected "Success Runs Don't Need Review" to "All Runs Must Be Reviewed" with explanation, added bulk review section (select multiple + mark all), updated status information to include blue badge for override-applied runs, changed access description from "modal" to "page" + - **Overrides & Exceptions page**: Updated "Treat as Success" action description to show blue badge instead of green, added visual differentiation explanation (green=genuine success, blue=override applied, yellow/red=unexpected problems) + - All changes ensure documentation accurately reflects actual workflow: Run Checks is primary tool, all runs need review (including successes), blue badges indicate overrides + ### 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), two-step save workflow clarification (same "Save settings" button clicked twice - once for credentials to enable folder browsing, then again for complete configuration), 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 to make two-step save workflow more obvious