Flexie Scripting: Wo es läuft und seine Grenzen

Der Datensatz, den ein Skript erhält

Jede Stelle, die Flexie Scripting auswertet, übergibt ihm einen Datensatz, mit dem es arbeitet, sowie die stets verfügbaren globalen Werte. Welcher Datensatz das ist, hängt vom Kontext ab:

Wo es läuft	Der übergebene Datensatz
Eine E-Mail-Vorlage über einen Kontakt	dieser Kontakt
Eine Rechnungs-PDF-Vorlage	diese Rechnung
Eine Angebots-PDF-Vorlage	dieses Angebot
Eine Workflow-Aktion auf einem Deal	dieser Deal
Eine SMS-Vorlage	der Empfänger-Datensatz der Nachricht
Ein Snippet	derselbe Datensatz wie die Vorlage, die es eingebunden hat

Sie lesen die Felder dieses Datensatzes direkt, {{ first_name }}, {{ total_incl_tax }}, ohne record.-Präfix. Um mit einem anderen Datensatz zu arbeiten (einem verknüpften Lead, einer aktuellen Rechnung, der verknüpften Firma), verwenden Sie eine Lookup-Funktion wie findOne, findMany oder getAccountContacts und weisen das Ergebnis einer eigenen Variablen zu.

Eingebaute verknüpfte Arrays. In einem Workflow, dessen Datensatztyp Standard-Beziehungen hat, etwa ein Deal mit einer verknüpften Firma und vielen verknüpften Kontakten, stehen diese verknüpften Datensätze automatisch auch als Arrays unter ihrem Plural-Namen bereit: {{ contacts[0].first_name }}, {{ accounts[0].account_name }}. Mit [0] greifen Sie auf den ersten (oder einzigen) zu.

Der Namespace `__data` (innerhalb von Workflows)

Wenn ein Skript innerhalb eines Workflows läuft, hat es zusätzlich Zugriff auf alles, was der Workflow bisher gesammelt hat, unter einem einzigen Namespace namens __data.

So fließen Daten von einem Schritt zum nächsten. Wenn ein Workflow durch ein eingehendes Signal ausgelöst wird (eine E-Mail trifft ein, ein Formular wird abgeschickt, ein Webhook wird empfangen) oder wenn eine frühere Aktion einen Wert gespeichert hat, steht diese Information jedem späteren Schritt als {{ __data.something }} zur Verfügung:

{{ __data.incoming_email.subject }}
{{ __data.incoming_sms.text }}
{{ __data.last_task.due_date }}

Die vollständige Funktionsweise von __data, was jeder Trigger bereitstellt und wie Sie eigene Werte für spätere Schritte speichern, ist in Daten zwischen Schritten weitergeben beschrieben. Bei dynamischen Endpunkten wird auch der eingehende Request-Body auf diese Weise bereitgestellt, siehe Dynamische Endpunkte, Daten empfangen.

Ergebnisgrenzen

Damit Vorlagen schnell und sicher bleiben, sind Lookups, die viele Zeilen zurückgeben können, auf 1.000 Ergebnisse begrenzt:

findMany(...) verwendet standardmäßig 1.000 und überschreitet diesen Wert nicht.
query(...) ist auf 1.000 Zeilen begrenzt.

Wenn Sie Summen über mehr als das hinaus benötigen, summieren Sie an der Quelle mit findSum, findCount, findMin, findMax (die in der Datenbank rechnen), statt jede Zeile zurückzuholen und sie in der Vorlage zusammenzuzählen.

query(...) ist schreibgeschützt: nur SELECT und WITH werden akzeptiert. Alles, was Daten ändern oder entfernen würde (INSERT, UPDATE, DELETE, DROP), sowie SELECT * werden abgelehnt. Sie erhalten stattdessen ein {"error": "…"}-Ergebnis.

Die Sicherheits-Sandbox

Flexie Scripting läuft innerhalb einer geschützten Sandbox. Genau das macht es sicher genug, um es in Vorlagen und Workflow-Feldern bereitzustellen. Die Grenzen:

Nur das dokumentierte Werkzeugset existiert

Nur die Funktionen, Filter und Tags, die in diesem Abschnitt aufgeführt sind, stehen zur Verfügung. Verwendet ein Skript etwas anderes, bricht es mit einem Fehler ab, statt etwas Unerwartetes zu tun. Die verfügbaren Tags sind genau:

{% if %} / {% elseif %} / {% else %} / {% endif %}
{% for %} / {% endfor %}
{% set %}
{% snippet "alias" %}

(Es gibt kein „Datei einbinden", kein „import", kein „macro" oder Ähnliches, diese sind bewusst nicht verfügbar.)

Sie lesen Daten, Sie rufen keine Methoden darauf auf

Datensätze werden Ihrem Skript als einfache Daten bereitgestellt, sodass das Lesen von Feldern genau so funktioniert wie gezeigt: {{ email }}, {{ total_incl_tax }}, {{ row['some key'] }} (wobei row eine Variable ist, die Sie aus einem Lookup gesetzt haben). Was Sie nicht tun können, ist Methoden aufzurufen oder interne Eigenschaften von Objekten zu erreichen; die Sandbox erlaubt das nicht. Alles, was Sie brauchen, ist entweder als lesbare Datensatz-Daten oder als eine der dokumentierten Funktionen verfügbar.

Es kann nicht über Flexie hinausreichen

Ein Skript kann keine Dateien auf dem Server lesen oder schreiben, keine Programme ausführen und nichts verwenden, was nicht bewusst verfügbar gemacht wurde. Die einzigen Wege, über die ein Skript die Außenwelt berührt, führen über die dedizierten, kontrollierten Funktionen, die hier dokumentiert sind (zum Beispiel wird ein Webhook von einer Workflow-Aktion gesendet, nicht von der Vorlagensprache selbst).

Fehler bleiben eingegrenzt

Wenn ein Skript fehlschlägt, etwa durch einen falschen Funktionsnamen oder fehlerhafte Eingaben, löst es genau an dieser einen Stelle einen Fehler aus. Es bringt nicht die umgebende Seite zum Absturz und beschädigt keine Daten.

Praktische Konsequenzen

Testen Sie mit einem echten Datensatz. Da ein Skript von dem Datensatz abhängt, den es erhält, prüfen Sie es immer an einem echten Beispiel in der Vorschau, bevor es live geht. Workflows haben einen eingebauten Testmodus (siehe Planung, Test und Fehlersuche); Vorlagen haben eine Vorschau.
Sichern Sie sich gegen leere Werte ab. Ein Feld kann leer sein. Verwenden Sie default(...), coalesce(...) oder ein {% if %}, damit ein fehlender Wert keine hässliche Ausgabe erzeugt.
Bevorzugen Sie Summen auf Datenbankseite. findSum und findCount statt Zeilen zu holen und zusammenzuzählen: schneller, und stößt nie an die 1.000-Zeilen-Grenze.
Halten Sie aufwendige Lookups aus engen Schleifen heraus. Ein findMany-Aufruf innerhalb einer for-Schleife, die selbst über viele Datensätze läuft, vervielfacht die Arbeit. Einmal holen, dann durchlaufen.

Nächste Schritte

Rezepte: vollständige, echte Beispiele, die diese Grenzen einhalten.
Funktionsreferenz: das vollständige Werkzeugset.

Wo es läuft und seine Grenzen