Workflows anpassen und programmieren

Ein Skript ist ein Schritt im Workflow-Designer, der Code ausführt: Es liest das Dokument und den Workflow, rechnet, entscheidet über den Ausgang des Schritts und setzt Felder, Schlagwörter, Akten, Hinweise und Benachrichtigungen. Sie schreiben es in TypeScript oder in reinem JavaScript, mit Vervollständigung für die Dokumenttypen und Felder Ihres Arbeitsbereichs. Skripte gehören zum Add-on Workflow-Designer und brauchen dasselbe Recht wie der Designer.

Diese Seite erklärt die Begriffe, führt durch Ihr erstes Skript und beschreibt den Editor. Jede Funktion des SDK steht in der API-Referenz, jede Meldung der Prüfung unter Skripte: Fehler beheben.

Die Begriffe

Workflows, Versionen und Entwürfe

Ein Skript gehört zu einem Workflow wie seine anderen Schritte. Sie bearbeiten es im Entwurf des Workflows, und erst Veröffentlichen macht es wirksam (Veröffentlichen und Versionen):

Beim Veröffentlichen prüft Acriva jedes Skript des Entwurfs noch einmal auf dem Server und friert es mit der Version ein. Ein Skript mit einem Fehler verhindert das Veröffentlichen, gleich was der Editor vorher zeigte.
Eine veröffentlichte Version ändert sich nie. Laufende Workflows bleiben bei den Skripten der Version, mit der sie gestartet sind.
Ein neuer Entwurf beginnt mit den Skripten der veröffentlichten Version, so wie er mit ihren Schritten beginnt. Eine Kopie eines Workflows übernimmt seine Skripte ebenso.
Als Entwurf übernehmen unter Versionen nimmt die Skripte dieser Version mit ihren Schritten mit. Die Skripte von Schritten, die die Version nicht hat, verlassen den Entwurf; Rückgängig bringt diese Schritte und ihre Skripte zurück, ein Skript, das die Version ersetzt hat, behält aber den Code der Version.
Alle Skripte einer Version verwenden dieselbe Version des SDK.

Der Skript-Schritt

Den Schritt Skript ziehen Sie aus dem Bereich Schritte auf die Arbeitsfläche. Er nennt:

die Datei, etwa kostenstelle.ts: Kleinbuchstaben, Ziffern und Bindestriche, am Anfang ein Buchstabe oder eine Ziffer, höchstens 63 Zeichen vor der Endung .ts. Ein Workflow hat höchstens 20 Skript-Schritte;
den Hook: wann das Skript läuft und was es darf (unten);
die Eingaben: die Felder des Dokuments, die das Skript liest. Ein Skript sieht nur die Felder, die sein Schritt als Eingabe nennt, und nie den Text des Dokuments;
die Rückgaben: benannte Werte mit einem Typ (Text, Zahl, Betrag, Datum, Ja/Nein, Verweis oder eine feste Auswahl), die spätere Bedingungen lesen. Sie kommen aus outputs im Code;
die Ausgänge: Ist eine Rückgabe eine feste Auswahl, wird jeder ihrer Werte ein Ausgang des Schritts. Gibt das Skript keinen zurück, geht der Workflow zum Standard-Nachfolger. Scheitert das Skript, geht er zum Ausgang für Fehler, wenn der Schritt einen hat, sonst ebenfalls zum Standard-Nachfolger. Der Workflow läuft in beiden Fällen weiter.

Hooks

Der Hook legt fest, wann ein Skript läuft und welche Änderungen es vornehmen darf.

Hook	Wann	Was das Skript ändern darf
`onDocumentArrived`	sobald ein Dokument eingegangen und erkannt ist, vor dem ersten Schritt	alles: Felder, Schlagwörter, Akten, Benachrichtigungen, Hinweise, den Ausgang
`beforeApproval`	vor einer Freigabe oder Prüfung	nur einen Hinweis an diese Aufgabe; es liest sonst nur
`onApproved`	nach einer Freigabe	alles, aber nur Felder, die leer sind und die der Workflow deklariert
`onRejected`	nach einer Zurückweisung	alles
`onTimer`	nach einer Frist oder einem Zeitplan	alles; nach einer Freigabe Felder nur, wenn sie leer und deklariert sind

