Tasks API

AbanteCart core provides tasks API to to create and run tasks. The task can be used to break large or long processes into smaller steps that can be run with AJAX or with a backend script. Using task/steps you can show progress to the user and prevent the browser or connection from timing out in longer processes.




Currently, tasks are used in 2 places of core AbanteCart. 
Task is used in a backup and in bulk messaging. We use these places as example in this manual.

  • Task core files:

    core/lib/task_manager.php - Admin class ATaskManager
    core/engine/task.php - Core class ATypeTask.
  • Task related database tables:

    [pefix]tasks - Main table for task information and status 
    [pefix]task_details - Task details table for settings 
    [pefix]task_steps - Task steps with settings for execution

Task is an organizational process to handle execution of created requests (steps). Execution of each step is passed to specified controller with provided settings in this given step. 
Task can be execute right away or postponed to specified time. 
Each task consists of steps that are organized in a sequence in which they are executed. Each task must have at least one step.
Now let's look into task creation and execution process and data with more details.


Task

To create a new task in the code, you need instantiate class ATaskManager in admin controller or model and run addTask() method with required parameters to create the task.

$tm = new ATaskManager();
		$task_id = $tm->addTask(

			array( 'name' => $task_name,

					'starter' => 1, //admin-side is starter

					'created_by' => $this->user->getId(), //get starter id

					'status' => 1, // schedule it!

					'start_time' => date('Y-m-d H:i:s', mktime(0,0,0, date('m'), date('d')+1, date('Y')) ),

					'last_time_run' => '0000-00-00 00:00:00',

					'progress' => '0',

					'last_result' => '0',

					'run_interval' => '0',

					'max_execution_time' => '0'

			)

		);

Once task is creates with addTask() method, it returns new task ID. Using this task ID, tasks steps can be created with addStep() method. 


In the task creation you can specify details for this task. 



Description of task parameters

name

->Task name. This can be any name your.
starter->Who will start the task Admin (1) or Storefront (0)
created_by->User ID who creates this task
status->Status of the task 0 - disabled, 1 - scheduled, 2 - active
start_time->time to start task with Mysql date time format
last_time_run->last time task ran
progress->Percentage of task progress
last_result->Status of last task ran 0 - success, 1 - failed, 2 - interrupted
run_interval->interval in seconds since last run, 0 - without interval or run once
max_execution_time->maximum execution time for this task before it gets terminated.



Steps

At least one step is required to be created for task to be executed. To create a step use addStep() method. Before creating a step, task should be already created and there should be task ID available.


$step_id = $tm->addStep( array(

				'task_id' => $task_id,

				'sort_order' => 1,

				'status' => 1,

				'last_time_run' => '0000-00-00 00:00:00',

				'last_result' => '0',

				'max_execution_time' => ceil($db_size/2794843)*4,

				'controller' => 'task/tool/backup/dumptables',

				'settings' => array(

								'table_list' => $data['table_list'],

								'sql_dump_mode'=> $data['sql_dump_mode'],

								'backup_name' => $backup_filename

								)

			));


Following parameters need are specified during step creation:
task_idUnique task ID provided by addTask() method
sort_orderSequence of the step. This sequence starts from lower integer to higher
statusStep status 0 - disabled, 1 - scheduled, 2 - active
last_time_runlast time task ran
last_resultStatus of last task ran 0 - success, 1 - failed, 2 - interrupted
max_execution_timemaximum execution time for this task before it gets terminated
controllerController path to be executed in this step
settingsData values to be passed to controller at execution time


One special setting, that is important mentioning, is interrupt_on_step_fault. If given step has interrupt_on_step_fault set to true, task execution will stop if that step returns a failure. 


After all needed steps are created task can be executed.

Task execution is considered successful only if all steps in that task executed sucessfuly.


Step controller

Each step should have a controller that will be called during task and this step execution. 
This is a basic response controller that is developed to perform some work required by this step. 
In example of backup, "task/tool/backup/dumptables" controller performs task of dumping tables data. Each step is a process of damping data for one table. 
Step response controller is expected to return appropriate Jason string with error is step has failed.


Task Execution

Task execution can be initiated 2 different ways.

1. Start from running task.php script from browser or from command line. Request to this script will put all scheduled tasks in the queue and will process them one by one. 

/task.php file in github


2. Start task from UI with explicitly requesting task to start with button click or some other browser/user action. This is done using admin JavaScript function available in admin/view/default/javascript/general.js

public_html/admin/view/default/javascript/general.js file in github.


Example of button to run the task:
<button class="btn btn-primary task_run" data-run-task-url="<?php echo $form['build_task_url']?>" data-complete-task-url="<?php echo $form['complete_task_url']?>">

	<i class="fa fa-database"></i> <?php echo $form['backup_now']->text; ?>

</button>
task_run->class that start last even is blinded to
data-run-task-url->URL to the task process creation response controller
data-complete-task-url->URL to the task/steps execution response controller that completes the task

Example of task creation and execution can be seen in store back up and bulk email See:


public_html/admin/controller/responses/tool/backup.php


public_html/admin/model/tool/backup.php


And 


public_html/admin/controller/responses/sale/contact.php


public_html/admin/model/sale/contact.php