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

• 1.0 Database Schema & Migrations
  • 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).
  • 1.2 Add veeam_compliance_results table to the same migration (included in 023_create_veeam_tables.sql)
  • 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
  • 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
  • 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
• 2.0 VSPC API Client & TypeScript Types
  • 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.
  • 2.2 Create /lib/services/veeam-client.ts with Bearer token auth, base URL from VEEAM_VSPC_URL env var
  • 2.3 Implement fetchAllPages<T>() generic paginated GET with offset/limit, auto-fetches all pages
  • 2.4 Implement VSPC filter query parameter support via optional filter arg on fetchAllPages
  • 2.5 Add rate limiting (100 req/min with wait) and error handling with descriptive logging
  • 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.
  • 2.7 Create /lib/services/veeam-factory.ts singleton factory following auvik-factory.ts pattern
  • 2.8 N/A — no .env.example exists; env vars already in .env
  • 2.9 Tested: connection successful, 58 organizations fetched, pagination working correctly
• 3.0 Veeam Sync Service & Scheduler Integration
  • 3.1 Created /lib/services/veeam-sync-service.ts with full/incremental sync, entity-level error handling, sync history recording
  • 3.2 Full sync implemented: orgs → servers → repos → backup jobs → agent jobs → workloads. FK safety checks prevent constraint violations.
  • 3.3 Incremental sync implemented (same as full since VSPC API lacks last-modified filtering; upserts make unchanged rows no-ops)
  • 3.4 Company matching: parses companyId string, validates against companies table, sets null if no match
  • 3.5 Sync history recorded in sync_history table with entity_type='veeam'
  • 3.6 Pagination handled by VeeamClient.fetchAllPages() — auto-fetches all pages per entity
  • 3.7 Added veeam-incremental (*/30 * * * *) and veeam-full (0 2 * * *) schedules to sync-scheduler.ts. Updated CHECK constraint and ScheduleConfig type.
  • 3.8 Veeam sync schedules visible in Admin Sync page via existing sync_schedules table
  • 3.9 Created POST /api/veeam/sync (triggers sync) and GET /api/veeam/sync (status check)
  • 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
• 4.0 Autotask Backup UDF Sync
  • 4.1 UDF field ID 29693319 confirmed from PRD; mapper searches by name 'Backup Type' or ID '29693319'
  • 4.2 Autotask queryEntity returns userDefinedFields by default for ConfigurationItems (verified in types/autotask.ts)
  • 4.3 Updated mapConfigurationItem() to extract backup UDF from userDefinedFields array and map to backup_type_udf
  • 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)
• 5.0 Backup Status API Endpoints
  • 5.1 Created GET /api/veeam/backup-status — summary stats with 24h success rate, failed/warning counts
  • 5.2 Created GET /api/veeam/companies — company-level overview with aggregated job counts and statuses
  • 5.3 Created GET /api/veeam/companies/[companyId]/workloads — per-company protected workloads
  • 5.4 Created GET /api/veeam/companies/[companyId]/jobs — server jobs + agent jobs per company
  • 5.5 N/A — sessions are embedded in job objects; jobs endpoint returns last run/status/duration
  • 5.6 Created GET /api/veeam/repositories — with backup server name join
  • 5.7 Created POST/GET /api/veeam/sync — trigger sync and check status
  • 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
• 6.0 Backup Status Page & UI Components
  • 6.1 Created backup-summary-cards.tsx — 5 KPI cards: Protected Workloads, Total Jobs, 24h Success Rate, Failed Jobs, Warnings
  • 6.2 Created company-backup-table.tsx — filterable/searchable table with expandable rows, status badges
  • 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)
  • 6.5 Created /app/backup-status/page.tsx — tabs for Backup Overview + Contract Compliance, sync button, stale warning
  • 6.6 Filters: search by company name, filter by status (All/Success/Warning/Failed)
  • 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
• 7.0 Contract Compliance Engine & UI
  • 7.1 Created GET /api/veeam/compliance — summary + mismatch list with company names
  • 7.2 Created GET /api/veeam/compliance/[companyId] — per-company compliance details
  • 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.
  • 7.4 Compliance results stored via DELETE + INSERT in veeam_compliance_results; totals logged
  • 7.5 Compliance auto-runs after successful Veeam sync (wired in veeam-sync-service.ts)
  • 7.6 Created compliance-summary-cards.tsx — 4 KPI cards
  • 7.7 Created compliance-detail-table.tsx — filterable by mismatch type and search
  • 7.8 Compliance tab integrated into backup-status/page.tsx with badge count
  • 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