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

> Dış verileri formlara toplu olarak aktarmak için yapılandırılabilir veri dönüşüm kuralları

ImportDefinition, dış kaynaklardan (CSV, Excel) form gönderimlerine otomatik veri aktarımı sağlar. Her tanım, giriş sütunlarını, dönüşüm mantığını ve form elemanlarına çıkış eşlemelerini belirtir.

## Temel Amaç

* **Veri Dönüşümü**: Harici veri formatlarını form uyumlu değerlere dönüştürür
* **Çoklu Site Desteği**: Tek bir içe aktarmada birden fazla site için veri işler
* **Tür Koruma**: Sayısal, metin ve boolean çıkış değerlerini destekler
* **Dönem İşleme**: Verileri YILLIK, AYLIK veya ÇEYREKLİK dönemlere eşler

## Tanım Yapısı

```
ImportDefinition {
  id: "impdef-...",
  name: "Enerji Fatura İçe Aktarma",
  description: "Aylık enerji tüketimini faturalardan içe aktar",
  inputSchema: [...],      // Beklenen giriş sütunları
  outputSchema: [...],     // Üretilen çıkış alanları
  processorCode: "...",    // JavaScript dönüşüm mantığı
  organizationId: "org-..." // Sistem geneli tanımlar için null
}
```

## Giriş Şeması

Kaynak dosyadan beklenen sütunları tanımlar:

```json theme={null}
{
  "inputSchema": [
    {
      "name": "site_adi",
      "type": "string",
      "required": true,
      "role": "site_identifier",
      "aliases": ["tesis", "lokasyon"]
    },
    {
      "name": "tuketim_kwh",
      "type": "number",
      "required": true
    },
    {
      "name": "yenilenebilir_mi",
      "type": "boolean",
      "required": false
    }
  ]
}
```

**Sütun Türleri**:

* `string`: Metin değerleri
* `number`: Sayısal değerler (metinden otomatik dönüştürülür)
* `boolean`: Doğru/yanlış ("true", "1", "evet" kabul eder)

**Sütun Rolleri**:

* `site_identifier`: Gruplu çıktılarda satırları sitelerle eşleştirmek için kullanılır

## Çıkış Şeması

Dönüşüm tarafından üretilen alanları tanımlar:

```json theme={null}
{
  "outputSchema": [
    {
      "key": "toplam_enerji",
      "label": "Toplam Enerji Tüketimi",
      "type": "number",
      "periodUnit": "YEARLY"
    },
    {
      "key": "aylik_tuketim",
      "label": "Aylık Tüketim",
      "type": "number",
      "periodUnit": "MONTHLY"
    },
    {
      "key": "enerji_kaynagi",
      "label": "Enerji Kaynağı",
      "type": "string"
    }
  ]
}
```

**Dönem Birimleri**:

* `YEARLY`: Yıl başına tek değer (varsayılan)
* `MONTHLY`: 1-12 dönemleri için değerler
* `QUARTERLY`: 1-4 dönemleri için değerler

## İşlemci Kodu

Giriş satırlarını çıkış değerlerine dönüştüren JavaScript kodu:

```javascript theme={null}
// Basit toplama
const toplam = inputValues.reduce((sum, row) => sum + row.tuketim_kwh, 0);
return { toplam_enerji: toplam };
```

**Kullanılabilir Değişkenler**:

* `inputValues`: Giriş satır nesnelerinin dizisi
* `$year`: İçe aktarma için hedef yıl

**Çıkış Formatları**:

*Tekil çıkış (tüm siteler)*:

```javascript theme={null}
return {
  toplam_enerji: 15420.5,
  enerji_kaynagi: "Şebeke Elektriği"
};
```

*Gruplu çıkış (site başına)*:

```javascript theme={null}
return {
  $grouped: true,
  $groupKey: "site_adi",
  results: {
    "Tesis A": { toplam_enerji: 8500 },
    "Tesis B": { toplam_enerji: 6920 }
  }
};
```

*Aylık veri*:

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

## Değer Türü Desteği

İçe aktarma sistemi tüm çıkış türlerini korur:

**Sayısal değerler**:

```javascript theme={null}
return { toplam_enerji: 15420.5 };
// Kaydedilir: 15420.5
```

**Metin değerler**:

```javascript theme={null}
return { enerji_kaynagi: "Yenilenebilir - Güneş" };
// Kaydedilir: "Yenilenebilir - Güneş"
```

**Boolean değerler**:

```javascript theme={null}
return { sertifikali_mi: true };
// Kaydedilir: true
```

**Null değerler** (mevcutu sil):

```javascript theme={null}
return { kaldirilmis_alan: null };
// Bu alan için mevcut gönderimi siler
```

## İçe Aktarma Yürütme Akışı

**1. Sütun Algılama**: Sistem dosya sütunlarını giriş şemasıyla eşleştirir

**2. Sütun Eşleme**: Kullanıcı sütun atamalarını onaylar veya düzenler

**3. Önizleme**: İşlemci örnek veriler üzerinde çalışarak beklenen sonuçları gösterir

**4. Çıkış Eşleme**: Kullanıcı çıkış alanlarını form elemanlarıyla eşler

**5. Yürütme**: Sistem tüm satırları işler ve gönderimleri oluşturur

**6. Sonuçlar**: ImportResult kayıtları neyin içe aktarıldığını takip eder

## Çoklu Site İçe Aktarmaları

Birden fazla site için veri içeren dosyalar için:

**Giriş dosyası**:

```csv theme={null}
site,ay,kwh
Tesis A,Ocak,1250
Tesis A,Şubat,1180
Tesis B,Ocak,980
Tesis B,Şubat,1020
```

**Gruplama ile işlemci**:

```javascript theme={null}
const siteBasina = {};
for (const row of inputValues) {
  if (!siteBasina[row.site]) siteBasina[row.site] = {};
  const ay = getMonthNumber(row.ay);
  siteBasina[row.site][ay] = row.kwh;
}

return {
  $grouped: true,
  $groupKey: "site",
  results: Object.fromEntries(
    Object.entries(siteBasina).map(([site, data]) => [
      site,
      { aylik_tuketim: data }
    ])
  )
};
```

Sistem grup anahtarlarını otomatik olarak site adlarıyla eşleştirir ve her site için ayrı gönderimler oluşturur.

## Erişim Kontrolü

* İçe aktarmalar site erişim izinlerine uyar
* Kullanıcılar yalnızca erişim yetkisi olan sitelere içe aktarabilir
* Erişilemeyen siteler için gruplar sessizce atlanır

## İçe Aktarma Kayıtları

Her içe aktarma yürütmesi şunları oluşturur:

**Import**: Durum ve satır sayısı ile ana kayıt

**ImportResult**: Site başına sonuçlar:

* İşlenmiş veri anlık görüntüsü
* Eklenen değerlerle alan eşlemeleri
* Dönem meta verileri

## Gerçek Dünya Örnekleri

**Fatura İçe Aktarma**:

* Giriş: CSV formatında aylık faturalar
* Çıkış: Site başına aylık enerji tüketimi
* Eşleme: Tüketim alanı → Enerji form elemanı

**Tedarikçi Veri Toplama**:

* Giriş: Tedarikçi emisyon tablosu
* Çıkış: Kategori etiketleriyle Kapsam 1, 2, 3 değerleri
* Eşleme: Birden fazla çıkış → Değerlendirme formu

**Çeyreklik Finansal Veri**:

* Giriş: Çeyreklik rakamlarla finansal raporlar
* Çıkış: Çeyrek bazında gelir ve maliyet
* Eşleme: Q1-Q4 değerleri → Finansal form elemanları

## Operasyonel Faydalar

**Verimlilik**: Saniyeler içinde yüzlerce değeri toplu içe aktar

**Doğruluk**: Otomatik dönüşüm manuel giriş hatalarını azaltır

**Esneklik**: Özel işlemciler her veri formatını işleyebilir

**Denetlenebilirlik**: Veri anlık görüntüleriyle tam içe aktarma geçmişi

**Tür Güvenliği**: Sayısal, metin ve boolean değerleri doğru şekilde korur