AWX Forms

AWX forms execute an AWX / Ansible Tower job template when submitted.

Targets an Awx Template.
The AWX Connection token must be set in the settings.

Awx Form

- name: Delete a vm
  roles:                                         # reference to roles defined earlier
  - vmware
  description: Delete a virtual machine
  help: This Form deletes a virtual machine.
  showHelp: true                                 # show help on load
  image: https://picsum.photos/64                # an image url (can be base64)
  categories:                                    # reference to categories defined earlier
  - Demo
  - Vmware
  - Decommissioning/Linux                        # Add to a subcategory using the `/` separator
  tileClass: bg-danger                           # a bootstrap background color style (https://getbootstrap.com/)
  template: remove_vm                            # template to launch (only if type = awx)
  inventory: inventory                           # optional awx inventory
  check: false                                   # run in checkmode or not
  diff: false                                    # show differences
  tags: vm,delete                                # optional ansible tags (comma separated)
  type: awx                                      # type is awx or ansible
  onSubmit:                                      # event handler on form submit
    - clear: 0                                   # clear form after 0 seconds
    - hide: 1                                   # hide form after 1 second
  onSuccess:                                     # event handler on form success
    - load: 1,Another Form                       # load another form after 1 second
  onFailure:                                     # event handler on job failure
    - show: 2                                    # show the form after 2 seconds
  onAbort:                                       # event handler on job failure
    - reload: 3                                  # reload the form after 3 seconds
  fieldGroupClasses:                             # give fieldgroups a custom background
    groupname1: bg-info-subtle
    groupname2: bg-success-subtle    
  fields:                                        # list of field objects

Properties

Properties specific to type: awx, in addition to the common form properties.

Basic

Attribute Comments
roles
array / required

Who has access
valid role names

You can have RBAC by adding roles to a form. If you want everyone to see the form, add the public role.
Note : An admin has always access.

Examples:

1) Give access to vmware team

name: Create virtual machine
roles:
- vmAdmins
- vmOperators
categories
array

Categories
valid category name

By adding one or more categories, you can group forms together in categories.

Examples:

1) Category vmware

name: Delete virtual machine
categories:
- Vmware
- Decommissioning
template
string

Awx template
a valid awx template name

This attribute is only used when the form type is awx. When using native Ansible, use the property playbook.

Note : You can also dynamically set the template by using a field called __template__. It must be sent as extravar. If this extravar is found it will overwrite the static template name.
Note : If you use multistep and you want to dynamically set every step, use the key property and model property to create separate extravars per step.

Examples:

1) Run AWX Template Helloworld

name: Helloworld
type: awx
template: Helloworld

2) Use dynamic template name

name: Foobar
type: awx
template: HelloWorld
fields:
  - name: __template__
    type: text
    default: Foobar # this will overwrite the template name
credentials
object
added in version 4.0.16

Send credentials to your playbook/template
key-value pairs

From the earlier versions, you could send credentials, stored in Ansible Forms, by using the field-property asCredentials.
From now on, you can also define them statically in the form.
Additionally, you can also set these dynamically by using the a field name credentials.
Note : that this also works in steps, so each step can have its own set of credentials.
Note : If you use multistep and you want to dynamically set every step, use the key property and model property to create separate extravars per step.
Note : The credential can be a regex Note : A second, fallback, credential kan be passed using a comma

Examples:

1) Send vmware and microsoft credentials

credentials:
  cred_vm: vcenter_creds # will take the credentials calld vcenter_creds and send them in the object `cred_vm`
  cred_ms: ad_creds # will take the credentials called ad_creds and send them in the object `cred_ms`
  cred_netapp: cluster1,clusters2 # will first search for cluster1 and as fallback to cluster2
  cred_veeam: veeam_server[0-9],veeam # will first search for a credential matching the regex, and as fallback search for veeam

2) Dynamically send credentials

fields:
  - name: my_vcenter_cred
    type: enum
    values:
      - vcenter_prod
      - vcenter_dev
    default: ad_prod            
  - name: __credentials__
    type: expression
    runLocal: true
    hide: true
    expression: "{vcenter:'$(my_vcenter_cred)'}"

# NOTE : this can also be done using `asCredential`

  - name: vcenter
    type: enum
    values:
      - vcenter_prod
      - vcenter_dev
    default: ad_prod                     
    asCredential: true
varsFiles
array
added in version 6.1.0

Load YAML files as constants
list of file paths (absolute or relative)

Load one or more YAML files as constants that will be merged with the base config constants. Files must contain a dictionary (not a list) and must have .yml or .yaml extension.

Path Resolution:

  • Absolute paths: used as-is (e.g., /opt/shared/vars/database.yaml)
  • Relative paths: resolved against VARS_FILES_PATH environment variable (default: persistent/vars/)

Use Cases:

  • Share common variables across multiple forms
  • Separate sensitive configuration from form definitions
  • Centralize environment-specific settings

Note: Files are merged in order. Later files override earlier ones if keys conflict. Variables from varsFiles are merged with base config constants.

Examples:

1) Load single vars file

varsFiles:
  - common/database.yaml    # relative to VARS_FILES_PATH

2) Load multiple vars files with absolute paths

varsFiles:
  - /opt/shared/globals.yaml
  - /etc/ansibleforms/env-prod.yaml

3) Mix relative and absolute paths

varsFiles:
  - common/shared.yaml           # relative
  - /opt/custom/overrides.yaml   # absolute

Interaction

Attribute Comments
approval
object

Add approval point
valid approval object

Ansible Forms allows to add an approval point before a job is ran.
An approval link is sent by email to a specific approver who can then approve or reject the job.
notifications
object

Add Notification
valid notification object

Add email notifications on job status events.

Examples:

1) Send on success

notifications:
  recipients:
    - info@ansibleguy.com
  onStatus:
    - success
onSubmit
array
added in version 3.1.0

Events on submit
valid job status action objects

Once a job is launched, Ansible Forms has a few status events you can act on.

  • onSubmit : Triggered the moment the submit button is pressed
  • onSuccess : Triggered when the job is finished succesfully
  • onFailure : Triggered when the job was not succesful
  • onAbort : Triggered when the job was aborted
  • onFinish : Triggered when the job is finished, regardless the status

Follow the link above to learn about the possible job status actions

Examples:

1) Examples

onSubmit:
  - clear: 0   # clear form after submit
  - hide: 2   # seconds later, hide the form
# more examples on the job-status-event page
onSuccess
array
added in version 3.1.0

Events on success
valid job status action objects

Once a job is launched, Ansible Forms has a few status events you can act on.

  • onSubmit : Triggered the moment the submit button is pressed
  • onSuccess : Triggered when the job is finished succesfully
  • onFailure : Triggered when the job was not succesful
  • onAbort : Triggered when the job was aborted
  • onFinish : Triggered when the job is finished, regardless the status

Follow the link above to learn about the possible job status actions

Examples:

1) Examples

onSuccess:
  - home: 0    # go home on success
# more examples on the job-status-event page
onFailure
array
added in version 3.1.0

Events on failure
valid job status action objects

Once a job is launched, Ansible Forms has a few status events you can act on.

  • onSubmit : Triggered the moment the submit button is pressed
  • onSuccess : Triggered when the job is finished succesfully
  • onFailure : Triggered when the job was not succesful
  • onAbort : Triggered when the job was aborted
  • onFinish : Triggered when the job is finished, regardless the status

Follow the link above to learn about the possible job status actions

Examples:

1) Examples

onFailure:
  - load: 3   # reload form after failure after 3 seconds
# more examples on the job-status-event page
onAbort
array
added in version 3.1.0

Events on abort
valid job status action objects

Once a job is launched, Ansible Forms has a few status events you can act on.

  • onSubmit : Triggered the moment the submit button is pressed
  • onSuccess : Triggered when the job is finished succesfully
  • onFailure : Triggered when the job was not succesful
  • onAbort : Triggered when the job was aborted
  • onFinish : Triggered when the job is finished, regardless the status

Follow the link above to learn about the possible job status actions

Examples:

1) Examples

onAbort:
  - clear: 3   # clear form after abort after 3 seconds
# more examples on the job-status-event page
onFinish
array
added in version 3.1.0

Events on finished
valid job status action objects

Once a job is launched, Ansible Forms has a few status events you can act on.

  • onSubmit : Triggered the moment the submit button is pressed
  • onSuccess : Triggered when the job is finished succesfully
  • onFailure : Triggered when the job was not succesful
  • onAbort : Triggered when the job was aborted
  • onFinish : Triggered when the job is finished, regardless the status

Follow the link above to learn about the possible job status actions

Examples:

1) Examples

onSubmit:
  - hide: 0    # hide on submit
onFinish:
  - clear: 0   # clear and show on finish
  - show: 0    
# more examples on the job-status-event page

Visualization

Attribute Comments
showHelp
boolean

Show Help

Show the help by default or collapse the help.

Default: true
icon
string

Form icon
Free fontawesome 6 icon

You can add a nice icon to your forms. The icon name is a free fontawesome 6 icon. You can find more information at www.fontawesome.com.
Note : You can either have an icon or an image, not both.

Examples:

1) Trash icon

name: Delete virtual machine
icon: trash
iconColor
string

Icon color
valid color name

Specifies the color of the icon. Use any valid CSS color class name (e.g., primary, success, danger, warning, info, dark, white, …).

Examples:

1) Red icon

name: My Form
icon: server
iconColor: danger
iconSize
string

Icon size
xs, sm, lg, 2x, 3x, 5x, 7x, 10x

Specifies the size of the icon.

Default: 3x

Examples:

1) Large icon

name: My Form
icon: server
iconSize: 5x
overlayIcon
string

Overlay icon on main icon
valid fontawesome icon name

Adds a icon on top of the main icon for layering effects. Useful for status indicators or badges.

Examples:

1) Server with check overlay

name: Server Status OK
icon: server
overlayIcon: check
overlayIconColor: success
overlayIconTransform: shrink-6 up-7 right-7
overlayIconTransform
string

Transform for overlay icon
valid fontawesome transform

Specifies the transform/positioning for the overlay icon. You can use FontAwesome transform values like shrink, grow, up, down, left, right.

Default: shrink-6 up-7 right-7

Examples:

1) Custom positioned overlay

name: My Form
icon: circle
overlayIcon: check
overlayIconTransform: shrink-8 down-2
overlayIconColor
string

Color for overlay icon
valid color name

Specifies the color of the overlay icon.

Default: success

Examples:

1) Red overlay icon

name: Alert Status
icon: circle
overlayIcon: exclamation
overlayIconColor: danger
overlayIconCircle
boolean

Show circle background behind overlay icon

When enabled, shows a colored circle background behind the overlay icon. The circle uses the overlayIconColor, and the icon inside becomes white in light mode or dark in dark mode. When disabled, the overlay icon appears without a circle background.

Default: true

Examples:

1) Overlay without circle

name: My Form
icon: server
overlayIcon: check
overlayIconCircle: false
overlayIconColor: success
overlayIconText
string

Text overlay on icon
any text

Adds text as an overlay on the icon. Can be used for badges, counters, or labels.

Examples:

1) New badge

name: New Feature
icon: star
overlayIconText: "New!"
overlayIconTextPosition: top-right
overlayIconTextColor: warning
overlayIconTextPosition
string

Position for text overlay
top-left, top-right, bottom-left, bottom-right

Specifies the position of the text overlay.

Default: bottom-left

Examples:

1) Top right badge

name: Notification
icon: bell
overlayIconText: "3"
overlayIconTextPosition: top-right
overlayIconTextColor
string

Color for text overlay
valid color name

Specifies the color of the text overlay.

Default: success

