Rundeck Forms

Forms that run a Rundeck job

Runs a job on Rundeck : the one job names (group/name, a name, or the job’s uuid ; template says the same), in the project of the runner named with runner:, or of the default rundeck runner. Only the options the job declares are sent, from the form values of the same name. See the runner property.

Restart a service through Rundeck

- name: Restart service
  type: rundeck
  job: ops/restart-service
  runner: rundeck-ops
  roles:
  - admin

Properties

Properties specific to type: rundeck, in addition to the common form properties.

Basic

Attribute Comments
roles
array / required

Who has access
valid role names

You can have RBAC by adding roles to a form. If you want everyone to see the form, add the default role (public, its old name, works too).
Note : An admin has always access.

Examples:

1) Give access to vmware team

name: Create virtual machine
roles:
- vmAdmins
- vmOperators
categories
array

Categories
valid category name

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

Examples:

1) Category vmware

name: Delete virtual machine
categories:
- Vmware
- Decommissioning
template
string

Template (or job)
the name of a template or job on the runner

What the runner runs : an AWX job or workflow template (type awx, aap, ascender), a Semaphore template (its name or id), a Rundeck or Jenkins job. job: says the same and reads better for a Rundeck or Jenkins form ; a form has one of the two. A playbook form (type ansible) uses playbook instead.

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

Examples:

1) Run AWX Template Helloworld

name: Helloworld
type: awx
roles:
  - default
fields: []
template: Helloworld

2) Use dynamic template name

name: Foobar
type: awx
roles:
  - default
template: HelloWorld
fields:
  - name: __template__
    type: text
    default: Foobar # this will overwrite the template name
credentials
object
added in version 4.0.16

Send credentials to your playbook/template
key-value pairs

From the earlier versions, you could send credentials, stored in Ansible Forms, by using the field-property asCredentials.
From now on, you can also define them statically in the form.
Additionally, you can also set these dynamically by using the a field name credentials.
Note : that this also works in steps, so each step can have its own set of credentials.
Note : If you use multistep and you want to dynamically set every step, use the key property and model property to create separate extravars per step.
Note : The credential can be a regex Note : A second, fallback, credential kan be passed using a comma
Note : The value __self__ sends the connection of Ansible Forms’ own database (host, port, user and password).
Note : A value can also read a secret store directly, without a stored credential : vault:<path> reads the store named vault, secret:<store>:<ref> any store. The role property secretStores limits the stores a user may read this way.

Examples:

1) Send vmware and microsoft credentials

credentials:
  cred_vm: vcenter_creds # will take the credentials calld vcenter_creds and send them in the object `cred_vm`
  cred_ms: ad_creds # will take the credentials called ad_creds and send them in the object `cred_ms`
  cred_netapp: cluster1,clusters2 # will first search for cluster1 and as fallback to cluster2
  cred_veeam: veeam_server[0-9],veeam # will first search for a credential matching the regex, and as fallback search for veeam
  cred_af: __self__ # the connection of the Ansible Forms database
  cred_dns: vault:infra/dns # read straight from the secret store `vault`
  cred_ipam: secret:cyberark:ipam-admin # read straight from the secret store `cyberark`

2) Dynamically send credentials

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

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

  - name: vcenter
    type: enum
    values:
      - vcenter_prod
      - vcenter_dev
    default: ad_prod                     
    asCredential: true
wizard
array
added in version 6.4.0

Wizard steps (form-layer)
a wizard step object

Turn a form into a multi-page wizard.
Where steps splits the execution into multiple jobs, wizard splits the input of a single form into multiple pages.
Each wizard step references a subform and is rendered as its own page with Back / Next navigation. A read-only review page is appended automatically as the last step — you do not declare it in YAML.
See the Wizard page for all step properties and examples.

Examples:

1) Three-step wizard

name: Provision host
type: ansible
roles:
  - default
playbook: provision.yml
wizard:
  - subform: basics
    title: Basics
  - subform: network
    title: Network
    defaultModel: net
  - subform: advanced
    title: Advanced
    optional: true
    when: $(__parent__.basics.kind) === 'vm'

2) Wizard mapped one-to-one onto multistep (defaultModel + key)

