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

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 (= ansible)

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

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.
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.
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 and foreground 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 and foreground color.

Examples:

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

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.

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.

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.

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            

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 (= awx)

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

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.
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.
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 and foreground 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 and foreground color.

Examples:

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

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.

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.

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.

Multistep steps
a step object

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

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 (= multistep)

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

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.
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.
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 and foreground 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 and foreground color.

Examples:

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

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.

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.

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.

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

The name of the step. Used for logging and visualization.

Step type

Every step can be an ansible-playbook or an awx-template

name: Create vm
type: awx
template: Create VM       

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

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.

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.

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

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.
Every step can have a differnt approval point.

approval:
  title: Please approve removal
  message: |
    You need to approve the removal of $(field1).  
    Double check please.
  roles:
    - public
  notifications:
    - info@ansibleforms.com    

Add Notification
valid notification object

Add email notifications on job status events.
Every step can have its own notifications

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

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 want to dynamically set every step, use the key property and model property to create separate extravars per step.

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 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 want to dynamically set every step, use the key property and model property to create separate extravars per step.

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 want to dynamically set every step, use the key property and model property to create separate extravars per step.

Extravar key
valid extravar reference

Ansible Forms can model the extravars into objects using the formfield model attribute. In a multistep form, by default, every step gets the full extravars payload. However, using this key attribute you can choose which step receives which part of the extravars.
Study the example below to understand how the key property works.

name: Resize volume
type: multistep
steps:
- name: Create datastore
  type: awx
  template: create_datastore
  key: datastore        # to create the datastore, we only send the datastore info        
- name: Create vm
  type: awx
  template: create_vm
fields:
  - name: datastore
    type: text
    model: datastore.name
  - name: datastore_size
    type: number
    model: datastore.size
  - name: vm
    type: text
    model: vm.name
  - name: vm_size
    type: number
    model: vm.size

# the extravars of the above example will be somewhat like this :
datastore: 
    name: ds1
    size: 123
vm:        
    name: vm1
    size: 100

# Step 1 will not receive the full set of extravars, due to the 'key: datastore'  
#        it will receive only 'name' (ds1) and 'size' (123) (the contents of key 'datastore')
# Step 2 has no key set, and will receive the full extravars
# Extra : Every step can reference its own key and thus send a piece of the extravars

Run step if ...

In a mulitstep form, by default, Ansible Forms will try to run every step sequentially one after the other.
Using this property you choose if a step should be run or not by setting the property to a part of the extravars that resolves into a boolean (expression or checkbox). This way you can dynamically skip steps.

name: Create something
type: multistep
steps:
- name: Create
  type: awx
  template: create
- name: Send email
  type: awx
  template: send mail
  ifExtraVar: sendmail
fields:
- name: name
  type: text
  label: What to create ?
- name: sendmail
  type: checkbox
  label: Should I send an email ?

Continue on fail

In a mulitstep form, by default, if 1 step fails, the multistep is stopped. However, if you want to continue to the next step, even if the current step failed, use this attribute and set it to true and the multistep will goto the next step. If this happens the status becomes ‘partially success’.

name: Resize volume
type: multistep
steps:
- name: Send email
  type: awx
  template: email
  continue: true       # if email send fails, we still continue
- name: Resize volume
  type: awx
  template: volume resize

Always run

In a mulitstep form, by default, if 1 step fails, the multistep is stopped. However, if you always want to run a certain step, even if a step failed somewhere, use this attribute and set it to true and the specific step will always run.

name: Resize volume
type: multistep
steps:
- name: Load cmdb
  type: awx
  template: load cmdb
- name: Resize volume
  type: awx
  template: volume resize
- name: Send email
  type: awx
  template: email
  always: true       # whether step 1 or 2 fails, this step always runs          

Field name
Alfanumeric + underscore + dash

This attribute represents the name of the form field.

Field type

Other attributes might only be available for some field types.

- type: text
  name: username
  label: Username
  default: ansibleguy
  placeholder: type a username
  required: true
  minLength: 4
  maxLength: 10
  regex:
    expression: "^[a-zA-Z]*$"
    description: Must be alpha numeric
  icon: user
  help: A help message    

# more examples per type, check out the links at the top of the page                                                 

DateType of the datetime picker

The datetime picker can pick several types

