Job Templates

What is a Job Template?

A Job Template is a reusable definition for running an Ansible playbook against an inventory with specific credentials and settings. Job templates are the primary way to launch automation jobs in AWX, providing a consistent interface for executing playbooks with parameterization and access control.

Job templates act as a “play button” for your automation - they define what to run, where to run it, and how to run it.

Core Concepts

Required Components

From the JobTemplate model (awx/main/models/jobs.py:194-558): A job template requires:

Project: The source of playbooks
Playbook: Specific playbook file from the project
Inventory (or prompt on launch): Target hosts
Credentials: Authentication for target systems

Key Fields

Field	Type	Description
`name`	String	Template name (unique within organization)
`description`	String	Optional description
`job_type`	Choice	`run` (execute playbook) or `check` (dry run)
`inventory`	ForeignKey	Target inventory
`project`	ForeignKey	Source project containing playbook
`playbook`	String	Playbook filename (must exist in project)
`scm_branch`	String	Override project branch (if allowed)
`forks`	Integer	Ansible parallelism (0 = unlimited)
`limit`	String	Limit job to specific hosts or groups
`verbosity`	Integer	Ansible output verbosity (0-4)
`extra_vars`	TextField	Additional variables (JSON or YAML)
`job_tags`	String	Only run plays/tasks tagged with these
`skip_tags`	String	Skip plays/tasks with these tags
`start_at_task`	String	Start playbook at specific task
`timeout`	Integer	Job timeout in seconds (0 = no timeout)
`diff_mode`	Boolean	Show textual changes to templated files
`become_enabled`	Boolean	Enable privilege escalation
`allow_simultaneous`	Boolean	Allow multiple jobs from this template to run concurrently
`use_fact_cache`	Boolean	Enable Ansible fact caching
`job_slice_count`	Integer	Number of job slices for parallel execution

Prompting on Launch

Job templates can be configured to prompt for values at launch time using ask_*_on_launch fields:

# From jobs.py:225-257
ask_diff_mode_on_launch = AskForField(blank=True, default=False)
ask_job_type_on_launch = AskForField(blank=True, default=False)
ask_verbosity_on_launch = AskForField(blank=True, default=False)
ask_credential_on_launch = AskForField(blank=True, default=False, allows_field='credentials')
ask_execution_environment_on_launch = AskForField(blank=True, default=False)
ask_forks_on_launch = AskForField(blank=True, default=False)
ask_job_slice_count_on_launch = AskForField(blank=True, default=False)
ask_timeout_on_launch = AskForField(blank=True, default=False)
ask_instance_groups_on_launch = AskForField(blank=True, default=False)

Prompted credentials and variables override the template’s defaults. Ensure users understand the security implications of prompted launches.

Credentials

Job templates support multiple credential types simultaneously:

# From jobs.py:167-181
@property
def machine_credential(self):
    return self.credentials.filter(credential_type__kind='ssh').first()

@property
def network_credentials(self):
    return list(self.credentials.filter(credential_type__kind='net'))

@property
def cloud_credentials(self):
    return list(self.credentials.filter(credential_type__kind='cloud'))

@property
def vault_credentials(self):
    return list(self.credentials.filter(credential_type__kind='vault'))

You can attach:

One SSH credential (machine credential)
Multiple network credentials
Multiple cloud credentials
Multiple vault credentials

Extra Variables

Extra variables follow a specific precedence order:

Job launch extra vars (highest)
Survey answers
Job template extra vars
Inventory variables
Host/group variables (lowest)

Variables are merged at runtime:

# From jobs.py:164
extra_vars_dict = VarsDictProperty('extra_vars', True)

Surveys

Job templates can have surveys that prompt users for input:

{
  "name": "Survey",
  "description": "Survey description",
  "spec": [
    {
      "question_name": "What is your environment?",
      "question_description": "Select target environment",
      "required": true,
      "type": "multiplechoice",
      "variable": "target_environment",
      "choices": ["dev", "staging", "production"],
      "default": "dev"
    },
    {
      "question_name": "Number of instances",
      "question_description": "How many instances?",
      "required": true,
      "type": "integer",
      "variable": "instance_count",
      "min": 1,
      "max": 10,
      "default": 1
    },
    {
      "question_name": "API Key",
      "question_description": "API Key",
      "required": true,
      "type": "password",
      "variable": "api_key"
    }
  ]
}

