docs(customization): Add model validation guidance for Custom Scripts

Adds warning and examples for validating NetBox objects before saving
in Custom Scripts. Direct ORM writes bypass UI/API validation and can
introduce invalid data. Recommends calling `full_clean()` explicitly.

Fixes #22249
This commit is contained in:
Martin Hauser 2026-05-20 15:01:25 +02:00 committed by Jeremy Stretch
parent 31338a28e3
commit 62b3d8f615
1 changed files with 32 additions and 0 deletions

View File

@ -220,6 +220,38 @@ class DeviceConnectionsReport(Script):
self.log_success("Passed", device)
```
## Model Validation
!!! warning "Validate objects before saving"
Direct ORM writes bypass validation normally performed by NetBox's UI and REST API.
Custom scripts can create and update NetBox objects directly through Django's ORM. When doing so, instantiate the model, call `full_clean()`, and then call `save()`:
```python
obj = SomeModel(
field_a=value_a,
field_b=value_b,
)
obj.full_clean()
obj.save()
```
Avoid using `Model.objects.create()` unless you intentionally want to skip model validation:
```python
SomeModel.objects.create(
field_a=value_a,
field_b=value_b,
)
```
Django does not call `full_clean()` automatically when saving a model instance. Skipping validation can allow invalid or inconsistent data to be written to the database, which may later result in UI, API, or script errors.
Bulk and direct queryset operations such as `bulk_create()`, `bulk_update()`, and `QuerySet.update()` should be used with the same care. These operations can bypass model validation and other model-specific save behavior.
When editing an existing object, also see the change logging guidance below.
## Change Logging
To generate the correct change log data when editing an existing object, a snapshot of the object must be taken before making any changes to the object.