Bulk Operations

Status: ✅ MVP Complete (Phase 1-4) Requirements: REQ-1, REQ-2, REQ-6, REQ-8, REQ-9

Overview

Bulk Operations allow you to perform actions on multiple content items simultaneously, saving time when managing large libraries of NPCs, encounters, plots, and other D&D content.

Available in MVP:

• ✅ Multi-select interface with keyboard shortcuts
• ✅ Batch tagging (add/remove tags)
• ✅ Bulk soft delete
• ✅ Operation undo
• ✅ Progress tracking and error handling

Deferred to Future Releases:

• ⏳ Mass PDF export
• ⏳ Encounter difficulty scaling
• ⏳ Find & replace
• ⏳ Treasure scaling

Quick Start

Basic Workflow

1. Select Items: Click checkboxes to select content items
2. Choose Action: Click "Actions" button to see available operations
3. Execute: Perform tagging, deletion, or other bulk actions
4. Undo (if needed): Use Operation History to revert changes

Features

1. Multi-Select Interface

Individual Selection

• Click checkbox in any row to select that item
• Selected items are highlighted
• Selection count badge shows how many items selected

Range Selection (Shift+Click)

1. Click first item checkbox
2. Hold Shift
3. Click last item checkbox
4. All items in range are selected

Select All (Cmd/Ctrl+A)

• Press Cmd+A (Mac) or Ctrl+A (Windows/Linux)
• Selects all items on current page
• Works when focus is on the content list

Clear Selection

• Click "Clear Selection" or deselect all checkboxes
• Selection auto-clears after successful operation

2. Batch Tagging

Add Tags to Multiple Items

1. Select items (minimum 1, maximum 500)
2. Click "Actions" → "Add Tags"
3. In the dialog:
   • Use Existing Tags: Check boxes for tags already in your library
   • Create New Tags: Type tag name and press Enter
   • Suggested Tags: Click suggested tags based on content type
4. Click "Add Tags"
5. Monitor progress bar
6. See success toast notification

Tag Suggestions by Content Type:

• NPCs: combat, friendly, boss, merchant, quest-giver
• Encounters: deadly, easy, trap, puzzle, social
• Plots: main-quest, side-quest, one-shot, mystery, dungeon-crawl

Limits:

• Max 500 items per batch
• Max 20 tags per operation
• Tag names: 1-50 characters

Remove Tags from Multiple Items

1. Select items
2. Click "Actions" → "Remove Tags"
3. Check tags to remove (only shows tags present on selected items)
4. Click "Remove Tags"
5. Monitor progress

Note: Removing a tag only affects items that have it. Items without the tag are skipped gracefully.

3. Bulk Delete

Soft Delete Multiple Items

1. Select items (minimum 1, maximum 500)
2. Click "Actions" → "Delete"
3. Review confirmation dialog:
   • Item count
   • List of items being deleted
   • Warning about potential broken references
4. Click "Delete X items" to confirm (or Cancel to abort)
5. Monitor progress
6. Items are soft deleted (archived)

Important:

• Items are soft deleted (status set to 'archived')
• Items can be restored via Undo
• Deleting items may break references in active campaigns, quests, or encounters
• Hard delete is not available in MVP (prevents accidental data loss)

4. Operation Undo

View Operation History

1. Click "Operation History" button
2. Panel shows recent bulk operations:
   • Operation summary (e.g., "Added tags to 5 items")
   • Timestamp (relative, e.g., "2 hours ago")
   • Status badges (Undone, X failed)
   • Undo button (for reversible operations)

Pagination:

• 10 operations per page
• Previous/Next buttons to navigate
• Total count displayed

Undo an Operation

1. Open Operation History panel
2. Find operation to undo
3. Click "Undo" button
4. Confirm in dialog:
   • Shows item count to restore
   • Special note for delete operations
5. Click "Confirm Undo"
6. Monitor progress
7. See success notification

