Context module for managing scheduled jobs.
Provides functions to create, cancel, and process scheduled jobs. The system uses
a behaviour-based handler pattern for extensibility - any module implementing
PhoenixKit.ScheduledJobs.Handler can be used to handle scheduled tasks.
Usage
# Schedule a job using a handler module
{:ok, job} = ScheduledJobs.schedule_job(
MyApp.Posts.ScheduledPostHandler,
post.id,
~U[2025-01-15 10:00:00Z],
%{notify: true}
)
# Cancel a scheduled job
{:ok, job} = ScheduledJobs.cancel_job(job)
# Process all pending jobs (called by cron worker)
{:ok, %{executed: 5, failed: 1}} = ScheduledJobs.process_pending_jobs()Handler Pattern
Handlers must implement the PhoenixKit.ScheduledJobs.Handler behaviour:
defmodule MyHandler do
@behaviour PhoenixKit.ScheduledJobs.Handler
def job_type, do: "my_job"
def resource_type, do: "my_resource"
def execute(resource_id, args), do: :ok
endSummary
Functions
Cancels a scheduled job.
Cancels all pending jobs for a specific resource.
Gets a scheduled job by ID.
Gets all scheduled jobs for a resource.
Gets the pending job for a resource (if any).
Gets all pending jobs that are due for execution.
Processes all pending jobs that are due for execution.
Reschedules a job to a new time.
Schedules a new job.
Functions
Cancels a scheduled job.
Only pending jobs can be cancelled. Returns error if job is already executed or cancelled.
Examples
iex> cancel_job(job)
{:ok, %ScheduledJob{status: "cancelled"}}
iex> cancel_job(already_executed_job)
{:error, :already_executed}Cancels all pending jobs for a specific resource.
Useful when deleting a resource or when rescheduling.
Examples
iex> cancel_jobs_for_resource("post", post.id)
{3, nil}Gets a scheduled job by ID.
Gets all scheduled jobs for a resource.
Examples
iex> get_jobs_for_resource("post", post.id)
[%ScheduledJob{}, ...]Gets the pending job for a resource (if any).
Examples
iex> get_pending_job_for_resource("post", post.id)
%ScheduledJob{status: "pending"}Gets all pending jobs that are due for execution.
Parameters
as_of- DateTime to check against (default: now)
Examples
iex> get_pending_jobs()
[%ScheduledJob{}, ...]Processes all pending jobs that are due for execution.
Called by the cron worker every minute. Jobs are processed in priority order (highest first), then by scheduled_at (oldest first).
Returns
{:ok, %{executed: count, failed: count}}- Processing summary
Examples
iex> process_pending_jobs()
{:ok, %{executed: 5, failed: 1}}Reschedules a job to a new time.
Resets attempts and clears any previous errors.
Examples
iex> reschedule_job(job, ~U[2025-01-20 10:00:00Z])
{:ok, %ScheduledJob{}}Schedules a new job.
Parameters
handler_module- Module implementingPhoenixKit.ScheduledJobs.Handlerresource_id- UUID of the target resourcescheduled_at- DateTime when the job should executeargs- Optional map of additional arguments (default: %{})opts- Optional keyword list with::priority- Job priority (default: 0):max_attempts- Max retry attempts (default: 3):created_by_id- UUID of user creating the job
Returns
{:ok, %ScheduledJob{}}- Job created successfully{:error, changeset}- Validation failed
Examples
iex> schedule_job(PostHandler, post.id, ~U[2025-01-15 10:00:00Z])
{:ok, %ScheduledJob{}}
iex> schedule_job(EmailHandler, email.id, scheduled_at, %{template: "welcome"}, priority: 10)
{:ok, %ScheduledJob{}}