0
# Schedule Management
1

2
Manage scheduled workflow executions with flexible calendar-based and interval-based scheduling configurations, supporting complex scheduling patterns and backfill operations.
3

4
## Capabilities
5

6
### ScheduleClient
7

8
Client for creating and managing scheduled workflow executions.
9

10
```typescript { .api }
11
/**
12
 * Client for schedule operations
13
 */
14
class ScheduleClient extends BaseClient {
15
  /** Create new schedule */
16
  create<A extends any[]>(options: ScheduleOptions<A>): Promise<ScheduleHandle>;
17

18
  /** Get handle to existing schedule */
19
  getHandle(scheduleId: string): ScheduleHandle;
20

21
  /** List schedules with optional filtering */
22
  list(options?: ListScheduleOptions): AsyncIterable<ScheduleSummary>;
23

24
  /** Raw gRPC access to WorkflowService */
25
  readonly workflowService: WorkflowService;
26
}
27

28
interface ScheduleClientOptions extends BaseClientOptions {
29
  namespace?: string;
30
  dataConverter?: DataConverter;
31
  interceptors?: ScheduleClientInterceptor[];
32
}
33
```
34

35
**Usage Examples:**
36

37
```typescript
38
import { ScheduleClient } from "@temporalio/client";
39

40
const scheduleClient = new ScheduleClient();
41

42
// Create daily backup schedule
43
const handle = await scheduleClient.create({
44
  scheduleId: 'daily-backup',
45
  spec: {
46
    calendars: [{
47
      hour: [2], // 2 AM
48
      dayOfWeek: [], // Every day
49
    }],
50
  },
51
  action: {
52
    type: 'startWorkflow',
53
    workflowType: 'backup-data',
54
    args: ['full-backup'],
55
    taskQueue: 'backup-queue',
56
  },
57
});
58

59
// List all schedules
60
for await (const schedule of scheduleClient.list()) {
61
  console.log(`Schedule: ${schedule.scheduleId}, State: ${schedule.info.paused ? 'Paused' : 'Active'}`);
62
}
63
```
64

65
### ScheduleHandle
66

67
Handle for interacting with a single schedule.
68

69
```typescript { .api }
70
/**
71
 * Handle to single schedule instance
72
 */
73
interface ScheduleHandle {
74
  /** Schedule identifier */
75
  readonly scheduleId: string;
76
  /** Reference to ScheduleClient */
77
  readonly client: ScheduleClient;
78

79
  /** Get schedule description */
80
  describe(): Promise<ScheduleDescription>;
81

82
  /** Update schedule configuration */
83
  update<W extends Workflow = Workflow>(
84
    updateFn: (previous: ScheduleDescription) => ScheduleUpdateOptions<ScheduleOptionsStartWorkflowAction<W>>
85
  ): Promise<void>;
86

87
  /** Delete schedule */
88
  delete(): Promise<void>;
89

90
  /** Trigger immediate execution */
91
  trigger(overlap?: ScheduleOverlapPolicy): Promise<void>;
92

93
  /** Backfill schedule over time periods */
94
  backfill(options: Backfill | Backfill[]): Promise<void>;
95

96
  /** Pause schedule */
97
  pause(note?: string): Promise<void>;
98

99
  /** Unpause schedule */
100
  unpause(note?: string): Promise<void>;
101
}
102
```
103

104
**Usage Examples:**
105

106
```typescript
107
// Get schedule handle and describe
108
const handle = scheduleClient.getHandle('daily-backup');
109
const description = await handle.describe();
110
console.log('Next runs:', description.info.nextActionTimes.slice(0, 3));
111

112
// Update schedule to run every 2 hours
113
await handle.update({
114
  schedule: {
115
    spec: {
116
      intervals: [{
117
        every: '2h',
118
      }],
119
    },
120
  },
121
});
122

123
// Pause schedule temporarily
124
await handle.pause('Maintenance window');
125

126
// Trigger immediate execution
127
await handle.trigger({ overlap: ScheduleOverlapPolicy.ALLOW_ALL });
128

129
// Backfill missed executions
130
await handle.backfill([{
131
  startTime: new Date('2023-01-01'),
132
  endTime: new Date('2023-01-07'),
133
  overlap: ScheduleOverlapPolicy.SKIP,
134
}]);
135
```
136

137
### Schedule Configuration
138

139
Options and types for creating and updating schedules.
140

