Script

Script ist ein deklarativer Backend-Endpunkt, den ein Frontend über HTTP aufruft. Statt Servercode zu schreiben, deklarieren Sie in JSON, "was zu tun ist", und die WEEGLOO-Engine führt es für Sie aus. Ziel ist es, mit einem einzigen Script die typische Backend-Verdrahtung zu ersetzen, die ein Frontend stützt (ein BFF, Backend-for-Frontend): Authentifizierung, Bedingungsprüfungen (Guards), verkettete CRUD-Operationen, Aufrufe externer APIs und die Aufbereitung von Werten.

Dieser Dokumentsatz ist die Referenz für die Script-Syntax. Die Details der einzelnen Syntaxbestandteile werden unten in Dokumente dieser Gruppe getrennt behandelt.

Script wird auf der CMA erstellt und ausgeführt (mit der Weegloo-User-Identität). Unter der Identität eines Mitglieds, das sich für das Produkt registriert hat (ein ServiceUser), können Sie es auf die gleiche Weise auch auf der ACMA verwenden. Die Script-API gibt es nur auf diesen beiden Management-APIs (CMA, ACMA); auf den schreibgeschützten Delivery-APIs (CDA, ACDA) gibt es sie nicht.

Mentales Modell

• Ein Script ist ein HTTP-Endpunkt. Über die Aufrufmethode (method) wird abgeglichen, welches Script ausgeführt wird.
• Der Rumpf ist ein statements-Array. Es wird sequenziell von oben nach unten ausgeführt. Das ist wie der Rumpf einer Funktion in der gewöhnlichen Programmierung.
• Es ist Deklaration, nicht Code. Sie betten keinen beliebigen Code (FaaS) ein, sondern kombinieren vordefinierte Statement-Typen. Es ist weniger für das manuelle Verfassen durch einen Menschen ausgelegt als für die Generierung durch einen AI-Agenten über MCP.
• Werte fließen durch JSON-Pointer-Vorlagen. Sie referenzieren das Ergebnis eines vorherigen Schritts, den eingehenden payload oder eine Variable mit { /pointer } und geben es an den nächsten Schritt weiter. Wenn Sie eine Bedingung oder eine Berechnung benötigen, verwenden Sie JsonLogic-Operatoren. Die ausführlichen Regeln werden in Wertausdrücke behandelt.

Struktur der obersten Ebene (ScriptDefinition)

Ein einzelnes Script wird mit der folgenden ScriptDefinition-Struktur definiert.

{
  "method": "Post",               // Get | Post | Put | Patch | Delete. Beim Aufruf abgeglichene HTTP-Methode (erforderlich)
  "payloadSchema": { /* ... */ }, // (optional) JSON Schema. Falls vorhanden, wird der Request-payload vor der Ausführung validiert
  "executionMode": "Sync",        // "Sync" | "Async" (erforderlich)
  "statements": [ /* Statement[]. Von oben nach unten ausgeführt (erforderlich, mindestens 1) */ ]
}

Der payload akzeptiert nur JSON. Auf den Aufruf-Body wird über die Kontextwurzel /payload zugegriffen ({ /payload/... }). Die HTTP-Header der Anfrage werden über die Wurzel /headers referenziert ({ /headers/... }, Schlüssel in Kleinbuchstaben). Die vollständige Menge der Kontextwurzeln wird in Wertausdrücke behandelt.

Anfrage und Antwort

Ein Script gibt letztlich den Wert seines Return-Statements an den Aufrufer zurück. Die Form der Antwort (oder des Async-Polling-Ergebnisses) sieht wie folgt aus.

{
  "requestId": "…",     // Ausführungskennung (bei Async wird das Ergebnis mit dieser id per Polling abgerufen)
  "durationMs": 1234,   // Ausführungsdauer (ms)
  "statusCode": 200,    // statusCode des erreichten Return (Standard 200)
  "return": <value>     // Nur wenn Return.isError false ist. Ist der Wert null, dann ""
  // "error": <value>   // Nur wenn Return.isError true ist (dann fehlt "return"). Ist der Wert null, dann ""
}

