Skip to content

Tags & custom fields

Danbyte ships with no pre-filled data, so you tailor it to your network two ways: tags for free-form labels you can stick on anything, and custom fields for structured extra data that appears on object forms. Both live under the sidebar's Customize section.

Tags

Tags are short labels - prod, core, monitored - that you attach to objects to group, filter, and find them. A tag belongs to the tenant that created it; a few older global tags, from before tags were tenant-scoped, are shared by every tenant and carry a small global chip in tag pickers and on the Tags list.

Managing tags

  1. Go to Customize → Tags and click Add tag.
  2. Give it a name and, optionally, a colour.
  3. Save.

The Tags list shows how many objects use each tag, and you can filter by usage or colour. For a site-scoped user the number counts only the tagged objects at the sites they can view (and shared, site-less ones).

Unique names

A tag name can exist only once among the tags a tenant sees: its own tags (site-local ones included) and the global ones. Case and surrounding spaces don't count, so Prod clashes with prod. Creating or renaming a tag into a name that is taken fails with an error naming the existing tag and its scope. A global tag's name must be free in every tenant.

The rule applies from now on. Installs that already have two tags of one name - typically a global prod and a tenant prod - keep both until you merge them: the Tags list shows a notice such as 2 tag names are used twice; Show (or the Names → Used twice filter) lists the pairs side by side.

Imports and hypervisor syncs reuse a tag of the same name the tenant already sees instead of creating a second one.

Tags in the API

API writes pick tags by id: tag_ids on a create or edit, add_tag_ids / remove_tag_ids on a bulk update, and tag_ids on the interface bulk add. An id must name a tag the tenant may use - one of its own, a global one, or, for a site-scoped user under enhanced site separation, a tag local to one of their sites. Anything else (another tenant's tag, another site's local tag, a tag name instead of an id) is a 400 on that field and nothing is written. These writes never create a tag; create it first under Customize → Tags (POST /api/tags/).

Merging tags

Use a row's Merge into… action to fold one tag into another. Pick the tag to keep; the dialog says how many objects move. On Merge every object carrying the tag gets the kept tag instead (an object that already has both keeps one), each object's change log records the swap, and the merged tag is deleted - all in one step.

The kept tag must be of the same scope or wider: a tag local to the same site, a tenant-wide tag, or a global tag. A global tag merges only into another global tag, and only a superuser can merge it. Merging needs the change and delete permissions on tags.

API: POST /api/tags/<id>/merge/ with {"into": <id>} returns {moved, already_tagged, into}; GET /api/tags/duplicates/ returns the colliding names as {count, results: [{name, ids}]}.

Seeing where a tag is used

Open a tag to see its Used by table - every object in the current tenant that carries it, with a link to each. (A global tag is shared, but this view only shows your active tenant's objects, so it never leaks another tenant's data.)

Tip

To apply a tag, open the object you want to label and add the tag on its form. You can also create a tag on the fly from there.

Custom fields

A custom field adds your own piece of data to an object - a warranty date, an owner team, a maintenance window - and it shows up on that object's form and overview. Custom fields are tenant-scoped: each tenant defines its own.

Field types

Type Use for
Text / Text area Short or long free text.
Integer / Decimal Whole or fractional numbers.
Boolean A yes/no checkbox.
Date A calendar date.
URL A link.
Select One choice from a list you define.
Multiselect Several choices from a list you define.
Object reference One live object of a model you pick - a user, group, device, VLAN, rack, prefix, tenant…

