Apex Scheduled Jobs

Apex Scheduled Jobs

Use this skill when designing, implementing, reviewing, or troubleshooting Apex classes that run on a time-based schedule using the Schedulable interface. The skill covers the full lifecycle: authoring, scheduling via cron expression, monitoring via CronTrigger, aborting, rescheduling, testing, and deployment considerations.

Before Starting

Gather this context before working in this domain:

• What is the scheduling target? Schedulable should act as the timer and dispatcher, not the data processor. Large-volume work belongs in Batch Apex or a Queueable dispatched from execute().
• What is the org's current scheduled job count? The platform limit is 100 scheduled jobs per org (shared across all types). Approaching this limit requires an audit before adding new jobs.
• Does the job need callouts? Scheduled Apex cannot make callouts directly. Callouts must be delegated to a @future(callout=true) method or a Queueable implementing Database.AllowsCallouts.
• Who will own the schedule post-deployment? Scheduled jobs are not deployed by the Metadata API. They must be created manually or via Anonymous Apex after deployment — plan for this in every release.
• Is this a sandbox refresh scenario? Scheduled jobs from production are not copied to a sandbox on refresh. Post-refresh scheduling must be scripted or run manually.

Core Concepts

The Schedulable Interface

A class becomes schedulable by implementing the Schedulable interface and defining a single global void execute(SchedulableContext SC) method. The global access modifier is required; public alone is insufficient.

global class MyScheduledJob implements Schedulable {
    global void execute(SchedulableContext SC) {
        // Dispatch work here — avoid heavy logic inline
    }
}

The SchedulableContext object provides getTriggerId(), which returns the CronTrigger record ID for the active job. This ID can be used inside execute() for self-identification or logging, but it cannot be used to modify or abort the job from within the same execution.

Cron Expressions

Salesforce uses a seven-field cron expression:

Seconds  Minutes  Hours  Day_of_month  Month  Day_of_week  [Year]

Key rules:

• Day_of_month and Day_of_week are mutually exclusive — one must always be ?.
• Seconds must be 0 — sub-minute scheduling is not supported.
• Field values are 0-indexed for seconds/minutes/hours; months and days of week use named constants or 1-based integers.

Common patterns:

Always schedule during off-peak hours to reduce contention with user traffic and other async jobs.

System.schedule() and the CronTrigger Object

A scheduled job is created with:

String jobId = System.schedule('Job Display Name', cronExpression, new MyScheduledJob());

• The first argument is the display name shown in Setup > Scheduled Jobs. It must be unique per org — duplicate names throw a System.AsyncException at runtime.
• The method returns a CronTrigger record ID (not an AsyncApexJob ID).
• Jobs can be scheduled from Anonymous Apex, a trigger, a controller, or another Apex class — but not from within a Schedulable's own execute() method to reschedule itself (use a separate post-execute mechanism if rescheduling is needed).

Monitor active jobs with:

SELECT Id, CronJobDetail.Name, CronExpression, State, NextFireTime, PreviousFireTime
FROM CronTrigger
WHERE State = 'WAITING'
ORDER BY NextFireTime ASC

CronTrigger.State values: WAITING, PAUSED, COMPLETE, ERROR, DELETED, BLOCKED.

Abort a scheduled job with:

System.abortJob('CronTrigger_Id_Here');

Mode Selection

This skill operates in three modes based on the practitioner's need:

• Mode 1 — Implement: Design and create a new scheduled job from scratch. Follow the Schedulable-as-dispatcher pattern and produce both the class and the scheduling call.
• Mode 2 — Review/Audit: Evaluate existing scheduled jobs in an org — query CronTrigger, check proximity to the 100-job limit, verify off-peak scheduling, and confirm that heavy work is delegated rather than inlined.
• Mode 3 — Troubleshoot: Diagnose a job that is not running, stuck in BLOCKED or ERROR state, or failing silently. Start with CronTrigger.State, then check AsyncApexJob for the most recent execution record.

Common Patterns

Schedulable as Dispatcher (Preferred Pattern)

When to use: Any case where the scheduled job processes records, performs DML, or does anything beyond trivial computation. This is the default pattern.

How it works:

1. The Schedulable class holds minimal state — typically a constructor parameter for scoping (e.g., record type, org-specific flag).
2. execute() instantiates and dispatches a Batch Apex class or enqueues a Queueable. It does not perform DML or SOQL at scale itself.
3. The Batch or Queueable carries all governor-intensive work within its own transaction limits.

global class NightlyLeadCleanupScheduler implements Schedulable {
    global void execute(SchedulableContext SC) {
        Database.executeBatch(new LeadCleanupBatch(), 200);
    }
}

Why not the alternative: Performing large SOQL queries or DML directly in execute() burns the Schedulable's governor limits (which are the same full limits as any Apex transaction). If the data volume grows, the job silently fails at governor limit boundaries with no automatic retry.

Self-Identifying Job for Conditional Logic

