Form Builder - Configuration Guide

The Form Builder in Entity Manager lets you create dynamic, multi-step forms for data collection. For permitting solutions, forms power permit applications, inspection checklists, review workflows, and citizen-facing submissions.

Form Builder Capabilities

Feature	Description
Multi-Step Forms	Create wizard-style forms with multiple steps
Form Sections	Organize fields into logical sections within steps
Drag & Drop	Reorder fields, sections, and steps
Field Configuration	Customize validation, appearance, and behavior
Conditional Logic	Show/hide fields based on conditions
Form Sharing	Generate public links for external submissions
Submission Actions	Trigger automations on form/step submission
Review Steps	Add review steps for users to verify entered data
AI Autofill	Configure AI-powered field population
Navigation Controls	Customize button labels for form navigation

Prerequisites

Before You Start

Entity has been created with all required fields
User has CREATE permission on the ENTITY resource
Required field types are defined on the entity
For payment fields: Payment provider is configured in system settings
For APO fields: GIS integration is configured

Section 1: Field Types Reference

Available Field Types

The platform supports 27+ field types organized by category.

Suggested Fields (Quick Access)

Field Type	Value	Description
Text	`text`	Single-line text for short names, titles, or codes
Text Area	`textarea`	Multi-line input for detailed notes or descriptions
Form Status	`formStatus`	Indicator of form submission state

Text & Content Fields

Field Type	Value	Description
Text	`text`	Single-line text for short names, titles, or codes
Text Area	`textarea`	Multi-line input for detailed notes or descriptions
Rich Text	`richtext`	Formatted content with basic styling (max 1000 chars)
JSON	`json`	Structured JSON input for advanced data

Contact Fields

Field Type	Value	Description
Email	`email`	Email input with structure validation
Phone	`phone`	Phone number input with validation
URL	`url`	Website link with URL validation

Numeric Fields

Field Type	Value	Description
Number	`number`	Numeric input supporting integers or decimals
Formula	`formula`	Auto-computed value from other fields
Payment	`payment`	Static payment information (amount, description)

Date & Time Fields

Field Type	Value	Description
Date	`date`	Calendar picker for a specific date
Date Range	`date_range`	Pick start and end dates together
Time	`time`	Select a precise time of day
Time Range	`time_range`	Pick start and end times in one place

Selection Fields

Field Type	Value	Description
Dropdown	`dropdown`	Choose one option from a preset list
Radio	`radio`	Select exactly one visible option
Checkbox	`checkbox`	Pick multiple options from a list
Boolean	`boolean`	Binary yes/no choice (toggle or checkbox)

File & Media Fields

Field Type	Value	Description
File	`file`	Upload documents or attachments
Image	`image`	Upload images (logos, photos)
Signature	`signature`	Record a digital signature

Relationship Fields

Field Type	Value	Description
Association	`association`	Link to another entity record
User	`user`	Assign or reference a system user

Location Fields

Field Type	Value	Description
Location	`location`	Capture address or coordinates
APO	`apo`	Composite field: Address, Parcel, Owner from GIS

Advanced Fields

Field Type	Value	Description
List	`list`	Ordered collection of items
Repeatable Group	`repeatable_group`	Group of fields that can be repeated
Combobox	`combobox`	Searchable dropdown with typing

Section 2: Field Configuration Options

2.1 Basic Field Settings

Every field has these configuration options:

Setting	Field Name	Description	Required
Field Type	`fieldType`	The type of field	Yes
Field Label	`fieldName`	Display name for the field	Yes
Description	`fieldDescription`	Help text for the field	No
Default Value	`defaultValue`	Pre-populated value	No
Required	`requiredInTasks`	Whether field is required	No
Hidden	`hideField`	Hide field from view	No

2.2 Selection Field Options (Dropdown, Radio, Checkbox)

Setting	Description
Options	List of label/value pairs (min 2 required)
Allow Multiple Select	Enable multi-select (Checkbox, Dropdown)
Show as Badge	Display options as colored badges
Color-code Options	Enable color coding for each option

Validation Rules

At least two options are required
Duplicate option labels are not allowed
Options can be reordered by dragging

2.3 Number Field Configuration

Navigation: Field Config → Advanced Configuration

Setting	Field Name	Description
Unit	`unit`	Unit symbol/prefix for the number
Unit Position	`unitPosition`	Left or Right of the number
Custom Unit Value	`unitCustomValue`	Custom unit text (when Custom selected)
Allow Manual Adjustment	`allowIncrementDecrement`	Show +/- buttons