Examples:

1) Warning badge

name: Pending Items
icon: inbox
overlayIconText: "!"
overlayIconTextColor: warning
image
string

Form image
valid image url

You can add a nice image to your form. You can provide a local or remote url. But if you are in a secured location, you might want to go for a base64 encode image. This allows you to embed the image in the yaml file.
To do this, find a not-to-large PNG image or better, an SVG image and convert to a base64 image url. You can do this here.
Note : You can either have an icon or an image, not both.

Examples:

1) Microsoft image

name: Add Windows Virtual Machine
image: |
  data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My
  5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyMyAyMyI+PHBhdGggZmlsbD
  0iI2YzZjNmMyIgZD0iTTAgMGgyM3YyM0gweiIvPjxwYXRoIGZpbGw9IiNmMz
  UzMjUiIGQ9Ik0xIDFoMTB2MTBIMXoiLz48cGF0aCBmaWxsPSIjODFiYzA2Ii
  BkPSJNMTIgMWgxMHYxMEgxMnoiLz48cGF0aCBmaWxsPSIjMDVhNmYwIiBkPS
  JNMSAxMmgxMHYxMEgxeiIvPjxwYXRoIGZpbGw9IiNmZmJhMDgiIGQ9Ik0xMi
  AxMmgxMHYxMEgxMnoiLz48L3N2Zz4=

2) Internet image

name: Add Windows Virtual Machine
image: https://upload.wikimedia.org/wikipedia/commons/4/44/Microsoft_logo.svg

3) Local image

name: Add Netapp storage
image: /assets/images/netapp.svg # the docker compose has a few brand images, feel free to add your own
tileClass
string

Form tile background colour
valid bootstrap background class

Ansible Forms uses the Bootstrap css framework to style the webapplication.
Bootstrap has a few color helper classes you can use to give your formtile a background color.
You can find them here background color and foreground color.
Hint: Try to add a matching foreground color.

Default: bg-info-subtle

Examples:

1) warning color

name: Cleanup jobs
icon: trash
tileClass: bg-warning text-light

2) success light color

name: New job
icon: plus
tileClass: bg-success-subtle text-dark
fieldGroupClasses
object

Fieldgroup background color
key-value pairs

Ansible Forms uses the Bootstrap css framework to style the webapplication. Bootstrap has a few color helper classes you can use to give your fieldgroups a background color. You can find them here background color and foreground color.

Examples:

1) Color fieldgroup

fieldGroupClasses:                             # give fieldgroups a custom background
  groupname1: bg-info-subtle
  groupname2: bg-success-subtle
order
integer
added in version 5.1.0

Order of the form in the list

The order of the form in the list of forms. Forms are sorted by this order, so you can have a specific order in the list. Note : If you do not set this property, it will be ordered alphabetically by name.

Workflow

Attribute Comments
inventory
string

Inventory

In both awx and ansible core you can pass an inventory. In the case of ansible core, it will be a yaml file. In case of awx it will be the inventory name.

Note : You can also dynamically set the inventory by using a field called __inventory__. It must be sent as extravar. If this extravar is found it will overwrite the static inventory.
Note : Ansible core allows multiple inventories (so you can use an array), however awx does not support multiple inventories. Note : If you use multistep and you want to dynamically set every step, use the key property and model property to create separate extravars per step.
executionEnvironment
string
added in version 5.0.0

Execution Environment

In newer versions of AWX you can choose an execution environment. Use this property to pass it to your template.

Note : You can also dynamically set the executionEnvironment by using a field called __executionEnvironment__. It must be sent as extravar. If this extravar is found it will overwrite the static executionEnvironment.
Note : If you use multistep and you want to dynamically set every step, use the key property and model property to create separate extravars per step.
instanceGroups
array or string
added in version 5.0.0

Instance Groups

In newer versions of AWX you can choose instance groups. Use this property to pass it to your template.
It can be a single string (name of instancegroup) or an array (list of names).

