Creating formfields

Now that you master creating forms, let's focus on the formfields.

Create forms Tablefields

Search

Type Description
text

A text input field

textarea

A textarea input field

datetime

A datetime input field

html

An HTML field

file

A file upload field, the file is uploaded prior to the job start and the extravars will contain the uploaded file info.

number

A number input field

password

A password masked input field

checkbox

A checkbox field

radio

A radio field (multi options)

enum

A multi-column filterable dropdown box

expression

A powerfull javascript driven expression field

table

A table input field (insert, modify, delete)

text formfield

A text input field
Below are the properties that are specifically for a text formfield

Attribute Comments
basic
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

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

name
string / required / unique

Field name
Alfanumeric + underscore + dash

This attribute represents the name of the form field.

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

type
string / required

Field type (= text)

data
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

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

Examples:

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                      

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

output
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

Examples:

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

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

Examples:

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

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
security
noLog
boolean
added in version 2.2.3

Disable backend logging

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

Default:
false

Examples:

1) hide password in log

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

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

Examples:

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              

maxLength
number

Field maximum length
Integer > 0

Forces a string-field to be maximum x long.

Only available with types:
text, expression, password

minLength
number

Field minimum length
Integer > 0

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

Only available with types:
text, expression, password

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

Examples:

1) Check if ip exists

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

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

Examples:

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           

required
boolean

Required field

Makes the field required.

Default:
false
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

Examples:

1) Password doublecheck

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

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)

Examples:

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)

Examples:

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                    

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

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

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

Examples:

1) Name and lastname

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

Examples

- 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     

textarea formfield

A textarea input field
Below are the properties that are specifically for a textarea formfield

Attribute Comments
basic
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

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

name
string / required / unique

Field name
Alfanumeric + underscore + dash

This attribute represents the name of the form field.

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

type
string / required

Field type (= textarea)

data
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

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

Examples:

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                      

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

Examples:

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

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
security
noLog
boolean
added in version 2.2.3

Disable backend logging

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

Default:
false

Examples:

1) hide password in log

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

validation
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
required
boolean

Required field

Makes the field required.

Default:
false
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)

Examples:

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)

Examples:

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                    

visualization
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

Examples:

1) Name and lastname

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

Examples

- type: textarea
  name: comments
  label: Comments
  default: |
    Line 1
    Line 2
  placeholder: add your comments
  required: true
  help: A help message       

datetime formfield

A datetime input field
Below are the properties that are specifically for a datetime formfield

Attribute Comments
basic
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

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

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

name
string / required / unique

Field name
Alfanumeric + underscore + dash

This attribute represents the name of the form field.

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

type
string / required

Field type (= datetime)

data
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

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

Examples:

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                      

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

Examples:

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

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
security
noLog
boolean
added in version 2.2.3

Disable backend logging

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

Default:
false

Examples:

1) hide password in log

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

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

Examples:

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              

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

Examples:

1) Check if ip exists

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

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

Examples:

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           

required
boolean

Required field

Makes the field required.

Default:
false
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)

Examples:

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)

Examples:

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                    

visualization
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

Examples:

1) Name and lastname

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

Examples

- type: datetime
  dateType: date
  name: mydate
  label: Date
  default: "2023-12-01"
  required: true
  help: A help message 
- type: datetime
  dateType: datetime
  name: mydateandtime
  line: Demo1
  label: I will default to now
  evalDefault: true
  default: "new Date().toISOString().substring(0,19).replace('T',' ')"
  required: true                      
- type: datetime
  dateType: datetime
  name: mydateandtime
  label: DateTime
  default: "2023-12-01 13:01:00"
  required: true
  help: A help message       
- type: datetime
  dateType: time
  name: mytime
  label: Time
  default: "13:01:00"
  required: true
  help: A help message     

html formfield

Version4.0.9

An HTML field
Below are the properties that are specifically for a html formfield

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

data
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

Examples:

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

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

Examples:

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                      

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

Examples:

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

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
security
noLog
boolean
added in version 2.2.3

Disable backend logging

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

Default:
false

Examples:

1) hide password in log

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

validation
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
required
boolean

Required field

Makes the field required.

Default:
false
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)

Examples:

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)

Examples:

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                    

visualization
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

Examples:

1) Name and lastname

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

Examples

- type: html
  name: alert
  expression: |
    '<div class="notification is-danger">
      danger mister robinson !
    </div>'
- type: html   
  name: image
  expression: |
    '<img src="https://dummyimage.com/16:9x1080" />' 
