Entity Builder - Configuration Guide

---

Overview

Entity Builder is the foundational module for creating data structures in the GovAssist platform. Entities are the containers that hold your data—think of them as custom database tables. Before you can build forms, create automations, or configure views, you must first define your entities and their fields.

Entity Builder Capabilities

---

Prerequisites

Before configuring entities, ensure:

• User has CREATE and UPDATE permissions on ENTITY resource
• User has access to Entity Manager module
• Understanding of data requirements for your solution

---

Section 1: Entity Fundamentals

1.1 What is an Entity?

An Entity is a data container that represents a real-world object or concept in your organization. Examples:

1.2 Entity Structure

1.3 Creating an Entity

1. Navigate to Entity Manager from the sidebar
2. Click + New Entity or right-click a folder → New Entity
3. Enter entity details:

1. Click Create to save the entity

---

Section 2: Field Types Reference

The Entity Builder supports 28 field types organized into categories.

2.1 Text & Content Fields

2.2 Numeric Fields

Number Field Configuration

Numbers support unit configuration:

Additional Options:

• allowIncrementDecrement: Show +/- buttons for easy adjustment

2.3 Date & Time Fields

Date Field Configuration

Date Format Examples:

2.4 Selection Fields

Selection Field Options

Options require at least 2 entries:

Display Settings:

Boolean Field Configuration

2.5 File & Media Fields

File Field Restrictions

Common File Type Presets:

2.6 Relationship Fields

Association Field Configuration

Allowed Lookup Field Types:

• text, number, email, textarea, formula

Excluded from Lookup:

• association, file, image

User Field Configuration

2.7 Special Fields

---

Section 3: Field Configuration

3.1 General Field Settings

Every field supports these base settings:

3.2 Validation Rules

3.3 Protected and Private Fields

---

Section 4: Section Configuration

4.1 What are Sections?

Sections group related fields within an entity. They provide logical organization and improve the user experience when viewing or editing records.

4.2 Section Settings

Allowed Characters in Title:

• Letters (a-z, A-Z)
• Numbers (0-9)
• Spaces (no consecutive)
• Apostrophes, parentheses, brackets, braces, ampersand

4.3 Default Section

Every entity has a default section with ID: default-section

New fields are added to this section unless otherwise specified.

4.4 Creating Sections

1. Open the entity in Entity Builder
2. Click + Add Section or drag the Section component
3. Enter section title
4. Drag fields into the section

4.5 Reordering Sections and Fields

Use drag-and-drop to reorder:

---

Section 5: Folder Organization

5.1 Creating Folders

1. In Entity Manager, right-click the entity list
2. Select New Folder
3. Enter folder name
4. Optionally select a parent folder for nesting

5.2 Moving Entities to Folders

1. Drag and drop entities into folders
2. Or right-click entity → Move to Folder

5.3 Folder Hierarchy

Folders support unlimited nesting levels. Example structure:

---

Section 6: Color Configuration

6.1 Available Colors

The system provides 16 preset colors for badges, statuses, and visual indicators:

6.2 Applying Colors to Options

For dropdown, radio, and checkbox fields with color_code_options enabled:

1. Edit the field
2. Enable Color-code options
3. Click the color swatch next to each option
4. Select a color from the palette

---

Section 7: Formula Fields

7.1 Formula Basics

Formula fields automatically compute values based on other fields.

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

7.2 Supported Operations

7.3 Formula Field References

Formulas can reference:

• Fields in the same entity
• Fields from associated entities (via reference_field)

---

Section 8: Permitting Solution Patterns

8.1 Recommended Entity Structure

For a Permitting solution, create these core entities:

8.2 Common Field Patterns

Status Field (Dropdown)

Permit Number (Text)

Property Address (APO)

Application Date (Date)

8.3 Entity Relationship Pattern

---

Section 9: Best Practices

9.1 Naming Conventions

9.2 Field Organization

1. Start with identification - Permit number, record ID at the top
2. Group by category - Use sections for logical grouping
3. Required fields first - Place required fields prominently
4. Calculated fields last - Formula fields after their source fields

9.3 Performance Considerations

---

Section 10: Troubleshooting

10.1 Common Issues

10.2 Validation Errors

---

Appendix: Code Reference

Source Files

Query Keys

INVALIDATE_QUERY_KEYS = {
  ENTITY_SECTIONS: 'entity-sections',
  FIELDS: 'fields',
  ENTITY_RECORD: 'entityRecord',
  RECORDS: 'records',
  ENTITY_FIELDS: 'entity-fields',
  GET_ENTITY_LIST: 'get-entity-list',
}

---

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