Cron-Jobs
Zweck
CronJob modelliert wiederkehrende Aufgaben in SpeamCore. Pro Job wird ein Cron-Schedule (schedule, klassisches Cron-Format), eine Zeitzone (timezone, IANA), ein Aktiv-Flag (enabled) und der polymorphe Parent (parentType/parentId) gepflegt. Backend nutzt BullMQ + Redis zur Ausführung; ein Lock-Mechanismus (lockedBy, lockedAt) verhindert Doppellauf.
CronJobs werden typischerweise nicht direkt erstellt, sondern durch Modul-Workflows referenziert — z. B. erzeugt eine wiederkehrende Ausgabe automatisch einen CronJob für monatliche Buchungs-Erzeugung.
Voraussetzungen
Berechtigungen (CASL)
| Action | Subject | Wirkung | Keycloak-Rolle |
|---|---|---|---|
view | FE_CronJob, CronJob | Liste/Detail aufrufbar | — |
create/update/delete | CronJob | Pflegen | APP_SPEAMCORE_CREATE/UPDATE/DELETE_CRON_JOB |
do | RunCronJob | Manueller „Run Now"-Aufruf | APP_SPEAMCORE_DO_RUN_CRON_JOB |
Schritt-für-Schritt-Anleitung
Eigenen CronJob anlegen
- Cron-Jobs (
/cron-jobs) → + Neu. nameunddescriptionpflegen.- Schedule über
cronSchedule-Field — Cron-Notation (z. B.0 3 * * *für „täglich um 3 Uhr"). timezonewählen — IANA-Liste ausIntl.supportedValuesOf("timeZone").enabled = truesetzen, damit der Job durch den Worker ausgeführt wird.
Last-Run-Status prüfen
Liste zeigt lastRunAt, lastRunStatus (success, failed) und lastRunError. Bei Fehler ist die Detail-Sicht der schnellste Weg zum Stack-Trace.
Manueller Lauf
Bei Berechtigung do:RunCronJob ist ein Button Jetzt ausführen sichtbar — POST /api/cron-jobs/:id/run-now.
Felder und Eingaben
| Feldname | Pflicht | Datentyp | Wirkung beim Ausfuellen | Voraussetzung |
|---|---|---|---|---|
name | nein | String | Anzeigename. | — |
description | nein | TEXT | Erlaeuterung. | — |
schedule | nein | String (Cron) | Cron-Schedule (z. B. 0 0 * * *). | Gueltige Cron-Notation. |
timezone | nein | String (IANA) | Zeitzone der Ausführung. | — |
enabled | ja | Boolean | Aktiv-Flag. | — |
parentId/parentType | nein | Polymorph | Verknuepfung zu auslоsendem Modell (z. B. Expense). | — |
lockedBy, lockedAt | nein (read-only) | String / DateTime | Lock-Mechanismus zur Vermeidung von Doppellauf. | — |
lastRunAt | nein (read-only) | DateTime | Zeit des letzten Laufs. | — |
lastRunStatus | nein (read-only) | String | success / failed. | — |
lastRunError | nein (read-only) | TEXT | Fehler-Details. | — |
Wiederverwendbare Konzepte
Verknuepfungen zu anderen Modulen
- Ausgaben — wiederkehrende Ausgaben referenzieren
cronJobIdfür monatliche Erzeugung. - Notification-Events — koennen über CronJobs ausgeloest werden.
- Datentransfer — automatische Exporte koennen über CronJobs laufen.
Häufige Fehler und Lösungen
| Fehler | Lösung |
|---|---|
Job laeuft nicht trotz enabled = true | Worker-Prozess (BullMQ) nicht aktiv oder Redis nicht erreichbar. |
lastRunStatus = failed permanent | lastRunError einsehen, Backend-Logs durchsuchen. |
| Lock haengt | lockedBy/lockedAt manuell zuruecksetzen, falls Worker abgestuerzt ist. |
| Doppellauf | Lock-Mechanismus prüfen — lockedBy sollte beim Lauf gesetzt sein. |
API/Schnittstellen
| Methode | Endpoint | Zweck | CASL |
|---|---|---|---|
GET | /api/cron-jobs | Liste | view CronJob |
POST | /api/cron-jobs | Anlegen | create CronJob |
GET | /api/cron-jobs/:id | Detail | view CronJob |
PATCH | /api/cron-jobs/:id | Ändern | update CronJob |
DELETE | /api/cron-jobs/:id | Soft-Delete | delete CronJob |
POST | /api/cron-jobs/:id/run-now | Manueller Lauf | do RunCronJob |
Versionshinweise
- 2026-04-30: Initiale Veroeffentlichung.