Skip to content

docs: explain typed custom fields and Jinja2 templating (INT-415)#1573

Draft
ldrozdz93 wants to merge 1 commit into
netbox-community:develfrom
ldrozdz93:int-415-custom-field-jinja2-docs
Draft

docs: explain typed custom fields and Jinja2 templating (INT-415)#1573
ldrozdz93 wants to merge 1 commit into
netbox-community:develfrom
ldrozdz93:int-415-custom-field-jinja2-docs

Conversation

@ldrozdz93

Copy link
Copy Markdown
Collaborator

What this does

Adds a Custom Fields section to the "Using Modules" guide explaining how the custom_fields argument 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 integer 3.

This is ansible-core templating behaviour, not something the collection controls:

  • Before ansible-core 2.19, non-native Jinja is the default and the output of any Jinja2 filter is rendered back to a string — so "{{ rack_units | default(omit) }}", and even "{{ rack_units | int }}", produce "3".
  • Starting with ansible-core 2.19, native Jinja is the default and can no longer be turned off, so templated values keep their Python type and typed custom fields work with no extra steps.

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_native setting (via ansible.cfg or ANSIBLE_JINJA2_NATIVE=1) as the workaround for older ansible-core.

Verification

Reproduced the templating behaviour with ansible-playbook on both ansible-core versions in the CI matrix (variable value 3):

Template ansible-core 2.18.1 ansible-core 2.19.10
{{ x }} 3 (int) 3 (int)
{{ x | default(omit) }} "3" (str) ✗ 3 (int) ✓
{{ x | int }} "3" (str) ✗ 3 (int) ✓

With ANSIBLE_JINJA2_NATIVE=1 on 2.18.1 all three return the integer 3, matching the 2.19 default — confirming the documented workaround.

antsibull-changelog lint passes.

Background: #985

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>

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants