Scheduled Runs
Scheduled runs allow you to trigger a workflow at a specific time in the future. This is useful when you need to execute a workflow at a specific time, such as sending a reminder email at a specific hour or a one-time maintenance task at a predetermined time.
Hatchet supports scheduled runs to run on a schedule defined in a few different ways:
- Programmatically: Use the Hatchet SDKs to dynamically set the schedule of a workflow (i.e. customer defined schedule).
- Hatchet Dashboard: Manually create scheduled runs from the Hatchet Dashboard.
The scheduled time is when Hatchet enqueues the workflow, not when the run starts. Scheduling constraints like concurrency limits, rate limits, and retry policies can affect run start times.
Programmatically Creating Scheduled Runs
Create a Scheduled Run
You can create dynamic scheduled runs programmatically via the API. This is useful if you want to create a scheduled run that is not known at the time of workflow definition,
Here's an example of creating a a scheduled run to trigger a report for a specific customer 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.
Note: Be mindful of the time zone of the scheduled run. Scheduled runs are always stored and returned in UTC.
Delete a Scheduled Run
You can delete a scheduled run by passing the scheduled run object or a scheduled run id to the delete method.
Note: Deleting a scheduled run will not cancel any scheduled runs that have already entered the queue, but it will prevent future runs from starting.
List Scheduled Runs
Retrieves a list of all scheduled runs matching the criteria.
Managing Scheduled Runs in the Hatchet Dashboard
In the Hatchet Dashboard, you can view and manage scheduled runs for your workflows.
Navigate to "Triggers" > "Scheduled Runs" in the left sidebar and click "Create Scheduled Run" at the top right.
You can specify run parameters such as Input, Additional Metadata, and the Scheduled Time.
Scheduled Run Considerations
When using scheduled runs, there are a few considerations to keep in mind:
-
Time Zone: Scheduled runs are stored and returned in UTC. Make sure to consider the time zone when defining your scheduled time.
-
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 workflow as close to the scheduled time as possible, but there may be slight delays due to system load or other factors.
-
Missed Schedules: If a scheduled workflow is missed (e.g., due to system downtime), Hatchet will not automatically run the missed instances.
-
Overlapping Schedules: If a workflow is still running when a second scheduled run is scheduled to start, Hatchet will start a new instance of the workflow or respect concurrency policy.