> ## 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

> Configurable data transformation rules for bulk importing external data into forms

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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```javascript theme={null}
// 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)*:

```javascript theme={null}
return {
  total_energy: 15420.5,
  energy_source: "Grid Electricity"
};
```

*Grouped output (per site)*:

```javascript theme={null}
return {
  $grouped: true,
  $groupKey: "site_name",
  results: {
    "Plant A": { total_energy: 8500 },
    "Plant B": { total_energy: 6920 }
  }
};
```

*Monthly data*:

```javascript theme={null}
return {
  monthly_consumption: {
    "1": 1250,
    "2": 1180,
    "3": 1340
  }
};
```

## Value Type Support

The import system preserves all output types:

**Numeric values**:

```javascript theme={null}
return { total_energy: 15420.5 };
// Stored as: 15420.5
```

**String values**:

```javascript theme={null}
return { energy_source: "Renewable - Solar" };
// Stored as: "Renewable - Solar"
```

**Boolean values**:

```javascript theme={null}
return { is_certified: true };
// Stored as: true
```

**Null values** (delete existing):

```javascript theme={null}
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**:

```csv theme={null}
site,month,kwh
Plant A,January,1250
Plant A,February,1180
Plant B,January,980
Plant B,February,1020
```

**Processor with grouping**:

```javascript theme={null}
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