PSA/docs/superpowers/specs/2026-06-09-levelio-rmm-integration-design.md

# Level.io RMM Integration — Design

**Date:** 2026-06-09
**Status:** Approved
**Provider key:** `levelio` · **Display name:** Level · **Edition:** EE-only · **Feature flag:** `levelio-rmm-integration`

## Summary

Add a Level.io RMM integration to Alga PSA, modeled on the existing NinjaOne/Tanium EE
integrations, with Temporal-first sync execution. v1 scope: connection management, Level
group → Alga client mapping, device/asset sync with cached live data, pending-patch counts
from Level's updates endpoint, alerts backfill, and an inbound alert webhook. No new
database tables or migrations — all RMM tables are provider-agnostic.

## Level API facts (v2 REST)

- Base URL fixed at `https://api.level.io` (SaaS; no per-instance URL).
- Auth: static API key sent in the `Authorization` header.
- Pagination: cursor-based (`starting_after`, `limit` 1–100, `has_more`).
- Resources used: `/v2/groups` (hierarchical; the org-mapping unit), `/v2/devices` (rich
  hardware/OS/security detail via `include_*` query flags; `role` of
  workstation/server/domain_controller; `online`, `last_seen_at`, `last_reboot_time`),
  `/v2/alerts` (severities information/warning/critical/emergency; active/resolved),
  `/v2/updates` (OS patch inventory, `status=available|installed`).
- Not available in the API: software inventory, remote access links, device control
  (reboot/run script), webhook registration. Level → Alga webhooks are configured manually
  in Level's automation builder as an HTTP POST action.
- Device list supports `group_id` (direct children) and `ancestor_group_id` (recursive)
  filters; the API has no modified-since filter, so there is no incremental sync.

## Architecture

### Identity & registration

Registration touchpoints (all additive):

| File | Change |
|---|---|
| `packages/types/src/interfaces/asset.interfaces.ts` | Add `'levelio'` to `RmmProvider` union |
| `ee/server/src/interfaces/rmm.interfaces.ts` | Add `'levelio'` to `RmmProvider` union |
| `packages/assets/src/actions/inboundActions.ts` | Add to `KNOWN_RMM_PROVIDERS` |
| `packages/integrations/src/lib/rmm/providerRegistry.ts` | New registry entry; extend `icon` and `featureFlagKey` unions and `RmmProviderAvailabilityContext` |
| `packages/integrations/src/components/settings/integrations/RmmIntegrationsSetup.tsx` | Banner icon case, `useFeatureFlag('levelio-rmm-integration')`, dynamic import of EE settings component, `providerSettingsComponents` entry |
| `packages/assets/src/lib/rmmProviderDisplay.ts` | Display name/icon |
| `ee/server/src/components/workflow-designer/WorkflowDesigner.tsx` | Provider icon |
| `packages/types/src/interfaces/rmmProvider.typecheck.test.ts` | Extend typecheck |

Registry entry: `requiresEnterprise: true`, `featureFlagKey: 'levelio-rmm-integration'`,
capabilities `{connection: true, scopeSync: true, deviceSync: true, events: true,
remoteActions: false}`.

### Auth & secrets

Tenant secrets via the secret provider: `levelio_api_key` (entered by the user) and
`levelio_webhook_secret` (generated server-side on first save). The `rmm_integrations` row
uses `provider = 'levelio'`, `instance_url = 'https://api.level.io'`.

### API client

`ee/server/src/lib/integrations/levelio/levelApiClient.ts`

- `LevelIoApiClient`, fetch-based, with a `listAll` cursor-pagination helper (limit 100).
- Methods: `listGroups()`, `listDevices({groupId?, ancestorGroupId?})` with all `include_*`
  detail flags enabled, `getDevice(id)`, `listAlerts({deviceId?, status?})`,
  `resolveAlert(id)`, `listUpdates({deviceId?, status?})`, `testConnection()`
  (`GET /v2/groups?limit=1`).
- Error mapping with user-facing hints: 401 → invalid API key, 429 → rate limited (respect
  `Retry-After`, bounded retries), HTML/non-JSON body → clear error.