Survey answers are passed as extra variables. Password-type questions are encrypted.

Job Slicing

Job slicing enables parallel execution across multiple job instances:

# From jobs.py:359-383
def create_unified_job(self, **kwargs):
    prevent_slicing = kwargs.pop('_prevent_slicing', False)
    slice_ct = self.get_effective_slice_ct(kwargs)
    slice_event = bool(slice_ct > 1 and (not prevent_slicing))
    if slice_event:
        # A Slice Job Template will generate a WorkflowJob rather than a Job
        from awx.main.models.workflow import WorkflowJobTemplate, WorkflowJobNode

        kwargs['_unified_job_class'] = WorkflowJobTemplate._get_unified_job_class()
        kwargs['_parent_field_name'] = "job_template"
        kwargs.setdefault('_eager_fields', {})
        kwargs['_eager_fields']['is_sliced_job'] = True

When job_slice_count > 1, AWX:

Creates a workflow job instead of a regular job
Creates one job node per slice
Distributes inventory hosts across slices
Runs slices in parallel

Job slicing is effective for large inventories with independent hosts. It won’t speed up playbooks with dependencies between hosts.

Jobs

When a job template is launched, it creates a Job (awx/main/models/jobs.py:560-868):

Job Lifecycle

Pending

Job is created and queued

Waiting

Job is waiting for dependencies (project updates, inventory updates)

Running

Job is executing on an AWX instance

Completed

Job finished with status: successful, failed, error, or canceled

Job Fields

Jobs inherit all fields from the job template plus:

Field	Type	Description
`job_template`	ForeignKey	Source template
`status`	String	Current job status
`started`	DateTime	When job execution started
`finished`	DateTime	When job completed
`elapsed`	Float	Execution time in seconds
`artifacts`	JSON	Artifacts from `set_stats` module
`scm_revision`	String	Git commit used from project
`project_update`	ForeignKey	Related project update job
`job_slice_number`	Integer	Slice number (if sliced)
`job_slice_count`	Integer	Total slices (if sliced)

Dependencies

Jobs may wait for dependencies before running:

# From jobs.py:638-650
def _set_default_dependencies_processed(self):
    """
    This sets the initial value of dependencies_processed
    and here we use this as a shortcut to avoid the DependencyManager for jobs that do not need it
    """
    if (not self.project) or self.project.scm_update_on_launch:
        self.dependencies_processed = False
    elif (not self.inventory) or self.inventory.inventory_sources.filter(update_on_launch=True).exists():
        self.dependencies_processed = False
    else:
        # No dependencies to process
        self.dependencies_processed = True

Dependencies include:

Project updates (if scm_update_on_launch)
Inventory updates (if inventory sources have update_on_launch)

Execution Environments

Job templates can specify an execution environment:

# From unified_jobs.py (inherited)
execution_environment = models.ForeignKey(
    'ExecutionEnvironment',
    null=True,
    blank=True,
    default=None,
    on_delete=polymorphic.SET_NULL,
    related_name='%(class)ss',
    help_text=_('The container image to be used for execution.')
)

If not specified, the execution environment is resolved from:

Job template’s execution_environment
Project’s default_environment
Organization’s default_environment
Global default execution environment

Instance Groups

Job templates can specify which instance groups run the job:

# From jobs.py:804-816
@property
def preferred_instance_groups(self):
    # If the user specified instance groups those will be handled by the unified_job.create_unified_job
    # This function handles only the defaults for a template w/o user specification
    selected_groups = []
    for obj_type in ['job_template', 'inventory', 'organization']:
        if getattr(self, obj_type) is not None:
            for instance_group in getattr(self, obj_type).instance_groups.all():
                selected_groups.append(instance_group)
            if getattr(getattr(self, obj_type), 'prevent_instance_group_fallback', False):
                break

Instance groups control where jobs execute in clustered/containerized environments.

API Endpoints

List Job Templates

GET /api/v2/job_templates/

Create Job Template

POST /api/v2/job_templates/
Content-Type: application/json

