Configuration Guide: End-to-End Permit Workflow

---

Overview

This comprehensive guide walks you through setting up a complete permit workflow - from creating permit entities to enabling citizen form submissions with AI-powered evaluation, and configuring the inspection scheduling system.

What You'll Configure

1. Part 1: Permit Application Setup - Entity creation, form design, Permit Menu configuration, and AI-powered evaluation
2. Part 2: Inspection Scheduling Setup - Calendar configuration, inspector assignment, and permit-inspection mapping
3. Part 3: Citizen Experience - How citizens interact with the completed system

Entity Dependency Map

Understanding how entities relate to each other is critical for successful configuration:

                    +-------------------------------------------------------------+
                    |                     PERMIT MENU ENTITY                       |
                    |  (Central registry that controls portal visibility)          |
                    |                                                              |
                    |  Fields:                                                     |
                    |  - application_type (filters permits by type)                |
                    |  - entity_id (references permit entity)                      |
                    |  - form_id (links to submission form)                        |
                    |  - process_id (links to AI evaluation process)               |
                    +-----------------------------+--------------------------------+
                                                  |
                         +------------------------+------------------------+
                         |                        |                        |
                         v                        v                        v
              +------------------+     +------------------+     +------------------+
              |  PERMIT ENTITY   |     |   PERMIT FORM    |     |     PROCESS      |
              |  (Data storage)  |     |  (Citizen input) |     | (AI Evaluation)  |
              |                  |     |                  |     |                  |
              | - permit_number  |     | - Form fields    |     | - Template       |
              | - property_addr  |     | - Sections       |     | - Entity config  |
              | - owner_name     |     | - Steppers       |     | - Intake trigger |
              | - status         |     | - Validation     |     | - Status rules   |
              +--------+---------+     +------------------+     +------------------+
                       |
                       | Inspections reference permit records
                       v
        +----------------------------------------------------------------------+
        |                  PERMIT-INSPECTION MAPPING                            |
        |  (Links permit types to inspection calendars and codes)               |
        |                                                                       |
        |  Fields:                                                              |
        |  - permit_entity_id (which permit entity)                             |
        |  - inspection_code_id (which inspection type)                         |
        |  - calendar_id (which calendar for scheduling)                        |
        +-------------------------------+--------------------------------------+
                                        |
                    +-------------------+-------------------+
                    v                   v                   v
         +------------------+  +------------------+  +------------------+
         | INSPECTION CODES |  |     CALENDAR     |  |     TAX MAPS     |
         | (Inspection types)|  | (Scheduling)     |  | (Geographic zones)|
         |                  |  |                  |  |                  |
         | - name           |  | - calendar_type  |  | - zone_name      |
         | - category       |  | - assigned_users |  | - boundaries     |
         | - duration       |  | - availability   |  | - inspector_ids  |
         +------------------+  | - tax_map_links  |  +------------------+
                               | - forms          |
                               +------------------+

---

Prerequisites

Before starting, ensure you have:

• Admin access to Entity Manager
• Admin access to Process Library (Document Processing App)
• Admin access to Calendar Settings
• Understanding of your permit types and inspection requirements
• Tax Map / Geographic zone data (if using zone-based inspector assignment)

---

Part 1: Permit Application Setup

Overview

This section covers the initial setup required to allow citizens to submit permit applications through the portal, with automatic AI-powered evaluation.

---

Step 1: Create a Permit Entity

The Permit Entity stores all application data for a specific permit type.

1.1 Navigate to Entity Manager

1. Open Entity Manager
2. Click Create New Entity

1.2 Configure Entity Basic Information

1.3 Add Entity Fields

Add fields that capture all necessary permit information:

Common Permit Fields:

GovAssist Status Field Options:

Configure dropdown options that align with your workflow:

1.4 Save Entity

1. Review all fields
2. Click Save to create the entity
3. Note the Entity ID for later use

---

Step 2: Create the Permit Form

Design a citizen-facing form that captures permit application data.

2.1 Navigate to Form Builder

1. Open Entity Manager
2. Select your permit entity (e.g., "Building Permits")
3. Go to Forms tab
4. Click Create New Form

2.2 Configure Form Settings

2.3 Design Form Layout

Best Practice: Keep the form focused - include only fields relevant to this permit type to improve user experience and data quality.

Recommended Form Structure:

Section 1: Property Information
+-- Property Address (required)
+-- Parcel ID / Tax Map
+-- Zoning District

