Skript-Konsole¶

Die Skript-Konsole führt JavaScript aus, ohne dass ein Formular dazu nötig ist. Sie ist das Werkzeug, um einen Schnipsel auszuprobieren, eine Abfrage zu prüfen oder einmalig Daten zu bereinigen. Sie liegt unter System-Administration → Werkzeuge & Diagnose → Skript-Konsole.

Ein Skript läuft hier mit derselben Skript-API wie ein Formular-Hook: db, mail, log, kc, fs, xml, csv, http, ws, ldap, forms, pdf, view, modules und die übrigen Bindungen sind vorhanden. Was in der Konsole funktioniert, funktioniert also auch im Formular.

Die Konsole arbeitet auf den echten Daten

Es gibt keinen Probelauf. Ein db.update(...) ändert die Datenbank, ein mail.send(...) verschickt eine echte Mail, ein fs[...] schreibt eine echte Datei. Wer die Skript-Konsole öffnen darf, kann damit alles, was ein Administrator kann. Das Recht SCRIPT_CONSOLE gilt deshalb als admin-gleich, siehe Benutzer & Gruppen.

Aufbau¶

Von oben nach unten:

Bereich	Wozu
Werkzeugleiste	durch die gespeicherten Skripte blättern, neu, speichern, löschen, Anlagen
Titel / Beschreibung	Name des Skripts in der Liste. Der Titel ist Pflicht, sobald Sie speichern
Skript-Bibliotheken einbinden	Bibliotheken auswählen, die vor dem Skript geladen werden
JavaScript-Code	der Editor
Test-Daten für `ctx.form`	vier Felder, die das Skript als Formularwerte sieht
Ausführen / Speichern / Zurücksetzen	Knöpfe unter dem Editor; rechts daneben die Laufzeit
Ergebnis	Rückgabe, Protokoll, geänderte Werte, Fehler (siehe unten)
Dateianlagen zum Skript	Dateien, die das Skript als `ctx.attachments` sieht

Über dem Editor steht eine kurze Gedächtnisstütze mit den wichtigsten Bindungen und Schreibweisen.

Ein Skript ausführen¶

Code eintippen und Ausführen klicken oder Ctrl+Enter drücken. Ein Speichern vorher ist nicht nötig.

var n = db.query("SELECT COUNT(*) AS anzahl FROM users")[0].anzahl;
log.info("Benutzer: " + n);
n;

Der Wert der letzten Zeile ist die Rückgabe, hier die Zahl der Benutzer. Ein return gibt es auf oberster Ebene nicht.

Der Editor kennt die üblichen Tasten: Ctrl+F sucht, Ctrl+H sucht und ersetzt, F3 / Shift+F3 springen zum nächsten bzw. vorigen Treffer, Esc schließt die Suche. Ctrl+Z macht rückgängig.

Das Ergebnis lesen¶

Unter den Knöpfen erscheint nach jedem Lauf:

Kasten	Inhalt
Fehler (rot)	die Fehlermeldung, wenn das Skript abgebrochen ist, meist mit Zeilennummer
Rückgabe (grün)	der Wert der letzten Zeile; „(kein Rückgabewert)“, wenn es keinen gibt
Logs (n)	alles, was `log.debug/info/warn/error` geschrieben hat, mit Uhrzeit und Stufe
ctx.form nach Ausführung	die Formularwerte nach dem Lauf, wenn das Skript welche gesetzt hat
ctx.errors	Feldfehler, die das Skript mit `ctx.addError(...)` gemeldet hat
ctx.effects	aufgezeichnete Nebenwirkungen: verschickte Mails und Anweisungen an die Oberfläche (`view.*`), die in der Konsole nicht angezeigt werden

Läuft ein Skript in einen Fehler, zeigt die Konsole trotzdem, was es bis dahin protokolliert und gesetzt hatte. Das hilft, die Stelle einzugrenzen.

Die Protokollzeilen stehen außerdem in script.log, dort mit dem Vorsatz [console], siehe Log-Konfiguration und System-Logs.

Test-Daten¶

Rechts neben dem Editor stehen vier Felder. Das Skript sieht sie als Formularwerte, sowohl über ctx.form als auch in der Kurzschreibweise:

Feld	im Skript	Typ
`ctx.form.text`	`$text`	Text
`ctx.form.number`	`$number`	Zahl; ein Komma wird als Dezimaltrenner gelesen
`ctx.form.date`	`$date`	Datum
`ctx.form.flag`	`$flag`	Ja/Nein

Ein leeres Feld kommt als null an, so wie ein nicht ausgefülltes Feld im Formular. Setzt das Skript einen dieser Werte, etwa $text = "Hallo", erscheint der neue Wert nach dem Lauf in dem Feld. So lässt sich eine Berechnung mehrmals hintereinander ausprobieren.

ctx.formId ist in der Konsole leer, weil kein Formular beteiligt ist. ctx.user ist der angemeldete Benutzer.

Skript-Bibliotheken einbinden¶

Gibt es aktive Skript-Bibliotheken, stehen sie als Knöpfe über dem Editor. Ein Klick wählt eine Bibliothek aus oder ab. Die ausgewählten werden vor dem Skript geladen, ihre Funktionen sind dann im Code verfügbar.

Die Auswahl gilt für die laufende Sitzung in der Konsole und wird nicht mit dem Skript gespeichert. Nach dem Neuladen der Seite wählen Sie sie neu.

Skripte speichern¶

Ein Skript, das Sie öfter brauchen, speichern Sie mit Speichern. Dafür braucht es einen Titel. Gespeichert werden Titel, Beschreibung, Code und die Test-Daten; ist das Skript schon gespeichert, heißt der Knopf Aktualisieren.

Mit der Werkzeugleiste blättern Sie durch die gespeicherten Skripte wie durch Datensätze eines Formulars. Beim Öffnen der Konsole lädt sie das zuletzt angelegte Skript. Neu bzw. Zurücksetzen leert den Editor. Löschen fragt vorher nach.

Gespeicherte Skripte sind gemeinsam

Alle, die die Konsole öffnen dürfen, sehen dieselbe Liste und können jedes Skript ändern oder löschen. Für persönliche Notizen ist sie nicht gedacht, und Zugangsdaten gehören nicht hinein.

Dateianlagen¶

Unten hängen Sie Dateien an das gespeicherte Skript, etwa eine CSV-Datei für einen einmaligen Import. Das Skript sieht sie als ctx.attachments, genau wie ein Formular-Hook:

var datei = ctx.attachments[0];
log.info(datei.filename + ", " + ctx.attachments.length + " Anlage(n)");

Anlagen gibt es erst, wenn das Skript gespeichert ist. Vorher zeigt der Bereich einen Hinweis statt des Upload-Felds. Der Knopf für Anlagen in der Werkzeugleiste springt zu diesem Bereich und zeigt, wie viele Dateien anhängen.

Typische Verwendung¶

Eine Abfrage ausprobieren, bevor sie in einen Lookup oder ein Formular-Skript wandert.
Ein Stück Skript-API kennenlernen: Die Beispiele aus dem Handbuch lassen sich hier einfügen und ausführen.
Einmalige Arbeiten: Datensätze nachbessern, eine Datei einlesen, einen Bericht erzeugen. Speichern Sie solche Skripte mit einer Beschreibung, damit später nachvollziehbar ist, was gelaufen ist.

Zum Weiterlesen: Scripting im Überblick, und für Abfragen ohne JavaScript der DB-Client.