docs: explain typed custom fields and Jinja2 templating (INT-415)#1573
Draft
ldrozdz93 wants to merge 1 commit into
Draft
docs: explain typed custom fields and Jinja2 templating (INT-415)#1573ldrozdz93 wants to merge 1 commit into
ldrozdz93 wants to merge 1 commit into
Conversation
Integer/boolean custom-field values set from a Jinja2 expression are
rejected by NetBox on ansible-core < 2.19 because non-native Jinja
renders filter output back to a string ("3" instead of 3). ansible-core
2.19 makes native Jinja the default and non-disableable, so templated
values keep their Python type and typed custom fields work as-is.
Add a Custom Fields section to the "Using Modules" guide covering the
behaviour, the exact NetBox error, the ansible-core >= 2.19 default, and
the jinja2_native workaround for older ansible-core.
Documents netbox-community#985
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this does
Adds a Custom Fields section to the "Using Modules" guide explaining how the
custom_fieldsargument works and how typed custom fields (integer, boolean, …) behave when their values come from Jinja2 expressions.Why
NetBox validates each custom-field value against the type declared for that field. A long-standing complaint is that an integer custom field set from a Jinja2 expression is rejected with
Invalid value for custom field '...': Value must be an integer., because the value arrives as the string"3"instead of the integer3.This is ansible-core templating behaviour, not something the collection controls:
"{{ rack_units | default(omit) }}", and even"{{ rack_units | int }}", produce"3".The new docs section shows how to set custom fields, explains the typed-value/Jinja2 interaction and the exact error users hit, notes that ansible-core ≥ 2.19 needs nothing extra, and gives the
jinja2_nativesetting (viaansible.cfgorANSIBLE_JINJA2_NATIVE=1) as the workaround for older ansible-core.Verification
Reproduced the templating behaviour with
ansible-playbookon both ansible-core versions in the CI matrix (variable value3):{{ x }}3(int)3(int){{ x | default(omit) }}"3"(str) ✗3(int) ✓{{ x | int }}"3"(str) ✗3(int) ✓With
ANSIBLE_JINJA2_NATIVE=1on 2.18.1 all three return the integer3, matching the 2.19 default — confirming the documented workaround.antsibull-changelog lintpasses.Background: #985