- `createLevelIoClient(tenantId)` factory reads secrets; importable by both server actions
  and the Temporal worker (worker resolves `@ee/*` → `ee/server/src/*`).
- Local types for the response subset we consume: `LevelIoGroup`, `LevelIoDevice`,
  `LevelIoAlert`, `LevelIoUpdate`.

### Group → client mapping

- Scope sync lists all groups and upserts them into `rmm_organization_mappings`
  (`external_organization_id` = group id, name, parent group id in mapping metadata so the
  UI can render hierarchy paths such as "Acme Corp / Branch Office").
- Any group may be mapped to a client. During device sync each device is assigned to its
  **deepest mapped ancestor group**: fetch all groups once, build a parent map, walk each
  device's group chain upward to the nearest mapped group. Deterministic when both a parent
  and child are mapped. Devices with no mapped ancestor are skipped.
- One full device sweep per sync (no per-mapping API queries).

### Sync engine (single source of truth)

`ee/server/src/lib/integrations/levelio/sync/syncEngine.ts` — exported functions called by
both the direct transport and Temporal activities (NinjaOne worker pattern; no duplicated
logic):

- `runLevelIoScopeSync(tenantId, integrationId)` — groups → org mappings.
- `runLevelIoFullSync(tenantId, integrationId, options)` — full device sweep with detail
  includes → `ingestNormalizedRmmDeviceSnapshot` (shared service); then one sweep of
  `/v2/updates?status=available` grouped by `device_id` to fill `pending_os_patches`;
  updates `last_full_sync_at`.
- `runLevelIoDeviceSync(tenantId, integrationId, deviceId)` — single-device refresh
  (device + its available updates).
- `runLevelIoAlertsBackfill(tenantId, integrationId)` — active + resolved alerts upserted
  into `rmm_alerts` keyed on `(tenant, integration_id, external_alert_id)`.

Engine emits `RMM_SYNC_STARTED/COMPLETED/FAILED` (and device-level
`RMM_DEVICE_CREATED/UPDATED`) via the Redis stream client, so events fire identically under
both transports. DB access via `getAdminConnection()`.

### Device → snapshot mapping

`ee/server/src/lib/integrations/levelio/mappers/deviceMapper.ts` →
`NormalizedRmmExternalDeviceSnapshot`:

- Asset type: `role` server/domain_controller → `server`; workstation or null →
  `workstation`.
- Display name `nickname ?? hostname`; serial number; `online` → agent status
  online/offline; `last_seen_at` → lastSeenAt; city/country → location.
- Extension: `platform` → osType; `operating_system` → osVersion; `last_logged_in_user` →
  currentUser; uptimeSeconds computed from `last_reboot_time` (only while online);
  `last_reboot_time` → lastRebootAt; lanIp = first private IPv4 found on a non-virtual
  interface (interfaces whose description contains "virtual" are skipped; null if none); `cpus` →
  cpuModel/cpuCores; `total_memory` bytes → ramGb; `disk_partitions` → diskUsage
  (mount point/label, total/free GB, utilization); `security.antivirus_provider/status` →
  antivirus fields; pendingOsPatches from the updates sweep.
- `systemInfo` carries manufacturer, model, security_score, risk, maintenance_mode, tags,
  flag, group id.
- Alert severity: emergency → critical, critical → major, warning → moderate,
  information → minor.

### Temporal-first execution

- `ee/temporal-workflows/src/workflows/levelio-sync-workflow.ts`:
  `levelIoSyncWorkflow({tenantId, integrationId, syncType: 'organizations' | 'full' |
  'alerts', options})` and `levelIoDeviceSyncWorkflow({tenantId, integrationId, deviceId})`.
  Activity proxy options follow NinjaOne: `startToCloseTimeout: '1h'`,
  `heartbeatTimeout: '2m'`, retry max 2 attempts.
- `ee/temporal-workflows/src/activities/levelio-sync-activities.ts`: thin wrappers that
  import the sync engine via `@ee/*` and invoke it.
- Register both in `workflows/non-authored-index.ts` and `activities/non-authored-index.ts`.
  Task queue: `TEMPORAL_JOB_TASK_QUEUE` (default `alga-jobs`).
