Skip to main content

0043: Workflow Scheduled and Recurring Tasks

Date: 2025-11-08

Status: Proposed

Context​

The Citadel platform requires the ability to run recurring, time-based background jobs (i.e., cron jobs). Examples include generating nightly reports, cleaning up temporary data, or syncing with external systems on a schedule.

We could build a dedicated "Cron Job Service" to manage these tasks. However, this would introduce another microservice to maintain and would separate the logic for scheduled tasks from other long-running business processes, which are already handled by the workflow-service.

Our chosen workflow engine, Temporal (ADR-0039), has robust, built-in support for scheduling workflows with cron expressions.

Decision​

We will implement all scheduled and recurring tasks as Scheduled Workflows within the Temporal engine.

We will explicitly decide against building a separate, dedicated "Cron Job Service". The workflow-service will be responsible for defining and deploying these scheduled workflow definitions to the Temporal cluster. The Temporal UI will be the primary tool for observing and managing these scheduled tasks.

Consequences​

Positive​

  • Unified Orchestration: All business logic, whether user-triggered or time-triggered, is managed, monitored, and executed by a single, consistent system (Temporal).
  • Reduced Complexity: Avoids the operational overhead of building, deploying, and maintaining a separate service just for scheduling.
  • Excellent Observability: We can use the standard Temporal UI to monitor the execution history, status, and logs of scheduled jobs, just like any other workflow.
  • Reliability: Scheduled tasks automatically benefit from Temporal's built-in durability, retry policies, and error handling capabilities.

Negative​

  • Centralized Dependency: All scheduled tasks across the platform become dependent on the availability of the central Temporal cluster. This is an acceptable trade-off for the operational simplicity gained.
  • Discovery: Developers must know that cron job definitions reside within the workflow-service repository, not a separate "cron" service. This can be mitigated with clear documentation.