Ein Skript setzt nie die Felder, die Finanzen für eine Eingangsrechnung liest (etwa Beträge und Lieferant), denn sonst änderte es eine Rechnung, die schon geprüft oder freigegeben ist.

Die Sandbox und ihre Grenzen

Ein Skript läuft in einer abgeschotteten Umgebung ohne Netzwerk, ohne Dateien und ohne Zugriff auf andere Arbeitsbereiche. Es sammelt seine Änderungen nur: Acriva prüft sie nach dem Lauf und wendet sie dann als der Workflow an. Für jeden Lauf gelten diese Grenzen:

Grenze	Wert
Rechenzeit	2 Sekunden (das Warten auf eine Datenquelle zählt nicht)
Gesamtdauer eines Laufs	45 Sekunden, das Warten auf einen freien Platz eingeschlossen
Speicher	64 MB
Rückgaben, Änderungen und Ausgang zusammen	256 KB
Konsole	1.000 Zeilen oder 64 KB; eine längere Zeile wird nach 1.000 Zeichen abgeschnitten
Änderungen	höchstens 100 je Lauf, davon höchstens 5 Benachrichtigungen an je höchstens 20 Empfängerinnen und Empfänger
Texte	ein Hinweis höchstens 500 Zeichen, eine Benachrichtigung höchstens 1.000, ein Textfeld oder eine Text-Rückgabe höchstens 1.000
Datenquellen	10 Aufrufe je Lauf, jeder höchstens 5 Sekunden, zusammen höchstens 30 Sekunden
Datentabellen	50 Abfragen je Lauf
Reguläre Ausdrücke	250 Millisekunden je Ausdruck
Größe eines Skripts	64 KB
Gleichzeitige Läufe	20 je Arbeitsbereich

Was bei einer überschrittenen Grenze passiert, steht unter Grenzen überschritten.

Was ein Skript darf und was nicht

Ein Skript darf:

die Felder lesen, die sein Schritt als Eingabe nennt, dazu den Dokumenttyp, die Schlagwörter, die Akten des Dokuments und den Schritt und das letzte Ergebnis einer Aufgabe im Workflow (ctx.document, ctx.instance);
die Uhrzeit des Laufs, den heutigen Tag in Deutschland und eine Zufallszahl abfragen (ctx.now(), ctx.today(), ctx.random());
Zeilen in die Konsole schreiben (ctx.log);
je nach Hook Felder setzen, vorhandene Schlagwörter hinzufügen, das Dokument in einer Akte ablegen, Mitglieder oder Rollen benachrichtigen und einen Hinweis an die nächste Aufgabe hängen;
Datenquellen und Datentabellen lesen, die Ihr Arbeitsbereich eingerichtet hat und die sein Schritt als Eingabe nennt (ctx.sources, ctx.tables). Eine Datentabelle liefert eine Zeile zu ihrem Schlüssel (lookup) oder bis zu 100 Zeilen, die in bis zu drei Spalten übereinstimmen (query), höchstens 50-mal je Lauf. Ein abgelehnter Aufruf erreicht das Skript als Error, den es abfangen kann; eine Datentabelle, die der Schritt nicht nennt, beendet den Lauf mit table-not-declared (siehe Grenzen überschritten).

Ein Skript darf nicht:

ins Netzwerk gehen (fetch, XMLHttpRequest, WebSocket): Externe Daten liest es über eine Datenquelle;
Code zur Laufzeit erzeugen (eval, Function), Module laden (require, import()) oder etwas anderes importieren als '@acriva/workflow-sdk';
warten (setTimeout, setInterval): Ein Workflow wartet mit einem Zeitgeber-Schritt;
Date.now() oder Math.random() verwenden, die in der Sandbox fehlen: Nehmen Sie ctx.now() und ctx.random();
eine freie E-Mail-Adresse benachrichtigen: nur Mitglieder per E-Mail-Adresse und Rollen;
eine Aufgabe erledigen oder etwas freigeben. Eine Freigabe trifft immer ein Mensch.

