Surveys - AWX

Surveys provide a user-friendly way to collect input when launching job templates and workflow job templates. Instead of requiring users to write YAML/JSON extra variables, surveys present a form with validation.

Understanding Surveys

A Survey is a set of questions presented to users before launching a job. Survey responses are:

Passed as extra variables to the playbook
Validated according to defined rules
Stored with job history
Can be required or optional
Support multiple input types

Use Cases

Application Deployment

Prompt for version, environment, branch

Server Provisioning

Collect hostname, IP, region, size

User Management

Ask for username, email, groups

Configuration Changes

Request service name, port, protocol

Survey Question Types

Free-form text input

type: text
question_name: Application Name
variable: app_name
required: true
default: myapp
min: 3
max: 50

Best for: Names, URLs, paths

Sensitive text input (masked)

type: password
question_name: Database Password
variable: db_password
required: true

Best for: Passwords, tokens, secrets

Password values are encrypted in the database

Whole number input

type: integer
question_name: Number of Instances
variable: instance_count
required: true
default: 1
min: 1
max: 10

Best for: Counts, ports, IDs

Decimal number input

type: float
question_name: Memory Limit (GB)
variable: memory_gb
required: false
default: 2.5
min: 0.5
max: 64.0

Best for: Percentages, resource limits, ratios

Select one option from a list

type: multiplechoice
question_name: Environment
variable: environment
required: true
choices:
  - dev
  - staging
  - production
default: dev

Best for: Environments, regions, sizes

Select multiple options from a list

type: multiselect
question_name: Features to Enable
variable: features
required: false
choices:
  - monitoring
  - backup
  - ssl
  - cdn
default: "monitoring\nbackup"

Best for: Tags, features, components

Default uses newline-separated values

Creating a Survey

Create the Survey Specification

A survey specification is a JSON object with name, description, and spec (array of questions):

{
  "name": "Deployment Survey",
  "description": "Collect deployment parameters",
  "spec": [
    {
      "type": "text",
      "question_name": "Application Version",
      "question_description": "Version to deploy (e.g., 2.0.1)",
      "variable": "app_version",
      "required": true,
      "default": "",
      "min": 0,
      "max": 50
    },
    {
      "type": "multiplechoice",
      "question_name": "Target Environment",
      "question_description": "Which environment to deploy to",
      "variable": "environment",
      "required": true,
      "choices": ["dev", "staging", "production"],
      "default": "dev"
    },
    {
      "type": "multiselect",
      "question_name": "Deploy Components",
      "question_description": "Select components to deploy",
      "variable": "components",
      "required": false,
      "choices": ["api", "web", "worker", "scheduler"],
      "default": "api\nweb"
    }
  ]
}

Add Survey to Job Template

Web UI
API
Ansible

Navigate to your job template
Click the Survey tab
Click Add
For each question:
- Select question type
- Fill in question details
- Set variable name
- Configure validation
Click Save
Toggle Survey Enabled

# Create survey spec
curl -X POST https://awx.example.com/api/v2/job_templates/1/survey_spec/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d @survey_spec.json

# Enable survey
curl -X PATCH https://awx.example.com/api/v2/job_templates/1/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"survey_enabled": true}'

- name: Create job template with survey
  awx.awx.job_template:
    name: Deploy Application
    project: Infrastructure Playbooks
    playbook: deploy.yml
    inventory: Production Servers
    survey_enabled: true
    survey_spec:
      name: Deployment Survey
      description: Collect deployment parameters
      spec:
        - type: text
          question_name: Application Version
          question_description: Version to deploy
          variable: app_version
          required: true
          default: ""
        - type: multiplechoice
          question_name: Target Environment
          question_description: Environment to deploy to
          variable: environment
          required: true
          choices:
            - dev
            - staging  
            - production
          default: dev
    state: present

Launch with Survey Responses

When launching a job with a survey, provide answers:

curl -X POST https://awx.example.com/api/v2/job_templates/1/launch/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "extra_vars": {
      "app_version": "2.1.0",
      "environment": "production",
      "components": ["api", "web", "worker"]
    }
  }'

With Ansible:

- name: Launch job with survey responses
  awx.awx.job_launch:
    job_template: Deploy Application
    extra_vars:
      app_version: "2.1.0"
      environment: production
      components:
        - api
        - web
        - worker
    wait: true

Survey Validation

Text Validation

{
  "type": "text",
  "variable": "hostname",
  "min": 5,        // Minimum length
  "max": 63,       // Maximum length
  "required": true,
  "default": "server01"
}

Integer Validation

{
  "type": "integer",
  "variable": "port",
  "min": 1,        // Minimum value
  "max": 65535,    // Maximum value
  "required": true,
  "default": 8080
}

Float Validation