Note : You can also dynamically set the instanceGroups by using a field called __instanceGroups__. It must be sent as extravar. If this extravar is found it will overwrite the static instanceGroups.
Note : If you use multistep and you want to dynamically set every step, use the key property and model property to create separate extravars per step.
scmBranch
string
added in version 5.0.0

SCM Branch

Awx allows to pass the scm branch. Use this property to pass it to your template.

Note : You can also dynamically set the scmBranch by using a field called __scmBranch__. It must be sent as extravar. If this extravar is found it will overwrite the static scmBranch.
Note : If you use multistep and you want to dynamically set every step, use the key property and model property to create separate extravars per step.
awx
string
added in version 6.0.0

Add awx instance to your template
name of awx instance

From now on you can have multiple AWX instances. The database will be updated during upgrade but you will need to set your current AWX instance to default.

Note : you can also set these dynamically by using a field called __awx__. It must be sent as extravar. If this extravar is found it will overwrite the static awx.
Note : this also works in steps, so each step can have its own set of awx instances.
Note : If you use multistep and you want to dynamically set every step, use the key property and model property to create separate extravars per step.

Examples:

1) Add awx instance to your template

awx: my_awx_instance
awxCredentials
array
added in version 4.0.16

Add awx credentials to your template
name of credential in AWX

In AWX you can set credentials on your template.
From now on, you can also add credentials from Ansible Forms.

Note : you can also set these dynamically by using the a field name awxCredentials. It must be sent as extravar. If this extravar is found it will overwrite the static awxCredentials.
Note : this also works in steps, so each step can have its own set of awxCredentials.
Note : the credentials will be added on top of the ones already selected in the template, they will be merged.
Note : If you use multistep and you want to dynamically set every step, use the key property and model property to create separate extravars per step.

Examples:

1) Add awx credentials to your template

awx_credentials:
  - vmware_prod
  - ad_prod

2) Dynamically send credentials

fields:
  - name: my_ad_creds
    type: enum
    values:
      - ad_prod
      - ad_dev
    default: ad_prod
  - name: __awxCredentials__
    type: expression
    runLocal: true
    expression: "['vmware_prod','$(my_ad_creds)']"
check
boolean

Run in check mode

In both awx and ansible core you run a playbook in check mode. Enable this attribute to do so.

Note : You can also dynamically set the check mode by using a field called __check__. It must be sent as extravar. If this extravar is found it will overwrite the static check field. The field must result in a boolean (expression or checkbox) Note : If you use multistep and you want to dynamically set every step, use the key property and model property to create separate extravars per step.
limit
text

Run against a limited number of hosts
a valid host pattern

In awx and ansible core you run a playbook against limited hosts by supplying a host pattern. Use this attribute to do so.

Note : You can also dynamically set the limit by using a field called __limit__. It must be sent as extravar. If this extravar is found it will overwrite the static check field. The field must result in number (number field or expression) Note : If you use multistep and you want to dynamically set every step, use the key property and model property to create separate extravars per step.
diff
boolean

Run in diff mode

In both awx and ansible core you run a playbook in diff mode. Enable this attribute to do so.

Note : You can also dynamically set the check mode by using a field called __diff__. It must be sent as extravar. If this extravar is found it will overwrite the static diff field. The field must result in a boolean (expression or checkbox)
Note : If you use multistep and you want to dynamically set every step, use the key property and model property to create separate extravars per step.
abortable
boolean
added in version 5.0.8

Allow aborting the job

By default you can allow the user to abort the job. Use this attribute to disable this behaviour.

Default: true
tags
string

Set tags
comma separated tag-list

In both awx and ansible core you can pass tags. Use this attribute to pass a comma separted list of tags.

Note : You can also dynamically set the tags by using a field called __tags__. It must be sent as extravar. If this extravar is found it will overwrite the static tags.
Note : If you use multistep and you want to dynamically set every step, use the key property and model property to create separate extravars per step.

Copyright © 2023-2026 AnsibleForms. All rights reserved.