Die Prüfung meldet die meisten dieser Fälle schon im Editor, jeden mit einem eigenen Code; Date.now() und Math.random() scheitern erst im Lauf.

Sicherheit und Nachvollziehbarkeit

Der Server entscheidet. Was der Editor im Browser prüft, ist eine Hilfe. Beim Veröffentlichen prüft Acriva jedes Skript selbst; ausgeführt wird nur das eingefrorene, geprüfte Skript der Version.
Jeder Lauf steht im Verlauf. Jeder Lauf eines Skripts erscheint im Protokoll des Dokuments als Skript eines Workflows ausgeführt, mit seinem Ergebnis und bei einem Fehler mit dessen Code. Die Werte eines Laufs (seine Eingaben, Rückgaben, Änderungen und seine Konsole) löscht Acriva 90 Tage nach dem Ende des Workflows; das Ergebnis und der Code bleiben.
Änderungen als der Workflow. Was ein Skript ändert, ändert der Workflow, und es steht im Verlauf des Dokuments wie jede andere Änderung eines Workflows. Ein Skript bekommt nie mehr Rechte, als der Workflow hat.
Ein Skript, das die Sandbox dreimal zum Absturz bringt, sperrt Acriva für Ihren Arbeitsbereich, bis Sie das Skript ändern und eine neue Version veröffentlichen.

Ihr erstes Skript in 5 Minuten

Das Beispiel leitet eine Eingangsrechnung je nach Bruttobetrag an die Geschäftsführung oder an die Kostenstelle und gibt der Freigabe einen Hinweis mit.

Öffnen Sie unter Einstellungen › Workflows einen eigenen Workflow für Eingangsrechnungen im Designer, oder legen Sie einen an (Einen Workflow anlegen).
Ziehen Sie Skript aus dem Bereich Schritte hinter den Eingang.
Nennen Sie die Datei weg.ts, wählen Sie den Hook onDocumentArrived, und fügen Sie unter Eingaben das Feld des Bruttobetrags hinzu.
Die Rückgabe weg, eine feste Auswahl mit den Werten gf und kostenstelle, kommt aus outputs im Code unten. Der Schritt übernimmt sie und bekommt dadurch zwei Ausgänge.

Schreiben Sie den Code:

import { defineScript, money } from '@acriva/workflow-sdk';

export default defineScript({
  hook: 'onDocumentArrived',
  outputs: { weg: ['gf', 'kostenstelle'] },
  run(ctx) {
    const betrag = ctx.document.fields.totalGross;
    if (betrag == null) return; // ohne Betrag zum Standard-Nachfolger
    ctx.log('Bruttobetrag', money.format(betrag));
    if (betrag > 500) {
      ctx.hint('Über 500 €: Die Geschäftsführung gibt frei.');
      return ctx.branch('gf');
    }
    return ctx.branch('kostenstelle');
  },
});

totalGross ist der Schlüssel des Felds Bruttobetrag der Eingangsrechnung; der Editor schlägt die Felder vor, die der Schritt als Eingaben liest, sobald Sie ctx.document.fields. tippen. Ein Feld, das nicht Pflicht ist, kann leer sein, darum prüft das Skript zuerst auf null.

Probieren Sie das Skript im Testlauf an einer Eingangsrechnung aus. Der Testlauf zeigt den Ausgang, die Felder, die sich ändern würden, und die Konsole, und er ändert nichts.
Verbinden Sie unter Ausgaben die Ausgänge weg = 'gf' und weg = 'kostenstelle' mit je einer Freigabe, und veröffentlichen Sie den Workflow.

Ab dann läuft das Skript für jede neue Eingangsrechnung. Ein Feld, das der Workflow deklariert, setzen Sie mit ctx.setField('kostenstelle', '4200'). Die Felder, die Finanzen für eine Eingangsrechnung liest, setzt kein Skript; welche Felder ein Skript setzen darf, schlägt der Editor vor.

Der Editor

Der Editor öffnet sich im Eigenschaftenbereich eines Skript-Schritts, mit den Reitern Code, Eingaben, Ausgaben und Testlauf; Vollbild gibt ihm die ganze Breite.

