Creating forms

Once you understand the forms.yaml structure, you can now focus on the forms part.
You can choose to either put all the forms in the master forms.yaml file, or you can create several yaml files under the /forms folder.
AnsibleForms will read them all and merge them together.

Forms configuration Formfields

Search

Type Description
ansible

Targets an Ansible Core playbook.

awx

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

multistep

Executes multiple jobs sequentially.
Each step can be a different type (ansible, awx).

ansible Form

Targets an Ansible Core playbook.

Below are the properties that are specifically for a ansible Form

Attribute Comments
basic
playbook
string

Ansible playbook
a valid yaml file

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

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

Only available with types:
ansible

Examples:

1) Run foobar playbook

name: Foobar
type: ansible
playbook: foobar.yaml  

2) Use dynamic playbook name

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

name
string / required / unique

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

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

roles
array / required

Who has access
valid role names

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

Examples:

1) Give access to vmware team

name: Create virtual machine
roles:
- vmAdmins
- vmOperators

categories
array

Categories
valid category name

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

Examples:

1) Category vmware

name: Delete virtual machine
categories:
- Vmware
- Decommissioning     

description
string

Form description
free text

A short description, explaining what the form does.

help
string

Help
valid markdown

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

Examples:

1) blockquote with title, list, italic and bold

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

type
string

Form type (= ansible)

credentials
object
added in version 4.0.16

Send credentials to your playbook/template
key-value pairs

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

Examples:

1) Send vmware and microsoft credentials

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

2) Dynamically send credentials

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

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

  - name: vcenter
    type: enum
    values:
      - vcenter_prod
      - vcenter_dev
    default: ad_prod                     
    asCredential: true

ansibleCredentials
string
added in version 4.0.17

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

Ansible allows to pass default ansible credentials in the form of 2 extravars ansible_user and ansible_password

vaultCredentials
string
added in version 5.0.2

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

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

fields
array

fields
valid field object

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

Examples:

1) Examples

fields:
  - name : name
    label: Your name
    type: text
    required: true
  - name : email
    label: Your email
    type: text
    regex:
      expression: "^[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,4}$"
      description: Please enter a valid email address
    required: true

interaction
approval
object

Add approval point
valid approval object

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

notifications
object

Add Notification
valid notification object

Add email notifications on job status events.

Examples:

1) Send on success

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

onSubmit
array
added in version 3.1.0

Events on submit
valid job status action objects

Once a job is launched, Ansible Forms has a few status events you can act on.
* onSubmit : Triggered the moment the submit button is pressed
* onSuccess : Triggered when the job is finished succesfully
* onFailure : Triggered when the job was not succesful
* onAbort : Triggered when the job was aborted
* onFinish : Triggered when the job is finished, regardless the status

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

Examples:

1) Examples

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

onSuccess
array
added in version 3.1.0

Events on success
valid job status action objects

Once a job is launched, Ansible Forms has a few status events you can act on.
* onSubmit : Triggered the moment the submit button is pressed
* onSuccess : Triggered when the job is finished succesfully
* onFailure : Triggered when the job was not succesful
* onAbort : Triggered when the job was aborted
* onFinish : Triggered when the job is finished, regardless the status

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

Examples:

1) Examples

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

onFailure
array
added in version 3.1.0

Events on failure
valid job status action objects

Once a job is launched, Ansible Forms has a few status events you can act on.
* onSubmit : Triggered the moment the submit button is pressed
* onSuccess : Triggered when the job is finished succesfully
* onFailure : Triggered when the job was not succesful
* onAbort : Triggered when the job was aborted
* onFinish : Triggered when the job is finished, regardless the status

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

Examples:

1) Examples

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

onAbort
array
added in version 3.1.0

Events on abort
valid job status action objects

Once a job is launched, Ansible Forms has a few status events you can act on.
* onSubmit : Triggered the moment the submit button is pressed
* onSuccess : Triggered when the job is finished succesfully
* onFailure : Triggered when the job was not succesful
* onAbort : Triggered when the job was aborted
* onFinish : Triggered when the job is finished, regardless the status

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

Examples:

1) Examples

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

onFinish
array
added in version 3.1.0

Events on finished
valid job status action objects

Once a job is launched, Ansible Forms has a few status events you can act on.
* onSubmit : Triggered the moment the submit button is pressed
* onSuccess : Triggered when the job is finished succesfully
* onFailure : Triggered when the job was not succesful
* onAbort : Triggered when the job was aborted
* onFinish : Triggered when the job is finished, regardless the status

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

Examples:

1) Examples

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

visualization
showHelp
boolean

Show Help

Show the help by default or collapse the help.

Default:
true
icon
string

Form icon
Free fontawesome 6 icon

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

Examples:

1) Trash icon

name: Delete virtual machine
icon: trash

image
string

Form image
valid image url

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

Examples:

1) Microsoft image

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

2) Internet image

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

3) Local image

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

tileClass
string

Form tile background colour
valid 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.

Default:
has-background-light

Examples:

1) warning color

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

2) success light color

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

fieldGroupClasses
object

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:

1) Color fieldgroup

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

workflow
inventory
string

Inventory

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

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

executionEnvironment
string
added in version 5.0.0

Execution Environment

In newer versions of AWX you can choose an execution environment. Use this property to pass it to your template.
Note : You can also dynamically set the executionEnvironment by using a field called __executionEnvironment__. It must be sent as extravar. If this extravar is found it will overwrite the static executionEnvironment.
Note : If you use multistep and you want to dynamically set every step, use the key property and model property to create separate extravars per step.

instanceGroups
array or string
added in version 5.0.0

Instance Groups

In newer versions of AWX you can choose instance groups. Use this property to pass it to your template.
It can be a single string (name of instancegroup) or an array (list of names).
Note : You can also dynamically set the instanceGroups by using a field called __instanceGroups__. It must be sent as extravar. If this extravar is found it will overwrite the static instanceGroups.
Note : If you use multistep and you want to dynamically set every step, use the key property and model property to create separate extravars per step.

