Documentation is unclear on how to access data structures in Scripts/Reports/Config Templates/Export Templates

[8ctorres]

trafficstars

Change Type

Addition

Area

Customization

Proposed Changes

Hi!

First of all, sorry is this is my falt for not seeing it correctly.

The issue is, I'm starting to dive into the customization/scripting capabilities of Netbox, like Reports and Config Templates, and I'm having a very hard time knowing how to access the data from Netbox itself, since the documentation only provides a very simple example. I don't know which "objects" are accesible from a config template, nor I know what fields those objects have or the information they contain, or the methods they have.

For example: In a config template for a router that has several circuits connected, I want to know the bandwidth of each circuit in order to configure QoS in the router. How do I do that? I know (and I only know it from the example) that I can access "device.interfaces.all()". And from there? What does the data structure for "interface" look like? What other fields are there in the "device" object besides the obvious name, type, role... etc? What other methods, besides "all()" are there. Is there a filter? What's the syntax for it?

There are a lot of unanswered questions. If this information can be found somewhere, even if it's buried in the source code, I would be happy to contribute to the documentation page by summarizing it, so that newcomers don't get frustrated trying to find it. I just need somebody to tell me where to look.

Thanks!!

[zndrr]

Without looking at proper NetBox doc resources for you, might pay to poke around in NetBox Shell:

source /opt/netbox/venv/bin/activate
python3 /opt/netbox/netbox/manage.py nbshell

# In nbshell
lsmodels()
help(_input_model_here_)

e.g. help(Interface)
# help(Interface) provides a manpage-like document

2. There's also the UI import forms when mass adding objects for attr lists for easyish digestion.
3. And host API schema: https://{your_netbox_host}/api/schema/swagger-ui/

In nbshell you can also try your code. If you access an object then you can print available attrs interactively. Be careful though, you can also change them...

Interfaces

intf = Interface.objects.get(id=1004)

dir(intf)  # Prints list of attributes
- OR -
intf.? (outputs to terminal all context-help like)

# Can access attrs directly, printing to terminal
intf.id
intf.speed
print(getattr(intf, 'speed'))  # Note: getattr useful in loops

# Loop through interfaces printing intf+speed to terminal
for i in Interface.objects.all():  # Refine your query or nest inside another loop.
    i_speed = f'Interface: {i.name}, Speed: {getattr(i, "speed")}'  # Formatted for print
    print(i_speed)

output eg:
| Interface: ether1, Speed: None
| Interface: ether2, Speed: None
| ... etc

... essentially several ways to go about it. Probably some more efficient ways too.

Back to config templates, I was involved in a discussion historically that provided great insight: https://github.com/netbox-community/netbox/discussions/12568 Uses Jinja2, but you can typically massage the queries similarly.

Disclaimer: Uneducated, unaffiliated peasant and fellow NB scripter. I normally do nbshell experimentation to get where I want. YMMV, hope this helps a little

P.S. I suspect this may move to a Discussion rather than a Bug.

[8ctorres]

There is a netbox interactive shell! Fellow internet stranger, you have officially made my day. This will help me so much. This week I've spent a fair amount of time looking at the source code, specially the models, just to figure out which attributes and methods the objects have.

Thank you!

I might even write some documentation about this and to a PR to include this, since I can say I've read most of (if not all) of the documentation, and I did not know about the nbshell.

[jeffgdotorg]

@8ctorres I'm so glad to hear that you found nbshell useful! Are you still interested in contributing a documentation PR to help fellow travelers become aware of it from the official docs?

[8ctorres]

Hello @jeffgdotorg

Absolutely. I’ve been busy at work this last few weeks (mostly developing config templates, reports and scripts for Netbox), but I will try to make some time this weekend a write a page for the documentation to include a section about the nbshell. I really think it would help newcomers to start coding their own scripts.

Is there anything I should know before starting to write?