Vervollständigung: Der Editor kennt das SDK und die Typen Ihres Arbeitsbereichs: Dokumenttypen und ihre Felder, Akten-Typen, Schlagwörter, Kostenstellen und Rollen. Er schlägt sie beim Tippen vor und zeigt zu jeder Funktion ihre Beschreibung.
Prüfung beim Schreiben: Er prüft Typen und Regeln, während Sie schreiben, mit denselben Werkzeugen wie der Server. Jede Markierung trägt einen Code wie ACR-S012; Mehr erfahren führt zu seinem Eintrag unter Skripte: Fehler beheben. Für manche Meldungen bietet er eine Schnellkorrektur an, für fetch etwa Datenquelle verwenden; Strg+. (⌘. auf dem Mac) öffnet sie an der Stelle des Cursors. Fehler verhindern das Veröffentlichen, Warnungen nicht.
Per Tastatur: Im Editor rückt die Tabulatortaste ein. Nach Strg+M (Ctrl+Umschalt+M auf dem Mac) verlässt sie den Editor zum nächsten Element; dieselbe Tastenkombination schaltet wieder zurück.
Veröffentlichen nicht möglich: Beim Veröffentlichen prüft der Server die Skripte noch einmal. Findet er Fehler, nennt der Dialog Veröffentlichen nicht möglich jeden mit Code, Text, Datei und Stelle. Zum ersten Fehler öffnet den Skript-Schritt mit dem Cursor auf der Zeile des ersten Fehlers, der Pfeil einer Zeile auf ihrem Fehler.
Formatieren bringt den Code in eine einheitliche Form. Die Statusleiste zeigt die Sprache, die SDK-Version, die Zahl der Warnungen und Fehler, Zeile und Spalte und ob gespeichert ist.
Testlauf: Er führt das Skript einmal an einem Beispieldokument aus und ändert nichts; mehr dazu unter Testlauf.

Vollbild

Vollbild im Reiter Code öffnet die Skripte des Workflows über dem ganzen Fenster; Zurück zum Designer schließt es wieder, mit demselben Entwurf und dem zuletzt gezeigten Skript ausgewählt. Bearbeitet wird ein Skript immer nur an einer Stelle: Solange das Vollbild offen ist, zeigt der Eigenschaftenbereich keinen Editor. Oben rechts stehen Formatieren, Testlauf (siehe Testlauf) und Veröffentlichen.

Dateien: Links stehen die Skripte des Workflows unter scripts, eines je Skript-Schritt, und die schreibgeschützten Typen des SDK unter types (acriva.d.ts). Jede Datei öffnet sich in einem eigenen Reiter. workflow.yaml zeigt den Entwurf so, wie ihn der Export des Workflows schreibt, schreibgeschützt; die Datei ändert sich mit jedem Speichern des Entwurfs. Darunter stehen die Datenquellen des Arbeitsbereichs und unter Neue Felder dieser Version die Felder, die das Veröffentlichen anlegt.
Hooks & API: Rechts stehen die Hooks und die Funktionen von ctx, jeweils mit einer kurzen Beschreibung. Suchen … (Strg+Umschalt+F, ⌘+Umschalt+F auf dem Mac) filtert beide Listen. Ein Eintrag klappt auf, mit einer längeren Beschreibung und einem Beispiel: Einfügen setzt das Beispiel an der Stelle des Cursors ein, Doku öffnet in einem neuen Tab bei einem Hook den Abschnitt Hooks dieser Anleitung, bei einer Funktion ihren Eintrag in der Referenz des SDK. Der Hook des gezeigten Skripts trägt aktiv.
Probleme: Unter dem Editor stehen die Meldungen des gezeigten Skripts mit Code, Text, Zeile und Spalte, Mehr erfahren und, wo es eine gibt, der Schnellkorrektur. Ein Klick auf eine Meldung (oder die Eingabetaste) setzt den Cursor auf ihre Stelle. Die letzte Zeile sagt, wie die Typprüfung auf dem Server beim letzten Speichern ausging.
Ausgabe: Hier steht, was im Vollbild geschah: gespeichert, das Ergebnis der Prüfung auf dem Server, formatiert, eine Änderung an anderer Stelle, das Öffnen einer Datei und eine Datei, die sich nicht laden ließ. Nach einem Testlauf folgen seine Konsole und eine Zeile mit seinem Ergebnis; darüber steht das Ergebnis des letzten Testlaufs des gezeigten Skripts. Wie die übrigen Zeilen behält Ausgabe höchstens die letzten 200.
Git: Der Schalter Dateien | Git oben in der linken Seitenleiste zeigt die Git-Gegenstelle, den letzten Push und das letzte Holen sowie Pushen und Holen; mehr unter Git: pushen und holen.
Schmale Bildschirme: Unter 1280 px Breite bearbeiten Sie das Skript nur im Vollbild; Im Vollbild bearbeiten im Reiter Code öffnet es. Eingaben und Ausgaben bleiben im Eigenschaftenbereich.

