Skip to content

Correct userdocs regarding optional survey variables - #1179

Open
versteht-nur-bahnhof wants to merge 1 commit into
ctrliq:mainfrom
versteht-nur-bahnhof:userdocs
Open

versteht-nur-bahnhof wants to merge 1 commit into
ctrliq:mainfrom
versteht-nur-bahnhof:userdocs

Conversation

@versteht-nur-bahnhof

@versteht-nur-bahnhof versteht-nur-bahnhof commented Nov 4, 2026 •

Copy link
Copy Markdown
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
  • Bug, Docs Fix or other nominal change
COMPONENT NAME
  • Docs
ASCENDER VERSION
awx: 0.1.dev1123+g80b2b64e5
ADDITIONAL INFORMATION

none

@cigamit cigamit self-assigned this Nov 10, 2026
@cigamit
cigamit requested a balanced review from Copilot November 10, 2026 06:40

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🟡 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

@cigamit

cigamit commented Nov 10, 2026

Copy link
Copy Markdown
Collaborator

Thanks for this, the current docs are indeed wrong. I checked it against the code and on a live instance:

  • Since Upstream 16289 - Do not add optional survey fields with empty strings #242 (in 25.3.5), _update_unified_job_kwargs skips an optional, non-password survey variable whose default is "" when the launch doesn't supply a value. The old bullets described the behavior before that change.
  • The UI never sends blank answers (getSurveyValues drops ""), so for UI launches an unanswered optional question now means the variable is not passed at all.
  • I launched a job template and a workflow template with optional Text (min 0 and min 5), Textarea, Integer and Multiple Choice questions. With no answers, no survey variables were passed. The workaround works: my_var: "" in the template variables reaches the job, and a real survey answer still overrides it.

"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):

  1. Add the minimum-length condition. Before 25.3.5, unanswered Text/Textarea questions were only passed when their minimum length was 0. With a minimum above 0 they failed validation and were never passed, and that hasn't changed. Without this, users with min > 0 questions may add a workaround they don't need.
  2. Describe the current behavior, not only the old one. Right now the section only talks about 25.3.4 and earlier. I'd add a sentence saying the variable is not passed and that playbooks should handle it being undefined. That puts the proper fix (| default('')) first and the workaround second, which I think also covers your concern about documenting it.

Minor: the edit leaves two extra blank lines after the note in both files.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

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):

Suggested change
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.

@versteht-nur-bahnhof versteht-nur-bahnhof Nov 13, 2026 •

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

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

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.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Same as in job_templates.rst, since workflow templates use the same survey code:

Suggested change
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.

@cigamit cigamit added the Needs triage When a Issue needs to be researched or a PR has an issue that needs fixing before merging label Nov 10, 2026
Signed-off-by: Jerome Garin <jerome.garin@muenchen.de>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Needs triage When a Issue needs to be researched or a PR has an issue that needs fixing before merging

Development

Successfully merging this pull request may close these issues.

3 participants