Field label
Free text

A friendly name/label for the field

In-field help value
Free text

Some form fields allow an in-field hint value.

Field help message
Free text

Some fields require additional help information. This help message will be shown below the field.

The list of fields in a table
Tablefield object

Every table field has its own separated table fields. The explanation of a tablefield requires a separate help.
You can read of them here. [TODO]

A list of values

To manually populate an enum field

- name: cities
  type: enum
  values:
  - Rome
  - Paris
- name: cities2
  type: enum
  values:
  - name: Rome
    short: RO
  - name: Paris
    short: PA
- name: your_choice
  type: local
  expression: "'You chose $(cities2.name) or just short $(cities2.short)'"

A fixed value (any type) for the expression

To manually populate an expression field (dictionary, array, number, boolean, string).
runLocal will be ignored.

- name: cities
  type: expression
  value:
  - Rome
  - Paris

- name: myObject
  type: expression
  value:
    foo: bar
    ping: pong

Default value

The type of the value depends on the field type.
Can be string,boolean, number, array or object. When using multiple, the default must be an array.
When using an enum field, you can use the following special values : * __auto__ : select the first * __none__ : select none * __all__ : select all (if multiple is true)

Evaluates default value

A default can be treated as javascript and can thus hold expressions like '$(other_field)'.toUpperCase() or Math.PI or Date.getDate.toISOString()

A javascript expression.
Valid javascript

By default this javascript is evaluated on the server side and limited to predefined functions (for security). However in combination with runLocal, the evaluation is ran in the browsers sandbox and allows the full javascript power. When used in an enum field, the expression must return a flat array or array of flat objects, to make it presentable in a dropdown box.
An expression supports placeholders. Read more about placeholders here. [TODO] Click here to find out more about the predefined functions. [TODO]

tip : use the alias local (type=’expression’,runLocal=true,hide=true,noOutput=true)
tip : use the alias local_out (type=’expression’,runLocal=true,hide=true)
tip : use the alias credential (type=’expression’,runLocal=true,hide=true,asCredential=true)

- name: users
  type: enum
  expression: fn.fnRestBasic('get','http://myapi/user','','credential_name')

- name: superheros
  type: enum
  expression: |
    fnArray.from($(mylist))
    .filterBy({has_ability:true})
    .selectAttr('name','ability')
    .sortBy('name')"
  runLocal: true

- name: numbers
  type: enum
  expression: Array.from({length: 10}, (_, i) => i + 1)
  runLocal: true

- name: uppercase
  type: local
  expression: "'test'.toUpperCase()"
  runLocal: true // this is default with type=local                  
  hide: true     // this is default with type=local
  noOutput: true // this is default with type=local

- name: uppercase
  type: local
  expression: "'test'.toUpperCase()"
  runLocal: true // this is default with type=local                  
  hide: true     // this is default with type=local

Run an expression locally

When running expressions, by default they are run remotely on the server.
But remote expressions are limited to predefined functions.
To unleash more javascript power, use this property.
The code will be evaluated in the sandbox of the browser, offloading the server, saving api-calls and making it more secure.

Allow a manual or auto refresh

A query or expression is by default run once (if it doesn’t contain any dependencies).
Sometimes a refresh would be handy.
Set this property to true to allow a refresh, or set 5s for example to allow auto refresh.

Makes an expression editable

An expression is by default readonly.
By setting this property, you can flip the expression field to a regular text field.

A database connection object

When you want to query data from a database, you will need the proper connection information.
This object has 2 properties : name (pointing to a stored credential name) and type (mysql, sql, postgres, mongodb).

- name: cities
  type: enum
  dbConfig:
    name: CMDB_CONN
    type: mysql
  query: select name, country from cities

- name: user
  type: expression
  dbConfig:
    name: USER_DB_CONN
    type: mongodb
  query: cmdb~users~{"name":"ansibleguy"}
  # the query in mongodb has 3 parts, separated by ~  
  # database, collection and the query in valid json

The query to select data from a database
A valid sql query

This is typically a classic SELECT statement.
However, in the case of mongodb, the query is slightly different. See the examples.
An expression supports placeholders. Read more about placeholders here. [TODO]

- name: cities
  type: enum
  dbConfig:
    name: CMDB_CONN
    type: mysql
  query: select name, country from cities