Object reference turns a custom field into a real dropdown of existing objects: pick the referenced model on the field definition, and every form carrying the field offers that model's instances through the advanced picker (devices, racks, VLANs, prefixes and IPs get their full filter-modal pickers; every other model - including users and groups - gets a searchable picker automatically). Values are validated against live rows (tenant-scoped where the model is), and detail pages render the object's name as a link, resolved through the registry - a deleted target degrades to its raw id, never an error. So does a target you may not view: the name is resolved with your own access (the object type's view permission and the sites it covers), and with no active tenant nothing resolves.

Users and groups are the exception, because listing accounts is user administration. A user field's picker lists the active members of the tenant, and a group field's picker the groups they are in, for anyone who may add or change one of the types the field applies to. Without a permission on users, the address is left out. On detail pages the value still reads as a name when it is one of the tenant's members or their groups.

Which objects can have custom fields

Every model that carries the custom_fields mixin - the list is auto-derived, so new models (and plugin models) appear in the "Applies to" checklist without anyone maintaining a list. Targeting device types and device roles lets you annotate the catalog itself - for example a warranty date on a device type or a service tier on a device role.

Each of those models also carries custom_fields on its API rows - device components included (console, power, front and rear ports, bays, modules and inventory items), so a field defined for them can be read and set through the API like any other.

For plugin developers

Two registration hooks in customization/object_registry.py: register_customizable_model(slug, label) adds your model to the "Applies to" list (models using CustomFieldsMixin are picked up automatically), and register_reference_model(ReferenceModel(...)) makes it a valid object-reference target - endpoint, label field and detail route included, so the SPA's pickers and value rendering work with zero frontend changes. Call both from your AppConfig.ready().

Three ReferenceModel fields decide how your model is scoped and labelled:

  • tenant_field - the ORM path from your model to its Tenant. A lookup path is fine, not just a local field: a model with no tenant FK of its own says something like "device__tenant" (interfaces do). None means the model is global and skips tenant filtering entirely - never use it to work around a path that doesn't resolve, because that turns a scoping bug into a cross-tenant leak.
  • label_field - the attribute holding the display label, or None to use the model's __str__. Prefer None when the bare field is ambiguous: an interface name is unique only per device, so Gi2/1 means nothing without sw-01 in front of it.
  • select_related - joins to follow while resolving labels, so a __str__ that reaches through a relation isn't an N+1 across a 200-id batch.

customization/tests_reference_registry.py walks every registered entry and fails if a tenant_field, label_field or select_related doesn't resolve - including entries added by plugins.

Adding a custom field

  1. Go to Customize → Custom fields and click Add custom field.
  2. Set the key (the internal name, unique within your tenant) and a label (what people see).
  3. Choose the type. For Select / Multiselect, add the list of choices.
  4. Pick which objects it applies to.
  5. (Optional) Mark it required, give a default, and add a description.
  6. Save.

The field now appears on every matching object's form, with the right kind of input for its type, and on the object's overview. It is also a column on every list of those objects: open the list's Columns menu and tick it under Custom fields (it starts hidden). The column sorts - numbers by value, dates by date - and exports with its value as text (an object reference exports its name). Anyone who can view the list sees the column; a field local to one site is offered only to people who work at that site. See Table columns. On the virtual machine list the selection bar's Edit sets custom fields on many VMs at once, one field at a time.

Required and choice fields are enforced

When you save an object, Danbyte checks its custom fields: required fields must be filled in, and select/multiselect values must come from your list. Any problems are reported next to the field.

Hidden. Tick Hidden on a definition and its values stay on the objects - and stay searchable - but no detail card, table column or form shows them. Meant for bookkeeping fields such as an imported NetBox id that nobody needs to read on every page. Untick to bring them back.

Custom field groups

When a tenant has many custom fields, one flat list gets unwieldy. Groups bucket related fields under a heading on forms and detail pages - e.g. a Monitoring group holding install_btop, enable_netdata, and syslog_profile.

  1. Go to Customize → Custom field groups → Add.
  2. Give it a name (the heading). Optionally set a weight (sections sort low → high), a description, and Start collapsed to fold the section by default on detail pages.
  3. On each custom field, pick the Group in its form.

Fields with no group stay under the default Custom fields heading, so nothing changes until you start grouping. Deleting a group simply un-groups its fields - they're never lost.

Open a group

Clicking a group's name in Customize → Custom field groups opens its detail page:

  • Overview - the heading name, slug, description, its weight and Start collapsed setting, and (under enhanced site separation) whether the group is global or owned by one site.
  • Fields - the definitions filed under this heading, in the order the section will render them. Read it before you rename a group or move a field.
  • Journal - your notes on this group.
  • Change log - the automatic record of changes to the group itself.

The Custom fields list also carries a Group column, so you can see which section every field belongs to without opening each one.

Why a real group, not a label

Danbyte uses a first-class group object rather than a free-text group name: rename or reorder a group in one place, the picker is a dropdown so typos can't silently split a group, and a group can carry a description + a collapse default. Grouping is presentation only - the Ansible inventory's danbyte.custom_fields stays a flat {name: value} map, so playbooks are unaffected.