Developing a Simple Workflow within SugarCRM

Workflow is about getting the right work to the right people at the right time, repeatedly—and knowing you have done so. Workflow is human-centric. First and foremost, workflow is a human activity that is made by and for those who use it: workflow is something that can easily be handled and understood by human beings.
UK Enterprise Workflow National e-Government Project—Workflow from a Business Perspective
Well, that sounds good, but the problems start to occur when you ask people to consider workflow in their organization, and there are usually a few main issues to deal with:

• You'll find that people are normally experts in their own fields—there are often very few people who have an overview of the whole process that you're trying to map.
• Sections of a large organization will often have different ways of carrying out the same overall process.
• People don't really like to be told how to do their jobs—they especially don't like to have any extra processes imposed on them for now obvious reason—well, would you?
• Talk of 'improved utilization of resources', 'improved performance monitoring', and such like can soon alienate the staff who are going to be using the system. They'll soon start using terms such as 'Big Brother'.

How you are able to deal with these will depend on your organization and the people that are available to you. At least once you've read this article by Dr. Mark Alexander Bain, you'll know that, once you've overcome those problems, the workflow itself will be easy.

A Very Simple Workflow

In our simple workflow we'll assume that each task is carried out by one person at a time, and that all tasks are done sequentially (i.e. none are done in parallel). So, we'll look at the PPI Preliminary Investigation which, as you remember, maps to the standard SugarCRM Opportunity. Also, in this example, we're going to have a different person carrying out each one of the Investigation stages.

Setting up the Process Stages

If you look at SugarCRM then you'll see that by default none of the stages are related to investigations—they're all named using standard CRM terms:

Obviously the first thing to do is to decide what the preliminary investigation stages actually are, and then map these to the SugarCRM stages. You'll realize that you'll need to edit the custom/include/langauge/en_us.lang.php file:

$app_list_strings['sales_stage_dom']=array (
  'Prospecting' => 'Fact Gathering',
  'Qualification' => 'Witness and Subject Location',
  'Needs Analysis' => 'Witness and Subject Interviews',
  'Value Proposition' => 'Scene Investigation',
  'Id. Decision Makers' => 'Financial and background Investigation',
  'Perception Analysis' => 'Document and evidence retrieval',
  'Proposal/Price Quote' => 'Covert Camera surveillance',
  'Negotiation/Review' => 'Wiretapping',
  'Closed Won' => 'Full Investigation required',
  'Closed Lost' => 'Insufficient Evidence',
);

Don't forget that you can also do this via Studio. However, once you've added your mapping into custom/include/langauge/en_us.lang.php file, and refresh your browser, then you'll see the new stages:

Now that our stages are set up we need to know who'll be carrying out each one.

Deciding Who Does What

In our simple workflow there may not be the need to do anything further. Each person just needs to know who does what next:
For example, once Kurt finishes the 'Covert Camera surveillance' stage then he just needs to update the Preliminary Investigation so that the stage is set to 'Wiretapping' and the assigned user as 'dobbsm'.
However, things are rarely as simple as that. It's much more likely that:

• Investigations may be based on geographical locations, so that the above table may only apply to investigations based in London. Investigations based in New York follow the same process but with a different set of staff.
• On Mondays Fran does 'Witness and Subject Location' and William does 'Fact Gathering'.

This means, of course, that we need to be using some businesses rules.

Introducing Business Rules

There are six 'triggers' that will cause the logic hooks to fire:

• after_retrieve
• before_save
• before_delete
• after_delete
• before_undelete
• after_undelete

And the logic hooks are stored in custom/modules//logic_hook.php, so for 'Preliminary Inquiries' this will be custom/modules/Opportunities/logic_hook.php. You'll also remember, of course, that the logic hook file needs to contain:

• The priority of the business rule
• The name of the businesses rule
• The file containing the business rule
• The business rule class
• The business rule function

So, custom/modules/Opportunities/logic_hook.php needs to contain something like:

#As always ensure that the file can only be accessed through SugarCRM
if(!defined('sugarEntry') || !sugarEntry) die(
     'Not A Valid Entry Point');
$hook_array = Array(); #Create an array

$hook_array['before_save'] = Array();
$hook_array['before_save'][] = Array(1, 'ppi_workflow',
  'custom/include/ppi_workflow.php',
  'ppi_workflow', 'ppi_workflow');
?>

Next we'll need the file that logic hook will be calling, but to start with this can be very basic—so, custom/include/ppi_workflow.php just needs to contain something like:

#Define the entry point
if(!defined('sugarEntry') || !sugarEntry) die(
     'Not A Valid Entry Point');
#Load any required files
require_once('data/SugarBean.php');
require_once('modules/Opportunities/Opportunity.php');

#Define the class
class ppi_workflow
{
  function ppi_workflow (&$bean, $event, $arguments)
  {

  }
}
?>

With those two files set up as above nothing obvious will change in the operation of SugarCRM—the logic hook will fire, but we haven't told it to do anything, and so that what we'll do now.
When the logic hook does run (i.e. when any Primary Investigation is saved) we would want it to:

• Check to see what stage we're now at
• Define the assigned user accordingly

All of the relevant information (i.e. the new stage) is passed to the logic hook by means of the $bean object, and we can obtain the stage from $bean->sales_stage. Now all we have to do is combine this with PHP's switch statement into the ppi_workflow function:

switch ($bean->sales_stage)
{
    case "Prospecting":
      $assigned_user = "varadyf";
      break;
    case "Qualification":
      $assigned_user = "monkw";
      break;
    case "Needs Analysis":
      $assigned_user = "pittc";
      break;
    case "Value Proposition":
      $assigned_user = "brockd";
      break;
    case "Id. Decision Makers":
      $assigned_user = "brunettig";
      break;
    case "Perception Analysis":
      $assigned_user = "thanetl";
      break;
    case "Proposal/Price Quote":
      $assigned_user = "wallanderk";
      break;
    case "Negotiation/Review":
      $assigned_user = "dobbsm";
      break;
    case "Closed Won":
      $assigned_user = "bluek";
      break;
    case "Closed Lost":
      $assigned_user = "bluek";
      break;
}

You'll notice from the code that we must use the original SugarCRM sales stage terms and not our new mapping—that only appears on the screen.
Next we'll have to add the code to update $bean->assigned_user_id with the ID of our new user:

global $db;

$sql =
  "select id from users where user_name = '" . $assigned_user ."'";
$result = $db->query($sql);
$bean->assigned_user_id = mysql_result($result,0,0);

With the code in place, if you now change the Investigation (or Sales) stage, and then save the Preliminary Investigation (or Opportunity) then you'll see that the assigned user is automatically updated for you.
However, this is still only a semi-automatic process—the correct person for the stage is selected correctly, but only if the stage is selected manually. The process running correctly still depends on someone telling SugarCRM what that next stage is. Obviously the next step is to move from stage to stage automatically.

Completing the Automated Workflow

At the moment we're relying on a user telling the application which stage to move to next. However, it would be much better for the user to tell SugarCRM that the current stage has been completed, and then for the business rules to decide which stage should be carried out next. We want to keep it simple and therefore an 'Investigation Stage Complete' checkbox will do the job.
If you look at the edit view for any of the existing Opportunities then you'll see that there's nothing that can really be renamed to represent our 'Investigation Stage Complete':

We can use the SugarCRM Studio to add the field that we're going to need:

After adding the custom field itself we'll need to add text for the field label into custom/modules/Opportunities/language/en_us.lang.php:
And then we're ready to see the new edit view:

$mod_strings['lbl_chk_complete_c_10'] = "Investigation Stage 
Completed";

We can now go back to our code (in custom/include/ppi_workflow.php), and we can place all of our functionality within an if statement:

if ( $bean->chk_complete_c == 1 )
{
  switch ($bean->sales_stage)
  {
    /* etc, etc, etc */
  }
}

Our logic hook will, of course, fire every time a save is made—but our business rule will only be implemented if the Investigation Stage Completed box is ticked. So now we need the code that will define the process itself, and you would need to place this before the code for deciding who the assigned user is:

switch ($bean->sales_stage)
{
  case "Prospecting":
    $bean->sales_stage = "Qualification";
    break;
  case "Qualification":
    $bean->sales_stage = "Needs Analysis";
    break;
  case "Needs Analysis":
    $bean->sales_stage = "Value Proposition";
    break;
  case "Value Proposition":
    $bean->sales_stage = "Id. Decision Makers";
    break;
  case "Id. Decision Makers":
    $bean->sales_stage = "Perception Analysis";
    break;
  case "Perception Analysis":
    $bean->sales_stage = "Proposal/Price Quote";
    break;
  case "Proposal/Price Quote":
    $bean->sales_stage = "Negotiation/Review";
    break;
  case "Negotiation/Review":
    $bean->sales_stage = "Closed Won";
    break;
}
//Now decide who the assigned user is...

And finally we need to reset the completed status back to 0:

$bean->chk_complete_c = 0;

You'll notice that we've not taken the process all the way to the final stage—this is because the final two stages are 'Closed won' or 'Closed lost' (in PPI speak—'Full Investigation required' and 'Insufficient Evidence'). Korora will need to make that decision herself.
However, the important thing is that you can see just how easy it is to set up a simple process (not that any process is ever simple).

Summary

Before you start work on your workflow, ensure that: the people who understand the processes in the organization are available to you; both managers and staff agree that the process plan is correct; staff don't feel that the process is being enforced on them; and that this isn't another case of 'Big Brother'.
When you do start building the work flow ensure that you've correctly mapped your organization's stages onto the SugarCRM stages and that you have a complete listing of who does what and when.
Business rules are created by making use of SugarCRM's logic hooks. The logic hook file contains the priority of the business rule, the name of the businesses rule, the file containing the business rule, the business rule class, and the business rule function.