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.

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:

name: Create virtual machine
roles:
- vmAdmins
- vmOperators

Categories
valid category name

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

Examples:

name: Delete virtual machine
categories:
- Vmware
- Decommissioning     

Form description
free text

A short description, explaining what the form does.

Help
valid markdown

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

Examples:

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

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

Examples:

name: Create vm
type: awx
template: Create VM       

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

name: Trigger awx job
type: multistep
steps:
- name: Create vm
  type: awx
  template: create_vm        
- name: Start vm
  type: awx
  template: start_vm                                 

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:

name: Helloworld
type: awx
template: Helloworld

name: Foobar
type: awx
template: HelloWorld
fields:
  - name: __template__
    type: text
    default: Foobar # this will overwrite the template name            

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:

name: Foobar
type: ansible
playbook: foobar.yaml  

name: HelloWorld
type: ansible
playbook: foobar.yaml
fields:
  - name: __playbook__
    type: text
    default: helloworld.yaml # this will overwrite the playbook name

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:

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

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

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

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.

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

Multistep steps
a step object

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

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:

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

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

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

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:

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

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.

Add Notification
valid notification object

Add email notifications on job status events.

Examples:

notifications:
  recipients:
    - info@ansibleguy.com
  onStatus:
    - success

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:

onSubmit:
  - clear: 0   # clear form after submit
  - hide: 2   # seconds later, hide the form
# more examples on the job-status-event page

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:

onSuccess:
  - home: 0    # go home on success
# more examples on the job-status-event page  

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:

onFailure:
  - load: 3   # reload form after failure after 3 seconds
# more examples on the job-status-event page  

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:

onAbort:
  - clear: 3   # clear form after abort after 3 seconds
# more examples on the job-status-event page   

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:

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

Show Help

Show the help by default or collapse the help.

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](https://www.fontawesome.com). **Note** : You can either have an icon or an image, not both.

Examples:

name: Delete virtual machine
icon: trash

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](https://base64.guru/converter/encode/image). **Note** : You can either have an icon or an image, not both.

Examples:

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

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

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

Form tile background colour
valid bulma background class

Ansible Forms uses the Bulma css framework to style the webapplication. Bulma has a few color helper classes you can use to give your formtile a background color. You can find them here [background color](https://bulma.io/documentation/helpers/color-helpers/#background-color) and [foreground color](https://bulma.io/documentation/helpers/color-helpers/#text-color). **Hint**: Try to add a matching foreground color.

Examples:

name: Cleanup jobs
icon: trash
tileClass: has-background-warning has-text-white-ter

name: New job
icon: plus
tileClass: has-background-success-light has-text-black-ter  

Fieldgroup background color
key-value pairs

Ansible Forms uses the Bulma css framework to style the webapplication. Bulma has a few color helper classes you can use to give your fieldgroups a background color. You can find them here [background color](https://bulma.io/documentation/helpers/color-helpers/#background-color) and [foreground color](https://bulma.io/documentation/helpers/color-helpers/#text-color).

Examples:

fieldGroupClasses:                             # give fieldgroups a custom background
  groupname1: has-background-info-light
  groupname2: has-background-success-light                 

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.

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.

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.

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.

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.

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:

awx: my_awx_instance

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:

awx_credentials:
  - vmware_prod
  - ad_prod

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)']"

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.

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.

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.

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.

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.

Allow aborting the job

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

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.