Testlauf

Der Testlauf führt das Skript eines Schritts einmal an einem Dokument Ihrer Wahl aus, so wie es ein laufender Workflow täte. Testlauf ändert nichts. Felder, Ablage, Datenquellen-Ergebnisse und Benachrichtigungen werden nur angezeigt, nicht gespeichert oder gesendet: Das Dokument bleibt, wie es ist, kein Schlagwort, keine Akte und kein Hinweis kommt dazu, niemand wird benachrichtigt, und im Verlauf und im Protokoll des Dokuments erscheint nichts.

Wählen Sie den Skript-Schritt auf der Arbeitsfläche aus, und öffnen Sie den Reiter Testlauf.
Wählen Sie unter Beispieldokument ein Dokument. Die Liste zeigt die neuesten Dokumente, die Sie lesen dürfen, vom Dokumenttyp des Eingangs, wenn der Workflow einen hat; Dokument suchen sucht darin.
Wählen Sie Ausführen. Danach heißt die Schaltfläche Erneut ausführen.

Der Testlauf führt das gespeicherte Skript des Entwurfs aus, das der Server vorher noch einmal prüft. Solange der Entwurf oder das Skript eine Änderung hat, die noch nicht gespeichert ist, wartet er darauf. Findet die Prüfung Fehler, läuft das Skript nicht, und der Reiter zeigt die Meldungen; ein Klick auf eine Stelle öffnet sie im Reiter Code.

Nach dem Lauf zeigt der Reiter:

das Ergebnis: Erfolgreich oder Fehlgeschlagen, wie lange der Lauf dauerte und wann, was das Skript zurückgab (etwa branch('gf')) und den nächsten Schritt. Bei einem Fehler stehen darunter sein Code, sein Text und, wo bekannt, Zeile und Spalte im Skript; ein Klick darauf öffnet die Stelle im Reiter Code. Das Kreuz (Ergebnis schließen) blendet das Ergebnis wieder aus.
Felder, die gesetzt würden: jedes Feld mit seinem Wert jetzt und dem neuen Wert; darunter, was der Lauf außerdem täte, etwa ein Schlagwort setzen, das Dokument in einer Akte ablegen, eine Benachrichtigung senden oder einen Hinweis anzeigen.
Verbrauch: Laufzeit, Speicher, die Aufrufe von Datenquellen und die Abfragen von Datentabellen, jeweils gegen die Grenzen der Sandbox.
Konsole: die Zeilen, die das Skript in die Konsole schrieb (ctx.log), mit Uhrzeit und Stufe (info, log, warn, error); höchstens 1.000 Zeilen, jede höchstens 1.000 Zeichen, zusammen höchstens 64 KB. Kopieren kopiert sie.

Auf der Arbeitsfläche zeigt der Skript-Schritt die Dauer des letzten Testlaufs, mit einem Haken für einen erfolgreichen und einem Kreuz für einen fehlgeschlagenen Lauf. Der Ausgang, den der Lauf nahm, ist hervorgehoben, und der nächste Schritt trägt Testlauf. Das verschwindet, wenn Sie das Ergebnis schließen, das Skript ändern oder den Entwurf ändern.