name: Provision and verify host
type: multistep
roles:
  - default
wizard:
  - subform: basics
    title: Basics
    defaultModel: basics      # wraps fields under `basics`
  - subform: network
    title: Network
    defaultModel: network     # wraps fields under `network`
steps:
  - name: Create host
    type: ansible
    playbook: create_host.yml
    key: basics                # receives only the basics payload
  - name: Configure network
    type: ansible
    playbook: configure_network.yml
    key: network                # receives only the network payload
varsFiles
array
added in version 6.1.0

Load YAML files as constants
list of file paths (absolute or relative)

Load one or more YAML files as constants that will be merged with the base config constants. Files must contain a dictionary (not a list) and must have .yml or .yaml extension.

Path Resolution:

  • Absolute paths: used as-is (e.g., /opt/shared/vars/database.yaml)
  • Relative paths: resolved against VARS_FILES_PATH environment variable (default: persistent/vars/)

Use Cases:

  • Share common variables across multiple forms
  • Separate sensitive configuration from form definitions
  • Centralize environment-specific settings

Note: Files are merged in order. Later files override earlier ones if keys conflict. Variables from varsFiles are merged with base config constants.

Examples:

1) Load single vars file

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

2) Load multiple vars files with absolute paths

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

3) Mix relative and absolute paths

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

Interaction

Attribute Comments
approval
object

Add approval point
valid approval object

Ansible Forms allows to add an approval point before a job is ran.
An approval link is sent by email to a specific approver who can then approve or reject the job, and to the notification channels it names (channels: Slack, Microsoft Teams, Telegram, a webhook - Connections > Notifications).
notifications
object

Add Notification
valid notification object

Add notifications on job status events : by email (recipients), and to notification channels (channels : Slack, Microsoft Teams, Telegram, a webhook, or a mail server of Connections > Notifications).

Examples:

1) Send on success

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

2) Post to Slack and Teams when it fails

notifications:
  channels:
    - ops-slack
    - ops-teams
  onStatus:
    - failed
onSubmit
array
added in version 3.1.0

Events on submit
valid job status action objects

Once a job is launched, Ansible Forms has a few status events you can act on.

  • onSubmit : Triggered the moment the submit button is pressed
  • onSuccess : Triggered when the job is finished succesfully
  • onFailure : Triggered when the job was not succesful
  • onAbort : Triggered when the job was aborted
  • onFinish : Triggered when the job is finished, regardless the status

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

Examples:

1) Examples

onSubmit:
  - clear: 0   # clear form after submit
  - hide: 2   # seconds later, hide the form
# more examples on the job-status-event page
onSuccess
array
added in version 3.1.0

Events on success
valid job status action objects

Once a job is launched, Ansible Forms has a few status events you can act on.

  • onSubmit : Triggered the moment the submit button is pressed
  • onSuccess : Triggered when the job is finished succesfully
  • onFailure : Triggered when the job was not succesful
  • onAbort : Triggered when the job was aborted
  • onFinish : Triggered when the job is finished, regardless the status

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

Examples:

1) Examples

onSuccess:
  - home: 0    # go home on success
# more examples on the job-status-event page
onFailure
array
added in version 3.1.0

Events on failure
valid job status action objects

Once a job is launched, Ansible Forms has a few status events you can act on.

  • onSubmit : Triggered the moment the submit button is pressed
  • onSuccess : Triggered when the job is finished succesfully
  • onFailure : Triggered when the job was not succesful
  • onAbort : Triggered when the job was aborted
  • onFinish : Triggered when the job is finished, regardless the status

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

Examples:

1) Examples

onFailure:
  - load: 3   # reload form after failure after 3 seconds
# more examples on the job-status-event page
onAbort
array
added in version 3.1.0

Events on abort
valid job status action objects

Once a job is launched, Ansible Forms has a few status events you can act on.

  • onSubmit : Triggered the moment the submit button is pressed
  • onSuccess : Triggered when the job is finished succesfully
  • onFailure : Triggered when the job was not succesful
  • onAbort : Triggered when the job was aborted
  • onFinish : Triggered when the job is finished, regardless the status

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

Examples:

1) Examples

