ImportDefinition

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

Getting Started

Deployment

AI & Integrations

Organization Sync

Concepts

Core Purpose

Definition Structure

Input Schema

Output Schema

Processor Code

Value Type Support

Import Execution Flow

Multi-Site Imports

Access Control

Import Records

Real-World Examples

Operational Benefits

​Core Purpose

​Definition Structure

​Input Schema

​Output Schema

​Processor Code

​Value Type Support

​Import Execution Flow

​Multi-Site Imports

​Access Control

​Import Records

​Real-World Examples

​Operational Benefits

Core Purpose

Definition Structure

Input Schema

Output Schema

Processor Code

Value Type Support

Import Execution Flow

Multi-Site Imports

Access Control

Import Records

Real-World Examples

Operational Benefits