Forms

Overview

The Forms module is the structured input layer for MyGov. Citizens submit forms via the public website; staff submit forms via the admin portal. A submitted form creates a FormResponse record that becomes the trigger for the Workflow Engine — the primary mechanism by which form submissions drive automated actions across the platform.

Forms are highly configurable: fields, validation rules, routing (which forms appear where), and post-submission actions are all managed in the admin portal without code changes. This makes Forms one of the highest-leverage integration points in the system — nearly every public-facing workflow starts here.

Relationships with Other Systems

Forms → Workflow Engine (primary trigger source)

Form submissions are the most common trigger for the Workflow Engine. When a FormResponse is created, WorkflowActionRunner.StartWorkflow(FormResponse) is called, executing all FormAction rows configured for that form. Actions run in Order sequence with a configurable Schedule value (null = on submit; "Status:Approved" = on staff approval; etc.). This is the multi-step approval pattern used by Reservations and available to any form. See Workflow Engine.

Forms → Reservations

The citizen-facing reservation request is a form. FacilitySpaceReservationController posts a synthetic FormResponse to the named form "FacilitySpaceReservation" and calls WorkflowActionRunner to trigger confirmation and notification actions. The reservation flow is the most developed example of the Form → Workflow pattern in the codebase. See Reservations.

Forms → Distribution & Publishing (confirmation emails)

Post-submission confirmation emails are sent via FormAction workflow steps using MailHandler or MSGraphHandler/SendTemplate. The form response fields are available as Handlebars context values (e.g. {{FirstName}}, {{Email}}) in the email template. This is the primary mechanism by which transactional emails reach citizens. See Distribution & Publishing.

Forms → Microsoft Platform (Graph API actions)

FormAction steps can use MSGraphHandler to create SharePoint list items, send emails via the Graph API, create Exchange calendar events, or read user data. This is commonly used for routing form responses into SharePoint document libraries or notifying staff via Teams. See Microsoft Platform.

Forms → Location (address and facility fields)

Forms that collect address or facility information (service requests, permit applications, reservation requests) may include a facility or space picker field. The selected FacilitySpaceId or FacilityId becomes available in the workflow context for downstream actions. See Location.

Forms → Calendar & Time (event registration)

Registration forms for Programs and Events collect attendee information for a specific session. Currently, Parks registration uses an external platform. Where registration is internal (Library, or future in-house registration), the form response links a registrant to a ProgramSession via its ID. See Calendar & Time and Programs & Registration.

Forms ↔ WebPages / CMS (embed and display)

Forms are embedded in public website pages via a web component. The CMS page references a Form by ID; the component renders the form and handles submission. Form responses can also be surfaced on admin portal pages (e.g. viewing reservation requests tied to a facility). The mechanism for page → form FK and response display is part of the undocumented surface area.

What This Doc Should Cover When Written

• Form and field data model — Form, FormField, FormFieldOption, FormResponse, FormResponseValue. Types of fields (text, select, file upload, facility picker, date/time).
• Public embed model — how forms are embedded on public pages; the web component interface; how responses are authenticated (unauthenticated vs. Azure AD).
• Admin portal module — form builder, response viewer, routing rules.
• Form → Workflow configuration — how FormAction rows are managed per form; the Schedule value pattern; multi-step approval wiring.
• Response storage and access — where responses are stored, who can access them, retention policy.
• Named forms — some forms are referenced by string name from other modules (e.g. "FacilitySpaceReservation"). This convention should be documented and the full list of named forms inventoried.
• File upload handling — where uploaded files are stored, how they are associated with responses.