###########
SchedulerDB
###########


****
NAME
****


Kernel::System::Daemon::SchedulerDB - Scheduler database lib


***********
DESCRIPTION
***********


Includes all scheduler related database functions.


****************
PUBLIC INTERFACE
****************


new()
=====


create a scheduler database object. Do not use it directly, instead use:


.. code-block:: perl

     my $SchedulerDBObject = $Kernel::OM->Get('Kernel::System::Daemon::SchedulerDB');



TaskAdd()
=========


add a new task to scheduler task list


.. code-block:: perl

     my $TaskID = $SchedulerDBObject->TaskAdd(
         Type                     => 'GenericInterface',     # e. g. GenericInterface, Test
         Name                     => 'any name',             # optional
         Attempts                 => 5,                      # optional (default 1)
         MaximumParallelInstances => 2,                      # optional (default 0), number of tasks
                                                             #   with the same type (and name if
                                                             #   provided) that can exists at the same
                                                             #   time, value of 0 means unlimited
         Data => {                                           # data payload
             # ...
         },
     );


Returns:


.. code-block:: perl

     my $TaskID = 123;  # false in case of an error or -1 in case of reach MaximumParallelInstances



TaskGet()
=========


get scheduler task


.. code-block:: perl

     my %Task = $SchedulerDBObject->TaskGet(
         TaskID => 123,
     );


Returns:


.. code-block:: perl

     %Task = (
         TaskID         => 123,
         Name           => 'any name',
         Type           => 'GenericInterface',
         Data           => $DataRef,
         Attempts       => 10,
         LockKey        => 'XYZ',
         LockTime       => '2011-02-08 15:08:01',
         LockUpdateTime => '2011-02-08 15:08:01',
         CreateTime     => '2011-02-08 15:08:00',
     );



TaskDelete()
============


delete a task from scheduler task list


.. code-block:: perl

     my $Success = $SchedulerDBObject->TaskDelete(
         TaskID => 123,
     );



TaskList()
==========


get the list of scheduler tasks


.. code-block:: perl

     my @List = $SchedulerDBObject->TaskList(
         Type => 'some type',  # optional
     );


Returns:


.. code-block:: perl

     @List = (
         {
             TaskID => 123,
             Name   => 'any name',
             Type   => 'GenericInterface',
         },
         {
             TaskID => 456,
             Name   => 'any other name',
             Type   => 'GenericInterface',
         },
         # ...
     );



TaskListUnlocked()
==================


get a list of unlocked tasks


.. code-block:: perl

     my @TaskList = $SchedulerDBObject->TaskListUnlocked();


Returns:


.. code-block:: perl

     @TaskList = ( 456, 789, 395 );



TaskLock()
==========


locks task to a specific PID


.. code-block:: perl

     my $Success = $SchedulerDBObject->TaskLock(
         TaskID => 123,
         NodeID => 1,    # the id on the node in a cluster environment
         PID    => 456,  # the process ID of the worker that is locking the task
     );



TaskCleanup()
=============


deletes obsolete worker tasks


.. code-block:: perl

     my $Success = $SchedulerDBObject->TaskCleanup();



TaskSummary()
=============


get a summary of the tasks from the worker task table divided into handled and unhandled


.. code-block:: perl

     my @Summary = $SchedulerDBObject->TaskSummary();



TaskLockUpdate()
================


sets the task lock update time as current time for the specified tasks


.. code-block:: perl

     my $Success = $SchedulerDBObject->TaskLockUpdate(
         TaskIDs => [123, 456],
     );



TaskUnlockExpired()
===================


remove lock status for working tasks that has not been updated its lock update time for more than 5 minutes


.. code-block:: perl

     my $Success = $SchedulerDBObject->TaskUnlockExpired();



FutureTaskAdd()
===============


add a new task to scheduler future task list


.. code-block:: perl

     my $TaskID = $SchedulerDBObject->FutureTaskAdd(
         ExecutionTime            => '2015-01-01 00:00:00',
         Type                     => 'GenericInterface',  # e. g. GenericInterface, Test
         Name                     => 'any name',          # optional
         Attempts                 => 5,                   # optional (default 1)
         MaximumParallelInstances => 2,                   # optional (default 0), number of tasks
                                                          #   with the same type (and name if provided)
                                                          #   that can exists at the same time,
                                                          #   value of 0 means unlimited
         Data => {                                        # data payload
             # ...
         },
     );