onAbort:
  - clear: 3   # clear form after abort after 3 seconds
# more examples on the job-status-event page
onFinish
array
added in version 3.1.0

Events on finished
valid job status action objects

Once a job is launched, Ansible Forms has a few status events you can act on.

  • onSubmit : Triggered the moment the submit button is pressed
  • onSuccess : Triggered when the job is finished succesfully
  • onFailure : Triggered when the job was not succesful
  • onAbort : Triggered when the job was aborted
  • onFinish : Triggered when the job is finished, regardless the status

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

Examples:

1) Examples

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

Visualization

Attribute Comments
showHelp
boolean

Show Help

Show the help by default or collapse the help.

Default: true
icon
string

Form icon
Free fontawesome 6 icon

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

Examples:

1) Trash icon

name: Delete virtual machine
icon: trash
iconColor
string

Icon color
valid color name

Specifies the color of the icon. Use any valid CSS color class name (e.g., primary, success, danger, warning, info, dark, white, …).

Examples:

1) Red icon

name: My Form
icon: server
iconColor: danger
iconSize
string

Icon size
xs, sm, lg, 2x, 3x, 5x, 7x, 10x

Specifies the size of the icon.

Default: 3x

Examples:

1) Large icon

name: My Form
icon: server
iconSize: 5x
overlayIcon
string

Overlay icon on main icon
valid fontawesome icon name

Adds a icon on top of the main icon for layering effects. Useful for status indicators or badges.

Examples:

1) Server with check overlay

name: Server Status OK
icon: server
overlayIcon: check
overlayIconColor: success
overlayIconTransform: shrink-6 up-7 right-7
overlayIconTransform
string

Transform for overlay icon
valid fontawesome transform

Specifies the transform/positioning for the overlay icon. You can use FontAwesome transform values like shrink, grow, up, down, left, right.

Default: shrink-6 up-7 right-7

Examples:

1) Custom positioned overlay

name: My Form
icon: circle
overlayIcon: check
overlayIconTransform: shrink-8 down-2
overlayIconColor
string

Color for overlay icon
valid color name

Specifies the color of the overlay icon.

Default: success

Examples:

1) Red overlay icon

name: Alert Status
icon: circle
overlayIcon: exclamation
overlayIconColor: danger
overlayIconCircle
boolean

Show circle background behind overlay icon

When enabled, shows a colored circle background behind the overlay icon. The circle uses the overlayIconColor, and the icon inside becomes white in light mode or dark in dark mode. When disabled, the overlay icon appears without a circle background.

Default: true

Examples:

1) Overlay without circle

name: My Form
icon: server
overlayIcon: check
overlayIconCircle: false
overlayIconColor: success
overlayIconText
string

Text overlay on icon
any text

Adds text as an overlay on the icon. Can be used for badges, counters, or labels.

Examples:

1) New badge

name: New Feature
icon: star
overlayIconText: "New!"
overlayIconTextPosition: top-right
overlayIconTextColor: warning
overlayIconTextPosition
string

Position for text overlay
top-left, top-right, bottom-left, bottom-right

Specifies the position of the text overlay.

Default: bottom-left

Examples:

1) Top right badge

name: Notification
icon: bell
overlayIconText: "3"
overlayIconTextPosition: top-right
overlayIconTextColor
string

Color for text overlay
valid color name

Specifies the color of the text overlay.

Default: success

Examples:

1) Warning badge

name: Pending Items
icon: inbox
overlayIconText: "!"
overlayIconTextColor: warning
image
string

Form image
valid image url

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

Examples:

1) Microsoft image

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

2) Internet image

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

3) Local image

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

Form tile background colour
valid bootstrap background class

Ansible Forms uses the Bootstrap css framework to style the webapplication.
Bootstrap has a few color helper classes you can use to give your formtile a background color.
You can find them here background color and foreground color.
Hint: Try to add a matching foreground color.

Default: bg-info-subtle

Examples:

1) warning color

name: Cleanup jobs
icon: trash
tileClass: bg-warning text-light

2) success light color

name: New job
icon: plus
tileClass: bg-success-subtle text-dark
fieldGroupClasses
object

Fieldgroup background color
key-value pairs