Im Vollbild führt Testlauf in der oberen Leiste das gezeigte Skript an dem Beispieldokument aus, das Sie im Reiter Testlauf gewählt haben. Ohne eines fragt ein kleiner Dialog danach; auch er wartet, solange das Skript eine Änderung hat, die noch nicht gespeichert ist. Die Konsole und das Ergebnis erscheinen unter Ausgabe. Ist das Ergebnis von einem anderen Dokument als dem jetzt gewählten, oder hat sich der Entwurf seitdem geändert, sagt das ein Hinweis darüber, wie im Reiter Testlauf.

Für einen Testlauf gilt:

Es gelten dieselben Grenzen wie für einen Lauf im Workflow. Dazu führt jede Person höchstens 10 Testläufe in der Minute aus; danach sagt der Reiter, wann es weitergeht.
Führt ein Weg vom Eingang zum Schritt über eine Freigabe, verhält sich das Skript wie nach einer Freigabe: Es setzt nur leere, deklarierte Felder (Hooks).
Das Dokument darf einen anderen Dokumenttyp haben als den des Eingangs. Ein Feld, das der Schritt an diesem Dokument nicht setzen darf, lässt den Lauf mit effect-refused scheitern, wie es im Workflow geschähe.
Das Ergebnis sehen nur Sie, und nur, solange der Designer offen ist.

Der Testlauf des Designers probiert dagegen den ganzen Entwurf aus, führt keine Skripte aus und hält an einem Skript-Schritt an.

Mit KI schreiben und Fehler beheben

Im Reiter Code schreibt die KI ein Skript nach Ihrer Beschreibung, erklärt eine Meldung der Prüfung und schlägt eine Korrektur vor. Auf Wunsch schlägt sie auch beim Tippen Code vor. Die KI macht immer nur Vorschläge: Sie entscheiden, was in den Entwurf kommt, und veröffentlichen kann nur ein Mensch. Dafür muss im Arbeitsbereich KI eingerichtet sein; sonst meldet der Editor KI ist in diesem Arbeitsbereich nicht eingerichtet.

Ein Skript schreiben lassen

Wählen Sie in der Dateileiste über dem Editor Mit KI. Die Karte Mit KI schreiben öffnet sich.
Beschreiben Sie, was das Skript tun soll, zum Beispiel wann eine Rechnung an wen geht.
Wählen Sie Schreiben (oder drücken Sie im Textfeld Strg+Enter). Solange die KI schreibt, bricht Abbrechen ab.

Die Antwort erscheint im Editor als Vorschlag: Die eingefügten Zeilen sind grün markiert, entfernte Zeilen rot. Eine Leiste unten rechts nennt, wie viele Zeilen sich ändern, etwa 5 Zeilen eingefügt, und ändert nur den Entwurf, die Prüfung läuft danach; die Statusleiste zeigt Vorschlag offen.

Übernehmen (oder Strg+Enter, ⌘+Enter auf dem Mac, im Editor) übernimmt den Vorschlag als eine Änderung, die Strg+Z rückgängig macht.
Verwerfen (oder Esc im Editor) verwirft ihn.

Vor dem Übernehmen wird nichts gespeichert. Danach wird das Skript gespeichert wie jede Änderung, die Sie tippen, und der Server prüft es: Ein Skript mit Fehlern bleibt ein Entwurf mit seinen Meldungen und verhindert das Veröffentlichen des Workflows. Ein von der KI übernommener Text bleibt im Editor markiert (Von KI übernommen, noch nicht gespeichert), bis das Skript gespeichert ist. Ein Skript, das mit von der KI übernommenem Text gespeichert wurde, bleibt gekennzeichnet, bis der Workflow veröffentlicht oder der Entwurf verworfen wird: Der Dialog zum Veröffentlichen nennt es unter Mit KI geschrieben, damit Sie prüfen, was es tut, bevor Sie veröffentlichen. Ein Skript aus einem importierten Workflow ist nicht gekennzeichnet.

Die KI arbeitet mit dem gespeicherten Skript, deshalb wartet eine Anfrage, bis Ihre letzte Änderung gespeichert ist. Enthält die Antwort kein Skript, meldet der Editor Die Antwort enthält kein Skript. Formulieren Sie die Beschreibung neu.

Fehler erklären und beheben lassen

