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

FROM DATABASE : If config is imported into the database, it will be used (highest priority)
FROM REPOSITORY (use_for_config) : Repository with “use for config” switch enabled (new in 6.1.0)
FROM REPOSITORY (use_for_forms) : Repository with “use for forms” switch enabled (backwards compatibility fallback)
FROM LOCAL FILE : The local config.yaml file (CONFIG_PATH environment variable)
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

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. allowJobRelaunch: The user can relaunch jobs with pre-filled form data from previous submissions. 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`

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.
allowJobRelaunch: The user can relaunch jobs with pre-filled form data from previous submissions.

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. 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):

FROM DATABASE - If config is imported into the database (highest priority)
FROM REPOSITORY (use_for_config) - Repository with “use for config” switch enabled
FROM REPOSITORY (use_for_forms) - Repository with “use for forms” switch enabled (backwards compatibility)
FROM LOCAL FILE - The local config.yaml file (CONFIG_PATH environment variable)
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

Categories - Learn about organizing forms
Roles - Set up RBAC
Constants - Define global variables