Migration to the TCA registration for scheduler tasks
Deprecated since version 14.0
Registering tasks and additional field providers via
$GLOBALS
has
been deprecated.
The
Additional
and
Abstract
have also
been deprecated.
Table of contents
Migrating tasks with AdditionalFieldProviders to TCA registration
Scheduler tasks should now be registered as native task types using TCA. This provides a more integrated and maintainable approach to task configuration.
Migration steps:
- Remove the registration from
ext_
localconf. php - Create a TCA override file in
Configuration/
TCA/ Overrides/ scheduler_ my_ task_ type. php - Update your task class to implement the new parameter methods
- Remove the
Additional
class if it existsField Provider
Note
The new TCA-based approach automatically migrates existing task data.
When upgrading, existing task configurations are preserved through the
get
and
set
methods.
Example migration: Scheduler task with additional fields suppporting TYPO3 13 and 14
Remove the registration from ext_
once TYPO3 13 support is
dropped:
<?php
declare(strict_types=1);
use MyVendor\MyExtension\Task\MyTask;
if ((new \TYPO3\CMS\Core\Information\Typo3Version())->getMajorVersion() < 14) {
// Todo: Remove when TYPO3 13 support is dropped
$GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['scheduler']['tasks'][MyTask::class] = [
'extension' => 'my_extension',
'title' => 'LLL:EXT:my_extension/Resources/Private/Language/locallang.xlf:myTask.title',
'description' => 'LLL:EXT:my_extension/Resources/Private/Language/locallang.xlf:myTask.description',
'additionalFields' => \MyVendor\MyExtension\Task\MyTaskAdditionalFieldProvider::class,
];
}
And also remove the
My
class once
TYPO3 13 support is dropped.
Create a TCA override file in Configuration/
:
<?php
declare(strict_types=1);
use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;
use MyVendor\MyExtension\Task\MyTask;
defined('TYPO3') or die();
if (isset($GLOBALS['TCA']['tx_scheduler_task'])) {
// Add custom fields to the tx_scheduler_task table
ExtensionManagementUtility::addTCAcolumns(
'tx_scheduler_task',
[
'my_extension_field' => [
'label' => 'LLL:EXT:my_extension/Resources/Private/Language/locallang.xlf:field.label',
'config' => [
'type' => 'input',
'size' => 30,
'required' => true,
'eval' => 'trim',
'placeholder' => 'Enter value here...',
],
],
'my_extension_email_list' => [
'label' => 'LLL:EXT:my_extension/Resources/Private/Language/locallang.xlf:emailList.label',
'config' => [
'type' => 'text',
'rows' => 3,
'required' => true,
'placeholder' => 'admin@example.com',
],
],
]
);
// Register the task type
ExtensionManagementUtility::addRecordType(
[
'label' => 'Some title or LLL:EXT reference',
'description' => 'Some description or LLL:EXT reference',
'value' => MyTask::class,
'icon' => 'mimetypes-x-tx_scheduler_task_group',
'group' => 'my_extension',
],
'
--div--;LLL:EXT:core/Resources/Private/Language/Form/locallang_tabs.xlf:general,
tasktype,
task_group,
description,
my_extension_field,
my_extension_email_list,
--div--;LLL:EXT:scheduler/Resources/Private/Language/locallang.xlf:scheduler.form.palettes.timing,
execution_details,
nextexecution,
--palette--;;lastexecution,
--div--;LLL:EXT:core/Resources/Private/Language/Form/locallang_tabs.xlf:access,
disable,
--div--;LLL:EXT:core/Resources/Private/Language/Form/locallang_tabs.xlf:extended,',
[],
'',
'tx_scheduler_task'
);
}
Update your (existing) task class to implement the new methods:
<?php
declare(strict_types=1);
namespace MyVendor\MyExtension\Task;
use MyVendor\MyExtension\BusinessLogic;
use TYPO3\CMS\Core\Messaging\FlashMessage;
use TYPO3\CMS\Core\Messaging\FlashMessageService;
use TYPO3\CMS\Core\Type\ContextualFeedbackSeverity;
use TYPO3\CMS\Core\Utility\GeneralUtility;
use TYPO3\CMS\Scheduler\Task\AbstractTask;
final class MyTask extends AbstractTask
{
protected string $myField = '';
protected string $emailList = '';
public function execute(): bool
{
# Dependency injection cannot be used in scheduler tasks
$businessLogic = GeneralUtility::makeInstance(BusinessLogic::class);
return $businessLogic->run($this->myField, $this->emailList, '…');
}
/**
* Return current field values as associative array.
* This method is called during migration from old serialized tasks
* and when displaying task information.
*/
public function getTaskParameters(): array
{
return [
'my_extension_field' => $this->myField,
'my_extension_email_list' => $this->emailList,
];
}
/**
* Set field values from associative array.
* This method handles both old and new parameter formats for migration.
*
* @param array $parameters Values from either old AdditionalFieldProvider or new TCA fields
*/
public function setTaskParameters(array $parameters): void
{
// Handle migration: check old parameter names first, then new TCA field names
$this->myField = $parameters['myField'] ?? $parameters['my_extension_field'] ?? '';
$this->emailList = $parameters['emailList'] ?? $parameters['my_extension_email_list'] ?? '';
}
/**
* Validate task parameters.
* Only implement this method for validation that cannot be handled by FormEngine.
* Basic validation like 'required' should be done via TCA 'eval' configuration.
*/
public function validateTaskParameters(array $parameters): bool
{
$isValid = true;
// Example: Custom email validation (beyond basic 'required' check)
$emailList = $parameters['my_extension_email_list'] ?? '';
if (!empty($emailList)) {
$emails = GeneralUtility::trimExplode(',', $emailList, true);
foreach ($emails as $email) {
if (!GeneralUtility::validEmail($email)) {
GeneralUtility::makeInstance(FlashMessageService::class)
->getMessageQueueByIdentifier()
->addMessage(
GeneralUtility::makeInstance(
FlashMessage::class,
'Invalid email address: ' . $email,
'',
ContextualFeedbackSeverity::ERROR
)
);
$isValid = false;
}
}
}
return $isValid;
}
public function getAdditionalInformation(): string
{
$info = [];
if ($this->myField !== '') {
$info[] = 'Field: ' . $this->myField;
}
if ($this->emailList !== '') {
$info[] = 'Emails: ' . $this->emailList;
}
return implode(', ', $info);
}
/**
* is called by additional field provider
* Todo: Remove setters once TYPO3 13 support is dropped
* @deprecated
*/
public function setMyField(string $myField): void
{
$this->myField = $myField;
}
/**
* is called by additional field provider
* Todo: Remove setters once TYPO3 13 support is dropped
* @deprecated
*/
public function setEmailList(string $emailList): void
{
$this->emailList = $emailList;
}
}
The new TCA-based approach uses three key methods for parameter handling:
- getTaskParameters(): array
-
This method is already implemented in
AbstractTask
to handle task class properties automatically, but can be overridden in task classes for custom behavior.The method is primarily used:
- For migration from old serialized task format to new TCA structure
- For non-native (deprecated) task types to store their values in the legacy
parameters
field
For native TCA tasks, this method is typically no longer needed in custom tasks after the migration has been done, since field values are then stored directly in database columns.
- setTaskParameters(array $parameters): void
-
Sets field values from an associative array. This method handles:
- Migration from old AdditionalFieldProvider field names to new TCA field names
- Loading saved task configurations when editing or executing tasks
- Parameter mapping during task creation and updates
- The method should always be implemented, especially for native tasks
The migration pattern is:
$this->my
Field = $parameters ['old Name'] ?? $parameters ['new_ tca_ field_ name'] ?? ''; - validateTaskParameters(array $parameters): bool
-
Optional method. Only implement this for validation that cannot be handled by FormEngine.
- Basic validation (required, trim, etc.) should be done via TCA configuration (
required
property andeval
options) - Use this method for complex business logic validation (e.g., email format validation, external API checks)
- Return
false
and add FlashMessage for validation errors - FormEngine automatically handles standard TCA validation rules
- Basic validation (required, trim, etc.) should be done via TCA configuration (
For a complete working example, see
\TYPO3\
and its corresponding TCA configuration in
EXT:
.