Plugin Development: Scheduled Tasks
Previous Section: Extending Templates
If your plugin needs to perform a recurring task, you can set up a scheduled task to run on your chosen schedule for the plugin.
Why Use a Scheduled Task?
Scheduled tasks let you run a function on a recurring basis at an interval of your choice. Example cases where this is useful:
- Check for tickets from an external source (our Facebook and X channels)
- Perform actions that are not currently covered by our macro, follow up or escalation rules systems
Registering a Scheduled Task
A task can be registered by using the Scheduled Task model's register method in the plugin's activate function. The first parameter is the name of the task, the second is a description that is shown on the scheduled tasks page and the third is the frequency in seconds. The frequency should be reduced by 15 seconds as this is the buffer we account for to ensure it does not add an extra minute when actually running. For example, you would enter 885 for every 15 minutes, or 3585 for every hour.
public function activate()
{
// Add scheduled task
\App\Modules\Core\Models\ScheduledTask::register(
'My Task',
'This is my task for My Plugin.',
885
);
return true;
}
When the plugin is now activated, it will add the scheduled task which will be visible when you visit Settings -> Core -> Scheduled Tasks.
Remove Scheduled Task
A task can be removed by using the Scheduled Task model's deregister method in the plugin's deactivate and uninstall functions. It should be ran in both functions as the task must be removed if the plugin is no longer active or installed.
public function deactivate()
{
// Remove scheduled task
\App\Modules\Core\Models\ScheduledTask::deregister();
return true;
}
public function uninstall()
{
// Remove scheduled task
\App\Modules\Core\Models\ScheduledTask::deregister();
return true;
}
Running Scheduled Task
The scheduled task is now set up and scheduled to run on the interval you've set, but you still need to code what it should do. The plugin controller must implement ScheduledTaskInterface and then define a runTask function which is what is ran each time the scheduled task runs, like below.
<?php
namespace Addons\Plugins\HelloWorld\Controllers;
use App\Modules\Core\Controllers\Plugins\Plugin;
use App\Modules\Core\Interfaces\ScheduledTaskInterface;
class HelloWorld extends Plugin implements ScheduledTaskInterface
{
...
public function runTask()
{
// Run our task code
}
}
The function doesn't need a return statement, but it should throw an exception with a message is there is an error, this will log the error in application log files.