Scheduled Tasks in Joomla

1. The Basics

1.1 What Are Scheduled Tasks?

The Scheduled Tasks component (com_scheduler) lets you run a piece of work automatically on a timing rule. Joomla introduced it in version 4.1 (early 2022), and it has shipped in core ever since. It replaces the old pattern of writing your own cron scripts for routine Joomla maintenance.

A few ideas make it special:

• Each task is one row in a single table: #__scheduler_tasks.
• A task does not contain code. It points to a task routine that a plugin provides. The plugin does the actual work.
• Timing is data, not code. You pick a rule ("every 6 hours", "every night at 03:00", or a full cron expression) and Joomla calculates the next run.
• Tasks can run from web traffic, from a real server cron, from the command line, or from a secure webcron URL. You choose.

In short: the component is the manager, the plugins are the workers, and the table is the to-do list.

1.2 Where Do I Find It?

In the Joomla 6 backend, these places are relevant:

System → Manage → Scheduled Tasks            (the task list)
System → Manage → Scheduled Tasks → New      (create a task)
System → Manage → Scheduled Tasks → Options  (settings + ACL)
System → Manage → Plugins (filter "Task")     (the task routines)

The component lives at administrator/components/com_scheduler/. The task routines live as plugins under plugins/task/. There is one more piece: a system plugin, System - Schedule Runner (plg_system_schedulerunner), which lets web visitors trigger due tasks in the background.

1.3 The Three Pieces

Scheduled Tasks is built from three parts that work together:

Disable the task plugin and its routine disappears from the "New Task" list. Disable the Schedule Runner and the web-based triggering stops, although a real server cron still works.

1.4 A Task vs a Routine

This distinction trips up a lot of people, so fix it early:

• A routine is a capability that a plugin offers, identified by a string such as session.gc or delete.actionlogs. It is the same for every site.
• A task is your configured instance of a routine: a title, a timing rule, some parameters, and a state. You can create several tasks from the same routine, for example two "Make a GET request" tasks pointing at two different URLs.

A routine is the recipe. A task is the meal you actually scheduled.

3. The Core Task Types

Joomla 6 ships nine task plugins out of the box. Together they cover the most common maintenance chores. Here is what each one does and the routine id it provides.

Two of these deserve a special mention. Update Notification turns Joomla into something that watches its own version for you, which is one of the simplest security wins on any site. And Requests is the bridge to the outside world: schedule a GET to a webhook and you can trigger anything an external service exposes, from a Slack message to a cache warm-up on a CDN.

5. How Tasks Actually Run

Defining a task does not make it run. Something has to wake the Scheduler up and ask "is anything due?". Joomla offers four ways to do that, and choosing the right one is the single most important decision you will make with this component.

5.1 The Lazy Scheduler (web traffic)

This is the default. When Lazy Scheduler is enabled in the Options, the Schedule Runner plugin injects a tiny background request into ordinary page loads. When a real visitor opens your site and a task is due, that visitor's page silently triggers the task through an AJAX call (onAjaxRunSchedulerLazy).

It is convenient and needs no server configuration, but it has a weakness: no traffic means no runs. A quiet site at 03:00 will not run its nightly task until the first visitor arrives in the morning. The lazy scheduler also has a minimum interval (default 300 seconds) so it does not fire on every single page view.

5.2 A Real Server Cron (recommended)

For reliable timing, let the operating system do the waking. Add one line to the server crontab that calls the Joomla CLI every few minutes:

*/5 * * * * /usr/bin/php /path/to/site/cli/joomla.php scheduler:run --all

Now the Scheduler is checked every five minutes regardless of visitors. This is the professional choice for any site where timing matters. See section 8 for the full command.

5.3 The Webcron URL

If you cannot add a system cron but your host (or an external service like a monitoring tool) can fetch a URL on a schedule, enable Web Cron in the Options. Joomla generates a secret key and builds a URL like this:

https://example.test/index.php?option=com_ajax&plugin=RunSchedulerWebcron
       &group=system&format=json&hash=YOUR_SECRET_KEY