Jede Meldung der Prüfung mit einem Code wie ACR-S012 hat unter ihren Code-Aktionen zwei Aktionen mit KI; die Glühbirne neben der Zeile oder Strg+. (⌘. auf dem Mac) öffnet sie. Die eigene Schnellkorrektur der Regel steht zuerst und kostet nichts.

Fehler erklären (KI, 1 Credit) zeigt die Antwort unter dem Editor, als Erklärung zu ACR-S012. Links in einer Erklärung führen nur zu docs.acriva.de; jede andere Adresse bleibt einfacher Text. Erklärung schließen (×) blendet sie aus.
Fehler beheben in der Erklärung oder Fehler beheben (KI, 1 Credit) unter den Code-Aktionen schlägt eine Korrektur vor, genauso wie Mit KI schreiben: als markierte Zeilen, die Sie Übernehmen oder Verwerfen.

Vorschläge beim Tippen

Wenn Sie sie einschalten, ergänzt die KI die Zeile, die Sie gerade schreiben, als grauen Text hinter dem Cursor: Tab übernimmt ihn, Esc verwirft ihn. Ein Vorschlag ist höchstens die aktuelle Anweisung, und er kommt nach einer kurzen Pause beim Tippen.

Wählen Sie in der Statusleiste des Editors KI-Vorschläge aus. Das Fenster KI im Editor öffnet sich.
Schalten Sie Vorschläge beim Tippen ein. Die Statusleiste zeigt dann KI-Vorschläge an.

Der Schalter ist standardmäßig aus. Er gilt nur für Sie, in diesem Browser: Auf einem anderen Computer oder in einem anderen Browser bleiben die Vorschläge aus, bis Sie sie auch dort einschalten.

Was es kostet

Aktion	KI-Credits
Mit KI schreiben, Fehler erklären, Fehler beheben	je 1
Vorschläge beim Tippen	1 je 10

Am Tag sind höchstens 200 Vorschläge beim Tippen möglich. Danach sagt das Fenster Für heute sind keine Vorschläge beim Tippen mehr möglich., und die Statusleiste zeigt bis zum nächsten Tag KI-Vorschläge aus.
Schreiben, Erklären und Beheben zusammen erlauben höchstens 20 Anfragen in der Minute je Person.
Eine Anfrage, die Sie abbrechen, kostet nichts.
Hat der Arbeitsbereich keine KI-Credits mehr, meldet der Editor Der Arbeitsbereich hat keine KI-Credits mehr., und die Vorschläge beim Tippen enden. Wer den KI-Verbrauch sehen darf, sieht in der Karte Mit KI schreiben auch, wie viele Credits übrig sind.

Was an das Modell geht

Das Modell bekommt:

den Code des Skripts, auch die Texte und Kommentare im Skript: Was Sie in einen Kommentar oder eine Zeichenkette schreiben, geht so an das Modell, wie es dasteht;
die Meldungen der Prüfung;
die Namen und Typen Ihrer Felder, Dokumenttypen, Datenquellen und Datentabellen;
Ihre Beschreibung und bei einem Vorschlag beim Tippen den Text um den Cursor.

Werte aus Dokumenten, Datenquellen oder Datentabellen bekommt es nie, ebenso wenig das Dokument, das Ergebnis oder die Konsole eines Testlaufs. Jede KI-Anfrage wird gezählt und protokolliert wie die übrigen KI-Schritte.

Eingaben und Ausgaben

Eingaben deklariert, was das Skript liest:

Dokumentfelder: die Felder des Dokumenttyps des Workflows, die das Skript als ctx.document.fields liest. Feld hinzufügen bietet die Felder des Typs und die Felder an, die der Workflow deklariert. Ein Workflow ohne Dokumenttyp hat keine.
Datenquellen und Datentabellen: die Datenquellen, die das Skript über ctx.sources abfragt. Datenquelle hinzufügen bietet die Datenquellen Ihres Arbeitsbereichs an, Datenquellen verwalten führt zu ihnen. Eine Datentabelle kommt über die Datei des Workflows hinzu (siehe Datentabellen).
Immer verfügbar: die Schlagwörter und Akten des Dokuments und das Ergebnis der letzten Aufgabe, die jedes Skript ohne Deklaration liest.