141
```typescript { .api }
142
/**
143
 * Options for creating schedules
144
 */
145
interface ScheduleOptions<A extends any[]> {
146
  /** Schedule identifier */
147
  scheduleId: string;
148
  /** Schedule specification */
149
  spec: ScheduleSpec;
150
  /** Action to perform when scheduled */
151
  action: ScheduleAction<A>;
152
  /** Schedule policies */
153
  policies?: SchedulePolicies;
154
  /** Initial schedule state */
155
  state?: ScheduleState;
156
  /** Memo for the schedule */
157
  memo?: Record<string, any>;
158
  /** Search attributes */
159
  searchAttributes?: SearchAttributes;
160
}
161

162
/**
163
 * Options for updating schedules
164
 */
165
interface ScheduleUpdateOptions<A extends any[]> {
166
  /** Updated schedule configuration */
167
  schedule: {
168
    spec?: ScheduleSpec;
169
    action?: ScheduleAction<A>;
170
    policies?: SchedulePolicies;
171
    state?: ScheduleState;
172
    memo?: Record<string, any>;
173
    searchAttributes?: SearchAttributes;
174
  };
175
}
176

177
/**
178
 * Options for listing schedules
179
 */
180
interface ListScheduleOptions {
181
  /** Maximum number of schedules to return */
182
  pageSize?: number;
183
  /** Namespace to search in */
184
  namespace?: string;
185
}
186

187
/**
188
 * Options for triggering schedules immediately
189
 */
190
interface TriggerImmediatelyOptions {
191
  /** Overlap policy for immediate trigger */
192
  overlap?: ScheduleOverlapPolicy;
193
}
194
```
195

196
### Schedule Specifications
197

198
Define when schedules should trigger using calendar or interval patterns.
199

200
```typescript { .api }
201
/**
202
 * Complete schedule specification
203
 */
204
interface ScheduleSpec {
205
  /** Calendar-based scheduling */
206
  calendars?: CalendarSpec[];
207
  /** Interval-based scheduling */
208
  intervals?: IntervalSpec[];
209
  /** Cron expressions (alternative to calendars/intervals) */
210
  cronExpressions?: string[];
211
  /** Exclude certain times */
212
  excludeCalendars?: CalendarSpec[];
213
  /** Start time constraint */
214
  startTime?: Date;
215
  /** End time constraint */
216
  endTime?: Date;
217
  /** Jitter for randomizing execution times */
218
  jitter?: string | number;
219
  /** Timezone for calendar specs */
220
  timeZone?: string;
221
}
222

223
/**
224
 * Calendar-based schedule specification
225
 */
226
interface CalendarSpec {
227
  /** Seconds (0-59) */
228
  second?: number[];
229
  /** Minutes (0-59) */
230
  minute?: number[];
231
  /** Hours (0-23) */
232
  hour?: number[];
233
  /** Day of month (1-31) */
234
  dayOfMonth?: number[];
235
  /** Month (1-12) */
236
  month?: number[];
237
  /** Year */
238
  year?: number[];
239
  /** Day of week (0=Sunday, 6=Saturday) */
240
  dayOfWeek?: number[];
241
  /** Additional comment */
242
  comment?: string;
243
}
244

245
/**
246
 * Interval-based schedule specification
247
 */
248
interface IntervalSpec {
249
  /** Interval between executions */
250
  every: string | number;
251
  /** Offset from interval boundary */
252
  offset?: string | number;
253
}
254

255
/**
256
 * Description version of ScheduleSpec
257
 */
258
type ScheduleSpecDescription = {
259
  calendars?: CalendarSpecDescription[];
260
  intervals?: IntervalSpecDescription[];
261
  cronExpressions?: string[];
262
  excludeCalendars?: CalendarSpecDescription[];
263
  startTime?: string;
264
  endTime?: string;
265
  jitter?: string;
266
  timeZone?: string;
267
};
268
```
269

270
### Schedule Actions & Policies
271

272
Define what happens when schedules trigger and how to handle conflicts.
273

