Script API

Script API; diğer script’leri zamanlayıcıya bağlama / çıkarma, anında çalıştırma, durum sorgulama ve script’ler arası veri paylaşmak için kullanılır. Paylaşımlı veri katmanı bellek içi önbellekte tutulur ve proje kapsamlıdır.

Script Meta Verisi ve Durum

ins.getScript(name) / (projectName, name)

Bir script’in tanımını döner — RepeatableScriptResponseDto.

var s = ins.getScript("HourlyReport");
ins.consoleLog(s.getName() + " type=" + s.getType() + " period=" + s.getPeriod() + "ms");

Alanlar:

Metod	Tür	Açıklama
getName() / getDsc()	String	Script adı ve açıklama
getCode()	String	JavaScript kaynak kodu
getType()	ScheduleType	PERIODIC / DAILY / ONCE / NONE
getPeriod()	Integer	Periodic tipi için ms cinsinden periyot
getOffset()	Integer	Periodic için ms cinsinden offset
getDelay()	Integer	Once tipi için gecikme (ms)
getTime()	Date	Daily için tetikleme saati
getLog()	Boolean	Çalıştırma log’u aktif mi
getProjectId()	String	Proje ID

ins.getScriptStatus(name) / (projectName, name)

ScriptStatus enum döner — iki değer:

Değer	Anlam
"Scheduled"	Zamanlayıcıya bağlı
"Not Scheduled"	Bağlı değil (manuel çalıştırılabilir)

if (ins.getScriptStatus("HourlyReport") == "Not Scheduled") {
    ins.scheduleScript("HourlyReport");
}

Script Yönetimi

ins.scheduleScript(name) / (projectName, name)

Script’i tanımındaki ScheduleType’a göre zamanlayıcıya ekler. type=NONE olan script’lere etkisi yoktur.

ins.scheduleScript("HourlyReport");

ins.cancelScript(name) / (projectName, name)

Script’i zamanlayıcıdan çıkarır — kalan tetiklemeler iptal edilir, ama o sırada çalışan bir execution kesilmez (mevcut execution doğal sonuna kadar gider).

ins.cancelScript("HourlyReport");

ins.executeScript(name) / (projectName, name)

Script’i anında çalıştırır ve döndürdüğü değeri döner. Senkron çalışır — script bitene kadar blocker.

var dailyTotal = ins.executeScript("Calculate_DailyTotal");
ins.setVariableValue("DailyProduction_kWh", { value: dailyTotal });

Not

Çağıran ve çağrılan script aynı statement/timeout limitleri altındadır; çağrılan script’in çalışma süresi, çağıranın toplam süresine yazılır. Script yoksa ScriptException fırlar.

Global Object — Script’ler Arası Paylaşım

Script’ler birbirinden izole çalışır (paylaşımlı memory yoktur). Bunu aşmak için setGlobalObject / getGlobalObject ikilisi, bellek içi önbellekte duran bir anahtar-değer deposu sunar. Anahtarlar proje kapsamlıdır: aynı adı iki ayrı projede kullanmak iki ayrı nesne demektir, birbirlerini görmezler.

ins.setGlobalObject(name, object)

Objeyi süresiz (TTL yok) saklar.

ins.setGlobalObject("daily_counter", 42);
ins.setGlobalObject("shift_data", {
    shift: "A",
    count: 150,
    startTime: ins.now().toString()
});

ins.setGlobalObject(name, object, ms)

Nesneyi yaşam süresiyle saklar — ms milisaniye sonra kendiliğinden silinir.

// 60 saniye sonra silinecek cache
ins.setGlobalObject("temp_cache", { value: 99 }, 60000);

ins.getGlobalObject(name)

Objeyi döner; yoksa null. TTL’e dokunmaz.

var counter = ins.getGlobalObject("daily_counter");
// → 42 veya null

ins.getGlobalObject(name, ms)

Nesneyi döndürür ve aynı anda yaşam süresini ms’e sıfırlar (kayan süre). Tipik kullanım: “her okuma nesneyi canlı tutsun”.

// Oturum gibi davranan veri: her okuma 5 dk canlılık ekler
var session = ins.getGlobalObject("user_session", 5 * 60 * 1000);

Not

Objeler JSON olarak serileşir. Date → string’e dönüşür, fonksiyonlar / class instance’ları kaybolur. Yalnızca plain objeler, diziler, sayılar, string’ler, boolean’lar güvenlidir.

Not

Global nesneler bellek içi önbellekte paylaşıldığı için çoklu node kurulumda her node’dan görünür. Yeniden başlatmada ne olacağı, o önbelleğin kalıcılık ayarına bağlıdır.

Kullanım Kalıpları

Backend → UI Veri Aktarımı

// Backend script (her 10 sn):
function main() {
    ins.setGlobalObject("dashboard_summary", {
        power:   ins.getVariableValue("ActivePower_kW").value,
        voltage: ins.getVariableValue("Voltage_V").value,
        updatedAt: ins.now().getTime()
    }, 30000);   // 30 sn TTL — veri "stale" olmasın
}
main();

UI tarafındaki custom HTML widget, client-side Inscada.* ile aynı anahtara okuma yapabilir.

Rate Limiting

function main() {
    var last = ins.getGlobalObject("report_last_run");
    var now  = ins.now().getTime();

    if (last && (now - last) < 3600000) {
        ins.consoleLog("1 saat dolmadı, atla");
        return;
    }

    ins.executeScript("generate_hourly_report");
    ins.setGlobalObject("report_last_run", now);
}
main();

Bayrak / Mutex

function main() {
    if (ins.getGlobalObject("maintenance_mode")) {
        ins.consoleLog("Bakım modu, script atlandı");
        return;
    }
    // normal iş...
}
main();