Automatisierungen mit Lua schreiben

▧Originalbild aus Werkstube folgt

Screenshot der zentralen Werkstube-Ansicht „Automatisierungen mit Lua schreiben“ mit den im Artikel beschriebenen Bedienelementen.

#Wann Lua sinnvoll ist

Nutze Lua, wenn Bedingungen oder Datenverarbeitung im visuellen Editor zu unübersichtlich werden. Für normale Benachrichtigungen, Statuswechsel und einzelne Aktionen bleibt der visuelle Ablauf leichter zu warten.

Ein Skript arbeitet mit der globalen Tabelle action. Du musst keine internen API-Anfragen aufbauen. Werkstube stellt fertige, berechtigungsgeprüfte Funktionen bereit.

local job_id = action.require("entity_id", "Auftrags-ID fehlt")

action.jobs.add_history{
  jobId = job_id,
  text = "Der Auftrag wurde durch den Ablauf automatisch geprüft",
  actor = "Automatisierung",
}

action.notify(
  "Auftrag geprüft",
  "Der automatische Schritt ist abgeschlossen.",
  { severity = "success", link = "/auftraege/" .. job_id }
)

#Daten des Auslösers lesen

action.trigger enthält das vollständige Ereignis. Direkter Zugriff ist möglich, bei optionalen Feldern ist action.get aber sicherer:

local status = action.get("payload.status", "unbekannt")
local first_item = action.get("payload.items.1")

action.require(pfad, meldung) beendet den Lauf mit deiner verständlichen Meldung, wenn ein Pflichtwert fehlt. action.require_value bleibt als ausgeschriebener Alias verfügbar. Verwende die Funktion am Anfang, bevor eine E-Mail oder Datenänderung ausgeführt wird.

#Werkstube-Aktionen

Die rechte Referenz im Skripteditor zeigt nur Aktionen, die du mit deinen aktuellen Rechten verwenden darfst. Ein Klick fügt ein Beispiel ein. Die wichtigsten Muster sind:

local customer = action.customers.create{
  company = "Muster GmbH",
  email = "buero@example.de",
}

local job = action.jobs.create{
  title = "Wartung Heizung",
  customerId = customer.customer.id,
}

local loaded = action.jobs.get{ id = job.job.id }

Beim Anlegen von Kunden, Aufträgen, Anfragen, Angeboten, Rechnungen, Terminen, Auftragsnotizen und Bestellungen ergänzt Werkstube die internen Anfragehüllen selbst. Ältere Skripte mit einer ausdrücklich verschachtelten Form wie action.jobs.create{job={...}} funktionieren weiterhin.

Daneben stehen unter anderem diese Bereiche zur Verfügung:

• action.customers — Kunden anlegen, laden und suchen
• action.jobs — Aufträge anlegen, laden, weiterschalten und Notizen ergänzen
• action.inquiries, action.quotes, action.invoices — kaufmännische Vorgänge
• action.calendar — Termine anlegen
• action.inventory — Bestand, Nachbestellung und Bestellungen

Die genaue Liste richtet sich nach deinen Betriebsmodulen und Rechten.

#Benachrichtigung, E-Mail und KI

action.notify("Titel", "Text", {
  severity = "warning", -- info | success | warning | danger
  link = "/auftraege/42",
})

action.email("chef@example.de", "Betreff", "Nachricht")

local antwort = action.ai("Fasse diese Angabe kurz zusammen: " .. action.get("payload.text", ""))

Für komplexere Empfängerangaben bleiben die Tabellenformen action.notify{...} und action.email{...} verfügbar. Relative Links dürfen nur innerhalb von Werkstube führen. E-Mail-Empfänger und Betreff werden gegen Header-Manipulation geprüft.

#Protokoll und JSON

action.log("Lauf gestartet")
action.warn({ status = action.get("payload.status") })
action.error("Manuelle Prüfung erforderlich")

local data = action.json.decode('{"priority":"high"}')
action.log(action.json.encode(data))

Tabellen erscheinen im Laufprotokoll als lesbares JSON. action.error schreibt eine rote Protokollzeile; zum tatsächlichen Abbrechen verwendest du error("Begründung") oder action.require.

#Fehler gezielt behandeln

Aktionen brechen das Skript bei einem Fehler ab. Wenn ein Fehler fachlich erwartet ist, kannst du ihn mit pcall behandeln:

local ok, result = pcall(function()
  return action.jobs.get{ id = action.require("entity_id") }
end)

if not ok then
  action.warn("Auftrag konnte nicht geladen werden: " .. tostring(result))
  return
end

Behandle Fehler nur, wenn der Ablauf danach sicher weiterlaufen oder erfolgreich enden darf. Verschlucke keine fehlgeschlagene Buchung oder versandte Nachricht.

#Sicherheitsgrenzen

Lua läuft in einer abgeschotteten Umgebung. Es gibt keinen Zugriff auf Betriebssystem, Dateien, Prozesse, Netzwerk-Sockets oder native Bibliotheken. Gesperrt sind insbesondere os, io, debug, package, syscall, ffi, socket, http, require und Funktionen zum dynamischen Laden von Code.

Verfügbar sind die sicheren Lua-Grundfunktionen sowie table, string und math. Zusätzlich gelten:

• höchstens 64 KB Skriptquelle
• höchstens 10 Sekunden Laufzeit
• höchstens 64 KB Laufprotokoll
• begrenzte Tiefe und Größe für Tabellen und JSON
• aktuelle Rechte der Person, die den Ablauf ausführt beziehungsweise zuletzt gespeichert hat

Die Werte stehen im Skript auch unter action.limits; action.dry_run zeigt, ob gerade ein Probelauf ausgeführt wird.

#Vor dem Aktivieren

1. Pflichtwerte mit action.require prüfen.
2. Syntaxanzeige im Editor abwarten.
3. Einen Probelauf mit realistischem Ereignis ausführen.
4. Im Protokoll Eingaben, Ergebnisse und gewählten Pfad prüfen.
5. Irreversible Schritte wie E-Mail oder Bestellung möglichst ans Ende setzen.

Mehr zum sicheren Wiederholen fehlgeschlagener Läufe findest du unter Testen & Laufprotokolle.