Skip to main content

Identify an entity by its HFID

Each entity of an inventory has an HFID (Human-Friendly ID), such as a device name. A consumer uses it to read one entity, to filter a list, and to link a record in another system to the entity.

curl -s localhost:8080/v1/inventories/devices/entities/fw-01

How Census forms an HFID​

Each contribution names the source field that supplies the HFID, for example the device name in Infrahub and in NetBox. Census cleans the value by removing the whitespace around it and converting it to lowercase, and keeps every other character. Records with the same cleaned HFID in one inventory form one entity.

Source valuesEntities
FW-01 in Infrahub and fw-01 in NetBoxOne: fw-01
fw-01 and fw_01Two
fw-01 and fw-01.example.netTwo
fw-01 in the devices inventory and fw-01 in the audit inventoryTwo unrelated entities, one per inventory

The API always returns the cleaned HFID. Full detail gives each source's original value in hfid_original.

Read one entity​

GET /v1/inventories/{inventory}/entities/{hfid} cleans the HFID in the path before it looks it up, so /entities/FW-01 and /entities/%20FW-01%20 both find fw-01. Encode characters that are not allowed in a URL path, such as / or a space.

The lookup accepts detail, branch and require_complete, with the same meaning as for lists. The body is the entity, plus inventory, view, completeness and health, the health of each contribution. The health block is named health here because a full-detail entity uses contributions for its source records.

An HFID with no entity returns 404 entity-not-found.

When an entity appears or disappears​

  • An entity exists while at least one eligible record has its HFID. When the last record is removed, because the source deleted the object or a successful refresh no longer contains it, the entity disappears from lists and its lookup returns 404.
  • A source that cannot be reached does not remove anything: its last published records stay.
  • When a source renames an object, the record moves to the new HFID. Census keeps no link or redirect from the old HFID. While one source has the new name and another the old one, the inventory holds two entities.

Records that do not form an entity​

A record with no HFID, and the records of one contribution that share an HFID, take no part in any entity. They make the inventory incomplete and are listed in the diagnostics as missing_hfid and duplicate_hfid. When two records of one contribution share an HFID, other contributions can still supply that entity.