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.

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:

scheduled_run = hatchet.scheduled.create(
    workflow_name="simple-workflow",
    trigger_at=datetime.now() + timedelta(seconds=10),
    input={
        "data": "simple-workflow-data",
    },
    additional_metadata={
        "customer_id": "customer-a",
    },
)
 
id = scheduled_run.metadata.id  # the id of the scheduled run trigger

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.

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.

hatchet.scheduled.delete(scheduled=scheduled_run.metadata.id)

List Scheduled Runs

Retrieves a list of all scheduled runs matching the criteria.

scheduled_runs = hatchet.scheduled.list()

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:

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: 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.

3. Missed Schedules: If a scheduled workflow is missed (e.g., due to system downtime), Hatchet will not automatically run the missed instances.

4. 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.