Ansible Forms

Ansible forms execute a local Ansible Core playbook when submitted.

Targets an Ansible Core playbook.

Ansible Core Form

forms:
  - name: Create a vm
    roles:                                         # reference to roles defined earlier
    - vmware
    description: Create a virtual machine
    help: |
      This Form creates a virtual machine.  it will connect to `vcenter`.  This help is Markdown
      so you can use **markdown** markup to highlight __certain words__.
    showHelp: true                                 # show help on load
    icon: computer                                 # a font awesome icon
    categories:                                    # reference to categories defined earlier
    - Demo
    - Vmware/Linux                                 # Add to a subcategory using the `/` separator
    tileClass: bg-success-subtle                   # a bootstrap background color style (https://getbootstrap.com/)
    playbook: playbook_vm.yml                      # playbook to launch (only if type = ansible)
    inventory: inventory.yml                       # optional ansible inventory file
    check: false                                   # run in checkmode or not
    diff: false                                    # show differences
    verbose: false                                 # verbose output
    keepExtravars: false                           # keep extravars json file                  
    tags: vm,create                                # optional ansible tags (comma separated)
    type: ansible                                  # 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
    onFinish:                                      # event handler on job finished
      - show: 2                                    # show the form after 2 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: ansible, 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
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.

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..
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.
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.