scmBranch
string
added in version 5.0.0

SCM Branch

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

awxCredentials
array
added in version 4.0.16

Add awx credentials to your template
name of credential in AWX

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

Examples:

1) Add awx credentials to your template

awx_credentials:
  - vmware_prod
  - ad_prod

2) Dynamically send credentials

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

check
boolean

Run in check mode

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

limit
text

Run against a limited number of hosts
a valid host pattern

In awx and ansible core you run a playbook against limited hosts by supplying a host pattern. Use this attribute to do so.
Note : You can also dynamically set the limit by using a field called __limit__. It must be sent as extravar. If this extravar is found it will overwrite the static check field. The field must result in number (number field or expression) Note : If you use multistep and you want to dynamically set every step, use the key property and model property to create separate extravars per step.

diff
boolean

Run in diff mode

In both awx and ansible core you run a playbook in diff mode. Enable this attribute to do so. Note : You can also dynamically set the check mode by using a field called __diff__. It must be sent as extravar. If this extravar is found it will overwrite the static diff field. The field must result in a boolean (expression or checkbox)
Note : If you use multistep and you want to dynamically set every step, use the key property and model property to create separate extravars per step.

verbose
boolean
added in version 4.0.0

Run in verbose mode

In ansible core you run a playbook in verbose mode. Enable this attribute to do so. Note : You can also dynamically set the verbose mode by using a field called __verbose__. It must be sent as extravar. If this extravar is found it will overwrite the static diff field. The field must result in a boolean (expression or checkbox)
Note : If you use multistep and you want to dynamically set every step, use the key property and model property to create separate extravars per step.

keepExtravars
boolean
added in version 4.0.0

Do not remove the extarvars json file

In ansible core we temporarily store the extravars in a json file. After run, this file is removed. Use this property to disable this behaviour. Note : You can also dynamically set this property by using a field called __keepExtravars__. It must be sent as extravar. If this extravar is found it will overwrite the static diff field. The field must result in a boolean (expression or checkbox)
Note : If you use multistep and you want to dynamically set every step, use the key property and model property to create separate extravars per step.

tags
string

Set tags
comma separated tag-list

In both awx and ansible core you can pass tags. Use this attribute to pass a comma separted list of tags.
Note : You can also dynamically set the tags by using a field called __tags__. It must be sent as extravar. If this extravar is found it will overwrite the static tags.
Note : If you use multistep and you want to dynamically set every step, use the key property and model property to create separate extravars per step.

Examples

1) Ansible Core Form

forms:
  - name: Create a vm
    roles:                                         # reference to roles defined earlier
    - vmware
    description: Create a virtual machine
    help: |
      This Form creates a virtual machine.  it will connect to `vcenter`.  This help is Markdown
      so you can use **markdown** markup to highlight __certain words__.
    showHelp: true                                 # show help on load
    icon: computer                                 # a font awesome icon
    categories:                                    # reference to categories defined earlier
    - Demo
    - Vmware/Linux                                 # Add to a subcategory using the `/` separator
    tileClass: has-background-success-light        # a bulma background color style (https://bulma.io)
    playbook: playbook_vm.yml                      # playbook to launch (only if type = ansible)
    inventory: inventory.yml                       # optional ansible inventory file
    check: false                                   # run in checkmode or not
    diff: false                                    # show differences
    verbose: false                                 # verbose output
    keepExtravars: false                           # keep extravars json file                  
    tags: vm,create                                # optional ansible tags (comma separated)
    type: ansible                                  # type is awx or ansible
    onSubmit:                                      # event handler on form submit
      - clear: 0                                   # clear form after 0 seconds
      - hide: 1                                    # hide form after 1 second
    onFinish:                                      # event handler on job finished
      - show: 2                                    # show the form after 2 seconds
    fieldGroupClasses:                             # give fieldgroups a custom background
      groupname1: has-background-info-light
      groupname2: has-background-success-light    
    fields:                                        # list of field objects 

awx Form

Targets an Awx Template.
The AWX Connection token must be set in the settings.
Below are the properties that are specifically for a awx Form

Attribute Comments
basic
template
string

Awx template
a valid awx template name

This attribute is only used when the form type is awx. When using native Ansible, use the property playbook.
Note : You can also dynamically set the template by using a field called __template__. It must be sent as extravar. If this extravar is found it will overwrite the static template name.
Note : If you use multistep and you want to dynamically set every step, use the key property and model property to create separate extravars per step.

Only available with types:
awx

Examples:

1) Run AWX Template Helloworld

name: Helloworld
type: awx
template: Helloworld

2) Use dynamic template name

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

name
string / required / unique

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

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

roles
array / required

Who has access
valid role names

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

Examples:

1) Give access to vmware team

name: Create virtual machine
roles:
- vmAdmins
- vmOperators

categories
array

Categories
valid category name

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

Examples:

1) Category vmware

name: Delete virtual machine
categories:
- Vmware
- Decommissioning     

description
string

Form description
free text

A short description, explaining what the form does.

help
string

Help
valid markdown

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

Examples:

1) blockquote with title, list, italic and bold

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

type
string

Form type (= awx)

credentials
object
added in version 4.0.16

Send credentials to your playbook/template
key-value pairs

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

Examples:

1) Send vmware and microsoft credentials

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

2) Dynamically send credentials

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

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

  - name: vcenter
    type: enum
    values:
      - vcenter_prod
      - vcenter_dev
    default: ad_prod                     
    asCredential: true

ansibleCredentials
string
added in version 4.0.17

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

Ansible allows to pass default ansible credentials in the form of 2 extravars ansible_user and ansible_password

vaultCredentials
string
added in version 5.0.2

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

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

fields
array

fields
valid field object

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

Examples:

1) Examples

