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. 

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

								)

			));

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.

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.

<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>

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

API Reference

ATaskManager class API methods in task_manager.php file

runTasks
runTask
addTask
updateTask
updateTaskDetails
addStep
updateStep
deleteTask
deleteStep
getTaskById
getTaskByName
getTaskSteps
getTotalTasks
getTasks