Getting Started

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.

Timer Loop vs. Schedule API
Durable-timer loop
One workflow that remembers

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.

Schedule API
Fresh run per tick

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.

Need memory between runs? Loop. Need wall-clock cron and ops control? Schedule.

Example: a recurring daily report

1
import {
2
Workflow,
3
Tasks,
4
Task,
5
WorkflowContext,
6
createTaskRefs,
7
} from '@orcher/sdk';
8
9
@Tasks()
10
class 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
}
17
18
@Task()
19
async generateReport(data: MetricsData): Promise<string> {
20
const pdf = reportBuilder.buildDailyReport(data);
21
return await storage.upload('reports', pdf);
22
}
23
24
@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
}
33
34
const tasks = createTaskRefs(ReportTasks);
35
36
// Recurring daily report — runs once, sleeps 24h, repeats
37
@Workflow({ name: 'daily_report', version: '1.0.0' })
38
class DailyReport {
39
async run(ctx: WorkflowContext, config: ReportConfig): Promise<void> {
40
while (true) {
41
// Collect and generate
42
const data = await ctx.executeTask(tasks.collectMetrics, undefined);
43
const reportUrl = await ctx.executeTask(tasks.generateReport, data);
44
45
// Distribute
46
await ctx.executeTask(tasks.sendReportEmail, {
47
recipients: config.recipients,
48
reportUrl,
49
});
50
51
// 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:

1
POST /api/v1/schedules
2
{
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.

Next Steps