fields:
  - name : name
    label: Your name
    type: text
    required: true
  - name : email
    label: Your email
    type: text
    regex:
      expression: "^[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,4}$"
      description: Please enter a valid email address
    required: true

interaction
approval
object

Add approval point
valid approval object

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

notifications
object

Add Notification
valid notification object

Add email notifications on job status events.

Examples:

1) Send on success

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

onSubmit
array
added in version 3.1.0

Events on submit
valid job status action objects

Once a job is launched, Ansible Forms has a few status events you can act on.
* onSubmit : Triggered the moment the submit button is pressed
* onSuccess : Triggered when the job is finished succesfully
* onFailure : Triggered when the job was not succesful
* onAbort : Triggered when the job was aborted
* onFinish : Triggered when the job is finished, regardless the status

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

Examples:

1) Examples

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

onSuccess
array
added in version 3.1.0

Events on success
valid job status action objects

Once a job is launched, Ansible Forms has a few status events you can act on.
* onSubmit : Triggered the moment the submit button is pressed
* onSuccess : Triggered when the job is finished succesfully
* onFailure : Triggered when the job was not succesful
* onAbort : Triggered when the job was aborted
* onFinish : Triggered when the job is finished, regardless the status

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

Examples:

1) Examples

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

onFailure
array
added in version 3.1.0

Events on failure
valid job status action objects

Once a job is launched, Ansible Forms has a few status events you can act on.
* onSubmit : Triggered the moment the submit button is pressed
* onSuccess : Triggered when the job is finished succesfully
* onFailure : Triggered when the job was not succesful
* onAbort : Triggered when the job was aborted
* onFinish : Triggered when the job is finished, regardless the status

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

Examples:

1) Examples

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

onAbort
array
added in version 3.1.0

Events on abort
valid job status action objects

Once a job is launched, Ansible Forms has a few status events you can act on.
* onSubmit : Triggered the moment the submit button is pressed
* onSuccess : Triggered when the job is finished succesfully
* onFailure : Triggered when the job was not succesful
* onAbort : Triggered when the job was aborted
* onFinish : Triggered when the job is finished, regardless the status

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

Examples:

1) Examples

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

onFinish
array
added in version 3.1.0

Events on finished
valid job status action objects

Once a job is launched, Ansible Forms has a few status events you can act on.
* onSubmit : Triggered the moment the submit button is pressed
* onSuccess : Triggered when the job is finished succesfully
* onFailure : Triggered when the job was not succesful
* onAbort : Triggered when the job was aborted
* onFinish : Triggered when the job is finished, regardless the status

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

Examples:

1) Examples

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

visualization
showHelp
boolean

Show Help

Show the help by default or collapse the help.

Default:
true
icon
string

Form icon
Free fontawesome 6 icon

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

Examples:

1) Trash icon

name: Delete virtual machine
icon: trash

image
string

Form image
valid image url

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

Examples:

1) Microsoft image

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

2) Internet image

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

3) Local image

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

tileClass
string

Form tile background colour
valid 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.

Default:
has-background-light

Examples:

1) warning color

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

2) success light color

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

fieldGroupClasses
object

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:

1) Color fieldgroup

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

workflow
inventory
string

Inventory

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

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

executionEnvironment
string
added in version 5.0.0

Execution Environment

In newer versions of AWX you can choose an execution environment. Use this property to pass it to your template.
Note : You can also dynamically set the executionEnvironment by using a field called __executionEnvironment__. It must be sent as extravar. If this extravar is found it will overwrite the static executionEnvironment.
Note : If you use multistep and you want to dynamically set every step, use the key property and model property to create separate extravars per step.

instanceGroups
array or string
added in version 5.0.0

Instance Groups

In newer versions of AWX you can choose instance groups. Use this property to pass it to your template.
It can be a single string (name of instancegroup) or an array (list of names).
Note : You can also dynamically set the instanceGroups by using a field called __instanceGroups__. It must be sent as extravar. If this extravar is found it will overwrite the static instanceGroups.
Note : If you use multistep and you want to dynamically set every step, use the key property and model property to create separate extravars per step.

scmBranch
string
added in version 5.0.0

SCM Branch

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

awxCredentials
array
added in version 4.0.16

Add awx credentials to your template
name of credential in AWX

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

Examples:

1) Add awx credentials to your template

awx_credentials:
  - vmware_prod
  - ad_prod

2) Dynamically send credentials

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

check
boolean

Run in check mode

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

limit
text

Run against a limited number of hosts
a valid host pattern

In awx and ansible core you run a playbook against limited hosts by supplying a host pattern. Use this attribute to do so.
Note : You can also dynamically set the limit by using a field called __limit__. It must be sent as extravar. If this extravar is found it will overwrite the static check field. The field must result in number (number field or expression) Note : If you use multistep and you want to dynamically set every step, use the key property and model property to create separate extravars per step.

diff
boolean

Run in diff mode

In both awx and ansible core you run a playbook in diff mode. Enable this attribute to do so. Note : You can also dynamically set the check mode by using a field called __diff__. It must be sent as extravar. If this extravar is found it will overwrite the static diff field. The field must result in a boolean (expression or checkbox)
Note : If you use multistep and you want to dynamically set every step, use the key property and model property to create separate extravars per step.

verbose
boolean
added in version 4.0.0

Run in verbose mode

In ansible core you run a playbook in verbose mode. Enable this attribute to do so. Note : You can also dynamically set the verbose mode by using a field called __verbose__. It must be sent as extravar. If this extravar is found it will overwrite the static diff field. The field must result in a boolean (expression or checkbox)
Note : If you use multistep and you want to dynamically set every step, use the key property and model property to create separate extravars per step.

keepExtravars
boolean
added in version 4.0.0

Do not remove the extarvars json file

In ansible core we temporarily store the extravars in a json file. After run, this file is removed. Use this property to disable this behaviour. Note : You can also dynamically set this property by using a field called __keepExtravars__. It must be sent as extravar. If this extravar is found it will overwrite the static diff field. The field must result in a boolean (expression or checkbox)
Note : If you use multistep and you want to dynamically set every step, use the key property and model property to create separate extravars per step.

