How to Add Custom Fields to a Class in iTop (CMDB)

— ny_wk

iTop's data model ships with sensible defaults, but every organization tracks something the stock fields don't cover — a warranty date, an access method, a patch history. The right way to add those isn't hacking the core; it's building a small extension that adds your fields to a class cleanly and survives upgrades. Here's how to do it properly, using extra fields on the Server class as the example.

Why an extension, not a core edit

It's tempting to edit iTop's built-in datamodel files directly. Don't. iTop upgrades overwrite core files, so your changes vanish on the next update. An extension module lives in extensions/, layers your changes on top of the core, and persists through upgrades. It's the supported, future-proof path.

What we're adding

For this example we'll add four fields to the Server class:

• How to Access — connection/login instructions for the server.
• Patch History — a running log of patches applied.
• Cluster Details — which cluster the server belongs to.
• Additional Details — a free-text catch-all.

These mirror the kind of operational notes teams constantly wish were in the CMDB.

Step 1 — Create the extension skeleton

Under iTop's extensions/ folder, create a module directory (e.g., my-server-fields/) containing two files: a module.<name>.php that registers the module, and a datamodel.<name>.xml that defines your changes. The module file tells iTop the extension exists and its version; the XML is where the fields live.

Step 2 — Declare the fields in the datamodel XML

In the datamodel XML, target the existing Server class and add your attributes inside its <fields> block. Each field is an AttributeText (for multi-line notes like Patch History) or AttributeString (for short values). Give each a unique code, a type, and a default. For example, "Patch History" and "Additional Details" suit AttributeText; "How to Access" and "Cluster Details" can be AttributeString or text depending on length.

Also add them to the class's presentation (the details and search forms) so they actually show up in the UI — declaring a field without placing it in a zlist means users never see it.

Step 3 — Provide labels (the dictionary)

Add dictionary entries so the field codes render as human labels ("How to Access" instead of access_method). iTop uses these language files for the UI text; skip them and you'll see raw attribute codes.

Step 4 — Deploy via the setup page

With the files in place, run iTop's setup/installation page. It detects the new extension, lets you enable it, and applies the datamodel change — which alters the underlying database schema to add your columns. iTop handles the SQL; you don't touch the database by hand.

Step 5 — Verify

Open any Server object. Your four fields should appear on the details form (and in search). Edit one, save, and confirm it persists. Done — and because it's an extension, it'll survive the next iTop upgrade.

Common pitfalls

• Field declared but invisible — you forgot to add it to the presentation (zlist). Declaring isn't displaying.
• Raw codes showing in the UI — missing dictionary/label entries.
• Editing core files — changes lost on upgrade; always use an extension module.
• Not re-running setup — the schema only changes when you run the installation/setup step.

Key takeaways

• Add fields via an extension module (module PHP + datamodel XML) — never by editing core files.
• Define attributes on the target class, then add them to the presentation so they're visible.
• Provide dictionary labels so codes render as readable names.
• Run the setup page to apply the schema change; verify on a Server object.

Frequently asked questions

Will custom fields survive an iTop upgrade?

Yes — if you add them through an extension module in extensions/. Core edits do not survive upgrades.

Why isn't my new field showing up?

It's declared but not added to the class presentation (zlist). Add it to the details/search layout.

Do I need to touch the database directly?

No — running iTop's setup applies the datamodel change and updates the schema for you.

String or Text attribute?

Use AttributeString for short single-line values and AttributeText for multi-line notes like patch history.

Build a small extension, declare and present your fields, label them, and re-run setup — that's the clean, upgrade-safe way to make iTop's CMDB fit how your team actually works.