Define an inventory
An inventory is a named set of entities of one kind, such as devices, with its own fields.
An administrator defines it under [inventories.<id>]. The id appears in every API path of
the inventory, for example /v1/inventories/devices/entities.
[inventories.devices]
description = "Network devices from Infrahub and NetBox"
entity_kind = "device"
priority = ["infrahub", "netbox"]
[inventories.devices.fields.role]
type = "string"
[inventories.devices.fields.status]
type = "string"
vocabulary = ["active", "planned", "offline"]
[inventories.devices.fields.ports]
type = "number"
An inventory needs at least one field, at least one contribution and a location hierarchy.
Inventory settings
| Setting | Required | Meaning |
|---|---|---|
id, in [inventories.<id>] | Yes | Lowercase letters, digits, - and _, starting with a letter or a digit, for example devices or dc-racks. |
description | No | Shown to consumers in the inventory list and the web UI. |
entity_kind | No | The kind of entity the inventory holds, for example device. It is shown to consumers and has no effect on processing. |
priority | Yes | Every contribution id of the inventory, once each, highest priority first. Choose which source supplies each field explains how Census uses it. |
Declare fields
Each field is a table [inventories.<id>.fields.<name>]. A field name starts with a
lowercase letter and contains lowercase letters, digits and _.
| Setting | Required | Meaning |
|---|---|---|
type | Yes | string, number or boolean. |
vocabulary | No | The list of canonical values. Normalize source values describes it. |
default | No | The value used when a source supplies a value that has no mapping. Requires vocabulary. |
priority | No | The contribution order for this field. It replaces the inventory's priority for this field. |
Census does not convert between types. A source value whose JSON type differs from the
field's type, for example the string "48" for a number field, is reported as
wrong_type. The field is null for that source, the rest of the entity stays available,
and the problem is listed in the diagnostics.
Fields hold one value each. Lists, nested objects and other specialised types are not supported.
An inventory collects every source object of its types
An inventory definition does not filter the objects it collects by their values. A
contribution collects every object of its object types. Consumers filter at query time, for
example with filter.status=active.
To collect a smaller set of objects, define the inventory on object types that hold only those objects in the source.
Several inventories from the same sources
Each inventory is independent:
- It fetches and stores its own copy of the source data.
- Equal HFIDs in two inventories are unrelated entities.
- A configuration change in one inventory does not affect the data of another.
This lets an administrator expose the same devices with different fields or different
priorities, for example a devices inventory where NetBox is authoritative for the status
and an audit inventory where Infrahub is.