Ausgaben zeigt, was das Skript zurückgibt und wohin der Workflow danach geht:

Rückgaben kommen aus outputs im Code. Der Schritt übernimmt jeden Schlüssel und Typ, sobald der Editor den Code geprüft hat, Sie deklarieren sie also nur einmal; solange der Code einen Syntaxfehler hat, behält der Schritt die bisherigen. Jede Änderung ist ein Schritt, den Sie mit Strg+Z rückgängig machen. Verwendet von nennt die späteren Bedingungen, die einen Wert lesen, und Ausgänge dieses Schritts den Wert, nach dem das Skript mit ctx.branch verzweigt.
Ausgänge: eine Zeile je Wert der Verzweigung, etwa weg = 'gf', mit dem Schritt, zu dem er führt, und Sonst für jedes andere Ergebnis. Ein Skript, das nicht verzweigt, hat stattdessen Weiter. Die Arbeitsfläche zeichnet dieselben Ausgänge mit ihrem Wert, und eine Verbindung, die Sie dort ziehen oder entfernen, ändert sie auch hier.
Bei Fehler: wohin der Workflow geht, wenn das Skript scheitert (Grenze überschritten, Ausnahme, abgelehnte Änderung). Mit Schritt schlägt fehl (Standard) vermerkt der Verlauf einen fehlgeschlagenen Schritt, und der Workflow geht weiter wie bei Sonst oder Weiter.
Felder, die das Skript setzt: die Schlüssel von ctx.setField im Code, jeder mit seinem Feld: ein vorhandenes Feld des Dokumenttyps oder ein Feld, das der Workflow deklariert, markiert mit neu. Neues Feld deklarieren, oder Deklarieren neben einem Schlüssel, den kein Feld hat, legt ein Feld an, das der Workflow braucht: seinen Schlüssel, seine Art, die Bezeichnungen auf Deutsch und Englisch, die Optionen einer Auswahl und die Dokumenttypen, in die es kommt. Deklarierte Felder gelten für den ganzen Workflow; das Veröffentlichen legt sie in ihren Dokumenttypen an, und der Dialog zum Veröffentlichen nennt sie unter Neue Felder dieser Version.

Ein Skript mit dem Hook beforeApproval liest nur: Es hat keine Rückgaben, verzweigt nicht und setzt keine Felder, seine Ausgaben haben deshalb nur Weiter und Bei Fehler.

TypeScript und JavaScript

Jede Skriptdatei endet auf .ts, und Sie können darin TypeScript oder reines JavaScript schreiben: Gültiges JavaScript ist auch gültiges TypeScript. TypeScript lohnt sich, weil die Prüfung dann mehr findet, etwa ein Feld, das es nicht gibt, oder einen Text, wo ein Betrag stehen muss. Aber auch ohne Typangaben leitet der Editor die Typen aus dem SDK ab und prüft mit ihnen.

Beträge sind Zahlen in Euro (Money); money.format(1249.5) gibt '1.249,50 €', money.parse('1.249,50 €') den Betrag zurück, money.round rundet kaufmännisch auf Cent.
Tage sind Texte JJJJ-MM-TT (PlainDate), die sich mit < und > vergleichen lassen; date.format, date.parse, date.addDays und date.daysBetween rechnen mit ihnen.
run darf async sein und auf Datenquellen und Datentabellen warten (await ctx.sources.get(…)).
Ein switch über einen Wert, den das SDK liefert (etwa einen Hook oder das Ergebnis einer Aufgabe), braucht einen default-Zweig: Das SDK wächst in Version 1 nur durch Ergänzungen, aber eine Ergänzung kann einen neuen Wert bringen.

Weiter

Die API-Referenz beschreibt jede Funktion und jeden Typ des SDK, je Version, mit ihrem Änderungsprotokoll.
Das Workflow-Kochbuch zeigt fertige Workflows mit Skripten, jeden mit seinem Code und dem Ergebnis, das ein Test prüft.
Skripte: Fehler beheben erklärt jeden Code der Prüfung, die überschrittenen Grenzen und häufige Typfehler.