CMDB Developer Guide

CMDB — Developer Guide

The foundations: how a configuration item is modelled, why there are two entirely separate kinds of link, where the write rules actually live, and the rules you cannot break without breaking something else.

Read this before the feature guides. The siblings are Impact analysis (the blast radius) and Multi-tenancy (§7 here is a summary of it). The user-facing page is CMDB; the design doc and roadmap is docs/cmdb.md.

---

1. 📁 The files involved

Colour key: 🗄️ schema · ⚙️ engine · 🔌 API · 🖥️ UI · 🎨 CSS · 🌍 i18n · 🧪 tests · 📄 docs

🎨	File	What it does
⚙️	includes/services/cmdb.php	CmdbService — the shared write rules. Object create/update/delete and relationship create/delete. Both the UI endpoints and the REST API call it; it validates and writes, never emits HTTP
⚙️	includes/cmdb_impact.php	the blast radius + the three direct-impact buckets — see the impact guide
⚙️	includes/cmdb_audit.php	the data-quality checks
🗄️	database/freeitsm.sql	the 8 cmdb_* tables, their FKs, and the seeded relationship verbs
🗄️	includes/db_verify_schema.php	the same columns for the upgrade path. ⚠️ columns + PK only — UNIQUE keys and FKs are not generated from here
🔌	api/cmdb/save_object.php · delete_object.php	thin wrappers over CmdbService
🔌	api/cmdb/save_class.php · save_class_property.php · save_relationship_type.php (+ their delete_/get_ twins)	the admin surface. Not in the service layer — UI-only, see §4
🔌	api/cmdb/get_object.php · get_objects.php · search_objects.php	reads for the detail page, browse table and pickers
🔌	api/cmdb/get_object_impact.php · get_object_tickets.php · get_audit.php	the synthesis panels
🔌	api/cmdb/create_impact_diagram.php	the handoff to Network Mapper — turns a blast radius into a real diagram. Checks both module gates, see the impact guide §10
🔌	api/cmdb/generate_object_summary.php · ai_suggest_properties.php · ai_suggest_questions.php · _ai_helpers.php	the AI surface
🔌	api/cmdb/get_ai_settings.php · save_ai_settings.php · test_ai_key.php	provider / key / model, stored in system_settings under cmdb_ai_*
🔌	api/v1/resources/cmdb.php	REST v1. Mirrors the UI through the same service
🖥️	cmdb/index.php + browse.js	class sidebar + object table
🖥️	cmdb/object.php + object.js + options-editor.js	the detail page — inline editing, hierarchy, relationships, impact, activity, mini-graph
🖥️	cmdb/settings/index.php + settings.js + manifest.php	classes, properties, relationship types, AI
🖥️	cmdb/audit.php + audit.js	data quality
🖥️	cmdb/includes/header.php	the module nav — $current_page drives the active state
🖥️	cmdb/help.php	the in-module help guide — 14 sections with sticky scroll-spy nav
🌍	lang/en/cmdb.php + lang/pt-BR/cmdb.php	586 keys each, same commit

---

2. 🔑 Two kinds of link, and they are not interchangeable

This is the single most important thing to understand, and getting it wrong produces a model that looks fine and behaves badly.

Containment — cmdb_objects.parent_id. Ontological dependency: the child is part of the parent and cannot outlive it. A NIC in a server, a database on an instance. One parent, forming a strict tree.

Relationships — cmdb_object_relationships. A user-defined verb between two objects, both of which exist independently. depends on, connects to, hosted on. Many-to-many, no ownership implied.

The consequences are load-bearing:

• Deleting an object deletes its whole descendant subtree. That is correct precisely because parenthood means ontological dependency. Relationships are only unlinked, never followed into a delete.
• Impact travels down containment automatically, but along a relationship only if its type is configured to carry impact. A parent failing takes the children by definition; "A is managed by B" implies nothing.
• Parent assignment is cycle-checked (validateParent(), walking up to 100 hops); relationships are not, because a cycle of relationships is legitimate.

