Activity

​

Yaşam Döngüsü

1. ActivityDefinition ile bağlantılı form elementi seçilir
2. UI üzerinden girişler toplanır
3. Sunucuda calculate fonksiyonu çalıştırılır
4. Sonuç Activity olarak kaydedilir ve FormElementSubmission ile ilişkilendirilir
5. Görüntüleme, dışa aktarma veya yeniden hesaplama yapılır

​

Veri Modeli

• definitionId: kullanılan ActivityDefinition kimliği
• input: gönderilen giriş değerleri (JSON)
• value: hesaplama sonucu sayısal değer
• metadata: hesaplamaya dair detaylar (JSON)
• form submission, form elementi, site, yıl, periyot bağlantıları

{
  "definitionId": "ad_123",
  "input": { "electricityKwh": 1200, "gridRegion": "Türkiye" },
  "value": 432.0,
  "metadata": { "factor": 0.36, "year": 2025 }
}

​

Aktivitelerle Çalışma

• activities.addActivity
  • Girdi: { formId, key, siteId, year, periodUnit, input }
  • formId + key ile elementi bulur, bağlı ActivityDefinition’ı kullanır, hesaplar ve kaydeder.
• activities.getActivities
  • Girdi: { formId, key, siteIds?, years?, periodUnits? }
  • Elemandaki aktiviteleri döndürür; input/metadata parse edilir, bağlamsal alanlar (siteId, siteName, year, periodUnit) eklenir.
• activities.importActivities
  • Toplu içe aktarma; tüm satırların aynı ActivityDefinition’a bağlı elementleri hedeflediğini doğrular; satır bazlı hesaplama ve hata raporlar.
• activities.exportActivities
  • CSV/XLSX dışa aktarım; sabit sütun sırası: bağlam alanları, düzleştirilmiş input_*, düzleştirilmiş metadata_*, ve value.
• activities.removeActivity
  • Aktivite ve bağlı FormElementSubmission kayıtlarını siler; periyot durumunu iş akışına göre ayarlar.
• activities.recalculateActivity / activities.recalculateActivities
  • Tekil veya filtrelenmiş bir grup aktiviteyi, güncel ActivityDefinition calcCode ile yeniden hesaplar.

​

Dışa Aktarım Formatı

• activityId, site, year, periodUnit, value
• ActivityDefinition inputs listesindeki her giriş (adlarıyla eşleşen sütunlar)
• Her metadata anahtarı için metadata_* sütunları

• Bağlam: activityId, site, year, periodUnit, value
• Girdiler: electricityKwh, gridRegion, … (tanımdaki girişler)
• Metadata: metadata_factor, metadata_year, … (düzleştirilmiş anahtarlar)

​

İçe Aktarım Kuralları ve Hatalar

• Tüm satırlar, aynı ActivityDefinition’a bağlı elementleri hedeflemelidir (anahtar üzerinden eşleşir).
• Site erişimi satır bazında doğrulanır.
• Hatalar satır numarası ve bağlam (key/site/yıl/periyot) ile birlikte kullanıcı dostu mesajla döner; örn.: Satır 3 (energy - siteA 2024 Period 1): electricityKwh sıfırdan büyük eşit olmalıdır.

​

Yeniden Hesaplama

• Yeniden hesaplama
  • güncel ActivityDefinition calcCode,
  • kayıtlı input,
  • güncel bağlam (site/yıl/periyot) ve dataset’leri kullanır.
• NaN/Infinity değerleri hem value hem de sayısal metadata alanlarında 0’a normalize edilir.

​

UI & Spreadsheet

• Aktivite UI’si ActivityDefinition’ın uiCode’una göre dinamik render edilir. onAddActivity(values) çağrısı addActivity’yi tetikler.
• Zengin tablo görünümü; site/yıl/periyot filtreleri, tanımda yer alan “standart” giriş sütunlarını vurgulama, ekstra giriş ve meta sütunlarını gösterme desteği içerir.

​

İş Akışı & Durum

• Form veya organizasyon iş akışı onay gerektiriyorsa ilgili periyottaki gönderimler COMPLETED olur.
• Aksi durumda gönderimler anında APPROVED olur.

​

Hata Yönetimi & Kalite

• Hesaplama hatalarında açık ve anlaşılır mesajlar fırlatın; UI bunları kullanıcıya gösterir.
• NaN/Infinity değerleri value ve sayısal meta veride 0’a normalize edilir.
• Girdi alanlarını sade ve anlamlı seçin; example değerleri CSV tespiti ve UI ipuçlarını iyileştirir.

​

Güvenlik

• Tüm işlemlerde site erişim kuralları uygulanır.
• $datasets/$kpis/$sites yardımcıları, organizasyon bağlamına göre RLS ile sınırlandırılır.

​

Bkz.

• ActivityDefinition (girdi/UI/hesaplama ve önizleme)
• Activity Calculation Variables (bağlam değişkenleri ve örnekler)
• Dataset Access Examples (uçtan uca kullanım örnekleri)
• API Örnekleri

curl -H "Authorization: Bearer YOUR_TOKEN" \
  --get \
  --data-urlencode "formId=FORM_ID" \
  --data-urlencode "key=energy_usage" \
  https://your.api/activities

curl -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -X POST https://your.api/activities \
  -d '{
    "formId": "FORM_ID",
    "key": "energy_usage",
    "siteId": "SITE_ID",
    "year": 2025,
    "periodUnit": 1,
    "input": { "electricityKwh": 1200, "gridRegion": "Türkiye" }
  }'

curl -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -X POST https://your.api/activities/recalculate \
  -d '{ "formId": "FORM_ID", "key": "energy_usage", "year": 2025 }'

curl -H "Authorization: Bearer YOUR_TOKEN" \
  --get \
  --data-urlencode "formId=FORM_ID" \
  --data-urlencode "key=energy_usage" \
  --data-urlencode "format=csv" \
  https://your.api/activities/export

​

Sorun Giderme

• Ekle/ithal işlemi kullanıcı hatasıyla başarısız → Hesaplama Error("...") fırlatmış olabilir; girdi veya mantığı mesaj doğrultusunda düzeltin.
• İthalatta çoklu satır hatası → Hata detaylarındaki satır indeksini ve bağlamı kullanarak veriyi düzeltin.
• Yeniden hesaplama sıfırlar üretiyor → İlgili yıl için dataset değerlerini/anahtarlarını kontrol edin; yedek kullanın.
• Dışa aktarımdan sütun eksik → ActivityDefinition inputs şemasında alanın mevcut olduğundan emin olun.

​

Performans İpuçları

• Gerekliyse tek seferde getCoefficients ile alın ve tekrar kullanın.
• Aktivite başına metadata’yı küçük tutun; dışa aktarım hızlanır.

​

Metadata Kuralları

• Açık anahtarlar ve birimleri tercih edin (ör.: efKgCO2ePerKWh).
• Analizi kolaylaştırmak için uygun olduğunda year, period veya siteId ekleyin.