config.yaml

AnsibleForms uses a config.yaml file for categories and roles configuration. If none is provided, one will be generated with minimum configuration. The config can also be imported into the database, eliminating the need for a config.yaml file.

Overview

The config.yaml file contains the configuration for categories, roles, and constants used by AnsibleForms.

VIDEO: Create your first form

The file below is a minimal sample config.yaml file to start with.
It has only the required default category and the required admin and public roles.

categories: # a list of categories to group forms
  - name: Default
    icon: bars
roles: # a list of roles
  - name: admin
    groups:
      - local/admins
  - name: public
    groups: []
    options:
      allowJobRelaunch: true
constants: {} # free objects to re-use over all forms

Configuration Loading Priority

AnsibleForms loads the config.yaml file in the following order (first match wins):

  1. FROM DATABASE : If config is imported into the database, it will be used (highest priority)
  2. FROM REPOSITORY (use_for_config) : Repository with “use for config” switch enabled (new in 6.1.0)
  3. FROM REPOSITORY (use_for_forms) : Repository with “use for forms” switch enabled (backwards compatibility fallback)
  4. FROM LOCAL FILE : The local config.yaml file (CONFIG_PATH environment variable)
  5. FROM LEGACY FILE : The legacy forms.yaml file (FORMS_PATH environment variable)

Note: Only ONE repository should have “use for config” enabled. If multiple are enabled, a warning will be logged and the first one will be used.

Main Attributes

Attribute Comments
categories
array

Categories
🔗 valid category object

The categories group the forms together in a tree-like view. The Default category is mandatory and holds all forms without a category.

Added 3.1.0

Added nested categories

Examples:

1) Categories

categories:
- name: Default          # is mandatory
  icon: bars
- name: Provisioning
  icon: pencil-alt
- name: Decommissioning
  icon: trash-alt
  items:                 # sub categories
    - name: Linux
      icon: star
    - name: Windows
      icon: bullseye
roles
array

Roles
🔗 valid role object

The roles provide RBAC. Each role has a name and 1 or more groups (local, ldap or azuread). The admin and public rol is mandatory.
Since version 4.0.11 you can also add users (local, ldap or azuread).
Since version 5.0.8 options are introduced to add specific role-options.

  • showDesigner: The user can see the designer
  • showSettings: The user can see the settings page
  • showDebugButtons: The user can see the debug buttons on a form
  • showExtraVars: The user can see the extravars on a form
  • showLogs: The user can see the logs page
  • extendedTokenExpiration: The user can request a token with a longer expiration time (for coding api purposes for example)
  • showAllJobLogs: The user can see all job logs (not only his own) (Added in 5.0.9)
  • enableLogin: The user can login.
  • allowBackupOps: The user can perform database operations, such as backup and restore.
  • allowVerboseMode: The user can enable verbose mode on ansible forms.
  • allowJobRelaunch: The user can relaunch jobs with pre-filled form data from previous submissions.
  • allowScheduledJobs: The user can create and manage scheduled jobs (recurring cron or one-time). (Added in 6.2.0)
  • allowStoredJobs: The user can store and load job data for later use. (Added in 6.2.0)
  • allowPlannedJobs: The user can schedule jobs to run at a specific time. (Added in 6.2.0)

When options are not set, the admin role will have all options.
When options are set on the public role, they will have the lowest precedence and can be used as default options for all roles.
You can add options on role level, which will override the public role options.

The enableLogin option is different, that is for the backend. By default everyone can login.
You can set it to false on public and then enable on the roles you want to give access. Watch out you don’t lock yourself out.

Examples:

1) Roles

roles:
- name: admin        # is mandatory
  groups:
  - local/admins
  - ldap/Domain Admins
  - azuread/Domain Admins
- name: operator
  groups:
  - local/operator
- name: architect
  groups:
  - local/architect
  options:
    showDesigner: true      # architects can see the designer
    showLogs: true          # architects can see the logs
    allowJobRelaunch: true  # architects can relaunch jobs with pre-filled data
- name: demo
  groups:
  - local/demo
- name: usersonly
  users:
  - local/myuser
- name: public        # is mandatory
  groups: []  
  options:
    showDebugButtons: true  # everyone can see the debug buttons
    showExtraVars: true     # everyone can see the extravars
constants
object

Constants
Free object structure

