CMDB

Overview

The Configuration Management Database (CMDB) stores configuration items (CIs) — every component of your IT infrastructure and the relationships between them. CIs can be hardware, software, services, applications, network devices, or any abstraction you choose to track. The CMDB powers topology visualisation, impact analysis, change risk assessment, and incident enrichment.

CI Classes

CIs are organised into classes. Each class defines the attributes available on that CI type. FlowOS ships with the following built-in classes:

Base CI Fields (all classes)

Class-Specific Attributes

server / virtual_machine

database

certificate

Relationship Types

Relationships connect CIs in the topology graph. Each relationship has a type and a direction.

Hardware, Network & Compliance Fields

Beyond the base fields, every CI (regardless of class) carries a set of hardware, network, data-centre and monitoring/compliance attributes directly on the record — these are plain schema fields, not entries in the free-form attributes bag.

Network & hardware

Data centre & virtualisation

Monitoring & compliance

CI Lifecycle Transition Validation

CIs use a 9-state lifecycle: ordered · installed · configured · active · maintenance · inactive · decommissioning · retired · disposed. A model-level hook enforces which transitions are legal:

Any other transition is rejected with an error of the form Invalid lifecycle transition: active → ordered. Allowed: maintenance, inactive, decommissioning, retired, and the save fails — the status change is not persisted.

CMDB Data Quality Score

Each CI carries a computed dataQualityScore (0–100) that reflects how complete its record is. The score is a weighted sum over 18 fields — a field counts as “present” if it is not null, undefined, an empty string, or 0:

The earned weight divided by the total (100) is rounded to the nearest integer and stored on dataQualityScore.

CI Configuration Compliance

Baseline & drift detection for CI configuration, gated behind the feature_ci_compliance flag. A baseline captures the expected value of one or more fields, scoped to either specific CIs (ciIds) or an entire CI class (ciClass). Baselines can be typed by hand or captured from a live CI via snapshotFromCiId.

Running POST /compliance/baselines/:id/scan loads every CI in scope and, for each one, compares the live value of each field named in the snapshot against the expected value (via a JSON string comparison). Any mismatch is recorded as a { field, expected, actual } drift entry. If a CI has one or more drifted fields its status is drifted, otherwise compliant — and the scan writes that result straight back onto the CI's complianceStatus field (non_compliant / compliant). Drift results are upserted per (baseline, CI) pair, so re-running a scan updates the existing record rather than duplicating it.

A drift item can be marked remediated via POST /compliance/drift/:id/remediate — this only changes the drift record's status (and records who/when); it does not modify the CI or re-scan it.

POST /api/cmdb/compliance/baselines
{
  "name": "Prod DB baseline",
  "ciClass": "database",
  "snapshotFromCiId": "665f1...",
  "snapshot": { "osVersion": "", "patchGroup": "", "backupEnabled": "" }
}

Software Asset Management (SAM)

SAM, gated behind feature_sam, is a set of read-mostly views built on top of the existing InstallBase collection (see Install Base below) filtered to assetClass in software/license. It does not introduce a new storage model.

CI ↔ ITSM Linking

Bidirectional linking between CIs and Incidents, Changes, and Problems. Attaching or detaching a CI on either side re-resolves the record's business-service linkage (via the CMDB impact-linkage service) so that businessServiceId/impactedServiceIds stay in sync with the current set of affected CIs.

• •Incident — primary ciId plus an affectedCiIds array.
• •ChangeRequest — affectedCiIds array plus derived impactedServiceIds.
• •Problem — a single rootCauseCiId plus an affectedCiIds array.

A combined view is available per CI at GET /cis/:id/affected-records, returning all non-closed incidents, changes, and problems that reference it (as primary, root cause, or affected CI).

Alert Storm Suppression

When a CI has autoCreateIncident enabled (or the tenant default is on) and its health status changes to down or degraded, FlowOS auto-creates an incident — but repeated flapping shouldn't flood the queue with duplicate incidents. Alert suppression windows prevent that:

1. 1

   A health update arrives (manual PATCH/POST /cis/:id/health, or an external monitoring push to POST /monitoring/push) with a new status of down or degraded.

2. 2

   FlowOS checks for an AlertSuppression record for that CI with status: 'active' whose startedAt falls within the last ci.suppressionWindowMinutes (default 5) minutes.

3. 3

   If one is found, the alert is suppressed: suppressedCount and alertCount are incremented and lastAlertAt is updated — no new incident is created.

4. 4

   If none is found, a new incident is created (priority critical for down, high for degraded), and — if ci.maxAlertsBeforeSuppress (default 3) is greater than 0 — a fresh AlertSuppression window is opened, linked to that incident.

Install Base — Asset Inventory

The InstallBase collection tracks individual hardware, software, cloud, virtual, and license assets — separate from (but optionally linked to) a CMDB CI via ciId. It carries financial, lifecycle, assignment, and ITSM-linkage detail that doesn't belong on the CI record itself.

GET /install-base accepts status, type/assetClass, and customerId filters, plus two added for cross-linking asset views into other record types: ciId (powers the “Assets” tab on a CI detail page) and assignedUserId (powers an “Equipment” tab on an employee/user detail page).

Depreciation & Expiry Jobs

Asset Depreciation Calculator

Runs monthly (1st of the month at 02:00 UTC — checked every 15 minutes, guarded so it fires once per month). It recalculates currentValue on CmdbCi records (not InstallBase records) that have depreciationMethod of straight_line or declining_balance, a status other than retired/disposed, purchaseCost > 0, and a purchaseDate.

ageYears = (now - purchaseDate) / 365.25 days
depYears = ci.depreciationYears ?? 5

straight_line:
  annualDepreciation = purchaseCost / depYears
  newValue = max(0, purchaseCost - annualDepreciation * ageYears)

declining_balance (double-declining):
  fixedRate = 2 / depYears
  newValue = max(0, purchaseCost * (1 - fixedRate) ^ ageYears)

The result is rounded to 2 decimal places and written to currentValue only if it differs from the stored value by more than $0.01.

Asset Expiry Check

Runs daily at 09:00 UTC across every active tenant (also invocable on demand as cron script cmdb_install_base_expiry_check). It scans non-retired/disposed InstallBase records whose licenseExpiry, warrantyExpiry, or contractExpiry falls within the next 30 days.

For each matching record, recipients are the asset's assignedUserId plus, if it is linked to a CI, that CI's ownerId and technicalOwnerId. A system notification is created per recipient for each of the license/warranty dates that is actually within the window — type asset_expiry_critical if ≤ 7 days out, otherwise asset_expiry_warning — with a title, body, and meta: { assetId, expiryType, daysUntilExpiry }.

API Quick Reference

CI Compliance

Software Asset Management

CI ↔ ITSM Linking

Health & Alert Suppression

Install Base