{
  "type": "float",
  "variable": "cpu_limit",
  "min": 0.1,      // Minimum value
  "max": 16.0,     // Maximum value
  "required": false,
  "default": 1.0
}

Multiple Choice Validation

{
  "type": "multiplechoice",
  "variable": "size",
  "choices": ["small", "medium", "large"],
  "required": true,
  "default": "medium"
}

The selected value must be one of the defined choices

Multi-Select Validation

{
  "type": "multiselect",
  "variable": "tags",
  "choices": ["web", "api", "db", "cache"],
  "required": false,
  "default": "web\napi"  // Newline-separated defaults
}

Using Survey Variables in Playbooks

Survey responses are available as extra variables:

---
- name: Deploy Application
  hosts: "{{ environment }}_servers"
  vars:
    version: "{{ app_version }}"
  
  tasks:
    - name: Display deployment info
      debug:
        msg: "Deploying version {{ app_version }} to {{ environment }}"
    
    - name: Deploy components
      include_tasks: "deploy_{{ item }}.yml"
      loop: "{{ components }}"
      when: components is defined
    
    - name: Configure application
      template:
        src: app.conf.j2
        dest: /etc/app/config.ini
      vars:
        app_version: "{{ app_version }}"
        environment: "{{ environment }}"

Advanced Survey Examples

Complete Deployment Survey

{
  "name": "Application Deployment",
  "description": "Complete deployment configuration",
  "spec": [
    {
      "type": "text",
      "question_name": "Application Version",
      "question_description": "Semantic version (e.g., 2.1.0)",
      "variable": "app_version",
      "required": true,
      "min": 5,
      "max": 20,
      "default": ""
    },
    {
      "type": "multiplechoice",
      "question_name": "Environment",
      "question_description": "Target deployment environment",
      "variable": "environment",
      "required": true,
      "choices": ["dev", "qa", "staging", "production"],
      "default": "dev"
    },
    {
      "type": "text",
      "question_name": "Git Branch",
      "question_description": "Git branch or tag to deploy",
      "variable": "git_branch",
      "required": false,
      "default": "main",
      "min": 1,
      "max": 100
    },
    {
      "type": "multiselect",
      "question_name": "Services",
      "question_description": "Services to restart after deployment",
      "variable": "restart_services",
      "required": false,
      "choices": ["nginx", "gunicorn", "celery", "redis"],
      "default": "gunicorn\ncelery"
    },
    {
      "type": "multiplechoice",
      "question_name": "Run Migrations",
      "question_description": "Run database migrations?",
      "variable": "run_migrations",
      "required": true,
      "choices": ["yes", "no"],
      "default": "yes"
    },
    {
      "type": "integer",
      "question_name": "Timeout",
      "question_description": "Deployment timeout in seconds",
      "variable": "deploy_timeout",
      "required": false,
      "default": 300,
      "min": 60,
      "max": 3600
    }
  ]
}

Server Provisioning Survey

{
  "name": "Server Provisioning",
  "description": "Provision new server instance",
  "spec": [
    {
      "type": "text",
      "question_name": "Server Name",
      "question_description": "Hostname for the new server",
      "variable": "server_name",
      "required": true,
      "min": 3,
      "max": 63
    },
    {
      "type": "multiplechoice",
      "question_name": "Instance Size",
      "question_description": "Server size/tier",
      "variable": "instance_size",
      "required": true,
      "choices": ["t3.small", "t3.medium", "t3.large", "t3.xlarge"],
      "default": "t3.medium"
    },
    {
      "type": "multiplechoice",
      "question_name": "Region",
      "question_description": "AWS region",
      "variable": "aws_region",
      "required": true,
      "choices": ["us-east-1", "us-west-2", "eu-west-1", "ap-southeast-1"],
      "default": "us-east-1"
    },
    {
      "type": "multiselect",
      "question_name": "Security Groups",
      "question_description": "Security groups to assign",
      "variable": "security_groups",
      "required": true,
      "choices": ["web", "ssh", "monitoring", "backup"],
      "default": "web\nssh\nmonitoring"
    },
    {
      "type": "integer",
      "question_name": "Disk Size",
      "question_description": "Root volume size in GB",
      "variable": "disk_size_gb",
      "required": true,
      "default": 50,
      "min": 20,
      "max": 500
    }
  ]
}

Survey Best Practices

Clear Questions

Use descriptive question names and helpful descriptions

Sensible Defaults

Provide safe default values for optional fields

Appropriate Types

Use multiple choice for limited options instead of text

Validation Rules

Set min/max constraints to prevent invalid input

Combining with Extra Variables

Survey variables can be combined with job template extra_vars:

# Job template extra_vars
extra_vars:
  ansible_user: deploy
  base_path: /opt/app

