EXT: Scheduler

Extension Key: scheduler

Language: en

Keywords: forAdmins, forIntermediates

Copyright 2000-2011, François Suter, <francois@typo3.org>

This document is published under the Open Content License

available from http://www.opencontent.org/opl.shtml

The content of this document is related to TYPO3

- a GNU/GPL CMS/Framework available from www.typo3.org

Table of Contents

EXT: Scheduler	1

Introduction	3

What does it do?	3

Screenshots	3

Credits	3

Overview	4

Why a scheduling tool?	4

Tasks management	4

Tasks execution	4

Follow-up	4

Glossary	4

Installation	5

Installing the extension	5

Checking the setup	5

The Scheduler user	5

The Scheduler shell script	5

Setting up the cron job	6

The base tasks	6

Administration	8

The backend module	8

Adding or editing a task	10

Deleting a task	11

Stopping a task	11

Manually executing a task	11

Developer's Guide	12

Creating a new task	12

Scheduler API	15

Known problems	16

To-Do list	17

ChangeLog	18

Appendix A – Technical Background	19

Appendix B – Migrating from Gabriel	20

Events	20

Database records	20

Introduction

What does it do?

The Scheduler is designed to be the central place to manage all kind of tasks that need to be executed on a regular basis, without needing someone to actually press a button.

Screenshots

This is a view of the BE module's main screen, where you can see all tasks that are currently registered with the Scheduler.

Credits

The Scheduler derives from extension Gabriel, originally developed by Christian Jul Jensen and further developed by Markus Friedrich.

A lot of clean up and optimization was done during core integration. This results in the Scheduler and Gabriel not being compatible. It is however not such a big work to adapt an existing Gabriel event to run with the Scheduler and the differences between the two extensions are described in Appendix B, to help developers make the transition as smoothly as possible.

The Scheduler's extension icon is taken from the famous Silk Icons set (http://www.famfamfam.com/lab/icons/silk/).

Overview

Why a scheduling tool?

When running and maintaining a complex system like TYPO3, there are a number of tasks that need to be automated or executed in the small hours, when no one is around to press the button. Indeed quite a few extensions come with some command-line scripts meant to be run regularly using cron jobs. When each of these scripts need their separate entry in the server's crontab, maintenance complexity increases, as well as the cost of migration. Furthermore there's no simple way to keep an overview of and manage these tasks inside TYPO3.

The Scheduler aims to address this issue.

Tasks management

Scripts can be developed as Scheduler tasks by extending a base class provided by the Scheduler. They can then be registered with the Scheduler. At that point it becomes possible to set up a schedule for them by using the Scheduler's BE module.

The BE module provides an overview of all scheduled tasks and some indication of their status, e.g. are they currently running or are they late, did something wrong happen during last execution, etc. It is also possible to manually start the execution of tasks from the BE module.

Tasks execution

The Scheduler provides a command-line tool to be run by TYPO3's command-line dispatcher. Only this script needs to be registered in the server's cron tab for all other recurring tasks to be executed. Indeed every time the Scheduler is launched by the cron daemon, it will look for all tasks that are due (or overdue) and execute them.

When a task is executed by the Scheduler it is marked as being executed in the corresponding database record (in the field called “serialized_executions”). When the task has finished running, the execution is removed from the database record. This mechanism makes it possible to know that a given task is currently running and also helps prevent multiple executions. Indeed it may be that a task requires more time to run than the frequency it is set up for. In such a case a new run may be started which is not always desirable. It is possible to deny such parallel (or multiple) executions.

Follow-up

Whenever a task starts or ends a message is written to TYPO'3 system log (viewable in the Admin Tools > Log module). A message is also written when a parallel execution has been blocked. This makes it possible to follow what happens, since the main purpose of the Scheduler is to run things when nobody is watching.

A task that fails may report on the reasons for failure using exceptions. Such a message will be logged in the Scheduler's database table and will be displayed in the BE module.

There's no default output to the command-line as scheduled tasks are designed to run in the background.

Glossary