tags
string

Set tags
comma separated tag-list

In both awx and ansible core you can pass tags. Use this attribute to pass a comma separted list of tags.
Note : You can also dynamically set the tags by using a field called __tags__. It must be sent as extravar. If this extravar is found it will overwrite the static tags.
Note : If you use multistep and you want to dynamically set every step, use the key property and model property to create separate extravars per step.

Examples

1) Awx Form

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

multistep Form

Executes multiple jobs sequentially.
Each step can be a different type (ansible, awx).
Below are the properties that are specifically for a multistep Form

Attribute Comments
basic
steps
array

Multistep steps
a step object

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

Only available with types:
multistep

name
string / required / unique

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

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

roles
array / required

Who has access
valid role names

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

Examples:

1) Give access to vmware team

name: Create virtual machine
roles:
- vmAdmins
- vmOperators

categories
array

Categories
valid category name

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

Examples:

1) Category vmware

name: Delete virtual machine
categories:
- Vmware
- Decommissioning     

description
string

Form description
free text

A short description, explaining what the form does.

help
string

Help
valid markdown

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

Examples:

1) blockquote with title, list, italic and bold

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

type
string

Form type (= multistep)

credentials
object
added in version 4.0.16

Send credentials to your playbook/template
key-value pairs

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

Examples:

1) Send vmware and microsoft credentials

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

2) Dynamically send credentials

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

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

  - name: vcenter
    type: enum
    values:
      - vcenter_prod
      - vcenter_dev
    default: ad_prod                     
    asCredential: true

ansibleCredentials
string
added in version 4.0.17

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

Ansible allows to pass default ansible credentials in the form of 2 extravars ansible_user and ansible_password

vaultCredentials
string
added in version 5.0.2

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

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

fields
array

fields
valid field object

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

Examples:

1) Examples

fields:
  - name : name
    label: Your name
    type: text
    required: true
  - name : email
    label: Your email
    type: text
    regex:
      expression: "^[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,4}$"
      description: Please enter a valid email address
    required: true

interaction
approval
object

Add approval point
valid approval object

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

notifications
object

Add Notification
valid notification object

Add email notifications on job status events.

Examples:

1) Send on success

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

onSubmit
array
added in version 3.1.0

Events on submit
valid job status action objects

Once a job is launched, Ansible Forms has a few status events you can act on.
* onSubmit : Triggered the moment the submit button is pressed
* onSuccess : Triggered when the job is finished succesfully
* onFailure : Triggered when the job was not succesful
* onAbort : Triggered when the job was aborted
* onFinish : Triggered when the job is finished, regardless the status

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

Examples:

1) Examples

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

onSuccess
array
added in version 3.1.0

Events on success
valid job status action objects

Once a job is launched, Ansible Forms has a few status events you can act on.
* onSubmit : Triggered the moment the submit button is pressed
* onSuccess : Triggered when the job is finished succesfully
* onFailure : Triggered when the job was not succesful
* onAbort : Triggered when the job was aborted
* onFinish : Triggered when the job is finished, regardless the status

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

Examples:

1) Examples

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

onFailure
array
added in version 3.1.0

Events on failure
valid job status action objects

Once a job is launched, Ansible Forms has a few status events you can act on.
* onSubmit : Triggered the moment the submit button is pressed
* onSuccess : Triggered when the job is finished succesfully
* onFailure : Triggered when the job was not succesful
* onAbort : Triggered when the job was aborted
* onFinish : Triggered when the job is finished, regardless the status

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

Examples:

1) Examples

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

onAbort
array
added in version 3.1.0

Events on abort
valid job status action objects

Once a job is launched, Ansible Forms has a few status events you can act on.
* onSubmit : Triggered the moment the submit button is pressed
* onSuccess : Triggered when the job is finished succesfully
* onFailure : Triggered when the job was not succesful
* onAbort : Triggered when the job was aborted
* onFinish : Triggered when the job is finished, regardless the status

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

Examples:

1) Examples

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

onFinish
array
added in version 3.1.0

Events on finished
valid job status action objects

Once a job is launched, Ansible Forms has a few status events you can act on.
* onSubmit : Triggered the moment the submit button is pressed
* onSuccess : Triggered when the job is finished succesfully
* onFailure : Triggered when the job was not succesful
* onAbort : Triggered when the job was aborted
* onFinish : Triggered when the job is finished, regardless the status

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

Examples:

1) Examples

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

visualization
showHelp
boolean

Show Help

Show the help by default or collapse the help.

Default:
true
icon
string

Form icon
Free fontawesome 6 icon

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

Examples:

1) Trash icon

name: Delete virtual machine
icon: trash

image
string

Form image
valid image url

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

Examples:

1) Microsoft image

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

2) Internet image

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

3) Local image

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

tileClass
string

Form tile background colour
valid 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.

Default:
has-background-light

Examples:

1) warning color

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

2) success light color

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

fieldGroupClasses
object

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:

1) Color fieldgroup

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

workflow
inventory
string

Inventory

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

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

executionEnvironment
string
added in version 5.0.0

Execution Environment

In newer versions of AWX you can choose an execution environment. Use this property to pass it to your template.
Note : You can also dynamically set the executionEnvironment by using a field called __executionEnvironment__. It must be sent as extravar. If this extravar is found it will overwrite the static executionEnvironment.
Note : If you use multistep and you want to dynamically set every step, use the key property and model property to create separate extravars per step.

instanceGroups
array or string
added in version 5.0.0

Instance Groups

In newer versions of AWX you can choose instance groups. Use this property to pass it to your template.
It can be a single string (name of instancegroup) or an array (list of names).
Note : You can also dynamically set the instanceGroups by using a field called __instanceGroups__. It must be sent as extravar. If this extravar is found it will overwrite the static instanceGroups.
Note : If you use multistep and you want to dynamically set every step, use the key property and model property to create separate extravars per step.

