Scheduled tasks

Scheduled tasks are tasks that will run on a regular schedule. A default schedule can be set, but administrators have the ability to change the default schedule if required.

note

Tasks will only run as often as cron is run in Moodle. It is recommended that cron be run at least once per minute to get the most benefit from the task scheduling.

Creating scheduled tasks

To create a new scheduled task and set its default configuration you should:

1. create a new class which extends the \core\task\scheduled_task class;
2. create an entry for your scheduled task in the db/tasks.php file within your plugin; and
3. increment the version number for your plugin.

Task class

The class for your scheduled task, which extends the \core\task\scheduled_task class, should be in the classes/task directory of your plugin.

View example scheduled task

namespace mod_example\task;

/**
 * An example of a scheduled task.
 */
class do_something extends \core\task\scheduled_task {

    /**
     * Return the task's name as shown in admin screens.
     *
     * @return string
     */
    public function get_name() {
        return get_string('dosomething', 'mod_example');
    }

    /**
     * Execute the task.
     */
    public function execute() {
        // Call your own api
    }
}

db/tasks.php

Task schedule configuration

Upgradable

File path: /db/tasks.php

The db/tasks.php file contains the initial schedule configuration for each of your plugins scheduled tasks. Adhoc tasks are not run on a regular schedule and therefore are not described in this file.

Editing the schedule for an existing task

If an existing task is edited, it will only be updated in the database if the administrator has not customised the schedule of that task in any way.

The following fields also accept a value of R, which indicates that Moodle should choose a random value for that field:

• minute
• hour
• dayofweek
• day

See db/tasks.php for full details of the file format.

View example

[path/to/plugintype]/pluginname/db/tasks.php

<?php
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.

/**
 * Task schedule configuration for the plugintype_pluginname plugin.
 *
 * @package   plugintype_pluginname
 * @copyright Year, You Name <your@email.address>
 * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */

$tasks = [
    [
        'classname' => 'mod_example\task\do_something',
        'blocking' => 0,
        'minute' => '30',
        'hour' => '17',
        'day' => '*',
        'month' => '1,7',
        'dayofweek' => '0',
    ],
];

Running tasks for disabled plugins

In rare cases, you may want the scheduled tasks for a plugin to run, even when the plugin is disabled. One example use-case is in Enrolment plugins where a disabled plugin must still clear up data.

To support this, your scheduled task must override the get_run_if_component_disabled() method to return true.

Debugging

When called from the command line for testing purposes errors can be hidden and a misleading error about locks can be displayed. You can view more information of the error using the --showdebugging parameter when calling the scheduled task from the CLI.