wulf-pulse/tasks/tasks-prd-veeam-integration.md

## Relevant Files

- `lib/services/veeam-client.ts` - VSPC REST API client handling authentication, pagination, filtering, and rate limiting.
- `lib/services/veeam-factory.ts` - Singleton factory for the Veeam client instance.
- `lib/services/veeam-sync-service.ts` - Sync orchestration service for fetching and persisting Veeam data to PostgreSQL.
- `lib/services/veeam-compliance-service.ts` - Contract compliance computation logic (cross-referencing Autotask config items with Veeam workloads).
- `lib/types/veeam.ts` - TypeScript type definitions for all Veeam entities and UI models.
- `lib/utils/entity-mapper.ts` - Existing entity mapper; needs update to map backup UDF from Autotask config items.
- `lib/services/sync-scheduler.ts` - Existing sync scheduler; needs Veeam sync schedule integration.
- `migrations/023_create_veeam_tables.sql` - Database migration for all Veeam tables and compliance results table.
- `migrations/024_add_backup_type_udf.sql` - Database migration to add `backup_type_udf` column to `configuration_items`.
- `app/api/veeam/backup-status/route.ts` - API endpoint for backup summary statistics.
- `app/api/veeam/companies/route.ts` - API endpoint for company-level backup overview.
- `app/api/veeam/companies/[companyId]/workloads/route.ts` - API endpoint for per-company protected workloads.
- `app/api/veeam/companies/[companyId]/jobs/route.ts` - API endpoint for per-company backup jobs.
- `app/api/veeam/companies/[companyId]/sessions/route.ts` - API endpoint for per-company job sessions.
- `app/api/veeam/repositories/route.ts` - API endpoint for repository capacity overview.
- `app/api/veeam/sync/route.ts` - API endpoint to trigger manual Veeam sync.
- `app/api/veeam/compliance/route.ts` - API endpoint for compliance summary and mismatch list.
- `app/api/veeam/compliance/[companyId]/route.ts` - API endpoint for per-company compliance details.
- `app/backup-status/page.tsx` - Main Backup Status page with tabs for Backup Overview and Contract Compliance.
- `components/backup/backup-summary-cards.tsx` - Summary KPI cards component (protected, unprotected, success rate, failed, repo usage).
- `components/backup/company-backup-table.tsx` - Company backup overview table with expandable rows.
- `components/backup/company-backup-detail.tsx` - Expanded company detail view (workloads, jobs, sessions, compliance).
- `components/backup/repository-overview.tsx` - Repository capacity visualization component.
- `components/backup/compliance-summary-cards.tsx` - Compliance KPI cards (contracted, matched, missing backup, no contract).
- `components/backup/compliance-detail-table.tsx` - Compliance mismatch detail table with filters.

### Notes

- Unit tests should typically be placed alongside the code files they are testing (e.g., `veeam-client.ts` and `veeam-client.test.ts` in the same directory).
- Use `npx jest [optional/path/to/test/file]` to run tests. Running without a path executes all tests found by the Jest configuration.

## Tasks

- [x] 1.0 Database Schema & Migrations
  - [x] 1.1 Create migration `023_create_veeam_tables.sql` with tables: `veeam_organizations`, `veeam_backup_servers`, `veeam_backup_jobs` (VM jobs), `veeam_backup_agent_jobs` (workstation/physical jobs), `veeam_protected_workloads`, `veeam_repositories`, `veeam_compliance_results`. Note: `veeam_job_sessions` and `veeam_restore_points` were removed — session data (lastRun, lastEndTime, status, bottleneck, failureMessage) is embedded directly on job objects in the VSPC API. Agent jobs (753 total) were added as a separate table since they have a different schema than backup server jobs (182 total).
  - [x] 1.2 Add `veeam_compliance_results` table to the same migration (included in 023_create_veeam_tables.sql)
  - [x] 1.3 Add indexes on `organization_uid`, `company_id`, `status`, `synced_at`, `last_run` across Veeam tables; indexes on `veeam_compliance_results.company_id`, `mismatch_type`, and `computed_at`
  - [x] 1.4 Create migration `024_add_backup_type_udf.sql` to add `backup_type_udf` (VARCHAR, nullable) column to the existing `configuration_items` table, with an index on `backup_type_udf`
  - [x] 1.5 Test that both migrations run cleanly against the existing database schema without errors — verified 7 veeam_* tables created and backup_type_udf column added to configuration_items
