1Otto-Engine und ES5.1-Sandbox

Die ScriptEngine basiert auf der Otto-JavaScript-Engine und unterstützt ECMAScript 5.1. Sie läuft als Sandbox ohne Dateisystem- oder Netz-IO außerhalb der eingebauten Module. (PH Einführung; AH 7.2)

Du schreibst keine vollständige Datei, sondern nur den Rumpf einer Funktion. Die Plattform legt einen künstlichen Funktionskopf um deinen Code und ruft ihn mit den übergebenen Parametern auf.

In Klartext: Dein Code läuft in einer abgeschotteten Mini-JavaScript-Umgebung — kein Internet- oder Dateizugriff außer über die freigegebenen Module. Du schreibst nur den Inhalt der Funktion; den Rahmen drumherum setzt AuxData automatisch.

2Funktionssignatur & String-Konvertierung

Die Plattform umschließt deinen Code etwa so — du lieferst nur den markierten Rumpf:

// Künstlicher Kopf der Plattform (nur zur Veranschaulichung):
function executorFunctionWrapper(parameter1, parameter2) {

  // ── ab hier schreibst du den Rumpf ──
  // Wichtig: ALLE Parameter kommen als String an!
  var summe = parseInt(parameter1) + parseInt(parameter2); // numerisch
  return String(summe); // Rückgabe wird als String erwartet

}

Der Rückgabewert wird als String erwartet. Ohne return oder bei einem Abbruch im Fehlerfall ist der Rückgabewert undefined.

1Was ES5.1 unterstützt

Unterstützt sind var (kein let/const), die Typen String/Number/Boolean/Array/Object/null/undefined, die üblichen Operatoren, if/else, for, while, JSON.stringify/JSON.parse sowie eingebaute String-/Array-/Math-/Date-Funktionen. (PH ECMAScript-5.1-Referenz)

var namen = ["Anna", "Ben"];   // Array mit []
namen.push("Carla");           // mit push füllen

var antwort = "";
for (var i = 0; i < namen.length; i++) {
  if (namen[i] === "Ben") {    // strenge Gleichheit
    antwort = "gefunden";
  }
}

var daten = JSON.parse('{"ok": true}'); // String -> Objekt
var text  = JSON.stringify(daten);      // Objekt -> String

2Nicht unterstützt (ES6+)

Diese Konstrukte laufen in Otto nicht: let/const, Arrow-Funktionen, Template-Strings, Destructuring, Spread, class, Promise, async/await.

Häufige Fehler: var nicht vergessen (sonst entsteht eine globale Variable); konsequent strenge Gleichheit (===) verwenden; Arrays als [] anlegen und mit push füllen.

1Module initialisieren

Jedes Modul wird zuerst mit getModule("modulname") initialisiert; danach stehen seine Funktionen als globale Namen bereit. (PH Module; AH 7.2)

getModule("log");
getModule("http");

log_info("Modul http bereit");
var antwort = http_get("https://api.example.com/v1/data", {});

2Wichtige Module & exakte Signaturen

http

http_get(url, header), http_post(url, contentType, header, body), http_put(url, contentType, header, body), http_delete(url, header), http_queryEscape(value), http_search(search, exactMatch).

graphapi

graphapi_getResource(graphApiConfig, url), graphapi_postResource(graphApiConfig, url, body), graphapi_putResource(graphApiConfig, url, body), graphapi_deleteResource(graphApiConfig, url), graphapi_send(graphApiConfig, mail), graphapi_getNewFromInbox(graphApiConfig, maxCount).

aiservice

aiservice_run(agentId, serviceId, params), aiservice_runAsync(agentId, serviceId, params), aiservice_runWithToken(token, agentId, serviceId, params); Ergebnis über resultObj.MultiResults.Results[0].Result.

knowledgedb

saveText(agentId, containerId, name, content, documentId), saveBinary(agentId, containerId, name, content, documentId), find(searchText, agentId, containerId, qualityGate, resultLimit), findByKeyword(searchText, agentId, containerId, resultLimit).

personalknowledgedb

Lese-/Schreibzugriff auf die persönliche Wissens-DB des ausführenden Users — ohne Agent-/Container-Parameter.

sql

sql_execute(connectionConfig, sqlCommand), sql_query(connectionConfig, sqlCommand).

email

send(mail, smtpConfig), getNewFromInbox(imapConfig), getByCriteria(imapConfig, criteria), move(mailId, originFolder, destinationFolder, imapConfig).

document

document_readText(agentId, filename, filecontent, readImages).

user

user_getUser().

organisation

organisation_getOrganisation() — liefert u. a. ADConfig (MsGraphTenantId/ClientId/ClientSecret) und TeamsBotConfig; ideal, um graphApiConfig direkt aus der Org zu bauen statt aus Umgebungsvariablen.

log

log_info(message), log_warn(message), log_error(message), log_fatal(message), log_logs().

weitere

webcrawler_crawlWeb(url), webcrawler_crawlWebEnhanced(url, depth, pageCount) (max. Tiefe 3, 10 Seiten), webcrawler_liveSearch(prompt, maxPages, searchMode); docdb_load(documentId), docdb_save(documentId, document), docdb_delete(documentId).

1Org- vs. Funktions-Variablen

