Document automatic actions; fixes #23

source/devapi/crontasks.rst

@@ -0,0 +1,127 @@
+Automatic actions
+-----------------
+
+Goals
+^^^^^
+
+Provide a scheduler for background tasks used by GLPI and its plugins.
+
+Implementation overview
+^^^^^^^^^^^^^^^^^^^^^^^
+
+The entry point of automatic actions is the file ``front/cron.php``. On each execution, it executes a limited number of automatic actions.
+
+There are two ways to wake up the scheduler :
+ - when a user browses in GLPI (the internal mode)
+ - when the operating system's scheduler calls ``front/cron.php`` (the external mode)
+
+When GLPI generates an HTML page for a browser, it adds an invisible image generated by ``front/cron.php``. This way, the automatic action runs in a separate process and does not imapct the user.
+
+The automatic actions are defined by the `CronTask class <https://forge.glpi-project.org/apidoc/class-CronTask.html>`_. GLPI defines a lot of them for its own needs. They are created in the installation or upgrade process.
+
+Implementation
+^^^^^^^^^^^^^^
+
+Automatic actions could be related to an itemtype and the implemention is defined in its class or haven't any itemtype relation and are implemented directly into `CronTask class <https://forge.glpi-project.org/apidoc/class-CronTask.html>`_.
+
+When GLPI shows a list of automatic actions, it shows a short description for each item. The description is gathered in the static method ``cronInfo()`` of the itemtype.
+
+.. Note::
+
+   An itemtype may contain several automatic actions.
+
+Example of implementation from the `QueuedMail class <https://forge.glpi-project.org/apidoc/class-QueuedMail.html>`_ :
+
+.. code-block:: php
+
+   <?php
+   class QueuedMail extends CommonDBTM {
+
+      // ...
+
+      /**
+       * Give cron information
+       *
+       * @param $name : automatic action's name
+       *
+       * @return arrray of information
+      **/
+      static function cronInfo($name) {
+
+         switch ($name) {
+            case 'queuedmail' :
+               return array('description' => __('Send mails in queue'),
+                            'parameter'   => __('Maximum emails to send at once'));
+         }
+         return array();
+      }
+
+      /**
+       * Cron action on queued mails : send mails in queue
+       *
+       * @param CronTask $task for log, if NULL display (default NULL)
+       *
+       * @return integer 1 if an action was done, 0 if not
+      **/
+      static function cronQueuedMail($task=NULL) {
+         global $DB, $CFG_GLPI;
+
+         if (!$CFG_GLPI["use_mailing"]) {
+            return 0;
+         }
+         $cron_status = 0;
+
+         // Send mail at least 1 minute after adding in queue to be sure that process on it is finished
+         $send_time = date("Y-m-d H:i:s", strtotime("+1 minutes"));
+         $query       = "SELECT `glpi_queuedmails`.*
+                         FROM `glpi_queuedmails`
+                         WHERE NOT `glpi_queuedmails`.`is_deleted`
+                               AND `glpi_queuedmails`.`send_time` < '".$send_time."'
+                         ORDER BY `glpi_queuedmails`.`send_time` ASC
+                         LIMIT 0, ".$task->fields['param'];
+
+         $mail = new self();
+         foreach ($DB->request($query) as $data) {
+            if ($mail->sendMailById($data['id'])) {
+               $cron_status = 1;
+               if (!is_null($task)) {
+                  $task->addVolume(1);
+               }
+            }
+         }
+         return $cron_status;
+      }
+
+      // ...
+
+   }
+
+If the argument ``$task`` is a `CronTask <https://forge.glpi-project.org/apidoc/class-CronTask.html>`_ object, the method must increment the quantity of actions done. In this example, each email actually sent increments the volume by 1.
+
+Register an automatic actions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Automatic actions are defined in the empty schema located in ``install/mysql/``. Use  the existing sql queries creating rows in the table ``glpi_crontasks`` as template for a new automatic action.
+
+To handle upgrade from a previous version, the new automatic actions must be added in the appropriate update file ``install/update_xx_to_yy.php``.
+
+.. code-block:: php
+
+   <?php
+   // Register an automatic action
+   CronTask::register('QueuedMail', 'QueuedMail', HOUR_TIMESTAMP,
+         array(
+         'comment'   => '',
+         'mode'      => CronTask::MODE_EXTERNAL
+   ));
+
+The ``register`` method takes four arguments:
+
+* ``itemtype``: a ``string`` containing an itemtype name containing the automatic action implementation
+* ``name``: a ``string`` containing the name of the automatic action
+* ``frequency`` the period of time between two executions in seconds (see ``inc/define.php`` for convenient constants)
+* ``options`` an array of options
+
+.. Note::
+
+   The name of an automatic action is actually the method's name without the prefix cron. In the example, the method ``cronQueuedMail`` implements the automatic action named ``QueudMail``.

source/devapi/index.rst

@@ -12,5 +12,6 @@ Apart from the current documentation, you can also check the `full PHP documenta
    dbmodel
    rules
    translations
-   tools
    acl
+   crontasks
+   tools

source/plugins/crontasks.rst

@@ -0,0 +1,25 @@
+Automatic actions
+-----------------
+
+Goals
+^^^^^
+
+Plugins may need to run automatic actions in backgroud, or at regular interval. GLPI provides a task scheduler for itself and its plugins.
+
+Implement an automatic action
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A plugin must implement its automatic action the same way as GLPI does, except the method is located in a plugin's itemtype. See :doc:`crontasks <../devapi/crontasks>`.
+
+Register an automatic action
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A plugin must register its automatic action the same way as GLPI does in its upgrade process. See :doc:`crontasks <../devapi/crontasks>`.
+
+
+Unregister a task
+^^^^^^^^^^^^^^^^^
+
+GLPI unregisters tasks of a plugin when it cleans or uninstalls it.
+
+

source/plugins/index.rst

@@ -21,4 +21,5 @@ If you want to see more advanced examples of what it is possible to do with plug
    database
    objects
    hooks
+   crontasks
    tips