Repository navigation
Correct userdocs regarding optional survey variables - #1179
versteht-nur-bahnhof wants to merge 1 commit into
Conversation
There was a problem hiding this comment.
🟡 Changes recommended
The migration notes omit the zero-minimum-length qualification, incorrectly suggesting that unanswered Text/Textarea questions with a positive minimum also need the workaround.
1 open issue
What changed in this PR
Updates the job and workflow template guides to reflect the optional survey variable behavior introduced by #242.
Changes:
- Removes outdated rules for passing unanswered optional survey variables.
- Adds migration notes describing earlier behavior and a Template Variables workaround for playbooks that expect empty strings.
| File | Description |
|---|---|
| docs/docsite/rst/userguide/workflow_templates.rst | Replaces outdated survey rules with workflow template migration guidance. |
| docs/docsite/rst/userguide/job_templates.rst | Adds matching migration guidance for job template surveys. |
Review effort: Balanced
|
Thanks for this, the current docs are indeed wrong. I checked it against the code and on a live instance:
"25.3.4 and earlier" is also correct, since 25.3.5 is the first tag with #242. Two changes I'd like before merging (suggestions inline):
Minor: the edit leaves two extra blank lines after the note in both files. |
There was a problem hiding this comment.
Suggest stating the current behavior first, and limiting the old behavior to questions with a minimum length of 0 (min > 0 questions were never passed when left blank):
| If an optional survey question is left unanswered, its variable is not passed to the playbook at all, so the playbook must handle it being undefined, for example with ``{{ my_var | default('') }}``. | |
| .. note:: | |
| In Ascender 25.3.4 and earlier, optional *Text* and *Textarea* questions with a minimum length of 0 were passed to the playbook as an empty string ( "" ) when left unanswered. If a playbook relies on this and cannot be updated, add a matching entry with an empty string value to the Template Variables, for example ``my_var: ""``. A survey answer still overrides it. |
There was a problem hiding this comment.
Sounds good to me. I also added another clause about the variables remaining unset even with a nonzero minimum length on the current version, which makes perfect sense but still confused me at least for a moment.
There was a problem hiding this comment.
Same as in job_templates.rst, since workflow templates use the same survey code:
| If an optional survey question is left unanswered, its variable is not passed to the playbook at all, so the playbook must handle it being undefined, for example with ``{{ my_var | default('') }}``. | |
| .. note:: | |
| In Ascender 25.3.4 and earlier, optional *Text* and *Textarea* questions with a minimum length of 0 were passed to the playbook as an empty string ( "" ) when left unanswered. If a playbook relies on this and cannot be updated, add a matching entry with an empty string value to the Template Variables, for example ``my_var: ""``. A survey answer still overrides it. |
Signed-off-by: Jerome Garin <jerome.garin@muenchen.de>
5eee742 to
6acffc9
Compare

SUMMARY
The current behaviour (since #242) is to not pass optional survey variables if their value is an empty string, regardless of the variable's type or minimum length, so the existing userdocs seem to be incorrect. This patch removes the wrong description and adds a note for users used to the previous behaviour, which is also the behaviour of the latest AWX release.
I'm not sure if it's a good idea to document the workaround of attaching empty string variables to the job template, since users running into issues with this should really just update their playbooks to handle undefined variables. But my experience is that for various reasons some users really don't want to change their Ansible code if at all possible, and this is something that I would expect most large-ish orgs migrating from AWX to run into at some scale.
ISSUE TYPE
COMPONENT NAME
ASCENDER VERSION
ADDITIONAL INFORMATION
none