Section 2: Owner Information
+-- Owner Name (required)
+-- Owner Email (required)
+-- Owner Phone
+-- Mailing Address

Section 3: Project Details
+-- Project Description (required)
+-- Estimated Cost
+-- Square Footage
+-- Number of Stories

Section 4: Documents
+-- Site Plan Upload
+-- Construction Plans Upload
+-- Contractor License Upload

Section 5: Acknowledgments
+-- Terms and Conditions Checkbox

2.4 Configure Multi-Step Forms (Optional)

For complex applications, break the form into steps:

1. Click Add Stepper in Form Builder
2. Divide sections across multiple steps
3. Configure step labels and descriptions
4. Set validation per step

2.5 Save and Publish Form

1. Click Save to save form configuration
2. Click Publish to make the form available
3. Note the Form ID for the next steps

---

Step 3: Add a Record in the Permit Menu

The Permit Menu Entity is a special system entity that controls which permits are visible on the Citizen Portal. Without a record in this entity, citizens cannot see or access your permit type.

3.1 Understanding the Permit Menu Entity

Why It Matters: The Permit Menu acts as a registry/index of all permit types available to citizens. It:

• Filters which permits appear based on application_type (Building, Fire, Licenses, etc.)
• Links the Citizen Portal to actual permit entities
• Controls which forms are displayed when citizens apply

3.2 Navigate to Permit Menu

1. Open Entity Manager
2. Select the Permit Menu entity (system entity)
3. Click View Records
4. Click Add New Record

3.3 Configure Permit Menu Record

3.4 Save Permit Menu Record

1. Review configuration
2. Click Save
3. The permit type is now visible on the Citizen Portal

---

Step 4: Create a New Process (AI Evaluation)

Processes define how applications are evaluated using AI-powered rules.

4.1 Navigate to Process Library

1. Open Document Processing App (or Process Library)
2. Click Create New Process

4.2 Step 4.1: Basic Info

Process Type Options:

• Application - For permit/license applications
• Contract - For contract documents
• Form - For general form processing
• Other - For other document types

Click Next to continue.

4.3 Step 4.2: Template

Select the existing form you created earlier:

1. Choose "Use Existing Form" option
2. Select: Residential Additional Duplex Permit Application

This links the process to evaluate submissions from your permit form.

Click Next to continue.

4.4 Step 4.3: Entity (AI Evaluation Rules)

This step configures the AI-powered evaluation logic.

Configure GovAssist Status Field

1. Locate the GovAssist Status field in the entity field list
2. Click the "..." menu next to the field
3. Select "Autofill with AI"
4. In the popup, define your evaluation instructions

Example AI Evaluation Instructions

Evaluate the permit application and set the status based on these rules:

INCOMPLETE Status:
- If property_address is not provided
- If owner_name is empty
- If project_description is blank

DENIED Status:
- If owner_name contains "test" or "sample"
- If estimated_cost is negative
- If license_number does not exist in the valid licenses knowledge base

MANUAL REVIEW Status:
- If owner_name is "XXX" or contains placeholder text
- If estimated_cost exceeds $500,000
- If project_description mentions "demolition"

CID REVIEW REQUIRED Status:
- If estimated_cost > $100,000
- If project involves commercial property

APPROVED Status:
- All required fields are complete
- No issues detected
- Owner information appears valid

Using Knowledge Base for Validation

You can reference a Knowledge Base (KB) for advanced checks:

- If contractor_license does not exist in the "Valid Contractor Licenses" KB -> Status = "Denied"
- If property_address is in the "Historic District Properties" KB -> Status = "Manual Review"

Best Practice: Use clear, consistent logic statements. The AI will apply these rules automatically upon form submission.

Click Next to continue.

4.5 Step 4.4: Form Configuration

Configure what happens when the form is submitted.

For Single-Step Forms:

1. Go to Form Settings
2. Locate Form Submission Actions

For Multi-Step Forms:

1. Go to First Stepper Config (must always be first stepper)
2. Locate Stepper Submission Action

Configure Submission Action

Why This Linkage is Important: This configuration ensures that when a citizen submits a permit application, the system knows exactly which permit type they applied for - enabling proper routing, evaluation, and display in their portal.

Click Next to continue.

4.6 Step 4.5: Intake Configuration

Choose when the AI evaluation should be triggered.

Intake Trigger Options:

For permit applications: Select Form Submission

