> ## 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.

# FormElementSubmission

> Individual field values with period handling, status, and attachments

FormElementSubmission stores the actual value for a single form element within a FormSubmission. It supports multi-period data, TIMESTAMP entries, per-value workflow status, and multiple entries per period.

## Core Purpose

* **Individual values**: Each field response is stored as a separate row
* **Multi-period**: YEARLY, QUARTERLY, MONTHLY, or TIMESTAMP-based collection
* **Multiple entries**: Multiple rows per period for the same field if needed
* **Activity outputs**: Can reference activity computations

## Data Storage

```
FormElementSubmission {
  formElementId: "energy-consumption",
  formSubmissionId: "formsub-...",
  periodUnit: 3,         // MONTHLY: 1..12, QUARTERLY: 1..4, YEARLY: 1
  sequence: 1,           // 1,2,3... when multiple entries exist
  value: 1250.5,         // JSON value
  recordedAt: null,      // For TIMESTAMP elements only (UTC)
  status: "COMPLETED",   // COMPLETED | APPROVED | REJECTED
}
```

TIMESTAMP elements require a `recordedAt` UTC timestamp. The `periodUnit` for TIMESTAMP rows is derived from the recorded month.

## Value Types

`value` is JSON and can represent various types:

* Number: `1250.5`
* Text: `"Purchased renewable electricity"`
* Array: `["Solar", "Wind"]`
* Object: `{"scope1": 450, "scope2": 280, "total": 730}`

## Activity Integration

When a field uses an activity definition, values may link to calculated outputs:

```
FormElementSubmission {
  formElementId: "scope1-emissions",
  value: 2847.3,
  activityId: "act_...",
  status: "COMPLETED"
}
```

## Attachments (supporting documents)

Supporting documents are linked to a value (FormElementSubmission) and retrieved via APIs using the value’s identifier. Files are not stored inside the `value` JSON.

* **Drawer workflow**: Submitters open a side drawer per element/period to upload or download evidence. Private submissions attach files directly to the FormElementSubmission, while public submissions stage uploads against a draft submission before final send.
* **Badges & counts**: The form UI shows a badge on the paperclip icon whenever files exist, keeping approvers aware of supporting evidence.
* **Deletion rules**: Authenticated users with permissions can delete attachments; public contributors can only add files unless explicitly allowed.
* **Opt-in public mode**: When a form sets `publicSupportingDocumentsMode = "opt-in"`, only elements whose metadata contains `allowSupportingDocumentsUpload: true` will expose the paperclip to public contributors. Internal users continue to see the drawer for every element with attachments enabled.

## Aggregation and Rollup

**Site hierarchy**: Child site data can be rolled up to parents for analysis.

**Time periods**: Monthly can roll up to quarterly and annual totals.

## Examples

**TIMESTAMP value**

```json theme={null}
{
  "formElementId": "electricity",
  "periodUnit": 3,
  "sequence": 1,
  "value": 15420.5,
  "recordedAt": "2024-03-31T23:59:59Z",
  "status": "COMPLETED"
}
```

**YEARLY value with object**

```json theme={null}
{
  "formElementId": "supplier-emissions",
  "periodUnit": 1,
  "sequence": 1,
  "value": { "scope1": 450.2, "scope2": 280.7, "scope3": 125.9, "total": 856.8 },
  "status": "APPROVED"
}
```

## Query Patterns

* By element: values for a specific field across sites/periods
* By site+period: values for a site in a specific period
* By submission: all values within a single submission
* Aggregated views: sum or count across submissions and periods

## Workflow Status

Each value has a status (COMPLETED, APPROVED, REJECTED) based on the configured workflow. Approvals are per value; bulk operations are available for ACTIVITY elements.

## Operational Benefits

* **Flexibility**: JSON-based value storage
* **Scalability**: Large-scale collection across organizations
* **Integration**: Connects to calculations, dashboards, reporting