Ivo Oskamp 467f350184 Auto-commit local changes before build (2026-02-23 10:14:36)

2026-02-23 10:14:36 +01:00

8.1 KiB

Raw Blame History

TODO: Cove Data Protection Integration

Date: 2026-02-23
Status: Research COMPLETED — Ready for implementation
Priority: Medium

🎯 Goal

Integrate Cove Data Protection (formerly N-able Backup / SolarWinds Backup) into Backupchecks for backup status monitoring via scheduled API polling. The integration runs server-side within the Backupchecks web application.

Challenge: Cove does NOT work with email notifications like other backup systems (Veeam, Synology, NAKIVO). We use the JSON-RPC API instead.

✅ Research Phase — COMPLETED (2026-02-23)

Confirmed findings

API endpoint: https://api.backup.management/jsonapi
Protocol: JSON-RPC 2.0, POST requests, Content-Type: application/json
Authentication: Login method returns a visa token — include in all subsequent calls
PartnerId: 139124 (MCC Automatisering) — required for all queries, partnernaam is NIET nodig
Alle benodigde data is beschikbaar — eerdere blockers (D02/D03 errors) waren door gebruik van legacy column codes. Vervangen door D10/D11.
Geen MSP-level beperking — elke API user heeft dezelfde toegang. Toegang tot alle sub-customers via top-level account.
Geen EnumerateAccounts nodig — EnumerateAccountStatistics met juiste columns geeft alles wat we nodig hebben.

Officiële documentatie (van N-able support, Andrew Robinson)

Getting Started: https://developer.n-able.com/n-able-cove/docs/getting-started
Column Codes: https://developer.n-able.com/n-able-cove/docs/column-codes
Construct a Call: https://developer.n-able.com/n-able-cove/docs/construct-a-json-rpc-api-call
Authorization: https://developer.n-able.com/n-able-cove/docs/authorization

📡 API — Vastgestelde werking

POST https://api.backup.management/jsonapi
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": "jsonrpc",
  "method": "Login",
  "params": {
    "username": "{{cove_api_username}}",
    "password": "{{cove_api_password}}"
  }
}

Response bevat:

visa — sessie token (meegeven in alle vervolg calls)
result.PartnerId — het partner ID (139124 voor MCC Automatisering)

Stap 2: EnumerateAccountStatistics

{
  "jsonrpc": "2.0",
  "visa": "{{visa}}",
  "id": "jsonrpc",
  "method": "EnumerateAccountStatistics",
  "params": {
    "query": {
      "PartnerId": 139124,
      "StartRecordNumber": 0,
      "RecordsCount": 250,
      "Columns": [
        "I1", "I18", "I8", "I78",
        "D09F00", "D09F09", "D09F15", "D09F08",
        "D1F00",  "D1F15",
        "D10F00", "D10F15",
        "D11F00", "D11F15",
        "D19F00", "D19F15",
        "D20F00", "D20F15",
        "D5F00",  "D5F15",
        "D23F00", "D23F15"
      ]
    }
  }
}

📋 Column codes — wat ze betekenen

Device info

Column	Betekenis	Type
`I1`	Device naam (intern, uniek)	String
`I18`	Computer naam (leesbaar) — leeg bij M365	String
`I8`	Klant naam	String
`I78`	Actieve datasources, bijv. `D01D02D10`	String

Datasource status (per datasource herhaalbaar)

Suffix	Betekenis	Type
`F00`	Status van laatste sessie	Int (zie tabel)
`F09`	Tijdstip laatste succesvolle sessie	Unix timestamp
`F15`	Tijdstip laatste sessie (ongeacht status)	Unix timestamp
`F08`	Color bar laatste 28 dagen (28 cijfers)	String

Status waarden (F00)

Waarde	Betekenis
`1`	In process
`2`	Failed ❌
`3`	Aborted
`5`	Completed ✅
`6`	Interrupted
`8`	CompletedWithErrors ⚠️
`9`	InProgressWithFaults
`10`	OverQuota
`11`	NoSelection (geconfigureerd maar niets geselecteerd)
`12`	Restarted

Datasources

