Forms

Forms are added as YAML files in the forms folder. Each YAML file can contain a single form or a list of forms. Subfolders are supported if you want to organize your forms. Forms are the core of AnsibleForms. Each form represents a web interface that collects user input and executes an Ansible playbook or AWX/Tower template with that data.

VIDEO: Create your first form

Understanding Form Structure

Every form in AnsibleForms is a Form Object. This object contains all the configuration for a single form, including its name, type, roles, categories, and fields.

A basic form looks like this:

forms:
  - name: Create VM
    type: ansible
    playbook: playbooks/create_vm.yml
    roles:
      - admin
    categories:
      - Provisioning
    fields:
      - name: vm_name
        type: text
        label: VM Name

See the Form Object Reference section below for all available attributes and configuration options.

How forms are loading

AnsibleForms loads forms from the following locations:

  1. FROM REPOSITORIES : All repositories with “use for forms” switch enabled (supports multiple repositories)
    • Forms are automatically merged from all enabled repositories
    • First checks for a forms/ subfolder in each repository
    • Falls back to repository root if forms/ subfolder doesn’t exist
  2. FROM LOCAL FOLDER : The local forms/ folder (FORMS_FOLDER_PATH environment variable) if no repositories are configured

Note: You can enable “use for forms” on multiple repositories and all forms will be merged together. Make sure form names are unique across repositories to avoid conflicts.

Form Object Reference

Each form in the forms list is configured with the below attributes.

Attribute Comments
basic
name
string / required / unique

The name of the form
alphanumeric + dash + underscore + space

The name of a form is also the identifier of the form and thus must be unique.
For simplicity we have chosen not to some sore of guid as unique identifier. This does mean, however, that when your rename a form any reference to it will be broken.
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
description
string

Form description
free text

A short description, explaining what the form does.
help
string

Help
valid markdown

Using markdown you can a more detailed help message to help the operator understand the form.

Examples:

1) blockquote with title, list, italic and bold

> #### The quarterly results look great!
>
> - Revenue was off the chart.
> - Profits were higher than ever.
>
>  *Everything* is going according to **plan**.
type
string

Form type

Our form eventually sends extravars to a target. That target can be an ansible-playbook, an awx-template or a multistep (which is a list or combination of multiple playbooks/templates, executed sequentially).

Choices:
  • ansible
  • awx
  • multistep

Examples:

1) Run AWX Template Create VM

name: Create vm
type: awx
template: Create VM

2) Run Delete VM playbook

name: Delete vm
type: ansible
template: delete_vm.yaml

3) Run multistep job

name: Trigger awx job
type: multistep
steps:
- name: Create vm
  type: awx
  template: create_vm        
- name: Start vm
  type: awx
  template: start_vm
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.

Only available with types:
awx

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
playbook
string

Ansible playbook
a valid yaml file

This attribute is only used when the form type is ansible. When using awx, use the property template.

Note : You can also dynamically set the playbook by using a field called __playbook__. It must be sent as extravar. If this extravar is found it will overwrite the static playbook 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.

Only available with types:
ansible

Examples:

1) Run foobar playbook

name: Foobar
type: ansible
playbook: foobar.yaml

2) Use dynamic playbook name

name: HelloWorld
type: ansible
playbook: foobar.yaml
fields:
  - name: __playbook__
    type: text
    default: helloworld.yaml # this will overwrite the playbook 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
ansibleCredentials
string
added in version 4.0.17

Pass ansible_user and ansible_password to ansible playbook using stored credentials
a local credentialname

Ansible allows to pass default ansible credentials in the form of 2 extravars ansible_user and ansible_password
playbookSubPath
string
added in version 6.0.1

Subfolder structure for playbooks
a valid folder subpath

If you have a more complex ansible setup, you might want to organize them in subfolders. Use this property to define a subfolder (or multiple levels) where you want to launch ansible-playbook from.
vaultCredentials
string
added in version 5.0.2

Pass vault password to ansible playbook using stored credentials
a local credentialname

Ansible can encrypt variables in a vault, to unlock the vault a password is needed. This password can be stored in Ansible Forms (as credential) and passed to the playbook..
steps
array

Multistep steps
🔗 a step object

A multistep form is basically an array of multiple form type destinations, defined here as steps.

Only available with types:
multistep

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
fields
array

fields
🔗 valid field object

It makes sense that a form has 1 or more formfields. Read more about them in the separate formfield section.

Examples:

1) Examples

fields:
  - name : name
    label: Your name
    type: text
    required: true
  - name : email
    label: Your email
    type: text
    regex:
      expression: "^[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,4}$"
      description: Please enter a valid email address
    required: true
interaction
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
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
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.
verbose
boolean
added in version 4.0.0

Run in verbose mode

In ansible core you run a playbook in verbose mode. Enable this attribute to do so.

Note : You can also dynamically set the verbose mode by using a field called __verbose__. 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.
keepExtravars
boolean
added in version 4.0.0

Do not remove the extarvars json file

In ansible core we temporarily store the extravars in a json file. After run, this file is removed. Use this property to disable this behaviour.

Note : You can also dynamically set this property by using a field called __keepExtravars__. 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.