A few terms need to be defined more precisely:

Task: this word is used quite generally throughout this document, sometimes to cover different meanings. A task is really a piece of code that does a precise task and can be registered with the Scheduler in order to execute that piece of code at a precise time, recurrently or not.

Task class: this is the type of task. The “test” task is one particular task class. Its function is to send an email. The “sleep” task is another task class.

Registered task: an instance of a task class that has been registered with the Scheduler. A given task class may be registered several times, for example if it needs to be executed with different parameters.

Installation

Installing the extension

The process is pretty straightforward: just install the extension in the Extension Manager. One database table will be created. Once the extension is installed, the following settings are available:

Maximum lifetime: it may happen that a task crashes while executing. In this case it will stay in a state marked as “running”. That may prevent it from being executed again, if parallel executions are denied (see “Tasks execution” above). The maximum lifetime parameter ensures that old executions are removed after a while. The lifetime is expressed in minutes. The default is 15 minutes.

Enable logging: by default, the Scheduler will write an entry in the BE log every time it starts and ends, and also when it skips a (denied) parallel execution. This is helpful when setting up a system, but it may end up cluttering the log in the log run. It's possible to turn off all logging by unchecking this option.

Enable sample tasks: the Scheduler provides two sample tasks (called "Scheduler test task" and "Scheduler sleep task") which are useful during development and as code examples. However they have little use in real life, so this option makes it possible to turn them off. If disabled, they won't appear in the list of available tasks anymore.

Checking the setup

After installing the Scheduler, go to its BE module and call up the “Setup check” screen which runs a couple of basic checks on your installation. It will probably look something like this:

The first warning just means that the Scheduler has never run yet and can be safely ignored for now. The second message is an error and must be addressed. See next section.

The third message should normally be okay. If there's an error instead, it means that permissions to execute TYPO3's command-line dispatcher must be checked (this is not strictly related to the Scheduler).

The Scheduler user

When tasks are launched manually from the BE module, they are executed using the current BE user. When they are run from the command line, however, there needs to be a specific user, called “_cli_scheduler”.

This can be a simple BE user with no specific rights at first. However some tasks may need to check some specific rights, for example if they use TCEmain. It may thus be necessary, depending on the tasks that you run, to give additional rights to the “cli_scheduler” user.

The Scheduler shell script

The Scheduler provides a PHP shell script designed to be run using TYPO3's command-line dispatcher. To try and run that script a first time, type the following command (adapting the path to PHP and TYPO3 to match your system):

/usr/local/bin/php /home/bob/www/typo3/cli_dispatch.phpsh scheduler

If the “cli_scheduler” user was not created, this will result in the following error:

ERROR: No backend user named "_cli_scheduler" was found! [Database: my_typo3_database]

If the user exists, you should see nothing, as the Scheduler doesn't give any visual feedback while running.

Setting up the cron job

Tasks registered with the Scheduler can be run manually from the BE module. However this is of limited use. To really benefit from the Scheduler, it must be set up on the server to run regularly. The following chapters describe how to set this up on Unix or Unix-like system (including Mac OS X) and on Windows.

Choosing a frequency

Whatever system the Scheduler will run on, the first step is to define the frequency at which it should run. The Scheduler script should set up to run pretty often, but not unnecessarily often either. The frequency should be that of the most often running task or some frequency that fits all tasks.

For example, if you have some tasks running every quarter of an hour and some others running every hour, it is useless to have the Scheduler run every 5 minutes. On the other hand, if you have tasks scheduled to run every 10 minutes and others every 15 minutes, you will want to run the Scheduler every 5 minutes. Indeed, if you run it only at 10-minute intervals, it will run – assuming it is 8 o'clock – at 08:10, 08:20, 08:30, etc.. So the tasks that should run at 08:15 will actually run 5 minutes late.

On Unix and Mac OS X

On such systems the Scheduler must be set up as a cron job. There are several ways to achieve this, although the simplest is probably to add it to some user's crontab. Edit that user's crontab using:

crontab -e

and add a line like

