first commit
This commit is contained in:
salam committed
commit
1218dd1517
12716 files changed
+989233
No files matched your search
@@ -0,0 +1,7 @@
|
||||
# this is file .gitignore
|
||||
|
||||
# ignore everything in this directory
|
||||
_make/*
|
||||
|
||||
# but do not ignore this file
|
||||
!_not_versioned/.gitignore
|
||||
@@ -0,0 +1,147 @@
|
||||
.. ==================================================
|
||||
.. FOR YOUR INFORMATION
|
||||
.. --------------------------------------------------
|
||||
.. -*- coding: utf-8 -*- with BOM.
|
||||
|
||||
.. include:: ../../Includes.txt
|
||||
|
||||
|
||||
.. _backend-module:
|
||||
|
||||
The backend module
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
|
||||
|
||||
.. _setup-check-screen:
|
||||
|
||||
The setup check screen
|
||||
""""""""""""""""""""""
|
||||
|
||||
This screen has already been mentioned in the :ref:`Installation chapter <setup-check>`.
|
||||
It is mostly useful when setting up the Scheduler, as it indicates
|
||||
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 it was started
|
||||
manually (i.e. from the BE module) or automatically (i.e. from the
|
||||
command line).
|
||||
|
||||
|
||||
.. _information-screen:
|
||||
|
||||
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.
|
||||
|
||||
.. figure:: ../../Images/InformationScreen.png
|
||||
:alt: Scheduler information screen
|
||||
|
||||
List of available tasks in the Scheduler's information screen
|
||||
|
||||
|
||||
.. _scheduled-tasks-screen:
|
||||
|
||||
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.
|
||||
|
||||
|
||||
.. figure:: ../../Images/BackendModuleMainView.png
|
||||
:alt: Scheduler main screen
|
||||
|
||||
Main screen of the Scheduler BE module
|
||||
|
||||
|
||||
Disabled tasks have a gray label sign near the task name. 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 with an orange label sign near the task name:
|
||||
|
||||
.. figure:: ../../Images/LateTask.png
|
||||
:alt: A late task in the Scheduler main screen
|
||||
|
||||
A late task in the main screen of the Scheduler BE module
|
||||
|
||||
|
||||
The task list can be sorted by clicking the column label. With every click it
|
||||
switches between ascending and descending order of the items of the associated column.
|
||||
|
||||
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 simply displays the id of the task.
|
||||
|
||||
- The third 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 with an icon.
|
||||
|
||||
- The fourth column shows whether the task is recurring or will run only
|
||||
a single time.
|
||||
|
||||
- The fifth column shows the frequency.
|
||||
|
||||
- The sixth columns indicates whether parallel executions are allowed
|
||||
or not.
|
||||
|
||||
- The seventh column shows the last execution time and indicates whether
|
||||
the task was launched manually or was run via the command-line script
|
||||
(cron).
|
||||
|
||||
- The eighth 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.
|
||||
|
||||
- The last column contains possible actions, mainly editing, disable or
|
||||
deleting a task. There are also buttons for running the task on the
|
||||
next cron job or run it directly.
|
||||
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).
|
||||
|
||||
|
||||
|
||||
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 top of the screen is a link to add a new task.
|
||||
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:
|
||||
|
||||
.. figure:: ../../Images/MissingTaskClass.png
|
||||
:alt: A broken task
|
||||
|
||||
A scheduled task missing its corresponding class
|
||||
|
||||
|
||||
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.
|
||||
|
||||
@@ -0,0 +1,19 @@
|
||||
.. ==================================================
|
||||
.. FOR YOUR INFORMATION
|
||||
.. --------------------------------------------------
|
||||
.. -*- coding: utf-8 -*- with BOM.
|
||||
|
||||
.. include:: ../../Includes.txt
|
||||
|
||||
|
||||
|
||||
.. _deleting-a-task:
|
||||
|
||||
Deleting a task
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
When choosing to delete a task, a pop-up window will appear requesting
|
||||
confirmation. If confirmed, the deletion is final. There is no
|
||||
"deleted" flag in the Scheduler's table, deleted task registrations
|
||||
cannot be recovered.
|
||||
|
||||
@@ -0,0 +1,75 @@
|
||||
.. ==================================================
|
||||
.. FOR YOUR INFORMATION
|
||||
.. --------------------------------------------------
|
||||
.. -*- coding: utf-8 -*- with BOM.
|
||||
|
||||
.. include:: ../../Includes.txt
|
||||
|
||||
|
||||
.. _adding-editing-task:
|
||||
|
||||
Adding or editing a task
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
When adding or editing a task, the following form will show up:
|
||||
|
||||
.. figure:: ../../Images/AddingATask.png
|
||||
:alt: Add task form
|
||||
|
||||
Adding a new scheduled task
|
||||
|
||||
|
||||
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.
|
||||
|
||||
.. figure:: ../../Images/TaskConfigurationSelectClass.png
|
||||
:alt: Select a class
|
||||
|
||||
Select the class of the scheduled task
|
||||
|
||||
|
||||
- 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 :code:`@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.
|
||||
|
||||
.. figure:: ../../Images/InputValidation.png
|
||||
:alt: Input validation
|
||||
|
||||
Input validation failed when adding a new scheduled task or editing an existing one
|
||||
|
||||
|
||||
.. figure:: ../../Images/InputValidationOk.png
|
||||
:alt: Input validation OK
|
||||
|
||||
Input validation succeeded when adding a new scheduled task or editing an existing one
|
||||
|
||||
|
||||
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.
|
||||
|
||||
@@ -0,0 +1,18 @@
|
||||
.. ==================================================
|
||||
.. FOR YOUR INFORMATION
|
||||
.. --------------------------------------------------
|
||||
.. -*- coding: utf-8 -*- with BOM.
|
||||
|
||||
.. include:: ../../Includes.txt
|
||||
|
||||
|
||||
|
||||
.. _executing-a-task-on-next-cronjob:
|
||||
|
||||
Executing a task on next cron job
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
It is possible to manually set the next execution time of one or more
|
||||
registered tasks from the BE module to the current time.
|
||||
The selected tasks will then be running on the next cron job.
|
||||
|
||||
@@ -0,0 +1,41 @@
|
||||
.. ==================================================
|
||||
.. FOR YOUR INFORMATION
|
||||
.. --------------------------------------------------
|
||||
.. -*- coding: utf-8 -*- with BOM.
|
||||
|
||||
.. include:: ../../Includes.txt
|
||||
|
||||
|
||||
|
||||
.. _grouping-tasks:
|
||||
|
||||
Grouping tasks together
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
In case of a high number of different tasks, it may be useful to visually group similar tasks together:
|
||||
|
||||
.. figure:: ../../Images/GroupedTasks.png
|
||||
:alt: Overview of tasks with grouped
|
||||
|
||||
Grouping related tasks together
|
||||
|
||||
|
||||
Scheduler task groups are records stored on the root page (pid=0). They may be created, edited and sorted with Web > List:
|
||||
|
||||
.. figure:: ../../Images/GroupRecords.png
|
||||
:alt: Task group records
|
||||
|
||||
Management of scheduler task groups
|
||||
|
||||
|
||||
It is also possible to create a new task group from within the edit task form whith clicking on the `+` icon next to the
|
||||
task group select box.
|
||||
|
||||
Individual tasks may then be edited as usual and associated to a given scheduler task group.
|
||||
|
||||
The individual groups can be sorted independent of each other by clicking the column label.
|
||||
With every click it switches between ascending and descending order of the items of the associated column
|
||||
in the corresponding group.
|
||||
|
||||
.. note::
|
||||
Tasks inside a hidden group are neither automatically executed nor displayed in the scheduler module.
|
||||
@@ -0,0 +1,33 @@
|
||||
.. ==================================================
|
||||
.. FOR YOUR INFORMATION
|
||||
.. --------------------------------------------------
|
||||
.. -*- coding: utf-8 -*- with BOM.
|
||||
|
||||
.. include:: ../Includes.txt
|
||||
|
||||
|
||||
|
||||
.. _administration:
|
||||
|
||||
======================
|
||||
Backend 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.
|
||||
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 5
|
||||
:titlesonly:
|
||||
:glob:
|
||||
|
||||
BackendModule/Index
|
||||
EditTask/Index
|
||||
DeleteTask/Index
|
||||
GroupTask/Index
|
||||
StopTask/Index
|
||||
ManualExecution/Index
|
||||
ExecuteNextCronjob/Index
|
||||
|
||||
@@ -0,0 +1,29 @@
|
||||
.. ==================================================
|
||||
.. FOR YOUR INFORMATION
|
||||
.. --------------------------------------------------
|
||||
.. -*- coding: utf-8 -*- with BOM.
|
||||
|
||||
.. include:: ../../Includes.txt
|
||||
|
||||
|
||||
|
||||
.. _manually-executing-a-task:
|
||||
|
||||
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.
|
||||
|
||||
A single task can be started by pressing the appropriate button in
|
||||
the row of the task. Multiple tasks can be started by selecting the
|
||||
checkboxes on the left side of the task row and then pressing the
|
||||
appropriate button beneath the task list.
|
||||
|
||||
There is one button for directly starting the task and another button
|
||||
for starting the task with the next cron job.
|
||||
|
||||
@@ -0,0 +1,32 @@
|
||||
.. ==================================================
|
||||
.. FOR YOUR INFORMATION
|
||||
.. --------------------------------------------------
|
||||
.. -*- coding: utf-8 -*- with BOM.
|
||||
|
||||
.. include:: ../../Includes.txt
|
||||
|
||||
|
||||
.. _stopping-a-task:
|
||||
|
||||
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.
|
||||
|
||||
.. figure:: ../../Images/StoppingATask.png
|
||||
:alt: Stopping a task
|
||||
|
||||
Stopping a running task from the main screen
|
||||
|
||||
|
||||
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 a corresponding still running or continuously hanging
|
||||
process.
|
||||
|
||||
@@ -0,0 +1,41 @@
|
||||
.. ==================================================
|
||||
.. FOR YOUR INFORMATION
|
||||
.. --------------------------------------------------
|
||||
.. -*- coding: utf-8 -*- with BOM.
|
||||
|
||||
.. include:: ../Includes.txt
|
||||
|
||||
|
||||
|
||||
.. _technical-background:
|
||||
|
||||
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
|
||||
:code:`TYPO3\CMS\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
|
||||
:code:`TYPO3\CMS\Scheduler\Execution` objects.
|
||||
|
||||
|
||||
@@ -0,0 +1,352 @@
|
||||
.. ==================================================
|
||||
.. FOR YOUR INFORMATION
|
||||
.. --------------------------------------------------
|
||||
.. -*- coding: utf-8 -*- with BOM.
|
||||
|
||||
.. include:: ../../Includes.txt
|
||||
|
||||
|
||||
|
||||
.. _creating-tasks:
|
||||
|
||||
Creating a new task
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
|
||||
.. _creating-task-class:
|
||||
|
||||
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:
|
||||
|
||||
::
|
||||
|
||||
namespace Vendor\Extension\Task;
|
||||
class MyTask extends \TYPO3\CMS\Scheduler\Task\AbstractTask {
|
||||
public function execute() {
|
||||
...
|
||||
}
|
||||
}
|
||||
|
||||
The only method that **must** be implemented is the :code:`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 :code:`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:
|
||||
|
||||
::
|
||||
|
||||
namespace Vendor\Extension\Task;
|
||||
class MyTask extends \TYPO3\CMS\Scheduler\Task\AbstractTask {
|
||||
public function __construct() {
|
||||
parent::__construct();
|
||||
// Your code here...
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
.. _using-additional-fields:
|
||||
|
||||
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:
|
||||
|
||||
::
|
||||
|
||||
namespace Vendor\Extension\Task;
|
||||
class MyTaskAdditionalFieldProvider implements \TYPO3\CMS\Scheduler\AdditionalFieldProviderInterface {
|
||||
public function getAdditionalFields(array &$taskInfo, $task, \TYPO3\CMS\Scheduler\Controller\SchedulerModuleController $parentObject) {
|
||||
...
|
||||
}
|
||||
public function validateAdditionalFields(array &$submittedData, \TYPO3\CMS\Scheduler\Controller\SchedulerModuleController $parentObject) {
|
||||
...
|
||||
}
|
||||
public function saveAdditionalFields(array $submittedData, \TYPO3\CMS\Scheduler\Task\AbstractTask $task) {
|
||||
...
|
||||
}
|
||||
}
|
||||
|
||||
The three methods of the interface are described below:
|
||||
|
||||
|
||||
.. _getadditionalfields:
|
||||
|
||||
getAdditionalFields
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. container:: table-row
|
||||
|
||||
Method
|
||||
getAdditionalFields
|
||||
|
||||
Purpose
|
||||
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
|
||||
:code:`\TYPO3\CMS\Scheduler\AdditionalFieldProviderInterface` interface and can be
|
||||
seen in action in the existing task classes.
|
||||
|
||||
Parameters
|
||||
:code:`$taskInfo` : an array containing the information about the
|
||||
current task. May be modified inside this method to set default
|
||||
values, for example.
|
||||
|
||||
:code:`$task` : the current task object (when editing; when adding,
|
||||
"null" is passed to the method).
|
||||
|
||||
:code:`$parentObject` : a back-reference to the calling BE module's
|
||||
object.
|
||||
|
||||
|
||||
|
||||
.. _validateadditionalfields:
|
||||
|
||||
validateAdditionalFields
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. container:: table-row
|
||||
|
||||
Method
|
||||
validateAdditionalFields
|
||||
|
||||
Purpose
|
||||
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 :code:`addMessage()` method
|
||||
to output messages about validation errors.
|
||||
|
||||
Parameters
|
||||
:code:`$submittedData` : array of values from the submitted form. May
|
||||
be modified inside the method.
|
||||
|
||||
:code:`$parentObject` : a back-reference to the calling BE module's
|
||||
object.
|
||||
|
||||
|
||||
|
||||
.. _saveadditionalfields:
|
||||
|
||||
saveAdditionalFields
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. container:: table-row
|
||||
|
||||
Method
|
||||
saveAdditionalFields
|
||||
|
||||
Purpose
|
||||
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 :ref:`technical-background`).
|
||||
|
||||
Parameters
|
||||
:code:`$submittedData` : array of values from the submitted form,
|
||||
after validation.
|
||||
|
||||
:code:`$task` : the current task object.
|
||||
|
||||
|
||||
|
||||
.. _security-issues:
|
||||
|
||||
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 typecast to (int). If it's a string, but you don't
|
||||
expect any markup in it, run it through :code:`strip\_tags()` . Such
|
||||
simple measures can filter most of the harmful code.
|
||||
|
||||
One more thing to mind. In the :code:`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
|
||||
:code:`htmlspecialchars()` in this case. Example:
|
||||
|
||||
::
|
||||
|
||||
$fieldCode = '<input type="text" class="form-control" name="tx_scheduler[email]" id="' . $fieldID . '" value="' . htmlspecialchars($taskInfo['email']) . '" size="30">';
|
||||
|
||||
|
||||
.. _naming-of-additional-fields:
|
||||
|
||||
Naming of additional fields
|
||||
"""""""""""""""""""""""""""
|
||||
|
||||
The Scheduler expects all fields in the add/edit form to be named
|
||||
:code:`tx\_scheduler[...]` . Values from fields that don't follow this
|
||||
pattern will **not** appear in the :code:`$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:
|
||||
|
||||
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:
|
||||
|
||||
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.
|
||||
|
||||
|
||||
.. _declare-task-class:
|
||||
|
||||
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
|
||||
:code:`ext_localconf.php` file of the extension that provides the
|
||||
task. Let's look at one of the base classes declaration as an example:
|
||||
|
||||
::
|
||||
|
||||
// Add caching framework garbage collection task
|
||||
$GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['scheduler']['tasks'][\TYPO3\CMS\Scheduler\Task\CachingFrameworkGarbageCollectionTask::class] = array(
|
||||
'extension' => $_EXTKEY,
|
||||
'title' => 'LLL:EXT:' . $_EXTKEY . '/locallang.xlf:cachingFrameworkGarbageCollection.name',
|
||||
'description' => 'LLL:EXT:' . $_EXTKEY . '/locallang.xlf:cachingFrameworkGarbageCollection.description',
|
||||
'additionalFields' => \TYPO3\CMS\Scheduler\Task\CachingFrameworkGarbageCollectionAdditionalFieldProvider::class
|
||||
);
|
||||
|
||||
The registration is made in the array
|
||||
:code:`$GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['scheduler']['tasks']`.
|
||||
The key used corresponds to the task class. 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.
|
||||
|
||||
|
||||
.. _serialized-objects:
|
||||
|
||||
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 :code:`execute()` should be as
|
||||
simple as possible. Consider the following:
|
||||
|
||||
::
|
||||
|
||||
class MyTask extends \TYPO3\CMS\Scheduler\Task\AbstractTask {
|
||||
public function execute() {
|
||||
$businessLogic = \TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance(\Vendor\Extension\BusinessLogic::class);
|
||||
$businessLogic->run(arg1, arg2, …);
|
||||
}
|
||||
}
|
||||
|
||||
In such a setup the :code:`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 :code:`__wakeup()` method instead.
|
||||
|
||||
|
||||
.. _save-task-state:
|
||||
|
||||
Saving a task's state
|
||||
"""""""""""""""""""""
|
||||
|
||||
The task's state is saved automatically at the **start** of its
|
||||
execution. If you need to save a task's state at some point **during**
|
||||
its execution, you can simply call the task's own :code:`save()`
|
||||
method.
|
||||
|
||||
@@ -0,0 +1,27 @@
|
||||
.. ==================================================
|
||||
.. FOR YOUR INFORMATION
|
||||
.. --------------------------------------------------
|
||||
.. -*- coding: utf-8 -*- with BOM.
|
||||
|
||||
.. include:: ../Includes.txt
|
||||
|
||||
|
||||
|
||||
.. _developer-guide:
|
||||
|
||||
Developer's Guide
|
||||
-----------------
|
||||
|
||||
The Scheduler makes it very easy to create a new task class.
|
||||
Furthermore the tasks packaged with this extension provide
|
||||
a good basis to learn by example.
|
||||
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 5
|
||||
:titlesonly:
|
||||
:glob:
|
||||
|
||||
CreatingTasks/Index
|
||||
SchedulerApi/Index
|
||||
|
||||
@@ -0,0 +1,40 @@
|
||||
.. ==================================================
|
||||
.. FOR YOUR INFORMATION
|
||||
.. --------------------------------------------------
|
||||
.. -*- coding: utf-8 -*- with BOM.
|
||||
|
||||
.. include:: ../../Includes.txt
|
||||
|
||||
|
||||
|
||||
.. _scheduler-api:
|
||||
|
||||
Scheduler API
|
||||
^^^^^^^^^^^^^
|
||||
|
||||
It is possible to refer to the Scheduler from other extensions. Once a
|
||||
:code:`\TYPO3\CMS\Scheduler\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:
|
||||
|
||||
- :code:`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.
|
||||
|
||||
- :code:`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.
|
||||
|
||||
- :code:`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
|
||||
:code:`\TYPO3\CMS\Scheduler\Task\AbstractTask` class can be used.
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 65 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 103 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 14 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 22 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 90 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 125 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 40 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 37 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 35 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 21 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 70 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 36 KiB |
BIN
Binary file not shown.
|
After Width: | Height: | Size: 21 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 69 KiB |
@@ -0,0 +1,21 @@
|
||||
.. ==================================================
|
||||
.. FOR YOUR INFORMATION
|
||||
.. --------------------------------------------------
|
||||
.. -*- coding: utf-8 -*- with BOM.
|
||||
|
||||
.. This is 'Includes.txt'. It is included at the very top of each and
|
||||
every ReST source file in this documentation project (= manual).
|
||||
|
||||
|
||||
.. ==================================================
|
||||
.. DEFINE SOME TEXTROLES
|
||||
.. --------------------------------------------------
|
||||
|
||||
.. role:: typoscript(code)
|
||||
|
||||
.. role:: ts(typoscript)
|
||||
:class: typoscript
|
||||
|
||||
.. role:: php(code)
|
||||
|
||||
.. highlight:: php
|
||||
@@ -0,0 +1,67 @@
|
||||
.. ==================================================
|
||||
.. FOR YOUR INFORMATION
|
||||
.. --------------------------------------------------
|
||||
.. -*- coding: utf-8 -*- with BOM.
|
||||
|
||||
.. include:: Includes.txt
|
||||
|
||||
|
||||
.. _start:
|
||||
|
||||
=========
|
||||
Scheduler
|
||||
=========
|
||||
|
||||
:Extension key:
|
||||
scheduler
|
||||
|
||||
:Version:
|
||||
|release|
|
||||
|
||||
:Language:
|
||||
en
|
||||
|
||||
:Description:
|
||||
Management of scheduled tasks inside the TYPO3 Backend.
|
||||
|
||||
:Keywords:
|
||||
TYPO3 scheduler
|
||||
|
||||
:Copyright:
|
||||
2000-2021
|
||||
|
||||
:Author:
|
||||
TYPO3 CMS Core Development Team
|
||||
|
||||
:License:
|
||||
Open Content License available from `www.opencontent.org/opl.shtml
|
||||
<http://www.opencontent.org/opl.shtml>`_
|
||||
|
||||
:Rendered:
|
||||
|today|
|
||||
|
||||
The content of this document is related to TYPO3,
|
||||
|
||||
a GNU/GPL CMS/Framework available from `www.typo3.org
|
||||
<http://www.typo3.org/>`_
|
||||
|
||||
|
||||
|
||||
|
||||
**Table of Contents**
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 5
|
||||
:titlesonly:
|
||||
:glob:
|
||||
|
||||
Introduction/Index
|
||||
Overview/Index
|
||||
Installation/Index
|
||||
Administration/Index
|
||||
Installation/SchedulerShellScript/Index
|
||||
DevelopersGuide/Index
|
||||
KnownProblems/Index
|
||||
AppendixA/Index
|
||||
Targets
|
||||
|
||||
@@ -0,0 +1,114 @@
|
||||
.. ==================================================
|
||||
.. FOR YOUR INFORMATION
|
||||
.. --------------------------------------------------
|
||||
.. -*- coding: utf-8 -*- with BOM.
|
||||
|
||||
.. include:: ../../Includes.txt
|
||||
|
||||
|
||||
.. _base-tasks:
|
||||
|
||||
The base tasks
|
||||
^^^^^^^^^^^^^^
|
||||
|
||||
The Scheduler comes by default with several tasks:
|
||||
|
||||
- **Caching framework garbage collection** : some cache backends do not
|
||||
have an automatic garbage collection process. For these it is useful
|
||||
to run this Scheduler task to regularly free some space.
|
||||
|
||||
- **Fileadmin garbage collection** : empties :file:`_recycler_` folders in
|
||||
the fileadmin.
|
||||
|
||||
- **Table garbage collection** : cleans up old records from any table in
|
||||
the database. See related section below for more information on
|
||||
configuration.
|
||||
|
||||
|
||||
.. _table-garbage-collection-task:
|
||||
|
||||
Table garbage collection task
|
||||
"""""""""""""""""""""""""""""
|
||||
|
||||
The table garbage collection task can take a more elaborate
|
||||
configuration which is detailed below.
|
||||
|
||||
The task can be registered to clean up a particular table, in which
|
||||
case you simply choose the table and the minimum age of the records to
|
||||
delete from the task configuration screen.
|
||||
|
||||
.. figure:: ../../Images/TableGarbageCollectionTaskConfiguration.png
|
||||
:alt: Table Garbage Collection task configuration
|
||||
|
||||
Configuring the table garbage collection task
|
||||
|
||||
|
||||
It's also possible to clean up all configured table by
|
||||
checking the "Clean all available tables" box. The configuration for
|
||||
the tables to clean up is stored in
|
||||
:php:`$GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['scheduler']['tasks'][\TYPO3\CMS\Scheduler\Task\TableGarbageCollectionTask::class]['options']['tables']`.
|
||||
The syntax is the following:
|
||||
|
||||
- option :php:`expireField` can be used to point to a table field
|
||||
containing an expiry timestamp. This timestamp will then be used to
|
||||
decide whether a record has expired or not. If its timestamp is in the
|
||||
past, the record will be deleted.
|
||||
|
||||
- if a table has no expiry field, one can use a combination of a date
|
||||
field and an expiry period to decide which records should be deleted.
|
||||
The corresponding options are :php:`dateField` and :php:`expirePeriod`.
|
||||
The expiry period is expressed in days.
|
||||
|
||||
|
||||
.. _table-garbage-collection-task-example:
|
||||
|
||||
Example
|
||||
~~~~~~~
|
||||
|
||||
::
|
||||
|
||||
$GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['scheduler']['tasks'][\TYPO3\CMS\Scheduler\Task\TableGarbageCollectionTask::class]['options']['tables'] = array(
|
||||
'tx_realurl_errorlog' => array(
|
||||
'dateField' => 'tstamp',
|
||||
'expirePeriod' => '180'
|
||||
),
|
||||
'tx_realurl_uniqalias' => array(
|
||||
'expireField' => 'expire'
|
||||
)
|
||||
);
|
||||
|
||||
The first part of the configuration indicates that records older than
|
||||
180 days should be removed from table :code:`tx_realurl_errorlog` ,
|
||||
based on the timestamp field called "tstamp". The second part
|
||||
indicates that old records should be removed from table
|
||||
:code:`tx_realurl_uniqalias` directly based on the field "expire"
|
||||
which contains expiration dates for each record.
|
||||
|
||||
|
||||
.. _other-tasks:
|
||||
|
||||
Other tasks
|
||||
"""""""""""
|
||||
|
||||
More tasks are provided by system extensions, such as 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).
|
||||
|
||||
@@ -0,0 +1,112 @@
|
||||
.. ==================================================
|
||||
.. FOR YOUR INFORMATION
|
||||
.. --------------------------------------------------
|
||||
.. -*- coding: utf-8 -*- with BOM.
|
||||
|
||||
.. include:: ../../Includes.txt
|
||||
|
||||
|
||||
|
||||
.. _cron-job:
|
||||
|
||||
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.
|
||||
|
||||
|
||||
.. _frequency:
|
||||
|
||||
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.
|
||||
|
||||
|
||||
.. _unix-mac:
|
||||
|
||||
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/user/www/typo3/sysext/core/bin/typo3 scheduler:run
|
||||
|
||||
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.
|
||||
|
||||
.. seealso::
|
||||
|
||||
See :ref:`scheduler-shell-script` for more information about
|
||||
calling the scheduler from the command line.
|
||||
|
||||
If you are editing system crontabs (for example :code:`/etc/crontab`
|
||||
and :code:`/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/user/www/typo3/sysext/core/bin/typo3 scheduler:run
|
||||
|
||||
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).
|
||||
|
||||
|
||||
.. _windows:
|
||||
|
||||
On Windows
|
||||
""""""""""
|
||||
|
||||
On Windows, cron jobs are called "Scheduled tasks" and run with the
|
||||
:code:`schtasks` utility. :code:`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\sysext\core\bin\typo3 scheduler:run"
|
||||
|
||||
At task creation you will be prompted to give a password or you can
|
||||
use the :code:`/u` and :code:`/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 :code:`schtasks` is available at:
|
||||
http://technet.microsoft.com/en-us/library/bb490996.aspx
|
||||
|
||||
@@ -0,0 +1,26 @@
|
||||
.. ==================================================
|
||||
.. FOR YOUR INFORMATION
|
||||
.. --------------------------------------------------
|
||||
.. -*- coding: utf-8 -*- with BOM.
|
||||
|
||||
.. include:: ../Includes.txt
|
||||
|
||||
|
||||
|
||||
.. _installation:
|
||||
|
||||
====================
|
||||
Installation & setup
|
||||
====================
|
||||
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 5
|
||||
:titlesonly:
|
||||
:glob:
|
||||
|
||||
Installing/Index
|
||||
SetupCheck/Index
|
||||
CronJob/Index
|
||||
BaseTasks/Index
|
||||
|
||||
@@ -0,0 +1,39 @@
|
||||
.. ==================================================
|
||||
.. FOR YOUR INFORMATION
|
||||
.. --------------------------------------------------
|
||||
.. -*- coding: utf-8 -*- with BOM.
|
||||
|
||||
.. include:: ../../Includes.txt
|
||||
|
||||
|
||||
|
||||
.. _installing:
|
||||
|
||||
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:
|
||||
|
||||
- **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.
|
||||
|
||||
- **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.
|
||||
|
||||
.. figure:: ../../Images/ExtensionConfiguration.png
|
||||
:alt: Extension configuration
|
||||
|
||||
Configuring the extension settings
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,57 @@
|
||||
.. ==================================================
|
||||
.. FOR YOUR INFORMATION
|
||||
.. --------------------------------------------------
|
||||
.. -*- coding: utf-8 -*- with BOM.
|
||||
|
||||
.. include:: ../../Includes.txt
|
||||
|
||||
|
||||
|
||||
.. _scheduler-shell-script:
|
||||
|
||||
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 TYPO3
|
||||
to match your system and add the full path to the php interpreter
|
||||
in front of the command if php is not on the search path):
|
||||
|
||||
::
|
||||
|
||||
/home/user/www/typo3/sysext/core/bin/typo3 scheduler:run
|
||||
/usr/local/bin/php /home/user/www/typo3/sysext/core/bin/typo3 scheduler:run
|
||||
|
||||
If your installation is a composer based instance you can use this command line
|
||||
in your installation directory:
|
||||
|
||||
::
|
||||
|
||||
bin/typo3 scheduler:run
|
||||
/usr/local/bin/php bin/typo3 scheduler:run
|
||||
|
||||
|
||||
.. _options:
|
||||
|
||||
Providing options to the shell script
|
||||
"""""""""""""""""""""""""""""""""""""
|
||||
|
||||
The shell scripts accepts a number of options which can be provided in any
|
||||
order.
|
||||
|
||||
To run a specific scheduler task you need to provide the uid of the task:
|
||||
|
||||
::
|
||||
|
||||
/home/user/www/typo3/sysext/core/bin/typo3 scheduler:run --task=8
|
||||
|
||||
The example will trigger the task with uid 8.
|
||||
|
||||
To run a task even if it is disabled, you need to provide the force option
|
||||
|
||||
::
|
||||
|
||||
/home/user/www/typo3/sysext/core/bin/typo3 scheduler:run --task=8 -f
|
||||
|
||||
This will also run the task with uid 8 if it is disabled.
|
||||
@@ -0,0 +1,31 @@
|
||||
.. ==================================================
|
||||
.. FOR YOUR INFORMATION
|
||||
.. --------------------------------------------------
|
||||
.. -*- coding: utf-8 -*- with BOM.
|
||||
|
||||
.. include:: ../../Includes.txt
|
||||
|
||||
|
||||
.. _setup-check:
|
||||
|
||||
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:
|
||||
|
||||
.. figure:: ../../Images/SetupCheck.png
|
||||
:alt: Setup check screen
|
||||
|
||||
Checking the setup of the Scheduler
|
||||
|
||||
The first message shows a warning that the Scheduler has never run
|
||||
yet or an information about the last run.
|
||||
|
||||
The second 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 third message shows information about the current server time.
|
||||
@@ -0,0 +1,47 @@
|
||||
.. ==================================================
|
||||
.. FOR YOUR INFORMATION
|
||||
.. --------------------------------------------------
|
||||
.. -*- coding: utf-8 -*- with BOM.
|
||||
|
||||
.. include:: ../Includes.txt
|
||||
|
||||
|
||||
|
||||
.. _introduction:
|
||||
|
||||
Introduction
|
||||
------------
|
||||
|
||||
|
||||
.. _what-does-it-do:
|
||||
|
||||
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:
|
||||
|
||||
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.
|
||||
|
||||
.. figure:: ../Images/BackendModuleMainView.png
|
||||
:alt: Scheduler main screen
|
||||
|
||||
Main screen of the Scheduler BE module
|
||||
|
||||
|
||||
.. _credits:
|
||||
|
||||
Credits
|
||||
^^^^^^^
|
||||
|
||||
The Scheduler derives from extension Gabriel, originally developed by
|
||||
Christian Jul Jensen and further developed by Markus Friedrich.
|
||||
|
||||
@@ -0,0 +1,21 @@
|
||||
.. ==================================================
|
||||
.. FOR YOUR INFORMATION
|
||||
.. --------------------------------------------------
|
||||
.. -*- coding: utf-8 -*- with BOM.
|
||||
|
||||
.. include:: ../Includes.txt
|
||||
|
||||
|
||||
|
||||
.. _known-problems:
|
||||
|
||||
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.
|
||||
|
||||
|
||||
@@ -0,0 +1,112 @@
|
||||
.. ==================================================
|
||||
.. FOR YOUR INFORMATION
|
||||
.. --------------------------------------------------
|
||||
.. -*- coding: utf-8 -*- with BOM.
|
||||
|
||||
.. include:: ../Includes.txt
|
||||
|
||||
|
||||
|
||||
.. _overview:
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
|
||||
.. _why-a-scheduling-tool:
|
||||
|
||||
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:
|
||||
|
||||
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:
|
||||
|
||||
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:
|
||||
|
||||
Follow-up
|
||||
^^^^^^^^^
|
||||
|
||||
Whenever a task starts or ends a message is written to TYPO'3 system
|
||||
log (viewable in SYSTEM > Log). 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:
|
||||
|
||||
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.
|
||||
|
||||
@@ -0,0 +1,23 @@
|
||||
[general]
|
||||
|
||||
project = Scheduler
|
||||
version = latest (9-dev)
|
||||
release = latest (9-dev)
|
||||
t3author = François Suter
|
||||
copyright = 1997-2021
|
||||
|
||||
description = This is the documentation of TYPO3's system
|
||||
extension 'scheduler' which lets you register tasks
|
||||
to happen at a specific time.
|
||||
|
||||
|
||||
[html_theme_options]
|
||||
|
||||
# Add 'Edit me on Github' button
|
||||
github_branch = master
|
||||
github_repository = TYPO3/TYPO3.CMS
|
||||
path_to_documentation_dir = typo3/sysext/scheduler/Documentation
|
||||
|
||||
# show as related links
|
||||
project_issues = https://forge.typo3.org/projects/typo3cms-core/issues
|
||||
project_repository = https://github.com/typo3/typo3
|
||||
@@ -0,0 +1,13 @@
|
||||
.. ==================================================
|
||||
.. FOR YOUR INFORMATION
|
||||
.. --------------------------------------------------
|
||||
.. -*- coding: utf-8 -*- with BOM.
|
||||
|
||||
.. include:: Includes.txt
|
||||
|
||||
.. _index-labels-for-crossreferencing:
|
||||
|
||||
Index: Labels for Crossreferencing
|
||||
==================================
|
||||
|
||||
.. ref-targets-list::
|
||||
Reference in new issue
Block a user