How to create a Survey?

1. Navigate to Templates → Your Job Template

Ansible AWX Survey — Prompt Users for Input at Launch

Introduction

AWX surveys let you add a form to job templates — users fill in variables (environment, server name, version) before launch without editing playbooks or inventory. Surveys turn complex automation into self-service buttons that anyone on the team can use safely.

Create a Survey

Navigate to Templates → Your Job Template
Click the Survey tab
Click Add
Define questions (fields)

Field Types

Type	Use Case	Example
Text	Free-form input	Server hostname
Textarea	Multi-line input	SSH public key
Password	Hidden input	Database password
Integer	Numeric input	Port number
Float	Decimal input	CPU threshold
Multiple Choice (single)	Dropdown select	Environment: dev/staging/prod
Multiple Choice (multiple)	Multi-select	Services to restart

Survey Configuration Example

Environment Selection

# Survey question 1
Question: "Target Environment"
Variable: target_env
Type: Multiple Choice (single select)
Choices:
  - development
  - staging
  - production
Default: development
Required: Yes

Server Name

# Survey question 2
Question: "Server hostname"
Variable: server_name
Type: Text
Min Length: 3
Max Length: 64
Default: ""
Required: Yes

Version to Deploy

# Survey question 3
Question: "Application version"
Variable: app_version
Type: Text
Default: "latest"
Required: Yes

Database Password

# Survey question 4
Question: "Database admin password"
Variable: db_password
Type: Password
Required: Yes
# Password values are encrypted, never shown in logs

Use Survey Variables in Playbooks

---
- name: Deploy application
  hosts: "{{ target_env }}_servers"
  vars:
    # These come from the survey at launch time:
    # target_env, server_name, app_version, db_password
  tasks:
    - name: Deploy version
      ansible.builtin.debug:
        msg: "Deploying {{ app_version }} to {{ server_name }} in {{ target_env }}"

    - name: Pull application image
      community.docker.docker_image:
        name: "myapp:{{ app_version }}"
        source: pull

    - name: Configure database
      ansible.builtin.template:
        src: db.conf.j2
        dest: /etc/myapp/db.conf
      vars:
        db_pass: "{{ db_password }}"
      no_log: true

Survey API

Get Survey Spec

curl -s -H "Authorization: Bearer $AWX_TOKEN" \
  https://awx.example.com/api/v2/job_templates/42/survey_spec/ | jq

Set Survey Spec Programmatically

---
- name: Configure survey via API
  hosts: localhost
  vars:
    awx_host: https://awx.example.com
    awx_token: "{{ lookup('env', 'AWX_TOKEN') }}"
  tasks:
    - name: Set survey on job template
      ansible.builtin.uri:
        url: "{{ awx_host }}/api/v2/job_templates/42/survey_spec/"
        method: POST
        headers:
          Authorization: "Bearer {{ awx_token }}"
          Content-Type: application/json
        body_format: json
        body:
          name: "Deployment Survey"
          description: "Collects deployment parameters"
          spec:
            - question_name: "Target Environment"
              question_description: "Which environment to deploy to"
              variable: "target_env"
              type: "multiplechoice"
              required: true
              choices: ["development", "staging", "production"]
              default: "development"
            - question_name: "Application Version"
              question_description: "Docker image tag to deploy"
              variable: "app_version"
              type: "text"
              required: true
              min: 1
              max: 32
              default: "latest"
            - question_name: "Notify Slack"
              question_description: "Send deployment notification"
              variable: "notify_slack"
              type: "multiplechoice"
              required: false
              choices: ["yes", "no"]
              default: "yes"

Launch with Survey Answers

curl -X POST -H "Authorization: Bearer $AWX_TOKEN" \
  -H "Content-Type: application/json" \
  https://awx.example.com/api/v2/job_templates/42/launch/ \
  -d '{
    "extra_vars": {
      "target_env": "production",
      "app_version": "2.1.0",
      "notify_slack": "yes"
    }
  }'

Variable Precedence

Survey variables are injected as extra vars — highest precedence:

1. Survey answers (extra_vars)    ← HIGHEST
2. Job Template extra_vars
3. Inventory variables
4. Playbook vars
5. Role defaults                  ← LOWEST

⚠️ Survey variables override anything set in the playbook, inventory, or roles.

Validation

Setting	Effect
Required	Field must be filled before launch
Min/Max Length	Text field character limits
Min/Max Value	Integer/float range validation
Default	Pre-filled value (user can change)
Choices	Restricts to predefined options

Real-World Survey Examples

Self-Service VM Provisioning

Question: VM Name (text, required, 3-15 chars)
Question: OS (dropdown: ubuntu-22.04, rhel-9, windows-2022)
Question: Size (dropdown: small/medium/large)
Question: Team (dropdown: engineering/marketing/finance)
Question: Owner Email (text, required)

Database Operations

Question: Operation (dropdown: backup/restore/migrate/vacuum)
Question: Database Name (text, required)
Question: Confirm destructive action (dropdown: yes/no, default: no)

Certificate Renewal

Question: Domain (text, required)
Question: Environment (dropdown: staging/production)
Question: Force renewal (dropdown: yes/no, default: no)

Troubleshooting

Issue	Solution
Survey variable empty in playbook	Check variable name matches exactly (case-sensitive)
Can't override survey var	Survey extra_vars take highest precedence by design
Password shows in job output	Add `no_log: true` to tasks using password vars
Survey not showing at launch	Enable "Survey Enabled" toggle on job template
Default value ignored	Ensure default matches one of the choices (for dropdowns)

Best Practices

Set sensible defaults — users should be able to launch with minimal changes
Use dropdowns over free text — prevents typos and invalid input
Mark passwords as Password type — encrypts storage and hides in logs
Add descriptions — explain what each field does
Validate ranges — use min/max to prevent out-of-bounds values
Keep surveys short — 3-5 questions max; more = people won't use it
Use no_log: true in tasks that use sensitive survey variables

Conclusion

AWX surveys turn automation into self-service. Users fill in a form — environment, version, server name — and launch jobs without editing code. Use dropdowns to prevent errors, password fields for secrets, and defaults for common cases. Access survey variables in playbooks as regular extra_vars. Keep surveys short and well-documented for team adoption.