This ensures that initial validation checks run automatically when a citizen submits their permit application.

4.7 Save the Process

1. Review all configurations
2. Click Publish to activate the process
3. Note the Process ID

---

Step 5: Link the Process to the Permit Menu

Return to the Permit Menu entity and update the record you created in Step 3.

5.1 Update Permit Menu Record

1. Open Entity Manager -> Permit Menu -> View Records
2. Find and edit your permit menu record
3. Update the following field:

1. Click Save

---

Part 1 Complete!

Citizens can now:

1. Access the Citizen Portal
2. Navigate to the appropriate permit category (e.g., Building)
3. Select the permit type (e.g., Residential Additional Duplex Permit)
4. Fill out and submit the application form
5. Receive automated AI evaluation based on your defined rules

---

Part 2: Inspection Scheduling Setup

Overview

This section covers how to configure the calendar system for scheduling inspections, including inspector assignment based on geographic zones (Tax Maps), availability settings, and linking inspections to permits.

---

Step 1: Configure Tax Maps (Prerequisites)

Tax Maps define geographic zones used for inspector assignment. Configure these before creating calendars.

1.1 Access Tax Maps

1. Navigate to Calendar (bottom-left sidebar)
2. Click Calendar Settings
3. Select Tax Maps tab

1.2 Add Tax Map Zones

For each geographic zone, add a tax map record:

Example Tax Map Zones :

• Ellicott City (Western)
• Columbia East
• West Columbia
• Clarksville
• Savage

1.3 Save Tax Maps

Each tax map will be available for inspector assignment in calendar configuration.

---

Step 2: Access Calendar Settings and Create New Calendar

2.1 Navigate to Calendar Settings

1. Locate the Calendar feature in the bottom-left corner (alongside Entities and Automations)
2. Click to open Calendar Settings
3. Select Calendars tab
4. Click Create New Calendar

2.2 Choose Calendar Type

A dialog appears with calendar type options. Select the type that fits your workflow:

For Inspections: Select Round Robin

This ensures inspections are distributed evenly among available inspectors based on their assigned zones.

---

Step 3: Basic Calendar Information

Configure the calendar details:

---

Step 4: Configure Assigned Users (Inspectors)

This step determines which inspectors are available and how they are assigned based on location.

4.1 Add Inspectors

For each inspector, configure:

4.2 How Zone-Based Assignment Works

When a citizen books an inspection for a specific address:

1. System geocodes the property address to coordinates
2. Coordinates are matched to a Tax Map zone
3. System identifies inspectors assigned to that zone
4. Round Robin counter assigns the next available inspector
5. Workload is distributed evenly across the inspector pool

4.3 Example Inspector Configuration

Inspector 1:

User: John Smith
Priority: 1
Location Type: Tax Map
Tax Map: Ellicott City

Inspector 2:

User: Jane Doe
Priority: 2
Location Type: Tax Map
Tax Map: Ellicott City, Columbia East

Inspector 3:

User: Mike Johnson
Priority: 1
Location Type: Tax Map
Tax Map: West Columbia, Clarksville

Repeat this configuration for all team members who will perform this inspection type.

---

Step 5: Configure Availability Settings

Define when inspections can be scheduled and how slots are generated.

5.1 Meeting Duration Configuration

5.2 Buffer Time Configuration

5.3 Scheduling Window

5.4 Capacity Limits

5.5 Distribution Strategy

For Inspections: Select Optimize for Equal Distribution

5.6 Available Hours Configuration

Set working hours for each day of the week:

5.7 Example Slot Generation

Based on the configuration above (30-min slots, 8 AM - 4 PM Monday):

5.8 Date Overrides (Holidays/Closures)

Add date-specific overrides for holidays or special closures:

1. Navigate to Date Specific Hours section
2. Click Add Date Override
3. Configure:

---

Step 6: Configure Calendar Booking Payments

Enable payment collection for calendar bookings such as inspection fees, permit fees, or service charges.

6.1 Access Payment Configuration

1. Navigate to your calendar (e.g., Building Inspections for Residential Additional Duplex Permit)
2. Select the Forms & Payment tab
3. Locate the Payment Configuration section

6.2 Enable Payment Collection

Toggle Accept Payments to enable payment features for this calendar.

Code Reference: Payment configuration is controlled by the acceptPayments field which defaults to false.

6.3 Configure Base Payment Settings

Available Payment Providers:

Available Currencies:

