Skip to main content
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 
{
  "formElementId": "electricity",
  "periodUnit": 3,
  "sequence": 1,
  "value": 15420.5,
  "recordedAt": "2024-03-31T23:59:59Z",
  "status": "COMPLETED"
}
YEARLY value with object 
{
  "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