Skip to main content
ImportDefinition enables automated data ingestion from external sources (CSV, Excel) into form submissions. Each definition specifies input columns, transformation logic, and output mappings to form elements.

​
Core Purpose

  • Data Transformation: Convert external data formats into form-compatible values
  • Multi-Site Support: Process data for multiple sites in a single import
  • Type Preservation: Support numeric, string, and boolean output values
  • Period Handling: Map data to YEARLY, MONTHLY, or QUARTERLY periods

​
Definition Structure

ImportDefinition {
  id: "impdef-...",
  name: "Energy Bill Import",
  description: "Import monthly energy consumption from utility bills",
  inputSchema: [...],      // Expected input columns
  outputSchema: [...],     // Produced output fields
  processorCode: "...",    // JavaScript transformation logic
  organizationId: "org-..." // null for system-wide definitions
}

​
Input Schema

Defines the expected columns from the source file: 
{
  "inputSchema": [
    {
      "name": "site_name",
      "type": "string",
      "required": true,
      "role": "site_identifier",
      "aliases": ["facility", "location"]
    },
    {
      "name": "consumption_kwh",
      "type": "number",
      "required": true
    },
    {
      "name": "is_renewable",
      "type": "boolean",
      "required": false
    }
  ]
}
Column Types:
  • string: Text values
  • number: Numeric values (auto-converted from strings)
  • boolean: True/false (accepts “true”, “1”, “yes”)
Column Roles:
  • site_identifier: Used to match rows to sites in grouped outputs

​
Output Schema

Defines the fields produced by the transformation: 
{
  "outputSchema": [
    {
      "key": "total_energy",
      "label": "Total Energy Consumption",
      "type": "number",
      "periodUnit": "YEARLY"
    },
    {
      "key": "monthly_consumption",
      "label": "Monthly Consumption",
      "type": "number",
      "periodUnit": "MONTHLY"
    },
    {
      "key": "energy_source",
      "label": "Energy Source",
      "type": "string"
    }
  ]
}
Period Units:
  • YEARLY: Single value per year (default)
  • MONTHLY: Values for periods 1-12
  • QUARTERLY: Values for periods 1-4

​
Processor Code

JavaScript code that transforms input rows into output values: 
// Simple aggregation
const total = inputValues.reduce((sum, row) => sum + row.consumption_kwh, 0);
return { total_energy: total };
Available Variables:
  • inputValues: Array of input row objects
  • $year: The target year for the import
Output Formats: Single output (all sites): 
return {
  total_energy: 15420.5,
  energy_source: "Grid Electricity"
};
Grouped output (per site): 
return {
  $grouped: true,
  $groupKey: "site_name",
  results: {
    "Plant A": { total_energy: 8500 },
    "Plant B": { total_energy: 6920 }
  }
};
Monthly data: 
return {
  monthly_consumption: {
    "1": 1250,
    "2": 1180,
    "3": 1340
  }
};

​
Value Type Support

The import system preserves all output types: Numeric values: 
return { total_energy: 15420.5 };
// Stored as: 15420.5
String values: 
return { energy_source: "Renewable - Solar" };
// Stored as: "Renewable - Solar"
Boolean values: 
return { is_certified: true };
// Stored as: true
Null values (delete existing): 
return { deprecated_field: null };
// Deletes any existing submission for this field

​
Import Execution Flow

1. Column Detection: System matches file columns to input schema 2. Column Mapping: User confirms or adjusts column assignments 3. Preview: Processor runs on sample data to show expected results 4. Output Mapping: User maps output fields to form elements 5. Execution: System processes all rows and creates submissions 6. Results: ImportResult records track what was imported

​
Multi-Site Imports

For files containing data for multiple sites: Input file: 
site,month,kwh
Plant A,January,1250
Plant A,February,1180
Plant B,January,980
Plant B,February,1020
Processor with grouping: 
const bysite = {};
for (const row of inputValues) {
  if (!bysite[row.site]) bysite[row.site] = {};
  const month = getMonthNumber(row.month);
  bysite[row.site][month] = row.kwh;
}

return {
  $grouped: true,
  $groupKey: "site",
  results: Object.fromEntries(
    Object.entries(bysite).map(([site, data]) => [
      site,
      { monthly_consumption: data }
    ])
  )
};
The system automatically matches group keys to site names and creates separate submissions for each site.

​
Access Control

  • Imports respect site access permissions
  • Users can only import to sites they have access to
  • Groups for inaccessible sites are silently skipped

​
Import Records

Each import execution creates: Import: Parent record with status and row count ImportResult: Per-site results with:
  • Processed data snapshot
  • Field mappings with values inserted
  • Period metadata

​
Real-World Examples

Utility Bill Import:
  • Input: Monthly utility bills in CSV
  • Output: Monthly energy consumption per site
  • Mapping: Consumption field → Energy form element
Supplier Data Collection:
  • Input: Supplier emissions spreadsheet
  • Output: Scope 1, 2, 3 values with category labels
  • Mapping: Multiple outputs → Assessment form
Quarterly Financial Data:
  • Input: Financial reports with quarterly figures
  • Output: Revenue and cost by quarter
  • Mapping: Q1-Q4 values → Financial form elements

​
Operational Benefits

Efficiency: Bulk import hundreds of values in seconds Accuracy: Automated transformation reduces manual entry errors Flexibility: Custom processors handle any data format Auditability: Complete import history with data snapshots Type Safety: Preserves numeric, string, and boolean values accurately