> ## Documentation Index
> Fetch the complete documentation index at: https://docs.azalt.co/llms.txt
> Use this file to discover all available pages before exploring further.

# FormSubmission

> Submission container for a form at a specific site and year

FormSubmission is created per FormSite (site + year) and groups all field values (FormElementSubmissions) for that deployment.

## Purpose and Function

FormSubmission serves as:

* **Container**: Groups all field responses for one site/year
* **Scope**: Ties values to a specific `formSiteId`
* **Ownership**: Stores creator and organization

## Submission Types

**Internal submissions (private forms)**

* Exactly one active submission per FormSite (non-deleted)
* Auto-save functionality preserves work in progress
* Real-time validation and error checking
* Direct integration with user permissions

**External submissions (public forms)**

* Multiple submissions allowed per site/year
* No platform account required
* Branded public form header (optional)

## Submission Lifecycle

**1. Initiation**: User accesses a form deployment (FormSite)

**2. Data Entry**: User fills out form fields, creating FormElementSubmissions

**3. Validation**: System checks required fields, data types, and business rules

**4. Submission**: User completes and submits the form

**5. Review** (optional): Approvals happen per field value based on workflow

**6. Integration**: Data becomes available for calculations and reporting

## Data Structure

Each FormSubmission contains:

**Identification**:

* Unique submission ID
* Associated FormSite (form + site + year)
* Submitter information (user or external contact)

**Content**:

* Collection of FormElementSubmissions (individual field values)
* Supporting documents attached to specific values

**Timestamps**:

* Created/updated dates

## Multi-Period Data Handling

For forms with monthly or quarterly periods, a single FormSubmission can contain:

```
FormSubmission (Annual Energy Report - Plant A - 2024)
├── January Energy Consumption: 1,250 kWh
├── February Energy Consumption: 1,180 kWh
├── March Energy Consumption: 1,340 kWh
...
└── December Energy Consumption: 1,290 kWh
```

## External form management

**Public Access**: External forms generate unique URLs that don't require authentication

**Multiple Submissions**: Suppliers or contractors can submit multiple times for the same site/year

**Approvals**: Values may require approval (status at the field level)

**Aggregation**: Multiple external submissions can be analyzed and aggregated as needed

## Real-World Examples

**Monthly Energy Report**:

* Single submission per facility per year
* Contains 12 months of energy consumption data
* Auto-calculates annual totals and averages
* Links to supporting utility bills

**Supplier Assessment**:

* External submission from each supplier
* Contains company profile and emissions data
* Multiple suppliers can submit for same reporting year
* Internal team reviews and validates responses

**Quarterly Waste Tracking**:

* Four separate submissions per year per site
* Each submission contains waste stream data
* Progressive data collection throughout the year
* Real-time dashboard updates as submissions complete

## Integration and Export

**API access**: Retrieve submission data programmatically

**CSV/XLSX export**: Export/import of values is supported at the FormElementSubmission level

**Dashboard Integration**: Submission data automatically feeds into widgets and visualizations

**Dashboards**: Submissions contribute to dashboards and summaries

## Operational Benefits

**Data Integrity**: Complete submission tracking prevents data loss and duplication

**Workflow**: Clear status handling for approvals at the field level, with inline Approve/Reject/Revert controls and bulk actions for populated periods

**Scalability**: Handle thousands of submissions across multiple sites and forms

**Flexibility**: Support both internal data collection and external stakeholder engagement

**Progress telemetry**: Emit live “remaining vs. total” metrics for data-entry and approval stages that downstream dashboards can subscribe to