Entity Builder

The Entity Builder is the foundational tool for creating data structures in GovAssist. Entities are custom data containers — think of them as your own database tables. Everything else in the platform (forms, automations, views) is built on top of entities you define here.

What You Can Build

Feature	Description
Entities	Custom data containers (e.g., "Building Permits", "Inspections")
28+ Field Types	Text, numbers, dates, files, associations, and more
Sections	Logical groupings of related fields
Folder Hierarchy	Nested folders to organize entity libraries
Associations	Relationships between entities
Formula Fields	Auto-computed values from other fields

Before You Start

To use Entity Builder, you need:

CREATE and UPDATE permissions on the ENTITY resource
Access to the Entity Manager module
A clear understanding of the data your solution requires

Section 1: Entity Fundamentals

What is an Entity?

An entity is a data container representing a real-world object or concept in your organization.

Entity	Purpose	Example Fields
Building Permit	Track permit applications	permit_number, property_address, status
Inspection	Record inspection results	inspection_date, inspector, result
Contractor	Store contractor records	company_name, license_number, contact
Fee Schedule	Define fee structures	fee_type, amount, effective_date

Entity Structure

Component	Description
Settings	Name, label, description, icon
Sections	Logical groupings of fields
Fields	Individual data inputs within sections
Forms	Data entry interfaces built on entity fields
Views	Grid, Kanban, or Dashboard display configurations

Creating an Entity

Open Entity Manager

Navigate to Entity Manager from the sidebar.

Create a New Entity

Click + New Entity, or right-click a folder and select New Entity.

Fill in Entity Details

Enter the entity settings:

Setting	Description	Required
Name	Internal identifier (used in APIs/code)	Yes
Label	Display name shown in the UI	No (defaults to name)
Description	Purpose documentation	No
Folder	Parent folder for organization	No

Save

Click Create to save the entity and begin adding fields.

Section 2: Field Types Reference

Entity Builder supports 28 field types grouped into categories.

Text & Content Fields

Field Type	Key	Use Case
Text	`text`	Names, titles, IDs
Textarea	`textarea`	Descriptions, notes
Rich Text	`richtext`	Formatted documentation
Email	`email`	Contact emails
URL	`url`	External links
Phone	`phone`	Contact numbers

Numeric Fields

Field Type	Key	Use Case
Number	`number`	Quantities, amounts
Formula	`formula`	Auto-calculated values
Payment	`payment`	Fee collection

Number field units:

Unit	Symbol	Position
Dollar	`$`	Left or Right
Euro	`€`	Left or Right
Pound	`£`	Left or Right
Percentage	`%`	Left or Right
Custom	user-defined	Left or Right

Enable allowIncrementDecrement on number fields to show +/- buttons for quick adjustments — useful for quantity fields on applications.

Date & Time Fields

Field Type	Key	Use Case
Date	`date`	Due dates, birthdays
Date Range	`date_range`	Project periods
Time	`time`	Appointment slots
Time Range	`time_range`	Business hours

Date format options:

Format	Example
`us`	01/15/2026
`eu`	15/01/2026
`iso`	2026-01-15
`friendly`	January 15, 2026

Selection Fields

Field Type	Key	Use Case
Dropdown	`dropdown`	Status, category
Combobox	`combobox`	Large searchable option lists
Radio	`radio`	Yes/No/Maybe
Checkbox	`checkbox`	Tags, multi-select features
Boolean	`boolean`	On/Off toggles, flags

Selection fields require at least 2 options to save. Enable color_code_options to assign a badge color to each option — highly recommended for status fields.

File & Media Fields

Field Type	Key	Use Case
File	`file`	Document/attachment uploads
Image	`image`	Photos, logos
Signature	`signature`	Digital signature capture

File restriction settings:

Setting	Description	Example
`allowedTypes`	Permitted file extensions	PDF, DOCX, XLSX
`maxSizeValue`	Maximum file size	10
`maxSizeUnit`	Size unit	KB, MB, GB
`maxFiles`	Max number of files	5 (empty = unlimited)

Relationship Fields

Field Type	Key	Use Case
Association	`association`	Cross-entity relationships (Permit → Contractor)
User	`user`	User assignment (Assigned Inspector)

Association configuration:

Setting	Description
`reference.entity_id`	ID of the target entity
`reference.alias`	Display alias
`reference.fields`	Lookup fields to display
`associatedFormField`	Fields shown in the lookup popup

Association lookup fields only support: text, number, email, textarea, formula. The association, file, and image field types cannot be used as lookup fields.

Special Fields

Field Type	Key	Use Case
Location	`location`	Address or coordinates
APO	`apo`	Address, Parcel, Owner (GIS lookup)
JSON	`json`	Structured JSON data
Output Field	`output_field`	Read-only computed display
Repeatable Group	`repeatable_group`	Multiple entries of the same fields (e.g., multiple contacts)

Section 3: Field Configuration

General Settings

Every field supports these base settings:

Setting	Description	Required
Label	Display name	Yes
Name	Internal key (auto-generated from label)	Auto
Description	Help text shown below the field	No
Placeholder	Input placeholder text	No
Default Value	Pre-filled value	No

Validation Rules