Unit Options:

Unit	Value	Display
Dollar	`$`	$100
Euro	`€`	€100
Pound	`£`	£100
Percentage	`%`	100%
Custom	`custom`	User-defined

Unit Position Options:

Position	Value	Example
Left	`left`	$100
Right	`right`	100%

2.4 Date Field Configuration

Navigation: Field Config → Advanced Configuration

Setting	Field Name	Description
Date Format	`format_date`	How date is displayed
Show Time	`show_time`	Include time picker
Time Format	`format_time`	12-hour or 24-hour

Date Format Options:

Format	Value	Example
US	`us`	12/31/2025
EU	`eu`	31/12/2025
Local	`local`	System default
Friendly	`friendly`	December 31, 2025
ISO	`iso`	2025-12-31

Time Format Options:

Format	Value	Example
24-Hour	`24_hours`	14:30
12-Hour	`12_hours`	2:30 PM

2.5 Boolean Field Configuration

Navigation: Field Config → Advanced Configuration

Setting	Field Name	Options
Display As	`displayAs`	`switch` or `checkbox`

Display	Value	Description
Switch	`switch`	Toggle switch (default)
Checkbox	`checkbox`	Standard checkbox

2.6 File Field Configuration

Navigation: Field Config → Advanced Configuration → Enable File Restrictions

Setting	Field Name	Description
Allowed File Types	`allowedTypes`	Restrict to specific file types
Maximum File Size	`maxSizeValue`	Maximum size per file
Size Unit	`maxSizeUnit`	KB, MB, or GB
Maximum Files	`maxFiles`	Maximum number of files (leave empty for unlimited)

Allowed File Types:

Type	Value	Extension
PDF Documents	`application/pdf`	.pdf
Word Documents	`application/vnd...word`	.doc, .docx
Excel Spreadsheets	`application/vnd...sheet`	.xls, .xlsx
PowerPoint	`application/vnd...presentation`	.ppt, .pptx
Images	`image/jpeg,image/png,image/gif`	.jpg, .png, .gif
Text Files	`text/plain`	.txt
CSV Files	`text/csv`	.csv
ZIP Archives	`application/zip`	.zip
All Files	`*`	*

Size Units:

Unit	Value	Multiplier
Kilobytes	`KB`	1,024 bytes
Megabytes	`MB`	1,048,576 bytes
Gigabytes	`GB`	1,073,741,824 bytes

2.7 Association Field Configuration

Navigation: Field Config → Advanced Configuration

Setting	Field Name	Description
Entity ID	`entity_id`	Target entity to link to
Alias	`alias`	Display alias for the association
Fields	`fields`	Fields to display from linked record
Label Config	`label_config`	How to display linked records
Allow Multiple	`multi_select`	Allow linking to multiple records
Associated Form Field	`associatedFormField`	Form field to use for association
Layout Type	`layout_type`	How to display associated records
Visible Fields	`visible_fields`	Fields to show in the display

Layout Type Options:

Layout	Value	Description
Pills	`pills`	Compact badge-style display (single field)
Cards	`cards`	Card layout with multiple fields

Layout Types

Pills layout supports a single visible field. Cards layout supports multiple visible fields for richer displays.

2.8 User Field Configuration

Setting	Description
Allow Selecting Multiple	Enable multi-user selection
Specific Users	Filter to specific users
User Filter - Active	Show only active users

2.9 APO Field Configuration (Address, Parcel, Owner)

The APO field is a composite field that integrates with GIS to capture property information. It combines three data sections: Address, Parcel, and Owner.

Navigation: Field Config → Advanced Configuration

GIS Required

The APO field requires a configured GIS integration. Contact your system administrator if GIS is not available in your environment.

APO Required Components:

Setting	Field Name	Description
Require Address	`apo_required.address`	Make address selection mandatory
Require Parcel	`apo_required.parcel`	Make parcel selection mandatory
Require Owner	`apo_required.owner`	Make owner selection mandatory

Address Section Fields (8 fields):

Field	API Key	Display Label
Street Number	`street_number`	Street no
Street Name	`street_name`	Street Name
Street Type	`street_type`	Street type
Unit Type	`unit_type`	Unit type
Unit Number	`unit_number`	Unit no
City	`city`	City
State	`state`	State
ZIP Code	`zip_code`	Zip

Parcel Section Fields (7 fields):

