Logic Hooks: Lead History Transfer

Have you noticed what happens to history information associated with a lead when one converts that lead into a contact within SugarCRM? 

If not, give it a try. Enter a lead record named John Doe, add a Note under its History section. Next, convert the lead into a contact. Now, take a look at the History section on the new contact record for John Doe that was created via the conversion process and compare it to the History section on the lead record. You will notice that the Note entry is nowhere to be found on the contact record and instead, remains associated with the lead record.

This separation allows us to see which interactions were completed when the individual was a lead and which were completed after it was converted into a contact. In turn, it helps us identify processes and techniques that led us to converting it. 

All future activity relating to that individual would be recorded against the contact record, not the lead. However, many users find that the distinction between lead and contact history causes too much confusion.

One problem that is created by this separation of data is that looking at the History section of a contact does not give us a full picture of everything that has occurred over time, as it relates to the individual. One must toggle between the contact and lead record in order to gather that insight. 

How can we address this problem?

One school of thought would bring us to the conclusion that one should not use the Leads module at all and simply enter everyone as a contact. This would solve the History problem, but creates others, such as the inability to track lead conversion rates. 

A second approach would be to carry over the History data from the lead over to the contact record during the conversion. Doing so would solve the problem as all the History would appear on the contact record, but a facility for this does not exist in SugarCRM. Fortunately, it can be easily accomplished via a logic hook.

Let us take a look at the logic hook we would use.

To begin with, we need the standard logic hook definition which belongs in our logic_hooks.php file. In this case, it will be defined as a before_save hook, with the following code:

<?php

$hook_version = 1; 

$hook_array = Array(); 

$hook_array['before_save'] = Array(); 

$hook_array['before_save'][] = Array(1, 'DataTransfer', 'custom/modules/Leads/DataTransfer.php','DataTransfer', 'doDataTransfer'); 

?>

Alright, but where do we place this file? 

After all, when one converts a lead, more than one module is involved in the process. For example, the process creates a contact and an account, in addition to providing options for creating an opportunity, call and other type of records.

As it turns out, the best place for our logic hook is within the Leads module, thus, we will place the logic_hooks.php file in the custom/modules/Leads folder.

Lastly, we need to create the custom code file that performs the action of unlinking the History entry from the lead record and then links it to the contact. We have named the file DataTransfer.php within our logic hook definition, so this is the name we will use. Here is the content of DataTransfer.php:

<?php

/*************************************

Project: Relation Transfer

Original Dev: Angel Magaña, March 2012

@2012 Angel Magaña

cheleguanaco[at]cheleguanaco.com

Desc: Logic Hook for Transferring Relation

The contents of this file are governed by the GNU General Public License (GPL).

A copy of said license is available here: http://www.gnu.org/copyleft/gpl.html

This code is provided AS IS and WITHOUT WARRANTY OF ANY KIND.

*************************************/

class DataTransfer

{

function doDataTransfer($bean, $events, $arguments)

{

$action = $_REQUEST['action'];

if ($action == 'ConvertLead') //Must confirm it only triggers on conversion!!

{

$lead_id = $bean->id;

$contact_id = $bean->contact_id;

$bean->load_relationship('notes');

//Remove relationship 

$notes = array();

foreach ($bean->notes->getBeans() as $note)

{

$note_id = $note->id;

$notes[] = $note_id;

$bean->notes->delete($lead_id, $note_id);

}

$bean->save();

//Transfer relationship to Contact record

$contact = new Contact();

$contact->retrieve($contact_id);

$contact->load_relationship('notes');

foreach ($notes as $note)

{

$contact->notes->add($note);

}

}

}

}

?>

Note that for the purposes of our example, the code has been simplified a bit so as to only transfer Notes entries. In addition, notice the following lines from above:

$action  = $_REQUEST['action'];

if ($action == 'ConvertLead')

Because the logic hook is defined to trigger upon a save occurring on a lead record, we must be careful to not execute the code, and in turn unlink the Notes records, every time the save button is clicked on a lead. To do this, we must explicitly limit the transfer of the Notes data to only those situations where the save is the result of a conversion. The above referenced lines are used to confirm that by first obtaining the action that is occurring within SugarCRM and secondly, verifying it is the ConvertLead action, which is the one associated with the process we are concerned with.

We will want to place this file in the custom/modules/Leads folder as well. 

Once in place, give it a try by converting a lead with a related note entry in its History section and then check the resulting contact record.