From a0712e66bee09f31ec800bba7a32322eb5d3ff87 Mon Sep 17 00:00:00 2001 From: 8ctorres Date: Sun, 7 Apr 2024 12:00:11 +0000 Subject: [PATCH] Add references to Nbshell in export templates, reports and scripts --- docs/administration/netbox-shell.md | 36 +++++++++++++++++++++++- docs/customization/export-templates.md | 2 ++ docs/features/configuration-rendering.md | 2 ++ 3 files changed, 39 insertions(+), 1 deletion(-) diff --git a/docs/administration/netbox-shell.md b/docs/administration/netbox-shell.md index 21cef01b2..8a62c2a3c 100644 --- a/docs/administration/netbox-shell.md +++ b/docs/administration/netbox-shell.md @@ -1,6 +1,6 @@ # The NetBox Python Shell -NetBox includes a Python management shell within which objects can be directly queried, created, modified, and deleted. To enter the shell, run the following command: +NetBox includes a Python management shell within which objects can be directly queried, created, modified, and deleted. To enter the shell, run the following command from a shell that has the netbox virtualenv activated: ``` ./manage.py nbshell @@ -143,6 +143,40 @@ To return the inverse of a filtered queryset, use `exclude()` instead of `filter 346 ``` +If the query returns only one object, the get() method can be used. This method will yield the actual object resulting from the query, instead of a QuerySet. For this to work, the query must return only one object. The syntax is identical to the filter and exclude methods. For example, we can get a device from it's asset tag: + +``` +>>> +>>> Device.objects.get(asset_tag="100079912515") + +>>> +``` + +If the query returns more than one object, a MultipleObjectsReturned exception will be thrown: + +``` +>>> Device.objects.get(role_id=13) +Traceback (most recent call last): + File "", line 1, in + File "/srv/netbox/venv/lib/python3.10/site-packages/django/db/models/manager.py", line 87, in manager_method + return getattr(self.get_queryset(), name)(*args, **kwargs) + File "/srv/netbox/venv/lib/python3.10/site-packages/django/db/models/query.py", line 640, in get + raise self.model.MultipleObjectsReturned( +dcim.models.devices.Device.MultipleObjectsReturned: get() returned more than one Device -- it returned more than 20! +>>> +``` + +Queries can all also be executed from a particular object instead of from the model itself. For instance, to get all circuits that are assigned to one site, it is easier to filter from the site itself, instead of using the "Circuit" model and building the query from there. This is particularly useful for configuration templates and export templates, since it allows to query other database objects that are related to the object that we're rendering the template for. + +``` +>>> site.circuit_terminations.all() +, ]> +>>> +``` + +The same methods (all, filter, exclude, get...) can be used in this kind of queries. + + !!! info The examples above are intended only to provide a cursory introduction to queryset filtering. For an exhaustive list of the available filters, please consult the [Django queryset API documentation](https://docs.djangoproject.com/en/stable/ref/models/querysets/). diff --git a/docs/customization/export-templates.md b/docs/customization/export-templates.md index 640a97531..8be160011 100644 --- a/docs/customization/export-templates.md +++ b/docs/customization/export-templates.md @@ -32,6 +32,8 @@ If you need to use the config context data in an export template, you'll should {% endfor %} ``` +To see all the attributes of a given object, you can use the [Netbox Shell](../administration/netbox-shell.md). It supports autocompletion and allows one to see all of the methods and attributes a given object type has. All of them can be called from within a Jinja template. Using queries from one object to another, one can navigate pretty much the entire Netbox object model. For instance, from an export template for sites, one can get the devices that are in that site, the circuits that are connected to those devices, the providers that serve those circuits... etc, so an export template is not limited to just the model that it's being called from. In fact, the same result can be achieved in different ways, depending on which model you start from. + The `as_attachment` attribute of an export template controls its behavior when rendered. If true, the rendered content will be returned to the user as a downloadable file. If false, it will be displayed within the browser. (This may be handy e.g. for generating HTML content.) A MIME type and file extension can optionally be defined for each export template. The default MIME type is `text/plain`. diff --git a/docs/features/configuration-rendering.md b/docs/features/configuration-rendering.md index 44cacc684..2ebc0f25e 100644 --- a/docs/features/configuration-rendering.md +++ b/docs/features/configuration-rendering.md @@ -35,6 +35,8 @@ Configuration templates are written in the [Jinja2 templating language](https:// {% endblock %} ``` +To see all the attributes of a given object, you can use the [Netbox Shell](../administration/netbox-shell.md). It supports autocompletion and allows one to see all of the methods and attributes a given object type has. All of them can be called from within the configuration template. Also, other objects, for instance, a device's interfaces or connected circuits can be accessed from the template itself, so the rendered configuration may include information not only about the device itself, but also related objects like IP addresses or circuits. + When rendered for a specific NetBox device, the template's `device` variable will be populated with the device instance, and `ntp_servers` will be pulled from the device's available context data. The resulting output will be a valid configuration segment that can be applied directly to a compatible network device. ### Context Data