scmBranch
string
added in version 5.0.0

SCM Branch

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

awxCredentials
array
added in version 4.0.16

Add awx credentials to your template
name of credential in AWX

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

Examples:

1) Add awx credentials to your template

awx_credentials:
  - vmware_prod
  - ad_prod

2) Dynamically send credentials

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

check
boolean

Run in check mode

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

limit
text

Run against a limited number of hosts
a valid host pattern

In awx and ansible core you run a playbook against limited hosts by supplying a host pattern. Use this attribute to do so.
Note : You can also dynamically set the limit by using a field called __limit__. It must be sent as extravar. If this extravar is found it will overwrite the static check field. The field must result in number (number field or expression) Note : If you use multistep and you want to dynamically set every step, use the key property and model property to create separate extravars per step.

diff
boolean

Run in diff mode

In both awx and ansible core you run a playbook in diff mode. Enable this attribute to do so. Note : You can also dynamically set the check mode by using a field called __diff__. It must be sent as extravar. If this extravar is found it will overwrite the static diff field. The field must result in a boolean (expression or checkbox)
Note : If you use multistep and you want to dynamically set every step, use the key property and model property to create separate extravars per step.

verbose
boolean
added in version 4.0.0

Run in verbose mode

In ansible core you run a playbook in verbose mode. Enable this attribute to do so. Note : You can also dynamically set the verbose mode by using a field called __verbose__. It must be sent as extravar. If this extravar is found it will overwrite the static diff field. The field must result in a boolean (expression or checkbox)
Note : If you use multistep and you want to dynamically set every step, use the key property and model property to create separate extravars per step.

keepExtravars
boolean
added in version 4.0.0

Do not remove the extarvars json file

In ansible core we temporarily store the extravars in a json file. After run, this file is removed. Use this property to disable this behaviour. Note : You can also dynamically set this property by using a field called __keepExtravars__. It must be sent as extravar. If this extravar is found it will overwrite the static diff field. The field must result in a boolean (expression or checkbox)
Note : If you use multistep and you want to dynamically set every step, use the key property and model property to create separate extravars per step.

tags
string

Set tags
comma separated tag-list

In both awx and ansible core you can pass tags. Use this attribute to pass a comma separted list of tags.
Note : You can also dynamically set the tags by using a field called __tags__. It must be sent as extravar. If this extravar is found it will overwrite the static tags.
Note : If you use multistep and you want to dynamically set every step, use the key property and model property to create separate extravars per step.

Examples

1) Multistep form

- name: Create VM
  roles:                                         # reference to roles defined earlier
  - vmware
  description: Create and start a vm
  image: https://picsum.photos/64                # an image url (can be base64)
  categories:                                    # reference to categories defined earlier
  - Demo
  - Vmware
  tileClass: has-background-danger               # a bulma background color style (https://bulma.io)
  type: multistep                                # type is awx, ansible or multistep
  steps:
  - type: awx
    name: Create vm
    template: Create VM
    key: vmInfo
  - type: awx
    name: Start vm
    template: Start VM
    key: vmInfo
  - type: ansible
    name: Email results
    playbook: email.yaml
    always: true                                 # always run this task, even if others failed
  fieldGroupClasses:                             # give fieldgroups a custom background
    groupname1: has-background-info-light
    groupname2: has-background-success-light    
  fields:                                        # list of field objects      

Step Object

Each step is a new form destination. And steps are executed sequentially.
Use specific properties like continue, always and ifExtraVar to control the flow of a multistep form.

Attribute Comments
basic
name
string / required

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

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

type
string

Step type

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

Choices:
  • ansible
  • awx

1) Run AWX Template Helloworld

name: Create vm
type: awx
template: Create VM       

2) Run Ansible playbook

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

template
string

Awx template
a valid awx template name

This attribute is only used when the form type is awx. When using native Ansible, use the property playbook.
Note : You can also dynamically set the template by using a field called __template__. It must be sent as extravar. If this extravar is found it will overwrite the static template name.
Note : If you use multistep and you want to dynamically set every step, use the key property and model property to create separate extravars per step.

Only available with types:
awx

1) Run AWX Template Helloworld

name: Helloworld
type: awx
template: Helloworld

2) Use dynamic template name

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

playbook
string

Ansible playbook
a valid yaml file

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

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

Only available with types:
ansible

1) Run foobar playbook

name: Foobar
type: ansible
playbook: foobar.yaml  

2) Use dynamic playbook name

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

interaction
approval
object

Add approval point
valid approval object

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

1) Approve removal

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

notifications
object

Add Notification
valid notification object

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

1) Send on success

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

workflow
inventory
string

Inventory

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

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

check
boolean

Run in check mode

In both awx and ansible core you run a playbook in check mode. Enable this attribute to do so.
Note : You can also dynamically set the check mode by using a field called __check__. It must be sent as extravar. If this extravar is found it will overwrite the static check field. The field must result in a boolean (expression or checkbox) Note : If you want to dynamically set every step, use the key property and model property to create separate extravars per step.

diff
boolean

Run in diff mode

In both awx and ansible core you run a playbook in diff mode. Enable this attribute to do so. Note : You can also dynamically set the check mode by using a field called __diff__. It must be sent as extravar. If this extravar is found it will overwrite the static diff field. The field must result in a boolean (expression or checkbox)
Note : If you want to dynamically set every step, use the key property and model property to create separate extravars per step.

tags
string

Set tags
comma separated tag-list

In both awx and ansible core you can pass tags. Use this attribute to pass a comma separted list of tags.
Note : You can also dynamically set the tags by using a field called __tags__. It must be sent as extravar. If this extravar is found it will overwrite the static tags.
Note : If you want to dynamically set every step, use the key property and model property to create separate extravars per step.

key
string

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.

1) Resize volume

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

