Schedulers overview

z4j has two complementary surfaces in this section:

1. Per-engine scheduler adapters (below) - surface an existing native scheduler (celery-beat, rq-scheduler, APScheduler, etc.) in the z4j dashboard so operators can see them and use only the controls that each adapter advertises, without migrating away from the native scheduler. Useful when you're already running the native scheduler and it fits.
2. z4j-scheduler - a separate companion process that fires schedules against any of the six engines z4j supports. Schedules live in z4j's database; edit from the dashboard, declarative config, or REST without a daemon restart. Useful when you have multiple engines in one shop, or want a single audit-logged surface for schedule edits across the org. If you're running one engine and one schedule list, the existing native scheduler is probably fine.

Per-engine scheduler adapters

All six native scheduler integrations support source-confirmed dashboard controls once the producer setup in each linked guide is installed; installing an adapter into an unrelated web process is not sufficient. Without that setup, an adapter provides inventory and, where its guide says so, manual runs.

Scheduler	Package	Dashboard controls and required source
celery-beat	z4j-celerybeat	Database CRUD, pause/resume and manual runs; static definitions allow inventory/manual runs
rq-scheduler	z4j-rqscheduler	CRUD, pause/resume and manual runs with managed producers and Redis persistence
APScheduler	z4j-apscheduler	CRUD, pause/resume and manual runs on the selected APScheduler 3 jobstore
huey-periodic	z4j-hueyperiodic	CRUD, pause/resume and manual runs with durable overrides in the periodic consumer
arq-cron	z4j-arqcron	CRUD, pause/resume and manual runs with durable overrides on the actual Worker
taskiq-scheduler	z4j-taskiqscheduler	CRUD, pause/resume and manual runs with durable overrides on the stock label source

Code-defined schedules remain in code; persisted field overrides and deletion tombstones provide dashboard management without rewriting source files. New schedules invoke registered application tasks. Native producers continue during server outages, but new dashboard edits need an authorized online producer. A completed operation requires the native source to confirm the change.

Use z4j-scheduler when you want schedules stored in z4j's database with its own catch-up and overlap policies. Native integrations retain upstream scheduling and delivery semantics. A pause does not cancel work already queued or running. Worker engine adapters provide queue task history.

Discovery

Schedules are discovered on agent boot through the scheduler-specific API. The agent repeats the snapshot on a fixed resync interval, which defaults to 15 minutes and is not exposed as an agent setting. An operator can request a sync immediately. Changes made outside the dashboard are picked up on one of those snapshots.

CRUD operations

When the connected adapter advertises them, the UI can expose:

• Create - name, task, cron or interval, args/kwargs, enabled/disabled.
• Update - any of the above.
• Enable / Disable - toggle the native scheduler's enabled state where reversible control exists.
• Delete - remove the entry.

Every CRUD op writes an audit log entry.

Pitfalls

• Clock drift - if your brain and agent live in different timezones, use UTC crontabs. The dashboard renders in the viewer's local time.
• Multiple producers - use one authoritative native registry per project and scheduler owner. Registering unrelated applications under the same owner does not merge their registries. Follow each native scheduler’s process and persistence requirements.
• Paused-at-broker vs paused-at-scheduler - some engines have both; z4j operates at the scheduler level. If you pause at the broker, the dashboard still shows "enabled" on the schedule.