Skip to main content

Choose which source supplies each field

When several contributions supply the same field of an entity, Census keeps one value: the value of the highest-priority contribution that supplies the field. An administrator sets the order once for the inventory, and can set a different order for any field and for the location.

[inventories.devices]
priority = ["infrahub", "netbox"]          # default order for every field

[inventories.devices.fields.status]
type = "string"
priority = ["netbox", "infrahub"]          # NetBox decides the status

[inventories.devices.location]
levels = ["region", "site", "rack"]
locations = ["eu", "eu/par1", "eu/par1/r01"]
priority = ["netbox", "infrahub"]          # NetBox decides the location

Each priority list names every contribution of the inventory exactly once. Census refuses to start if a list misses a contribution or names one twice.

How Census resolves a field​

For each field, Census walks the field's priority list, highest priority first, and stops at the first contribution whose observation decides the field:

What the contribution observedResult for the fieldDoes Census look at the next contribution?
A usable value of the field's typeThat value. Empty strings, 0 and false are values.No
A value it could not use: unmapped, or of the wrong typeNull, with the reason unmapped or wrong_typeNo
No value: the field is not mapped, missing or null in the sourceNothing yetYes
No eligible record for this HFIDNothing yetYes

When no contribution decides the field, the field is null with the state missing.

An unusable value keeps its contribution's priority on purpose. If the highest-priority source reports a status that has no mapping, Census does not show a lower-priority source's status instead: it shows null, and full detail and the diagnostics explain why. The administrator fixes the mapping or the source data.

Priority does not change with freshness or health​

A contribution keeps its priority when its values are stale or when its source cannot be reached. Census keeps the last published values of a source that is down, and reports the outage through the contribution's health. Consumers decide from the freshness and health information whether to use the value.

How Census resolves the location​

The location follows the same rules as a field, with the location's priority list or, when it has none, the inventory's list. One rule is added: a lower-priority contribution can make the location more specific.

After it finds the location of the highest-priority contribution, Census looks at the other contributions in priority order. The first one whose location lies strictly below it replaces it. For example:

  • Infrahub, the higher priority, reports the site eu/par1.
  • NetBox reports the rack eu/par1/r01.
  • The entity's location is eu/par1/r01.

If NetBox reported us/nyc1/r01 instead, which is not inside eu/par1, the location would stay eu/par1. Full detail names the contribution that supplied each level.

Where consumers read which source won​

Each entity in a response has field_sources, which names the contribution that supplied each field and the location. Trace a value to its source shows the full resolution.