Workflow-Node-Referenz
Vollständige Referenz aller Knotentypen der Kasimir-Workflow-Engine mit Konfigurationsfeldern, Ein-/Ausgaben, Ports und Limits.
Diese Referenz dokumentiert jeden Knotentyp, den die Kasimir-Workflow-Engine (server/utils/workflowExecutor.ts) ausführt. Die Engine ist ein linearer Walker entlang der Kanten (workflow_edges): Ab dem trigger-Knoten wird einer Kanten-Queue gefolgt; mehrere Kanten aus einem Port laufen sequenziell in Einreihungs-Reihenfolge (Make.com-Semantik), jeder Knoten läuft pro Run höchstens einmal (Diamond-Join: erster Zweig gewinnt). Werte fließen über eine In-Memory-InterpolationState-Map und werden in nachgelagerten Knoten per Template-Referenz {{slug.feld[.pfad]}} aufgelöst. Alle *_template-Felder durchlaufen interpolate(); die Knoten-Typ-Literale (type) im config dienen als Diskriminator des NodeConfig-Union-Typs.
Grundkonzepte
Referenz-Syntax (Interpolation)
Templates referenzieren vorherige Knoten über {{slug.field[.path]}}. Das Regex erlaubt slug = [a-z][a-z0-9_]{0,39}, field = input oder output, plus optionalen punkt-getrennten Pfad.
Referenz | Bedeutung |
|---|---|
| Wert des Trigger-/Formular-Inputs |
| Voller Output des Knotens |
| Pfad-Traversal in ein JSON-Output-Objekt |
| Aktuelles Element / Index innerhalb eines |
| Antwort aus einem |
Fehlende Referenzen werden NICHT zum Fehler: nicht auflösbare Refs ergeben den Platzhalter-String [MISSING:slug] bzw. [MISSING:{{…}}]. null/undefined werden zu ''. Reservierte Slugs: trigger, now, output, error, headers, status, body.
Knoten-Querschnittsfelder
Diese Felder auf WorkflowNode gelten für JEDEN Knotentyp:
Feld | Typ | Wirkung |
|---|---|---|
|
| Anzeigename (Anzeige = |
|
| Notiz im Editor |
|
| Knoten wird übersprungen (Status |
|
|
|
|
| Bei Fehler wird der Knoten bis zu n-mal erneut ausgeführt, bevor |
|
| Run pausiert mit Status |
|
| KI-gefüllte Config-Felder; |
|
| Modell für die KI-Feld-Auflösung |
Eine Pause (ask_user, delay, requires_approval) hinter einem router oder parallelen Zweigen wird NICHT unterstützt — der Run schlägt mit entsprechender Meldung fehl, wenn die Kanten-Queue zum Pausenzeitpunkt nicht leer ist.
Knotenübersicht
| Kategorie | Output-Ports |
|---|---|---|
| Einstieg |
|
| KI |
|
| KI / Guardrail |
|
| KI |
|
| Logik |
|
| Verzweigung |
|
| Verzweigung | je Route eine Port-ID (+ Fallback) |
| Schleife |
|
| Aktion |
|
| Pause |
|
| Pause |
|
| Daten |
|
| Daten / RAG |
|
| Daten |
|
| Ausgabe |
|
| Ausgabe |
|
| Ausgabe |
|
| Aktion |
|
| Aktion |
|
| Aktion |
|
| Integration (Microsoft) |
|
| Integration (Microsoft) |
|
| Integration (Microsoft) |
|
| Integration (Google) |
|
Einstieg
trigger
Jeder Workflow hat genau einen Trigger; fehlt er, schlägt der Run sofort fehl (Kein Trigger-Knoten). Der Trigger definiert die Eingabevariablen, die als {{trigger.input.<key>}} verfügbar sind. Er führt selbst keine Logik aus — die Run-Inputs werden in den State geschrieben, der Knoten als completed markiert und die output-Kante verfolgt.
Config-Feld | Typ | Beschreibung |
|---|---|---|
|
| Auslöseart |
|
| Eingabevariablen (gemeinsam für alle Modi) |
|
| Nur bei |
|
| Trigger-Key aus |
|
| Provider-spezifische Felder |
WorkflowInputDef: key ([a-z][a-z0-9_]{0,39}), label, type (text/longtext/select/boolean), placeholder?, required, options? (nur select), default_value?. Pflichtfelder werden bei Run-Start validiert; optionale leere Felder bleiben als '' bzw. false erhalten.
Outlook-Mail-Trigger liefert einen FESTEN Variablensatz: from, subject, to, cc, body, received_at, message_id, attachments.
KI-Knoten
llm
Der zentrale Textgenerierungs-Knoten. Free-Text wird gestreamt (Partial-Flush nach output_text_partial alle 300 ms, Stream-Deadline 120 s); strukturierter Output und der agentische Pfad laufen non-streaming.
Config-Feld | Typ | Beschreibung |
|---|---|---|
|
|
|
|
| System-Prompt (interpoliert); aktuelles Datum wird stets vorangestellt |
|
| Nutzer-Prompt (interpoliert) |
|
| Teilmenge des |
|
| Legacy; mappt ohne |
|
| Agentische Tools; nicht-leer ⇒ Reasoning-Schleife (structured_output dann inaktiv) |
|
| Interpoliert; nicht-leer ⇒ Konversations-Memory aktiv (außer bei structured_output) |
|
| Anzahl geladener vergangener Interaktionen (Default 5) |
|
| Erzwingt JSON-Schema-Antwort |
|
| JSON-Schema bei |
|
|
|
|
| Max. Iterationen der Tool-Schleife (Clamp 1..25, Default 6) |
|
| Vorhandenen Assistenten wiederverwenden (liefert Persona/Modell/Web-Tools; Knoten-Werte haben Vorrang) |
Output: Free-Text-String, JSON-Objekt (structured) oder Agenten-Antwort. tokens_in/tokens_out werden erfasst. Bei structured_output mit unparsebarem JSON erfolgt ein Retry mit „Antworte ausschließlich als gültiges JSON."; scheitert auch das → Fehler. Verfügbare agentische Tools: web_search, fetch_page, doc_search. Die agentische Schleife hat eine Wall-Clock-Deadline von 150 s und droppt auf der letzten erlaubten Iteration die Tools, um eine finale Antwort zu erzwingen.
check (Guardrail / „Überprüfen")
LLM-basierte Inhaltsklassifikation; gibt ein Urteil zurück. DSGVO-relevant.
Config-Feld | Typ | Beschreibung |
|---|---|---|
|
| Zu prüfender Text (interpoliert) |
|
|
|
|
|
|
Output (JSON): { passed: boolean, flags: string[], reason: string (deutsch), checks: string[] }. passed ist false, sobald irgendeine aktivierte Prüfung anschlägt. Nicht parsebare Modellantwort ⇒ passed=false, flags=['parse_error'].
image_gen („Bildgenerierung")
Text-Prompt → OpenAI-kompatibles /images/generations über den LiteLLM-Proxy; speichert ein PNG.
Config-Feld | Typ | Beschreibung |
|---|---|---|
|
| Bild-Prompt (interpoliert) |
|
|
|
|
| Bildgröße |
|
| Anzahl Bilder |
Output: { path } (Pfad in workflow-outputs, output_file_path). Antwort wird als b64_json angefordert; fehlen die Bilddaten → Fehler. Laufzeit benötigt ein konfiguriertes Bildmodell in LiteLLM (Ops-Abhängigkeit).
Logik
code
Führt LLM-/nutzergeschriebenes Python im kasimir-codebox-Sidecar aus (Timeout 30 s). Ist die Sandbox nicht konfiguriert (CODEBOX_BASE_URL/API_KEY), schlägt der Knoten fehl.
Config-Feld | Typ | Beschreibung |
|---|---|---|
|
| Python-Quelltext |
Vorgänger-Outputs werden als inputs-Dict (Key = Node-Slug, jeweils {input} oder {output}) bereitgestellt — base64-kodiert eingebettet und in Python dekodiert. Eine Hilfsfunktion result(x) gibt JSON via print() aus.
Output: stdout getrimmt; gültiges JSON wird geparst (strukturierter Output), sonst Klartext. Code-Fehler/Timeout ⇒ Knoten-Fehler (stderr auf 500 Zeichen gekürzt).
Verzweigung
if_else
Wertet eine Bedingung aus und folgt dem Port true oder false.
Config-Feld | Typ | Beschreibung |
|---|---|---|
|
| Legacy-Einzelbedingung |
|
| Multi-Bedingung; nicht-leer ⇒ ersetzt |
|
|
|
Operatoren (op): ==, !=, contains, matches (RegExp), is_empty (leer oder [MISSING:…]), is_truthy, is_falsy, >, <, >=, <=. Beide Seiten werden interpoliert; numerische Vergleiche casten via Number(). Output-Port = true/false; output selbst ist null.
router (Make.com-Semantik)
ALLE Routen, deren Bedingungen passen, werden aktiviert und laufen sequenziell. Eine Route ohne Bedingungen läuft immer; die „Sonst"-Route (is_fallback) nur, wenn KEINE andere passte.
Config-Feld | Typ | Beschreibung |
|---|---|---|
|
| Liste der Routen |
RouterRoute: id (= Port-ID / edge.from_port), label, conditions[], match (all/any), is_fallback?. Output: { matched_routes: string[] }; output_port = kommaseparierte Liste der gematchten Route-IDs; der Walker reiht die Kanten ALLER gematchten Ports ein.
Schleife
for_each + aggregate
for_each wertet over_expr zu einem Array aus und führt die LINEARE Body-Kette vom output-Port bis zum nächsten aggregate-Knoten einmal pro Element aus.
| Typ | Beschreibung |
|---|---|---|
|
| z. B. |
|
| Optionaler Iterations-Deckel; |
Pro Iteration: {{<loopSlug>.output.item}} und .index. Ist over_expr ein String, wird JSON.parse versucht; liefert es kein Array ⇒ Fehler.
| Typ | Beschreibung |
|---|---|---|
|
| Pro Iteration ausgewertet (typisch |
|
|
|
|
| Nur bei |
|
| Duplikate (Werteglichheit) vor der Ausgabe entfernen |
Output am aggregate-output-Port: gesammeltes Array bzw. verbundener String.
v1-Beschränkungen: Body MUSS linear sein — verboten sind if_else, router, http_out, ask_user, delay und verschachtelte for_each im Body. Genau ein output-Port; Body muss in einem aggregate münden. Body-Knoten persistieren nur die LETZTE Iteration als Run-Node-Zeile. Ein aggregate ohne vorgelagertes for_each lässt den Run fehlschlagen.
Aktionen
http_out
Externer HTTP-Request mit SSRF-Schutz (httpsOnly, blockiert private/Loopback/Metadata-Hosts; jeder Redirect wird neu validiert, max. 5 Hops).
Config-Feld | Typ | Beschreibung |
|---|---|---|
|
| HTTP-Methode |
|
| Ziel-URL (interpoliert) |
|
| Angehängte Query-Parameter (interpoliert) |
|
| Header (Werte interpoliert) |
|
| Body-Modus (setzt ggf. |
|
| Request-Body (interpoliert) |
|
|
|
|
| Auth-Schema |
|
| Env-deklarierter Slot ( |
|
| Timeout (Default 30) |
Output: { status, body, headers }; Port = success (Status < 400) oder error. Timeout/Exception ⇒ status:0, Port error. Redirects: 301/302/303 → GET + Body verworfen; 307/308 → Methode/Body bleiben.
send_email
E-Mail über SendGrid; body_markdown wird via marked zu HTML.
Config-Feld | Typ | Beschreibung |
|---|---|---|
|
| Muss eine gültige Adresse ergeben (sonst Fehler) |
|
| Optional; Komma/Semikolon-getrennt, nur gültige Adressen |
|
| Betreff |
|
| Markdown-Body |
|
| Optionaler Reply-To |
|
| Optionaler Absender-Anzeigename (Adresse bleibt verifizierter Sender) |
Output: { to, cc, bcc, subject, body, sent }. Lehnt SendGrid ab (Key fehlt/ungültige Adresse) ⇒ Knoten-Fehler.
post_message
Postet in einen Chat-/Webhook-Endpoint; Payload-Shaping pro Ziel.
Config-Feld | Typ | Beschreibung |
|---|---|---|
|
| Zieltyp |
|
| Webhook-URL (interpoliert; muss |
|
| Nachrichtentext |
|
| Slack: optionaler Name-Override |
|
| Slack: optionaler Channel-Override |
Payload: Slack {text, username?, channel?}; Teams MessageCard-light; Webhook {text, source, workflow_id, node_slug}. Output: { target, status, ok }; nicht-OK-HTTP ⇒ Fehler.
notify („Benachrichtigung senden")
Schreibt eine In-App-Benachrichtigung in die Inbox des Run-Initiators. Kein Initiator (Zeitplan-/Webhook-Run) ⇒ No-Op.
Config-Feld | Typ | Beschreibung |
|---|---|---|
|
| Nachrichtentext (interpoliert) |
Output: der gerenderte Text.
Pause
ask_user
Pausiert den Run und sammelt ein Formular voller Antworten; verhält sich wie ein zweiter Trigger mitten im Flow. Run-Status → waiting_input. /resume ruft den Executor mit {resume} erneut auf; Antworten sind als {{<slug>.input.<key>}} verfügbar.
Config-Feld | Typ | Beschreibung |
|---|---|---|
|
| Über dem Formular angezeigt |
|
| Formularfelder (gleiche Shape wie Trigger) |
delay
Pausiert zeitgesteuert; Run-Status → waiting_timer, resume_at wird gesetzt.
Config-Feld | Typ | Beschreibung |
|---|---|---|
|
| Fester Wert |
|
| Einheit |
|
| Interpoliert zu einer Zahl > 0; überschreibt |
Daten
load_table
Lädt eine mit dem Workflow verknüpfte Tabelle (workflow_documents) aus dem documents-Bucket und parst sie.
Config-Feld | Typ | Beschreibung |
|---|---|---|
|
| Verknüpftes Dokument ( |
|
|
|
|
| Zeile 1 = Spaltennamen |
|
| Cap (Default 1000) |
Unterstützt .xlsx und .csv; das Dokument muss mit DIESEM Workflow verknüpft sein (Defense-in-Depth). Output: { rows: Record<string,string>[], count, columns }. Ein nachgelagerter for_each iteriert über {{slug.output.rows}}, Felder via {{loop.output.item.<spalte>}}.
doc_search (RAG)
Semantische Suche über firmenweite Dokument-Chunks (Embedding-Modell → searchChunks).
Config-Feld | Typ | Beschreibung |
|---|---|---|
|
| Suchanfrage (interpoliert) |
|
| siehe Hinweis |
|
| Default 5, Cap 20 |
Output: { chunks: [{document_name, snippet, score}], text }. Similarity-Schwelle 0.55.
v1-Gap: Treffer werden hart auf scope_type='company'-Dokumente beschränkt (DSGVO-Schutz). scope='project' fällt auf firmenweite Suche zurück — projektgescopte RAG erfordert eine RPC-Änderung.
web_search
Web-Suche über den konfigurierten Provider (Timeout 20 s).
Config-Feld | Typ | Beschreibung |
|---|---|---|
|
| Suchanfrage (interpoliert) |
|
| Default 5, Cap 10 |
Output: { results: [{title, url, snippet}], text }. Kein Provider konfiguriert ⇒ Knoten-Fehler Keine Web-Suche konfiguriert.
Ausgabe
doc_render
Erzeugt eine echte Datei (DOCX/XLSX/PDF/PPTX) und legt sie im workflow-outputs-Bucket ab.
Config-Feld | Typ | Beschreibung |
|---|---|---|
|
| Zielformat |
|
| Render-Pfad |
|
| Vorlage (nur |
|
| Markdown-Quelle (interpoliert) |
|
| Dateiname (interpoliert) |
Bei with_template werden alle Trigger-Inputs + Knoten-Outputs als Variablen bereitgestellt. Output: { path } (output_file_path). Pfad: {company_id}/{workflow_id}/{run_id}/{slug}.{ext}.
save_to_storage
Speichert Output dauerhaft als Datei (überlebt den Run).
Config-Feld | Typ | Beschreibung |
|---|---|---|
|
|
|
|
| Nur |
|
| Nur |
|
| Zieldateiname (interpoliert) |
|
| MIME bei |
Output: { path }. Pfad: {company_id}/{workflow_id}/outputs/{filename}. Fehlender Quellpfad / Upload-Fehler ⇒ Knoten-Fehler.
output
Schreibt einen benannten Wert in die Run-übergreifende outputs-Map (Read-Modify-Write).
Config-Feld | Typ | Beschreibung |
|---|---|---|
|
| Output-Schlüssel |
|
| Wert (interpoliert) |
Output: der gerenderte String; zusätzlich gemerged in workflow_runs.outputs.
Integrationen
Alle Integrations-Aktionen lösen den Run-Akteur auf: bei manuellen Runs der Initiator (user_id); bei Webhook-/Zeitplan-Runs (user_id NULL) der Workflow-Ersteller (Zapier/Make-Semantik). Fehlt eine gültige Verbindung oder Berechtigung (403 von der API), schlägt der Knoten mit einer Hinweis-Meldung auf /integrations fehl.
Microsoft (Graph)
| Endpoint | Berechtigung | Wichtige Config-Felder | Output |
|---|---|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| Adaptive Card an Teams-Incoming-Webhook | — (Webhook-URL ist das Credential) |
|
|
teams_card löst das verwaltete, company-gescopte Ziel auf und entschlüsselt dessen Webhook-URL; ein Button wird nur bei gültiger http(s)-URL hinzugefügt.
| Endpoint | Berechtigung | Wichtige Config-Felder | Output |
|---|---|---|---|---|
| Drive v3 Multipart-Upload |
|
|
|
| Calendar v3 |
|
|
|
| Sheets v4 |
|
|
|
forward-Modus (OneDrive/Google Drive/save_to_storage) holt die Bytes über source_node_slug aus dem Output eines doc_render-Knotens — die typische Kette ist llm → doc_render → *_upload.
Run-Status-Werte
Status | Bedeutung |
|---|---|
| In Warteschlange / läuft |
| Abgeschlossen / fehlgeschlagen / abgebrochen |
| Pausiert in |
| Pausiert in |
| Pausiert vor einem |
Run-Node-Status: pending, running, completed, failed, skipped. Nicht erreichte pending-Knoten werden am Run-Ende auf skipped gesetzt.