Import form element submissions

Import form element submissions data from external sources in bulk.

Import Features:

• Bulk data import from structured formats (CSV, Excel, JSON)
• Validation and error reporting for imported data
• Support for both new submissions and updates to existing ones
• Flexible mapping between external data formats and internal form structure

Data Validation:

• Validates form element types and constraints
• Ensures data integrity and consistency
• Provides detailed error reports for failed imports
• Supports rollback mechanisms for failed batch operations

TIMESTAMP support:

• Accepts a recordedAt (or timestamp) column; required for TIMESTAMP elements.
• Parses ISO 8601 (assumes UTC if timezone missing), validates that year matches the CSV year, and derives periodUnit from the UTC month.
• Upserts per (formSubmissionId/new_formSiteId, formElementId, recordedAt); duplicates by timestamp update the value; empty value with recordedAt deletes that exact entry.

Multi-form import:

• If the uploaded file contains a formName column (as produced by the export when includeFormName=true), rows are routed to their respective forms by name. In this case, formId in the request is ignored for those rows.
• When formName is not present, the import behaves as single-form and uses the provided formId.

Example request (CSV import, trimmed):

{
  "formId": "form-123",
  "format": "csv",
  "fileData": "<base64-csv>"
}

Example CSV content:

siteName,year,key,periodUnit,value,recordedAt
plant-a,2024,water_usage,,120.5,2024-03-15T10:30:00Z

Example response (trimmed):

{
  "success": true,
  "message": "Imported",
  "stats": { "created": 1, "updated": 0, "deleted": 0, "valuesDeleted": 0, "formSitesCreated": 0 }
}

This endpoint is essential for migrating data from legacy systems, bulk data entry operations, and automated data synchronization workflows.