CronJobs API

Die CronJobs API steuert geplante Automatisierung. Ein separater job-worker-Container führt die Jobs aus (Cron/Interval, Distributed Locking, Multi-Instance) — von einfachen Automatisierungen (Ticket erstellen/aktualisieren, Webhook, Zuweisung) bis zu den System-Monitoren (SLA-Monitor, Eskalations- und Cleanup-Jobs). Es gibt 28 Action-Typen und 23 Built-in-Templates.

Architektur

Backend API (/api/cronjobs)         CRUD, RBAC, Audit, Config        │  persistiert CronJob/JobExecution in Postgres        ▼
job-worker (separater Container)
  • Scheduler             — Cron/Interval  • Queue (BullMQ)        — Ausführungs-Warteschlange  • 28 Action-Typen  • Distributed Lock (Redis): cronjob:lock:{jobId}
  • Heartbeat (15s)       — Erkennung mehrerer Instanzen / Worker-Status  • Eingeschränkter DB-Zugriff: nur CronJob/JobExecution        │
        ▼  Mutationen über Backend-Internal-API, Notifications über notification-worker

Endpoints

Job-Verwaltung /api/cronjobs

GET / und GET /:id akzeptieren zusätzlich ?includeDeleted=true, um soft-gelöschte Jobs einzuschließen — das erfordert die eigene Permission cronjobs.viewDeleted (sonst 403).

Wiederherstellen verlangt zwei Rechte: cronjobs.restore für die Aktion und cronjobs.viewDeleted für den Zugriff auf den Papierkorb — wer den Papierkorb nicht sehen darf, holt auch nichts daraus zurück. Auf einem gelöschten Job wirkt sonst keine Mutation: Aktualisieren, Aktivieren/Deaktivieren, manuelles Ausführen, Dry-Run, Bulk-Aktionen und das Wiederholen einer Ausführung antworten mit 404, solange er im Papierkorb liegt. Die Ausführungs-Historie bleibt beim Löschen erhalten — sichtbar, aber nicht wiederholbar.

Ausführung & History

Worker & Config

Datenmodell

CronJob {
  id, name (unique),
  category: ESCALATION | NOTIFICATION | REPORTING | MAINTENANCE | MONITORING | WORKFLOW | CUSTOM,
  status:   ENABLED | DISABLED | RUNNING | ERROR,
  trigger:  Json,            // { type, schedule }
  actions:  Json,            // [{ type, parameters }]
  filters:  Json,            // entity scope (e.g. ticketStatuses)
  runConditions: Json,       // additional conditions
  dependencies: String[],    // job IDs that must succeed first
  timeoutMinutes, maxRetries, runOnStartup,
  lastExecutedAt, nextExecutionAt, executionCount, failureCount, avgDurationMs,
  createdById, deletedAt     // Soft-Delete
}

JobExecution {
  id, cronJobId,
  status:      PENDING | RUNNING | COMPLETED | FAILED | CANCELLED,
  triggeredBy: SCHEDULE | MANUAL | EVENT | CONDITION,
  startedAt, completedAt, durationMs, retryCount,
  results: Json,             // [{ action, status, metadata }]
  errorMessage?, workerId
}

Trigger

// Cron
{ "trigger": { "type": "cron", "schedule": { "cronExpression": "*/30 * * * *" } } }
// Interval
{ "trigger": { "type": "interval", "schedule": { "intervalMinutes": 5 } } }

Action-Typen (28)

Automatisierung

Monitore & Eskalation

Wartung / Cleanup

Grenzregel: Die zeitbasierte Aufbewahrung von Datenbank-Einträgen läuft über retention_purge — eine Stelle für alle Fristen; alles, was Dateien oder Virenscans anfasst, bleibt bei attachment_cleanup. Eskalation läuft über sla_monitor und lifecycle_stale_entity_reminder, Kapazität über workload_sync, Rückgabe-Erinnerungen über handover_return_reminder.

Built-in Templates (23)

GET /api/cronjobs/templates/list — liefert vorkonfigurierte Vorlagen (Felder: id, name, description, category, isBuiltIn, tags, template). Zu jeder Vorlage legt der Backend-Start den passenden Built-in-Job an, falls er fehlt — ENABLED, mit Ausnahme von Asset Model Deduplication, die DISABLED startet, weil sie vom genutzten Funktionsumfang abhängt. Die Lifecycle-Jobs wirken erst, wenn der Admin sie je Entität in der Lifecycle-Config aktiviert; der Digest-Job wirkt erst, wenn Benutzer den Digest gewählt haben; der Entra-ID-Sync wirkt erst, wenn die Entra-ID-Integration konfiguriert und aktiv ist. Schedules:

Built-in-Jobs: automatische Anlage beim Start

Die Built-in-Jobs werden bei jedem Backend-Start abgeglichen: Fehlende Built-in-Jobs werden anhand ihrer Vorlage angelegt (ENABLED oder DISABLED je Vorgabe, siehe oben), bestehende Jobs werden NIE verändert. Von Admins geänderte Zeitpläne, Parameter und der Aktiv-Status bleiben also erhalten. Ein Update bringt neue Standard-Jobs ohne manuellen Schritt mit.

Job erstellen

POST /api/cronjobs

{
  "name": "SLA Monitor - All Entities",
  "category": "ESCALATION",
  "description": "Check SLA deadlines and trigger escalations",
  "trigger": { "type": "interval", "schedule": { "intervalMinutes": 2 } },
  "actions": [ { "type": "sla_monitor", "parameters": { "entityType": null, "batchSize": 500 } } ],
  "timeoutMinutes": 5,
  "maxRetries": 3,
  "runOnStartup": true
}

