Skip to main content

Concepts

These terms are used across the administration guide, the API guide and the API itself.

Where the data comes from​

  • Source system: a system Census reads from. Infrahub and NetBox are supported. Census does not write to source systems.
  • Connection: the address and credentials of one source system, declared once in the configuration file and identified by an id. Any number of inventories can use one connection.
  • Source object: one object of a source system, such as an Infrahub node of kind InfraDevice or a NetBox object at dcim/devices. Census identifies it by its native id: the Infrahub node id or the NetBox numeric id.

What an administrator defines​

  • Inventory: a named set of entities of one kind, for example devices. Each inventory has its own fields, contributions, priorities, vocabularies, freshness budgets and location hierarchy. Each inventory fetches and stores its own copy of the source data, so two inventories can show different values for the same device.
  • Field: a typed attribute of an inventory's entities. The type is string, number or boolean.
  • Contribution: the use of one connection inside one inventory. It names the object types to collect, the source field that supplies the HFID, and the source field of each attribute and location level. Two contributions can use the same connection with different mappings.
  • Priority: the order in which contributions are considered when Census resolves a field or the location. Each inventory has a default order, and each field and the location can have their own.
  • Vocabulary: the list of canonical values of a field, for example active, planned and offline. Each contribution can map its own source spellings to these values.
  • Location hierarchy: the levels of an inventory's locations, for example region, site and rack, and every declared location as a path such as eu/par1/r01.
  • Freshness budget: how long a value stays fresh after its source last confirmed it.

What Census builds​

  • Record: one contribution's observation of one source object: its HFID, one observation per field, and its location.
  • HFID (Human-Friendly ID): the identifier of an entity inside one inventory. Census takes it from the source field the contribution names, removes surrounding whitespace and converts it to lowercase. Records with equal HFIDs in one inventory describe the same entity. Equal HFIDs in two inventories are unrelated.
  • Entity: the result of grouping the records that share an HFID and resolving each field by priority. The API returns entities, with their resolved values.
  • Full refresh: Census fetches every object of a contribution's object types and publishes them together. A refresh that fails part-way publishes nothing.
  • Snapshot: a contribution has a published snapshot once one full refresh has been published.
  • Webhook: a request a source system sends to Census when an object changes. Infrahub sends webhooks. NetBox contributions are updated by full refreshes only.

What a response reports​

  • Completeness: an inventory is complete when every contribution has a published snapshot and no record is excluded because its HFID is missing or duplicated.
  • Contribution health: ok, refreshing or degraded, with the time of the last published refresh and the last error.
  • Freshness: whether each value was confirmed by its source within the field's freshness budget (fresh) or not (stale).
  • View: the default view holds the data of each source's default branch. A branch view holds the data of a named branch, from the sources that have it, and default data from the others.
  • Diagnostic: a record that Census excluded, or a value it could not use, identified by its source reference.