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 inputnumber— Numeric inputemail— Email address inputurl— URL input
date— Date pickertime— Time pickertimestamp— Combined date and time picker
select— Single-select dropdownmulti_select— Multi-select dropdowncheckbox— Checkbox groupradio— Radio button group
Field IDs
Each field has anid 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. Setoptional 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 totrue 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 avisible_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.
Example
An access request where the duration and ticket depend on the environment, and sensitive data needs a justification:Selection Field Options
Theselect, 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 alabel (displayed to the user) and a value (submitted with the form).
Dynamic Options
Dynamic sources populate a selection field by calling aList 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
selectorradiofield 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
- User opens the form shortcut in Slack
- User selects a form from the searchable dropdown
- User fills out the fields. Picking a choice updates the form, showing or hiding fields and options that depend on it
- User submits. Answers that fail a validation rule, or options no longer offered, are flagged under their field and the form stays open
- A confirmation message with the submitted values is sent to the user
- Any workflows with a matching
form-submissiontrigger are executed
Formal Endpoint
Forms can also be filled out via the Formal Endpoint.Submission Flow
- User opens the Formal Endpoint
- User runs
formal form filland selects a form from the shown list - User fills out the fields and submits
- 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
- Any workflows with a matching
form-submissiontrigger are executed
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 theform-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 undertrigger.form_submission:
Terraform Example
Next Steps
Workflows
Learn about workflow triggers, actions, and chaining
Slack Integration
Configure your Slack integration for forms