Scheduled Jobs with Recurring Workflows
Periodic tasks like daily reports, nightly syncs, and cache warming use a recurring workflow pattern: the workflow does its work, then sleeps until the next scheduled time using a durable timer. Unlike external cron schedulers, the sleep survives process restarts and cluster failovers — if the worker is down at the scheduled time, the job runs as soon as it comes back up.
How it works
Orcher gives you two ways to run work on a schedule, and the right one depends on whether the runs need to remember each other. The mechanics of the timer loop — the suspended sleep, surviving deploys mid-sleep — are covered in scheduled sync; this page focuses on the choice.
State carries across iterations (watermarks, counters). Cadence is code, so it can be conditional. Serial by construction — a slow run delays the next, never overlaps it.
Cron expression + timezone, each tick starts a new execution. Pause, resume, and retune from the API without touching workers. Overlap is a policy: skip, queue, or allow.
Example: a recurring daily report
1import {2 Workflow,3 Tasks,4 Task,5 WorkflowContext,6 createTaskRefs,7} from '@orcher/sdk';89@Tasks()10class ReportTasks {11 @Task()12 async collectMetrics(): Promise<MetricsData> {13 const dbStats = await db.queryDailyStats();14 const apiStats = await monitoring.queryApiLatency();15 return { dbStats, apiStats };16 }1718 @Task()19 async generateReport(data: MetricsData): Promise<string> {20 const pdf = reportBuilder.buildDailyReport(data);21 return await storage.upload('reports', pdf);22 }2324 @Task()25 async sendReportEmail(input: ReportEmailInput): Promise<void> {26 await emailClient.send(27 input.recipients,28 'Daily Report',29 `Report available at: ${input.reportUrl}`,30 );31 }32}3334const tasks = createTaskRefs(ReportTasks);3536// Recurring daily report — runs once, sleeps 24h, repeats37@Workflow({ name: 'daily_report', version: '1.0.0' })38class DailyReport {39 async run(ctx: WorkflowContext, config: ReportConfig): Promise<void> {40 while (true) {41 // Collect and generate42 const data = await ctx.executeTask(tasks.collectMetrics, undefined);43 const reportUrl = await ctx.executeTask(tasks.generateReport, data);4445 // Distribute46 await ctx.executeTask(tasks.sendReportEmail, {47 recipients: config.recipients,48 reportUrl,49 });5051 // Sleep until tomorrow 9 AM (durable timer)52 await ctx.sleep(24 * 60 * 60 * 1000);53 }54 }55}Start this workflow once and it runs forever. The ctx.sleep() at the end of each iteration is a durable timer — if the worker restarts during the 24-hour wait, the timer picks up where it left off. You can also trigger an immediate run by starting a new workflow execution via the CLI: orcher workflow run daily_report --input '{}'.
Alternative: Cron Schedules
For standard cron jobs that don't need to carry state between iterations, use the Schedule API instead. Create a schedule via the REST API and the platform triggers new workflow executions on the cron cadence — no long-running workflow needed:
1POST /api/v1/schedules2{3 "name": "nightly-report",4 "cronExpression": "0 0 2 * * *",5 "timezone": "UTC",6 "taskTemplate": {7 "workflowType": "daily_report",8 "taskQueue": "reports",9 "input": { "recipients": ["team@example.com"] }10 },11 "overlapPolicy": "skip"12}Schedules can be paused, resumed, and managed independently of worker deployments. Use the durable timer loop (above) when you need state across iterations or complex scheduling logic.
Design notes
- Fixed sleeps drift.
sleep(24h)fires 24 hours after the work finishes, not at the same time each day — a 5-minute report pushes every subsequent run 5 minutes later. To anchor to a wall-clock time, compute the delta to the next 9 AM before each sleep, or use the Schedule API's cron expression and timezone, which exist for exactly this. - Bound the loop. The example's
loop {}runs forever, and every iteration appends journal entries. Stop after N iterations and restart with the final state — the same journal-growth reasoning as scheduled sync. - Overlap is impossible in the loop, a policy in the Schedule. The loop can't start run N+1 before run N finishes — slow work delays the schedule but never doubles it. Schedule-API runs are independent, so say what you want:
"overlapPolicy": "skip"drops a tick that would overlap a still-running job. - Late beats lost. If the platform is down at the scheduled moment, the timer fires on recovery and the run happens late — unlike cron, where a missed tick is simply gone. If a late report is worse than no report, check the time at the start of the run and skip when the window has passed.