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:

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

TaskAdd()#

add a new task to scheduler task list

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:

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

TaskGet()#

get scheduler task

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

Returns:

%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

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

TaskList()#

get the list of scheduler tasks

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

Returns:

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

TaskListUnlocked()#

get a list of unlocked tasks

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

Returns:

@TaskList = ( 456, 789, 395 );

TaskLock()#

locks task to a specific PID

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

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

TaskSummary()#

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

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

TaskLockUpdate()#

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

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

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

FutureTaskAdd()#

add a new task to scheduler future task list

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:

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

FutureTaskGet()#

get scheduler future task

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

Returns:

%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

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

FutureTaskList()#

get the list of scheduler future tasks

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

Returns:

@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

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

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

CronTaskToExecute()#

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

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

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

CronTaskSummary()#

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

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

GenericAgentTaskToExecute()#

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

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

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

GenericAgentTaskSummary()#

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

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

RecurrentTaskGet()#

get scheduler recurrent task

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

Returns:

%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

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

Returns:

@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

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

RecurrentTaskExecute()#

executes recurrent tasks like cron or generic agent tasks

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

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

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

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

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

returns

$String = '< 1 Second';

or

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

returns

$String = '8 Second(s)';

or

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

returns

$String = '1 Minute(s)';

or

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

returns

$String = '1 Hour(s)';

or

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

returns

$String = '1 Day(s)';

_GetIdentifier()#

calculate a task identifier.

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

returns

$Identifier = 1234456789;