- [x] 2.0 VSPC API Client & TypeScript Types
  - [x] 2.1 Create `/lib/types/veeam.ts` with interfaces for VSPC API response types (`VspcOrganization`, `VspcBackupServer`, `VspcBackupJob`, `VspcBackupAgentJob`, `VspcProtectedWorkload`, `VspcRepository`), DB entity types (`VeeamOrganization`, `VeeamBackupServer`, `VeeamBackupJob`, `VeeamBackupAgentJob`, `VeeamProtectedWorkload`, `VeeamRepository`, `VeeamComplianceResult`), and UI types (`VeeamBackupStatusSummary`, `VeeamCompanyBackupOverview`, `VeeamComplianceSummary`). Updated to match actual API shapes.
  - [x] 2.2 Create `/lib/services/veeam-client.ts` with Bearer token auth, base URL from `VEEAM_VSPC_URL` env var
  - [x] 2.3 Implement `fetchAllPages<T>()` generic paginated GET with `offset`/`limit`, auto-fetches all pages
  - [x] 2.4 Implement VSPC `filter` query parameter support via optional filter arg on `fetchAllPages`
  - [x] 2.5 Add rate limiting (100 req/min with wait) and error handling with descriptive logging
  - [x] 2.6 Implement data-fetching methods: `getOrganizations()`, `getBackupServers()`, `getBackupJobs()`, `getBackupAgentJobs()`, `getProtectedWorkloads()`, `getRepositories()`, `testConnection()`. Note: `getJobSessions()` and `getRestorePoints()` removed — data is embedded in job/workload objects.
  - [x] 2.7 Create `/lib/services/veeam-factory.ts` singleton factory following `auvik-factory.ts` pattern
  - [x] 2.8 N/A — no `.env.example` exists; env vars already in `.env`
  - [x] 2.9 Tested: connection successful, 58 organizations fetched, pagination working correctly
- [x] 3.0 Veeam Sync Service & Scheduler Integration
  - [x] 3.1 Created `/lib/services/veeam-sync-service.ts` with full/incremental sync, entity-level error handling, sync history recording
  - [x] 3.2 Full sync implemented: orgs → servers → repos → backup jobs → agent jobs → workloads. FK safety checks prevent constraint violations.
  - [x] 3.3 Incremental sync implemented (same as full since VSPC API lacks last-modified filtering; upserts make unchanged rows no-ops)
  - [x] 3.4 Company matching: parses companyId string, validates against companies table, sets null if no match
  - [x] 3.5 Sync history recorded in sync_history table with entity_type='veeam'
  - [x] 3.6 Pagination handled by VeeamClient.fetchAllPages() — auto-fetches all pages per entity
  - [x] 3.7 Added veeam-incremental (*/30 * * * *) and veeam-full (0 2 * * *) schedules to sync-scheduler.ts. Updated CHECK constraint and ScheduleConfig type.
  - [x] 3.8 Veeam sync schedules visible in Admin Sync page via existing sync_schedules table
  - [x] 3.9 Created POST /api/veeam/sync (triggers sync) and GET /api/veeam/sync (status check)
  - [x] 3.10 Tested: full sync completed in 2.8s — 58 orgs, 47 servers, 209 repos, 182 jobs, 753 agent jobs, 157 workloads = 1,406 records