Field	API Key	Display Label
Parcel Number	`parcel_number`	Property Id
Tax Map	`tax_map`	Tax map
ADC Map Coordinates	`adc_map_coordinates`	ADC map
Plan Area	`plan_area`	Plan Area
Tax ID	`tax_id`	state tax id
Stat Area	`stat_area`	stat Area
Lot	`lot`	Lot

Owner Section Fields (10 fields):

Field	API Key	Display Label
Full Name	`full_name`	Owner name
Mail Address	`mail_address_1`	Address
Mail City	`mail_city`	city
Mail State	`mail_state`	state
Mail ZIP	`mail_zip`	Zip
Phone	`phone`	Primary phone
Cell Number	`cell_number`	cell number
Fax Number	`fax_number`	fax number
Email	`email`	Email
Mail Country	`mail_country`	Country

2.10 Payment Field Configuration

Payment fields enable fee collection within forms. Configure how payment amounts are calculated.

Navigation: Field Config → Payment Configuration

Amount Type Options:

Type	Value	Description
Static	`static`	Fixed amount entered manually
Dynamic	`dynamic`	Amount pulled from another field
Calculation	`calculation`	Amount calculated from fee schedules

Payment Field Settings:

Setting	Field Name	Description
Payment Provider	`payment_provider_id`	Select configured payment gateway
Amount Type	`amount_type`	How the amount is determined
Static Amount	`amount`	Fixed fee amount (for static type)
Amount Field	`amount_field_id`	Field to pull amount from (for dynamic type)
Fee Schedules	`fee_schedules`	Fee definitions (for calculation type)
Currency	`currency`	Payment currency (default: USD)

Fee Schedule Configuration (Calculation Type):

Setting	Field Name	Description
Fee Definition	`fee_definition`	Select from configured fee definitions
Quantity	`quantity`	Number of units
Apply Tax	`apply_tax`	Enable tax calculation
Tax Formula	`tax_formula`	Formula for tax calculation
Apply Discount	`apply_discount`	Enable discount calculation
Discount Formula	`discount_formula`	Formula for discount calculation

Payment Add-Ons (Calculation Type):

Setting	Field Name	Description
Filing Fee Required	`filing_fee_required`	Add standard filing fee
Filing Fee	`filing_fee`	Filing fee amount
Technology Fee Required	`technology_fee_required`	Add technology fee
Technology Fee Percentage	`technology_fee_percentage`	Technology fee as % of total

2.11 Formula Field Configuration

Formula fields auto-calculate values based on other fields in the form.

Navigation: Field Config → Formula Configuration

Setting	Field Name	Description
Formula Code	`formulaCode`	The calculation expression

Formula Syntax

Reference fields using {"{fieldName}"} notation
Supports basic arithmetic: +, -, *, /
Supports comparison operators for conditions
Fields update dynamically when referenced values change

Example Formulas:

Purpose	Formula
Total Cost	`{"{labor_cost}"} + {"{material_cost}"}`
Tax Amount	`{"{subtotal}"} * 0.06`
Total with Tax	`{"{subtotal}"} + ({"{subtotal}"} * 0.06)`
Days Until Deadline	`{"{deadline_date}"} - {"{start_date}"}`

AI Formula Builder

Click Create with AI to describe the formula in natural language. AI will generate the appropriate formula code. Maximum instruction length: 3000 characters.

2.12 Validation Rules Configuration

Navigation: Field Config → Validation

Available Validation Rules:

Rule	Field Name	Applies To	Description
Required	`required`	All fields	Field must have a value
Minimum Length	`min_length`	Text, Textarea	Minimum character count
Maximum Length	`max_length`	Text, Textarea	Maximum character count
Pattern (Regex)	`pattern`	Text, Email, Phone	Regular expression validation
Pattern Example	`pattern_example`	Text, Email, Phone	Example of valid input
Minimum Value	`min_value`	Number	Minimum numeric value
Maximum Value	`max_value`	Number	Maximum numeric value

Built-in Regex Patterns:

Pattern	Value	Use Case
Email	`^[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}$`	Email validation
Phone	`^[0-9]{10,15}$`	Phone number (10-15 digits)

Validation Errors

Max Length must be greater than or equal to Min Length
Max Value must be greater than or equal to Min Value

Section 3: Multi-Step Form Configuration

3.1 Form Structure

Forms use a hierarchical structure:

Level	Component	Example
Form	Top-level container	Building Permit Application
Step	Wizard step	Step 1: Applicant Info
Section	Field grouping within step	Section A: Contact Details
Field	Individual input	Name, Email, Phone
Review Step	Summary step (optional)	Displays summary of all previous steps

3.2 Creating Steps

Navigation: Form Builder → Click + Add Step or + Add Review Step

Type	Button	Description
Regular Step	+ Add Step	Contains sections and fields for data entry
Review Step	+ Add Review Step	Displays summary of previously entered data

Review Steps

When users reach a review step, they can review the data they entered in previous steps before submitting. Steps can be reordered by dragging.

3.3 Step Configuration

Navigation: Click on step → Settings (gear icon)

Step General Settings:

Setting	Field Name	Description
Step Name	`title`	Display title for the step
Description	`description`	Help text shown under the title
Tooltip Text	`tooltipText`	Appears when hovering over the step

Step Submission Actions:

Configure actions that execute when a step is submitted. Use this to update field values, change statuses, or inject data into fields — including those not present in the current step.

Setting	Description
Add Action	Click to add a new submission action
Action Type	Select the action to perform
Target Field	Field to update
Value	Value to set

3.4 Creating Sections

Navigation: Form Builder → Step → Click + Add Section

Sections help organize related fields within a step. Sections can be expanded/collapsed and reordered within a step.

Section Settings:

Setting	Description
Section Title	Display name for the section
Collapsible	Allow section to expand/collapse
Default State	Expanded or collapsed by default

3.5 Adding Fields

Navigation: Form Builder → Section → Click + Add Field

Select a Field

Choose the field from the entity's available fields list.

Configure the Field

Set field-specific options including validation, default values, and visibility.

Position the Field

Drag to reorder within sections, between sections, or between steps.

3.6 Form Configuration Settings

Navigation: Form Builder → Click Configure Form (settings icon)

Form Details:

Setting	Field Name	Description
Form Name	`name`	Display name for the form
Description	`description`	Help text for the form

Navigation Controls:

Customize button labels throughout the form:

Setting	Field Name	Default	Description
Next Button	`next_button`	Save & Next	Label for proceeding to next step
Previous Button	`previous_button`	Previous	Label for going back
Reset Button	`cancel_button`	Reset	Label for clearing the form
Submit Button	`submit_button`	Submit	Label for final submission

Form Display Options:

Setting	Field Name	Description
Hide Section Header	`hideSectionHeader`	Hide section titles in form view
Show Field Description	`showDescription`	Display helper text for fields

Form Submission Actions:

Configure actions that execute when the entire form is submitted. Use this to update field values, change statuses, or inject data — including fields not present in the form.

Section 4: Conditional Logic

4.1 Field Visibility Conditions

Navigation: Field Config → Conditions → Visibility

Setting	Options	Description
Visibility	Always show, Based on condition	Control when field appears

4.2 Required Field Conditions

Option	Value	Description
Always	`always`	Field is always required
Based on Condition	`based_on_condition`	Required only when condition is met

Section 5: AI Autofill Configuration

5.1 Overview

AI Autofill automatically populates fields using AI analysis of other fields or attached documents.

Navigation: Field Config → Fill Method → Fill with AI

5.2 AI Autofill Settings

Setting	Field Name	Description
Fill Method	`fillMethod`	Manual Fill or Fill with AI
Field to Analyze	`watch_field_id`	Source field for AI analysis
AI Instruction	`instructions`	Instructions for the AI (max 3000 chars)
Field to Assign	`output_value`	Target field for the result

5.3 Knowledge Base Sources

Source Type	Description
File Upload	Upload documents for reference
Website	Add website URLs for context
SharePoint	Connect SharePoint documents
API	Connect external API endpoints

AI Instruction Best Practices

Be specific about what data to extract
Reference field names and expected formats
Maximum instruction length: 3000 characters
Test instructions with sample data before deploying

Section 6: Form Submission Actions

6.1 Step Submission Actions

Navigation: Step Settings → Submission Actions → Add Action

Action Type	Description
Update Field Value	Set a field's value when the step is submitted
Change Status	Update form/record status
Inject Data	Populate fields not in the current step

6.2 Form Submission Actions

Navigation: Form Settings → Submission Actions → Add Action

Action Type	Description
Update Field Value	Set any field's value on final submission
Change Status	Update final status
Trigger Automation	Run an automation workflow
Send Notification	Notify users or applicants

Section 7: Form Sharing

7.1 Generating Public Links