- name: user
  type: expression
  dbConfig:
    name: USER_DB_CONN
    type: mongodb
  query: cmdb~users~{"name":"ansibleguy"}
  # the query in mongodb has 3 parts, separated by ~  
  # database, collection and the query in valid json      

The column of a selected item that needs to exported as extravar

When you select an item in an enum field, by default the first column is used to send as extravar.
By setting this property, you can change it to another field.
This setting is ignored when outputObject is true.
new in v4.0.20 : setting valueColumn to “*” will export all columns

- name: users
  type: enum
  dbConfig:
    name: CMDB
    type: mysql
  query: SELECT name, username FROM users
  columns:
  - name
  valueColumn: username

The column of a selected item that is used in a placeholder

When you select an item in an enum field and later on you use this field as a placeholder, by default the first column is used as a value.
By setting this property you change the column to be used.
NOTE : this property is somewhat out-of-date since the introduction of the dot-notation.
See examples below.

New in v4.0.20 : setting placeholderColumn to “*” will output the entire record, instead of a single column.

- name: user
  type: enum
  dbConfig:
    name: CMDB
    type: mysql
  query: SELECT name, id FROM users
  columns:
  - name
  placeholderColumn:
  - id
- name: computername
  type: expression
  dbConfig:
    name: CMDB
    type: mysql
  query: SELECT name FROM computers where user_id=$(user)
- name: computername_2nd_example
  type: expression
  dbConfig:
    name: CMDB
    type: mysql
  query: SELECT name FROM computers where user_id=$(user.id)      
  # this example is better readable 
  # and removes the need of the placeholderColumn property

The dependency logical function

This attribute represents the logical function between multiple dependencies.

Show/hide this field based on the values or other fields
Reference to other formfields and their values

Each dependency element is either an object with the following 2 attributes: * name : holds the fieldname. * values : a list of valid values for the referenced field. Or with the following 2 attributes:
* name : holds the fieldname. * isValid : a boolean to check if the referenced is validated or not.
Use in combination with attribute dependencyFn.

- name: add_extra_comment
  label: Add extra comment ?
  type: checkbox
- name: extra_comment
  type: text
  label: Type your extra comment
  dependencies:
  - name: add_extra_comment
    values:
    - true

- name: code
  type: text
  regex: 
    expression: "^[a-z]{3}$"
    description: Must be 3 characters lowercase
  required: true
- name: code_uppercase
  type: expression
  runLocal: true
  expression: "'$(code)'.toUpperCase()"
  dependencies:
  - name: code
    isValid: true     # new in 4.0.13 -> code_uppercase will only be shown if code is validated

- name: job_type
  label: Job type
  type: enum
  values:
  - IT
  - HR
  - Sales
  - Management
- name: has_private_office
  type: checkbox
  label: Has private office ?
- name: office_name
  type: text
  label: What's the name of the office
  dependencyFn: or
  dependencies:
  - name: job_type
    values:
    - Sales
    - Management
  - name: has_private_office
    values:
    - true
- name: office_name2
  type: text
  label: What's the name of the office
  dependencyFn: or
  dependencies:
  - name: "!job_type"     # this will invert/negate - note the wrapping quotes!! needed for valid yaml
    values:
    - IT
    - HR
  - name: has_private_office
    values:
    - true                      

Enable responsiveness

Enable instant responsiveness whilst typing.
Can be important to re-evaluate expressions at every keystroke.

The list of columns that you can filter on

By default the previewColumn or first visible column is used to filter on.
With this property you can filter on the columns you want.

- name: volumes
  type: enum
  dbConfig:
    name: CMDB
    type: mysql
  query: SELECT id, name, title FROM volumes
  columns:
  - name
  - title
  filterColumns:
  - name
  - title                  

Allow table insert

A table can be used to modify existing data. If new data is allowed, set this property to false.

Allow table delete

A table can be used to modify existing data. If you don’t was recoreds to be deleted, set this property to false.

The readonly columns in table

With a tablefield, some fields might need to be readonly, like an id field for example.
Use this property to set the readonly fields.

The insert columns in table

With a tablefield, you can choose which fields are visible during insert. This way you can choose to hide certain fields. Use this property to set the insert fields.

Do not output as extravar

