0
# Extensibility and Automation
1
2
Advanced features including custom fields, relationships, jobs, webhooks, templates, secrets management, and configuration contexts. Enables customization and automation workflows for network operations.
3
4
## Capabilities
5
6
### Status and Role Management
7
8
Flexible status and role system for objects.
9
10
```python { .api }
11
class Status:
12
"""
13
Status objects for lifecycle management.
14
15
Attributes:
16
name (str): Status name
17
slug (str): URL-safe slug
18
color (str): Status color (hex)
19
description (str): Status description
20
content_types (list): Applicable content types
21
"""
22
23
class StatusField:
24
"""Status field for models."""
25
26
class StatusModel:
27
"""Base class for status-aware models."""
28
29
class Role:
30
"""
31
Role objects for functional classification.
32
33
Attributes:
34
name (str): Role name
35
slug (str): URL-safe slug
36
color (str): Role color (hex)
37
description (str): Role description
38
content_types (list): Applicable content types
39
weight (int): Role weight for ordering
40
"""
41
42
class RoleField:
43
"""Role field for models."""
44
```
45
46
### Tagging System
47
48
Flexible tagging system for object organization.
49
50
```python { .api }
51
class Tag:
52
"""
53
Tags for object categorization and organization.
54
55
Attributes:
56
name (str): Tag name
57
slug (str): URL-safe slug
58
color (str): Tag color (hex)
59
description (str): Tag description
60
content_types (list): Applicable content types
61
"""
62
63
class TaggedItem:
64
"""
65
Tagged item associations.
66
67
Attributes:
68
tag (Tag): Associated tag
69
content_type (ContentType): Tagged object type
70
object_id (UUID): Tagged object ID
71
content_object (object): Tagged object
72
"""
73
```
74
75
### Custom Fields System
76
77
Runtime-configurable custom fields for any model.
78
79
```python { .api }
80
class CustomField:
81
"""
82
Custom field definitions for extending models.
83
84
Attributes:
85
type (str): Field type (text, integer, boolean, date, etc.)
86
name (str): Field name
87
label (str): Field display label
88
description (str): Field description
89
required (bool): Whether field is required
90
filter_logic (str): Filter logic for searches
91
default (str): Default value
92
weight (int): Field ordering weight
93
validation_minimum (int): Minimum value validation
94
validation_maximum (int): Maximum value validation
95
validation_regex (str): Regex validation pattern
96
choices (list): Available choices for choice fields
97
content_types (list): Applicable content types
98
"""
99
100
class CustomFieldChoice:
101
"""
102
Choices for custom choice fields.
103
104
Attributes:
105
field (CustomField): Parent custom field
106
value (str): Choice value
107
weight (int): Choice ordering weight
108
"""
109
110
class CustomFieldModel:
111
"""Base class for models supporting custom fields."""
112
113
class ComputedField:
114
"""
115
Computed field definitions for calculated values.
116
117
Attributes:
118
content_type (ContentType): Target content type
119
slug (str): Field slug
120
label (str): Field display label
121
description (str): Field description
122
template (str): Jinja2 template for computation
123
fallback_value (str): Fallback value if computation fails
124
weight (int): Field ordering weight
125
"""
126
```
127
128
### Job System
129
130
Background job execution system for automation workflows.
131
132
```python { .api }
133
class Job:
134
"""
135
Background job definitions for automation.
136
137
Attributes:
138
name (str): Job name
139
description (str): Job description
140
installed (bool): Whether job is installed
141
enabled (bool): Whether job is enabled
142
is_job_hook_receiver (bool): Whether job receives hooks
143
soft_time_limit (int): Soft time limit in seconds
144
time_limit (int): Hard time limit in seconds
145
grouping (str): Job grouping
146
slug (str): Job slug
147
source (str): Job source
148
git_repository (GitRepository): Source Git repository
149
job_class_name (str): Job class name
150
module_name (str): Job module name
151
"""
152
153
class JobResult:
154
"""
155
Job execution results and status.
156
157
Attributes:
158
obj_type (ContentType): Job content type
159
name (str): Job name
160
created (datetime): Creation timestamp
161
completed (datetime): Completion timestamp
162
user (User): User who ran the job
163
status (str): Job status (pending, running, completed, errored, failed)
164
data (dict): Job input data
165
job_id (UUID): Celery job ID
166
result (dict): Job result data
167
traceback (str): Error traceback if failed
168
job_kwargs (dict): Job keyword arguments
169
schedule (ScheduledJob): Associated scheduled job
170
"""
171
172
class JobLogEntry:
173
"""
174
Job execution log entries.
175
176
Attributes:
177
job_result (JobResult): Associated job result
178
log_level (str): Log level (debug, info, success, warning, error, critical)
179
grouping (str): Log grouping
180
message (str): Log message
181
created (datetime): Log timestamp
182
line_number (int): Log line number
183
"""
184
185
class JobButton:
186
"""
187
Job UI buttons for object actions.
188
189
Attributes:
190
name (str): Button name
191
job (Job): Associated job
192
enabled (bool): Whether button is enabled
193
text (str): Button text
194
content_types (list): Applicable content types
195
group_name (str): Button group
196
weight (int): Button ordering weight
197
button_class (str): CSS button class
198
confirmation (bool): Whether to show confirmation dialog
199
"""
200
201
class JobHook:
202
"""
203
Job hooks for event-driven automation.
204
205
Attributes:
206
name (str): Hook name
207
job (Job): Associated job
208
enabled (bool): Whether hook is enabled
209
content_types (list): Applicable content types
210
type_create (bool): Trigger on object creation
211
type_update (bool): Trigger on object update
212
type_delete (bool): Trigger on object deletion
213
"""
214
```
215
216
### Job Scheduling
217
218
Scheduled job execution and queue management.
219
220
```python { .api }
221
class JobQueue:
222
"""
223
Job execution queues.
224
225
Attributes:
226
name (str): Queue name
227
enabled (bool): Whether queue is enabled
228
description (str): Queue description
229
"""
230
231
class JobQueueAssignment:
232
"""
233
Job to queue assignments.
234
235
Attributes:
236
job (Job): Associated job
237
queue (JobQueue): Assigned queue
238
enabled (bool): Whether assignment is enabled
239
"""
240
241
class ScheduledJob:
242
"""
243
Scheduled job execution definitions.
244
245
Attributes:
246
name (str): Scheduled job name
247
task (str): Task name
248
job_class (str): Job class name
249
job_model (Job): Associated job model
250
enabled (bool): Whether schedule is enabled
251
crontab (str): Cron expression
252
interval (str): Interval specification
253
one_off (bool): Whether job runs once
254
start_time (datetime): Schedule start time
255
user (User): User context for job execution
256
approval_required (bool): Whether approval is required
257
total_run_count (int): Total execution count
258
date_changed (datetime): Last modification date
259
description (str): Schedule description
260
kwargs (dict): Job arguments
261
queue (str): Execution queue
262
"""
263
264
class ScheduledJobs:
265
"""Scheduled job management utilities."""
266
```
267
268
### Data Sources
269
270
Git-based data source integration.
271
272
```python { .api }
273
class GitRepository:
274
"""
275
Git repositories for data source integration.
276
277
Attributes:
278
name (str): Repository name
279
slug (str): URL-safe slug
280
remote_url (str): Git remote URL
281
branch (str): Git branch
282
current_head (str): Current HEAD commit
283
provided_contents (list): Content types provided
284
secrets_group (SecretsGroup): Associated secrets
285
username (str): Git username
286
token (str): Git token/password
287
_token (str): Encrypted token
288
"""
289
```
290
291
### Configuration Management
292
293
Configuration context and schema management.
294
295
```python { .api }
296
class ConfigContext:
297
"""
298
Configuration context for objects.
299
300
Attributes:
301
name (str): Context name
302
weight (int): Context priority weight
303
description (str): Context description
304
is_active (bool): Whether context is active
305
schema (ConfigContextSchema): Validation schema
306
data (dict): Context data (JSON)
307
locations (list): Applicable locations
308
roles (list): Applicable roles
309
device_types (list): Applicable device types
310
platforms (list): Applicable platforms
311
cluster_groups (list): Applicable cluster groups
312
clusters (list): Applicable clusters
313
tenants (list): Applicable tenants
314
tags (list): Required tags
315
"""
316
317
class ConfigContextModel:
318
"""Base class for models supporting configuration context."""
319
320
class ConfigContextSchema:
321
"""
322
JSON schemas for configuration context validation.
323
324
Attributes:
325
name (str): Schema name
326
description (str): Schema description
327
data_schema (dict): JSON schema definition
328
slug (str): URL-safe slug
329
"""
330
```
331
332
### Object Relationships
333
334
Custom relationships between objects.
335
336
```python { .api }
337
class Relationship:
338
"""
339
Custom relationships between objects.
340
341
Attributes:
342
name (str): Relationship name
343
slug (str): URL-safe slug
344
description (str): Relationship description
345
type (str): Relationship type (one-to-one, one-to-many, many-to-many)
346
source_type (ContentType): Source object type
347
source_label (str): Source side label
348
source_hidden (bool): Whether source side is hidden
349
source_filter (dict): Source object filter
350
destination_type (ContentType): Destination object type
351
destination_label (str): Destination side label
352
destination_hidden (bool): Whether destination side is hidden
353
destination_filter (dict): Destination object filter
354
symmetric (bool): Whether relationship is symmetric
355
required_on (str): Which side requires the relationship
356
advanced_ui (bool): Whether to use advanced UI
357
"""
358
359
class RelationshipAssociation:
360
"""
361
Relationship associations between objects.
362
363
Attributes:
364
relationship (Relationship): Relationship definition
365
source_type (ContentType): Source object type
366
source_id (UUID): Source object ID
367
source (object): Source object
368
destination_type (ContentType): Destination object type
369
destination_id (UUID): Destination object ID
370
destination (object): Destination object
371
"""
372
373
class RelationshipModel:
374
"""Base class for models supporting relationships."""
375
```
376
377
### Contact Management
378
379
Contact and team management for object associations.
380
381
```python { .api }
382
class Contact:
383
"""
384
Contact information for object associations.
385
386
Attributes:
387
name (str): Contact name
388
phone (str): Phone number
389
email (str): Email address
390
address (str): Mailing address
391
comments (str): Additional comments
392
teams (list): Associated teams
393
"""
394
395
class ContactAssociation:
396
"""
397
Contact associations with objects.
398
399
Attributes:
400
contact (Contact): Associated contact
401
associated_object_type (ContentType): Associated object type
402
associated_object_id (UUID): Associated object ID
403
associated_object (object): Associated object
404
role (Role): Contact role
405
"""
406
407
class Team:
408
"""
409
Teams for contact organization.
410
411
Attributes:
412
name (str): Team name
413
phone (str): Team phone number
414
email (str): Team email address
415
address (str): Team address
416
comments (str): Team comments
417
contacts (list): Team members
418
"""
419
```
420
421
### Secrets Management
422
423
Secure storage and management of sensitive information.
424
425
```python { .api }
426
class Secret:
427
"""
428
Secure storage of sensitive information.
429
430
Attributes:
431
name (str): Secret name
432
slug (str): URL-safe slug
433
description (str): Secret description
434
provider (str): Secrets provider
435
parameters (dict): Provider-specific parameters
436
tags (list): Associated tags
437
"""
438
439
class SecretsGroup:
440
"""
441
Grouping of related secrets.
442
443
Attributes:
444
name (str): Group name
445
slug (str): URL-safe slug
446
description (str): Group description
447
secrets (list): Associated secrets
448
"""
449
450
class SecretsGroupAssociation:
451
"""
452
Secrets group associations.
453
454
Attributes:
455
group (SecretsGroup): Secrets group
456
secret (Secret): Associated secret
457
access_type (str): Access type (generic, environment-variable, etc.)
458
secret_type (str): Secret type (username, password, token, etc.)
459
"""
460
```
461
462
### Templates and Export
463
464
Template system for data export and formatting.
465
466
```python { .api }
467
class ExportTemplate:
468
"""
469
Export templates for data formatting.
470
471
Attributes:
472
content_type (ContentType): Target content type
473
name (str): Template name
474
description (str): Template description
475
template_code (str): Jinja2 template code
476
mime_type (str): Output MIME type
477
file_extension (str): Output file extension
478
as_attachment (bool): Whether to download as attachment
479
"""
480
481
class GraphQLQuery:
482
"""
483
Saved GraphQL queries.
484
485
Attributes:
486
name (str): Query name
487
slug (str): URL-safe slug
488
description (str): Query description
489
query (str): GraphQL query string
490
variables (dict): Query variables
491
"""
492
493
class CustomLink:
494
"""
495
Custom links for objects.
496
497
Attributes:
498
name (str): Link name
499
content_type (ContentType): Target content type
500
weight (int): Link ordering weight
501
group_name (str): Link group
502
button_class (str): CSS button class
503
new_window (bool): Whether to open in new window
504
link_text (str): Link text template
505
link_url (str): Link URL template
506
"""
507
```
508
509
### Webhook Integration
510
511
Webhook system for external integrations.
512
513
```python { .api }
514
class Webhook:
515
"""
516
Webhooks for external system integration.
517
518
Attributes:
519
name (str): Webhook name
520
content_types (list): Applicable content types
521
enabled (bool): Whether webhook is enabled
522
type_create (bool): Trigger on object creation
523
type_update (bool): Trigger on object update
524
type_delete (bool): Trigger on object deletion
525
payload_url (str): Webhook URL
526
http_method (str): HTTP method (GET, POST, PUT, PATCH, DELETE)
527
http_content_type (str): Content type header
528
additional_headers (str): Additional HTTP headers
529
body_template (str): Request body template
530
secret (str): Webhook secret
531
ssl_verification (bool): Whether to verify SSL certificates
532
ca_file_path (str): CA file path for SSL verification
533
"""
534
```
535
536
### File Management
537
538
File attachment and management system.
539
540
```python { .api }
541
class FileAttachment:
542
"""
543
File attachments for objects.
544
545
Attributes:
546
content_type (ContentType): Attached object type
547
object_id (UUID): Attached object ID
548
content_object (object): Attached object
549
file (FileField): Attached file
550
name (str): File name
551
created (datetime): Upload timestamp
552
"""
553
554
class ImageAttachment:
555
"""
556
Image attachments for objects.
557
558
Attributes:
559
content_type (ContentType): Attached object type
560
object_id (UUID): Attached object ID
561
content_object (object): Attached object
562
image (ImageField): Attached image
563
name (str): Image name
564
created (datetime): Upload timestamp
565
"""
566
567
class FileProxy:
568
"""File proxy for handling file operations."""
569
```
570
571
### Metadata System
572
573
Object metadata management.
574
575
```python { .api }
576
class MetadataType:
577
"""
578
Metadata type definitions.
579
580
Attributes:
581
name (str): Metadata type name
582
description (str): Type description
583
data_type (str): Data type (text, integer, boolean, etc.)
584
content_types (list): Applicable content types
585
"""
586
587
class MetadataChoice:
588
"""
589
Choices for metadata fields.
590
591
Attributes:
592
metadata_type (MetadataType): Parent metadata type
593
value (str): Choice value
594
weight (int): Choice ordering weight
595
"""
596
597
class ObjectMetadata:
598
"""
599
Object metadata associations.
600
601
Attributes:
602
metadata_type (MetadataType): Metadata type
603
content_type (ContentType): Object type
604
object_id (UUID): Object ID
605
content_object (object): Object
606
scoped_fields (list): Scoped field values
607
value (str): Metadata value
608
"""
609
```
610
611
### Dynamic Groups
612
613
Dynamic object grouping based on filters.
614
615
```python { .api }
616
class DynamicGroup:
617
"""
618
Dynamic object grouping based on filter criteria.
619
620
Attributes:
621
name (str): Group name
622
slug (str): URL-safe slug
623
description (str): Group description
624
content_type (ContentType): Group content type
625
filter (dict): Group filter criteria
626
children (list): Child groups
627
parent (DynamicGroup): Parent group
628
"""
629
630
class DynamicGroupMembership:
631
"""
632
Dynamic group membership tracking.
633
634
Attributes:
635
group (DynamicGroup): Dynamic group
636
parent_type (ContentType): Parent object type
637
parent_id (UUID): Parent object ID
638
parent_object (object): Parent object
639
operator (str): Membership operator
640
weight (int): Membership weight
641
"""
642
643
class StaticGroupAssociation:
644
"""
645
Static group associations.
646
647
Attributes:
648
associated_object_type (ContentType): Associated object type
649
associated_object_id (UUID): Associated object ID
650
associated_object (object): Associated object
651
"""
652
```
653
654
### Saved Views
655
656
User view customization and sharing.
657
658
```python { .api }
659
class SavedView:
660
"""
661
Saved views for customized object lists.
662
663
Attributes:
664
name (str): View name
665
slug (str): URL-safe slug
666
description (str): View description
667
content_type (ContentType): View content type
668
view (dict): View configuration
669
is_shared (bool): Whether view is shared
670
is_global_default (bool): Whether view is global default
671
"""
672
673
class UserSavedViewAssociation:
674
"""
675
User associations with saved views.
676
677
Attributes:
678
user (User): Associated user
679
saved_view (SavedView): Associated saved view
680
is_default (bool): Whether view is user default
681
"""
682
```
683
684
### External Integration
685
686
External system integration framework.
687
688
```python { .api }
689
class ExternalIntegration:
690
"""
691
External system integration definitions.
692
693
Attributes:
694
name (str): Integration name
695
remote_url (str): External system URL
696
verify_ssl (bool): Whether to verify SSL certificates
697
timeout (int): Request timeout in seconds
698
extra_config (dict): Additional configuration
699
secrets_group (SecretsGroup): Associated secrets
700
http_method (str): Default HTTP method
701
headers (dict): Default headers
702
"""
703
704
class HealthCheckTestModel:
705
"""Health check framework for system monitoring."""
706
```
707
708
### Notes System
709
710
Object notes and annotations.
711
712
```python { .api }
713
class Note:
714
"""
715
Notes and annotations for objects.
716
717
Attributes:
718
assigned_object_type (ContentType): Note target type
719
assigned_object_id (UUID): Note target ID
720
assigned_object (object): Note target object
721
user (User): Note author
722
created (datetime): Creation timestamp
723
slug (str): URL-safe slug
724
note (str): Note content
725
"""
726
```
727
728
## Usage Examples
729
730
### Custom Fields
731
732
```python
733
from nautobot.extras.models import CustomField
734
from nautobot.dcim.models import Device
735
736
# Create custom field
737
asset_tag_field = CustomField.objects.create(
738
type="text",
739
name="asset_tag",
740
label="Asset Tag",
741
description="Physical asset tag number",
742
required=True
743
)
744
745
# Add to device content type
746
from django.contrib.contenttypes.models import ContentType
747
device_ct = ContentType.objects.get_for_model(Device)
748
asset_tag_field.content_types.add(device_ct)
749
750
# Use custom field
751
device = Device.objects.get(name="router-01")
752
device.cf["asset_tag"] = "AST-001"
753
device.save()
754
755
# Query by custom field
756
devices_with_tag = Device.objects.filter(cf__asset_tag="AST-001")
757
```
758
759
### Job Creation
760
761
```python
762
from nautobot.extras.jobs import Job
763
from nautobot.dcim.models import Device
764
765
class DeviceHealthCheck(Job):
766
class Meta:
767
name = "Device Health Check"
768
description = "Check device health status"
769
770
def run(self):
771
self.log_info("Starting device health check")
772
773
devices = Device.objects.filter(status__name="Active")
774
healthy_count = 0
775
776
for device in devices:
777
# Health check logic here
778
if self.check_device_health(device):
779
healthy_count += 1
780
self.log_success(f"Device {device.name} is healthy")
781
else:
782
self.log_failure(f"Device {device.name} has issues")
783
784
result = f"Health check complete: {healthy_count}/{len(devices)} devices healthy"
785
self.log_info(result)
786
return result
787
788
def check_device_health(self, device):
789
# Custom health check logic
790
return True
791
```
792
793
### Relationships
794
795
```python
796
from nautobot.extras.models import Relationship, RelationshipAssociation
797
from nautobot.dcim.models import Device
798
from django.contrib.contenttypes.models import ContentType
799
800
# Create relationship
801
device_ct = ContentType.objects.get_for_model(Device)
802
backup_relationship = Relationship.objects.create(
803
name="device-backup",
804
type="one-to-one",
805
source_type=device_ct,
806
source_label="Primary Device",
807
destination_type=device_ct,
808
destination_label="Backup Device"
809
)
810
811
# Create association
812
primary_device = Device.objects.get(name="router-01")
813
backup_device = Device.objects.get(name="router-02")
814
815
RelationshipAssociation.objects.create(
816
relationship=backup_relationship,
817
source=primary_device,
818
destination=backup_device
819
)
820
```
821
822
### Webhooks
823
824
```python
825
from nautobot.extras.models import Webhook
826
from django.contrib.contenttypes.models import ContentType
827
from nautobot.dcim.models import Device
828
829
# Create webhook
830
device_ct = ContentType.objects.get_for_model(Device)
831
webhook = Webhook.objects.create(
832
name="Device Change Notification",
833
payload_url="https://api.example.com/nautobot-webhook",
834
http_method="POST",
835
enabled=True,
836
type_create=True,
837
type_update=True,
838
type_delete=True,
839
body_template='{"event": "{{ event_type }}", "device": "{{ data.name }}"}',
840
secret="webhook-secret-key"
841
)
842
843
webhook.content_types.add(device_ct)
844
```
845
846
### Configuration Context
847
848
```python
849
from nautobot.extras.models import ConfigContext
850
851
# Create configuration context
852
config_context = ConfigContext.objects.create(
853
name="SNMP Config",
854
weight=1000,
855
data={
856
"snmp": {
857
"community": "public",
858
"version": "2c",
859
"contact": "admin@example.com"
860
}
861
}
862
)
863
864
# Apply to specific roles
865
from nautobot.extras.models import Role
866
router_role = Role.objects.get(name="Router")
867
config_context.roles.add(router_role)
868
869
# Access context on device
870
device = Device.objects.get(name="router-01")
871
context_data = device.get_config_context()
872
snmp_config = context_data.get("snmp", {})
873
```