274
```typescript { .api }
275
/**
276
 * Action to perform when schedule triggers
277
 */
278
type ScheduleAction<A extends any[]> = {
279
  type: 'startWorkflow';
280
  workflowType: string;
281
  args: A;
282
  taskQueue: string;
283
  workflowExecutionTimeout?: string | number;
284
  workflowRunTimeout?: string | number;
285
  workflowTaskTimeout?: string | number;
286
  retry?: RetryPolicy;
287
  memo?: Record<string, unknown>;
288
  searchAttributes?: SearchAttributes;
289
};
290

291
/**
292
 * Schedule execution policies
293
 */
294
interface SchedulePolicies {
295
  /** Policy for handling overlapping executions */
296
  overlap?: ScheduleOverlapPolicy;
297
  /** Policy for handling catchup after pause */
298
  catchupWindow?: string | number;
299
  /** Pause on workflow failure */
300
  pauseOnFailure?: boolean;
301
}
302

303
/**
304
 * Schedule state configuration
305
 */
306
interface ScheduleState {
307
  /** Optional note about the schedule */
308
  note?: string;
309
  /** Whether schedule is paused */
310
  paused?: boolean;
311
  /** Remaining actions before auto-pause */
312
  limitedActions?: number;
313
  /** Remaining runs before completion */
314
  remainingActions?: number;
315
}
316

317
/**
318
 * Constants for schedule overlap policies
319
 */
320
const ScheduleOverlapPolicy = {
321
  /** Skip execution if workflow is running */
322
  SKIP: 'SKIP',
323
  /** Buffer executions to run after current completes */
324
  BUFFER_ONE: 'BUFFER_ONE',
325
  /** Buffer all missed executions */
326
  BUFFER_ALL: 'BUFFER_ALL',
327
  /** Cancel running workflow and start new one */
328
  CANCEL_OTHER: 'CANCEL_OTHER',
329
  /** Terminate running workflow and start new one */
330
  TERMINATE_OTHER: 'TERMINATE_OTHER',
331
  /** Allow multiple concurrent executions */
332
  ALLOW_ALL: 'ALLOW_ALL',
333
} as const;
334

335
type ScheduleOverlapPolicy = typeof ScheduleOverlapPolicy[keyof typeof ScheduleOverlapPolicy];
336
```
337

338
### Schedule Data Types
339

340
Types for schedule information and execution results.
341

342
```typescript { .api }
343
/**
344
 * Schedule summary from list operations
345
 */
346
interface ScheduleSummary {
347
  /** Schedule identifier */
348
  scheduleId: string;
349
  /** Schedule information */
350
  info: ScheduleInfo;
351
  /** Memo associated with schedule */
352
  memo?: Memo;
353
  /** Search attributes */
354
  searchAttributes?: SearchAttributes;
355
}
356

357
/**
358
 * Detailed schedule description
359
 */
360
type ScheduleDescription = {
361
  /** Schedule identifier */
362
  scheduleId: string;
363
  /** Current schedule configuration */
364
  schedule: {
365
    spec: ScheduleSpecDescription;
366
    action: ScheduleActionDescription;
367
    policies: SchedulePolicies;
368
    state: ScheduleState;
369
  };
370
  /** Schedule runtime information */
371
  info: ScheduleInfo;
372
  /** Memo associated with schedule */
373
  memo?: Memo;
374
  /** Search attributes */
375
  searchAttributes?: SearchAttributes;
376
};
377

378
/**
379
 * Schedule runtime information
380
 */
381
interface ScheduleInfo {
382
  /** Number of actions taken */
383
  numActions: number;
384
  /** Number of actions skipped */
385
  numActionsMissedCatchupWindow: number;
386
  /** Number of actions skipped due to overlap */
387
  numActionsSkippedOverlap: number;
388
  /** Running workflow executions started by this schedule */
389
  runningWorkflows: WorkflowExecution[];
390
  /** Recent actions taken */
391
  recentActions: ScheduleActionResult[];
392
  /** Next scheduled action times */
393
  nextActionTimes: Date[];
394
  /** When schedule was created */
395
  createTime: Date;
396
  /** When schedule was last updated */
397
  updateTime: Date;
398
}
399

400
/**
401
 * Result of schedule execution
402
 */
403
interface ScheduleExecutionResult {
404
  /** Scheduled action time */
405
  scheduledTime: Date;
406
  /** Actual action time */
407
  actualTime: Date;
408
  /** Started workflow execution */
409
  startWorkflowResult?: WorkflowExecution;
410
}
411

412
/**
413
 * Schedule list entry
414
 */
415
interface ScheduleListEntry extends ScheduleSummary {
416
  /** Additional metadata */
417
  searchAttributes?: SearchAttributes;
418
}
419
```
420

421
### Backfill Operations
422

423
Support for filling in missed schedule executions over historical time periods.
424

425
```typescript { .api }
426
/**
427
 * Backfill operation specification
428
 */
429
interface Backfill {
430
  /** Start time for backfill period */
431
  startTime: Date;
432
  /** End time for backfill period */
433
  endTime: Date;
434
  /** Overlap policy for backfill executions */
435
  overlap?: ScheduleOverlapPolicy;
436
}
437
```
438

439
**Usage Example:**
440

441
```typescript
442
// Backfill a schedule for the past week
443
await handle.backfill([
444
  {
445
    startTime: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000), // 7 days ago
446
    endTime: new Date(),
447
    overlap: ScheduleOverlapPolicy.SKIP,
448
  }
449
]);
450
```