*/15 * * * * /usr/local/bin/php /home/bob/www/typo3/cli_dispatch.phpsh scheduler

Save the modified crontab. Obviously the paths have to be adapted to your system. The above command will call up the Scheduler every 15 minutes.

If you are editing system crontabs (for example /etc/crontab and /etc/cron.d/*), there will be one additional parameter to enter, i.e. the user with which the job should run. Example (additional user parameter in bold):

*/15 * * * * www /usr/local/bin/php /home/bob/www/typo3/cli_dispatch.phpsh scheduler

This will run the job as user “www”.

If you are not familiar with cron syntax, refer to some Unix administration book or start with the Wikipedia page about it (http://en.wikipedia.org/wiki/Cron).

On Windows

On Windows, cron jobs are called “Scheduled tasks” and run with the schtasks utility. SchTasks.exe performs operations similar to those provided by Scheduled Tasks in the Control Panel. You can use either tool to create, delete, configure, or simply display scheduled tasks.

Assuming you want to run the TYPO3 Scheduler every 15 minutes, use the following command line to create a new task:

schtasks /create /sc minute /mo 15 /tn "T3scheduler" /tr "c:\winstaller\php\php.exe c:\winstaller\htdocs\quickstart\typo3\cli_dispatch.phpsh scheduler"

At task creation you will be prompted to give a password or you can use the /u and /p switches to provide user and password information. Note that the user must be a member of the Administrators group on the computer where the command will run.

The full reference for schtasks is available at: http://technet.microsoft.com/en-us/library/bb490996.aspx

The base tasks

The Scheduler comes by default with one task for collecting garbage from the caching framework. Some other system extensions also provide tasks, in particular the Extension Manager, which defines one for updating the available extensions list.

The Scheduler also comes with two sample tasks. As explained at the beginning of this chapter, they can be turned off from the extension's configuration options.

The “test” task just sends a mail to a given e-mail address. The “sleep” task goes to sleep for a given number of seconds. They are not very useful in the everyday running of a web site, but they are nice to have when testing stuff. If you want to make sure that your Scheduler installation is complete, register an instance of the “test” task and wait for the mail to arrive (if it doesn't arrive, check in the Log if the task has indeed run).

The “sleep” task is mostly useful for testing parallel executions (by creating an instance of the task that goes to sleep for a longer time than the frequency).

The base tasks are also there to serve as examples for task developers (see “Developer's Guide” below).

Administration

The Scheduler provides a BE module to manage tasks. It provides three screens: a setup check, an information screen and the main (default) one for actually managing the tasks.

The backend module

The setup check screen

This screen has already been mentioned in the “Installation” chapter. It is mostly useful when setting up the Scheduler, as it indicates whether the necessary “_cli_scheduler” BE user exist or not and whether the CLI script is executable or not. When everything is running fine, it contains mostly one useful piece of information: when the last run took place, when it ended and whether is was started manually (i.e. from the BE module) or automatically (i.e. from the command line).

The information screen

This screen shows a list of all available tasks in the current TYPO3 installation. When the Scheduler has just been installed, this will be limited to the two base tasks provided by the extension. The screen shows the name and description of the task. Clicking on the “Add” icon on the right side of each row will open up the new task registration screen, with the task class already predefined.

The scheduled tasks screen

This is the main screen when administering tasks. At first it will be empty and just offer a link to add a new task. When such registered tasks exists, this screen will show a list with various pieces of information.

Disabled tasks appear in grayed-out text. A disabled task is a task that will not be run automatically by the command-line script, but may still be executed from the BE module.

A late task will appear this way:

The table at the center of the above screenshot shows the following:

The first column contains checkboxes. Clicking on a checkbox will select that particular scheduled task for immediate execution. Clicking on the icon at the top of the column will toggle all checkboxes. To execute the selected tasks, click on the “Execute selected tasks” button. Read more in “Manually executing a task” below.

The second column contains possible actions, mainly editing or deleting a task. The actions will be unavailable for a task that is currently running, as it is unwise to edit or delete it a task in such a case. Instead a running task will display a “stop” button (see “Stopping a task” below).

The third column simply displays the id of the task.

The fourth column contains the name of the task, the extension it is coming from and any additional information specific to the task (for example, the e-mail to which the “test” task will send a message or the sleep duration of the “sleep” task). It also show a summary of the task's status, as a bullet. More details below.

The fifth column shows whether the task is recurring or will run only a single time.

The sixth column shows the frequency.

The seventh columns indicates whether parallel executions are allowed or not.

The eighth column shows the last execution time and indicates whether the task was launched manually or was run via the command-line script (cron).

The last column shows the planned execution time. If the task is overdue, the time will show up in bold, red numbers. A task may have no future execution date if it has reached its end date, if it was meant to run a single time and that execution is done, or if the task is disabled. The next execution time is also hidden for running tasks, as this information makes no sense at that point in time.

Note that all dates and times are displayed in the server's time zone. The server time appears at the bottom of the screen.

At the bottom of the screen is a link to add a new task and a legend explaining the various statuses shown in the tasks list. This is pretty much self-explanatory. If there are a lot of tasks that appear late, consider changing the frequency at which the cron job is running (see “Choosing a frequency” above).

Occasionally the following display may appear:

This will typically happen when a task provided by some extension was registered, then the extension was uninstalled, but the task was not deleted beforehand. In such a case, this task stays but the Scheduler doesn't know how to handle it anymore. The solution is either to install the related extension again or delete the registered task.

Adding or editing a task

When adding or editing a task, the following form will show up:

Some fields require additional explanations (inline help is available by moving the mouse over the field labels):

A disabled task will be skipped by the command-line script. It may still be launched manually, as described above.

The class selector is available only when adding a new task. The class cannot be changed when editing a task, since there's no sense in that.

A task must have a start date. The end date is not mandatory, though. A task without end date will run forever. Dates and times must be entered in the server's time zone. The server's time appears at the bottom of the form.

The frequency needs be entered only for recurring tasks. It can be either a number of seconds or a cron-like command. Since TYPO3 4.5 the Scheduler supports the full cron syntax, including ranges, steps and keywords like @weekly. For more information on cron syntax, see http://en.wikipedia.org/wiki/CRON_expression.

Parallel executions are denied by default (see “Tasks execution” above). They must be allowed explicitly.

At the bottom of the form (highlighted area) there may be one or more additional fields. Those fields are specific to each task and will change when a different class is selected.

If there are some input errors, the form will reload upon submission and display the relevant error messages. When the input is finished and correct, the view switches back to the list view and displays a confirmation message.

If an error occurs when validating a cron definition, the Scheduler's built-in cron parser tries to provide an explanation about what's wrong.

Deleting a task

When choosing to delete a task, a pop-up window will appear requesting confirmation. If confirmed, the deletion is final. There's no “deleted” flag in the Scheduler's table, deleted task registrations cannot be recovered.

Stopping a task

As was explained above, a task is marked as being executed while it is running. If the process running the task crashes or is killed for some reason, the task will stay marked as being executed. This will be cleaned up automatically according to the maximum lifetime parameter (also described previously), but this may be inconvenient in some circumstances.

In such cases it is possible to use the “stop” button to clean up marked executions for the given task. This will make it possible to run this task again. However please note that this will not kill the corresponding process should it be still running or hanging.

Manually executing a task

As mentioned above, it is possible to manually execute one or more registered tasks from the BE module. When the selected tasks have finished running, feedback is given about success or failure of each task's run. There's one important thing to note: if the task was overdue, a new execution date will be calculated. If the task was not overdue, the previously calculated next execution date stays.

Developer's Guide

The Scheduler makes it very easy to create a new task class. Furthermore the two examples tasks that are packaged with the extension provide a good basis to learn by example.

Creating a new task

Creating the task class

This is the heart of a task. It is the code that actually does what the task is supposed to do. A task is represented by a PHP class that extends the base task class:

class tx_myext_mytask extends tx_scheduler_Task {
public function execute() {
...
}
}

The only method that must be implemented is the execute() method which is expected to perform the task logic. The method must return a boolean value of “true” if the execution was successful, and “false” otherwise. It may also throw exceptions to report more precisely on errors that may happen during the run. The message of the exception is stored in the database so that it can be displayed in the BE module.

A method called getAdditionalInformation() may optionally be implemented too. It is called by the BE module to display additional information about a registered task in the list view. This is quite convenient if a task class may be registered several times with different parameters, in order to tell apart the various registrations.

If the task class uses a constructor it is absolutely necessary to include a call to the parent's constructor, most probably as the first thing inside the constructor, unless there are some very special reasons not to:

class tx_myext_mytask extends tx_scheduler_Task {
public function __construct() {
parent::__construct();

// Your code here...
}
}

Using additional fields

A task class may require additional parameters to be executed properly. For example, the “test” task is designed to send an e-mail, but the e-mail address must be defined at the time when the task class is actually registered. This appears as an additional field in the task registration form. The Scheduler provides an interface which may be implemented to provide such fields. It is comprised of three methods, which must all be implemented (since it's an interface).

The implementation may be done in a separate class or in the same class as the task. It may look something like:

class tx_myext_mytask_AdditionalFieldProvider implements tx_scheduler_AdditionalFieldProvider {
public function getAdditionalFields(array &$taskInfo, $task, tx_scheduler_Module $parentObject) {
...
}
public function validateAdditionalFields(array &$submittedData, tx_scheduler_Module $parentObject) {
...
}
public function saveAdditionalFields(array $submittedData, tx_scheduler_Task $task) {
...
}
}

The three methods of the interface are described below:

Method:	Purpose:	Parameters:
getAdditionalFields	This method returns the list of fields to display in the editing form. This list of fields is a 2-dimensional array. The first dimension uses the ID of the field (as used in the “id” attribute of the field tag). Then for each field, there must be the HTML code to render the field, the label of the field, the key and the label for the context-sensitive help (CSH). All this is documented in the tx_scheduler_AdditionalFieldProvider interface and can be seen in action in the example task classes.	$taskInfo: an array containing the information about the current task. May be modified inside this method to set default values, for example. $task: the current task object (when editing; when adding, “null” is passed to the method). $parentObject: a back-reference to the calling BE module's object.
validateAdditionalFields	This method is called to validate the values that were input in the additional fields provided by the specific task. It is expected to return false if any of the fields contained errors, true otherwise. The method should use the parent object's addMessage() method to output messages about validation errors.	$submittedData: array of values from the submitted form. May be modified inside the method. $parentObject: a back-reference to the calling BE module's object.
saveAdditionalFields	This method is used to store the values contained in the additional fields. The simplest method is to simply assign them to member variables, so that they will be stored along the serialized task object in the database (see “Appendix A – Technical Background”).	$submittedData: array of values from the submitted form, after validation. $task: the current task object.

Security issues

The handling of additional fields is entirely up to the developer, in particular as far as validation and display is concerned. Thus it is up to you to make sure that the data entered in your additional fields does not contain any harmful input (for example, XSS).

The safest way to proceed is to very strictly handle input. For example, if all you expect is some integer number, pass the value through a call to intval(). If it's a string, but you don't expect any markup in it, run it through strip_tags(). Such simple measures can filter most of the harmful code.

One more thing to mind. In the getAdditionalFields() method, the whole form element must be assembled. If the input didn't validate, you may well want to insert it in the field again, so that the user can correct it. Harmful code entered at that point may be executed. It is thus very strongly recommended to use htmlspecialchars() in this case. Example:

$fieldCode = '<input type="text" name="tx_scheduler[email]" id="' . $fieldID . '" value="' . htmlspecialchars($taskInfo['email']) . '" size="30" />';

Naming of additional fields

The Scheduler expects all fields in the add/edit form to be named tx_scheduler[...]. Values from fields that don't follow this pattern will not appear in the $submittedData array.

It is also important to think about using field names that will not create conflicts with other existing fields or future fields that may happen. Since there is no name-spacing mechanism available, it is up to each developer to choose proper names. A very good practice is to prepend the extension's key to the additional fields names in order to guarantee the unicity of those names.

Bad examples

Here are some examples of bad additional fields names:

foo

tx_scheduler[name]

The first name doesn't use the syntax and thus will not be handled by the Scheduler. The second one respects that syntax, but the name is too generic and may cause conflicts with other fields.

Good examples

Here are good examples of additional fields names:

tx_scheduler[myextension_myvalue]

tx_scheduler[myextension][myvalue]

In both cases the proper syntax is used as well as the extension key, making it very unlikely that a naming conflict could happen.

Autoloading

The Scheduler expects all task classes and all additional fields provider classes to be available with the TYPO3 autoloader. They thus must be declared in the ext_autoload.php file of the extension that provides these classes. Again the ext_autoload.php file of the Scheduler can be used as an example. Here's an extract:

$extensionPath = t3lib_extMgm::extPath('scheduler');

return array(

...

'tx_scheduler_testtask' => $extensionPath . 'examples/class.tx_scheduler_testtask.php',

'tx_scheduler_testtask_additionalfieldprovider' => $extensionPath . 'examples/class.tx_scheduler_testtask_additionalfieldprovider.php',

...

);

Note that the keys to this array are the class names all in lower case.

Declaring the task class

As a last step, the task class must be declared so the Scheduler knows of its existence. The declaration must be placed in the ext_localconf.php file of the extension that provides the task. Let's look at the test class declaration as an example:

$GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['scheduler']['tasks']['tx_scheduler_TestTask'] = array(
'extension' => $_EXTKEY,
'title' => 'LLL:EXT:' . $_EXTKEY . '/locallang.xml:testTask.name',
'description' => 'LLL:EXT:' . $_EXTKEY . '/locallang.xml:testTask.description',
'additionalFields' => 'tx_scheduler_TestTask_AdditionalFieldProvider'
);

The registration is made in the array $GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['scheduler']['tasks']. A key is then used that corresponds to the task class (in bold above). Then come 4 parameters:

extension: the key of the extension that provides the class. This is used for informational purposes.

title: the name of the task. May use localized labels.

description: a text describing the task. It is displayed in the information screen of the BE module. May use localized labels.

additionalFields: the name of the class that provides the additional fields. Leave empty if task class does not require any such fields.

Working with serialized objects

When a task is registered with the Scheduler the corresponding object instance is serialized and stored in the database (see Appendix A for more details). This is not a very common practice. There are advantages but also some pitfalls, so please read this section carefully.

A serialized object may happen to be “out of sync” with its class if the class changes some of its variables or methods. If a variable's name is changed or if variables are added or removed, the serialized object will not reflect these changes. The same goes if a method is renamed, added or deleted. Problems will also arise if the number or order of arguments used to call a method are changed. In such cases weird errors may appear, which can be very difficult to track. The only solution is to delete the registered task and register it anew.

To minimize such risks it is worth to consider implementing the business logic in a separate class, so that the task class itself changes as little as possible. The execute() should be as simple as possible. Consider the following:

class tx_myext_mytask extends tx_scheduler_Task {
public function execute() {
$businessLogic = t3lib_div::makeInstance('tx_myext_BusinessLogic');

$businessLogic->run(arg1, arg2, …);
}
}

In such a setup the execute() is kept to the strict minimum and the operations themselves are handled by a separate class.

Also remember that the constructor is not called when unserializing an object. If some operations need to be run upon unserialization, implement a __wakeup() method instead.

Scheduler API

It is possible to refer to the Scheduler from other extensions. Once a tx_scheduler object has been instantiated all of its public methods can be used. The PHPdoc of the methods should be enough to understand what each is to be used for. It would be excessive to describe them all here.

However a few deserve a special mention:

fetchTask(): this method is used to fetch a registered task from the database given an id. If no id is given, it will return the next due task. The return value is the unserialized task object.

fetchTaskRecord(): is also used to retrieve a registered task from the database, but it returns the record corresponding to the task registration and not the task object itself. It is not designed fetch the next due task.

fetchTasksWithCondition(): can be used to retrieve one or more registered tasks, that fit a given SQL condition. It returns an array containing all the records of the matching tasks registrations.

These are the main methods that will be used from outside the Scheduler as they can retrieve registered tasks from the database. When a task has been fetched, all public methods from the tx_scheduler_Task class can be used.

Known problems

The main problem currently is that a running task cannot be killed, because no relation exists to the (cron) process that is running the Scheduler. The process pid could be retrieved, but that may not work on all platforms. And can the process be killed afterwards? Anyway it may not be safe to do that.

Problems should be reported to the TYPO3 bug tracker (http://bugs.typo3.org/) in the “TYPO3 Core” project and “tx_scheduler” sub-project.

To-Do list

Here are a few ideas for possible evolutions:

check the possibility to use t3lib_syslock instead of serialized executions to mark running tasks;

use TCEform to render the edit form, instead of custom code;

provide a way to register tasks automatically when an extension providing a task class is installed;

deliver the Scheduler with some useful tasks, possibly some of the cron scripts from the TYPO3 Core.

Feature ideas or wishes can be entered into the TYPO3 bug tracker (http://bugs.typo3.org/) in the “TYPO3 Core” project and “tx_scheduler” sub-project.

ChangeLog

Version	Changes:
1.1.0	Support for the full cron syntax Several bug fixes
1.0.1-1.0.2	Minor bug fixes Updated screenshots for TYPO3 4.4
1.0.0	Integration into the TYPO3 Core

Appendix A – Technical Background

This section aims to give some more in-depth information about what happens behind the scene in the Scheduler.

When a task is registered with the Scheduler, an instance of the task class is created and stored in a database record as a serialized object. The database record itself contains additional information about the registration, mostly about past and future executions. The theory is that all the information that is really proper to the task should be defined as member variables of the task class and is thus encapsulated inside the task object. The information which relates to executing a registered task is stored in the Scheduler's database table.

That being said, a task also contains information about its execution. Indeed each task class has an instance of tx_scheduler_Execution as a member variable, which contains information such as start and end date and is used to calculate the next execution date.

When a task is running, its start time is stored into an array, which is serialized and stored in the corresponding database record. If several executions are running at the same time, the array will contain several timestamps. Thus the “serialized_executions” field actually contains an array of integers and not serialized instances of tx_scheduler_Execution objects.

Appendix B – Migrating from Gabriel

Events

Transforming a Gabriel event into a Scheduler task is not very difficult. First off the class must inherit from tx_scheduler_Task instead of tx_gabriel_event. The main method to implement is still execute(). The main difference is that it is expected to return a boolean value instead of nothing. It should return true if it successfully executed, false otherwise. Additionally it becomes possible to throw exceptions from within the execute() method. The exception is caught during execution and stored in the “lastexecution_failure” field of the database table. This makes it possible to give some feedback in the BE module about why a task failed.

The concept of CRID was dropped entirely. The database now stores simply the task class name. The CRID could also be used to pass additional parameters to a task, so that it could be registered several times with different “options”. This is not possible anymore and has been replaced by the additional fields, which are much cleaner, since they can be validated upon input.

Another small difference is that each task now contains a single execution object. With Gabriel it held an array of executions. With the Scheduler each execution of a given task class correspond to a separate database record, which is not only cleaner but also far easier to manage.

Database records

There's no way existing records from table “tx_gabriel” may be moved to table “tx_scheduler_task”. The tables are quite different. Furthermore the serialized Gabriel event object will not fit a Scheduler task object. So once the Gabriel event class has been transformed into a Scheduler task class, there's no choice but to register all tasks again.

EXT: Scheduler - scheduler	Appendix B – Migrating from Gabriel

20

EXT: Scheduler

scheduler

forAdmins forIntermediates

Kasper Skårhøj

2002-11-01T00:32:00

Francois Suter

Kasper Skårhøj