batchSize ist die SEITENGRÖSSE, nicht die Obergrenze eines Laufs: der Monitor liest den fälligen Bestand seitenweise durch, bis nichts mehr folgt. Bricht er dennoch ab (Schutz gegen Endlosläufe), steht das im Job-Ergebnis und im Log.

// Response 201
{
  "id": "clx...",
  "name": "SLA Monitor - All Entities",
  "category": "ESCALATION",
  "status": "DISABLED",
  "trigger": { "type": "interval", "schedule": { "intervalMinutes": 2 } },
  "nextExecutionAt": null,
  "createdAt": "2026-01-27T23:00:00.000Z"
}

Neue Jobs starten als DISABLED — Aktivieren über PATCH /:id/toggle (cronjobs.enableDisable).

Ausführung, Dry-Run & Retry

# Run manually (cronjobs.executeManually)
POST /api/cronjobs/:id/execute        { "reason": "Testing config" }   # -> 202 { executionId }

# Dry-Run: shows affected entities, makes NO changes
POST /api/cronjobs/:id/dry-run

# Retry a failed execution (only status FAILED)
POST /api/cronjobs/executions/:id/retry   { "reason": "Network issue resolved" }

# History (filter jobId/status, pagination)
GET /api/cronjobs/executions/list?status=FAILED&limit=20

Status-Werte

Selbstheilung

Jobs sind (teil-)selbstheilend — ein Job bleibt nicht dauerhaft hängen:

• ERROR ist nicht terminal: Status ERROR bedeutet nur „letzter Lauf fehlgeschlagen". Der Job bleibt aktiv, wird weiter nach Schedule eingeplant (nextRunAt wird neu berechnet) und heilt beim nächsten erfolgreichen Lauf von selbst zurück.
• Kein Hängenbleiben in RUNNING: Bei Fehler/Timeout wird der Distributed-Lock freigegeben; ein Job bleibt nicht fälschlich in RUNNING hängen.
• Catch-up beim (Neu-)Start: Beim Start des job-workers werden überfällige Jobs (nextRunAt in der Vergangenheit) erkannt, als PENDING-Execution nachgeholt und neu terminiert — sie hängen nicht „Overdue für immer". Ein Distributed-Lock stellt sicher, dass nur EINE Instanz den Catch-up macht.
• runOnStartup: Jobs mit diesem Flag (z.B. SLA Monitor) erhalten bei jedem Worker-Start eine Ausführung.
• Orphan-Cleanup: In der Queue (BullMQ) vorhandene, in der DB aber gelöschte Jobs werden beim Start entfernt.

„Teil-selbstheilend": Die zugrunde liegende Fehlerursache wird nicht automatisch behoben — der Job versucht es lediglich beim nächsten Schedule (bzw. innerhalb eines Laufs bis maxRetries) erneut und verlässt den ERROR-Zustand bei Erfolg. Dauerhafte Fehler sollten über die Execution-History/Activity geprüft werden.

Worker-Management

Mehrere job-worker-Instanzen melden sich per Heartbeat (instanceId). GET /workers/status liefert pro Instanz health (null bei offline) und executions; die Queue-Zähler stehen als eigenes Feld queue unter health — waiting, active, completed, failed, delayed — und sind null, solange die Queue der Instanz noch nicht initialisiert ist. Für Wartung lassen sich Worker pausieren (global oder pro Instanz). Pause/Resume ist eine kritische, auditierte Aktion und verlangt einen Grund (reason, min. 10 Zeichen).

POST /api/cronjobs/workers/pause-all   { "reason": "Database maintenance window" }
# -> { "pausedWorkers": ["job-worker-abc123"], "failedWorkers": [] }

Filter & Run-Conditions

filters schränken die Ziel-Entities ein; runConditions sind zusätzliche Voraussetzungen. Ein runCondition trägt genau type + duration (Mindestalter in Minuten) — type ist ticket_age oder change_pending_approval.

{
  "filters": { "ticketStatuses": ["OPEN", "IN_PROGRESS"], "ticketPriorities": ["LOW", "MEDIUM"] },
  "runConditions": [ { "type": "ticket_age", "duration": 4320 } ]
}

In ticketStatuses und ticketPriorities sind nur gültige Ticket-Status bzw. -Prioritäten erlaubt; eine leere Liste wirkt wie kein Filter, ein unbekannter Wert lässt die Bedingungsprüfung fehlschlagen — der Job wird dann nicht ausgelöst. ticket_age zählt Tickets, die älter als duration sind und den Filtern entsprechen; change_pending_approval zählt Changes im Status PENDING_APPROVAL und wertet die Filter nicht aus. Beide Bedingungen sind erfüllt, sobald mindestens ein Datensatz zutrifft.

Webhook-Sicherheit

• SSRF: blockiert localhost, private IPs (10/172.16-31/192.168), Link-Local (169.254), Cloud-Metadata (169.254.169.254)
• Circuit Breaker + Rate-Limit + Retry (Exponential Backoff) + konfigurierbares Timeout

Fehlercodes

GLOBAL_PAUSE_ACTIVE: Solange eine globale Worker-Pause aktiv ist, lässt sich keine einzelne Instanz fortsetzen — die globale Pause muss zuerst als Ganzes aufgehoben werden (resume-all).