Search documentation of phoenix_kit

# PhoenixKit.ScheduledJobs (phoenix_kit v1.7.87)

Copy Markdown View Source

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.uuid,
      ~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_uuid, args), do: :ok
    end

## Summary

### Functions

cancel_job(job)

Cancels a scheduled job.

cancel_jobs_for_resource(resource_type, resource_uuid)

Cancels all pending jobs for a specific resource.

delete_old_jobs(days \\ 7, statuses \\ ["executed", "failed", "cancelled"])

Deletes old completed jobs to prevent table bloat.

get_job(id)

Gets a scheduled job by ID.

get_jobs_for_resource(resource_type, resource_uuid)

Gets all scheduled jobs for a resource.

get_pending_job_for_resource(resource_type, resource_uuid)

Gets the pending job for a resource (if any).

get_pending_jobs(as_of \\ UtilsDate.utc_now())

Gets all pending jobs that are due for execution.

process_pending_jobs()

Processes all pending jobs that are due for execution.

reschedule_job(job, new_scheduled_at)

Reschedules a job to a new time.

schedule_job(handler_module, resource_uuid, scheduled_at, args \\ %{}, opts \\ [])

Schedules a new job.

## Functions

# cancel_job(job)

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}

# cancel_jobs_for_resource(resource_type, resource_uuid)

Cancels all pending jobs for a specific resource.

Useful when deleting a resource or when rescheduling.

## Examples

    iex> cancel_jobs_for_resource("post", post.uuid)
    {3, nil}

# delete_old_jobs(days \\ 7, statuses \\ ["executed", "failed", "cancelled"])

Deletes old completed jobs to prevent table bloat.

## Parameters

- `days` - Retention period in days (default: 7)
- `statuses` - List of statuses to delete (default: ["executed", "failed", "cancelled"])

## Returns

- `{count, nil}` - Number of deleted records

## Examples

    iex> delete_old_jobs(7)
    {1234, nil}

    iex> delete_old_jobs(30, ["executed"])
    {500, nil}

# get_job(id)

Gets a scheduled job by ID.

# get_jobs_for_resource(resource_type, resource_uuid)

Gets all scheduled jobs for a resource.

## Examples

    iex> get_jobs_for_resource("post", post.uuid)
    [%ScheduledJob{}, ...]

# get_pending_job_for_resource(resource_type, resource_uuid)

Gets the pending job for a resource (if any).

## Examples

    iex> get_pending_job_for_resource("post", post.uuid)
    %ScheduledJob{status: "pending"}

# get_pending_jobs(as_of \\ UtilsDate.utc_now())

Gets all pending jobs that are due for execution.

## Parameters

- `as_of` - DateTime to check against (default: now)

## Examples

    iex> get_pending_jobs()
    [%ScheduledJob{}, ...]

# process_pending_jobs()

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}}

# reschedule_job(job, new_scheduled_at)

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{}}

# schedule_job(handler_module, resource_uuid, scheduled_at, args \\ %{}, opts \\ [])

Schedules a new job.

## Parameters

- `handler_module` - Module implementing `PhoenixKit.ScheduledJobs.Handler`
- `resource_uuid` - UUID of the target resource
- `scheduled_at` - DateTime when the job should execute
- `args` - 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_uuid` - UUID of user creating the job

## Returns

- `{:ok, %ScheduledJob{}}` - Job created successfully
- `{:error, changeset}` - Validation failed

## Examples

    iex> schedule_job(PostHandler, post.uuid, ~U[2025-01-15 10:00:00Z])
    {:ok, %ScheduledJob{}}

    iex> schedule_job(EmailHandler, email.uuid, scheduled_at, %{template: "welcome"}, priority: 10)
    {:ok, %ScheduledJob{}}