Ansible Forms uses the Bootstrap css framework to style the webapplication. Bootstrap has a few color helper classes you can use to give your fieldgroups a background color. You can find them here background color and foreground color.

Examples:

1) Color fieldgroup

fieldGroupClasses:                             # give fieldgroups a custom background
  groupname1: bg-info-subtle
  groupname2: bg-success-subtle
order
integer
added in version 5.1.0

Order of the form in the list

The order of the form in the list of forms. Forms are sorted by this order, so you can have a specific order in the list. Note : If you do not set this property, it will be ordered alphabetically by name.

Workflow

Attribute Comments
inventory
string

Inventory

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

Ansible : the name of an inventory of the designer’s Inventories section (inventory: production) runs the playbook against that inventory - its inventory.yaml with the group_vars and host_vars beside it : the repository of that name used for inventories (use_for_inventories, the inventory at its root), or the folder of that name in INVENTORY_PATH. Anything else (a path, a file) is passed to ansible as it is, relative to the playbooks folder.

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

Examples:

1) Run against an inventory of the designer

- name: Patch the web servers
  type: ansible
  playbook: patch.yaml
  inventory: production
  roles:
  - admin
runner
string
added in version 7.0.0

Where the job runs
the name of a runner (Connections > Runners)

The runner that runs this form’s job, of the type the form’s type asks for : rte (a runtime environment container) for ansible, awx (AWX / Ansible Automation Platform / Ascender) for awx, aap and ascender, and semaphore, rundeck, jenkins for the forms of that type. Runners are added under Connections > Runners. A runner of another type fails the job and says which type to name. Without this property the default runner of the form’s type is used (every type has one : the first runner of a type, or the one chosen under Edit defaults) ; without a default the job fails and says how to add one. Since 7 AnsibleForms runs no playbook itself.

Semaphore : a form of type semaphore runs the Semaphore template named by template (its name, or its id) in the runner’s project. The form’s values and its resolved credentials are its extra vars ; check and diff are passed on. inventory (a name or an id) runs it on another of the project’s inventories - with that inventory’s key - and limit on fewer hosts : both need “Allow override inventory” / “Allow override limit” on the template in Semaphore, and without it the job fails rather than run on other hosts than the form asked for. verbose needs “Allow debug” ; without it the output is not verbose. awxCredentials, executionEnvironment, instanceGroups and scm_branch are AWX’s and are not used.

Rundeck : a form of type rundeck runs the Rundeck job named by job (or template) - group/name, a bare name, or the job’s uuid - in the runner’s project. Only the job’s own options are sent, each from the form value or credential of the same name (a list or an object as its json) ; other values stay in AnsibleForms. limit becomes the node filter, verbose the DEBUG log level ; the AWX properties are not used. The job’s output is shown as Rundeck logs it, its error lines in red ; once it comes from several nodes, each line starts with its [node]. What the form sends is shown as the job’s payload (Rundeck’s word ; the other types call it extravars) ; the API takes and answers both names.

Jenkins : a form of type jenkins builds the Jenkins job named by job (or template) - its name, or its path when it is in a folder (ops/deploy), under the runner’s folder when the runner has one. Only the job’s own parameters are sent, each from the form value or credential of the same name (a list or an object as its json) ; other values stay in AnsibleForms. The build waits in Jenkins’ queue as any other (the job output says why), then its console is shown as Jenkins writes it ; a result other than SUCCESS fails the job, an abort stops the build. The AWX properties are not used.

Examples:

1) Run on the vmware runtime

- name: Create a vm
  type: ansible
  playbook: create_vm.yaml
  runner: rte-vmware

2) Run a template on a named AAP

- name: Deploy
  type: awx
  template: deploy
  runner: aap-prod

3) Run a Semaphore template

- name: Deploy
  type: semaphore
  template: deploy
  runner: semaphore-ops

4) Run a Rundeck job

- name: Restart service
  type: rundeck
  job: ops/restart-service
  runner: rundeck-ops

5) Build a Jenkins job

- name: Deploy
  type: jenkins
  job: ops/deploy-pipeline
  runner: jenkins-ci
awx
string
added in version 6.0.0

