Skip to content

Statuses

Nautobot provides the ability for custom statuses to be defined within an organization to be used on various objects to facilitate business workflows around object statuses.

Status Basics

The value of a status field on a model (such as Device.status) will be represented as a nautobot.extras.models.Status object.

When created, a Status can be associated to one or more model content-types using a many-to-many relationship. The relationship to each model is referenced across all user interfaces using the {app_label}.{model} naming convention (e.g. dcim.device).

Statuses may be managed by navigating to Organization > Statuses in the navigation menu.

Importing Objects with a status Field

When using CSV import to reference a status field on an object, the Status.slug field is used.

For example, the default Active status has a slug of active, so the active value would be used for import.

Customizing Statuses

With Status as a model, statuses can be customized. This can be as simple as removing the option to configure an existing status with a particular model or to remove that status entirely.

The real benefit of custom status is adding your own organization status and process names directly to Nautobot. An example of custom statuses would be including End of Life information for your devices. A simple End of Life status could be EOx for a device hitting any end of life milestone; more specific statuses like EOSS (End of Software Support), EOS (End of Sale), and Pre-EOS (for 1 year prior to EOS) to be more specific. Once the end of life information is tracked as a status, developing a report for Devices that have reached EOSS is trivial.

Another example for sites is tracking the nature of a specific site's installation status. A site that is under construction could received a status like 'Pre Production'.

For Virtual Machines, if utilizing OpenStack, statuses in Nautobot could be customized to reflect the specific Nova virtual machine states.

Status Internals

Warning

The section below is largely intended for developers who may need to create data models of their own that implement a status field. Proceed at your own risk!

Any model that is intended to have a status field must inherit from nautobot.extras.models.statuses.StatusModel. This abstract model will add an nautobot.extras.models.statuses.StatusField to the model. The abstract base will automatically assign a related_name for the reverse relationship back to the inheriting model's name (e.g. devices).

StatusField model field

The StatusField field type subclass of a django.db.models.ForeignKey with extra extensions to have it behave like field with choices. Because this pattern is replacing hard-coded ChoiceSets (such as dcim.choices.DeviceStatusChoices) with database objects, it is not possible to use the choices= argument on a foreign key.

Because of this, StatusField implements a .contribute_to_class() method which will automatically bind .get_status_display() and .get_status_color() methods to any model that implements this field, so that these do not need to be manually defined on each model.

This model field also emits its own form field to eliminate the requirement for a form field to be explicitly added to model forms.

StatusFilter filter field

Any filter that is intended to have a status field must inherit from nautobot.extras.filters.StatusModelFilterSetMixin. This will add a nautobot.extras.filters.StatusFilter to the filter, which allows filtering by the name of the status.

Form fields

Any model form that is intended to have a status field must inherit from one of three mixins, depending on the use-case:

  • nautobot.extras.forms.StatusModelFilterFormMixin should be used to add a non-required, multiple-choice status filter field to UI filter forms. This multiple-choice field allows for multiple status values to be selected for filtering objects in list views in the web UI.
  • nautobot.extras.forms.StatusModelBulkEditFormMixin should be used to add a non-required status form field to a an object's model form. This field constrains status choices eligible to the object type being edited.

Changed in version 1.4.0

In prior Nautobot versions these mixins were named StatusFilterFormMixin and StatusBulkEditFormMixin; the old names are still available as aliases but will be removed in a future major release.

  • FIXME: CSV import forms

StatusSerializerField serializer field

Any serializer that is intended to have a status field must inherit from nautobot.extras.api.serializers.StatusModelSerializerMixin. This adds an nautobot.extras.api.fields.StatusSerializerField to the serializer.

The StatusSerializerField is a writable slug-related choice field that allows writing to the field using the name value of the status (e.g. "active"). Writing to this field is normalized to always be converted to lowercase.

Table field

If you wish for a table to include a status field, your table must inherit from nautobot.extras.tables.StatusTableMixin. This includes a ColorColumn on the table.

Status object integrations

To fully integrate a model to include a status field, assert the following:

Model

  • The model must inherit from nautobot.extras.models.statuses.StatusModel
  • Decorate the model class with @extras_features('statuses') (from nautobot.extras.utils import extras_features)

Forms

  • Generic model forms will automatically include a StatusField
  • CSV model import forms must inherit from nautobot.extras.forms.StatusModelCSVFormMixin
  • Bulk edit model forms must inherit from nautobot.extras.forms.StatusModelBulkEditFormMixin
  • Filter forms must inherit from nautobot.extras.forms.StatusModelFilterFormMixin

Changed in version 1.4.0

In prior Nautobot releases the latter two mixins were named StatusBulkEditFormMixin and StatusFilterFormMixin respectively; the old names are still available as aliases but will be removed in a future major release.

Filters

  • Filtersets for your model must inherit from nautobot.extras.filters.StatusModelFilterSetMixin

Serializers

  • Serializers for your model must inherit from nautobot.extras.api.serializers.StatusModelSerializerMixin

Tables

  • The table class for your model must inherit from nautobot.extras.tables.StatusTableMixin