diff --git a/frontend/docs/pages/v1/scheduled-runs.mdx b/frontend/docs/pages/v1/scheduled-runs.mdx index 08d202ec6..cd2880ca2 100644 --- a/frontend/docs/pages/v1/scheduled-runs.mdx +++ b/frontend/docs/pages/v1/scheduled-runs.mdx @@ -5,30 +5,21 @@ import UniversalTabs from "@/components/UniversalTabs"; # Scheduled Runs -Scheduled runs allow you to trigger a task at a specific time in the future. +Scheduled runs trigger a task at a specific point in the future. Common use cases include: -Some example use cases of scheduling runs might include: - -- Sending a reminder email at a specific time after a user took an action. -- Running a one-time maintenance task at a predetermined time as determined by your application. For instance, you might want to run a database vacuum during a maintenance window any time a task matches a certain criteria. -- Allowing a customer to decide when they want your application to perform a specific task. For instance, if your application is a simple alarm app that sends a customer a notification at a time that they specify, you might create a scheduled run for each alarm that the customer sets. - -Hatchet supports scheduled runs to run on a schedule defined in a few different ways: - -- [Programmatically](/v1/scheduled-runs#programmatically-creating-scheduled-runs): Use the Hatchet SDKs to dynamically set the schedule of a task. -- [Hatchet Dashboard](/v1/scheduled-runs#managing-scheduled-runs-in-the-hatchet-dashboard): Manually create scheduled runs from the Hatchet Dashboard. +- Sending a reminder email after a user action. +- Running a one-time maintenance task (e.g., a database vacuum) during a predetermined window. +- Letting a customer specify when a task should run, such as setting an alarm. The scheduled time is when Hatchet **enqueues** the task, not when the run - starts. Scheduling constraints like concurrency limits, rate limits, and retry - policies can affect run start times. + starts. Concurrency limits, rate limits, and retry policies can affect the + actual start time. -### Create a Scheduled Run +## Create a Scheduled Run -You can create dynamic scheduled runs programmatically via the API to run tasks at a specific time in the future. - -Here's an example of creating a scheduled run to trigger a task tomorrow at noon: +Scheduled runs can be created programmatically. This gives an option for the trigger time to differ per customer or be derived from application logic. @@ -47,16 +38,13 @@ Here's an example of creating a scheduled run to trigger a task tomorrow at noon -In this example you can have different scheduled times for different customers, or dynamically set the scheduled time based on some other business logic. - -When creating a scheduled run via the API, you will receive a scheduled run object with a metadata property containing the ID of the scheduled run. This ID can be used to reference the scheduled run when deleting the scheduled run and is often stored in a database or other persistence layer. +The API returns a scheduled run object whose ID should be persisted — it is required for subsequent delete or reschedule operations. - Note: Be mindful of the time zone of the scheduled run. Scheduled runs are - **always** stored and returned in UTC. + Scheduled runs are always stored and returned in UTC. -### Deleting a Scheduled Run +## Deleting a Scheduled Run @@ -73,7 +61,7 @@ When creating a scheduled run via the API, you will receive a scheduled run obje -### Listing Scheduled Runs +## Listing Scheduled Runs @@ -90,7 +78,7 @@ When creating a scheduled run via the API, you will receive a scheduled run obje -### Rescheduling a Scheduled Run +## Rescheduling a Scheduled Run @@ -112,14 +100,14 @@ When creating a scheduled run via the API, you will receive a scheduled run obje - You can only reschedule scheduled runs created via the API (not runs created - via a code-defined schedule), and Hatchet may reject rescheduling if the run - has already triggered. + Only scheduled runs created via the API can be rescheduled — not runs defined + in code. Hatchet will reject a reschedule request if the run has already + triggered. -### Bulk operations (delete / reschedule) +## Bulk Operations (Delete / Reschedule) -Hatchet supports bulk operations for scheduled runs. You can bulk delete scheduled runs, and you can bulk reschedule scheduled runs by providing a list of updates. +Hatchet supports bulk delete and bulk reschedule operations for scheduled runs. @@ -144,14 +132,12 @@ Hatchet supports bulk operations for scheduled runs. You can bulk delete schedul -## Scheduled Run Considerations +## Considerations -When using scheduled runs, there are a few considerations to keep in mind: +1. **Time zone**: All scheduled run times are stored and returned in UTC. -1. **Time Zone**: Scheduled runs are stored and returned in UTC. Make sure to consider the time zone when defining your scheduled time. +2. **Execution time**: Hatchet enqueues the task as close to the scheduled time as possible, but system load or other factors may introduce minor delays. -2. **Execution Time**: The actual execution time of a scheduled run may vary slightly from the scheduled time. Hatchet makes a best-effort attempt to enqueue the task as close to the scheduled time as possible, but there may be slight delays due to system load or other factors. +3. **Missed schedules**: Hatchet does not replay missed runs after downtime. If a scheduled task is missed, it will not execute when the service recovers. -3. **Missed Schedules**: If a scheduled task is missed (e.g., due to system downtime), Hatchet will not automatically run the missed instances when the service comes back online. - -4. **Overlapping Schedules**: If a task is still running when a second scheduled run is scheduled to start, Hatchet will start a new instance of the task or respect [concurrency](/v1/concurrency) policy. +4. **Overlapping runs**: If a prior run is still active when a new scheduled run triggers, Hatchet starts a new instance or applies the configured [concurrency](/v1/concurrency) policy. diff --git a/frontend/docs/public/schedule-dash.gif b/frontend/docs/public/schedule-dash.gif new file mode 100644 index 000000000..18fe41413 Binary files /dev/null and b/frontend/docs/public/schedule-dash.gif differ diff --git a/sdks/python/examples/simple/schedule.py b/sdks/python/examples/simple/schedule.py index 0a8b331ef..b0ac6811e 100644 --- a/sdks/python/examples/simple/schedule.py +++ b/sdks/python/examples/simple/schedule.py @@ -4,7 +4,9 @@ from examples.simple.worker import simple # > Schedule a Task -tomorrow_noon = datetime.now(tz=timezone.utc).replace(hour=12, minute=0, second=0, microsecond=0) + timedelta(days=1) +tomorrow_noon = datetime.now(tz=timezone.utc).replace( + hour=12, minute=0, second=0, microsecond=0 +) + timedelta(days=1) scheduled_run = simple.schedule(tomorrow_noon, input={"Message": "hello"})