Sync Schedule
Data Entity
Description
Configures the automated synchronization frequency and preferred time window for an organization integration. Supports daily, weekly, monthly, and manual-trigger-only modes. Stores the next scheduled run time and the most recent execution outcome for display in the integration admin dashboard.
Data Structure
| Name | Type | Description | Constraints |
|---|---|---|---|
id |
uuid |
Primary key for the sync schedule record | PKrequiredunique |
organization_integration_id |
uuid |
Foreign key referencing the parent organization_integration record. Enforces the one-to-one relationship — each integration has exactly one sync schedule. | requiredunique |
frequency |
enum |
How often the sync should automatically execute. 'manual' disables automatic scheduling entirely and requires an admin to trigger runs explicitly. | required |
preferred_time |
string |
Preferred time-of-day for the sync to run, in HH:MM (24-hour) format in the organization's configured timezone. Used by the scheduler when computing next_scheduled_at. Null when frequency is 'manual'. | - |
preferred_day_of_week |
enum |
Day of the week on which weekly syncs should execute. Only meaningful when frequency = 'weekly'. Null for all other frequencies. | - |
preferred_day_of_month |
integer |
Day of the month (1–28) on which monthly syncs should execute. Capped at 28 to avoid last-day-of-month ambiguity across February. Only meaningful when frequency = 'monthly'. | - |
timezone |
string |
IANA timezone identifier (e.g. 'Europe/Oslo') used to interpret preferred_time and preferred_day_of_week/month when computing next_scheduled_at. Defaults to 'Europe/Oslo' for Norwegian organizations. | required |
is_enabled |
boolean |
Whether automated syncing is active. When false, the scheduler skips this record even if frequency is not 'manual'. Allows temporary suspension without losing schedule configuration. | required |
next_scheduled_at |
datetime |
UTC timestamp of the next planned automatic sync execution. Computed and updated by the scheduler after each successful or failed run. Null when frequency = 'manual' or is_enabled = false. | - |
last_run_at |
datetime |
UTC timestamp when the most recent sync execution started. Null if no sync has ever been triggered for this schedule. | - |
last_run_status |
enum |
Outcome of the most recent sync execution. 'never_run' is the initial state. Displayed on the integration admin dashboard to give admins an at-a-glance health indicator. | required |
last_run_error |
text |
Human-readable error message or stack trace from the most recent failed or partial sync execution. Null when last_run_status is 'success', 'never_run', or 'running'. Displayed to org admins in the dashboard for diagnosis. | - |
last_run_records_synced |
integer |
Count of records successfully transferred in the most recent sync execution. Used alongside last_run_status to differentiate a successful zero-record run from a skipped or failed one. | - |
created_at |
datetime |
UTC timestamp when this sync schedule was first created, typically during integration setup. | required |
updated_at |
datetime |
UTC timestamp of the most recent change to any field on this record. Auto-updated on every write. | required |
Database Indexes
idx_sync_schedule_integration_id
Columns: organization_integration_id
idx_sync_schedule_next_run
Columns: next_scheduled_at
idx_sync_schedule_frequency_enabled
Columns: frequency, is_enabled
Validation Rules
valid_frequency_enum
error
Validation failed
preferred_time_format
error
Validation failed
valid_iana_timezone
error
Validation failed
day_of_month_range
error
Validation failed
foreign_key_integrity
error
Validation failed
last_run_status_valid_enum
error
Validation failed
error_message_only_on_failure
warning
Validation failed
Business Rules
one_schedule_per_integration
Each organization_integration record must have exactly one sync_schedule. The unique constraint on organization_integration_id enforces this at the database level. Creating a second schedule for the same integration is rejected.
manual_frequency_clears_next_run
When frequency is set to 'manual', next_scheduled_at must be set to null and is_enabled has no effect on scheduling. The scheduler must skip records with frequency = 'manual' entirely.
weekly_requires_day_of_week
When frequency = 'weekly', preferred_day_of_week must be populated. preferred_day_of_month must be null. The setup wizard enforces this before saving.
monthly_requires_day_of_month
When frequency = 'monthly', preferred_day_of_month must be set to a value between 1 and 28. preferred_day_of_week must be null.
next_scheduled_recomputed_after_run
After every sync execution completes (success, partial, or failed), the scheduler must update next_scheduled_at to the next valid run time based on frequency, preferred_time, and timezone. This ensures the dashboard always shows a meaningful upcoming run.
running_status_timeout_guard
If last_run_status = 'running' and last_run_at is more than 2 hours ago, the sync-scheduler must transition the status to 'failed' with an appropriate timeout error message. Prevents stale 'running' states from persisting in the dashboard.
disabled_schedule_nulls_next_run
When is_enabled is set to false, next_scheduled_at must be set to null. Re-enabling recomputes next_scheduled_at from the current time using the configured frequency and preferred_time.
CRUD Operations
Storage Configuration
Entity Relationships
Each integration has exactly one sync schedule configuring its automated execution frequency and preferred time window