ifExtraVar
extravar reference

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.

1) Run step based on checkbox

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
boolean

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

Default:
false

1)

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
boolean

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.

Default:
false

1)

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          

Formfield Object

Each form contains 1 or more formfields. Each formfield can be heavily tuned with the below parameters.

Attribute Comments
basic
name
string / required / unique

Field name
Alfanumeric + underscore + dash

This attribute represents the name of the form field.

type
string / required

Field type

Other attributes might only be available for some field types.

Choices:
  • text
  • textarea
  • datetime
  • html
  • file
  • number
  • password
  • checkbox
  • radio
  • enum
  • expression
  • table

1) Text

- 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
string
added in version 4.0.2

DateType of the datetime picker

The datetime picker can pick several types

Choices:
  • date
  • datetime
  • time
  • month
  • year
Only available with types:
datetime

label
string

Field label
Free text

A friendly name/label for the field

Only available with types:
text, textarea, datetime, number, password, checkbox, radio, enum, expression, table, file

placeholder
string

In-field help value
Free text

Some form fields allow an in-field hint value.

Only available with types:
text, textarea, datetime, number, password, checkbox, radio, enum, expression, table, file

help
string

Field help message
Free text

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

Only available with types:
text, textarea, datetime, number, password, checkbox, radio, enum, expression, table, file

tableFields
array

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]

Only available with types:
table

data
values
array

A list of values

To manually populate an enum field

Only available with types:
enum

1) list of cities

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

value
any
added in version 4.0.17

A fixed value (any type) for the expression

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

Only available with types:
expression

1) list of cities

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

2) custom object

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

default
many

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)

Only available with types:
text, textarea, number, expression, password, enum, radio, checkbox, datetime

Added4.0.5

A default can now hold placeholders like $(other_field), and together with evalDefault be evaluated as javascript.

evalDefault
boolean
added in version 4.0.5

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

Default:
false
Only available with types:
text, textarea, number, expression, password, enum, radio, checkbox, datetime

expression
string

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)

Only available with types:
enum, expression, table, html

1) Get a list of users from a rest api

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

2) Filter and sort an array of objects

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

3) Make a numbered list

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

4) Use the alias `local`

- 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

5) Use the alias `local_out`

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

runLocal
boolean

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.

Default:
false
Only available with types:
enum, expression, table

refresh
boolean|string

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.

Default:
false
Only available with types:
enum, expression

editable
boolean

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.

Default:
false
Only available with types:
expression

dbConfig
string, array or object

A database connection

When you want to query data from a database, you will need the proper connection information.
We use a credential name to lookup the connection details. Legacy was to pass an object (name and type).
Since version 5.0.2 you can just specify the name of the credential. The type is fetched from the credential itself (mysql, mssql, postgres, oracle or mongodb). In case of no type set, mysql is assumed.
Additionally you can set an array of credential names, to use multiple databases with a single query. The result will be a join of the results.
Doubles will not be removed automatically.

Only available with types:
enum, expression, table

1) get information from a mysql database (legacy example)

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

2) get information from a mysql database (new example)

- name: cities
  type: enum
  dbConfig: CMDB_CONN # type is derived from the credential
  query: select name, country from cities     

3) get information from a mysql database (array example)

- name: cities
  type: enum
  dbConfig: # the query will be a join of the results of the 2 databases
  - CMDB_CONN1
  - CMDB_CONN2
  query: select name, country from cities                                  

4) get information from a mongodb

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

query
string

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]

Only available with types:
expression, enum, table

1) get information from a mysql database

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

2) get information from a mongodb

- 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      

valueColumn
string

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

Default:
first column
Only available with types:
enum

1) Export name

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

placeholderColumn
string

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.

Default:
first column
Only available with types:
enum

1) Export name

- 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

interaction
dependencyFn
string
added in version 4.0.0

The dependency logical function

This attribute represents the logical function between multiple dependencies.

Choices:
  • and (default)
  • or
dependencies
list / elements=object

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.

Added4.0.0

Add an exlamation mark ! before the referencing field’s name, to invert the match. Wrap it in quotes because the ! mark has special meaning in YAML.

Added4.0.13

Add a new way of dependency. Use isValid property to show/hide a field.

1) Show a field based on a checkbox

- 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

2) Show a field if another field is valid

- 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

3) Show a field based on 2 fields, using the 'or' function

- 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                      

keydown
boolean
added in version 2.2.0

Enable responsiveness

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

Default:
false
Only available with types:
text, password

filterColumns
array

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.

Only available with types:
enum

1) Show usage

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

allowInsert
boolean

Allow table insert

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

Default:
true
Only available with types:
table

allowDelete
boolean

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.

Default:
true
Only available with types:
table

readonlyColumns
array

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.

Only available with types:
table

insertColumns
array
added in version 4.0.5

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.

Only available with types:
table

output
noOutput
boolean

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.

Default:
false
model
string or array

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.

Added4.0.9

model can now be an array

Added5.0.1

you can now model arrays

1) Model 2 fields together as a single object

- 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

asCredential
boolean

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.

Default:
false
Only available with types:
text, password, enum, expression

1) Search and send the credential named 'vcenter'

- 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

outputObject
boolean

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

Default:
false
Only available with types:
enum

deleteMarker
string

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.

Only available with types:
table

1) Mark delete record

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

insertMarker
string

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.

Only available with types:
table

1) Mark new record

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

security
noLog
boolean
added in version 2.2.3

Disable backend logging

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

Default:
false

1) hide password in log

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

validation
required
boolean

Required field

Makes the field required.

Default:
false
minLength
number

Field minimum length
Integer > 0

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

Only available with types:
text, expression, password

maxLength
number

Field maximum length
Integer > 0

Forces a string-field to be maximum x long.

Only available with types:
text, expression, password

minValue
number

Field minimum value
Integer

Forces a number-field to not be lower than…

Only available with types:
number

maxValue
number

Field maximum value
Integer

