Designing your CMDB

🧱 Designing your CMDB

For #313 · Module page: CMDB

This page is for someone setting up the CMDB for their team and wondering where to start: what should be a configuration item and what should only be an asset, how many classes to make, and what properties to give them. It ends with a starter set of classes you can copy.

None of it is a rule. The CMDB will take whatever shape you give it - this is the shape I would start with, and why.

---

Assets and configuration items

A server is usually two records in FreeITSM, and they answer different questions.

	The asset (Assets)	The configuration item (CMDB)
Says	What the box is	What it does, and what depends on it
Holds	Make, model, serial number, asset tag, status, location, what the inventory agent last saw	Its role, owner, support team, environment, what runs on it, what breaks if it fails
Used for	Inventory, warranty, handover, audits	Changes, incidents, "if this failed"

The asset is the box. The CI is what it does and what depends on it.

You don't have to type the hardware twice. A CI can be linked to one asset - the same piece of equipment - and its Asset card then shows the asset's type, make and model, serial number, asset tag, status, location and inventory freshness, read live from the asset and labelled From the asset. Nothing is copied into the CI, so there is nothing to keep in step: to change the serial number, change the asset.

To make that the normal path rather than a chore:

1. Assets → Settings → Asset types → (a type) → CMDB class - choose the class each asset type becomes: Server for servers, Laptop / desktop for laptops. Choosing a class creates nothing by itself and changes nothing on existing assets. It only makes the next button appear.
2. On an asset of that type with no CI yet, the Configuration item card offers Create linked CI. It first lists any unlinked CI of that class in the same company with the same name, in case one already exists (Link this one instead); otherwise you name the new CI, fill in anything the class requires, and Create makes the CI and the link together.

Leave the CMDB class as None for types that will never be a CI, and untick Configuration item in that type's Layout to hide the card altogether. The full story is in Linking an asset to its configuration item.

The link says same equipment, nothing more. It never spreads impact - what depends on what is recorded inside the CMDB, as below.

---

What to put in the CMDB

The test I use: would a change to it, or a failure of it, matter to a service someone relies on? If yes, it belongs in the CMDB. If it only matters that you know where it is and who has it, it is an asset and that is enough.

Usually in:

• Services - what people actually use and would ring you about: email, payroll, the website, the phone system
• Applications - the software behind those services
• Servers and virtual machines
• Databases
• Network kit - firewalls, core switches, wireless controllers, internet links
• Laptops and desktops - only if you track their operating system or software, or link them to tickets
• Subscriptions - the SaaS and licences a service depends on

Usually out (assets only, or nothing at all): mice, keyboards, headsets, monitors, docking stations, cables, spare kit in a cupboard.

Start with the services and work down. A CMDB with ten services and what they really run on is more use than one with four hundred laptops and nothing connecting them.

---

Classes

A class is a kind of thing - Server, Database, Service. Every CI has one, and the class decides which properties it has. They live in CMDB → Settings → Classes.

Keep them few and generic. A class should describe a kind of thing, not a brand, a site or a customer. One Server class with an Operating system dropdown beats Windows Server, Linux Server and Dell Server. For a small estate, one Service class covering email, monitoring and file shares beats a dozen narrow ones - split later if you genuinely need different properties.

Never put a company name in a class. On an install with more than one company, classes, their properties and relationship types are shared by every company; it is the CIs that belong to a company. Acme Server is a class every company will see. Make one Server class and let each company's servers belong to that company.

Property, parent or relationship?

Once you have a few classes, the question is how to say two things are connected. There are three ways, and the in-app help calls this the single most common question:

Use	When	Examples
A property	The link is single, named, and part of what this thing is	Owner, Support team, Host server
A parent	The child cannot exist without the parent. Deleting the parent deletes the children	Database → SQL instance → Server
A relationship	Anything else - many-to-many, verb-driven, often optional	depends on Active Directory, monitored by the monitoring tool, replicates to the DR site

