SugarCRM Customization: Custom Workflow E-mails

E-mail has become a popular tool for communication and for a number of purposes.

Within the scope of SugarCRM, the topic usually comes up in relation to the automation of some aspect of a business process, such as alerting a user when a record within the database has been assigned to them.  SugarCRM includes such a feature out of the box, but what if one wanted a bit more flexibility?

Suppose we encounter the following scenario:

Our deployment uses the Leads module to track and qualify potential customers.  Leads enter the system via two different ways: manual entry and web-to-lead.

Entries are required to have an e-mail address or they are not considered valid as our internal process use it for communications and other purposes.  Whenever a new lead is entered, it is automatically assigned to a specific user, who in turn receives an e-mail alerting them of the new record.  However, we want to expand this functionality to also automatically send a generic "Welcome/Thank You For Your Interest" message to the  Lead itself.

How do we go about accomplishing the above?

A simple technique that accomplishes the goal is the use of a logic hook.  (Check out my logic hook primer to learn the basics)

Through the use of a logic hook one can grab the e-mail address of the corresponding lead record and also create the message.  There are two additional techniques this approach teaches us:

1. Sending of e-mail via the Sugar mailer engine
2. Using the XTemplate engine to create the e-mail content

Here is the code that does our magic:

class Welcome {

function sendMessage(&$bean, $event, $arguments)

{
     require_once('include/SugarPHPMailer.php');
     $welcome_msg = new SugarPHPMailer();

     //Grab the Lead's Status (only send if Status = New)
     $status = $bean->status;

     //Set the TO name and e-mail address for the message
     $rcpt_name = $bean->first_name . ' ' . $bean->last_name;
     $rcpt_email = $bean->email1;

     //Set RCPT address
     $welcome_msg->AddAddress($rcpt_email, $rcpt_name);

     //Setup template
     require_once('XTemplate/xtpl.php');
     $xtpl = new XTemplate('custom/modules/Leads/WelcomeMessage.html');

     //Check the status on record
     if ($status == 'New')
     {
          //Send welcome msg to Lead
          $template_name = 'Lead';

          //Assign values to variables in template
          $xtpl->assign('EMAIL_ADDY', $rcpt_email);
          $xtpl->parse($template_name);

          $welcome_msg->Body = from_html(trim($xtpl->text($template_name))); 
          $welcome_msg->Subject = 'This is my test subject';
          $welcome_msg->prepForOutbound();
          $welcome_msg->setMailerForSystem();
          $welcome_msg->From = 'from_sample@example.com';
          $welcome_msg->FromName = 'Sample User';

          //Send the message, log if error occurs
          if (!$welcome_msg->Send())
          {
               $GLOBALS['log']->fatal('Error sending e-mail: ' . $welcome_msg->ErrorInfo);
          }
     }
 }

}

OK, that is the logic that creates and sends the message, but what about the actual content of the message?

That is contained in the WelcomeMessage.html file referenced in the above code.  Its content is included below:

<!-- BEGIN: Lead -->

Thank you for your inquiry and interest in our services.
{EMAIL_ADDY}
<!-- END: Lead -->

Notice that the template is rather simple, but clearly demonstrates how one is created and in turn, how one can merge SugarCRM data into it via the XTemplate engine.