Forces a number-field to not be higher than…

Only available with types:
number

minSize
number

File minimum size
Integer

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

Only available with types:
file

maxSize
number

File maximum size
Integer

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

Only available with types:
file

regex
object

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.

Only available with types:
text, expression, password, datetime, file

1) Validate email address

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

2) Strong password

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

3) Only pdf files

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

notIn
object
added in version 2.2.4

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)

Only available with types:
text, expression, password, datetime

1) Check if ip exists

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

in
object
added in version 2.2.4

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)

Only available with types:
text, expression, password, datetime

1) Check if ip is in range

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

validIf
object
added in version 2.2.4

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)

1) Ip must be pingable

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

validIfNot
object
added in version 2.2.4

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)

1) Check if powered off

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                    

sameAs
string

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.

Only available with types:
text, expression, password

1) Password doublecheck

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

ignoreIncomplete
boolean

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.

Default:
false
visualization
icon
string

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

Only available with types:
text, number, expression, password, enum, file

group
string

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.

line
string
added in version 4.0.3

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.

width
string
added in version 4.0.3

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

Choices:
  • is-three-quarters
  • is-two-thirds
  • is-half
  • is-one-third
  • is-one-quarter
  • is-full
  • is-four-fifths
  • is-three-fifths
  • is-two-fifths
  • is-one-fifth
  • is-1
  • is-2
  • is-3
  • is-4
  • is-5
  • is-6
  • is-7
  • is-8
  • is-9
  • is-10
  • is-11
  • is-12

1) Name and lastname

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

isHtml
boolean

Renders text as html

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

Default:
false
Only available with types:
expression

1) Show bold in an expression

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

hide
boolean

Hides an expression field

Set to true if you want your expression hidden.

Default:
false
Only available with types:
expression

sticky
boolean

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.

Default:
false
Only available with types:
enum

horizontal
boolean
added in version 4.0.3

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.

Default:
false
Only available with types:
enum

columns
array

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.

Only available with types:
enum

1) Show only wanted columns

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

pctColumns
array

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.

Only available with types:
enum

1) Show usage

- 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

previewColumn
string

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.

Default:
first column
Only available with types:
enum

1) Export name

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

name
string / required / unique

Field name
Alfanumeric + underscore + dash

This attribute represents the name of the form field.

type
string / required

Field type

Other attributes might only be available for some field types.

Choices:
  • text
  • textarea
  • datetime
  • html
  • file
  • number
  • password
  • checkbox
  • radio
  • enum
  • expression
  • table

1) Text

- 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
string
added in version 4.0.2

DateType of the datetime picker

The datetime picker can pick several types

Choices:
  • date
  • datetime
  • time
  • month
  • year
Only available with types:
datetime

label
string

Field label
Free text

A friendly name/label for the field

Only available with types:
text, textarea, datetime, number, password, checkbox, radio, enum, expression, table, file

placeholder
string

In-field help value
Free text

Some form fields allow an in-field hint value.

Only available with types:
text, textarea, datetime, number, password, checkbox, radio, enum, expression, table, file

help
string

Field help message
Free text

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

Only available with types:
text, textarea, datetime, number, password, checkbox, radio, enum, expression, table, file

icon
string

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

Only available with types:
text, number, expression, password, enum, file

group
string

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.

line
string
added in version 4.0.3

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.

width
string
added in version 4.0.3

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

Choices:
  • is-three-quarters
  • is-two-thirds
  • is-half
  • is-one-third
  • is-one-quarter
  • is-full
  • is-four-fifths
  • is-three-fifths
  • is-two-fifths
  • is-one-fifth
  • is-1
  • is-2
  • is-3
  • is-4
  • is-5
  • is-6
  • is-7
  • is-8
  • is-9
  • is-10
  • is-11
  • is-12

1) Name and lastname

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

dependencyFn
string
added in version 4.0.0

The dependency logical function

This attribute represents the logical function between multiple dependencies.

Choices:
  • and (default)
  • or
dependencies
list / elements=object

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.

Added4.0.0

Add an exlamation mark ! before the referencing field’s name, to invert the match. Wrap it in quotes because the ! mark has special meaning in YAML.

Added4.0.13

Add a new way of dependency. Use isValid property to show/hide a field.

1) Show a field based on a checkbox

- 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

2) Show a field if another field is valid

- 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

3) Show a field based on 2 fields, using the 'or' function

- 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                      

keydown
boolean
added in version 2.2.0

Enable responsiveness

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

Default:
false
Only available with types:
text, password

noLog
boolean
added in version 2.2.3

Disable backend logging

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

Default:
false

1) hide password in log

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

multiple
boolean

Enable multi select

Enable multiple select with dropdown boxes.

Default:
false
Only available with types:
enum

values
array

A list of values

To manually populate an enum field

Only available with types:
enum

1) list of cities

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

value
any
added in version 4.0.17

A fixed value (any type) for the expression

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

Only available with types:
expression

1) list of cities

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

2) custom object

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

default
many

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)

Only available with types:
text, textarea, number, expression, password, enum, radio, checkbox, datetime

Added4.0.5

A default can now hold placeholders like $(other_field), and together with evalDefault be evaluated as javascript.

evalDefault
boolean
added in version 4.0.5

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

Default:
false
Only available with types:
text, textarea, number, expression, password, enum, radio, checkbox, datetime

required
boolean

Required field

Makes the field required.

Default:
false
minLength
number

Field minimum length
Integer > 0

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

Only available with types:
text, expression, password

maxLength
number

Field maximum length
Integer > 0

Forces a string-field to be maximum x long.

Only available with types:
text, expression, password

minValue
number

Field minimum value
Integer

Forces a number-field to not be lower than…

Only available with types:
number

maxValue
number

Field maximum value
Integer

Forces a number-field to not be higher than…

Only available with types:
number

minSize
number

File minimum size
Integer

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

Only available with types:
file

maxSize
number

