Task Scheduling & Crons

Relevant source files

The following files were used as context for generating this wiki page:

• convex/crons.ts
• convex/workflows/scheduling.ts
• convex/workflows/helpers.ts
• convex/schema.ts
• frontend/src/features/workflows/components/ScheduleDialog.tsx
• frontend/src/features/workflows/types/index.ts

The Task Scheduling & Crons system is responsible for the automated execution of workflows and maintenance tasks within the platform. It leverages the Convex Crons component to manage recurring jobs, such as daily profile resets, automated unsubscribing, and periodic workflow triggers. The system ensures that background processes run at specific intervals or predefined UTC times, providing a reliable infrastructure for long-running automation tasks.

This module bridges the gap between the database state and the execution environment. It defines how schedules are configured by users in the frontend, validated in the backend, and eventually registered as cron jobs that trigger internal mutations or external API calls.

System Architecture

The scheduling architecture is divided into global system crons and individual workflow-specific schedules. Global crons handle system-wide maintenance, while workflow schedules are dynamically registered and deregistered based on user interaction.

Execution Flow

When a scheduled job triggers, it typically follows a path from the Convex scheduler to an internal mutation, which then coordinates with external services (like a Python runner) if necessary.

Components and Descriptions

Component	Description
Convex Crons	Utility used to register, update, and delete recurring cron jobs within the Convex environment.
ScheduleConfig	A data structure defining the timing (interval, hour, days, etc.) for a specific task.
Workflow State	Tracks isActive, cronJobId, and runsToday to manage the execution lifecycle.
Internal Mutations	Backend functions that update database state and trigger execution without direct user auth requirements.

Sources: convex/workflows/helpers.ts:13-21, convex/schema.ts:98-115, convex/workflows/scheduling.ts:14

Schedule Configurations

The system supports multiple schedule types to accommodate various automation needs. Configurations are validated before being persisted to the database to ensure cron expressions can be correctly generated.

Supported Schedule Types

1. Interval: Runs every X milliseconds (e.g., every 10 minutes).
2. Daily: Runs once a day at a specific UTC hour and minute.
3. Weekly: Runs on specific days of the week at a set UTC time.
4. Monthly: Runs on a specific day of the month.
5. Cron: Accepts a standard raw cronspec expression.
6. Instant: Executes immediately upon activation without recurring.

Sources: convex/workflows/helpers.ts:13-21, convex/workflows/helpers.ts:31-70

Logic and Validation

The validation logic ensures that time-based values fall within valid ranges (e.g., hours 0-23, minutes 0-59) and that required fields for a specific type (like intervalMs for intervals) are present.

export function validateScheduleConfig(scheduleType: ScheduleType, config: ScheduleConfig) {
	switch (scheduleType) {
		case "interval":
			if (!Number.isInteger(config.intervalMs) || (config.intervalMs ?? 0) <= 0) {
				throw new Error("intervalMs must be a positive integer");
			}
			return;
		case "daily":
			requireIntegerInRange(config.hourUTC, "hourUTC", 0, 23);
			requireIntegerInRange(config.minuteUTC, "minuteUTC", 0, 59);
			return;
        // ... additional cases
	}
}

Sources: convex/workflows/helpers.ts:31-70

Global System Crons

Global crons are defined statically to handle platform-wide maintenance. These are typically initialized during the deployment of the Convex functions.

Job Name	Schedule (UTC)	Function Called	Purpose
reset daily scraping	00:01	profiles.scraping.resetDailyScrapingUsed	Resets the usage counter for all scraping profiles.
reset workflow daily runs	00:02	workflows.scheduling.resetDailyRuns	Resets the runsToday counter for all active workflows.
auto unsubscribe	03:00	instagramAccounts.autoUnsubscribe	Automatically unsubscribes stale accounts.
assign accounts	03:15	instagramAccounts.assignAvailableAccountsDaily	Re-assigns available accounts to profiles.

Sources: convex/crons.ts:24-34, convex/workflows/scheduling.ts:245-260

Workflow Schedule Management

Workflows can be toggled between active and inactive states. Activating a workflow registers a new cron job dynamically using the @convex-dev/crons component.

Activation Lifecycle

The following sequence diagram illustrates the process of activating a workflow and registering its associated cron job.

Daily Run Limits

Workflows can be configured with a maxRunsPerDay. The system tracks runsToday and compares it against this limit before starting a scheduled execution.

• Limit Check: Performed inside executeScheduledWorkflow. If runsToday >= maxRunsPerDay, the execution is skipped.
• Daily Reset: A global cron job runs resetDailyRuns every day at 00:02 UTC to set all runsToday counters back to zero.

Sources: convex/workflows/scheduling.ts:166-173, convex/workflows/scheduling.ts:245-260

Frontend Configuration

The ScheduleDialog component allows users to configure these settings. It handles timezone conversions between the user's local time and the UTC format required by the backend.

Timezone Handling

The frontend utilizes localToUTC and utcToLocal helpers to translate UI inputs into hourUTC and minuteUTC for storage in the ScheduleConfig.

function localToUTC(hour: number, minute: number, tz: string): { hourUTC: number; minuteUTC: number } {
  if (tz === 'UTC') return { hourUTC: hour, minuteUTC: minute }
  // ... conversion logic using toLocaleString
}

Sources: frontend/src/features/workflows/components/ScheduleDialog.tsx:14-41

Data Models

The workflows table in the schema contains specific fields dedicated to the scheduling system.

Field	Type	Description
isActive	boolean	Whether the workflow is currently scheduled.
scheduleType	union	Type of schedule (daily, interval, etc.).
scheduleConfig	object	Parameters like hourUTC, intervalMs, daysOfWeek.
timezone	string	The user's preferred timezone for display.
cronJobId	string	Unique identifier for the registered Convex cron.
runsToday	number	Counter for executions within the current day.

Sources: convex/schema.ts:98-115

Conclusion

The Task Scheduling & Crons module provides a robust framework for automating complex workflows and system maintenance. By combining a flexible scheduling configuration with strict validation and a centralized management system through Convex, it ensures that automation tasks are executed predictably while adhering to system limits and user-defined constraints.