Navigation: Form Builder → Click Share Form

Sharing generates a public URL that anyone can use to submit the form — no account required.

Setting	Description
Public Link	Shareable URL for external access
Link Expiration	Optional expiration date
Submission Limits	Limit total number of submissions

Section 8: Permitting Solution Patterns

8.1 Permit Application Form Pattern

Step	Section	Fields
Step 1: Applicant Information	Contact Details	Name (Text, Required), Email (Email, Required), Phone (Phone, Required), Address (Location)
	Representative Info (Conditional)	Is Representative (Boolean), Representative Details (Text, show if Is Representative = true)
Step 2: Property Information	Property Details	APO Selection (APO, Required), Property Type (Dropdown), Property Description (Text Area)
Step 3: Permit Details	Permit Request	Permit Type (Dropdown, Required), Work Description (Text Area, Required), Estimated Cost (Number with $ unit)
	Documents	Plans (File, PDF only, Required), Supporting Documents (File, All types)
Step 4: Review & Signature	Review Summary	Read-only display of all entered data
	Agreement	Acknowledgment (Boolean, Required), Signature (Signature, Required)

8.2 Inspection Checklist Pattern

Step	Section	Fields
Step 1: Inspection Details	—	Permit Reference (Association), Inspection Type (Dropdown), Inspector (User), Date (Date)
Step 2: Checklist Items	Safety Items	Item Status (Radio: Pass/Fail/NA), Item Notes (Text Area)
	Code Compliance	Item Status (Radio: Pass/Fail/NA), Item Notes (Text Area)
Step 3: Results	—	Overall Result (Dropdown), Inspector Notes (Rich Text), Photos (Image), Signature (Signature)

8.3 Recommended Field Configurations for Permits

Field Purpose	Type	Configuration
Application Fee	Number	Unit: $, Position: Left
Work Start Date	Date	Format: US, Show Time: No
Permit Status	Dropdown	Show as Badge: Yes, Color-coded
Plans Upload	File	PDF only, Max 10MB, Max 5 files
Contractor License	Text	Required in specific permit types
Inspection Result	Radio	Pass/Fail/Corrections Required
Property Owner Signature	Signature	Required

Troubleshooting

Fields Not Appearing in Form Builder

Check Entity Fields

Ensure the fields are created on the entity first. Fields must exist on the entity before they can be added to a form.

Verify Permissions

Confirm you have CREATE permission on the ENTITY resource.

Refresh the Page

Reload the form builder — newly created fields may require a refresh to appear.

Conditional Logic Not Working

Common Causes

The condition field must be included in the form (even if hidden)
Condition values must match exactly (case-sensitive)
Check whether another rule is overriding the condition

File Upload Failures

Verify:

File size is within configured limits
File type is in the allowed list
Maximum file count has not been exceeded

Submission Actions Not Executing

Verify:

Action configuration is complete (no empty required fields)
Target fields exist on the entity
Review automation logs for related errors

Code Reference

Source Files

Field Type Configuration:

File	Location	Purpose
Field Types	`govt-assist-shared/src/const/fieldTypeConstants.ts`	All field type definitions and descriptions
Field Icons	`govt-assist-shared/src/const/fieldTypes.ts`	Field type icons

Entity & Field Configuration:

File	Location	Purpose
Field Config	`entity-manager-app/src/pages/Entity/.../consts.ts`	Field configuration options
Advanced Config	`entity-manager-app/src/pages/Entity/.../AdvanceConfiguration/consts.ts`	Number, Date, Boolean, Unit options
File Config	`entity-manager-app/.../FileFieldConfiguration/consts.ts`	File type options, size multipliers

Form Builder Configuration:

File	Location	Purpose
Form Constants	`entity-manager-app/src/pages/Form/ConfigureForm/const.ts`	Form builder options
Form Configuration	`entity-manager-app/.../FormConfiguration/const.ts`	Navigation controls, form details
Step Configuration	`entity-manager-app/.../StepConfiguration/const.ts`	Step settings, submission actions
Field Configuration	`entity-manager-app/.../FieldConfiguration/const.ts`	Validation rules, layout types

Next Steps

Fee Definitions

Configure fee schedules and payment rules for permit forms.

Automation Builder

Trigger actions automatically based on form submissions.

Entity Builder

Create and manage the entities that power your forms.

Role-Based Access Control

Control who can view and submit forms.

This guide is aligned with the entity-manager-app codebase as of January 2026.