Sometimes you want to have global-like variables. The constants section gives you all freedom. Whether it are objects, arrays, strings, numbers or booleans. They will be available in every form.

Examples:

1) Constants

constants:
  SERVERX: 172.16.0.1 # reference it later as $(SERVERX)
  VCENTER:
    fqdn: vcenter.demo.local  # reference it later as $(VCENTER.fqdn)
    ip: 172.16.0.2

Category Object

A category groups together 1 or more forms.

Attribute Comments
name
string / required / unique

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

The name of a category has to be unique. The Default category is mandatory and holds all non-category forms.
icon
string

Category icon
Free fontawesome 6 icon

You can add a nice icon to your categories. The icon name is a free fontawesome 6 icon. You can find more information at www.fontawesome.com.
items
object
added in version 3.1.0

Sub categories
A category object

A category can have sub categories, which is again a category object.
Examples

1) Categories

categories:
- name: Default          # is mandatory
  icon: bars
- name: Provisioning
  icon: pencil-alt
- name: Decommissioning
  icon: trash-alt
  items:                 # sub categories
    - name: Linux
      icon: star
    - name: Windows
      icon: bullseye

Role Object

A role allows RBAC. Each role has 1 or more groups (local or ldap). Except the public role, which has no groups.
The public and admin roles are mandatory.

Attribute Comments
name
string / required / unique

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

The name of a role has to be unique. The public and admin roles are mandatory.
groups
array / required

Groups
A group (local, ldap or azuread)

A list of groups. They must be in the format of local/groupname or ldap/groupname or azuread/groupname
users
array / required
added in version 4.0.10

User
A user (local, ldap or azuread)

A list of local or ldap users. They must be in the format of local/username or ldap/username or azuread/username
options
object
added in version 5.0.8

Role options
Key value pairs

Since version 5.0.8 you can add specific role options. The options are used to enable or disable certain features for a role.
The options are:

  • showDesigner: The user can see the designer
  • showSettings: The user can see the settings page
  • showDebugButtons: The user can see the debug buttons on a form
  • showExtraVars: The user can see the extravars on a form
  • showLogs: The user can see the logs page
  • extendedTokenExpiration: The user can request a token with a longer expiration time (for coding api purposes for example)
  • showAllJobLogs: The user can see all job logs (not only his own) (Added in 5.0.9)
  • enableLogin: The user can login.
  • allowBackupOps: The user can perform database operations, such as backup and restore.
  • allowVerboseMode: The user can enable verbose mode on ansible forms.
  • allowJobRelaunch: The user can relaunch jobs with pre-filled form data from previous submissions.
  • allowScheduledJobs: The user can create and manage scheduled jobs (recurring cron or one-time). (Added in 6.2.0)
  • allowStoredJobs: The user can store and load job data for later use. (Added in 6.2.0)
  • allowPlannedJobs: The user can schedule jobs to run at a specific time. (Added in 6.2.0)

When options are not set, the admin role will have all options.
When options are set on the public role, they will have the lowest precedence and can be used as default options for all roles.
You can add options on role level, which will override the public role options.
Examples

1) Roles

roles:
- name: admin        # is mandatory
  groups:
  - local/admins
  - ldap/Domain Admins
- name: operator
  groups:
  - local/operator
  users:
  - azuread/mike
- name: architect
  groups:
  - local/architect
  options:
    showDesigner: true # architects can see the designer
    showLogs: true     # architects can see the logs
- name: demo
  groups:
  - local/demo
- name: public        # is mandatory
  groups: []  
  options:
    showDebugButtons: true  # everyone can see the debug buttons
    showExtraVars: true     # everyone can see the extravars

AnsibleForms loads the config.yaml file in the following order (first match wins):

  1. FROM DATABASE - If config is imported into the database (highest priority)
  2. FROM REPOSITORY (use_for_config) - Repository with “use for config” switch enabled
  3. FROM REPOSITORY (use_for_forms) - Repository with “use for forms” switch enabled (backwards compatibility)
  4. FROM LOCAL FILE - The local config.yaml file (CONFIG_PATH environment variable)
  5. FROM LEGACY FILE - The legacy forms.yaml file (FORMS_PATH environment variable)

Only ONE repository should have “use for config” enabled. If multiple are enabled, a warning will be logged and the first one will be used.

Next Steps

Copyright © 2023-2026 AnsibleForms. All rights reserved.