Form fields are by default send as extravars.
If you do not want a field to be sent as extravar, set this attribute to true.

Extravar modelling
An dot-based string notation of an object, or an array of these

By default, a field is sent as a root-extravar.
If you want model the output of the extravars, you can specify a dot-notation of how this field should be modelled.

- name: diskName
  type: text
  model: disk[0].name
- name: diskSize
  type: number
  model: disk[0].size
# the extravars of this example will be like this :
disk:
- name: mydisk
  size: 123

Send credential as extravar

Use the value of this field to search for a credential with the same name
and send that credential (with user and password) hidden to the playbook as extravar.
Since 4.0.16, you can use this in combination with the credentials form-property.

- name: vcenter_creds
  type: expression
  expression: "'vcenter'"
  asCredential: true
- name: vcenter_creds2
  type: credential    # alias for cleaner code
  expression: "'vcenter'"

# in the backend following will happen :
# - lookup credential call 'vcenter'
# - inject credential details in extravars as 'vcenter_creds'

# the extravars will now contain something like this :
vcenter_creds:
  user: admin
  password: T0pS3cr#t!
  host: vcenter1.domain.local
  port: 443

Output the selection of a enum-field as a full object.

When selecting from an enum-field (dropdown), either the first column or
the column defined in valueColumn is sent as an extravar.
If you want the full selected record, use the property.
New in v4.0.20 : valueColumn: “*” has the same behavior, and will output all columns

Adds an additional deletemarker field

When you remove a record in a table, it gets removed.
When working with ansible and idempotency, the playbook never knew it got removed.
You need to explicitly set the status to absent.
So you can add a custom property to the deleted record, marking the record as deleted and sending it to the playbook for removal.

- type: table
  name: member
  expression: "[{firstname:'ansible',lastname:'guy'}]"
  deleteMarker: deleted
  tableFields:
    - name: firstname
      type: text
      icon: user
    - name: lastname
      type: text

Adds an additional insertmarker field

When you add a record in a table, it simply gets added.
When working with ansible and idempotency, your playbook doesn’t know which records are new and which are not.
You might want to explicitly run a taks on only the new records.
So you can add a custom property to the inserted record, marking the record as new.

- type: table
  name: member
  expression: "[{firstname:'ansible',lastname:'guy'}]"
  insertMarker: new
  tableFields:
    - name: firstname
      type: text
      icon: user
    - name: lastname
      type: text  

Disable backend logging

Disables logging in the backend, to hide passwords for example.

- name: password
  type: password
  label: Enter password
  noLog: true

Required field

Makes the field required.

Field minimum length
Integer > 0

Forces a string-field to be at least x long.

Field maximum length
Integer > 0

Forces a string-field to be maximum x long.

Field minimum value
Integer

Forces a number-field to not be lower than…

Field maximum value
Integer

Forces a number-field to not be higher than…

File minimum size
Integer

Forces a file-fields size to not be lower than…

File maximum size
Integer

Forces a file-fields size to not be higher than…

A regular expression validation

Enforces a validation where the current field must match a regular expression. This field requires an object with 2 attributes: * expression : The regular expression * description : A validation message to show when the regex is not matched.

regex:
  expression: "[a-z0-9]+@[a-z]+\.[a-z]{2,3}"
  description: Please type a valid email address

regex:
  expression: "(?=^.{8,}$)(?=.*\d)(?=.*[!@#$%^&*]+)(?![.\n])(?=.*[A-Z])(?=.*[a-z]).*$"
  description: Must be complex (8 or longer ; uppercase ; lowercase ; numeric ; specials)

type: file
regex:
  expression: "pdf$"
  descriptoin: You can only upload pdf files           

A list validation (can not be in list)

Enforces a validation where the current field can not be one of the values in a list (referencing another field). This field requires an object with 2 attributes: * field : The name of the field that holds the list * description : A validation message to show when the validation is not met. (new in v5.0.1 : can have placeholder)

notIn:
  field: list_of_ips  # list_of_ips is an other expression array field
  description: This ip already exists            

A list validation (must be in list)

Enforces a validation where the current field must be one of the values in a list (referencing another field). This field requires an object with 2 attributes: * field : The name of the field that holds the list * description : A validation message to show when the validation is not met. (new in v5.0.1 : can have placeholder)