- [x] 4.0 Autotask Backup UDF Sync
  - [x] 4.1 UDF field ID 29693319 confirmed from PRD; mapper searches by name 'Backup Type' or ID '29693319'
  - [x] 4.2 Autotask queryEntity returns userDefinedFields by default for ConfigurationItems (verified in types/autotask.ts)
  - [x] 4.3 Updated mapConfigurationItem() to extract backup UDF from userDefinedFields array and map to backup_type_udf
  - [x] 4.4 Migration 024 already applied (Task 1.5)
  - [ ] 4.5 Pending: trigger Autotask config items sync to populate backup_type_udf values (requires Autotask sync run)
  - [ ] 4.6 Pending: query Autotask picklist for complete UDF values (requires Autotask API call)
  - [ ] 4.7 Contract status = 1 used for Active in compliance queries (standard Autotask value)
- [x] 5.0 Backup Status API Endpoints
  - [x] 5.1 Created GET /api/veeam/backup-status — summary stats with 24h success rate, failed/warning counts
  - [x] 5.2 Created GET /api/veeam/companies — company-level overview with aggregated job counts and statuses
  - [x] 5.3 Created GET /api/veeam/companies/[companyId]/workloads — per-company protected workloads
  - [x] 5.4 Created GET /api/veeam/companies/[companyId]/jobs — server jobs + agent jobs per company
  - [x] 5.5 N/A — sessions are embedded in job objects; jobs endpoint returns last run/status/duration
  - [x] 5.6 Created GET /api/veeam/repositories — with backup server name join
  - [x] 5.7 Created POST/GET /api/veeam/sync — trigger sync and check status
  - [x] 5.8 All endpoints return graceful empty arrays/objects on error via try/catch
  - [ ] 5.9 Pending: test endpoints with real synced data via browser
- [x] 6.0 Backup Status Page & UI Components
  - [x] 6.1 Created backup-summary-cards.tsx — 5 KPI cards: Protected Workloads, Total Jobs, 24h Success Rate, Failed Jobs, Warnings
  - [x] 6.2 Created company-backup-table.tsx — filterable/searchable table with expandable rows, status badges
  - [x] 6.3 Created company-backup-detail.tsx — expanded view with workloads, jobs (server+agent), compliance issues
  - [ ] 6.4 Pending: repository-overview.tsx with capacity progress bars (repos have minimal data from API)
  - [x] 6.5 Created /app/backup-status/page.tsx — tabs for Backup Overview + Contract Compliance, sync button, stale warning
  - [x] 6.6 Filters: search by company name, filter by status (All/Success/Warning/Failed)
  - [x] 6.7 Added HardDrive icon + Backup Status link to app-navigation.tsx
  - [ ] 6.8 Pending: verify page renders with real data via browser
  - [ ] 6.9 Pending: verify responsive layout
- [x] 7.0 Contract Compliance Engine & UI
  - [x] 7.1 Created GET /api/veeam/compliance — summary + mismatch list with company names
  - [x] 7.2 Created GET /api/veeam/compliance/[companyId] — per-company compliance details
  - [x] 7.3 Created veeam-compliance-service.ts — matches config items (backup_type_udf + company active contract) against Veeam workloads by hostname. Note: uses company-level contract matching since config_items don't have direct contract_id.
  - [x] 7.4 Compliance results stored via DELETE + INSERT in veeam_compliance_results; totals logged
  - [x] 7.5 Compliance auto-runs after successful Veeam sync (wired in veeam-sync-service.ts)
  - [x] 7.6 Created compliance-summary-cards.tsx — 4 KPI cards
  - [x] 7.7 Created compliance-detail-table.tsx — filterable by mismatch type and search
  - [x] 7.8 Compliance tab integrated into backup-status/page.tsx with badge count
  - [x] 7.9 Company backup detail shows compliance issues section when mismatches exist
  - [ ] 7.10 Pending: test compliance with known data after Autotask sync populates backup_type_udf