Grundlagen von JavaScript in agorum core

Diese Dokumentation enthält allgemeine Hintergrundinformationen zur Verwendung von JavaScript in agorum core.

JavaScript in agorum core

agorum core führt JavaScript in der Regel serverseitig aus. Das hat etwa folgende Auswirkungen:

• Kein Browser-Kontext
• Globaler Kontext und Modulsystem: Die Verfügbarkeit globaler Hilfsobjekte (z. B. sc, sca) ist vom Ausführungskontext abhängig, siehe Erste Zeile eines JavaScripts. Bibliotheken werden über require(...) eingebunden.
• Kompatibilität: Nicht jede moderne JavaScript-Syntax ist verfügbar. Halten Sie sich an die in agorum core vorgesehenen Patterns.

Aufbau eines Skripts (Einsteiger)

Ein typisches agorum core Skript folgt einer klaren Struktur:

1. Benötigte Bibliotheken am Anfang des Skripts laden (require).
2. Funktionen definieren (möglichst klein und gut benannt).
3. Hauptlogik ausführen und Fehler behandeln.

Objekt‑ID (Objekte eindeutig referenzieren)

In der agorum core JavaScript API müssen Objekte häufig über eine Kennung referenziert werden (z. B. beim Laden, Verknüpfen, Verschieben oder beim Zugriff auf Inhalte/Metadaten).
In dieser Dokumentation verwenden wir dafür den Begriff Objekt‑ID als Sammelbegriff für alle von agorum core akzeptierten Objektkennungen.

• Objekt‑ID: Oberbegriff für die unterstützten Identifikationsformate (z. B. UUID, weitere von agorum core akzeptierte Objekt-Referenzen je nach API-Funktion).
• Numerische ID: Wird explizit verwendet, wenn eine reine Zahl gemeint ist, z. B. 12345.

Formate einer Objekt-ID

Typische Formate einer Objekt‑ID sind:

• ID (z. B. 12345) – eindeutige Kennung.
• UUID (z. B. 714f1580-ce62-11e0-b47a-0800276e2399) – eindeutige, systemweit stabile Kennung.
• Pfadbasierte Referenzen (z. B. /agorum/...) – werden in einigen Kontexten verwendet bzw. in technische IDs aufgelöst (je nach Funktion).
• Kontext-/Alias-Referenzen (z. B. home:..., user:...) – werden von agorum core kontextabhängig aufgelöst.

Debugging & Logging

Für produktive, nachvollziehbare Protokollierung (z. B. mit Severity-Level, Details, Sticky-Einträgen) sollten Sie das strukturierte Logging über agorum.dev/js/lib/logger verwenden. Für die schnelle Diagnose während der Entwicklung können Sie zudem Ausgaben über console.* erzeugen. Die Log-Ausgaben erscheinen in den System-Logs (Support Tool) sowie, je nach Kontext, in der Skript-Konsole, in der Browser-Konsole oder im Workflow-Protokoll.

Debug-Ausgaben mit console

Verwenden Sie console, um während der Ausführung Werte und Statusinformationen auszugeben (z. B. beim Debugging, bei der Entwicklung oder zur Nachvollziehbarkeit von Skriptabläufen).

Die folgenden Funktionen stehen zur Verfügung:

Funktion	Verwendung (kurz)
console.debug()	Detaillierte Debug-Ausgaben für Diagnosezwecke (z. B. Zwischenschritte, interne Zustände). Das Debugging muss dafür zunächst im Support Tool durch Setzen des Log-Levels Debug unter Base System > Sub Statistics > Engine Factory aktiviert werden, siehe Schaltflächen im Log.
console.info()	Allgemeine Status-/Info-Meldungen (z. B. „Import gestartet“, „Verarbeitung abgeschlossen“).
console.log()	Standardausgabe für Debugging/Entwicklung (allgemeine Ausgaben ohne spezielles Level).
console.warn()	Warnungen bei unerwarteten, aber nicht unbedingt fatalen Situationen (z. B. fehlende optionale Daten, Fallback wird genutzt).
console.error()	Fehlerausgaben für fehlgeschlagene Operationen (z. B. Exception im catch).
console.assert(condition, )	Prüft eine Bedingung und loggt nur, wenn sie false ist (hilfreich für Annahmen/Invariant-Prüfungen).
console.trace()	Gibt zusätzlich einen Stacktrace aus (hilfreich, um Aufrufketten zu verstehen).
console.clear()	Leert die Ausgabe

Beispielverwendung

console.debug('test debug');
console.info('test info');
console.log('test log');
console.warn('test warn');
console.error('test error');
console.assert(false, 'test assert');
console.trace('test trace');
// console.clear();

console;

//returns:
/*
{
  "warn" : { },
  "trace" : { },
  "debug" : { },
  "log" : { },
  "assert" : { },
  "_aguila" : true,
  "clear" : { },
  "error" : { },
  "info" : { }
}
*/

Produktives Logging

Für produktive Systeme (Monitoring, Auditing, Troubleshooting) sollten Sie nicht auf Browser-Ausgaben setzen, sondern ein strukturiertes Logging verwenden. agorum core stellt dafür eine eigene Bibliothek bereit: agorum.dev/js/lib/logger