Entity Associations - Configuration Guide

---

Overview

Entity Associations in the GovAssist platform enable relationships between different entities, allowing records to reference and link to records in other entities. This is fundamental for permit systems where permits need to link to inspections, review tasks, applicants, and other related records.

Association Capabilities

---

Prerequisites

Before configuring associations, ensure:

• Both source and target entities exist
• User has CREATE and UPDATE permissions on ENTITY resource
• Target entity has fields suitable for display (text, number, email, etc.)
• Understanding of which entity is the "parent" vs "child" in the relationship

---

Section 1: Association Concepts

1.1 Association Types

1.2 Association Field Type

The association field type creates the link between entities.

1.3 Association vs Lookup

---

Section 2: Creating Association Fields

2.1 Adding an Association Field to an Entity

Navigation: Entity Manager → Select Entity → Configure Entity → Add Field → Association

Basic Configuration

2.2 Association Reference Configuration

Navigation: Field Config → Advanced Configuration

2.3 Lookup Fields Configuration

Select which fields from the target entity should be accessible in the source entity.

Navigation: Field Config → Advanced Configuration → Lookup Fields

Labels:

Allowed Field Types for Lookup:

Filter Configuration:

2.4 Display Label Configuration

Configure which field displays as the association's label in forms and views.

Navigation: Field Config → Advanced Configuration → Choose field to show in form

The selected field's value will be used as the display text when showing the association in forms and views.

---

Section 3: Association Display Configuration

3.1 Layout Types

Association fields support two display layouts in forms:

Configuration Location: Form Builder → Field Configuration → Layout Type

3.2 Pills Layout

The pills layout displays associated records as compact inline badges.

Visual Example: John Smith | Jane Doe | Bob Johnson

3.3 Cards Layout

The cards layout displays associated records as expanded cards with multiple fields.

Card Layout Structure:

3.4 Visible Fields Configuration

Control which fields from the associated record are displayed.

Navigation: Form Builder → Field Configuration → Fields (Visible Fields)

Selection Behavior:

UI Labels:

3.5 Layout Type Selection

---

Section 4: Association Filters and Visibility

4.1 Conditional Visibility

Association fields can be shown or hidden based on conditions.

Navigation: Form Builder → Field Configuration → Conditions → Visibility

4.2 Visibility Options

4.3 Association Filters Structure

Association filters use the advanced filter structure:

{
  operator: 'and' | 'or',
  conditions: [
    {
      field: string,      // Field to evaluate
      operator: string,   // Comparison operator
      value: any          // Value to compare against
    }
  ]
}

4.4 Filter Operators

For String Fields:

For Number Fields:

---

Section 5: Associations in Views

5.1 Grid View Display

In grid views, association fields display as:

• Single Association: Shows the label config field value
• Multi Association: Shows comma-separated values or badge count

5.2 Kanban View Display

In Kanban cards, associations can be configured via the Customize panel:

• Add association field to card display
• Shows as pills or configured display

5.3 Form View Integration

In forms, associations provide:

• Dropdown/multi-select for record selection
• Search functionality for finding records
• Create new record inline (if configured)
• Display of associated record details

5.4 Record Detail View

When viewing a record, associations show:

• List of associated records
• Quick navigation to associated record detail
• Count of associated records

---

Section 6: Permitting Association Patterns

6.1 Permit → Review Tasks Pattern

Use Case: Link a permit to its review tasks for workflow tracking.

On the Permit Side:

• Field: review_tasks (association, multi-select)
• Display: Shows all review tasks with status

On the Review Task Side:

• Field: parent_permit (association, single-select)
• Display: Shows permit number/type

6.2 Permit → Inspections Pattern

Use Case: Link permits to scheduled inspections.

6.3 Permit → Applicant Pattern

Use Case: Link permits to applicant/contractor records.

6.4 Parent-Child Permit Pattern

Use Case: Link trade permits to their parent building permit.

6.5 License Renewal Pattern

Use Case: Link renewed licenses to their previous version.

---

Section 7: Associations with Automations

7.1 Create Associated Records

Use automations to create linked records automatically.

Trigger: When permit is submitted Action: Create Review Task record with parent association set

7.2 Update Associated Records

Update multiple associated records based on parent changes.

Trigger: When permit status changes to "Approved" Action: Update all associated review tasks to "Completed"

7.3 Rollup/Summary from Associated Records

Use formula fields to aggregate data from associations:

• Count of associated records
• Sum of values from child records
• Latest date from associated records

---

Section 8: Best Practices

8.1 Association Design Principles

1. Clear Direction: Decide which entity is the "parent" (one) vs "child" (many)
2. Naming Convention: Use descriptive names like parent_permit, review_tasks
3. Minimal Lookups: Only pull fields you actually need to display
4. Appropriate Layout: Use Pills for simple references, Cards for detailed info

8.2 Performance Considerations

8.3 Common Pitfalls

---

Troubleshooting

Common Issues

Association Field Not Showing Records

Check:

1. Target entity has records
2. User has VIEW permission on target entity
3. No visibility conditions are hiding the field
4. Label config field has values in target records

Lookup Fields Not Displaying

Check:

1. Lookup fields are configured on the association
2. Field types are allowed (text, number, email, textarea, formula)
3. Target record has values in those fields

Cannot Create Association

Check:

1. User has CREATE permission on ENTITY resource
2. Target entity exists and is accessible
3. Entity configuration is saved

Pills Showing Wrong Field

Check:

1. Review visible_fields configuration
2. Pills mode only shows first visible field
3. Verify label_config is set correctly

---

Code Reference

Source Files

Association Field Configuration

Association Display

Layout Configuration

Condition Configuration

API Constants

// Layout Type Options
LAYOUT_TYPE_OPTIONS = [
  { value: 'pills', label: 'Pills' },
  { value: 'cards', label: 'Cards' },
];

// Association Field Filters (for lookup fields)
ASSOCIATED_FIELD_FILTERS = {
  EXCLUDED_TYPES: ['association', 'file', 'image'],
  ALLOWED_TYPES: ['text', 'number', 'email', 'textarea', 'formula'],
};

// Field Type
FIELD_TYPES.ASSOCIATION = 'association';

---

Related Documentation

• Form Builder Guide - Association field in forms
• View Configuration - Association display in views
• Role-Based Access Control - Entity permissions
• Automation Builder - Automating association creation

---

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