Asset CI Link

Linking an asset to its configuration item

A server is often two records in FreeITSM. The asset (in Assets) says what the box is: make, model, serial number, where it is, what the inventory agent last saw. The configuration item (in the CMDB) says what it does: what runs on it, what depends on it, and what breaks if it fails.

A link joins the two and says these are the same piece of equipment. Each page then shows the other, so an analyst on either one can reach the other in one click.

Built for issue #201. The design and the decisions behind it are in Linking an asset to its configuration item - design.

---

Linking

Where	The card	What it shows
An asset, Key info	Configuration item	The CI's name and class, a link into the CMDB, and what would be affected if it failed
A configuration item, under Details	Asset	The asset's name, a link to it, and its details From the asset

1. Press Link on either card.
2. Search: from an asset you search configuration items by name; from a configuration item you search assets by name, serial number or asset tag. Only records in the same company are offered. A result already linked to something else says already linked.
3. Pick one. The link is made, and both pages show it straight away.

The link doesn't depend on FreeITSM's inventory agent. An asset that came from Intune, a spreadsheet, a REST tool or was typed in by hand links the same way.

One each

An asset has one configuration item, and a configuration item has one asset. If you pick one that is already linked elsewhere, FreeITSM says so and names the other record (or says it is one you cannot open), and offers to Replace it:

• Replace ends the old link and makes the new one, in one step. Both ended links stay in the history.
• If somebody changed the link while you were looking at it, the replace is refused and the card reloads with the new state. A newer link is never overwritten without you seeing it.

Anything else - a cluster and its nodes, the VMs on a host, the applications on a server - is an ordinary CMDB relationship, not this link.

Unlink

Unlink ends the link. Neither the asset nor the configuration item is deleted, and the link stays in the history.

Creating the configuration item from the asset

If the asset has no configuration item yet, it can make one:

1. An administrator chooses which CMDB class each asset type becomes: Assets → Settings → Asset types → (a type) → CMDB class - Server for servers, say. Choosing a class never creates anything by itself and changes nothing on existing assets. It only makes the button appear.
2. On an unlinked asset of that type, the card offers Create linked CI beside Link.
3. If configuration items of that class, in the same company, already have the asset's name (ignoring case) and are not linked to anything, they are listed first with Link this one instead. A matching name is a hint, never proof, so nothing is linked automatically.
4. Otherwise - or with Create a new one - give it a name (the asset's, to start with) and fill in anything the class requires. Create makes the configuration item and links it in one step: you get both, or neither.

Nothing hardware-shaped is copied into the new item: its serial number, model and so on are read from the asset through the link.

---

The asset's details on the configuration item

The Asset card on a configuration item shows, read live from the asset:

• type
• manufacturer and model
• serial number and asset tag
• status and location
• inventory - when the asset was last seen, and whether its inventory sources are current, stale, or failed on their last read

They are labelled From the asset and are never copied into the CI, so there is nothing to keep in step. To change one, open the asset (the card links to it).

CMDB → Settings → Asset card chooses which of these the card shows. All of them are ticked to start with.

---

"If this failed" on the asset

When an asset is linked, its card adds a line from the configuration item's own impact analysis:

If this failed, affected: 14 (6 Virtual machine, 3 Application, 2 Service) Show · Open as diagram

• Show opens the configuration item at its If this failed panel.
• Open as diagram draws it in Network Mapper (for analysts who can open Network Mapper).

This is exactly what the CMDB says, following its own relationship types and impact settings. The asset itself is never part of the CMDB graph: the link adds no relationship and spreads no impact.

---

Link history

Both cards end with Link history: every link the record has had, with:

• who linked it, when, and how - on the page, or through the REST API with which key
• when it ended, who ended it, and why: Unlinked, Replaced, Configuration item deleted, or Ended when two assets were merged

The asset's own View History also records each change as Configuration item.

---

When records go away

What happens	The link
A configuration item is deleted	Its link ends. The asset is kept and shows No configuration item. The history keeps the deleted CI's name. The delete confirmation says the asset is kept
Two assets are merged (Asset review)	The link moves to the asset you keep, and its history says which asset it was made on. If both were linked, the merge window shows both links and asks which to keep. Merge stays greyed out until you tick I understand the other link will end. Cancel leaves everything as it was. Neither configuration item, nor any of its relationships, is changed

Deleting a configuration item also clears any Link to something else → configuration item custom field that pointed at it. Before, those kept showing the deleted item's number.

---

Who can do what

You can	You see	You can link
Open and change both Assets and the CMDB	Both cards in full	Yes
Open the CMDB but not Assets	Linked asset - restricted: no name, no number, no details	No - the card says why
Open Assets but not the CMDB	Linked configuration item - restricted	No

The same rule applies to the link history, to the asset's history, to messages about conflicts, and to the REST API. The link never reveals a record you could not otherwise open. On a multi-company install both records always belong to the same company.

Neither module has a Read only access level yet. If either gains one, read-only analysts will be able to see links but not change them, with no further change needed.

---

Hiding the card

A monitor or a mouse will never be a configuration item. In Assets → Settings → Asset types → (a type) → Layout, untick Configuration item to hide the card on that type. The Peripheral and Mobile device starting points already leave it unticked. Hiding is display only: it never removes a link.

---

The REST API

GET /assets/{id}/ci-link	The live link and the history, from the asset
POST /assets/{id}/ci-link	Link (or replace)
DELETE /assets/{id}/ci-link	Unlink
POST /assets/{id}/ci-link/create-ci	Create linked CI (also needs cmdb_objects.create)
GET /cmdb/objects/{id}/asset-link	The same, from the configuration item

GET /assets/{id} also has linked_ci, and GET /cmdb/objects/{id} has linked_asset. The permission is Asset and configuration item links (asset_ci_links), so an integration can keep links up to date without being able to edit assets or configuration items. Details are in REST API - Assets.

---

Custom link fields

A custom asset field of type Link to something else → A configuration item is a separate thing: a fact recorded on the asset, one-way, that the CMDB does not show. It is left exactly as it is. Use the link on this page for the same equipment, and a custom field for anything else you want to record.

---

Related pages

• CMDB · Assets · Asset type layouts · Asset review · Inventory freshness
• Linking an asset to its configuration item - Developer Guide