Sharepoint-Toolbox/.planning/phases/04-bulk-operations-and-provisioning/04-CONTEXT.md

Phase 4: Bulk Operations and Provisioning - Context

Gathered: 2026-04-02 Status: Ready for planning

## Phase Boundary

Users can execute bulk write operations (member additions, site creation, file transfer) with per-item error reporting and cancellation, capture site structures as reusable templates, apply templates to create new sites, and provision folder structures from CSV — all without silent partial failures.

Requirements: BULK-01, BULK-02, BULK-03, BULK-04, BULK-05, TMPL-01, TMPL-02, TMPL-03, TMPL-04, FOLD-01, FOLD-02

## Implementation Decisions

Bulk operation failure behavior

• Continue all items on error, report summary at end — never stop on first failure
• Errors are logged live in the log panel (red) AND user can export a CSV of failed items after completion
• Failed-items CSV includes: original row data, error message, timestamp — user can fix and re-import
• "Retry Failed" button appears after completion with partial failures, re-runs only failed items
• User can also manually re-import the corrected failed-items CSV
• Always show a confirmation summary dialog before any bulk write operation starts (e.g., "12 members will be added to 3 groups — Proceed?")

File transfer semantics

• User chooses Copy or Move (radio button or dropdown) — both options always visible
• Move deletes source files only after successful transfer to destination
• Conflict policy is user-selectable per operation: Skip / Overwrite / Rename (append suffix)
• One conflict policy applies to all files in the batch
• Source and destination selection: site picker + library/folder tree browser on both sides (reuse SitePickerDialog pattern from Phase 2)
• Metadata preservation: best effort — try to set original author and dates via CSOM; if SharePoint rejects (common cross-tenant), log a warning and continue

Template capture scope

• User selects what to capture via checkboxes (not a fixed capture)
• Available capture options (core set): Libraries, Folders, Permission groups, Site logo, Site settings (title, description, regional settings)
• No custom columns, content types, or navigation links in v1 — keep templates lightweight
• Template remembers source site type (Communication or Teams) and creates the same type on apply — no user choice of target type
• Templates persisted as JSON locally (TMPL-03)
• Dedicated Templates tab in the main UI — templates are a first-class feature area with: list of saved templates, capture button, apply button, rename/delete

CSV format and pre-flight validation

• Bundled example CSV templates shipped with the app for each bulk operation (member addition, site creation, folder structure) — pre-filled with sample data as reference
• After CSV import: full validation pass + DataGrid preview showing all rows with valid/invalid indicators
• User reviews the preview grid, then clicks "Execute" to proceed
• Invalid rows highlighted — user can fix and re-import before executing
• CSV encoding: UTF-8 with BOM detection (accept with or without BOM, matches Excel output and app's own CSV exports)

Tab organization

• Each operation gets its own top-level tab: Transfer, Bulk Members, Bulk Sites, Folder Structure, Templates
• Matches the existing PowerShell tool's tab structure
• Each tab follows FeatureViewModelBase pattern (AsyncRelayCommand + IProgress + CancellationToken)

Claude's Discretion

• Exact CSV column names and schemas for each bulk operation type
• Tree browser component implementation details for file transfer source/destination
• Template JSON schema structure
• PnP Provisioning Engine usage details for template apply
• Confirmation dialog layout and wording
• DataGrid preview grid column configuration
• Retry mechanism implementation details

<code_context>

Existing Code Insights

Reusable Assets

• FeatureViewModelBase: Base for all feature ViewModels — AsyncRelayCommand, IProgress, CancellationToken, TenantSwitchedMessage handling
• SitePickerDialog: Site selection dialog from Phase 2 — reuse for source/destination pickers in file transfer
• OperationProgress(int Current, int Total, string Message): Shared progress model used by all services
• ExecuteQueryRetryHelper: Auto-retry on 429/503 with exponential backoff — all CSOM calls use this
• SharePointPaginationHelper: Async enumerable for paginated list queries
• SessionManager: Singleton holding all ClientContext instances — GetOrCreateContextAsync(TenantProfile, CancellationToken)
• CsvExportService pattern: UTF-8 BOM, RFC 4180 quoting — follow for bulk operation error report exports

Established Patterns

• Service interfaces registered as transient in DI (App.xaml.cs)
• ViewModels use [ObservableProperty] attributes + ObservableCollection<T> for results
• Export commands use SaveFileDialog wired via Func<> factory from View code-behind
• Per-tab progress bar + cancel button (Visibility bound to IsRunning)
• Results accumulated in List on background thread, assigned as new ObservableCollection on UI thread

Integration Points

• App.xaml.cs RegisterServices(): Add new services, ViewModels, Views
• MainWindow.xaml: Add new TabItems for Transfer, Bulk Members, Bulk Sites, Folder Structure, Templates
• MainWindow.xaml.cs: Wire View content from DI at runtime (same pattern as Permissions, Storage, Search tabs)
• Core/Models/: New models for bulk operation items, template schema, CSV row types
• Services/: New service interfaces and implementations for each bulk operation
• Strings.resx / Strings.fr.resx: Localization keys for all Phase 4 UI strings

</code_context>

## Specific Ideas

• Tab structure should match the existing PowerShell tool (9 tabs: Perms, Storage, Templates, Search, Dupes, Transfer, Bulk, Struct, Versions)
• Bundled CSV examples should have realistic sample data (not just headers) so MSP admins can understand the format immediately
• Confirmation dialog before writes is non-negotiable — these are destructive operations on client tenants
• Failed-items CSV should be directly re-importable without editing (same format as input CSV, with an extra error column appended)

## Deferred Ideas

None — discussion stayed within phase scope

---

Phase: 04-bulk-operations-and-provisioning Context gathered: 2026-04-02