Use parent sparingly. Delete cascades all the way down, and a parent is only right when the child is meaningless without it. A virtual machine is not the child of its host - it can move to another host and still be the same VM - so it gets a Host property or a relationship instead.

Don't record the same link twice. If a database has a Host server property pointing at SQLSVR01, it doesn't also need a depends on SQLSVR01 relationship.

---

Properties

A property is a field on a class. Every CI of the class gets the same set. Click the property-count badge on a class in Settings → Classes to manage them, or open the ⚙ cog on any field of a CI.

What to record

Record what someone will use - to find the thing, to decide who to call, to judge how bad an outage is, to plan a change. Five or six properties per class is plenty to start. You can add more when someone asks for them, and Suggest with AI in the properties manager will ask about your environment and propose more.

Leave out anything the asset already holds. The serial number, model and location of a server are on its asset and shown on the CI through the link.

Naming

Use plain words: Host server, not hostsrv; Support team, not SUP_TM. Labels are what analysts see, and they feed the AI summary and suggestions too. A label can be renamed at any time - the property's key never changes, so stored values are safe.

Required - sparingly

A Required property must be filled before a CI can be created. Use it only for what a CI is useless without. A CI with most fields blank is still useful; a CMDB analysts avoid because every create is a form-filling exercise is not. If you make something required later, Data quality lists the CIs created before that are missing it.

Choosing the type

Type	Use for
Dropdown	Anything with a short, known list: environment, criticality, status, operating system. Searchable, filterable, and consistent - Production is always spelled the same. Each option can have a colour, shown as a coloured pill, and a Criticality dropdown also colours the CI's header
Text	Genuinely free values: version numbers, an IP address, hours of service
Number	Things you will compare: seats, CPU count. Filters offer is at least and is at most
Date	Renewal dates, end of support. Filters offer on or before and on or after
Yes/No	A single fact: Backed up, Encrypted, Managed
Person, Analyst, Team, Location, Company, Supplier, Contract	Someone or something FreeITSM already holds - see below
Object Reference	Another CI: a VM's host, an application's database

If you catch yourself typing the same five words into a text field, it should be a dropdown.

People, teams and places are records, not classes

Don't make a Person, Team, Site or Vendor class and keep CIs for them by hand. Since 5.3.0 a property can point at the real record (the Points at a record group in the type list):

Type	Points at
Person	someone in People, from the CI's own company
Analyst	an analyst - and the CI shows up in that analyst's leaving checks
Team	a team
Location	a place from System → Locations, shown as a full path
Company	any company you can reach - for example a client's server Maintained by your own company
Supplier	a supplier
Contract	a contract from the CI's own company

The CI always shows the record's current name, with a link where it has a page. Rename a team and every CI says the new name. More in Properties that point at real records.

Object references and "This is a dependency"

An Object Reference property points at another CI of a class you choose - Host on a Virtual machine points at a Server. When a failure of the thing it points at would take this one down, tick This is a dependency on the property. Then If this failed on the server lists the VM, and the VM's own dependants after it. Without the tick the link is shown but the blast radius quietly misses it, and Data quality lists ticked properties left empty under Dependencies not filled in.

Relationship types and which way failure travels

Relationships use verbs from Settings → Relationship types. Each has a verb and its inverse (depends on / is depended on by), and a When something fails setting:

• B fails → A is affected - for depends on, runs on: when the thing depended on fails, the thing that depends on it is affected
• A fails → B is affected - for verbs written the other way round, such as hosts
• Nothing else is affected - for links that say where something sits or who looks after it, such as managed by, so a server failing doesn't claim to affect the building

