KPI API Entegrasyonu (Pull)

Hedef Kitle: Admin, Geliştirici
Sayfa Türü: Nasıl Yapılır + Referans
Plan Özelliği: kpi_api_integration (tenant'ınız için etkinleştirilmiş olmalı)

---

Genel Bakış

COS, dış API'lerden KPI ölçüm verilerini otomatik olarak belirli zamanlarda çekebilir. Bu pull entegrasyon modelidir — COS, tanımlanan aralıklarla API uç noktalarınızı çağırır ve elde edilen değerleri KPI ölçümü olarak yazar.

Nasıl Çalışır

Dış API  ←──── COS (cron zamanlama) ────→  KPI Ölçüm Tablosu
   (BI aracınız,       HTTP GET/POST             (otomatik doldurulur)
    veri ambarınız,      + auth header'ları
    izleme sisteminiz)   + JSONPath çıkarma

1. Bir Entegrasyon Uç Noktası tanımlarsınız (base URL + auth bilgileri)
2. Belirli KPI'ları API yanıt alanlarına bağlayan KPI Bağlantıları oluşturursunuz
3. COS, API'yi cron zamanlamasına göre çağırır ve JSONPath ile değerleri çıkarır
4. Çıkarılan değerler ilgili KPI'ya ölçüm olarak yazılır

---

Ön Koşullar

• Plan Özelliği: Tenant'ınız için kpi_api_integration etkinleştirilmiş olmalı
• İzin: Entegrasyon menü/API izni (KPI_INTEGRATION_BINDING) ve hedef üzerinde yetki: KPI için o KPI'ı düzenleme yetkisi (KPI düzenleme izni + KPI'ın sorumlusu, sahip/üst birim lideri veya yönetici rolü); Anahtar Sonuç için mevcut OKR yetkisi
• Dış API: Veri kaynağınız HTTP/HTTPS üzerinden erişilebilir olmalı

---

Adım 1: Entegrasyon Uç Noktası Oluşturma

Uç nokta, dış API bağlantı detaylarını tanımlar.

Yol: Hedefler & Takip → KPI Takibi → KPI detayı → Entegrasyon sekmesi → Uç Noktaları Yönet

Gerekli Alanlar

Alan	Açıklama	Örnek
Ad	Açıklayıcı isim	"BI Dashboard API"
Base URL	API temel URL'i	https://api.example.com/v1
Auth Türü	Kimlik doğrulama yöntemi	Bkz. Auth Türleri
Kimlik Bilgileri	Auth bilgileri (şifreli saklanır)	Auth türüne göre değişir

Desteklenen Auth Türleri

Auth Türü	Kimlik Bilgileri	Gönderilen Header
NONE	—	Auth header'ı yok
BEARER_TOKEN	{ token: "..." }	Authorization: Bearer {token}
BASIC_AUTH	{ username: "...", password: "..." }	Authorization: Basic {base64}
API_KEY_HEADER	{ headerName: "X-API-Key", headerValue: "..." }	{headerName}: {headerValue}
API_KEY_QUERY	{ queryName: "api_key", queryValue: "..." }	URL'ye ?{queryName}={queryValue} eklenir

---

Adım 2: KPI Bağlantısı Oluşturma

Bağlantı, belirli bir KPI'yı yanıt eşleme kurallarıyla bir API uç noktasına bağlar.

Gerekli Alanlar

Alan	Açıklama	Örnek
Hedef	Ölçüm alacak KPI Kaydı KPI'ı (kpiType: KPI) veya OKR Anahtar Sonucu (OKR_KEY_RESULT)	(açtığınız KPI'dan otomatik seçilir)
Uç Nokta	Çağrılacak entegrasyon uç noktası	"BI Dashboard API"
Path Eki	Base URL'ye eklenir	/metrics/revenue
Yanıt Eşleme	Değer çıkarmak için JSONPath ifadeleri	Aşağıya bakın
Cron İfadesi	Zamanlama (ör. saatlik, günlük)	0 */6 * * * (her 6 saatte)

Yanıt Eşleme (JSONPath)

Yanıt eşleme, COS'a API yanıtı JSON'ından sayısal değerlerin nasıl çıkarılacağını söyler.

Alan	Açıklama	JSONPath Örneği
actual	Zorunlu. Mevcut metrik değeri	$.value, $.data.metrics.current
target	İsteğe bağlı hedef. Eksik/null/boş değer aynı KPI'ın son hedefini kullanır; açık 0 korunur. Kullanılabilir önceki hedef yoksa 0 kaydedilir.	$.target, $.data.metrics.target
forecast	İsteğe bağlı. Tahmin değeri	$.forecast
statusNote	İsteğe bağlı. Metin notu	$.status

Örnek API Yanıtı:

{
  "metric": "revenue",
  "value": 1250000,
  "target": 1500000,
  "unit": "USD"
}

Yanıt Eşleme:

{
  "actual": "$.value",
  "target": "$.target"
}

Yaygın Formatlar İçin JSONPath Desenleri

API Formatı	actual için JSONPath
Düz: { "value": 42 }	$.value
İç içe: { "data": { "metrics": { "current": 42 } } }	$.data.metrics.current
Dizi (son): { "series": [{ "value": 40 }, { "value": 42 }] }	$.series[-1:].value
İsimli anahtar: { "kpis": { "revenue": { "actual": 42 } } }	$.kpis.revenue.actual
Sayfalanmış: { "results": [{ "measurement": 42 }] }	$.results[0].measurement