File maximum size
Integer

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

Only available with types:
file

regex
object

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.

Only available with types:
text, expression, password, datetime, file

1) Validate email address

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

2) Strong password

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

3) Only pdf files

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

notIn
object
added in version 2.2.4

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)

Only available with types:
text, expression, password, datetime

1) Check if ip exists

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

in
object
added in version 2.2.4

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)

Only available with types:
text, expression, password, datetime

1) Check if ip is in range

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

validIf
object
added in version 2.2.4

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)

1) Ip must be pingable

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

validIfNot
object
added in version 2.2.4

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)

1) Check if powered off

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                    

sameAs
string

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.

Only available with types:
text, expression, password

1) Password doublecheck

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

ignoreIncomplete
boolean

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.

Default:
false
noOutput
boolean

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.

Default:
false
model
string or array

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.

Added4.0.9

model can now be an array

Added5.0.1

you can now model arrays

1) Model 2 fields together as a single object

- 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

asCredential
boolean

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.

Default:
false
Only available with types:
text, password, enum, expression

1) Search and send the credential named 'vcenter'

- 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

outputObject
boolean

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

Default:
false
Only available with types:
enum

expression
string

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)

Only available with types:
enum, expression, table, html

1) Get a list of users from a rest api

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

2) Filter and sort an array of objects

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

3) Make a numbered list

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

4) Use the alias `local`

- 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

5) Use the alias `local_out`

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

runLocal
boolean

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.

Default:
false
Only available with types:
enum, expression, table

refresh
boolean|string

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.

Default:
false
Only available with types:
enum, expression

isHtml
boolean

Renders text as html

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

Default:
false
Only available with types:
expression

1) Show bold in an expression

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

hide
boolean

Hides an expression field

Set to true if you want your expression hidden.

Default:
false
Only available with types:
expression

editable
boolean

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.

Default:
false
Only available with types:
expression

dbConfig
string, array or object

A database connection

When you want to query data from a database, you will need the proper connection information.
We use a credential name to lookup the connection details. Legacy was to pass an object (name and type).
Since version 5.0.2 you can just specify the name of the credential. The type is fetched from the credential itself (mysql, mssql, postgres, oracle or mongodb). In case of no type set, mysql is assumed.
Additionally you can set an array of credential names, to use multiple databases with a single query. The result will be a join of the results.
Doubles will not be removed automatically.

Only available with types:
enum, expression, table

1) get information from a mysql database (legacy example)

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

2) get information from a mysql database (new example)

- name: cities
  type: enum
  dbConfig: CMDB_CONN # type is derived from the credential
  query: select name, country from cities     

3) get information from a mysql database (array example)

- name: cities
  type: enum
  dbConfig: # the query will be a join of the results of the 2 databases
  - CMDB_CONN1
  - CMDB_CONN2
  query: select name, country from cities                                  

4) get information from a mongodb

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

query
string

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]

Only available with types:
expression, enum, table

1) get information from a mysql database

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

2) get information from a mongodb

- 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      

sticky
boolean

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.

Default:
false
Only available with types:
enum

horizontal
boolean
added in version 4.0.3

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.

Default:
false
Only available with types:
enum

columns
array

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.

Only available with types:
enum

1) Show only wanted columns

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

pctColumns
array

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.

Only available with types:
enum

1) Show usage

- 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

filterColumns
array

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.

Only available with types:
enum

1) Show usage

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

valueColumn
string

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

Default:
first column
Only available with types:
enum

1) Export name

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

placeholderColumn
string

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.

Default:
first column
Only available with types:
enum

1) Export name

- 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

previewColumn
string

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.

Default:
first column
Only available with types:
enum

1) Export name

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

allowInsert
boolean

Allow table insert

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

Default:
true
Only available with types:
table

allowDelete
boolean

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.

Default:
true
Only available with types:
table

deleteMarker
string

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.

Only available with types:
table

1) Mark delete record

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

insertMarker
string

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.

Only available with types:
table

1) Mark new record

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

readonlyColumns
array

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.

Only available with types:
table

insertColumns
array
added in version 4.0.5

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.

Only available with types:
table

tableFields
array

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]

Only available with types:
table

Approval point Object

When you want to pause a job and ask for approval first. You can insert an approval point using the approval-object attributes

Attribute Comments
title
string / required

Approval message title
Free text with placeholders

The approval point consists out of a title and message. This is the title attribute.
Note: This supports placeholders (the placeholders point to extravars)

message
string / required

Approval message
Free text with placeholders

The approval point consists out of a title and message. This is the message attribute.
Note: This supports placeholders (the placeholders point to extravars)

roles
array / required

The approver roles
a valid role

Every role in this list will have the power to approve or reject this job.

notifications
array / required

The approval recipients
a valid email address

Every email-address in this list will receive the approval message by email with the approval link.

Notifications Object

When you want to send an email on job-event

Attribute Comments
recipients
array / required

Recipients
email address

A list of email addresses who need to receive a notification

onStatus
array / required

Jobstatus event

A list of jobstatus events you want to send a notification on. Use all, if you always want a notification.

Choices:
  • any
  • success
  • failed
  • aborted

Job Status Action Object

Start a GUI action, triggered by a job status. Such as clear, hide, show, …

Attribute Comments
clear
number

Clear the form
integer >= 0

This action clears the form after x seconds.

hide
number

Hide the form
integer >= 0

This action hides the form after x seconds.

show
number

Show the form
integer >= 0

This action shows the form after x seconds.

home
number

Go to Home
integer >= 0

This action navigates to the home page

reload
number

Reload form
integer >= 0

This action reloads the form (and cleans the job output)

load
string

Load a form
number_of_seconds,name_of_form

This action allows you to load another form.
new in v4.0.20 : the previous jobid is sent as __previous__jobid__.
You must make sure you have this field in your form, it will be populated with the previous jobid.
This is particularly interesting to grab information from the previous job (for example, load output, …)