- Server actions route through the existing `runRmmSyncWithTransport()`
  (`ee/server/src/lib/integrations/rmm/sync/syncOrchestration.ts`) with **both executors
  implemented**. Transport resolution for this provider: `LEVELIO_SYNC_TRANSPORT` →
  `RMM_SYNC_TRANSPORT` → default **`temporal`** (Temporal-first; the direct executor remains
  for local development). Workflow IDs: `levelio:<op>:<tenant>:<integration>:<timestamp>`.

### Server actions

`ee/server/src/lib/actions/integrations/levelIoActions.ts` — `'use server'`, every action
wrapped in `withAdvancedAssetsAccess` (Tanium pattern):

`getLevelIoSettings`, `saveLevelIoConfiguration` (validates the key with a live test call
before persisting; generates webhook secret on first save), `testLevelIoConnection`,
`disconnectLevelIoIntegration` (deactivates row, removes secrets, publishes
`INTEGRATION_DISCONNECTED`), `syncLevelIoOrganizations`,
`listLevelIoOrganizationMappings`, `updateLevelIoOrganizationMapping`,
`triggerLevelIoFullSync`, `backfillLevelIoAlerts`, `syncLevelIoSingleDevice`,
`getLevelIoWebhookInfo`, `getLevelIoConnectionSummary`.

### Inbound webhook

`server/src/app/api/webhooks/levelio/route.ts` (Tactical pattern):

- `POST {baseUrl}/api/webhooks/levelio?tenant=<tenant>` with header
  `X-Alga-Webhook-Secret` checked against `levelio_webhook_secret`.
- Users configure this manually as an HTTP POST action in a Level automation; the settings
  UI documents a recommended JSON payload template:
  `{event, alert_id, device_id, hostname, name, severity, description}` where `event` is
  `alert.triggered` or `alert.resolved`.
- Handler: verify secret → upsert `rmm_alerts` → resolve asset via
  `tenant_external_entity_mappings` → publish `RMM_WEBHOOK_RECEIVED` → fire-and-forget
  single-device sync (start the Temporal workflow without awaiting the result; direct
  best-effort fallback when transport is direct). The webhook response never blocks on sync.

### Settings UI

`ee/server/src/components/settings/integrations/LevelIoIntegrationSettings.tsx`, modeled on
`TaniumIntegrationSettings`: API key entry; test/save/disconnect; sync buttons (groups,
devices, alerts backfill); org-mapping table with hierarchical group paths and client
dropdown; webhook info card with copyable URL/secret and Level automation setup
instructions; connection summary counts. Dynamic-imported from `RmmIntegrationsSetup` via
`@enterprise/components/settings/integrations/LevelIoIntegrationSettings`.

## Error handling

- Client: 401 → "invalid API key" hint surfaced in the settings UI; 429 → bounded retry
  honoring `Retry-After`; malformed/HTML responses → explicit error.
- Sync: per-device ingestion failures are counted (`items_failed`) and logged without
  aborting the sweep; sync-level failures emit `RMM_SYNC_FAILED` and set
  `sync_status = 'failed'` on the integration row.
- Webhook: bad tenant/secret → 400/401; unparseable payloads → 400 with no side effects;
  device-sync kick-off failures are swallowed (alert upsert already committed).

## Testing

Unit tests beside the existing ones in `ee/server/src/__tests__/unit/integrations/`:

- Device mapper: role → asset type, disk partition → diskUsage conversion, uptime from
  last reboot, severity mapping, null-heavy devices.
- Deepest-mapped-ancestor group assignment (parent+child mapped, unmapped device skipped).
- Client: cursor pagination, 429 retry, 401 error hint (mocked fetch).
- Transport resolution: env precedence and the `temporal` default for levelio.
- Extend `rmmProvider.typecheck.test.ts` for the new union member.

## Out of scope (v1)

- Alert → ticket rules engine (currently NinjaOne-specific).
- Remote actions / script execution / triggering Level automations
  (`POST /v2/automations/webhooks/{token}`).
- Software inventory (not exposed by Level's API).
- Incremental sync (no modified-since filter in the API).
- Resolving Level alerts from Alga (`POST /v2/alerts/{id}/resolve`) — easy follow-up.
- Custom field sync (`/v2/custom_fields`).