Statuses - Nautobot Documentation

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.name` field is used.

Changed in version 2.0.0

Changed the CSV import reference for Statuses from `Status.slug` to `Status.name`.

## 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 locations is tracking the nature of a specific location's installation status. A location that is under construction could receive 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 use a `nautobot.extras.models.statuses.StatusField` for its foreign-key to the model. This field type will automatically assign a `related_name` for the reverse relationship back to the inheriting model's verbose plural name (e.g. `devices`).

Changed in version 2.0.0

The related name for Statuses was changed to be based on the model's `verbose_name_plural` instead of the pattern `%(app_label)s_%(model)s_related`. For example, `Status.devices` and not `Status.dcim_device_related`. Additionally, the recommendation to inherit from `StatusModel` has been replaced with a recommendation to directly include a `StatusField`.

### `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.

### 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 use a `nautobot.extras.models.statuses.StatusField`
- Decorate the model class with `@extras_features('statuses')` (`from nautobot.extras.utils import extras_features`)

### Forms

- Generic model forms will automatically include a `StatusField`
- Bulk edit model forms must inherit from `nautobot.extras.forms.StatusModelBulkEditFormMixin`
- Filter forms must inherit from `nautobot.extras.forms.StatusModelFilterFormMixin`

### Filters

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

### Tables

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