Workflow forms

Forms that run one of the designer’s workflows

Runs one of the designer’s workflows (Designer > Workflows), named with workflow:, as AWX runs a workflow job : its nodes run by AWX’s rules (on success, on failure, always, all parents must converge), side by side when they can. A playbook node runs on the RTE as a job of its own, with the node’s inventory, credentials, limit and tags ; an approval node holds the job for approval. The form’s fields reach every node as extra vars. The jobs page draws the workflow, live.

What a node’s playbook gathers with set_stats goes to the nodes after it as extra vars, AWX’s way : from the parents whose link fired, over the node’s extra_data, under the workflow’s extra_vars and the form’s values. It is the node job’s artifacts (Show artifacts, on its page) ; the workflow job keeps all of them.

Three keys of a node are AnsibleForms’ own (AWX ignores them), so a workflow does what a multistep does :

  • runner: <name> on a job template node runs that runner’s template or job instead of a designer playbook - AWX, Semaphore, Rundeck, Jenkins - so one workflow mixes them ; an RTE runner runs the node’s playbook there.
  • if_extra_var: <key> : the node runs only when that extravar is true (as a step’s ifExtraVar) ; not met, it is skipped, and what follows it runs as after a success.
  • extra_vars_key: <key> : the node gets only that key of the extravars, the user copied in (as a step’s key).

Deploy through a workflow

- name: Deploy the app
  type: workflow
  workflow: deploy-app
  roles:
  - admin
  fields:
  - name: release
    type: text

Properties

Properties specific to type: workflow, in addition to the common form properties. The Workflows section describes the workflow files themselves.

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

Workflow
the name of one of the designer's workflows

The workflow a form of type workflow runs : a workflow_job_templates entry of a file in the designer’s Workflows section (the local workflows folder, WORKFLOWS_PATH, or a repository used for workflows), in the AWX export syntax. Two workflows of one name stop the job : rename one of them.

Examples:

1) Run the deploy-app workflow

name: Deploy
type: workflow
workflow: deploy-app
roles:
  - admin
fields: []
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
verbose
boolean
added in version 4.0.0

Run in verbose mode

In ansible core you run a playbook in verbose mode. Enable this attribute to do so.

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

Do not remove the extarvars json file

In ansible core we temporarily store the extravars in a json file. After run, this file is removed. Use this property to disable this behaviour.

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

Let ansible template Jinja in the form's values

A value that contains Jinja ({{ }}, {% %} or {# #}) is passed to the playbook as plain text - ansible receives it marked unsafe and never templates it. Without this, a user could type {{ lookup('pipe', '...') }} into a field and run commands on the RTE. AWX applies the same rule to launch-time extra vars by default.

Set this to true only when the form deliberately passes Jinja for the playbook to evaluate. Values without Jinja are never affected.

Note : You can also dynamically set this property by using a field called __allowJinjaInExtravars__. The field must result in a boolean true.
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