• return und error erscheinen nie zusammen. Das isError des Return-Statements entscheidet, welches von beiden es ist.
• Wenn das Script endet, ohne ein Return-Statement zu erreichen, fehlen return und error beide, und statusCode ist der Standardwert (200).
• Ist ein Wert null, wird das betreffende Feld als leerer String "" ausgegeben.

Mit value, isError und statusCode des Return steuern Sie den Antwort-Body und den Statuscode. Details werden in Return im Statement-Katalog behandelt.

Ausführungsmodi: Sync und Async

• Gibt es externe I/O, ist nur Async erlaubt. Wenn irgendein Statement eine netzwerkgebundene Operation ausführt, etwa einen externen Http-Aufruf (ExternalIo) oder einen Media-Datei-Ingest (MediaIngest, aus url oder base64), muss executionMode zwingend Async sein; der Versuch, es als Sync zu speichern, wird zum Speicherzeitpunkt abgelehnt. So wird verhindert, dass der Request-Thread durch externe Latenz blockiert wird.
• Es ist nur ein Unterschied im Ausführungsort; in beiden Fällen ist das Ergebnis der Return-Wert.

Die ausführlichen Regeln, wie eine Fähigkeit einen Modus erzwingt, samt der geltenden Grenzwerte, werden in Ausführungssemantik, Beschränkungen und Sicherheit behandelt.

Minimales Beispiel

Erstellt aus Titel und Text im Request-payload einen Beitrags-Content, veröffentlicht ihn sofort und gibt anschließend die erzeugte sys.id zurück.

{
  "method": "Post",
  "executionMode": "Sync",
  "statements": [
    { "type": "ResourceCreate", "resource": "Content",
      "contentType": { "sys": { "id": "ct_post" } },
      "fields": {
        "title": { "en-US": "{ /payload/fields/title }" },
        "body":  { "en-US": "{ /payload/fields/body }" }
      },
      "publish": true,
      "name": "post" },
 
    { "type": "Return", "value": { "id": "{ /post/sys/id }" }, "statusCode": 201 }
  ]
}

• ResourceCreate erstellt den Content und bindet das Ergebnis an den Namen post.
• Return gibt { "id": <neue Content-id> } mit 201 zurück.
• Warum die fields-Werte in einem Content Locale-Maps sind ({ "en-US": ... }), wird in Locale-Maps in den Wertausdrücken behandelt.

Weitere, vielfältigere Szenarien finden Sie im Cookbook.

Dokumente dieser Gruppe

• Wertausdrücke: Behandelt { /pointer }-Referenzen, Literale, JsonLogic-Operationen und -Bedingungen, Kontextwurzeln und Locale-Maps. Das ist der Kern der Syntax.
• Statement-Katalog: Behandelt die Felder und Ergebnisse der 17 Statement-Typen (Ressourcen-CRUD und -Lesen, Http, SetVar, If, Loop, Parallel, Try, Return).
• Ausführungssemantik, Beschränkungen und Sicherheit: Behandelt Ausführungsreihenfolge, Guards, Kompensation, optimistisches Sperren, Fehler, statische Beschränkungen und Plan-Grenzwerte sowie das Sicherheitsmodell.
• Cookbook: Behandelt vollständige Beispiele wie upsert, einen Credit-Guard, einen LLM-Proxy, Paginierung, Parallelität und eine Zahlungs-Saga.
• Script-Ressource und Endpunkte: Behandelt die sys-Struktur der Script-Ressource sowie die Spezifikation der HTTP-Endpunkte für Erstellung und Ausführung (/execute).

Wenn dies Ihr erstes Mal ist, empfehlen wir, ab dieser Seite in der Reihenfolge Wertausdrücke, dann Statement-Katalog zu lesen. Das Cookbook können Sie auch komplett durchsehen.