Whatever fetches that URL triggers the due tasks (onAjaxRunSchedulerWebcron). Add &id=5 to run only task id 5. The hash is what keeps strangers from triggering your tasks, so treat it like a password and never share it in public.

5.4 The Test Run Button

The Test Run icon in the backend list fires a single task on demand (onAjaxRunSchedulerTest). It ignores the schedule and is meant for checking a task right after you create it. Use it freely while setting up; do not rely on it for production timing.

5.5 Which Should You Use?

On a site you care about, set up a server cron and switch the lazy scheduler off. That removes the small overhead from your visitors' page loads and gives you timing you can trust.

7. Writing Your Own Task Plugin

7.1 The Shape of a Task Plugin

A task plugin is an ordinary Joomla plugin in the task group. It does three things: it advertises its routines, it runs them, and it optionally adds form fields for its parameters. Joomla gives you a trait, TaskPluginTrait, that handles most of the plumbing.

The heart of the plugin is a TASKS_MAP constant that maps each routine id to a method and a language prefix:

protected const TASKS_MAP = [
    'mycompany.cleanup' => [
        'langConstPrefix' => 'PLG_TASK_MYCLEANUP',
        'method'          => 'doCleanup',
        'form'            => 'cleanupForm',
    ],
];

7.2 Subscribing to the Events

The plugin subscribes to the Scheduler's events. onTaskOptionsList makes the routine appear in the "New Task" list; onExecuteTask runs it:

public static function getSubscribedEvents(): array
{
    return [
        'onTaskOptionsList'    => 'advertiseRoutines',
        'onExecuteTask'        => 'standardRoutineHandler',
        'onContentPrepareForm' => 'enhanceTaskItemForm',
    ];
}

The first two handlers come straight from TaskPluginTrait. You only write the routine method itself.

7.3 The Routine Method

Your method receives the execute event, does the work, and returns one of the status codes from section 6:

protected function doCleanup(ExecuteTaskEvent $event): int
{
    $params = $event->getArgument('params');

    // ... do the actual work here ...

    $this->logTask('Cleanup finished.');

    return Status::OK;   // 0 = success
}

Return Status::OK when all is well, or another constant to signal a problem. Joomla records the code, updates the counters, and recalculates the next run. That is the whole contract: subscribe, advertise, run, return a code.

7.4 The Key Classes

If you ever want a worked example, the nine core plugins under plugins/task/ are short, readable, and follow exactly this pattern. sessiongc is the simplest place to start.

7.5 Long-running Work: Batching with WILL_RESUME

What about a job too big for one run, such as resizing ten thousand images or emailing a newsletter to every subscriber? Run it in one go and it will hit a PHP memory limit or a time limit, especially under the lazy scheduler or a webcron, where the trigger lives inside a normal web request.

Joomla solves this with a dedicated exit code, Status::WILL_RESUME (123). The idea is simple: do one small batch per run, then tell Joomla you are not finished yet.

• Process a manageable chunk (say 100 records), then return Status::WILL_RESUME.
• Joomla logs the run as a success and leaves the task due, so the next trigger calls your routine again for the next batch.
• When the final batch is done, return Status::OK and the task settles back onto its normal schedule.

The shape of a resumable routine looks like this:

protected function doImport(ExecuteTaskEvent $event): int
{
    $offset = (int) $this->getProgress();   // where the last batch stopped

    $batch = $this->fetchRecords($offset, 100);

    foreach ($batch as $record) {
        $this->processOne($record);
    }

    if (\count($batch) < 100) {
        $this->clearProgress();
        return Status::OK;            // last batch, we are done
    }

    $this->saveProgress($offset + 100);
    return Status::WILL_RESUME;       // more to do, run me again
}

One thing the framework does not do for you: it does not remember where you were. Each run is a fresh call, so your routine must persist its own progress (a cursor, an offset, or the ids already handled) between batches. Store it somewhere durable, such as the task parameters or your own table, and read it back at the start of the next run.