# Survey adds:
# app_version: "2.1.0"
# environment: "production"

# Final variables (survey takes precedence):
# ansible_user: deploy
# base_path: /opt/app
# app_version: "2.1.0"
# environment: "production"

Survey variables override job template extra_vars if there are conflicts.

Managing Surveys

View Survey Specification

curl https://awx.example.com/api/v2/job_templates/1/survey_spec/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Update Survey

curl -X POST https://awx.example.com/api/v2/job_templates/1/survey_spec/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d @updated_survey.json

Delete Survey

curl -X DELETE https://awx.example.com/api/v2/job_templates/1/survey_spec/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Enable/Disable Survey

# Disable survey
curl -X PATCH https://awx.example.com/api/v2/job_templates/1/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"survey_enabled": false}'

# Enable survey
curl -X PATCH https://awx.example.com/api/v2/job_templates/1/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"survey_enabled": true}'

Workflow Surveys

Workflows can also have surveys:

- name: Create workflow with survey
  awx.awx.workflow_job_template:
    name: Release Pipeline
    organization: Engineering
    survey_enabled: true
    survey_spec:
      name: Release Survey
      description: Release configuration
      spec:
        - type: text
          question_name: Release Version
          variable: release_version
          required: true
        - type: multiplechoice
          question_name: Release Type
          variable: release_type
          choices:
            - major
            - minor
            - patch
          default: minor
    state: present

Workflow survey variables are available to all job templates in the workflow.

Troubleshooting

Survey not appearing when launching

Verify:

Survey is enabled: survey_enabled: true
Survey spec is not empty
At least one question is defined

Check status:

curl https://awx.example.com/api/v2/job_templates/1/ \
  -H "Authorization: Bearer YOUR_TOKEN" | \
  jq '{survey_enabled, ask_variables_on_launch}'

Validation errors on launch

Common issues:

Value outside min/max range
Required field not provided
Choice not in defined list
Wrong data type (string vs integer)

Test validation:

# Launch with -v to see validation errors
curl -X POST https://awx.example.com/api/v2/job_templates/1/launch/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"extra_vars": {"app_version": "test"}}' \
  -v

Variables not available in playbook

Check:

Variable name in survey matches playbook usage
Survey is enabled
Launch included survey responses

Verify variables received:

- name: Debug all variables
  debug:
    var: vars

Multi-select not working

For multi-select:

Use array in launch: ["option1", "option2"]
Default uses newline: "option1\noption2"
In playbook, access as list: {{ components }}

Example:

loop: "{{ components | default([]) }}"

Survey vs Ask on Launch

Comparison:

Feature	Survey	Ask on Launch
User Interface	Custom form	Standard fields
Validation	Custom rules	Basic validation
Variable Names	Custom names	Predefined (inventory, limit, etc.)
Use Case	Custom application variables	Job template settings

Use both together:

job_template:
  survey_enabled: true  # For app_version, environment
  ask_inventory_on_launch: true  # For inventory selection
  ask_limit_on_launch: true  # For host limiting

Job Templates

Create job templates that use surveys

Workflows

Add surveys to workflow templates

Extra Variables

Learn about variable precedence

Job Launch API

API reference for launching jobs with surveys

Overview

Installation

Core Concepts

User Guide

Advanced Features

Integrations

Administration

​Understanding Surveys

​Use Cases

Application Deployment

Server Provisioning

User Management

Configuration Changes

​Survey Question Types

​Creating a Survey

​Survey Validation

​Text Validation

​Integer Validation

​Float Validation

​Multiple Choice Validation

​Multi-Select Validation

​Using Survey Variables in Playbooks

​Advanced Survey Examples

​Complete Deployment Survey

​Server Provisioning Survey

​Survey Best Practices

Clear Questions

Sensible Defaults

Appropriate Types

Validation Rules

​Combining with Extra Variables

​Managing Surveys

​View Survey Specification

​Update Survey

​Delete Survey

​Enable/Disable Survey

​Workflow Surveys

​Troubleshooting

​Survey vs Ask on Launch

​Related Resources

Job Templates

Workflows

Extra Variables

Job Launch API

Build docs developers (and LLMs) love

Understanding Surveys

Use Cases

Survey Question Types

Creating a Survey

Survey Validation

Text Validation

Integer Validation

Float Validation

Multiple Choice Validation

Multi-Select Validation

Using Survey Variables in Playbooks

Advanced Survey Examples

Complete Deployment Survey

Server Provisioning Survey

Survey Best Practices

Combining with Extra Variables

Managing Surveys

View Survey Specification

Update Survey

Delete Survey

Enable/Disable Survey

Workflow Surveys

Troubleshooting

Survey vs Ask on Launch

Related Resources