Validation	Applies To	Description
`required`	All fields	Field must have a value
`unique`	Text, email, number	Value must be unique across records
`min_length`	Text, textarea	Minimum character count
`max_length`	Text, textarea	Maximum character count
`min_value`	Number	Minimum numeric value
`max_value`	Number	Maximum numeric value
`pattern`	Text, email	Regex pattern validation
`index`	Any	Create a database index for faster queries

Protected & Private Fields

Flag	Description
`is_protected`	System field — cannot be deleted
`is_private`	Hidden from certain users or views

Section 4: Sections

Sections group related fields within an entity, providing logical organization and improving UX when viewing or editing records.

Section Settings

Setting	Validation
Title	Max 50 characters; letters, numbers, spaces, apostrophes, parentheses, brackets, ampersand
Order	Integer 1–1000

Every entity includes a default section (ID: default-section). New fields are added here unless you specify otherwise.

Managing Sections

Add a Section

Click + Add Section or drag the Section component into the entity canvas.

Name It

Enter a section title (e.g., "Property Information", "Applicant Details").

Add Fields

Drag fields into the section from the field palette.

Reorder

Use drag-and-drop to reorder sections, fields, or rows within a section.

Section 5: Folder Organization

Creating Folders

Open Context Menu

Right-click in the entity list panel.

New Folder

Select New Folder and enter a name.

Nest (Optional)

Select a parent folder to create a nested structure.

Moving Entities

Drag and drop entities into folders, or right-click an entity and select Move to Folder.

Example folder hierarchy:

Level 1	Level 2	Entities
Permitting
	Applications	Building Permits, Fire Permits, Zoning Permits
	Inspections	Building Inspections, Fire Inspections
Licensing
		Business Licenses, Contractor Licenses
System
		Permit Menu, Fee Schedule

Section 6: Formula Fields

Formula fields auto-compute values based on other fields in the entity.

formula: [
  { is_field: true, field: 'quantity' },
  { is_field: false, field: '*' },        // Operator
  { is_field: true, field: 'unit_price' }
]

Supported operators:

Operator	Description
`+`	Addition
`-`	Subtraction
`*`	Multiplication
`/`	Division

Formulas can reference fields in the same entity or fields from associated entities via reference_field. Place formula fields after their source fields for clarity.

Section 7: Permitting Solution Patterns

Recommended Core Entities

Entity	Purpose	Key Fields
Permit Menu	Portal visibility control	application_type, entity_id, form_id, process_id
Building Permit	Building permit records	permit_number, property_address, status, applicant
Fire Permit	Fire permit records	permit_number, occupancy_type, status
Inspection Codes	Inspection type definitions	code, description, category
Permit-Inspection Mapping	Links permits to inspection types	permit_entity_id, inspection_code_id, calendar_id
Contractors	Licensed contractors	license_number, company_name, expiration_date

Common Field Patterns

Status field (dropdown):

Setting	Value
Type	`dropdown`
Options	Submitted, Under Review, Approved, Denied, Expired
Color-coded	Yes
Show as badge	Yes

Permit number (text):

Setting	Value
Type	`text`
Required	Yes
Unique	Yes
Pattern	`^[A-Z]{2}-\d{4}-\d{6}$`
Placeholder	e.g., BP-2026-000001

Property address (APO):

Setting	Value
Type	`apo`
Description	Start typing to search by address, parcel, or owner

Application date (date):

Setting	Value
Type	`date`
Default	Current date
Format	`us`
Show time	No

Entity Relationship Pattern

Entity	Role	Association Field	Links To	Lookup Fields
Building Permit	Parent	`inspections`	Building Inspection	inspection_date, result, inspector
Building Inspection	Child	`permit`	Building Permit	permit_number, property_address

Section 8: Best Practices

Naming Conventions

Element	Convention	Example
Entity name	snake_case	`building_permit`
Entity label	Title Case	Building Permit
Field name	snake_case	`permit_number`
Field label	Title Case	Permit Number
Section title	Title Case	Property Information

Field Organization

Recommended Field Order

Identification first — permit number, record ID at the top
Group by category — use sections for logical grouping
Required fields prominent — put required fields early in each section
Calculated fields last — place formula fields after their source fields

Performance Tips

Recommendation	Reason
Index frequently searched fields	Improves query speed
Limit file upload sizes	Reduces storage costs
Use dropdowns over free text for constrained values	Better data quality
Add descriptions to complex fields	Improves user understanding

Section 9: Troubleshooting

Issue	Cause	Solution
Cannot delete field	Field is protected	Check if it's a system field (`is_protected`)
Duplicate key error	Field name already exists	Rename the field
Options not saving	Fewer than 2 options	Add at least 2 options
Formula not calculating	Reference field missing or renamed	Verify field names match exactly
File upload fails	Size exceeds limit	Check `maxSizeValue` and `maxSizeUnit` settings

Validation errors:

Error	Fix
"Section title too long"	Max 50 characters
"Invalid characters"	Use only allowed characters (letters, numbers, spaces, punctuation listed above)
"Duplicate option label"	Make each option label unique
"Entity ID required"	Select the target entity for the association

Form Builder

Build data entry forms on top of your entities — configure fields, layout, and validation for citizen and staff-facing forms.

Automation Builder

Create no-code workflows triggered by entity record changes, form submissions, and scheduled events.

RBAC Configuration

Control who can read, create, update, and delete records in each entity using role-based access control.

Views

Configure Grid, Kanban, and Dashboard views to display entity records in the way your team works.

Aligned with entity-manager-app codebase as of January 2026.