From http://wiki.vtiger.com/archives

Faq | Howto

Contents 1 About 2 Features 3 How to Use? 3.1 Create Workflow 3.2 Create tasks 3.3 Configuring tasks 3.3.1 Common Fields 3.3.2 Email Task 3.3.3 Invoke custom function 3.3.4 Todo Task 3.3.5 Event Task 4 Configuring Cron Job 4.1 Setup Cron job 4.2 Update batch/shell script 4.2.1 Windows Users 4.2.2 *nix Users 5 References

About

The Workflow module in vtiger is a new addition which provides a simple interface to add actions upon save of an entity. These actions will be triggered when the given conditions are met.

Features

Workflow module provides a number of options to trigger actions based on conditions on save of entities (records). The basic features provided are -

• When to trigger the workflow. This can be of three types
  • Only on the first save: It will look for the condition at the time of creation and if specified condition mate it will execute work flow. If the condition will not match it will not look for the subsequent edit.
  • Until the first time the condition is true: It look for the condition and as soon as the condition is true, it will execute the workflow, but after this the workflow is no longer valid.
  • Every time the the record is saved: It checks the condition on every save (when ever save button is pressed create and edit in both the cases) and execute the workflow if condition matches.

• Conditions on which to trigger the workflow

How to Use?

To configure workflow for a module -

• As an admin user go to the Settings page and click on the Workflows link (this can be found under the Other Settings block)

• This will bring up the list of all defined workflows (by default all workflows are listed).
• You can see all the available workflow for any particular module using the Select Module dropdown on the page.

• Workflow in vtiger provides options to -

1. create a new workflow
2. edit an existing workflow
3. delete an existing workflow

Create Workflow

• Click on the New Workflow button. A popup will appear listing the available modules.

• Select a module and click 'Create'. You will be taken to an edit page for the workflow.
• Add a Description for the workflow. You can specify here when workflow should run.

• You can add more conditions by clicking the New Condition button.

• Click the 'Save' Button to save the new workflow.
• Once you have saved the workflow, you will be presented with a screen where you can add the tasks for the workflow. These task(s) will be executed once the workflow conditions are satisfied.

Create tasks

• Click on the New Task button to add a new task. You will get a popup to select the type of task you can create. Currently there are multiple types of tasks -

1. Send Email task which can be used to send mails
2. Invoke custom function task which will call certain specific methods on the entity objects.
3. Create Todo task which will create a todo when the workflow condition is met.
4. Create Event task, which is same as the Create todo task other than that it creates an event.

• Select a task type from the dropdown and click on the create button to create the task.

Configuring tasks

Common Fields

The following fields are common for all workflow tasks

1. Task Title - This is the title of the task used in the list task list to identify the task.
2. Status - This is a selection box which should be set to active if the task is to be executed when the workflow executes.
3. Execute the task after some delay - This is a check box, if this is checked you will be provided with additional fields to control when the task will be executed.

Email Task

In this task's edit page you have a description field. The workflow status field specifies whether the task is active, if the task is marked Inactive it will not be executed when the workflow evaluates to true. You can specify when the task is executed relative to the time in a date field. Also, you have the fields related to the module in a dropdown which you can use in the email template that you create.

Invoke custom function

This option provides a way for developers to add module specific actions to workflows. To define a task, you need to define a method to be called. This method should be defined as a function in it's own file.

File: module/Workflow/Demo.inc
<?php
function demo($entity){
$entity->focus->called = true;
}
?>

The method then needs to be registered, for example if the method was defined in the file modules/demo/Demo.inc for the Contacts module and given the name method.

require_once 'include/utils/utils.php';
require 'modules/com_vtiger_workflow/VTEntityMethodManager.inc';
$emm = new VTEntityMethodManager($adb);
$emm->addEntityMethod("PurchaseOrder", "method", "modules/Workflow/Demo.inc", "demo");

The method will appear in the list of methods available for the Contacts module.

Todo Task

Using this option, you can setup a workflow to create a new calendar Todo when a condition is matched. The following fields are provided in the createview of this option -

1. Todo - The title of the todo.
2. Description - Of the todo.
3. Status - The status of the todo, can be selected from the dropdown
4. Priority - The priority of the todo, can be selected from the dropdown.
5. Time - The start time of the todo, in 24 hours time.
6. Due Date - The due date for the todo, the start date is also set using this.
7. Send Notification - Set the send notification flag.

If the module which triggers the workflow is Contacts then the Contact Name field will be bound to the contact. If the module is one of the acceptable modules for the Related To field then the module Related To field will be bound to the module.

Event Task

This is same as Todo task other than that it creates a event instead of a task.

Configuring Cron Job

Path to Batch File  : <vtigercrm-source-directory>/cron/modules/com_vtiger_workflow/com_vtiger_workflow.bat

Path to Shell Script : <vtigercrm-source-directory>/cron/modules/com_vtiger_workflow/com_vtiger_workflow.sh

Setup Cron job

A Cron job has to be set, to send Emails at regular intervals for the Email task that are setup.

(Refer to How to setup cron job documentation for details)

Also You need to apply the Appkey in

vtigercrm/Cron/config.cron.php

To know how to do it please go to the following link

How to apply app_key

Update batch/shell script

Windows Users

In com_vtiger_workflow.bat file,

1. Update VTIGERCRM_ROOTDIR with path to Vtiger source directory.
2. Update PHP_EXE with path to php.exe file of PHP setup.

*nix Users

You do not need to update anything in the shell script.

References

http://forums.vtiger.com/viewtopic.php?p=104978