Keep each batch comfortably inside the global timeout from section 6.2, and keep the work idempotent so that a batch which runs twice (after a crash, for example) does no harm. None of the nine core task plugins need this pattern, but it is exactly how you would build a serious import, export, or bulk-mail task on top of the Scheduler.

9. Web Services and Headless

A common question: does the Scheduler have a REST API under /api, like articles or contacts do? In Joomla 6 the answer is no. The component does not register a Web Services route, so there is no v1/scheduler/tasks endpoint to create or list tasks over REST.

What it offers instead is the webcron endpoint, which is a triggering mechanism rather than a data API. It runs due tasks but does not let you read or edit task definitions:

curl "https://example.test/index.php?option=com_ajax&plugin=RunSchedulerWebcron&group=system&format=json&hash=<key>"

For everything else, treat the Scheduler as a server-side tool. If you need to manage tasks programmatically, use the PHP Scheduler and Task classes from section 7 inside your own code, or drive the CLI commands from a deployment script. For remote triggering on a timer, point an external monitoring service at the webcron URL.

11. Common Mistakes and Pitfalls

11.1 "My nightly task never runs"

Symptom: a task scheduled for 03:00 only runs hours later, or not at all.

Fix: you are relying on the lazy scheduler on a low-traffic site. No visitor at 03:00 means no trigger. Set up a real server cron (section 8) so timing no longer depends on traffic.

11.2 "Last exit code is 127"

Symptom: the task fails immediately with exit code 127.

Fix: NO_ROUTINE means Joomla cannot find the plugin that provides the routine. The task plugin is probably disabled or uninstalled. Re-enable it under System → Plugins, filtered by the Task group.

11.3 "The same task ran twice"

Symptom: a job appears to execute twice close together.

Fix: usually two triggers fired before the lock was written, or a server cron and the lazy scheduler are both active. Pick one trigger method and disable the lazy scheduler when you use a server cron.

11.4 "A task is stuck and will not run again"

Symptom: a task shows as running forever and never fires again.

Fix: the run crashed and left the locked column set. Wait for the timeout (default 300 seconds) to expire and Joomla clears the stale lock by itself. If it never recovers, lower the timeout or unlock the task from the list toolbar.

11.5 "I shared my webcron URL and tasks fire randomly"

Symptom: tasks run at odd times after the webcron URL leaked.

Fix: the hash in the URL is a secret. Regenerate the key in the Options to invalidate the old URL, then keep the new one private.

11.6 "The site went offline on its own"

Symptom: the site is unexpectedly in offline mode.

Fix: check for a Site Status task. Its whole job is to toggle the site online or offline, and a misconfigured schedule will do exactly that. Disable or retime the task.

13. Quick Reference

COMPONENT      System → Manage → Scheduled Tasks
NEW TASK       Scheduled Tasks → New (pick a routine)
OPTIONS        Scheduled Tasks → Options (timeout, lazy, webcron)
TASK PLUGINS   System → Plugins (filter "Task")
RUNNER PLUGIN  System - Schedule Runner (plg_system_schedulerunner)
MAIN TABLE     #__scheduler_tasks
LOGS TABLE     #__scheduler_logs (run history; Clear Logs to empty)
LOGS VIEW      Scheduled Tasks → Logs (filter by exit code)
RULE TYPES     interval-minutes/-hours/-days/-months, cron-expression, manual
TRIGGERS       lazy scheduler, server cron, webcron URL, Test Run
CLI RUN        php cli/joomla.php scheduler:run --all
CLI ONE        php cli/joomla.php scheduler:run --id N
CLI LIST       php cli/joomla.php scheduler:list
WEBCRON URL    index.php?option=com_ajax&plugin=RunSchedulerWebcron
               &group=system&format=json&hash=KEY
EXIT 0         OK (success)
EXIT 124       TIMEOUT          EXIT 127  NO_ROUTINE (plugin missing)
STATE          1 enabled, 0 disabled, -2 trashed
LOCK           "locked" timestamp; cleared after timeout (default 300s)
SINCE          Joomla 4.1 (2022)