Refreshed extras model documentation

docs/features/context-data.md

@@ -11,10 +11,6 @@ Configuration context data (or "config contexts" for short) is a powerful featur
 }
 ```
 
-While this is handy on its own, the real power of context data stems from its ability to be merged and overridden using multiple instances. For example, perhaps you need to define _different_ syslog servers within the region for a particular device role. You can create a second config context with the appropriate data and a higher weight, and apply it to the desired role. This will override the lower-weight data that applies to the entire region. As you can imagine, this flexibility can cater to many complex use cases.
-
-There are no restrictions around what data can be stored in a configuration context, so long as it can be expressed in JSON. Additionally, each device and VM may have local context data defined: This data is stored directly on the assigned object, and applies to it only. This is a convenient way for "attaching" miscellaneous data to a single device or VM as needed.
-
 Config contexts can be computed for objects based on the following criteria:
 
 | Type          | Devices          | Virtual Machines |
@@ -32,3 +28,57 @@ Config contexts can be computed for objects based on the following criteria:
 | Tenant group  | :material-check: | :material-check: |
 | Tenant        | :material-check: | :material-check: |
 | Tag           | :material-check: | :material-check: |
+
+There are no restrictions around what data can be stored in a configuration context, so long as it can be expressed in JSON.
+
+## Hierarchical Rendering
+
+While this is handy on its own, the real power of context data stems from its ability to be merged and overridden using multiple instances. For example, perhaps you need to define _different_ syslog servers within the region for a particular device role. You can create a second config context with the appropriate data and a higher weight, and apply it to the desired role. This will override the lower-weight data that applies to the entire region. As you can imagine, this flexibility can cater to many complex use cases.
+
+For example, suppose we want to specify a set of syslog and NTP servers for all devices within a region. We could create a config context instance with a weight of 1000 assigned to the region, with the following JSON data:
+
+```json
+{
+    "ntp-servers": [
+        "172.16.10.22",
+        "172.16.10.33"
+    ],
+    "syslog-servers": [
+        "172.16.9.100",
+        "172.16.9.101"
+    ]
+}
+```
+
+But suppose there's a problem at one particular site within this region preventing traffic from reaching the regional syslog server. Devices there need to use a local syslog server instead of the two defined above. We'll create a second config context assigned only to that site with a weight of 2000 and the following data:
+
+```json
+{
+    "syslog-servers": [
+        "192.168.43.107"
+    ]
+}
+```
+
+When the context data for a device at this site is rendered, the second, higher-weight data overwrite the first, resulting in the following:
+
+```json
+{
+    "ntp-servers": [
+        "172.16.10.22",
+        "172.16.10.33"
+    ],
+    "syslog-servers": [
+        "192.168.43.107"
+    ]
+}
+```
+
+Data from the higher-weight context overwrites conflicting data from the lower-weight context, while the non-conflicting portion of the lower-weight context (the list of NTP servers) is preserved.
+
+## Local Context Data
+
+Devices and virtual machines may also have a local context data defined. This local context will _always_ take precedence over any separate config context objects which apply to the device/VM. This is useful in situations where we need to call out a specific deviation in the data for a particular object.
+
+!!! warning
+    If you find that you're routinely defining local context data for many individual devices or virtual machines, [custom fields](./customization.md#custom-fields) may offer a more effective solution.

docs/features/customization.md

@@ -6,6 +6,18 @@ While NetBox strives to meet the needs of every network, the needs of users to c
 
 Most objects in NetBox can be assigned user-created tags to aid with organization and filtering. Tag values are completely arbitrary: They may be used to store data in key-value pairs, or they may be employed simply as labels against which objects can be filtered. Each tag can also be assigned a color for quicker differentiation in the user interface.
 
+Objects can be filtered by the tags they have applied. For example, the following API request will retrieve all devices tagged as "monitored":
+
+```no-highlight
+GET /api/dcim/devices/?tag=monitored
+```
+
+The `tag` filter can be specified multiple times to match only objects which have _all_ the specified tags assigned:
+
+```no-highlight
+GET /api/dcim/devices/?tag=monitored&tag=deprecated
+```
+
 ## Custom Fields
 
 While NetBox provides a rather extensive data model out of the box, the need may arise to store certain additional data associated with NetBox objects. For example, you might need to record the invoice ID alongside an installed device, or record an approving authority when creating a new IP prefix. NetBox administrators can create custom fields on built-in objects to meet these needs.

docs/models/extras/configcontext.md

@@ -1,69 +1,27 @@
 # Configuration Contexts
 
-Sometimes it is desirable to associate additional data with a group of devices or virtual machines to aid in automated configuration. For example, you might want to associate a set of syslog servers for all devices within a particular region. Context data enables the association of extra user-defined data with devices and virtual machines grouped by one or more of the following assignments:
+Context data is made available to [devices](../dcim/device.md) and/or [virtual machines](../virtualization/virtualmachine.md) based on their relationships to other objects in NetBox. For example, context data can be associated only with devices assigned to a particular site, or only to virtual machines in a certain cluster.
 
-* Region
+See the [context data documentation](../../features/context-data.md) for more information.
-* Site group
-* Site
-* Location (devices only)
-* Device type (devices only)
-* Role
-* Platform
-* Cluster type (VMs only)
-* Cluster group (VMs only)
-* Cluster (VMs only)
-* Tenant group
-* Tenant
-* Tag
 
-## Hierarchical Rendering
+## Fields
 
-Context data is arranged hierarchically, so that data with a higher weight can be entered to override lower-weight data. Multiple instances of data are automatically merged by NetBox to present a single dictionary for each object.
+### Name
 
-For example, suppose we want to specify a set of syslog and NTP servers for all devices within a region. We could create a config context instance with a weight of 1000 assigned to the region, with the following JSON data:
+A unique human-friendly name.
 
-```json
+### Weight
-{
-    "ntp-servers": [
-        "172.16.10.22",
-        "172.16.10.33"
-    ],
-    "syslog-servers": [
-        "172.16.9.100",
-        "172.16.9.101"
-    ]
-}
-```
 
-But suppose there's a problem at one particular site within this region preventing traffic from reaching the regional syslog server. Devices there need to use a local syslog server instead of the two defined above. We'll create a second config context assigned only to that site with a weight of 2000 and the following data:
+A numeric value which influences the order in which context data is merged. Contexts with a lower weight are merged before those with a higher weight.
 
-```json
+### Data
-{
-    "syslog-servers": [
-        "192.168.43.107"
-    ]
-}
-```
 
-When the context data for a device at this site is rendered, the second, higher-weight data overwrite the first, resulting in the following:
+The context data expressed in JSON format.
 
-```json
+### Is Active
-{
-    "ntp-servers": [
-        "172.16.10.22",
-        "172.16.10.33"
-    ],
-    "syslog-servers": [
-        "192.168.43.107"
-    ]
-}
-```
 
-Data from the higher-weight context overwrites conflicting data from the lower-weight context, while the non-conflicting portion of the lower-weight context (the list of NTP servers) is preserved.
+If not selected, this config context will be excluded from rendering. This can be convenient to temporarily disable a config context.
 
-## Local Context Data
+### Object Assignment
 
-Devices and virtual machines may also have a local config context defined. This local context will _always_ take precedence over any separate config context objects which apply to the device/VM. This is useful in situations where we need to call out a specific deviation in the data for a particular object.
+Each configuration context may be assigned with any number of objects of the supported types. If no related objects are selected, it will be considered a "global" config context and apply to all devices and virtual machines.
-
-!!! warning
-    If you find that you're routinely defining local context data for many individual devices or virtual machines, custom fields may offer a more effective solution.

docs/models/extras/customfield.md

@@ -1,5 +1,7 @@
 # Custom Fields
 
+NetBox administrators can extend NetBox's built-in data model by adding custom fields to most object types. See the [custom fields documentation](../../customization/custom-fields.md) for more information.
+
 ## Fields
 
 ### Model(s)

docs/models/extras/customlink.md

@@ -1,5 +1,7 @@
 # Custom Links
 
+Users can add custom links to object views in NetBox to reference external resources. For example, you might create a custom link for devices pointing to a monitoring system. See the [custom links documentation](../../customization/custom-links.md) for more information.
+
 ## Fields
 
 ### Name

docs/models/extras/exporttemplate.md

@@ -1,5 +1,7 @@
 # Export Templates
 
+Export templates are used to render arbitrary data from a set of NetBox objects. For example, you might want to automatically generate a network monitoring service configuration from a list of device objects. See the [export templates documentation](../../customization/export-templates.md) for more information.
+
 ## Fields
 
 ### Name

docs/models/extras/imageattachment.md

@@ -1,3 +1,13 @@
 # Image Attachments
 
 Certain objects in NetBox support the attachment of uploaded images. These will be saved to the NetBox server and made available whenever the object is viewed.
+
+## Fields
+
+### Name
+
+The name of the image being attached. If not defined, this will be inferred from the name of the uploaded file.
+
+### Image
+
+The image file to upload. Note that the uploaded file **must** be a supported image type, or validation will fail.

docs/models/extras/tag.md

@@ -2,16 +2,16 @@
 
 Tags are user-defined labels which can be applied to a variety of objects within NetBox. They can be used to establish dimensions of organization beyond the relationships built into NetBox. For example, you might create a tag to identify a particular ownership or condition across several types of objects.
 
-Each tag has a label, color, and a URL-friendly slug. For example, the slug for a tag named "Dunder Mifflin, Inc." would be `dunder-mifflin-inc`. The slug is generated automatically and makes tags easier to work with as URL parameters. Each tag can also be assigned a description indicating its purpose.
+## Fields
 
-Objects can be filtered by the tags they have applied. For example, the following API request will retrieve all devices tagged as "monitored":
+### Name
 
-```no-highlight
+A unique human-friendly label for the tag.
-GET /api/dcim/devices/?tag=monitored
-```
 
-The `tag` filter can be specified multiple times to match only objects which have _all_ of the specified tags assigned:
+### Slug
 
-```no-highlight
+A unique URL-friendly identifier. (This value will be used for filtering.) This is automatically generated from the tag's name, but can be altered as needed.
-GET /api/dcim/devices/?tag=monitored&tag=deprecated
+
-```
+### Color
+
+The color to use when displaying the tag in the NetBox UI.

docs/models/extras/webhook.md

@@ -1,19 +1,84 @@
 # Webhooks
 
-A webhook is a mechanism for conveying to some external system a change that took place in NetBox. For example, you may want to notify a monitoring system whenever the status of a device is updated in NetBox. This can be done by creating a webhook for the device model in NetBox and identifying the webhook receiver. When NetBox detects a change to a device, an HTTP request containing the details of the change and who made it be sent to the specified receiver. Webhooks are managed under Logging > Webhooks.
+A webhook is a mechanism for conveying to some external system a change that took place in NetBox. For example, you may want to notify a monitoring system whenever the status of a device is updated in NetBox. This can be done by creating a webhook for the device model in NetBox and identifying the webhook receiver. When NetBox detects a change to a device, an HTTP request containing the details of the change and who made it be sent to the specified receiver.
 
-## Model Fields
+See the [webhooks documentation](../../integrations/webhooks.md) for more information.
 
-* **Name** - A unique name for the webhook. The name is not included with outbound messages.
+## Fields
-* **Object type(s)** - The type or types of NetBox object that will trigger the webhook.
+
-* **Enabled** - If unchecked, the webhook will be inactive.
+### Name
-* **Events** - A webhook may trigger on any combination of create, update, and delete events. At least one event type must be selected.
+
-* **HTTP method** - The type of HTTP request to send. Options include `GET`, `POST`, `PUT`, `PATCH`, and `DELETE`.
+A unique human-friendly name.
-* **URL** - The fully-qualified URL of the request to be sent. This may specify a destination port number if needed. Jinja2 templating is supported for this field.
+
-* **HTTP content type** - The value of the request's `Content-Type` header. (Defaults to `application/json`)
+### Content Types
-* **Additional headers** - Any additional headers to include with the request (optional). Add one header per line in the format `Name: Value`. Jinja2 templating is supported for this field (see below).
+
-* **Body template** - The content of the request being sent (optional). Jinja2 templating is supported for this field (see below). If blank, NetBox will populate the request body with a raw dump of the webhook context. (If the HTTP cotent type is set to `application/json`, this will be formatted as a JSON object.)
+The type(s) of object in NetBox that will trigger the webhook.
-* **Secret** - A secret string used to prove authenticity of the request (optional). This will append a `X-Hook-Signature` header to the request, consisting of a HMAC (SHA-512) hex digest of the request body using the secret as the key.
+
-* **Conditions** - An optional set of conditions evaluated to determine whether the webhook fires for a given object.
+### Enabled
-* **SSL verification** - Uncheck this option to disable validation of the receiver's SSL certificate. (Disable with caution!)
+
-* **CA file path** - The file path to a particular certificate authority (CA) file to use when validating the receiver's SSL certificate (optional).
+If not selected, the webhook will be inactive.
+
+### Events
+
+The events which will trigger the webhook. At least one event type must be selected.
+
+| Name      | Description                          |
+|-----------|--------------------------------------|
+| Creations | A new object has been created        |
+| Updates   | An existing object has been modified |
+| Deletions | An object has been deleted           |
+
+### URL
+
+The URL to which the webhook HTTP request will be made.
+
+### HTTP Method
+
+The type of HTTP request to send. Options are:
+
+* `GET`
+* `POST`
+* `PUT`
+* `PATCH`
+* `DELETE`
+
+### HTTP Content Type
+
+The content type to indicate in the outgoing HTTP request header. See [this list](https://www.iana.org/assignments/media-types/media-types.xhtml) of known types for reference.
+
+### Additional Headers
+
+Any additional header to include with the outgoing HTTP request. These should be defined in the format `Name: Value`, with each header on a separate line. Jinja2 templating is supported for this field.
+
+### Body Template
+
+Jinja2 template for a custom request body, if desired. If not defined, NetBox will populate the request body with a raw dump of the webhook context.
+
+### Secret
+
+A secret string used to prove authenticity of the request (optional). This will append a `X-Hook-Signature` header to the request, consisting of a HMAC (SHA-512) hex digest of the request body using the secret as the key.
+
+### SSL Verification
+
+Controls whether validation of the receiver's SSL certificate is enforced when HTTPS is used.
+
+!!! warning
+    Disabling this can expose your webhooks to man-in-the-middle attacks.
+
+### CA File Path
+
+The file path to a particular certificate authority (CA) file to use when validating the receiver's SSL certificate (if not using the system defaults).
+
+## Context Data
+
+The following context variables are available in to the text and link templates.
+
+| Variable     | Description                                        |
+|--------------|----------------------------------------------------|
+| `event`      | The event type (`create`, `update`, or `delete`)   |
+| `timestamp`  | The time at which the event occured                |
+| `model`      | The type of object impacted                        |
+| `username`   | The name of the user associated with the change    |
+| `request_id` | The unique request ID                              |
+| `data`       | A complete serialized representation of the object |
+| `snapshots`  | Pre- and post-change snapshots of the object       |