Umgebungsvariablen halten Werte aus dem Code heraus, die keine Funktionsparameter sind (typisch: API-Tokens). Du setzt sie an der Organisation (gelten für jeden Funktionsaufruf) oder an der Funktion. (PH Umgebungsvariablen; AH 7.1/7.2)

Bei Namensgleichheit überschreibt die Organisation die Funktion. Beim Export einer Funktion wandern die Variablen-Deklarationen, aber nicht die Werte mit — so geraten keine Secrets in eine fremde Organisation. Vordefiniert ist timeout (Sekunden; nur an der Funktion wirksam, an der Organisation ignoriert; Default 600 s).

2Zugriff in der Funktion vs. im HTTP-Service

In der Funktion steht eine Umgebungsvariable als globaler Name bereit:

// Umgebungsvariable "api_token" steht als globaler Name bereit:
var apiKey = api_token;

// niemals hart codieren, niemals ins Log schreiben!
log_info("API-Aufruf vorbereitet"); // ok
// log_info("Token: " + api_token);  // FALSCH: Secret im Log

1Der Editor und seine Reiter

Der HTTP-Service ist ein vordefinierter REST-Aufruf, gepflegt auf Organisationsebene (Org-Admin+). Editor httpserviceeditor.html mit den Reitern Stammdaten, Anfrage, Parameter und Umgebungsvariablen. (AH 7.1)

Parameter (Name, Beschreibung, Default, Pflichtfeld) werden vom Aufrufer bzw. Workflow-Schritt gefüllt und im Body als ${parameter} referenziert. Umgebungsvariablen sind ein separater Schlüssel-Wert-Speicher für Secrets und produktionsabhängige URLs; sie lassen sich über ${env.NAME} in der Anfrage referenzieren und werden verschlüsselt in http_request.env gespeichert. Die eigene Testseite führt einen Probe-Aufruf aus und zeigt Request, Response, Status und Parsing-Ergebnis.

1Die Demo-Funktion zusammengesetzt

Wir setzen die Demo-Funktion vollständig zusammen, nach dem Muster aus dem PH-Tutorial „Erste Funktion erstellen". (PH Code-Beispiele; AH 7.2)

// Module einmal am Anfang initialisieren
getModule("log");
getModule("http");

// Aufruf protokollieren (keine Rohdaten, keine Secrets)
log_info("Funktion aufgerufen; Parameter name erhalten");

// 1) Parameter validieren
if (!name || typeof name !== "string" || name.trim() === "") {
  log_warn("Ungültiger Parameter: name fehlt oder ist leer");
  return "FEHLER: Parameter 'name' fehlt oder ist leer.";
}

var cleanName = name.trim();

// 2) Pflicht-Secret prüfen, ohne den Wert zu loggen
if (!api_token || typeof api_token !== "string" || api_token.trim() === "") {
  log_error("Umgebungsvariable api_token fehlt");
  return "FEHLER: API-Konfiguration fehlt.";
}

var cleanApiToken = api_token.trim();

// 3) HTTP-Aufruf im try-Block
try {
  var header = {};
  header["Authorization"] = "Bearer " + cleanApiToken; // aus Umgebungsvariable
  header["Content-Type"]  = "application/json";

  // URL-Bestandteile mit dem HTTP-Modul absichern
  var sicher = http_queryEscape(cleanName);
  var url = "https://api.example.com/v1/greeting?name=" + sicher;

  var response = http_get(url, header);
  log_info("HTTP-Antwort erhalten");
  return "Hallo " + cleanName + "! Antwort: " + response;

} catch (error) {
  // 4) Fehlerpfad: immer ein definierter String
  log_error("HTTP-Anfrage fehlgeschlagen: " + error);
  return "Hallo " + cleanName + "! Willkommen in der ScriptEngine.";
}

Die Funktion gibt über jeden Pfad — Eingabevalidierung, Secret-Prüfung, Erfolg, Fehler — immer einen definierten String zurück. Sie loggt keinen Token-Wert, nutzt den getrimmten Namen nur einmal und escaped URL-Bestandteile mit der vom HTTP-Modul bereitgestellten Funktion.

1Best Practices

Sieben Regeln aus dem Programmierhandbuch, die jede Funktion produktionsreif machen. (PH Best Practices)

Fehlerbehandlung

immer try/catch + log_error.

Logging

großzügig log_info, aber keine Passwörter/Tokens loggen.

Module

nur einmal am Anfang initialisieren.

Validierung

Parameter prüfen mit typeof, isNaN, trim.

Struktur

Funktionen klein halten und in Teilfunktionen zerlegen.

Secrets

sensible Daten in Umgebungsvariablen statt Hartkodierung.

AI-Ergebnisse

vor dem Zugriff prüfen: if (result && result.MultiResults && result.MultiResults.Results.length > 0).

2Sicherheit (AH 7.2)

HTTP-Calls werden gegen die URL-Whitelist geprüft; SQL nur für Admins; die Otto-Sandbox erlaubt kein Dateisystem-/Netz-IO außerhalb der Module. SQL- und HTML-Injection entschärfst du durch Escapen:

// einfache SQL-Escape-Hilfe (Demo): einfache Quotes verdoppeln
var sicher = eingabe.replace(/'/g, "''");

// Logging-Disziplin: Benutzer ja, Passwort niemals
log_info("Login-Versuch für Benutzer: " + benutzername); // erlaubt
// log_info("Passwort: " + passwort);                      // VERBOTEN