- name: header
  type: html
  expression: | 
    '<h3 class="title is-3">Your own title</h3>'          

file formfield

Version4.0.16

A file upload field, the file is uploaded prior to the job start and the extravars will contain the uploaded file info.
Below are the properties that are specifically for a file formfield

Attribute Comments
basic
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

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

name
string / required / unique

Field name
Alfanumeric + underscore + dash

This attribute represents the name of the form field.

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

type
string / required

Field type (= file)

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

Examples:

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                      

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

Examples:

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

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
security
noLog
boolean
added in version 2.2.3

Disable backend logging

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

Default:
false

Examples:

1) hide password in log

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

validation
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
maxSize
number

File maximum size
Integer

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

Only available with types:
file

minSize
number

File minimum size
Integer

Forces a file-fields size to not be lower 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

Examples:

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           

required
boolean

Required field

Makes the field required.

Default:
false
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)

Examples:

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)

Examples:

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                    

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

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

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

Examples:

1) Name and lastname

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

Examples

- type: file
  name: software_image
  label: Upload software image

number formfield

A number input field
Below are the properties that are specifically for a number formfield

Attribute Comments
basic
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

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

name
string / required / unique

Field name
Alfanumeric + underscore + dash

This attribute represents the name of the form field.

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

type
string / required

Field type (= number)

data
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

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

Examples:

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                      

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

Examples:

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

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
security
noLog
boolean
added in version 2.2.3

Disable backend logging

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

Default:
false

Examples:

1) hide password in log

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

validation
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
maxValue
number

Field maximum value
Integer

Forces a number-field to not be higher than…

Only available with types:
number

minValue
number

Field minimum value
Integer

Forces a number-field to not be lower than…

Only available with types:
number

required
boolean

Required field

Makes the field required.

Default:
false
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)

Examples:

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)

Examples:

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                    

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

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

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

Examples:

1) Name and lastname

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

Examples

- type: number
  name: numberfield
  label: Number
  default: '1'
  required: true
  minValue: 0
  maxValue: 10
  help: A help message    

password formfield

A password masked input field
Below are the properties that are specifically for a password formfield

Attribute Comments
basic
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

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

name
string / required / unique

Field name
Alfanumeric + underscore + dash

This attribute represents the name of the form field.

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

type
string / required

Field type (= password)

data
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

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

Examples:

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                      

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

output
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

Examples:

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

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

Examples:

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

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
security
noLog
boolean
added in version 2.2.3

Disable backend logging

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

Default:
false

Examples:

1) hide password in log

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

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

Examples:

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              

maxLength
number

Field maximum length
Integer > 0

Forces a string-field to be maximum x long.

Only available with types:
text, expression, password

minLength
number

Field minimum length
Integer > 0

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

Only available with types:
text, expression, password

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

Examples:

1) Check if ip exists

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

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

Examples:

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           

required
boolean

Required field

Makes the field required.

Default:
false
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

Examples:

1) Password doublecheck

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

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)

Examples:

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)

Examples:

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                    

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

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

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

Examples:

1) Name and lastname

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

Examples

- type: password
  name: mypassword
  label: Password
  default: ''
  required: true
  minLength: 8
  maxLength: 20
  regex:
    expression: "^(?=.*[a-z])(?=.*[A-Z])(?=.*[0-9])(?=.*[!@#\\$%\\^&\\*])"
    description: Must contain at least 1 numeric, 1 special, 1 upper and 1 lower character
  icon: lock
- type: password
  name: mypassword_verify
  label: Verify Password
  default: ''
  sameAs: mypassword       # sameas-validation : value must be the same as the field 'mypassword'
  icon: lock     

checkbox formfield

A checkbox field
Below are the properties that are specifically for a checkbox formfield

Attribute Comments
basic
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

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

name
string / required / unique

Field name
Alfanumeric + underscore + dash

This attribute represents the name of the form field.

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

type
string / required

Field type (= checkbox)

data
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

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

Examples:

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                      

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

Examples:

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

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
security
noLog
boolean
added in version 2.2.3

Disable backend logging

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

Default:
false

Examples:

1) hide password in log

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

validation
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
required
boolean

Required field

Makes the field required.

Default:
false
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)

Examples:

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)

Examples:

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                    

visualization
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

Examples:

1) Name and lastname

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

Examples

- type: checkbox
  name: areyousure
  label: Confirmation
  default: false
  placeholder: are you sure?

radio formfield

A radio field (multi options)
Below are the properties that are specifically for a radio formfield

Attribute Comments
basic
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

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

name
string / required / unique

Field name
Alfanumeric + underscore + dash