When to use: A single Schedulable class is reused for multiple schedules with different parameters, and the job needs to know which schedule triggered it.

How it works:

1. The SchedulableContext.getTriggerId() returns the CronTrigger.Id.
2. Query CronJobDetail from CronTrigger to retrieve the job name and branch logic accordingly.

global class MultiPurposeScheduler implements Schedulable {
    global void execute(SchedulableContext SC) {
        CronTrigger ct = [
            SELECT CronJobDetail.Name
            FROM CronTrigger
            WHERE Id = :SC.getTriggerId()
        ];
        if (ct.CronJobDetail.Name.contains('Nightly')) {
            Database.executeBatch(new NightlyBatch(), 200);
        } else {
            System.enqueueJob(new WeeklyReportQueueable());
        }
    }
}

Why not the alternative: Creating one Schedulable class per variation leads to class sprawl. A parameterized or self-identifying class reduces maintenance surface.

Abort-and-Reschedule for Schedule Changes

When to use: The cron schedule for a live job needs to change. There is no in-place modification API.

How it works:

1. Query CronTrigger to find the job ID by name.
2. Call System.abortJob(jobId).
3. Call System.schedule(sameName, newCronExpression, new MyScheduledJob()).

// Run from Anonymous Apex or a deployment script
List<CronTrigger> jobs = [
    SELECT Id FROM CronTrigger
    WHERE CronJobDetail.Name = 'Nightly Lead Cleanup'
    AND State = 'WAITING'
];
if (!jobs.isEmpty()) {
    System.abortJob(jobs[0].Id);
}
System.schedule('Nightly Lead Cleanup', '0 0 3 * * ?', new NightlyLeadCleanupScheduler());

Why not the alternative: Attempting to update CronExpression directly on the CronTrigger record via DML is not supported. The only path to change a schedule is abort and reschedule.

Decision Guidance

Recommended Workflow

Step-by-step instructions for an AI agent or practitioner activating this skill:

1. Gather context — confirm the org edition, relevant objects, and current configuration state
2. Review official sources — check the references in this skill's well-architected.md before making changes
3. Implement or advise — apply the patterns from Core Concepts and Common Patterns sections above
4. Validate — run the skill's checker script and verify against the Review Checklist below
5. Document — record any deviations from standard patterns and update the template if needed

Review Checklist

Run through these before marking scheduled job work complete:

• Class declares global (not public) access and implements Schedulable.
• execute(SchedulableContext SC) signature is correct — method is global void.
• Heavy work (SOQL at scale, DML at scale) is delegated to Batch or Queueable, not done inline.
• Cron expression is valid: seconds field is 0, Day_of_month and Day_of_week are mutually exclusive (?).
• Job name is unique in the org — duplicate names cause a runtime AsyncException.
• Job is scheduled during off-peak hours.
• Org is below 100 scheduled jobs — if close, a consolidation plan exists.
• No direct callouts in execute() — callouts are delegated to async contexts.
• Post-deployment scheduling script (Anonymous Apex) is prepared and documented.
• Test class uses Test.startTest() / Test.stopTest() and verifies CronTrigger state after scheduling.
• Sandbox refresh impact is understood and post-refresh scheduling is scripted.

Salesforce-Specific Gotchas

1. Scheduled jobs are not deployed by the Metadata API — The Schedulable class deploys, but the active job record in CronTrigger does not. Every release that changes or introduces a scheduled job requires a post-deployment step (Anonymous Apex or a post-install script) to create or recreate the schedule.

2. The 100-job limit is org-wide and shared — All scheduled Apex jobs, scheduled flows, and scheduled reports count against the same 100-job org limit. Orgs with many automations can exhaust this silently; new System.schedule() calls throw a System.AsyncException when the limit is reached.

3. Direct callouts from execute() are blocked at runtime — A Schedulable that attempts an HTTP callout throws System.CalloutException: Callout from scheduled Apex not supported. This must be delegated to a @future(callout=true) or Queueable with AllowsCallouts.

4. You cannot reschedule a job from within its own execute() method — Calling System.schedule() inside execute() throws a runtime exception. If a job needs to compute its next run time dynamically, use a Queueable dispatched from execute() to do the rescheduling.

5. Sandbox refreshes clear all scheduled jobs — Scheduled jobs from production are not carried to a refreshed sandbox. Teams that rely on scheduled jobs in sandboxes for testing or integration must re-create them after each refresh.

Output Artifacts

Related Skills

• apex/async-apex — use when the question is which async mechanism to choose (Schedulable vs Queueable vs Batch vs future).
• apex/batch-apex-patterns — use when the scheduled job needs to process large data volumes with chunked limits.
• apex/apex-queueable-patterns — use when the scheduled job needs to make callouts or chain async steps.
• apex/governor-limits — use when the scheduled job is hitting CPU, SOQL, or DML limits during execution.
• apex/debug-and-logging — use when diagnosing why a scheduled job failed or produced unexpected results.