Workflows & Automationen

Die Workflow-API verwaltet die mandanten-eigenen Automationen — Definitionen schreiben, Läufe starten, Run-Historie lesen. Hintergrund unter Workflows & Automationen.

Alle Endpoints erfordern die Permission workflow_manage (oder admin_bypass).

Resources

Definition anlegen

curl -X POST "https://os.codemeta.de/api/v1/workflows" \
  -H "X-Tenant-Id: $TENANT" \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "name": "Auto-Assign neuer High-Priority-Tickets",
    "description": "Wenn ein Ticket mit priority=high erstellt wird, schicke Notification an On-Call",
    "triggers": [
      {
        "type": "event",
        "entityType": "tickets",
        "operation": "CREATE",
        "conditions": [{ "field": "priority", "operator": "eq", "value": "high" }]
      }
    ],
    "steps": [
      {
        "id": "notify",
        "action": "send-notification",
        "params": {
          "recipientType": "role",
          "recipientValue": "on-call",
          "subject": "Neues High-Priority-Ticket: {{entity.title}}"
        }
      }
    ],
    "isActive": true,
    "priority": "NORMAL"
  }'

Wichtige Felder:

Body-Limit ist 10 MB — Workflows mit code-Steps können größere Snippets enthalten.

Trigger-Typen

// Event-Trigger
{ "type": "event", "entityType": "tickets", "operation": "UPDATE",
  "conditions": [{ "field": "status", "operator": "changed_to", "value": "RESOLVED" }] }

// Manueller Trigger mit Eingabe-Feldern
{ "type": "manual", "scope": "global",
  "inputFields": [
    { "key": "customerEmail", "type": "string", "label": "E-Mail", "required": true }
  ] }

// Cron-Trigger (Default-Tz Europe/Berlin)
{ "type": "cron", "cronExpression": "0 9 * * 1-5" }

// Webhook-Trigger
{ "type": "webhook",
  "webhookMethods": ["POST"],
  "webhookResponseMode": "immediate",
  "webhookAuth": { "type": "hmac" },
  "webhookRateLimit": { "max": 60, "windowSeconds": 60 },
  "webhookAllowedIps": [{ "kind": "manual", "value": "203.0.113.0/24" }] }

Trigger bekommen automatisch eine id (UUID), wenn keine mitgegeben wird.

Validierung & Fehler

Bei Permissions-Fehler enthält detail die Liste der fehlenden Permissions; bei Modul-Fehler steht missingModules am Body.

Definition lesen

curl "https://os.codemeta.de/api/v1/workflows?includeInactive=true" \
  -H "X-Tenant-Id: $TENANT" \
  -b cookies.txt

Default sind nur aktive Workflows in der Liste. Sortierung nach name, hard-cap 1000 Treffer (kein Cursor — Workflows sind selten so viele).

Manuell ausführen

curl -X POST "https://os.codemeta.de/api/v1/workflows/<id>/execute" \
  -H "X-Tenant-Id: $TENANT" \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "inputs": { "customerEmail": "alice@example.com" },
    "triggerId": "0192f2c0-…"
  }'

Optionale Felder:

Antwort: 202 Accepted mit instanceId und Status QUEUED.

{
  "instanceId": "0192f2c0-…",
  "workflowDefinitionId": "0192f2c0-…",
  "status": "QUEUED",
  "triggerId": "0192f2c0-…"
}

Die Ausführung passiert asynchron im Worker.

Run-Liste

curl "https://os.codemeta.de/api/v1/workflows/<id>/instances?limit=50" \
  -H "X-Tenant-Id: $TENANT" \
  -b cookies.txt

Die Liste ist nach startedAt absteigend sortiert (max. 100 pro Aufruf) und spart die schweren Felder (items, variables, stepHistory.output) aus. Für volle Detail-Daten den nächsten Endpoint nehmen.

Run-Detail

GET /api/v1/workflow-instances/<instanceId> liefert die volle Instance inklusive items, stepHistory[].output und variables. Sinnvoll für eine „Workflow-Run-Inspector”-UI.

Run abbrechen

curl -X POST "https://os.codemeta.de/api/v1/workflow-instances/<instanceId>/cancel" \
  -H "X-Tenant-Id: $TENANT" \
  -b cookies.txt

Funktioniert nur, solange der Lauf in QUEUED, RUNNING oder WAITING ist. Setzt status: CANCELLED, schreibt den User-Namen in error („Abgebrochen von …”) und schließt die completedAt-Zeit.

Webhook-Secrets

Webhook-Trigger mit webhookAuth.type: "hmac" | "bearer" brauchen ein Secret. Die Plattform speichert das Secret nur gehashed — beim Generieren gibt sie den Klartext einmal zurück:

curl -X POST "https://os.codemeta.de/api/v1/workflows/<id>/triggers/<triggerId>/webhook-secret" \
  -H "X-Tenant-Id: $TENANT" \
  -b cookies.txt

{
  "secret": "0aBcD…43chars",
  "secretRef": "0192f2c0-…"
}

Notieren Sie den secret-Wert sofort — ein zweiter Aufruf rotiert das Secret (altes wird gelöscht), nicht angezeigt. Empfänger-seitig HMAC verifizieren bzw. als Bearer-Token mitschicken; Details unter Webhook-Ingress.

DELETE auf denselben Pfad entfernt das Secret und setzt secretRef im Trigger zurück.

Run-Archive (S3)

Nach Ablauf der DB-Retention werden Runs (sofern archive.enabled) als JSON nach S3 ausgelagert und in automation_run_archives indiziert.

curl "https://os.codemeta.de/api/v1/workflow-archives?workflowDefinitionId=<id>&limit=50" \
  -H "X-Tenant-Id: $TENANT" \
  -b cookies.txt

GET /workflow-archives/<id> lädt Metadaten plus den Payload aus S3 (joined). GET /workflow-archives/<id>/download liefert eine Presigned-URL mit 5 Min. Gültigkeit für den direkten Download.

Verwandt

• Workflows als Konzept
• Transitions-API — der Layer darunter
• Webhook-Ingress — Empfangsseite externer Webhooks
• Webhooks (Outbound) — was die Plattform selbst sendet
• Konventionen — generische CRUD-Verträge