Lead Generation Forms with WordPress and SugarCRM

It took me quite some time to get around this, but I finally managed to get it working. As you might have heard, SugarCRM has a Community Edition, which is open source and free of charge. It’s a very neat tool to play with and it’s functionality will suit most SMEs and maybe some corporations.

I started playing with Sugar a few months ago, mostly with the modules functionality. Cannot compare it to Sales Force, but it’s quite flexible, as each module is customizable. If not within the built-in visual editor (Studio), then within the php sources in the modules directory of a SugarCRM installation. I managed to get some customized modules for real estate and took a few attempts to create a project management module.

Anyways, a few days ago I decided to take it outside Sugar and see what their Web Services are like. I was quite amazed at the flexibility there too. You can literally access any piece of information that’s inside the Sugar database, via quite simple to form SOAP requests. So today I’d like to show you how to construct a basic Lead Generation Form, and for the fun of it, let’s hook it up to WordPress.

If you’re a sales guy, you probably know what leads are. If you’re not, I’ll explain my understanding of it. A lead is a subset of information details about somebody, who in some way or another, is interested in your product or service. The minimum set for a lead would be a name and a phone number or an e-mail address. The maximum could be the inquiry description, budget, tonnes of contacts and more. Once a lead is processed and the person inquiring is still interested (perhaps after a phone call), it’s converted into an Opportunity, and that’s why there are Leads and Opportunities in basically every CRM system.

So, if you’re a business and you have a website, you probably have an inquiry form there somewhere. That inquiry form would be your Lead Generation form, which probably sends an e-mail to your backoffice, who parses the request and inputs it into the CRM, after which your sales team starts working on it. What a massive waste of time! Oh and by the way, e-mail was invented in 1965. Whaa? Come on, you gotta do better than this! I wonder if anybody has this tuned around Twitter accounts. It would be nice to get a DM when a new lead arrives.

Make sure you have a copy of SugarCRM installed somewhere. Locally will do. As I already mentioned, the SugarCRM Web Services works via the SOAP protocol, both to read and write data. But before we proceed, let’s build very a simple contact form somewhere in your WordPress theme files (sidebar maybe?):

<form method="POST">
	<label>First name:</label><input type="text" name="first_name" /><br />
	<label>Last name:</label><input type="text" name="last_name" /><br />
	<label>E-mail:</label><input type="text" name="email" /><br />
	<label>Message:</label><input type="text" name="message" /><br />
	<input type="hidden" name="lead-generation-form-submit" value="1" />
	<input type="submit" />
</form>

I guess there’s no reason to explain the code above, it’s more than straightforward ;)

Next, let’s prepare a short form processor where we’ll squeeze in the Sugar functions at a later stage. To keep it as simple as possible let’s just add a new action to the ‘init’ level where we could check for the existance of our POST data. Put this in your theme functions.php:

add_action('init', 'my_form_processor');
function my_form_processor() {
	if (isset($_POST['lead-generation-form-submit'])) {
		// Process data here
	}
}

The “Process data here” part is the one where people usually send the e-mail with the form data. We’ll put some Sugar there instead ;)

In order to work with the Sugar Web Services we’ll use the NuSOAP Web Services Toolkit for PHP, which is an open source library hosted at SourceForge. The choice is based on what is shipped with the SugarCRM CE bundle, so you can go ahead and just copy the whole nusoap directory from the include folder in Sugar, just note that they add an extra line at the very beginning of their files. You can remove them if you like, otherwise just define what they’re asking for at the beginning of your functions.php:

define('sugarEntry', true);

Let’s create a directory in your WordPress theme and call it “sugar”. Put the nusoap folder inside that directory and we’re almost ready to go.

Now, the next part is the tricky one, where you actually have to deal with SOAP and Sugar (soap and sugar, haha!). To make things simpler, I wrapped the functions I used into a tiny class which could then be extended based on your needs. In order to create a new lead we will need two functions. One to authenticate (login), which returns a session string that should be used for the other requests. The second one to create the new lead (createLead), which accepts a data array and returns the result of the SOAP request.

I also wrote a class constructor which stores the access credentials provided and initiates a new SOAP client, and don’t forget to include the NuSOAP library. Here’s the full code of my sugar.php file:

require_once('nusoap/nusoap.php');

// Wrapper class for SugarCRM Web Services
class SugarCRMWebServices {
	// Let's define a place to store our access credentials
	var $username;
	var $password;

	// We'll store the session ID here for later use
	var $session;

	// We'll initialize a new NuSOAP Client object into this one
	var $soap;

	// Constructor (PHP4-style)
	function SugarCRM($username, $password)
	{
		// Copy the credentials into our containers and initialize NuSOAP
		$this->username = $username;
		$this->password = $password;
		// Replace the URL with your copy of SugarCRM
		$this->soap = new nusoapclient('http://localhost/sugarcrm/soap.php');
	}

	// Login function which stores our session ID
	function login()
	{
		$result = $this->soap->call('login', array('user_auth' => array('user_name' => $this->username, 'password' => md5($this->password), 'version' => '.01'), 'application_name' => 'My Application'));
		$this->session = $result['id'];
	}

	// Create a new Lead, return the SOAP result
	function createLead($data)
	{
		// Parse the data and store it into a name/value list
		// which will then pe passed on to Sugar via SOAP
		$name_value_list = array();
		foreach($data as $key => $value)
			array_push($name_value_list, array('name' => $key, 'value' => $value));

		// Fire the set_entry call to the Leads module
		$result = $this->soap->call('set_entry', array(
			'session' => $this->session,
			'module_name' => 'Leads',
			'name_value_list' => $name_value_list
		));

		return $result;
	}
}

When you’re done with this, go back to your functions.php and find the “Process data here” comment which we left. The code below shows how to create a new lead when the form is posted:

// Process data here

// Load and initialize our sugar object
require_once('sugar/sugar.php');
$sugar = new SugarCRMWebServices('username', 'password');

// Login  and create a new lead
$sugar->login();
$result = $sugar->createLead(array(
	'lead_source' => 'Web Site',
	'lead_source_description' => 'Inquiry form on the website',
	'lead_status' => 'New',
	'first_name' => $_POST['first_name'],
	'last_name' => $_POST['last_name'],
	'email1' => $_POST['email'],
	'description' => $_POST['message']
));

That’s about it! You might be wondering where I got hold of all the field names, such as lead_source, etc. Well, some of them are quite obvious. Open up your SugarCRM, browse to the Admin panel and select Studio from Developer Tools. Pick Leads from the tree view on your left and select Fields. Most of the fields are there with their names, data types and labels, so feel free to add some extra input forms on your website, such as a phone number, etc.

Other fields, such as the email1 field I used above are pretty tricky to find. Open up your SugarCRM sources, browse to the modules directory and open up Leads. You’ll find a file called vardefs.php there. If you read carefully through that file, you’ll notice that all fields are there, even the ones hidden from the Studio.

You might also want to edit the Lead module and add an extra field or two to suit your needs, for instance a Website URL. Don’t forget to save and deploy. For more information visit the Sugar Developer Zone for some great Tools and Tutorials on SugarCRM tuning and customization.

That’s about it I guess! Don’t forget to give your form a good look (Web Form Design: Modern Solutions and Creative Ideas by Smashing Magazine) and of course descriptive and good looking error messages (Error Messages Design Showcase by SmileyCat.com).