🔑 When in doubt, ask "if I deleted the parent, should this vanish?" Yes → containment. No → relationship.

There is a third, quieter kind: an object_ref property, which is a typed pointer at another object. It is a field, not a link — but the module treats it as a real connection for impact and for the audit, because in practice that is how a lot of estates record dependencies.

---

3. 🗄️ The data model

Eight tables. class_key and property_key are immutable once created; display labels are freely editable, so renaming never breaks a reference.

Table	Notes
cmdb_classes	a type of thing. class_key immutable, name editable
cmdb_class_properties	property definitions. property_type ∈ text / number / date / boolean / dropdown / object_ref; target_class_id only for object_ref; is_required; spreads_impact
cmdb_class_property_options	dropdown values with optional colour
cmdb_objects	instances. parent_id, is_planned, ai_summary, tenant_id
cmdb_object_properties	values, strongly typed — value_text / value_number / value_date / value_boolean / value_object_id, one populated per row
cmdb_relationship_types	the verb library. verb + inverse_verb + impact_direction
cmdb_object_relationships	edges. Unique on (from, to, type)
cmdb_icons	curated icon lookup

A ninth table, ticket_cmdb_objects, carries the ticket ↔ CI links. It is not cmdb_-prefixed because it belongs to neither module outright, and both ends are company-checked on write.

⚠️ Values are stored in typed columns, not a single stringly-typed one. A "blank" value therefore means all five columns are NULL — which is exactly what the audit's required-field check has to test for, and why op.id IS NULL OR (…all five IS NULL) is the correct emptiness test rather than = ''.

⚠️ Only cmdb_objects carries tenant_id. Classes, properties, options and relationship types are install-wide admin config; the child tables inherit their company through their object.

---

4. ⚙️ Where the write rules live, and what deliberately isn't there

CmdbService owns objects and relationships — the parts that genuinely have two callers (the UI endpoints and REST v1). It takes an ActorContext plus canonical input, validates, writes, and throws ServiceError. It never emits HTTP.

Deliberately outside the service:

• Classes, property definitions and relationship types — UI-only admin settings. REST exposes classes and relationship types read-only, so there is no second writer to keep in step.
• CMDB ↔ ticket links — API-only, with no UI twin.

Extracting those would add indirection with nothing on the other side of it. 🔑 The rule is "share what has two callers", not "share everything".

The service accepts two property input shapes and normalises both: properties as a {property_key: value} map (REST's canonical form) and property_values as an id-addressed list (what the UI's inline editors send). Entries whose property_id isn't in the class are dropped rather than rejected, matching the UI's original behaviour.