in:
  field: range_of_ips   # range_of_ips is an other expression array field
  description: This ip must be in the specified range              

An field based validation (field must be true)

Enforces a validation where a referencing (expression) field must be true. This field requires an object with 2 attributes: * field : The name of the referencing field * description : A validation message to show when the validation is not met. (new in v5.0.1 : can have placeholder)

validIf:
  field: rest_api_ping_test  # an other expression field that is returning true or false
  description: The ip is not pingable            

An field based validation (field must be false)

Enforces a validation where a referencing (expression) field must be false. This field requires an object with 2 attributes: * field : The name of the referencing field * description : A validation message to show when the validation is not met. (new in v5.0.1 : can have placeholder)

validIfNot:
  field: rest_api_ping_test  # an other expression field that is returning true or false
  description: The ip is still pingable, shut down the machine first                    

An field based validation (field must be same as other field)
The name of another existing field

Enables a validation where the value of this field must match the value of another field. Perfect for password entry, for example.

- name: password
  type: password
  label: Enter password
- name: password2
  type: password
  label: Enter password again
  sameAs: password
  noOutput: true

Allow form submit on non-evaluated placeholders

When an expression-based field has placeholders,
the default form behaviour is not to allow form submit until all placeholders are resolved. When this attribute is true, the form does not wait for placeholder completion for this field.

Field icon
Free fontawesome 6 icon

Some formfields can hold a nice looking icon. The icon name is a free fontawesome 6 icon. You can find more information at www.fontawesome.com

The field group name
Free text

With this attribute you can group fields together.
When all fields in a group are hidden (due to dependencies), the group is also hidden.

The field line name
Free text

With this attribute you can group fields in a single line together.
Use together with the width parameter to set the width, if not, the width is auto.

The field width
A valid Bulma Column width

With this attribute you can set the width of a field.
Use together wit the line parameter to put fields on 1 line. see www.bulma.io

- type: text
  name: name
  label: Firstname
  group: login
  line: names
- type: text
  name: lastname
  label: Lastname
  group: login
  line: names

Renders text as html

If an expression value has html tags (for example ), it will render the value as such.

- name: feedback
  type: expression
  expression: "'<b style=\"color:red\">Error</b>'"
  isHtml: true

Hides an expression field

Set to true if you want your expression hidden.

Make a dropdown box permanently visible

A enum field is by default a dropdown box. However, you can change that behavior by setting this property.
The dropbox looses it reactivity and becomes a fixed table.

Converts a dropdown box to a horizontal selector

A enum field is by default a dropdown box. However, you can change that behavior by setting this property.
The unselected values are on the left and the selected values on the right. This works in combiniation with sticky.
PctColumns are disabled, due to the space it consumes horizontally.

The list of columns visible in the dropdown box

By default all properties are show in an enum field. With this property you can choose which are visible.

- name: users
  type: enum
  dbConfig:
    name: CMDB
    type: mysql
  query: SELECT id, name, username, zip, city FROM users
  columns:
  - name
  - username

The list of columns that should visualized as a percentage-bar

By default all properties are show with its regular value.
With a percentage it can be nice to visualize it as a graphical bar.
The assumption is that the value is an integer between 0 and 100.

- name: volumes
  type: enum
  dbConfig:
    name: CMDB
    type: mysql
  query: SELECT id, name, used, total, (used/total*100) as used_pct FROM volumes
  columns:
  - name
  - used_pct
  pctColumns:
  - used_pct

The column of the selected item(s) that is shown in the dropdown-preview

When you select an item in an enum field, by default the first column is used as a preview.
By setting this property you change the column to be used.

- name: user
  type: enum
  dbConfig:
    name: CMDB
    type: mysql
  query: SELECT id,name FROM users
  previewColumn: name

Field name
Alfanumeric + underscore + dash

This attribute represents the name of the form field.

Field type

Other attributes might only be available for some field types.

- type: text
  name: username
  label: Username
  default: ansibleguy
  placeholder: type a username
  required: true
  minLength: 4
  maxLength: 10
  regex:
    expression: "^[a-zA-Z]*$"
    description: Must be alpha numeric
  icon: user
  help: A help message    

# more examples per type, check out the links at the top of the page                                                 

DateType of the datetime picker

The datetime picker can pick several types

Field label
Free text

