Skip to main content

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.

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