Background job scheduling with the Alphabet Scheduler

Alphabet’s scheduler lets you create, manage, and monitor background jobs via REST API. Supports cron, interval, and one-time schedules with Hangfire.

Alphabet’s scheduler module gives you a complete background job management system accessible entirely through a REST API at /api/v1/scheduler. Under the hood it is powered by Hangfire, which provides reliable job persistence, retry logic, and a protected dashboard UI. You can create jobs that call HTTP endpoints, run stored procedures, execute custom .NET code handlers, or perform file operations — all without writing any scheduling infrastructure yourself.

Key concepts

Job — A definition of what to run and when. Each job has a type (what to do), a schedule (when to do it), and a configuration object that carries the parameters specific to that type. Jobs persist in the application database and survive restarts.

Execution — A single run of a job. Every time a job fires, Alphabet creates an execution record that tracks the outcome. Executions move through the following statuses:

Status	Meaning
Pending	Queued and waiting for a worker.
Running	Currently being processed by a Hangfire worker.
Succeeded	Completed without error.
Failed	Finished with an error; may be retried depending on retry policy.
Cancelled	Stopped before completion by an explicit cancel request.

Schedule types — How often a job runs:

• Cron — A standard five-field cron expression (e.g. "0 * * * *" for every hour on the hour).
• Interval — A repeat period expressed in seconds (e.g. 3600 for every hour).
• OneTime — A specific UTC timestamp after which the job runs once and stops.

Job types — What a job does when it runs:

• HttpCall — Makes an outbound HTTP request to a URL you specify.
• StoredProcedure — Executes a named stored procedure against the application database.
• CodeExecution — Runs a custom class that implements IJobHandler and is registered in the application’s DI container.
• FileOperation — Performs a file system operation (delete, move, archive, or compress) on a path within the configured allowed roots.

Workflow — An ordered set of jobs with explicit dependency relationships. A workflow lets you chain jobs so that one job only starts after another has succeeded, building pipelines without writing any orchestration code.

Configuration reference

The following settings in appsettings.json under the Scheduler key affect runtime behavior:

Setting	Default	Effect
Provider	Hangfire	The scheduler backend. Hangfire is the supported provider.
Hangfire.WorkerCount	5	Number of concurrent Hangfire workers processing jobs.
Hangfire.Queues	["default","critical","background"]	Named queues available for routing jobs.
Hangfire.JobExpirationDays	30	How long completed job records are retained before Hangfire expires them.
Jobs.DefaultTimeoutSeconds	300	Per-job execution timeout applied when no explicit timeoutSeconds is set.
Jobs.MaxConcurrentJobs	10	Maximum number of jobs that can run simultaneously across all workers.
Retry.DefaultMaxAttempts	3	Default number of retry attempts for a failed job.
Retry.DefaultDelaySeconds	60	Default delay between retry attempts in seconds.

The Hangfire dashboard is available at /hangfire and requires an authenticated admin session. It shows live queue depths, worker status, and execution history directly from the Hangfire storage.

Authentication

All scheduler endpoints under /api/v1/scheduler require a valid authenticated session. Pass a JWT bearer token in the Authorization header:

Authorization: Bearer <your_access_token>

Admin endpoints under /api/v1/scheduler/admin additionally require the AdminOnly authorization policy. Your account must belong to a role that satisfies that policy before those endpoints will respond with anything other than 403 Forbidden.

Calling admin endpoints such as POST /api/v1/scheduler/admin/pause-all without the AdminOnly policy will return 403 Forbidden. Do not use service accounts with elevated admin policies for routine job management.

What’s in this section

Job types

Create and manage HTTP call, stored procedure, code execution, and file operation jobs.

Workflows

Chain jobs into ordered pipelines with dependency rules and exclusion windows.

Monitoring

Track execution history, view dashboard stats, and manage running executions.