{
  "name": "Deploy Application",
  "description": "Deploy app to production",
  "job_type": "run",
  "inventory": 1,
  "project": 2,
  "playbook": "deploy.yml",
  "credentials": [3, 4],
  "forks": 10,
  "limit": "webservers",
  "verbosity": 1,
  "extra_vars": "---\napp_version: 1.2.3",
  "ask_variables_on_launch": true,
  "ask_limit_on_launch": true
}

Launch Job

POST /api/v2/job_templates/{id}/launch/
Content-Type: application/json

{
  "extra_vars": {
    "app_version": "1.2.4"
  },
  "limit": "web01.example.com"
}

Cancel Job

POST /api/v2/jobs/{id}/cancel/

Relaunch Job

POST /api/v2/jobs/{id}/relaunch/

Permissions

Job templates have these roles (jobs.py:264-275):

Admin Role: Full control over the template
Execute Role: Can launch jobs
Read Role: Can view template details

The execute role is inherited from the organization’s execute_role, making it easy to give users permission to run automation across all templates in an organization.

Notifications

Job templates can trigger notifications on job events:

# From jobs.py:527-550
@property
def notification_templates(self):
    base_notification_templates = NotificationTemplate.objects
    error_notification_templates = list(base_notification_templates.filter(
        unifiedjobtemplate_notification_templates_for_errors__in=[self, self.project]
    ))
    started_notification_templates = list(base_notification_templates.filter(
        unifiedjobtemplate_notification_templates_for_started__in=[self, self.project]
    ))
    success_notification_templates = list(base_notification_templates.filter(
        unifiedjobtemplate_notification_templates_for_success__in=[self, self.project]
    ))

Notifications can be sent:

When job starts (started)
When job succeeds (success)
When job fails (error)

Best Practices

Use Surveys for User Input

Instead of prompting for raw extra_vars, create surveys with typed inputs (integers, choices, etc.) for better UX and validation.

Enable Fact Caching

Set use_fact_cache: true to cache Ansible facts. This speeds up subsequent runs and enables fact-based smart inventories.

Set Appropriate Timeouts

Always set a timeout to prevent runaway jobs. Consider the longest expected runtime plus buffer.

Use Limit for Targeted Runs

Use the limit field or prompt for it to run playbooks against subsets of inventory without creating duplicate templates.

Leverage Job Slicing

For large inventories with independent hosts, use job slicing to parallelize execution and reduce total runtime.

Control Simultaneous Execution

Only enable allow_simultaneous if your playbooks are idempotent and safe to run concurrently.

Projects - Source of playbooks
Inventories - Target hosts
Credentials - Authentication
Workflows - Chain multiple job templates
Execution Environments - Container images for execution

Overview

Installation

Core Concepts

User Guide

Advanced Features

Integrations

Administration

Job Templates

What is a Job Template?

Core Concepts

Required Components

Key Fields

Prompting on Launch

Credentials

Extra Variables

Surveys

Job Slicing

Jobs

Job Lifecycle

Job Fields

Dependencies

Execution Environments

Instance Groups

API Endpoints

List Job Templates

Create Job Template

Launch Job

Cancel Job

Relaunch Job

Permissions

Notifications

Best Practices

Build docs developers (and LLMs) love

Overview

Installation

Core Concepts

User Guide

Advanced Features

Integrations

Administration

​What is a Job Template?

​Core Concepts

​Required Components

​Key Fields

​Prompting on Launch

​Credentials

​Extra Variables

​Surveys

​Job Slicing

​Jobs

​Job Lifecycle

​Job Fields

​Dependencies

​Execution Environments

​Instance Groups

​API Endpoints

​List Job Templates

​Create Job Template

​Launch Job

​Cancel Job

​Relaunch Job

​Permissions

​Notifications

​Best Practices

​Related Resources

Build docs developers (and LLMs) love

What is a Job Template?

Core Concepts

Required Components

Key Fields

Prompting on Launch

Credentials

Extra Variables

Surveys

Job Slicing

Jobs

Job Lifecycle

Job Fields

Dependencies

Execution Environments

Instance Groups

API Endpoints

List Job Templates

Create Job Template

Launch Job

Cancel Job

Relaunch Job

Permissions

Notifications

Best Practices

Related Resources