Code	Naam	Gebruik
`D09`	Total (alle datasources gecombineerd)	Altijd aanwezig, beste voor overall status
`D1`	Files & Folders	Servers/workstations
`D2`	System State	Servers/workstations
`D10`	VssMsSql (SQL Server)	Servers met SQL
`D11`	VssSharePoint	Servers met SharePoint
`D19`	Microsoft 365 Exchange	M365 tenants
`D20`	Microsoft 365 OneDrive	M365 tenants
`D5`	Microsoft 365 SharePoint	M365 tenants
`D23`	Microsoft 365 Teams	M365 tenants

Let op: D02 en D03 zijn legacy codes — gebruik D10 en D11.

Device types herkennen via I78

I78 bevat waarden zoals D01D02, D01D02D10, D19D20D05D23
Leeg I18 veld = Microsoft 365 tenant
Gevuld I18 veld = server of workstation

D09F08 — Color bar decoderen

28 tekens, elk karakter = 1 dag (oudste eerst):

5 = Completed ✅
8 = CompletedWithErrors ⚠️
2 = Failed ❌
1 = In progress
0 = Geen backup

🏗️ Architectuur beslissing

Gekozen: Option 2 — Parallel Import System

API Poller → Cove API Parser → JobRun (direct, zonder MailMessage)

Rationale:

Schone scheiding van email- en API-gebaseerde imports
Geen misbruik van MailMessage model voor data zonder email context
Toekomstbestendig voor andere API-gebaseerde backup systemen

Database wijzigingen nodig

JobRun.source_type — nieuw veld: "email" of "api"
JobRun.external_id — Cove AccountId als externe referentie
JobRun.mail_message — moet nullable worden (of aparte tabel)

🔧 Implementatie fases

Phase 1: Database migratie

source_type veld toevoegen aan JobRun (email / api)
external_id veld toevoegen aan JobRun (voor Cove AccountId)
mail_message FK nullable maken voor API-gebaseerde runs
Migratie schrijven en testen

Phase 2: Cove API client

Nieuw bestand: app/services/cove_client.py
Login methode (visa token ophalen)
enumerate_account_statistics() methode
Paginatie afhandelen (RecordsCount / StartRecordNumber)
Token verloop afhandelen (opnieuw inloggen)
Error handling & retry logic

Phase 3: Data transformatie

Nieuw bestand: app/services/cove_importer.py
Settings lijst omzetten naar dict voor makkelijke lookup
Unix timestamps omzetten naar datetime
Datasource status mappen naar Backupchecks status (success/warning/failed)
Device type bepalen (server vs M365) via I18 en I78
JobRun records aanmaken per device

Phase 4: Scheduled polling

Cronjob of scheduled task (elke 15-60 minuten?)
Duplicate detectie op basis van external_id + tijdstip
Logging & audit trail
Rate limiting respecteren

Phase 5: UI aanpassingen

Job Details: geen "Download EML" knop voor API-gebaseerde runs
Indicatie dat job afkomstig is van Cove API (niet email)
28-daagse color bar eventueel tonen

Phase 6: Configuratie

Cove API credentials opslaan in SystemSettings
PartnerId configureerbaar maken
Polling interval instelbaar

🔑 API Credentials

API User: backupchecks-cove-01
User ID: 1665555
PartnerId: 139124
Role: SuperUser + SecurityOfficer
Portal: https://backup.management/#/api-users

BELANGRIJK: Token opslaan in password manager — kan niet opnieuw worden opgevraagd!

❓ Openstaande vragen voor implementatie

Hoe slaan we de Cove API credentials veilig op in Backupchecks? (SystemSettings? Environment variable?)
Wat is de gewenste polling frequentie? (15 min / 30 min / 1 uur?)
Willen we historische data importeren bij eerste run, of alleen nieuwe sessies?
Willen we de 28-daagse color bar (D09F08) tonen in de UI?
Ondersteunen we meerdere Cove accounts (meerdere MSPs)?

🎯 Success Criteria (MVP)

Backup status (success/warning/failed) per device zichtbaar in Backupchecks
Klant naam en device naam correct gekoppeld
Tijdstip laatste backup beschikbaar
Zichtbaar in Daily Jobs & Run Checks
Servers én Microsoft 365 tenants worden ondersteund
Geen duplicates bij herhaalde polling

Nice to Have

28-daagse history grafiek
Per-datasource status (SQL, Exchange, etc.)
Polling frequentie instelbaar per klant

8.1 KiB Raw Blame History