Returns:


.. code-block:: perl

     my $TaskID = 123;  # or false in case of an error



FutureTaskGet()
===============


get scheduler future task


.. code-block:: perl

     my %Task = $SchedulerDBObject->FutureTaskGet(
         TaskID => 123,
     );


Returns:


.. code-block:: perl

     %Task = (
         TaskID        => 123,
         ExecutionTime => '2015-01-01 00:00:00',
         Name          => 'any name',
         Type          => 'GenericInterface',
         Data          => $DataRef,
         Attempts      => 10,
         LockKey       => 'XYZ',
         LockTime      => '2011-02-08 15:08:01',
         CreateTime    => '2011-02-08 15:08:00',
     );



FutureTaskDelete()
==================


delete a task from scheduler future task list


.. code-block:: perl

     my $Success = $SchedulerDBObject->FutureTaskDelete(
         TaskID => 123,
     );



FutureTaskList()
================


get the list of scheduler future tasks


.. code-block:: perl

     my @List = $SchedulerDBObject->FutureTaskList(
         Type => 'some type',  # optional
     );


Returns:


.. code-block:: perl

     @List = (
         {
             TaskID        => 123,
             ExecutionTime => '2015-01-01 00:00:00',
             Name          => 'any name',
             Type          => 'GenericInterface',
         },
         {
             TaskID        => 456,
             ExecutionTime => '2015-01-01 00:00:00',
             Name          => 'any other name',
             Type          => 'GenericInterface',
         },
         # ...
     );



FutureTaskToExecute()
=====================


moves all future tasks with reached execution time to the task table to execute


.. code-block:: perl

     my $Success = $SchedulerDBObject->FutureTaskToExecute(
         NodeID => 1,    # the ID of the node in a cluster environment
         PID    => 456,  # the process ID of the daemon that is moving the tasks to execution
     );



FutureTaskSummary()
===================


get a summary of the tasks from the future task table


.. code-block:: perl

     my @Summary = $SchedulerDBObject->FutureTaskSummary();



CronTaskToExecute()
===================


creates cron tasks that needs to be run in the current time into the task table to execute


.. code-block:: perl

     my $Success = $SchedulerDBObject->CronTaskToExecute(
         NodeID => 1,    # the ID of the node in a cluster environment
         PID    => 456,  # the process ID of the daemon that is creating the tasks to execution
     );



CronTaskCleanup()
=================


removes recurrent tasks that does not have a matching a cron tasks definition in SysConfig


.. code-block:: perl

     my $Success = $SchedulerDBObject->CronTaskCleanup();



CronTaskSummary()
=================


get a summary of the cron tasks from the recurrent task table


.. code-block:: perl

     my @Summary = $SchedulerDBObject->CronTaskSummary();



GenericAgentTaskToExecute()
===========================


creates generic agent tasks that needs to be run in the current time into the task table to execute


.. code-block:: perl

     my $Success = $SchedulerDBObject->GenericAgentTaskToExecute(
         NodeID => 1,    # the ID of the node in a cluster environment
         PID    => 456,  # the process ID of the daemon that is creating the tasks to execution
     );



GenericAgentTaskCleanup()
=========================


removes recurrent tasks that does not have a matching generic agent job


.. code-block:: perl

     my $Success = $SchedulerDBObject->GenericAgentTaskCleanup();



GenericAgentTaskSummary()
=========================


get a summary of the generic agent tasks from the recurrent task table


.. code-block:: perl

     my @Summary = $SchedulerDBObject->GenericAgentTaskSummary();



RecurrentTaskGet()
==================


get scheduler recurrent task


.. code-block:: perl

     my %Task = $SchedulerDBObject->RecurrentTaskGet(
         TaskID => 123,
     );


Returns:


.. code-block:: perl

     %Task = (
         TaskID            => 123,
         Name              => 'any name',
         Type              => 'GenericInterface',
         LastExecutionTime => '2015-01-01 00:00:00',
         LockKey           => 'XYZ',
         LockTime          => '2015-01-02 00:00:00',
         CreateTime        => '2015-01-01 00:00:00',
         ChangeTime        => '2015-01-02 00:00:00',
     );



RecurrentTaskList()
===================


get the list of scheduler recurrent tasks


.. code-block:: perl

     my @List = $SchedulerDBObject->RecurrentTaskList(
         Type => 'some type',  # optional
     );


