# Forms Module

## Table of Contents

* [Overview](#overview)
* [Who Uses the Forms Module](#who-uses-the-forms-module)
* [Forms and Their Settings](#forms-and-their-settings)
  * [Creating a Form](#creating-a-form)
  * [Form Properties](#form-properties)
  * [Response and Access Settings](#response-and-access-settings)
  * [Editing and Deleting Forms](#editing-and-deleting-forms)
* [Form Versions](#form-versions)
  * [Organization Type Restrictions](#organization-type-restrictions)
* [Building Questions](#building-questions)
  * [Question Types](#question-types)
  * [Question Properties](#question-properties)
  * [Choice-Based Questions](#choice-based-questions)
  * [Reordering Questions](#reordering-questions)
  * [Deleting a Question](#deleting-a-question)
* [Collecting Responses](#collecting-responses)
  * [How Respondents Fill Out a Form](#how-respondents-fill-out-a-form)
  * [Editing a Saved Response](#editing-a-saved-response)
  * [One Response Per User](#one-response-per-user)
  * [Email Collection](#email-collection)
* [Viewing and Exporting Responses](#viewing-and-exporting-responses)
  * [Reviewing Individual Responses](#reviewing-individual-responses)
  * [Downloading a CSV Export](#downloading-a-csv-export)
  * [Clearing All Responses](#clearing-all-responses)
* [Inviting Respondents by Email](#inviting-respondents-by-email)
* [Integration with Data Collection](#integration-with-data-collection)
  * [How the Event Bus Connection Works](#how-the-event-bus-connection-works)
  * [Form Status Transitions](#form-status-transitions)
* [Permissions](#permissions)
* [Troubleshooting](#troubleshooting)

***

## Overview

The Forms Module is the dynamic survey and data-entry engine inside OtisEd.Nimble. It lets administrators design structured forms with multiple question types, set rules for how responses are collected, and review submissions — including exporting all responses to a spreadsheet.

Forms are not standalone objects. When a form is linked to the Data Collection system, filling out and saving a response automatically updates the corresponding data collection record status. This means administrators can track completion progress across organizations without any manual bookkeeping.

***

## Who Uses the Forms Module

| Role                            | What they do                                                                                                       |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| Administrator / Form Owner      | Creates and configures forms, builds questions, manages settings, views and exports responses, sends invite emails |
| Respondent (authenticated user) | Opens an assigned form, fills out answers, and saves or updates their response                                     |
| Anonymous respondent            | Fills out a publicly accessible form (when login is not required)                                                  |

***

## Forms and Their Settings

### Creating a Form

Navigate to the form administration area and choose the option to create a new form. You must provide a title. A description is optional.

Once the form is saved, it is immediately available for question building and settings configuration. No questions are added automatically — you build them separately after the form exists.

### Form Properties

Each form has the following properties:

| Property    | What it controls                                                                                     |
| ----------- | ---------------------------------------------------------------------------------------------------- |
| Title       | The name displayed to respondents and in administration lists                                        |
| Description | An optional summary shown below the title                                                            |
| School Year | The academic year this form is associated with (for example, 2024-2025)                              |
| Start Date  | The first date respondents can fill out the form. Before this date, the edit action is not available |
| End Date    | The last date respondents can edit their response. After this date, the form closes for input        |
| Download ID | An optional identifier that links the form to a downloadable reference document                      |

### Response and Access Settings

After creating a form, open its settings panel to configure how responses are collected:

| Setting                         | What it controls                                                                                                        |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Accepting Responses             | When off, no new responses can be submitted. Use this to pause collection without deleting the form                     |
| Requires Login                  | When on, respondents must be signed in to view or answer the form                                                       |
| Can Edit Response               | When on, respondents are allowed to return and modify an answer they already saved                                      |
| Has Limit One Response Per User | When on, each signed-in user can only submit one response. This option is only effective when Requires Login is also on |
| Is Collecting Email             | When on, respondents must provide their email address before their response can be saved                                |
| Is Quiz                         | Marks the form as a quiz, enabling the correct/incorrect flag on individual answer choices                              |

### Editing and Deleting Forms

You can edit a form's title, description, school year, dates, and download ID at any time. Settings (the response behavior flags) are updated separately through the settings panel.

Deleting a form removes it and all of its questions. Responses are not deleted automatically — use the Clear All Responses action first if you also want to remove response data before deleting the form.

***

## Form Versions

Forms are organized into versions, one per school year. Each version is configured separately and controls its own settings, questions, and eligible respondents. Administrators create and edit versions from the form builder using the version edit dialog.

### Organization Type Restrictions

By default, any organization type -- State, District, or School -- can respond to a form version. Administrators can restrict a version to specific organization types using the **Respond by** setting in the version edit dialog.

**How to set organization type restrictions:**

1. Open the form in the Form Builder.
2. Open the version edit dialog for the version you want to configure.
3. Under **Respond by**, check one or more of the following options:
   * **State** -- Only state-level organizations can respond
   * **District** -- Only district-level organizations can respond
   * **School** -- Only school-level organizations can respond
4. Save the version.

If no options are checked, the restriction is removed and all organization types can respond.

When a new version is created, **School** is selected by default. Adjust this before publishing if other organization types also need to respond.

**What restrictions affect:**

* The **My Forms** tab in the Form Viewer only shows a form to an organization if that organization's type is included in the form's allowed types (or if no restrictions are set). See the [Form Viewer](/guides/form-viewer.md) guide for details.
* The **Summary** tab in the Form Viewer only counts organizations whose type is eligible for a given form.

Restrictions are per-version. A prior year's version is not affected when you change restrictions on the current year's version.

***

## Building Questions

Questions are added to a form one at a time. Each question belongs to exactly one form and is shown to respondents in the order defined by its position index.

### Question Types

The following question types are available:

| Question Type   | How respondents answer                                                                                                          |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| Short Text      | A single-line text field. Best for names, identifiers, and brief values                                                         |
| Rich Text       | A full word-processor-style editor with formatting tools. Best for narrative responses that need structure, tables, or emphasis |
| Numeric         | A number entry field. You can optionally set a minimum and maximum allowed value to constrain the answer                        |
| Date            | A date picker. Best for collecting specific dates                                                                               |
| Multiple Choice | A list of options where the respondent picks exactly one. Also known as radio-button style selection                            |
| Checkboxes      | A list of options where the respondent can pick one or more. An optional free-text "Other" field can be added                   |
| Dropdown List   | A list of options displayed as a dropdown menu. The respondent picks exactly one                                                |

### Question Properties

Every question, regardless of type, can be configured with:

| Property     | Purpose                                                                                   |
| ------------ | ----------------------------------------------------------------------------------------- |
| Title        | The question text the respondent sees                                                     |
| Description  | Additional context shown below the question title                                         |
| Display Text | An alternate label used in certain views and interfaces                                   |
| Report Label | A short column header used in CSV exports and reports                                     |
| Help Text    | Guidance shown near the answer field to assist respondents                                |
| Required     | When checked, the respondent must answer this question before their response can be saved |
| Index        | The display order position on the form. Questions with lower index values appear first    |

### Choice-Based Questions

For Multiple Choice, Checkboxes, and Dropdown List questions, you define the list of answer options when creating or editing the question. Each choice has a text value and two optional flags:

* **Is Correct** — Marks this choice as the correct answer. Useful when the form is used as a quiz.
* **Is Unique** — Marks this choice as mutually exclusive. When a respondent selects a unique choice, it cannot be combined with other selections.

For Multiple Choice and Checkbox questions, you can also enable the **Has Other Option** setting. This appends a free-text "Other" input to the choice list, allowing respondents to provide an answer not covered by the predefined options. The "Other" option always appears at the end of the list.

### Reordering Questions

Change the **Index** value on a question to move it to a different position. Questions are displayed to respondents in ascending index order.

### Deleting a Question

Deleting a question removes it and its associated choices permanently. Existing responses that included an answer to that question will show an empty value for that column in exports, since the question no longer exists.

***

## Collecting Responses

### How Respondents Fill Out a Form

When a respondent opens a form, all questions are displayed in order. They fill in answers and save their response. The response is recorded with the respondent's user identity (if logged in), their email address (if the form collects it), and a timestamp.

If the form has a Start Date in the future or an End Date in the past, the edit action will not be available and the form will appear read-only.

If the form's **Accepting Responses** setting is off, respondents cannot submit new answers.

### Editing a Saved Response

If the form has **Can Edit Response** enabled, a respondent can open their existing response and update any answers. All previous answers are replaced with the updated values when they save again.

If **Can Edit Response** is off, the form is effectively one-submission-only. Attempting to update a response when this setting is off will result in an error.

### One Response Per User

When **Has Limit One Response Per User** is on (and **Requires Login** is also on), the system checks whether the signed-in user already has a response for this form. If they do, submitting a second response is blocked. This prevents duplicate submissions from the same account.

### Email Collection

If **Is Collecting Email** is on, the respondent must enter their email address as part of their submission. Saving without an email address is not allowed unless the response is being saved as a draft.

***

## Viewing and Exporting Responses

### Reviewing Individual Responses

From the form administration view, open the responses panel for a specific form. Each row in the list represents one submission and shows the respondent's details and submission date. You can sort and filter the list by available fields.

Select a response row to open a detailed view showing each question paired with the respondent's answer.

### Downloading a CSV Export

Use the **Download Responses CSV** action to export all responses for a form to a spreadsheet file. The exported file contains:

* A **Date** column showing when each response was last saved (or created if never modified).
* One column per question, using the question's **Report Label** as the column header. If no report label was set, the question's title is used.
* One row per response.

All fields are quoted in the export. If a respondent did not answer a particular question, that cell is empty.

There is no upper limit on the number of rows exported — all responses matching any active filter criteria are included.

### Clearing All Responses

Administrators with the Response Delete permission can remove all responses for a form at once using the **Delete All Responses** action. This action is irreversible. The form itself and its questions are not affected — only the submitted response data is removed.

***

## Inviting Respondents by Email

From the form administration area, use the **Send Invite Email** action to compose and send an email invitation to one or more recipients. You provide the recipient address, subject line, and body text. The system sends the message using the platform's configured email sender.

Invite emails are sent immediately and are not tracked within the Forms Module — there is no delivery status or open-rate record stored.

***

## Integration with Data Collection

### How the Event Bus Connection Works

Forms that are linked to a Data Collection record are connected through an internal event bus. When a respondent saves a response (either creating a new one or updating an existing one), the Forms Module publishes a status change event. That event carries:

* The data collection form ID (the record being tracked on the Data Collection side)
* The new status value
* The identity of the user who triggered the change

The Data Collection system listens for this event and updates the corresponding record automatically. No administrator action is required.

### Form Status Transitions

The following status transitions are triggered automatically through the event bus when form responses are saved:

| Action                            | Resulting Status in Data Collection |
| --------------------------------- | ----------------------------------- |
| First answer saved (new response) | In Progress                         |
| Existing response updated         | In Progress                         |

The transition to **Completed** and **Finalized** statuses is managed by the Data Collection system independently of the Forms Module. See the [Data Collection Forms](/guides/data-collection-forms.md) guide for the full lifecycle.

***

## Permissions

Access to the Forms Module is controlled by the following permission grants:

| Permission            | What it allows                                                                                      |
| --------------------- | --------------------------------------------------------------------------------------------------- |
| Forms.Form            | View and manage forms, add and edit questions, view responses, export responses, send invite emails |
| Forms.Form.Delete     | Delete a form entirely                                                                              |
| Forms.Response.Delete | Delete individual responses or clear all responses from a form                                      |

Users without the Forms.Form permission cannot access the form administration interface. Some read operations (viewing a form's questions and settings, and counting responses) are accessible without authentication when the form does not require login, to support anonymous respondent workflows.

***

## Troubleshooting

**A respondent says they cannot submit their response.** Check whether the form's **Accepting Responses** setting is on. Also verify that the current date falls within the form's Start Date and End Date range (if dates are configured). If either condition is not met, submissions are blocked.

**A respondent reports they are getting an error about a duplicate response.** If **Has Limit One Response Per User** is on, the system will reject a second submission from the same account. The respondent may have already submitted under a different browser session. An administrator can delete the existing response if a fresh submission is needed.

**An email address is being required but the respondent does not want to provide one.** This is controlled by the **Is Collecting Email** setting on the form. An administrator with form management access can turn this setting off if collecting email is no longer required.

**The CSV export columns do not have meaningful headers.** Column headers in the CSV export come from each question's **Report Label**. If report labels were not set when questions were created, the full question title is used instead. Edit the questions and add concise report labels to improve export readability.

**The response list for a form is empty after responses were submitted.** Confirm that the responses were not cleared using the Delete All Responses action. Also confirm you are viewing the correct form — form titles can be similar across school years.

**A form linked to Data Collection is not showing status updates.** The status update happens through an internal event published when a response is saved. If the data collection record is not updating, verify that the form's link to the data collection record (the `DcFormId` association) was established correctly when the response was submitted. Contact your system administrator if the association appears to be missing.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://nimble.docs.otised.com/guides/forms-module.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.