---

Adım 3: Test Et ve Aktifleştir

1. Bağlantıyı oluşturduktan sonra doğrulamak için Test (Kuru Çalışma) düğmesine tıklayın:
   • API erişilebilir mi
   • Auth bilgileri geçerli mi
   • JSONPath çıkarma beklenen değerleri döndürüyor mu
2. Test sonucundaki çıkarılan değerleri inceleyin
3. Onaylandıktan sonra bağlantı, tanımlanan cron zamanlamasına göre otomatik çalışacaktır

Çalışma Günlükleri

Her entegrasyon çalışması aşağıdaki bilgilerle bir log kaydı oluşturur:

• HTTP durum kodu
• Yanıt süresi
• Çıkarılan değerler
• Hata mesajı (başarısızsa)
• İstek/yanıt detayları (temizlenmiş)

---

Plan Özellik Limitleri

Özellik Anahtarı	Açıklama	Varsayılan
kpi_api_integration	Pull entegrasyonu etkinleştir/devre dışı bırak	Devre dışı
max_api_integrations	Tenant başına maksimum bağlantı sayısı (-1 = sınırsız)	-1
min_cron_interval_minutes	İzin verilen minimum cron aralığı	60 dk

---

Mock API ile Test

COS, gerçek bir dış sisteme ihtiyaç duymadan entegrasyonları test etmek için yerleşik bir mock API sunar.

Konum: tools/mock-kpi-api/

cd tools/mock-kpi-api && npm install && npm start
# → http://localhost:4444

Mock API, 5 auth türünün tamamını ve çeşitli yanıt formatlarını destekler. Detaylar için Mock API Test Rehberi sayfasına bakın.

---

Bağlama hedefleri ve kurallar

Kırıcı değişiklik (KPI Kaydı)

Bağlamalar artık rapor bazlı KPI kopyalarını değil, iki hedef türünden birini gösterir:

kpiType	Hedef
KPI	KPI Kaydı'ndaki KPI. Çekilen değer, KPI'ı kullanan tüm raporlarda görünür.
OKR_KEY_RESULT	OKR Anahtar Sonucu

Eski aile türleri (THEME_KPI, BSC_KPI, ASIS_KPI, SWOT_KPI, PESTLE_KPI, KPI_DEFINITION, PRODUCT_SCORECARD_KPI) 400 döner. Eski aile bağlamaları kaldırıldı; gerekiyorsa KPI Kaydı'ndaki KPI üzerinde yeniden oluşturun.

• Yetki her çalıştırmada yeniden denetlenir. Zamanlanmış ve elle çalıştırılan pull, bağlamayı oluşturan (veya çekilecek veriyi değiştiren son) kullanıcının yetkisiyle çalışır. Bu kişi yetkisini kaybetmişse ölçüm yazılmaz.
• Bağlamayı değiştirmek veya silmek de hedef üzerinde yetki ister.
• Emekli KPI: KPI emekliye ayrılınca bağlamaları pasifleşir; yeniden etkinleştirmede otomatik açılmaz.
• Ölçüm tarihi (0.5.0): KPI hedefinde ölçüm tarihi, KPI'ın ölçüm sıklığına göre içinde bulunulan dönemin son günüdür (UTC; aylık KPI → ay sonu). Aynı dönemdeki tekrar çalıştırmalar aynı kaydı günceller.
• Anahtar Sonuç (0.5.0): her çalıştırma Anahtar Sonucun "Gerçekleşen" alanını (eşlenmişse hedefi de) günceller; ilerleme elle girişteki gibi hesaplanır. Ayrı ölçüm kaydı eklenmez. Onaylı OKR planında saklı değerden farklı hedef çalıştırmayı başarısız kılar (OKR_LOCKED); gerçekleşen değer güncellenebilir.
• Değer biçimi: çekilen değer sonlu bir sayı veya düz ondalık metin ("44.5") olmalıdır. "N/A", "1,234", "87 %" gibi değerler çalıştırmayı hiçbir şey yazmadan başarısız kılar. Kırılımlı eşlemelerde ağırlık (weights) yolları kaldırıldı.
• Kapalı OKR dönemi: Dönemi CLOSED veya COMPLETED olan Anahtar Sonuç atlanır ve çalışma günlüğüne CYCLE_LOCKED sebebi yazılır.
• Raporların veya plan döneminin kapalı olması aktif KPI'a pull yazımını engellemez.
• Header gizleme: Bağlama yanıtlarında, çalışma günlüklerinde ve tanılama çıktısında yapılandırılmış header değerleri [REDACTED] olarak gösterilir. Düzenleme sırasında [REDACTED] olarak geri gönderilen değer, saklı değeri korur.
• Bağlamaları yalnızca hedef KPI'ı (veya Anahtar Sonucu) görebilen kullanıcılar görür.
• Her pull yazımı KPI'ın Geçmiş sekmesine Pull entegrasyonu kanalı ve Entegrasyon bağlaması yetki yoluyla düşer.

---

Ayrıca bakınız

• Entegrasyonlara Genel Bakış
• Mock API Test Rehberi
• API Genel Bakış
• Kimlik Doğrulama ve Token'lar