CronJobs API

The CronJobs API drives scheduled automation. A separate job-worker container executes the jobs (cron/interval, distributed locking, multi-instance) — from simple automations (create/update ticket, webhook, assignment) to the system monitors (SLA monitor, escalation and cleanup jobs). There are 28 action types and 23 built-in templates.

Architecture

Backend API (/api/cronjobs)         CRUD, RBAC, audit, config        │  persists CronJob/JobExecution in Postgres        ▼
job-worker (separate container)
  • Scheduler             — cron/interval  • Queue (BullMQ)        — execution queue  • 28 action types  • Distributed Lock (Redis): cronjob:lock:{jobId}
  • Heartbeat (15s)       — multi-instance detection / worker status  • Restricted DB access: only CronJob/JobExecution        │
        ▼  mutations via backend internal API, notifications via notification-worker

Endpoints

Job Management /api/cronjobs

GET / and GET /:id additionally accept ?includeDeleted=true to include soft-deleted jobs — this requires the dedicated permission cronjobs.viewDeleted (otherwise 403).

Restoring requires two permissions: cronjobs.restore for the action and cronjobs.viewDeleted for access to the trash — whoever may not see the trash cannot pull anything out of it. No other mutation applies to a deleted job: update, enable/disable, manual run, dry run, bulk actions and retrying an execution all answer 404 while it sits in the trash. The execution history survives the deletion — visible, but not repeatable.

Execution & History

Workers & Config

Data Model

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
}

Triggers

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

Action Types (28)

Automation

Monitors & Escalation

Maintenance / Cleanup

Boundary rule: time-based retention of database rows runs via retention_purge — one place for all periods; anything touching files or virus scans stays with attachment_cleanup. Escalation runs via sla_monitor and lifecycle_stale_entity_reminder, capacity via workload_sync, return reminders via handover_return_reminder.

Built-in Templates (23)

GET /api/cronjobs/templates/list — returns preconfigured templates (fields: id, name, description, category, isBuiltIn, tags, template). For each template the backend start creates the matching built-in job if it is missing — ENABLED, except Asset Model Deduplication, which starts DISABLED because it depends on the features in use. The lifecycle jobs only take effect once the admin activates them per entity in the lifecycle config; the digest job only takes effect once users have chosen the digest; the Entra ID sync only takes effect once the Entra ID integration is configured and active. Schedules:

Built-in jobs: created automatically at start

The built-in jobs are reconciled on every backend start: missing built-in jobs are created from their template (ENABLED or DISABLED per default, see above), existing jobs are NEVER changed. Admin-changed schedules, parameters and the enabled status are therefore preserved. An update brings new standard jobs along without a manual step.

Create Job

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 is the PAGE SIZE, not the ceiling of a run: the monitor pages through the due backlog until nothing is left. If it does stop early (a guard against endless runs), the job result and the log say so.

// 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"
}

New jobs start as DISABLED — enable via PATCH /:id/toggle (cronjobs.enableDisable).

Execution, 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 Values

Self-Healing

Jobs are (partially) self-healing — a job does not stay stuck permanently:

• ERROR is not terminal: ERROR only means "last run failed". The job stays active, keeps being scheduled (nextRunAt is recomputed) and heals back on the next successful run.
• No jobs stuck in RUNNING: On error/timeout the distributed lock is released; a job does not get stuck falsely in RUNNING.
• Catch-up on (re)start: On job-worker startup, overdue jobs (nextRunAt in the past) are detected, queued as a PENDING execution and rescheduled — they do not stay "overdue forever". A distributed lock ensures only ONE instance runs the catch-up.
• runOnStartup: Jobs with this flag (e.g. SLA Monitor) get an execution on every worker start.
• Orphan-Cleanup: Jobs present in the queue (BullMQ) but deleted from the DB are removed on startup.

"Partially self-healing": the underlying failure cause is not resolved automatically — the job simply retries on its next schedule (or within a run up to maxRetries) and leaves the ERROR state on success. Persistent failures should be inspected via execution history/activity.

Worker Management

Multiple job-worker instances register via heartbeat (instanceId). GET /workers/status returns health (null when offline) and executions per instance; the queue counters are their own field queue inside health — waiting, active, completed, failed, delayed — and are null while the instance queue is not yet initialized. For maintenance, workers can be paused (globally or per instance). Pause/resume is a critical, audited action and requires a reason (min. 10 chars).

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

Filters & Run Conditions

filters scope the target entities; runConditions are additional preconditions. A runCondition carries exactly type + duration (minimum age in minutes) — type is ticket_age or change_pending_approval.

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

ticketStatuses and ticketPriorities accept only valid ticket statuses and priorities; an empty list acts as no filter, an unknown value makes the condition check fail — the job is then not triggered. ticket_age counts tickets older than duration that match the filters; change_pending_approval counts changes in status PENDING_APPROVAL and does not evaluate the filters. Both conditions are met as soon as at least one record matches.

Webhook Security

• SSRF: blocks 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) + configurable timeout

Error Codes

GLOBAL_PAUSE_ACTIVE: while a global worker pause is active, no single instance can be resumed — the global pause has to be lifted as a whole first (resume-all).