This attribute represents the name of the form field.

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

type
string / required

Field type (= radio)

data
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

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

Examples:

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                      

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

Examples:

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

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
security
noLog
boolean
added in version 2.2.3

Disable backend logging

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

Default:
false

Examples:

1) hide password in log

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

validation
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
required
boolean

Required field

Makes the field required.

Default:
false
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)

Examples:

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)

Examples:

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                    

visualization
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

Examples:

1) Name and lastname

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

Examples

- type: radio
  name: linuxfavourite
  label: Choose your favorite linux flavour
  values:
  - CentOS
  - Ubuntu
  - Red Hat
  - Debian
  default: CentOS
  required: true 

- type: radio
  name: linuxfavourite
  label: Choose your favorite linux flavour
  values:
  - label: CentOS
    value: c_os
  - label: Ubuntu
    value: ubu
  - label: Red Hat
    value: rht
  - label: Debian
    value: deb
  default: c_os
  required: true                       

enum formfield

A multi-column filterable dropdown box The enum field will create a powerfull dropdown box with multi-column, multiselect and filter capabilities. The enum field can be used in 3 ways. * fixed list : simply use the values property to set a fixed list * database query : you can use the query and dbConfig property to query a mysql, mssql, postgres, oracle or mongodb. * expression : you can use the expression property to create data. in this case the output of the expression can be : * single item : a single item like a string, integer, … * array of items : an array of strings, integers, … * object : a single 1-dimensional javascript object like {"name":"ansibleforms","description":"is awesome"} * array of objects : an array of objects like [{"name":"ansibleforms","description":"is awesome"},{"name":"ansibleguy","description":"is the best"}]

Filtering : You can just start typing when on an enum field, filtering will happen automatically.
You can tune with filterColumns. Otherwise filtering falls back to the previewColumn or the first visible column.
Multiselect : Use multiple to allow multiselect
Below are the properties that are specifically for a enum formfield

Attribute Comments
basic
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

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

name
string / required / unique

Field name
Alfanumeric + underscore + dash

This attribute represents the name of the form field.

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

type
string / required

Field type (= enum)

data
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

Examples:

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

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

Examples:

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

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

Examples:

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

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

Examples:

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      

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

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

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

Examples:

1) Export name

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

values
array

A list of values

To manually populate an enum field

Only available with types:
enum

Examples:

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

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

Examples:

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                      

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

Examples:

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                  

output
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

Examples:

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

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

Examples:

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

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

security
noLog
boolean
added in version 2.2.3

Disable backend logging

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

Default:
false

Examples:

1) hide password in log

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

validation
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
required
boolean

Required field

Makes the field required.

Default:
false
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)

Examples:

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)

Examples:

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                    

visualization
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

Examples:

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

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.

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

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

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.

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

Examples:

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

Examples:

1) Export name

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

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

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

Examples:

1) Name and lastname

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

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

Examples:

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

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

Examples:

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

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

Examples:

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

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.

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.

Examples:

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                      

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

Examples:

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

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

Examples:

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                  

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.

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

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

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

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

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.

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

Examples:

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

multiple
boolean

Enable multi select

Enable multiple select with dropdown boxes.

Default:
false
Only available with types:
enum

name
string / required / unique

Field name
Alfanumeric + underscore + dash

This attribute represents the name of the form field.

noLog
boolean
added in version 2.2.3

Disable backend logging

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

Default:
false

Examples:

1) hide password in log

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

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

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

Examples:

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

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

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

Examples:

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

Examples:

1) Export name

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

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

Examples:

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      

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

required
boolean

Required field

Makes the field required.

Default:
false
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

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

type
string / required

Field type (= enum)

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)

Examples:

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)

Examples:

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                    

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

Examples:

1) Export name

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

values
array

A list of values

To manually populate an enum field

Only available with types:
enum

Examples:

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

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

Examples:

1) Name and lastname

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

Examples

since queries are so diverse, there is a separate section on queries with examples.

expression formfield

A powerfull javascript driven expression field
Below are the properties that are specifically for a expression formfield

Attribute Comments
basic
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

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

name
string / required / unique

Field name
Alfanumeric + underscore + dash

This attribute represents the name of the form field.

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

type
string / required

Field type (= expression)

data
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

Examples:

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

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.

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

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

Examples:

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

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

Examples:

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      

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

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

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

Examples:

1) list of cities

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

2) custom object

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

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

Examples:

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                      

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

Examples:

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

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

Examples:

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

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
security
noLog
boolean
added in version 2.2.3