6.4 Configure Payment Mode

Important: Always test payment flows in Test Mode before enabling Live Mode. Toggle the Payment Mode switch to enable Live Mode when ready for production.

6.5 Configure Rescheduling Fees (Optional)

Rescheduling fees allow you to charge citizens for rescheduling appointments, with tiered pricing based on how many times they've rescheduled.

Add Rescheduling Fee Tiers

Click Add Rescheduling Fee to create fee tiers:

Example Rescheduling Fee Structure

Note: Leave Max Reschedule Count empty for unlimited (applies to all reschedules beyond the minimum).

6.6 Save Payment Configuration

1. Review all payment settings
2. Click Save to apply payment configuration
3. Test payment flow in Test Mode before going live

Dependency Note: Payment configuration requires a valid payment provider account (Govolution, Stripe, or PayPal) configured at the organization level. Contact your system administrator if payment providers are not available in the dropdown.

---

Step 7: Configure Inspection Forms

Two forms are required for the inspection workflow:

Form 1: Inspection Review Form

Purpose: Captures the inspector's detailed review after completing an inspection.

Create the Inspection Feedback Entity

1. Open Entity Manager
2. Create new entity: Inspection Feedbacks
3. Add fields:

Create the Inspection Review Form

1. Go to Inspection Feedbacks entity -> Forms
2. Create new form for inspectors to complete after inspections
3. Include fields for documenting findings

Form 2: Permit Update Form

Purpose: Updates the permit record based on inspection results.

1. Create a form on the Permit Entity that allows updating:
   • Inspection status
   • Inspection date
   • Inspector comments
   • Next steps

Link Forms to Calendar

1. Return to your calendar (e.g., Building Inspections for Residential Additional Duplex Permit)
2. Navigate to Forms & Payment section
3. Configure:

1. Save the calendar

Tip: Hover over the info icon (i) next to each form field for guidance on which form type is required.

---

Step 8: Create Inspection Code Records

Before mapping inspections to permits, ensure you have inspection codes defined.

8.1 Navigate to Inspection Codes Entity

1. Open Entity Manager
2. Select or create Inspection Codes entity

8.2 Add Inspection Code Records

For each inspection type, add a record:

Standard Inspection Types:

---

Step 9: Create Permit-Inspection Mapping

This step links your calendar and inspection codes to the permit type.

9.1 Navigate to Permit-Inspection Mapping Entity

1. Open Entity Manager
2. Select Permit Inspection Mapping entity
3. Click View Records -> Add New Record

9.2 Configure the Mapping

9.3 Add Multiple Mappings

Create a mapping record for each inspection type required for this permit:

Result: When a citizen with a Residential Additional Duplex Permit needs an inspection, they will see only the relevant inspection types, and the system will use the correct calendar for scheduling.

---

Part 2 Complete!

The inspection scheduling system is now fully configured!

---

Part 3: Citizen Experience

How Citizens Schedule Inspections

Once a citizen has submitted a permit application, they can schedule required inspections through the portal.

---

Step-by-Step Citizen Flow

1. View Submitted Applications

Citizens navigate to the specific permit category page (e.g., Building Permits) in the Citizen Portal to see their submitted records for that permit type.

+-------------------------------------------------------------+
|                   BUILDING PERMITS                           |
+-------------------------------------------------------------+
|                                                              |
|  +------------------------------------------------------------+
|  | Residential Additional Duplex Permit                       |
|  | Permit #: BLD-2025-001234                                  |
|  | Status: Approved                                            |
|  | Property: 123 Main Street, Columbia, MD                    |
|  |                                                            |
|  | [View Details]  [Schedule Inspection]                      |
|  +------------------------------------------------------------+
|                                                              |
+-------------------------------------------------------------+

2. Access Inspection Scheduling

From the permit record, citizens click "Schedule Inspection" to view available inspections.

The system displays:

• List of required inspection types (based on permit-inspection mapping)
• Available time slots (based on calendar configuration)

+-------------------------------------------------------------+
|               SCHEDULE INSPECTION                            |
|               Permit #: BLD-2025-001234                      |
+-------------------------------------------------------------+
|                                                              |
|  Select Inspection Type:                                     |
|  +------------------------------------------------------+   |
|  | o Foundation Inspection                               |   |
|  | o Framing Inspection                                  |   |
|  | o Electrical Rough-In Inspection                      |   |
|  | o Plumbing Rough-In Inspection                        |   |
|  | o Final Building Inspection                           |   |
|  +------------------------------------------------------+   |
|                                                              |
+-------------------------------------------------------------+

