API · v1 · stabil
CODEMETA OSDeveloper Center
Konsole öffnen
Konzept

Workflows & Automationen

Lesedauer · 10 Min.Aktualisiert · 2026-05-01

Workflows sind Codemeta OS’ Engine für automatisierte Abläufe — ähnlich wie n8n oder Zapier, aber mandantenintern und mit direktem Zugriff auf Ihre Plattform-Daten. Eine Workflow-Definition besteht aus Triggern, Steps und Edges; jeder Lauf ist eine Workflow-Instance.

Die UI lebt in der Plattform unter „Workflows“; das Datenmodell und die REST-API sind unter /api/workflows dokumentiert.

Workflow-Definition vs. Instance

Konzept Collection Bedeutung
Definition workflow_definitions Bauplan: Trigger + Steps + Edges
Instance workflow_instances Konkreter Lauf einer Definition (Run-History)
Run-Archive automation_run_archives Nach DB-Retention zu S3 ausgelagerte Runs

Eine Definition ist versioniert (version++ pro Update) und kann aktiv oder pausiert sein (isActive). System-Workflows kommen aus Codemeta selbst und sind nicht löschbar — sie können aber pausiert oder modifiziert werden.

Trigger — wann ein Workflow startet

Ein Workflow hat mindestens einen Trigger, kann aber mehrere haben (z. B. manuell + cron). Trigger-Typen:

type Wann es feuert
event Auf Codemeta-Entity-Änderungen (CREATE/UPDATE/DELETE)
manual Auf einen manuellen „Execute“-Klick
cron Auf einer Cron-Expression (Default-Tz Europe/Berlin)
webhook Auf eingehenden HTTP-Request unter /automations/webhook/<id>

Bei event-Triggern filtert man auf entityType (z. B. tickets), operation (z. B. UPDATE) und beliebige conditions über field/operator/value. Bei Integrations-Triggern (z. B. ein Salesforce- Webhook) registriert die Plattform den externen Webhook automatisch beim Provider.

Webhook-Trigger im Detail

Webhook-Trigger haben eine eigene URL, eine Auth-Konfiguration (none, hmac oder bearer) und ein optionales IP-Allowlist (manuelle Werte oder Referenzen auf Parties/Assets). Das Geheimnis wird einmalig beim Generieren angezeigt — danach nie wieder lesbar. Mehr unter Webhook-Ingress.

Steps — die Bausteine

Ein Step hat eine action, einen Eindeutigen id, freie params und einen next. Auswahl der eingebauten Actions:

Action Zweck
create-entity Neue Entity anlegen (z. B. Ticket aus Lead)
change-field Feld einer existierenden Entity setzen
lookup-entity Entity per ID/Filter laden
lookup-table Statisches Mapping anwenden
send-email Transaktionsmail aus Template
send-notification In-App-Notification
http-request Outbound-HTTP-Call
webhook Outbound-Webhook gegen registrierte Receiver
if-else 2-Branch-Verzweigung
switch n-Branch-Verzweigung
loop Sub-Graph pro Item iterieren
wait Pause auf Datum, Dauer oder Entity-Event
code JavaScript-Snippet im Sandbox-VM
set-variables Items annotieren
aggregate-items Items zusammenfassen
extract-items / merge-items / split-batches Item-Pipeline-Operationen
transform-rows Tabellen-Style-Transform
parse-document Dokument-Parsing (CSV/PDF/…)
dms-fetch DMS-Inhalt laden
fetch-integration Drittsystem-API über Integration-Provider

Welche Actions konkret existieren, sehen Sie im Source unter apps/worker/src/actions/.

Items, n8n-Style

Steps verarbeiten Daten als items — ein Array von Records. Der Output eines Steps wird zum items des nächsten. Per default läuft ein Step einmal pro Item (runMode: 'each'); mit runMode: 'all' läuft er einmal mit allen Items zusammen.

outputKey legt den Output unter einem Key statt flach in variables ab — nützlich für {{steps.<ref>.<feld>}}-Templates.

Branches: if-else, switch, loop

  • if-else hat trueBranch und falseBranch mit Target-Step-IDs.
  • switch hat eine Liste branches[] mit Conditions; erste Match gewinnt, sonst fallback.
  • loop ist ein Container — Body-Steps tragen parentLoopId und sind aus dem Haupt-DAG ausgenommen. Der Runtime führt sie pro Item im loopConfig.itemsExpression einmal aus.

Trigger-Eingaben: inputs & inputFields

Manuelle und Webhook-Trigger können Eingaben definieren (inputFields[]): Text, Zahl, Datum, Boolean, Select, Entity-Picker. Beim Aufruf der Workflow-Instance landen die Werte als inputs.<key> in den Templating- Kontext aller Steps.

// In einem Step-Param-Wert
"{{ inputs.customerEmail }}"

Permissions & Lizenzen

Beim Speichern einer Definition prüft die Plattform zwei Dinge:

  1. Rechte des Editors: jeder Step-Action wird ein Permission-Set zugeordnet (z. B. ticket_create für create-entity auf tickets). Fehlt ein Recht, wird 403 zurückgegeben.
  2. Lizenzierte Module: referenziert ein Step ein Schema in einem Modul, das im Plan nicht enthalten ist (ADR 0081), wird 403 mit module-not-licensed zurückgegeben.

Außerdem gilt ein Tier-Quota auf die Anzahl aktiver Workflows pro Mandant; bei Überschreitung antwortet die API mit 429.

Run-Retention & S3-Archiv

Pro Workflow lässt sich konfigurieren, wie lange Run-Daten in MongoDB bleiben (retentionConfig.dbDays, 1–7) und ob sie danach nach S3 archiviert werden (retentionConfig.archive). Archive lassen sich über die Workflow-API auflisten und mit Presigned-URL als JSON herunterladen.

Manuelle Ausführung & Re-Run

POST /api/v1/workflows/<id>/execute startet einen Lauf manuell. Der Body kann:

  • inputs — Werte für inputFields
  • triggerId — falls die Definition mehrere Trigger hat
  • startFromStepId / stopAfterStepId — partielle Re-Runs
  • initialItems — als Items vorgemerkte Datensätze

Die Antwort enthält die instanceId, mit der man via SSE die Live-Logs mitlesen oder den Lauf abbrechen kann.

Verwandte Konzepte

Suche