Disable backend logging

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

Default:
false

Examples:

1) hide password in log

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

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

Examples:

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              

maxLength
number

Field maximum length
Integer > 0

Forces a string-field to be maximum x long.

Only available with types:
text, expression, password

minLength
number

Field minimum length
Integer > 0

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

Only available with types:
text, expression, password

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

Examples:

1) Check if ip exists

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

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

Examples:

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           

required
boolean

Required field

Makes the field required.

Default:
false
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

Examples:

1) Password doublecheck

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

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)

Examples:

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)

Examples:

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                    

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

hide
boolean

Hides an expression field

Set to true if you want your expression hidden.

Default:
false
Only available with types:
expression

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

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

Examples:

1) Show bold in an expression

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

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

Examples:

1) Name and lastname

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

Examples

since expressions are so diverse, there is a separate section on expressions with examples.

table formfield

A table input field (insert, modify, delete) A table field allows you to manually add multi object arrays.
You can start from an empty list, but you can also retrieve existing data first using :
* database query : you can use the query and dbConfig property to query a mysql, mssql server, postgres, oracle or mongodb. * expression : you can use the expression property to create or retrieve data. in this case the output of the expression can be any type.

Below are the properties that are specifically for a table formfield

Attribute Comments
basic
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

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

name
string / required / unique

Field name
Alfanumeric + underscore + dash

This attribute represents the name of the form field.

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

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

type
string / required

Field type (= table)

data
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

Examples:

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

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

Examples:

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

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

Examples:

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      

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

interaction
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

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

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.

Examples:

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                      

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

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

output
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

Examples:

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

Examples:

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  

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

Examples:

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

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
security
noLog
boolean
added in version 2.2.3

Disable backend logging

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

Default:
false

Examples:

1) hide password in log

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

validation
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
required
boolean

Required field

Makes the field required.

Default:
false
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)

Examples:

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)

Examples:

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                    

visualization
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

Examples:

1) Name and lastname

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

Examples

- type: table
  name: member
  label: Add club members
  expression: "[{department:'HR',firstname:'Ansible',lastname:'Guy',age:46,food:'veggies',paid:true}]"
  allowInsert: true
  allowDelete: true
  insertMarker: isNewItem
  deleteMarker: isRemovedItem
  readonlyColumns:
  - department
  - firstname
  - lastname
  - paid
  required: true
  tableFields:
    - name: department
      label: Department
      type: enum
      from: another_expression_array_field
      columns: []
      valueColumn: column_holding_value
      previewColumn: column_as_preview
      pctColumns: []
      filterColumns: []
      outputObject: false
    - name: firstname
      label: First Name
      type: text
      required: true
      default: ""
      minLength: 2
      regex: 
        expression: "[a-zA-Z]*"
        description: Must be normal characters
      icon: user
    - name: lastname
      label: Last Name
      type: text
      required: true
      default: ""
      minLength: 5
    - name: age
      label: How old ?
      type: number
      required: true
      default: 12
      minValue: 12
      maxValue: 80
    - type: enum
      name: food
      label: Favorite food
      default: veggies
      values:
        - pasta
        - pizza
        - fries
        - steak
        - veggies
    - name: paid
      label: membership
      placeholder: Paid yet ?
      type: checkbox
      required: true
      default: true                                

Tablefield Object

Each tablefield is a miniature form on it’s own. As you will see, many of the form fields are also usable here.

Attribute Comments
basic
name
string / required / unique

Field name
Alfanumeric + underscore + dash

This attribute represents the name of the form field.

type
string / required

Tablefield type

Other attributes might only be available for some tablefield types.

Choices:
  • text
  • textarea
  • number
  • password
  • checkbox
  • datetime
  • enum

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
# more examples at the bottom of this help page         

label
string

Tablefield label
Free text

A friendly name/label for the tablefield

placeholder
string

In-field help value
Free text

Some form fields allow an in-field hint value.

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

data
default
many

Default value

The type of the value depends on the field type.
Can be string,boolean, number, array or object. 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, password, enum, checkbox, datetime

from
string

Datasource
expression reference

In a table we can have an enum field. The source of the data for this enum field must come from the main form.
So this from field points to the expression field that holds the query data.

Only available with types:
enum

outputObject
boolean

Output the selection of an 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 : you can also use valueColumn: “*” to export all columns

Default:
false
Only available with types:
enum

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 value “*” 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

datetime
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

interaction
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  

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

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

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)              

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              

visualization
icon
string

Field icon
Free fontawesome 6 icon

Some tablefields 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, password, enum, datetime

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