What Can Be Undone:

• ✅ Tag additions (removes tags that were added)
• ✅ Tag removals (re-adds tags that were removed)
• ✅ Soft deletes (restores items to active status)

What Cannot Be Undone:

• ❌ Operations that have already been undone
• ❌ Operations without version snapshots (rare edge case)

5. Progress Tracking

During Operations

• Progress Bar: Shows percentage completion
• Item Count: Displays current/total (e.g., "25/50")
• Estimated Time: Appears for operations > 5 seconds
• Phase Indicator: Shows current operation phase

After Operations

Success:

• Green checkmark icon
• Success toast: "Successfully tagged 5 items!"
• Auto-clears selection
• Refreshes content library

Partial Success:

• Amber warning icon
• Toast shows: "5 succeeded, 2 failed"
• Error summary with failed items
• Retry button for failed items

Total Failure:

• Red error icon
• Error toast with details
• No changes applied

Keyboard Shortcuts

Limits & Constraints

Best Practices

For Game Masters

Organizing Content:

1. Tag by campaign: waterdeep-campaign, curse-of-strahd
2. Tag by theme: undead, fey, urban, dungeon
3. Tag by status: ready, draft, needs-review
4. Tag by difficulty: tier-1, tier-2, deadly

Managing Large Libraries:

1. Use multi-select for batch tagging new content
2. Leverage tag suggestions for consistency
3. Use Operation History to track changes
4. Undo if you make a mistake—it's safe!

Before Deleting:

1. Review the item list carefully
2. Consider tagging as archived instead of deleting
3. Remember deletion breaks campaign references
4. You can always undo if needed

Performance Tips

For Best Performance:

• Batch operations in groups of 25-50 items
• Use specific tags (avoid vague tags like "misc")
• Close Operation History panel when not needed
• Avoid selecting 100+ items at once

Troubleshooting

"Some items failed to tag/delete"

Causes:

• Items you don't own (shared content)
• Network connectivity issues
• Database timeout

Solutions:

1. Check error summary for specific items
2. Click "Retry Failed Items"
3. Reduce batch size if timeout occurs

"Operation cannot be undone"

Causes:

• Operation already undone
• Missing version snapshots
• Non-reversible operation type

Solutions:

• Check if operation shows "Undone" badge
• Manual restoration may be needed for missing snapshots

Selection not working

Causes:

• Browser JavaScript disabled
• Conflicting browser extension
• Focus not on content list

Solutions:

1. Reload page
2. Disable conflicting extensions
3. Click on content list before using Cmd/Ctrl+A

API Endpoints

For developers integrating with bulk operations:

See API Documentation for detailed schemas and examples.

Technical Details

Database Schema

bulk_operations table:

• Audit trail for all bulk operations
• Tracks operation type, status, items affected
• Stores version snapshot IDs for undo
• Includes error details for failed items

content_versions table:

• Snapshots of content before modification
• Enables undo functionality
• Tracks who made changes and when

content.tags column:

• PostgreSQL TEXT[] array
• GIN index for fast tag searches
• Supports array operations (add, remove, contains)

Performance

Benchmarks (50 items):

• Batch tagging: ~700ms (p95)
• Batch delete: ~1.5s (p95)
• Undo operation: ~2s (p95)

See Performance Testing Guide for detailed metrics.

Future Enhancements

Phase 2: Batch Export & Scaling (future release)

• Mass PDF export with custom templates
• Encounter difficulty scaling with CR calculator
• Treasure scaling based on DMG tables

Phase 3: Advanced Operations (future release)

• Find & replace across content
• Dependency analysis before delete
• Full treasure tables (levels 11-20)

Support

Found a bug? Report at github.com/your-repo/issues Feature request? Create discussion at github.com/your-repo/discussions Need help? Check Documentation or contact support

---

Last Updated: 2026-02-03 Version: MVP (Phases 1-4 Complete)