Deprecated alias of runner
name of a runner of type awx

Deprecated since 7, removed in 8. Use runner. AWX/AAP connections are runners of type awx since 7 (Connections > Runners) ; the upgrade moves the existing ones there. awx: <name> still names that runner, with a warning in the log.

Note : you can also set these dynamically by using a field called __awx__. It must be sent as extravar. If this extravar is found it will overwrite the static awx.
Note : this also works in steps, so each step can have its own set of awx instances.
Note : If you use multistep and you want to dynamically set every step, use the key property and model property to create separate extravars per step.

Examples:

1) Add awx instance to your template

awx: my_awx_instance
check
boolean

Run in check mode

In both awx and ansible core you run a playbook in check mode. Enable this attribute to do so.

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

Run against a limited number of hosts
a valid host pattern

In awx and ansible core you run a playbook against limited hosts by supplying a host pattern. Use this attribute to do so.

Note : You can also dynamically set the limit by using a field called __limit__. It must be sent as extravar. If this extravar is found it will overwrite the static check field. The field must result in number (number field or expression) Note : If you use multistep and you want to dynamically set every step, use the key property and model property to create separate extravars per step.
diff
boolean

Run in diff mode

In both awx and ansible core you run a playbook in diff mode. Enable this attribute to do so.

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

Which keys of the user go into the extravars

Overrides the EXTRAVARS_USER_FIELDS environment variable for this form, so one form can ask for the full user object while the rest of the instance stays trimmed, or the other way around.

Leave it out and the form follows the global setting. all sends the whole ansibleforms_user object, none sends no ansibleforms_user at all, and a comma separated list such as username,email,type sends only those top level keys.

Note : a multistep applies the form’s value to every step, including the partial extravars a step receives through key.
abortable
boolean
added in version 5.0.8

Allow aborting the job

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

Default: true
allowRelaunch
boolean
added in version 6.2.0

Allow relaunching the job

By default, users with the allowJobRelaunch role option can relaunch any job.
Set this to false to prevent relaunching this specific form, regardless of user permissions.

Default: true

Examples:

1) Prevent relaunching a form

- name: Production Deployment
  allowRelaunch: false
launchValidation
string
added in version 6.4.1

Check every launch of this form on the server
off, log, enforce

Checks every launch of this form on the server against its validation rules, with the same engine the browser and the MCP server use - see the LAUNCH_VALIDATION environment variable for what log and enforce do.

Set it on a form that is launched over the REST API : with enforce, a launch that breaks the form’s rules is refused, and the job runs the extravars the server builds from the checked values - whatever the caller sent as extravars.

Mind the fields the server computes again : a timestamp (fn.fnTime()), a query or REST result that changed, or a runLocal expression using the browser’s timezone or locale can come out different from what the user saw, and the server’s value runs. See LAUNCH_VALIDATION ; try log first, it names the keys that differ.

The stricter of this property and LAUNCH_VALIDATION wins : a form can be made stricter than the instance, never looser. The MCP server always validates and builds the extravars itself, whatever this says.

A wizard form is checked step by step : every step the browser submits is resolved against its subform. See the Launch validation page of the documentation.

Default: the LAUNCH_VALIDATION environment variable

Examples:

1) A form that is launched over REST

- name: Create VM
  type: ansible
  roles:
    - default
  fields: []
  playbook: vm.yml
  launchValidation: enforce
enableForChat
boolean
added in version 6.5.0

Offer this form in the chat assistant

The chat assistant (ENABLE_CHAT) only offers the forms that set enableForChat: true - and of those, only the ones the user’s roles may open. It is the only allowlist : a form without it is never discussed, resolved or launched by the chat, even for a user who may open it in the browser.

The assistant fills the form in with the user, through the same form engine as the browser, and never launches it : the user clicks Launch on the exact payload the chat showed. Not for wizard forms.

Default: false

Examples:

1) A form the chat may offer

- name: Create a snapshot
  type: ansible
  roles:
    - default
  fields: []
  playbook: snapshot.yml
  enableForChat: true
tags
string

Set tags
comma separated tag-list

In both awx and ansible core you can pass tags. Use this attribute to pass a comma separted list of tags.

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