How to add a workflow task with the configuration screen

There are two types of workflow tasks that can be added to the system: custom workflow functions and full-blown workflow tasks. The difference is the configuration screen. A custom function is just a set of instructions and code that do not need any configuration options, it's task is clearly defined and it just needs to be launched on the given event. For example, a routine that relates the products and services of an invoice with the account of the invoice is a custom function. This custom function does not need anything more than what it receives to get its work done, but it could get a little complicated and we could require an option to indicate if we want to have only products and not services related or the reverse, or both. Now that we need to know which elements to relate the custom function needs a configuration screen and must be converted into a workflow task with the configuration screen.

The second type of workflows

A workflow task needs a name to show in the configuration section, a class that will extend VTTask and do the work, a template to show the configuration options on screen and it will be associated with certain modules and not to others. Finally, it may be active or not depending on a certain module is installed or not.

• Add a new task definition to the application. This is done by inserting a record with the details in the com_vtiger_workflow_tasktypes table.

  • tasktypename: internal name of the task

  • label: external name. will be translated before showing

  • classname: our class that extends VTTask

  • classpath: the script on the file system that contains our new workflow

  • templatepath: the Smarty template script on the file system that will show the configuration screen

  • modules: a JSON array of the module that the workflow is included and excluded from

  • sourcemodule: the main module the workflow is related to if this module is not installed/active the workflow will not be available. if left empty it will be available

  • An example would be:

    • “name”⇒“CBTagTask”: internal reference name

    • “label”⇒“CBTagTask”: label to show on screen

    • “classname”⇒“CBTagTask”: name of the class to invoke to do the work

    • “classpath”⇒“modules/com_vtiger_workflow/tasks/CBTagTask.inc”: path to class that does the work

    • “templatepath”⇒“com_vtiger_workflow/taskforms/CBTagTask.tpl”: path to the smarty template

    • “modules”⇒array('include' ⇒ array(), 'exclude'⇒array()): available for all modules

    • “sourcemodule”⇒'': not tied to any specific module

  • you can see more examples looking at the definitions of the preloaded workflow tasks

• Add new task file: modules/com_vtiger_workflow/tasks/CBTagTask.inc, which contains the class that will do the work. You can put the script anywhere you want in the application file system, but it has to be the same place indicated in the database record.

• The script modules/com_vtiger_workflow/tasks/CBTagTask.inc defines the base VTTask class extended for this case.

  • The name of the class has to be the same we added in the database record in the first step

  • Important is the getFieldNames() method where by simply adding a list of variables they will get saved with no other work than to send them through REQUEST

  • The doTask() method is where the action of the task has to be implemented

• Add translation strings for the new Task in com_vtiger_workflow/language

 

'CBTagTask' => 'Add/Delete Tag',

 

• Add new task template file: Smarty/templates/com_vtiger_workflow/taskforms/CBTagTask.tpl

  • This script must be inside the Smarty/templates directory and must be the same as the value we inserted in the database

  • This template file can do any magic that is needed, usually using the module's base translation files for screen output. Special considerations are that we have available a $task object with the definitions of the task we are editing and this object has properties for each of the variables we defined in the getFieldNames() method.

  • We simply have to create an HTML input or similar with the same name for it to be saved automatically

You can see a full example of how we add a new workflow task to add and delete Tags 

How to add a workflow custom function

The first type of workflows

A workflow method or custom function needs a name to show in the configuration section, a class that will extend VTTask and does the work, and it will be associated with certain modules and not to others. Finally, it may be active or not depending on a certain module is installed or not.

• Add a new task definition to the application. This is done by inserting a record with the details in the com_vtiger_workflowtasks_entitymethod table.

  • method_name: external name, visible when configuring workflow: available through the Invoke Custom Function workflow task

  • function_name: the name of the function to be called, a normal PHP function

  • function_path: the script on the file system that contains our new function

  • module_name: the name of the module that the method is available for

  • An example would be:

    • “method_name”⇒“Update Contact Assigned To”: label to show on screen

    • “function_name”⇒“updateContactAssignedTo”: name of the function to invoke to do the work

    • “function_path”⇒“include/wfMethods/updateContactAssignedTo.php”: the path to the script that contains the function

    • “module_name”⇒'Accounts': will be available only for this module, if more modules can use this function you must insert a new record for each module.

  • coreBOS has a helper method that can insert this record for you: VTEntityMethodManager::addEntityMethod(), an example call would be like this:

<?php
// Turn on debugging level
$Vtiger_Utils_Log = true;

require_once 'include/utils/utils.php';
include_once('vtlib/Vtiger/Module.php');
require 'modules/com_vtiger_workflow/VTEntityMethodManager.inc';
global $adb;

$emm = new VTEntityMethodManager($adb);
$emm->addEntityMethod("Accounts", "Update Contact Assigned To", "include/wfMethods/updateContactAssignedTo.php", "updateContactAssignedTo");
echo 'add Workflow Custom Function complete!';
?>

• • or like this using coreBOS Updater

• Add a new workflow function file: include/wfMethods/updateContactAssignedTo.php, which contains the function that will do the work. You can put the script anywhere you want in the application file system, but it has to be the same place indicated in the database record.

• The script include/wfMethods/updateContactAssignedTo.php defines the function indicated in the database record.

  • The name of the function has to be the same we added in the database record in the first step

  • The function will receive one parameter: a VTEntityData object of the record being saved. This object can be found in include/events/VTEntityData.inc and contains a variable called focus which contains the full CRMEntity record. It also has an array with all the values being saved in data.

  • We also have access to all of the coreBOS programming infrastructure

You can see a full example of how we add a new workflow method to assign contacts to the same account user