Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
8ctorres opened this issue Feb 2, 2024 · 4 comments · May be fixed by #15651
Assignees
Labels
status: accepted This issue has been accepted for implementation type: documentation A change or addition to the documentation

Comments

@8ctorres
Copy link

8ctorres commented Feb 2, 2024

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!!

@8ctorres 8ctorres added the type: documentation A change or addition to the documentation label Feb 2, 2024
@zndrr
Copy link

zndrr commented Feb 3, 2024

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

  1. There's also the UI import forms when mass adding objects for attr lists for easyish digestion.
  2. 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:
#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
Copy link
Author

8ctorres commented Feb 3, 2024

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.

@jeremystretch jeremystretch added the status: needs triage This issue is awaiting triage by a maintainer label Mar 26, 2024
@jeffgdotorg
Copy link
Collaborator

@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
Copy link
Author

8ctorres commented Apr 4, 2024

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?

@jeremystretch jeremystretch added status: accepted This issue has been accepted for implementation and removed status: needs triage This issue is awaiting triage by a maintainer labels Apr 5, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
status: accepted This issue has been accepted for implementation type: documentation A change or addition to the documentation
Projects
None yet
Development

Successfully merging a pull request may close this issue.

4 participants