A friendly name/label for the field

In-field help value
Free text

Some form fields allow an in-field hint value.

Field help message
Free text

Some fields require additional help information. This help message will be shown below the field.

Field icon
Free fontawesome 6 icon

Some formfields can hold a nice looking icon. The icon name is a free fontawesome 6 icon. You can find more information at www.fontawesome.com

The field group name
Free text

With this attribute you can group fields together.
When all fields in a group are hidden (due to dependencies), the group is also hidden.

The field line name
Free text

With this attribute you can group fields in a single line together.
Use together with the width parameter to set the width, if not, the width is auto.

The field width
A valid Bulma Column width

With this attribute you can set the width of a field.
Use together wit the line parameter to put fields on 1 line. see www.bulma.io

- type: text
  name: name
  label: Firstname
  group: login
  line: names
- type: text
  name: lastname
  label: Lastname
  group: login
  line: names

The dependency logical function

This attribute represents the logical function between multiple dependencies.

Show/hide this field based on the values or other fields
Reference to other formfields and their values

Each dependency element is either an object with the following 2 attributes: * name : holds the fieldname. * values : a list of valid values for the referenced field. Or with the following 2 attributes:
* name : holds the fieldname. * isValid : a boolean to check if the referenced is validated or not.
Use in combination with attribute dependencyFn.

- name: add_extra_comment
  label: Add extra comment ?
  type: checkbox
- name: extra_comment
  type: text
  label: Type your extra comment
  dependencies:
  - name: add_extra_comment
    values:
    - true

- name: code
  type: text
  regex: 
    expression: "^[a-z]{3}$"
    description: Must be 3 characters lowercase
  required: true
- name: code_uppercase
  type: expression
  runLocal: true
  expression: "'$(code)'.toUpperCase()"
  dependencies:
  - name: code
    isValid: true     # new in 4.0.13 -> code_uppercase will only be shown if code is validated

- name: job_type
  label: Job type
  type: enum
  values:
  - IT
  - HR
  - Sales
  - Management
- name: has_private_office
  type: checkbox
  label: Has private office ?
- name: office_name
  type: text
  label: What's the name of the office
  dependencyFn: or
  dependencies:
  - name: job_type
    values:
    - Sales
    - Management
  - name: has_private_office
    values:
    - true
- name: office_name2
  type: text
  label: What's the name of the office
  dependencyFn: or
  dependencies:
  - name: "!job_type"     # this will invert/negate - note the wrapping quotes!! needed for valid yaml
    values:
    - IT
    - HR
  - name: has_private_office
    values:
    - true                      

Enable responsiveness

Enable instant responsiveness whilst typing.
Can be important to re-evaluate expressions at every keystroke.

Disable backend logging

Disables logging in the backend, to hide passwords for example.

- name: password
  type: password
  label: Enter password
  noLog: true

Enable multi select

Enable multiple select with dropdown boxes.

A list of values

To manually populate an enum field

- name: cities
  type: enum
  values:
  - Rome
  - Paris
- name: cities2
  type: enum
  values:
  - name: Rome
    short: RO
  - name: Paris
    short: PA
- name: your_choice
  type: local
  expression: "'You chose $(cities2.name) or just short $(cities2.short)'"

A fixed value (any type) for the expression

To manually populate an expression field (dictionary, array, number, boolean, string).
runLocal will be ignored.

- name: cities
  type: expression
  value:
  - Rome
  - Paris

- name: myObject
  type: expression
  value:
    foo: bar
    ping: pong

Default value

The type of the value depends on the field type.
Can be string,boolean, number, array or object. When using multiple, the default must be an array.
When using an enum field, you can use the following special values : * __auto__ : select the first * __none__ : select none * __all__ : select all (if multiple is true)

Evaluates default value

A default can be treated as javascript and can thus hold expressions like '$(other_field)'.toUpperCase() or Math.PI or Date.getDate.toISOString()

Required field

Makes the field required.

Field minimum length
Integer > 0

Forces a string-field to be at least x long.

Field maximum length
Integer > 0

Forces a string-field to be maximum x long.

Field minimum value
Integer

Forces a number-field to not be lower than…

Field maximum value
Integer

Forces a number-field to not be higher than…

File minimum size
Integer

Forces a file-fields size to not be lower than…