SBAM — Complete User Guide

This guide details all user-facing capabilities of SBAM in both the Single Issue Panel and the Global Navigator.

---

Part 1: Single Issue Panel Operations

1. Category Tabs & Dynamic Counters

At the top of the panel, category pills classify attachments by their file extensions:

• All: Displays all visible files on the issue.
• PDF: .pdf documents.
• Office: .docx, .doc, .xlsx, .xls, .pptx, .csv, .txt, .rtf.
• Images: .png, .jpg, .jpeg, .gif, .svg, .webp.
• Archives: .zip, .7z, .rar, .tar, .gz.
• Data: .json, .log, .xml, .sql, .yaml, .yml.
• Other: Any file extension not categorized above.

Dynamic Counter Badges:
Each pill displays the count of matching attachments (e.g., PDF (3)). When you select files, the counter updates to show selection progress (e.g., PDF (2/3)).

---

2. Search & Smart Anti-Junk Filter

• Search Input: Type any part of a file name to filter the table instantly.
• Smart Anti-Junk Filter Checkbox: Automatically hides small image attachments (default: < 20 KB) typically generated by email signatures, social badges, and tracking pixels.
• Settings Button: Opens the Extension & Display Preferences modal:
  • Configure specific extensions targeted by the Anti-Junk filter.
  • Enable or disable default category tabs across all Jira issues.
  • Settings are saved per-user in isolated tenant storage (@forge/kvs).

---

3. Attachment Table Actions

Each row in the table provides metadata (Filename, Size, Author, Date Added) and individual action buttons:

• Checkbox Selection: Toggle individual files or use the header checkbox to select/deselect all visible items.
• Rename File (Pencil Icon): Opens the Atomic Rename Modal. Enter a new base name; the original extension is locked and preserved automatically. The backend executes an atomic rename with rollback protection.
• Move to Trash (Trash Icon): Moves the single file to the virtual Trash Vault (visible only if you have deletion permissions for that file).
• Download File (Download Icon): Downloads the single binary file directly to your local machine.

---

4. Bottom Action Bar (ZIP & Bulk Actions)

• Selection Summary: Shows the number of selected files versus visible files.
• Folder Structure Options:
  • Per-issue folder ([ISSUE-KEY]/): Places downloaded files inside a folder named after the issue key.
  • Category subfolders: Creates subfolders (PDFs/, Office/, Images/, etc.) inside the ZIP.
• Select All / Deselect All: Quickly toggles selection for all currently filtered items.
• Move to Trash Button: Moves all selected deletable files to the Trash Vault.
• Caret Dropdown Menu (▼):
  • Move Junk to Trash: Automatically detects and moves all junk/signature files on the issue to Trash in one click, without requiring manual selection.
• Download Selected (.ZIP): Packages all selected files using high-speed, parallel client-side JSZip streaming. A real-time progress indicator displays download and packaging status.

---

Part 2: Global Cross-Project Navigator

Access the Global Navigator from the Jira top navigation or the Issue Navigator action menu (SBAM — Smart Attachment Manager).

1. View Modes

• Project Folders: Groups attachments hierarchically by Project Key ([PROJ-KEY] Project Name) with total file count, combined storage weight, and nested issue accordions. Includes sub-pagination for projects with large issue counts.
• Issue Folders: Groups attachments by individual Jira issues ([KEY-123] Summary).
• Flat Files: Consolidated, full-height table view of all attachments across all queried issues.

---

2. Hybrid Search (Text vs. JQL Mode)

The search bar provides two distinct modes:

• Text Mode: Real-time client-side filtering across loaded file names, issue keys, summaries, and project names.
• JQL Mode: Server-side Jira Query Language execution (e.g., project = DEV AND status = "In Progress" or created >= -30d). Click Search or press Enter to fetch attachments across your Jira Cloud instance.

---

3. Custom Move to Trash (Rule-Based Cleanup)

Click the caret dropdown next to Move to Trash and select Custom Move to Trash to open the multi-criteria cleanup engine:

1. Step 1 — Criteria Configuration:
   • File Size: Greater than (>) or less than (<) specified KB / MB / GB.
   • File Age: Older than (>) or newer than (<) specified Days / Months / Years.
   • Author Name: Filter by specific uploader or bot name.
   • File Extensions: Select predefined groups or add custom extensions (e.g., .dmp, .log).
2. Step 2 — Impact Analysis & Confirmation:
   • SBAM calculates the exact number of matching files and total storage to be reclaimed.
   • Type TRASH into the confirmation field to execute the bulk move.

---

Part 3: Virtual Trash Vault

Click the Trash Vault button in the Global Navigator to open the soft-deletion recovery catalog.

1. Retention Status Indicators

• X days left (Blue): Standard active retention period.
• Expires in <24h (Yellow): Grace period / final 24 hours before automatic purge.
• Expired (Red): Scheduled for deletion by the daily background job.
• Never expires (Purple): Indefinite retention (set to 9999 days).

2. Restoring Files (3-Tier RBAC)

Select items and click Restore Selected:

• Standard Users: Can restore files they originally uploaded or moved to trash. Restricted files are indicated with a (Restricted) label.
• Project Administrators: Can restore any file belonging to their managed projects.
• Jira Global Administrators: Can restore any file across all projects.

3. Self-Healing Engine

If an attachment is deleted or renamed natively in Jira outside of SBAM, SBAM's reconciliation engine automatically detects the change and removes ghost records from the Trash Vault without user intervention.