A new install has three: depends on (carries impact), connects to and managed by (don't). I'd add runs on / hosts with B fails → A is affected for applications and databases on servers.

---

A starter set

Here is a set of classes I would start with. It is a starting point, not a standard to comply with - rename, drop or add to it freely. Required is left off everything on purpose.

Class	Properties
Service	Service owner (Person) · Support team (Team) · Criticality (Dropdown: Critical, High, Medium, Low) · Status (Dropdown: Live, Being retired, Retired) · Hours of service (Text)
Application	Business owner (Person) · Technical owner (Analyst) · Support team (Team) · Vendor (Supplier) · Support contract (Contract) · Version (Text) · Environment (Dropdown: Production, Test, Development)
Server	Role (Text) · Operating system (Dropdown) · Environment (Dropdown) · Location (Location) · Support team (Team)
Virtual machine	Host (Object Reference → Server, This is a dependency) · Operating system (Dropdown) · Environment (Dropdown) · Support team (Team)
Database	Engine (Dropdown: SQL Server, MySQL, PostgreSQL...) · Version (Text) · Environment (Dropdown) · Backed up (Yes/No) · Support team (Team)
Network device	Device type (Dropdown: Firewall, Switch, Router, Wireless) · Location (Location) · Management IP (Text) · Firmware version (Text) · Support contract (Contract)
Laptop / desktop	Primary user (Person) · Operating system (Dropdown) · Encrypted (Yes/No) · Location (Location)
Mobile device	Primary user (Person) · Platform (Dropdown: iOS, Android) · Managed (Yes/No) · Phone number (Text)
Subscription	Vendor (Supplier) · Contract (Contract) · Seats (Number) · Renewal date (Date) · Owner (Person)

Notice what isn't there: no serial numbers, models or warranty dates. For Server, Laptop / desktop, Mobile device and Network device those live on the asset, and the CI shows them through the link - map those asset types to these classes and use Create linked CI.

How they connect

From	Link	To
Service	depends on	Application (and Subscription, for a SaaS service)
Application	runs on	Server or Virtual machine
Application	depends on	Database
Database	runs on	Server or Virtual machine
Virtual machine	Host property (a dependency)	Server
Server	connects to	Network device

Draw these and If this failed on a server will walk up the chain: the VMs on it, the databases and applications on those, and finally the service your users notice. connects to doesn't carry impact out of the box; if a core switch failing should show what goes down with it, use depends on for that link instead.

---

Let FreeITSM build it for you (5.3.0)

You don't have to type the set above in by hand:

• Starter classes - CMDB → Settings → Classes → Starter classes previews the set above and adds it, with the runs on and is part of relationship types - only the classes and properties you don't already have. Nothing already there is changed.
• The CMDB assistant - Assistant in the CMDB header interviews you about your organisation - your services, what they run on, where, what you want to track - remembers what it learns for each company so the next conversation carries on, and proposes classes, properties and relationship types and then the CIs themselves. It follows the advice on this page: few, general classes, records rather than Person or Site classes, and never a class named after a company.

Either way, nothing is created until you have seen a preview of exactly what will be added, then it is applied with one click.

---

Common mistakes

Mistake	Why it hurts	Instead
A class per company (Acme Server, Globex Server)	Classes are shared by every company, so every company sees every other one's class names	One Server class; each CI belongs to its company
A class per manufacturer or OS (Dell Server, Linux Server)	Same properties copied many times, and a list split for no reason	One class with a Manufacturer on the asset, or an Operating system dropdown
Everything required	Creates become a chore and analysts stop using the CMDB	Required only for what a CI is useless without - usually nothing
Free text where a dropdown or record belongs	Prod, Production and live are three answers to one question; a typed owner's name goes stale	A dropdown for known lists; a Person, Team, Location or Supplier property for people and places
Person, Team or Site classes	A second copy of people and places to keep in step by hand	Record properties that point at the real ones
Relationships stored as text ("Runs on: SQLSVR01" in a text field)	Nothing links, nothing is clickable, and the blast radius can't follow it	An Object Reference property with This is a dependency, or a relationship
The same link twice	A property and a relationship for one connection; they drift apart	One or the other
Copying hardware details into the CI	Two serial numbers that eventually disagree	Link the asset; the CI reads them live

---

Related pages

• CMDB · Linking an asset to its configuration item · Locations · Assets
• CMDB - Developer Guide · Record references - Developer Guide