chore: import upstream snapshot with attribution
This commit is contained in:
wehub-resource-sync
@@ -0,0 +1,382 @@
|
||||
---
|
||||
title: "Scheduled tasks (cron)"
|
||||
description: "A task that is triggered on a recurring schedule using cron syntax."
|
||||
---
|
||||
|
||||
<Note>
|
||||
Scheduled tasks are only for recurring tasks. If you want to trigger a one-off task at a future
|
||||
time, you should [use the delay option](/triggering#delay).
|
||||
</Note>
|
||||
|
||||
## Defining a scheduled task
|
||||
|
||||
This task will run when any of the attached schedules trigger. They have a predefined payload with some useful properties:
|
||||
|
||||
```ts
|
||||
import { schedules } from "@trigger.dev/sdk";
|
||||
|
||||
export const firstScheduledTask = schedules.task({
|
||||
id: "first-scheduled-task",
|
||||
run: async (payload) => {
|
||||
//when the task was scheduled to run
|
||||
//note this will be slightly different from new Date() because it takes a few ms to run the task
|
||||
console.log(payload.timestamp); //is a Date object
|
||||
|
||||
//when the task was last run
|
||||
//this can be undefined if it's never been run
|
||||
console.log(payload.lastTimestamp); //is a Date object or undefined
|
||||
|
||||
//the timezone the schedule was registered with, defaults to "UTC"
|
||||
//this is in IANA format, e.g. "America/New_York"
|
||||
//See the full list here: https://cloud.trigger.dev/timezones
|
||||
console.log(payload.timezone); //is a string
|
||||
|
||||
//If you want to output the time in the user's timezone do this:
|
||||
const formatted = payload.timestamp.toLocaleString("en-US", {
|
||||
timeZone: payload.timezone,
|
||||
});
|
||||
|
||||
//the schedule id (you can have many schedules for the same task)
|
||||
//using this you can remove the schedule, update it, etc
|
||||
console.log(payload.scheduleId); //is a string
|
||||
|
||||
//you can optionally provide an external id when creating the schedule
|
||||
//usually you would set this to a userId or some other unique identifier
|
||||
//this can be undefined if you didn't provide one
|
||||
console.log(payload.externalId); //is a string or undefined
|
||||
|
||||
//the next 5 dates this task is scheduled to run
|
||||
console.log(payload.upcoming); //is an array of Date objects
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
You can see from the comments that the payload has several useful properties:
|
||||
|
||||
- `timestamp` - the time the task was scheduled to run, as a UTC date.
|
||||
- `lastTimestamp` - the time the task was last run, as a UTC date.
|
||||
- `timezone` - the timezone the schedule was registered with, defaults to "UTC". In IANA format, e.g. "America/New_York".
|
||||
- `scheduleId` - the id of the schedule that triggered the task
|
||||
- `externalId` - the external id you (optionally) provided when creating the schedule
|
||||
- `upcoming` - the next 5 times the task is scheduled to run
|
||||
|
||||
<Note>
|
||||
This task will NOT get triggered on a schedule until you attach a schedule to it. Read on for how
|
||||
to do that.
|
||||
</Note>
|
||||
|
||||
Like all tasks they don't have timeouts, they should be placed inside a [/trigger folder](/config/config-file), and you [can configure them](/tasks/overview#defining-a-task).
|
||||
|
||||
You can set a [TTL](/runs#time-to-live-ttl) on a scheduled task to automatically expire runs that aren't dequeued in time. This is useful when a schedule fires while the previous run is still executing - rather than queueing up stale runs, they'll expire:
|
||||
|
||||
```ts
|
||||
export const frequentTask = schedules.task({
|
||||
id: "frequent-task",
|
||||
ttl: "5m",
|
||||
run: async (payload) => {
|
||||
//...
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
## How to attach a schedule
|
||||
|
||||
Now that we've defined a scheduled task, we need to define when it will actually run. To do this we need to attach one or more schedules.
|
||||
|
||||
There are two ways of doing this:
|
||||
|
||||
- **Declarative:** defined on your `schedules.task`. They sync when you run the dev command or deploy.
|
||||
- **Imperative:** created from the dashboard or by using the imperative SDK functions like `schedules.create()`.
|
||||
|
||||
<Info>
|
||||
A scheduled task can have multiple schedules attached to it, including a declarative schedule
|
||||
and/or many imperative schedules.
|
||||
</Info>
|
||||
|
||||
### Declarative schedules
|
||||
|
||||
These sync when you run the [dev](/cli-dev-commands) or [deploy](/cli-deploy-commands) commands.
|
||||
|
||||
To create them you add the `cron` property to your `schedules.task()`. This property is optional and is only used if you want to add a declarative schedule to your task:
|
||||
|
||||
```ts
|
||||
export const firstScheduledTask = schedules.task({
|
||||
id: "first-scheduled-task",
|
||||
//every two hours (UTC timezone)
|
||||
cron: "0 */2 * * *",
|
||||
run: async (payload, { ctx }) => {
|
||||
//do something
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
If you use a string it will be in UTC. Alternatively, you can specify a timezone like this:
|
||||
|
||||
```ts
|
||||
export const secondScheduledTask = schedules.task({
|
||||
id: "second-scheduled-task",
|
||||
cron: {
|
||||
//5am every day Tokyo time
|
||||
pattern: "0 5 * * *",
|
||||
timezone: "Asia/Tokyo",
|
||||
//optional, defaults to all environments
|
||||
//possible values are "PRODUCTION", "STAGING", "PREVIEW" and "DEVELOPMENT"
|
||||
environments: ["PRODUCTION", "STAGING"],
|
||||
},
|
||||
run: async (payload) => {},
|
||||
});
|
||||
```
|
||||
|
||||
When you run the [dev](/cli-dev-commands) or [deploy](/cli-deploy-commands) commands, declarative schedules will be synced. If you add, delete or edit the `cron` property it will be updated when you run these commands. You can view your schedules on the Schedules page in the dashboard.
|
||||
|
||||
### Imperative schedules
|
||||
|
||||
Alternatively you can explicitly attach schedules to a `schedules.task`. You can do this in the Schedules page in the dashboard by just pressing the "New schedule" button, or you can use the SDK to create schedules.
|
||||
|
||||
The advantage of imperative schedules is that they can be created dynamically, for example, you could create a schedule for each user in your database. They can also be activated, disabled, edited, and deleted without deploying new code by using the SDK or dashboard.
|
||||
|
||||
To use imperative schedules you need to do two things:
|
||||
|
||||
1. Define a task in your code using `schedules.task()`.
|
||||
2. Attach 1+ schedules to the task either using the dashboard or the SDK.
|
||||
|
||||
## Supported cron syntax
|
||||
|
||||
```
|
||||
* * * * *
|
||||
┬ ┬ ┬ ┬ ┬
|
||||
│ │ │ │ |
|
||||
│ │ │ │ └ day of week (0 - 7, 1L - 7L) (0 or 7 is Sun)
|
||||
│ │ │ └───── month (1 - 12)
|
||||
│ │ └────────── day of month (1 - 31, L)
|
||||
│ └─────────────── hour (0 - 23)
|
||||
└──────────────────── minute (0 - 59)
|
||||
```
|
||||
|
||||
"L" means the last. In the "day of week" field, 1L means the last Monday of the month. In the "day of month" field, L means the last day of the month.
|
||||
|
||||
We do not support seconds in the cron syntax.
|
||||
|
||||
## When schedules won't trigger
|
||||
|
||||
There are two situations when a scheduled task won't trigger:
|
||||
|
||||
- For Dev environments scheduled tasks will only trigger if you're running the dev CLI.
|
||||
- For Staging/Production environments scheduled tasks will only trigger if the task is in the current deployment (latest version). We won't trigger tasks from previous deployments.
|
||||
|
||||
## Attaching schedules in the dashboard
|
||||
|
||||
You need to attach a schedule to a task before it will run on a schedule. You can attach static schedules in the dashboard:
|
||||
|
||||
<Steps>
|
||||
|
||||
<Step title="Go to the Schedules page">
|
||||
In the sidebar select the "Schedules" page, then press the "New schedule" button. Or you can
|
||||
follow the onboarding and press the create in dashboard button. 
|
||||
</Step>
|
||||
|
||||
<Step title="Create your schedule">
|
||||
Fill in the form and press "Create schedule" when you're done. 
|
||||
|
||||
These are the options when creating a schedule:
|
||||
|
||||
| Name | Description |
|
||||
| ----------------- | --------------------------------------------------------------------------------------------- |
|
||||
| Task | The id of the task you want to attach to. |
|
||||
| Cron pattern | The schedule in cron format. |
|
||||
| Timezone | The timezone the schedule will run in. Defaults to "UTC" |
|
||||
| External id | An optional external id, usually you'd use a userId. |
|
||||
| Deduplication key | An optional deduplication key. If you pass the same value, it will update rather than create. Scoped per project, not per environment. |
|
||||
| Environments | The environments this schedule will run in. |
|
||||
|
||||
</Step>
|
||||
|
||||
</Steps>
|
||||
|
||||
## Attaching schedules with the SDK
|
||||
|
||||
You call `schedules.create()` to create a schedule from your code. Here's the simplest possible example:
|
||||
|
||||
```ts
|
||||
const createdSchedule = await schedules.create({
|
||||
//The id of the scheduled task you want to attach to.
|
||||
task: firstScheduledTask.id,
|
||||
//The schedule in cron format.
|
||||
cron: "0 0 * * *",
|
||||
//this is required, it prevents you from creating duplicate schedules. It will update the schedule if it already exists.
|
||||
deduplicationKey: "my-deduplication-key",
|
||||
});
|
||||
```
|
||||
|
||||
<Note>The `task` id must be a task that you defined using `schedules.task()`.</Note>
|
||||
|
||||
You can create many schedules with the same `task`, `cron`, and `externalId` but only one with the same `deduplicationKey`.
|
||||
|
||||
<Note>
|
||||
The deduplication key is **per project**, not per environment. Using the same key in Production and Staging creates a single schedule; the last create/update decides which environment it appears in. For fixed schedules, prefer **declarative** (cron on the task). If using imperative across environments, use a different deduplication key per environment (e.g. include the env name in the key).
|
||||
</Note>
|
||||
|
||||
This means you can have thousands of schedules attached to a single task, but only one schedule per `deduplicationKey`. Here's an example with all the options:
|
||||
|
||||
```ts
|
||||
const createdSchedule = await schedules.create({
|
||||
//The id of the scheduled task you want to attach to.
|
||||
task: firstScheduledTask.id,
|
||||
//The schedule in cron format.
|
||||
cron: "0 0 * * *",
|
||||
// Optional, it defaults to "UTC". In IANA format, e.g. "America/New_York".
|
||||
// In this case, the task will run at midnight every day in New York time.
|
||||
// If you specify a timezone it will automatically work with daylight saving time.
|
||||
timezone: "America/New_York",
|
||||
//Optionally, you can specify your own IDs (like a user ID) and then use it inside the run function of your task.
|
||||
//This allows you to have per-user cron tasks.
|
||||
externalId: "user_123456",
|
||||
//You can only create one schedule with this key.
|
||||
//If you use it twice, the second call will update the schedule.
|
||||
//This is useful because you don't want to create duplicate schedules for a user.
|
||||
deduplicationKey: "user_123456-todo_reminder",
|
||||
});
|
||||
```
|
||||
|
||||
See [the SDK reference](/management/schedules/create) for full details.
|
||||
|
||||
### Dynamic schedules (or multi-tenant schedules)
|
||||
|
||||
By using the `externalId` you can have schedules for your users. This is useful for things like reminders, where you want to have a schedule for each user.
|
||||
|
||||
A reminder task:
|
||||
|
||||
```ts /trigger/reminder.ts
|
||||
import { schedules } from "@trigger.dev/sdk";
|
||||
|
||||
//this task will run when any of the attached schedules trigger
|
||||
export const reminderTask = schedules.task({
|
||||
id: "todo-reminder",
|
||||
run: async (payload) => {
|
||||
if (!payload.externalId) {
|
||||
throw new Error("externalId is required");
|
||||
}
|
||||
|
||||
//get user using the externalId you used when creating the schedule
|
||||
const user = await db.getUser(payload.externalId);
|
||||
|
||||
//send a reminder email
|
||||
await sendReminderEmail(user);
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
Then in your backend code, you can create a schedule for each user:
|
||||
|
||||
```ts Next.js API route
|
||||
import { reminderTask } from "~/trigger/reminder";
|
||||
|
||||
//app/reminders/route.ts
|
||||
export async function POST(request: Request) {
|
||||
//get the JSON from the request
|
||||
const data = await request.json();
|
||||
|
||||
//create a schedule for the user
|
||||
const createdSchedule = await schedules.create({
|
||||
task: reminderTask.id,
|
||||
//8am every day
|
||||
cron: "0 8 * * *",
|
||||
//the user's timezone
|
||||
timezone: data.timezone,
|
||||
//the user id
|
||||
externalId: data.userId,
|
||||
//this makes it impossible to have two reminder schedules for the same user
|
||||
deduplicationKey: `${data.userId}-reminder`,
|
||||
});
|
||||
|
||||
//return a success response with the schedule
|
||||
return Response.json(createdSchedule);
|
||||
}
|
||||
```
|
||||
|
||||
You can also retrieve, list, delete, deactivate and re-activate schedules using the SDK. More on that later.
|
||||
|
||||
## Testing schedules
|
||||
|
||||
You can test a scheduled task in the dashboard. Note that the `scheduleId` will always come through as `sched_1234` to the run.
|
||||
|
||||
<Steps>
|
||||
|
||||
<Step title="Go to the Test page">
|
||||
In the sidebar select the "Test" page, then select a scheduled task from the list (they have a
|
||||
clock icon on them) 
|
||||
</Step>
|
||||
|
||||
<Step title="Create your schedule">
|
||||
Fill in the form [1]. You can select from a recent run [2] to pre-populate the fields. Press "Run
|
||||
test" when you're ready 
|
||||
</Step>
|
||||
|
||||
</Steps>
|
||||
|
||||
## Managing schedules with the SDK
|
||||
|
||||
### Retrieving an existing schedule
|
||||
|
||||
```ts
|
||||
const retrievedSchedule = await schedules.retrieve(scheduleId);
|
||||
```
|
||||
|
||||
See [the SDK reference](/management/schedules/retrieve) for full details.
|
||||
|
||||
### Listing schedules
|
||||
|
||||
```ts
|
||||
const allSchedules = await schedules.list();
|
||||
```
|
||||
|
||||
See [the SDK reference](/management/schedules/list) for full details.
|
||||
|
||||
### Updating a schedule
|
||||
|
||||
```ts
|
||||
const updatedSchedule = await schedules.update(scheduleId, {
|
||||
task: firstScheduledTask.id,
|
||||
cron: "0 0 1 * *",
|
||||
externalId: "ext_1234444",
|
||||
deduplicationKey: "my-deduplication-key",
|
||||
});
|
||||
```
|
||||
|
||||
See [the SDK reference](/management/schedules/update) for full details.
|
||||
|
||||
### Deactivating a schedule
|
||||
|
||||
```ts
|
||||
const deactivatedSchedule = await schedules.deactivate(scheduleId);
|
||||
```
|
||||
|
||||
See [the SDK reference](/management/schedules/deactivate) for full details.
|
||||
|
||||
### Activating a schedule
|
||||
|
||||
```ts
|
||||
const activatedSchedule = await schedules.activate(scheduleId);
|
||||
```
|
||||
|
||||
See [the SDK reference](/management/schedules/activate) for full details.
|
||||
|
||||
### Deleting a schedule
|
||||
|
||||
```ts
|
||||
const deletedSchedule = await schedules.del(scheduleId);
|
||||
```
|
||||
|
||||
See [the SDK reference](/management/schedules/delete) for full details.
|
||||
|
||||
### Getting possible timezones
|
||||
|
||||
You might want to show a dropdown menu in your UI so your users can select their timezone. You can get a list of all possible timezones using the SDK:
|
||||
|
||||
```ts
|
||||
const timezones = await schedules.timezones();
|
||||
```
|
||||
|
||||
See [the SDK reference](/management/schedules/timezones) for full details.
|
||||
Reference in New Issue
Block a user