Skip to main content

Overview

Forms enable structured data collection that can trigger workflows. A form defines a set of typed fields that users fill out via Slack. When submitted, the form data is available to workflow actions via CEL expressions. Forms are useful for Access requests: Enable users to request access to perform specific actions on resources with time-bound parameters for policy suspensions.

Form Structure

A form consists of:
  • Name: A unique name within your organization
  • Description: Optional description shown to users when filling out the form
  • Fields: One or more typed fields for data collection

Field Types

Text and numeric inputs:
  • string — Plain text input
  • number — Numeric input
  • email — Email address input
  • url — URL input
Date and time inputs:
  • date — Date picker
  • time — Time picker
  • timestamp — Combined date and time picker
Selection inputs (require options configuration — see below):
  • select — Single-select dropdown
  • multi_select — Multi-select dropdown
  • checkbox — Checkbox group
  • radio — Radio button group

Field IDs

Each field has an id that must match the pattern field_[_a-zA-Z0-9]+. This ID is used to reference field values in workflow actions via trigger.form_submission.submission.field_<id>, and in validation rules and conditions.

Optional Fields

Fields are required by default. Set optional to let users leave a field empty. An unanswered optional field is submitted as "", or [] for multi_select and checkbox, so workflow expressions that reference it still resolve.

Validation Rules

A field can have a validation rule: a CEL expression that must evaluate to true when the form is submitted, and an optional error message (up to 100 characters). Fields are variables named by their ID, with the values workflows receive. In Slack, a failing rule shows its message under the field and the form stays open, so the user can fix the answer without starting over. A rule that errors also fails. A rule on an optional field must accept the empty answer, for example field_hours == "" || field_hours <= 24.

Conditional Fields and Options

A field, or a static option of a selection field, can have a visible_if condition: a CEL expression over the answers to earlier select, radio, multi_select, and checkbox fields. The field or option is shown only when the condition is true.
  • Hidden fields are left empty and their rules are skipped.
  • If all of a field’s options are hidden, the field is hidden too.
  • Only options currently shown can be submitted.
  • If a condition breaks, the form can’t be submitted until an admin fixes it.
Conditions are checked when the form is saved, so a condition can only reference earlier selection fields and must evaluate to a bool. In the form builder, each field has a Rules & conditions section for the optional switch, the validation rule, and the condition, and each static option can have its own condition. The preview applies conditions as you pick answers.

Example

An access request where the duration and ticket depend on the environment, and sensitive data needs a justification:

Selection Field Options

The select, multi_select, checkbox, and radio field types all require an options configuration: either static options or a dynamic options source, not both.

Static Options

Provide a fixed list of options directly in the field configuration. Each option has a label (displayed to the user) and a value (submitted with the form).

Dynamic Options

Dynamic sources populate a selection field by calling a List endpoint on Formal’s API. This is useful when the set of options changes over time (e.g., listing resources, users, or datastores). A dynamic source has the following configuration: The searchFields parameter in the input controls which fields the search term is matched against. For example, "searchFields": ["name", "technology", "hostname"] restricts matching to those three fields on the target resource.

Options That Depend on an Earlier Answer

${{ field_<id> }} in the input is replaced with the answer to that field, so the options follow an earlier choice. For example, to list only the resources of the technology the user picked:
  • The referenced field must be an earlier select or radio field with static options. Answers are checked against those options before the call runs as the machine user.
  • The field stays hidden until every referenced field is answered, so an empty filter never lists everything.
  • In Slack, changing the referenced answer refreshes the options.

Filling Out Forms

Slack Integration

Forms can be filled out via Slack using the “Fill out form” shortcut. A Slack integration needs to be linked to your Formal organization.

Slash Command

Type /formal form to open a modal where you can select and fill out a form.

Submission Flow

  1. User opens the form shortcut in Slack
  2. User selects a form from the searchable dropdown
  3. User fills out the fields. Picking a choice updates the form, showing or hiding fields and options that depend on it
  4. User submits. Answers that fail a validation rule, or options no longer offered, are flagged under their field and the form stays open
  5. A confirmation message with the submitted values is sent to the user
  6. Any workflows with a matching form-submission trigger are executed

Formal Endpoint

Forms can also be filled out via the Formal Endpoint.

Submission Flow

  1. User opens the Formal Endpoint
  2. User runs formal form fill and selects a form from the shown list
  3. User fills out the fields and submits
  4. A confirmation message with the submitted values is shown to the user, along with a command to submit the same payload again without needing to re-select the form
  5. Any workflows with a matching form-submission trigger are executed
You can also display forms and their fields using formal form list -o [jsonl|yaml] for programmatic use. Submissions from the Endpoint go through the same server-side checks as Slack: required fields, offered options, conditions, and validation rules.

Using Forms in Workflows

Forms connect to workflows via the form-submission trigger type. See the workflows documentation for trigger details. Form data will not be saved in the Formal Control Plane unless there is at least one workflow with the corresponding form-submission trigger type.

Example: Access Request with Approval

Referencing Form Data in CEL

Form submission data is available under trigger.form_submission:

Terraform Example

For a dynamic options source (e.g., fetching resources from Formal):
See the formal_form resource documentation for the full schema reference.

Next Steps

Workflows

Learn about workflow triggers, actions, and chaining

Slack Integration

Configure your Slack integration for forms