3. Select Inspection Type and Time Slot

Citizens:

1. Choose the desired inspection type
2. View available dates in calendar view
3. Select an available time slot
4. Click "Schedule Inspection"

4. Confirmation Screen

Upon successful booking, citizens see a confirmation with:

+-------------------------------------------------------------+
|                  INSPECTION SCHEDULED                        |
+-------------------------------------------------------------+
|                                                              |
|  [checkmark] Your inspection has been scheduled successfully!|
|                                                              |
|  -----------------------------------------------------------  |
|                                                              |
|  Inspection Type:    Foundation Inspection                   |
|  Date:               Wednesday, January 15, 2025             |
|  Time:               9:00 AM - 9:30 AM                       |
|  Inspector:          John Smith                              |
|  Confirmation #:     INS-2025-005678                         |
|                                                              |
|  Property Address:                                           |
|  123 Main Street, Columbia, MD 21044                         |
|                                                              |
|  -----------------------------------------------------------  |
|                                                              |
|  A confirmation email has been sent to your                  |
|  registered email address.                                   |
|                                                              |
|          [View All Inspections] [Return to Permit]           |
+-------------------------------------------------------------+

5. View All Scheduled Inspections

Citizens can view all inspections for a permit by:

1. Opening the permit record
2. Navigating to the Inspections tab

This tab displays:

• All scheduled inspections
• Inspection status (Scheduled, Completed, Passed, Failed)
• Inspector assignment
• Historical inspection results

---

Configuration Verification Checklist

Before going live, verify the complete workflow:

Part 1: Permit Application

• Permit Entity created with all required fields
• Permit Form created, published, and accessible
• Permit Menu record created with correct entity/form links
• Process created with AI evaluation rules
• Process linked to Permit Menu record
• Test: Submit a test application and verify AI evaluation

Part 2: Inspection Scheduling

• Tax Maps configured for geographic zones
• Calendar created with correct type (Round Robin)
• Inspectors added with Tax Map assignments
• Availability hours configured
• Capacity limits set appropriately
• Payment configuration enabled (if collecting fees)
• Payment provider selected and configured
• Payment mode set to Test for initial testing
• Rescheduling fees configured (if applicable)
• Inspection Forms created and linked to calendar
• Inspection Codes created for all inspection types
• Permit-Inspection Mapping records created
• Test: Schedule a test inspection and verify assignment
• Test: Complete a test payment in Test Mode

Part 3: Citizen Experience

• Citizen can view permit on portal
• Citizen can access inspection scheduling
• Correct inspection types appear for permit
• Available slots display correctly
• Booking creates appointment with correct inspector
• Confirmation displayed and email sent
• Inspection history visible on permit record

---

Troubleshooting

Permit Not Appearing on Citizen Portal

Check:

1. Permit Menu record exists and is marked Active
2. Application Type matches portal filter
3. Entity and Form IDs are correctly linked
4. Form is published

AI Evaluation Not Running

Check:

1. Process is linked to Permit Menu record
2. Intake trigger is set to Form Submission
3. GovAssist Status field has Autofill with AI configured
4. Evaluation rules are defined

No Available Inspection Slots

Check:

1. Calendar availability hours are configured
2. Inspectors are assigned to the calendar
3. Tax Maps are correctly linked
4. Minimum notice period hasn't passed
5. No date overrides blocking availability

Wrong Inspector Assigned

Check:

1. Property address geocodes to correct Tax Map zone
2. Inspector is assigned to that Tax Map
3. Round Robin counter is functioning
4. Priority settings are correct

Payment Not Processing

Check:

1. Accept Payments is toggled ON
2. Payment Provider is selected (Govolution, Stripe, or PayPal)
3. Total Amount is greater than 0
4. Payment provider account is configured at organization level
5. Payment Mode is set correctly (Test for testing, Live for production)

Rescheduling Fee Not Applying

Check:

1. Rescheduling fees are configured on the calendar
2. Min/Max reschedule counts are set correctly
3. Fee tiers don't have overlapping ranges
4. Currency is properly selected

---

Related Documentation

• Fee Definitions & Payment Forms - Payment configuration
• Request Additional Fee Workflow - Staff-initiated fees

---

For additional configuration assistance, contact the GovAssist support team.