Scheduling

Bizon Platform uses APScheduler for reliable cron-based scheduling of pipeline runs.

How Scheduling Works

1. Scheduler Process runs in-process with the FastAPI API server
2. Cron expressions define when pipelines should run
3. Job queue receives pending runs for workers to execute
4. Workers poll the queue and execute pipelines

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│    Scheduler    │────▶│   Job Queue     │────▶│     Workers     │
│  (APScheduler)  │     │  (PostgreSQL)   │     │  (Executors)    │
└─────────────────┘     └─────────────────┘     └─────────────────┘
        │                       │                       │
   Every minute            PipelineRun             Claim & Run
   checks cron             status=pending            pipelines

Cron Expression Format

Standard 5-field cron syntax:

┌───────────── minute (0-59)
│ ┌───────────── hour (0-23)
│ │ ┌───────────── day of month (1-31)
│ │ │ ┌───────────── month (1-12)
│ │ │ │ ┌───────────── day of week (0-6, 0=Sunday)
│ │ │ │ │
* * * * *

Common Schedules

Schedule	Expression	Description
Every hour	0 * * * *	At minute 0 of every hour
Every 6 hours	0 */6 * * *	At 00:00, 06:00, 12:00, 18:00
Daily at midnight	0 0 * * *	At 00:00 every day
Daily at 9 AM	0 9 * * *	At 09:00 every day
Weekdays at 8 AM	0 8 * * 1-5	Mon-Fri at 08:00
Weekly on Sunday	0 0 * * 0	Sunday at midnight
Monthly on 1st	0 0 1 * *	1st of month at midnight
Quarterly	0 0 1 1,4,7,10 *	Jan, Apr, Jul, Oct 1st

Setting a Schedule

UI

1. Edit the pipeline
2. Enter cron expression in “Schedule” field
3. Save changes

API

curl -X PUT http://localhost:8000/api/pipelines/{id} \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"schedule": "0 */6 * * *"}'

Removing a Schedule

Set the schedule to null or empty string for manual-only execution:

{"schedule": null}

Pipeline States

State	Scheduled Runs
enabled: true + schedule	Runs automatically
enabled: true + no schedule	Manual only
enabled: false + schedule	Schedule ignored
enabled: false + no schedule	Manual only

Timezone

Schedules use the server’s timezone. For consistent behavior in production:

# Set timezone in Docker
TZ=UTC

Concurrent Execution

If a run is still in progress when the next scheduled time arrives:

1. New pending run is created
2. Worker claims when available
3. No runs are skipped

To prevent overlap, ensure schedules account for typical run duration.

Monitoring Schedules

View Next Run

The UI shows the next scheduled run time for each pipeline.

Run History

Check if scheduled runs executed on time:

curl http://localhost:8000/api/pipelines/{id}/runs?triggered_by=schedule

Scheduler Health

The scheduler runs in the API process. Check API health:

curl http://localhost:8000/api/health
# {"status": "healthy"}

Troubleshooting

Pipeline Not Running

1. Check enabled - Pipeline must be enabled
2. Verify schedule - Test expression at crontab.guru
3. Check workers - At least one worker must be running
4. View logs - Check API logs for scheduler errors

Runs Delayed

1. Scale workers - Add more workers for high load
2. Check database - Ensure PostgreSQL is responsive
3. Review run duration - Long runs may cause backlog

Duplicate Runs

Rare, but can occur if:

• Multiple API instances without proper locking
• Clock skew between servers

Solution: Use a single API instance or shared lock.

Configuration

Setting	Default	Description
WORKER_POLL_INTERVAL	2	Seconds between worker polls

Best Practices

1. Stagger schedules - Avoid all pipelines at 0 0 * * *
2. Allow margin - Schedule before deadlines, not at
3. Monitor failures - Set up alerts for failed runs
4. Use off-peak hours - Heavy syncs during low-usage times