Documentation and changelog for #7006

docs/models/extras/customfield.md

@@ -19,6 +19,8 @@ Custom fields may be created by navigating to Customization > Custom Fields. Net
 * JSON: Arbitrary data stored in JSON format
 * Selection: A selection of one of several pre-defined custom choices
 * Multiple selection: A selection field which supports the assignment of multiple values
+* Object: A single NetBox object of the type defined by `object_type`
+* Multiple object: One or more NetBox objects of the type defined by `object_type`
 
 Each custom field must have a name. This should be a simple database-friendly string (e.g. `tps_report`) and may contain only alphanumeric characters and underscores. You may also assign a corresponding human-friendly label (e.g. "TPS report"); the label will be displayed on web forms. A weight is also required: Higher-weight fields will be ordered lower within a form. (The default weight is 100.) If a description is provided, it will appear beneath the field in a form.
 
@@ -41,3 +43,7 @@ NetBox supports limited custom validation for custom field values. Following are
 Each custom selection field must have at least two choices. These are specified as a comma-separated list. Choices appear in forms in the order they are listed. Note that choice values are saved exactly as they appear, so it's best to avoid superfluous punctuation or symbols where possible.
 
 If a default value is specified for a selection field, it must exactly match one of the provided choices. The value of a multiple selection field will always return a list, even if only one value is selected.
+
+### Custom Object Fields
+
+An object or multi-object custom field can be used to refer to a particular NetBox object or objects as the "value" for a custom field. These custom fields must define an `object_type`, which determines the type of object to which custom field instances point.

docs/release-notes/version-3.2.md

@@ -22,6 +22,12 @@ A new REST API endpoint has been added at `/api/ipam/vlan-groups/<pk>/available-
 
 A new model has been introduced to represent function roles for inventory items, similar to device roles. The assignment of roles to inventory items is optional.
 
+#### Custom Object Fields ([#7006](https://github.com/netbox-community/netbox/issues/7006))
+
+Two new types of custom field have been added: object and multi-object. These can be used to associate objects with other objects in NetBox. For example, you might create a custom field named `primary_site` on the tenant model so that a particular site can be associated with each tenant as its primary. The multi-object custom field type allows for the assignment of one or more objects of the same type.
+
+Custom field object assignment is fully supported in the REST API, and functions similarly to normal foreign key relations. Nested representations are provided for each custom field object.
+
 #### Modules & Module Types ([#7844](https://github.com/netbox-community/netbox/issues/7844))
 
 Several new models have been added to support field-replaceable device modules, such as those within a chassis-based switch or router. Similar to devices, each module is instantiated from a user-defined module type, and can have components associated with it. These components become available to the parent device once the module has been installed within a module bay. This makes it very convenient to replicate the addition and deletion of device components as modules are installed and removed. 
@@ -96,6 +102,8 @@ Inventory item templates can be arranged hierarchically within a device type, an
     * Removed the `asn`, `contact_name`, `contact_phone`, and `contact_email` fields
 * extras.ConfigContext
     * Add `cluster_types` field
+* extras.CustomField
+    * Added `object_type` field
 * ipam.VLANGroup
     * Added the `/availables-vlans/` endpoint
     * Added the `min_vid` and `max_vid` fields