Returns:


.. code-block:: perl

     @List = (
         {
             TaskID            => 123,
             Name              => 'any name',
             Type              => 'GenericInterface',
             LastExecutionTime => '2015-01-01 00:00:00',
             LockKey           => 'XYZ',
             LockTime          => '2015-01-02 00:00:00',
             CreateTime        => '2015-01-01 00:00:00',
             ChangeTime        => '2015-01-02 00:00:00',
         },
         {
             TaskID            => 456,
             Name              => 'any other name',
             Type              => 'GenericInterface',
             LastExecutionTime => '2015-01-01 00:00:00',
             LockKey           => 'XYZ',
             LockTime          => '2015-01-02 00:00:00',
             CreateTime        => '2015-01-01 00:00:00',
             ChangeTime        => '2015-01-02 00:00:00',
         },
         # ...
     );



RecurrentTaskDelete()
=====================


delete a task from scheduler recurrent task list


.. code-block:: perl

     my $Success = $SchedulerDBObject->RecurrentTaskDelete(
         TaskID => 123,
     );



RecurrentTaskExecute()
======================


executes recurrent tasks like cron or generic agent tasks


.. code-block:: perl

     my $Success = $SchedulerDBObject->RecurrentTaskExecute(
         NodeID                   => 1,                 # the ID of the node in a cluster environment
         PID                      => 456,               # the process ID of the daemon that is creating
                                                        #    the tasks to execution
         TaskName                 => 'UniqueTaskName',
         TaskType                 => 'Cron',
         PreviousEventTimestamp   => 1433212343,
         MaximumParallelInstances => 1,                 # optional (default 0) number of tasks with the
                                                        #    same name and type that can be in execution
                                                        #    table at the same time, value of 0 means
                                                        #    unlimited
         Data                   => {                    # data payload
             # ...
         },
     );



RecurrentTaskSummary()
======================


get a summary of the recurring tasks for the specified task type


.. code-block:: perl

     my @Summary = $SchedulerDBObject->RecurrentTaskSummary(
         Type         => 'some_type',
         DisplayType  => 'some type',
         TaskLookup   => {                       # only tasks with names in this table will be shown
             TaskName1 => '* * * * *',           #   the value of the items in this table is a crontab
             TaskName3 => '*/1 3,4 * * * 0',     #   format schedule
         }
     );



RecurrentTaskWorkerInfoSet()
============================


sets last worker information (success status and running time) to a recurrent task


.. code-block:: perl

     my $Success = $SchedulerDBObject->RecurrentTaskWorkerInfoSet(
         LastWorkerTaskID      => 123,        # the task ID from the worker table that is performing the
                                              #      recurring task
         LastWorkerStatis      => 1,          # optional 1 or 0, defaults to 0, 1 means success
         LastWorkerRunningTime => 123,        # optional, defaults to 0, the number in seconds a worker took
                                              #      to complete the task
     );



RecurrentTaskUnlockExpired()
============================


remove lock status for recurring tasks that has been locked for more than 1 minutes


.. code-block:: perl

     my $Success = $SchedulerDBObject->RecurrentTaskUnlockExpired(
         Type => 'some_type',
     );




*****************
PRIVATE INTERFACE
*****************


_Seconds2String()
=================


convert an amount of seconds to a more human readable format, e.g. < 1 Second, 5 Minutes


.. code-block:: perl

     my $String = $SchedulerDBObject->_Seconds2String(.2);


returns


.. code-block:: perl

     $String = '< 1 Second';


or


.. code-block:: perl

     my $String = $SchedulerDBObject->_Seconds2String(8);


returns


.. code-block:: perl

     $String = '8 Second(s)';


or


.. code-block:: perl

     my $String = $SchedulerDBObject->_Seconds2String(62);


returns


.. code-block:: perl

     $String = '1 Minute(s)';


or


.. code-block:: perl

     my $String = $SchedulerDBObject->_Seconds2String(3610);


returns


.. code-block:: perl

     $String = '1 Hour(s)';


or


.. code-block:: perl

     my $String = $SchedulerDBObject->_Seconds2String(86_640);


returns


.. code-block:: perl

     $String = '1 Day(s)';



_GetIdentifier()
================


calculate a task identifier.


.. code-block:: perl

     my $Identifier = $SchedulerDBObject->_GetIdentifier();


returns


.. code-block:: perl

     $Identifier = 1234456789;