Canonical behaviour, wherever the write came from: class is immutable after creation; parents are cycle-checked; required properties are enforced on create but only on touched properties on update (so inline editing one field doesn't fail on an unrelated blank); and every value is validated per type — numbers numeric, dropdowns against the option list, dates parsed, object_ref checked for existence, target class, and no self-reference.

---

5. ⚠️ Delete is explicit, not a foreign-key cascade

deleteObject() removes the descendant tree by hand: nulls inbound object_ref values, deletes properties, cleans Network Mapper nodes and connectors, deletes relationships both directions, removes ticket links, then deletes the objects.

🔑 It does not rely on FK cascades, because they may not exist. Installs grown through Database Verification have no CMDB foreign keys at all — db_verify_schema.php generates columns and primary keys, not FKs. Any cleanup that trusts a cascade works on a fresh freeitsm.sql install and silently leaves orphans on an upgraded one.

That asymmetry is worth holding onto generally: a fresh install and a Verify-grown install are not the same database. It is why the audit's broken-reference check can never fire on a fresh install and matters on an upgraded one.

---

6. 🔒 Capabilities

Four, in includes/capabilities.php:

Capability	Gates
cmdb.manage	umbrella
cmdb.classes	the CI schema itself — classes and property definitions
cmdb.relationship_types	the verb library
cmdb.ai	AI provider + API key

Every endpoint additionally calls requireModuleAccessJson('cmdb'). Settings tabs are filtered through settingsManifestFor('cmdb'), so a tab an analyst may not see is never rendered rather than merely hidden.

---

7. 🔒 One company per CI, and no shared CIs

Configuration items are company-scoped and — unlike knowledge articles — there is no "shared with everyone" CI. That one decision drives the rest:

• a CI's parent, its relationships and every object_ref property must point within the same company;
• the rule binds staff who can access every company too. A permission check alone would not stop them — they can legitimately reach both sides — and a cross-company link is a side channel even when the far CI is unreadable, because you can still confirm it exists;
• a CI outside scope is reported as not found, never forbidden, so the app never confirms it exists.

⚠️ NULL tenant_id means the default company's, not "shared". On a single-company install every row is NULL, so any comparison must resolve NULL to the default company id first or it matches nothing.

⚠️ Moving a CI between companies is deliberately not possible. Tickets and changes have it; a CI sits in a tree with links hanging off it, so a move must decide the fate of its parent, children and every relationship — and either default is wrong. A misfiled CI is deleted and recreated.

---

8. 🤖 The AI surface

Two features, both using the module's own provider/key (separate from Knowledge, Forms, Workflows — deliberately, for per-feature billing visibility). Configured through get_ai_settings.php / save_ai_settings.php / test_ai_key.php and the shared AI Providers panel:

• Object summary (generate_object_summary.php) — 2–3 sentences, cached on ai_summary + ai_summary_generated_at so page views cost nothing. The prompt is locked down to factual prose: no speculation, no markdown, no bullets.
• Suggest properties (ai_suggest_questions.php → ai_suggest_properties.php) — a two-stage wizard that asks clarifying questions first, then proposes properties. Auto-creates a missing target class when it suggests an object_ref.

⚠️ docs/cmdb.md lists a third, suggest a relationship, that was never built — there is no endpoint for it. If you are working from the design doc, check api/cmdb/ before assuming a feature exists.

🔑 The AI reads your vocabulary directly. Class names, property labels and relationship verbs go straight into the prompts, which is why the design doc insists on plain English (depends on, not DEP). Obscure abbreviations would force a glossary layer later.

---

9. 🧪 Verifying a change here

• Test the service, not the endpoint. CmdbService is where the rules are; a fixture-driven test against it in a rolled-back transaction covers both callers at once.
• ⚠️ A fresh install and a Verify-grown install differ in their foreign keys. If your change relies on referential integrity, decide which one you are relying on, and reproduce the other shape in a fixture (SET FOREIGN_KEY_CHECKS = 0) rather than assuming.
• ⚠️ Pair every "cannot do X across companies" test with a positive control — a same-company case that must succeed. A blanket failure passes the negative half perfectly.
• ⚠️ Check EN/pt-BR key parity in the same commit. An EN-only key falls back silently; nothing errors.
• ⚠️ Rendered markup does not prove the JS parses. Parse-check in headless Chrome with a deliberately broken file as a negative control.

---

10. ⬜ Known gaps

⚠️ docs/cmdb.md is a design doc, not a status report. It was written before the build and describes intent; divergences are tagged there but this list is the reliable one.

• No tree view. docs/cmdb.md UX principle 7 promises two browse modes; only the flat per-class list exists. Hierarchy navigation happens on the detail page instead (breadcrumb, children cards, mini-graph), which has covered the need so far.
• No "suggest a relationship" AI feature — designed in the doc, never built. See §8.
• No class inheritance. Classes are flat by design in v1; docs/cmdb.md V2 §2 sketches an optional parent_class_id.
• No versioning of property values — there is no history of what a CI used to say.
• No discovery/sync into the CMDB. vCenter, Intune and the asset scripts feed Assets, not this module.
• No CSV import. Only the demo-data importer exists. Probably the single biggest adoption blocker.
• Foreign keys are unguarded on Verify-grown installs — see §5.