SugarCRM Cookbook: Adding Leads via SOAP

bvdservices.com

Back in 1996 when I first got my start in the CRM world, I remember how impressed I was by a new feature about to roll out in an upcoming release of our software. It was something called "web import," which allowed web site visitors to enter information on a standard web form and the submitted data would then appear in the CRM system without any further user intervention. It was the early days of leveraging the web as a lead generation tool and this feature was nothing short of magical.

Nowadays, it is not so magical and is a standard feature in many CRM packages. In SugarCRM, it manifests itself as something aptly named Web-To-Lead. Through this feature, one can create a web form to embed in a company web site, with the necessary behind the scenes magic that allows for the data to automatically enter the SugarCRM system as a lead.

The drawback of this automated approach is that the resulting web form usually requires some fine tuning in order to seamlessly incorporate it into a company web site. For example, colors, fonts and other cosmetic aspects will likely need some adjustment. If you are using a Content Management System (CMS) such as Drupal or Joomla!, other challenges are likely to present themselves in the process. 

But all this means is that one might need to use a different approach to get the job done and sure enough, SugarCRM provides another method for entering data, more specifically, an Application Programming Interface (API). Through it, one can communicate with SugarCRM to read or write data, among various other things. 

There are two built-in APIs for SugarCRM, one is SOAP based and the second uses REST. The finer details of each are beyond the scope of this post, but for our purposes, we will focus on SOAP and the point that both allow us to interact with SugarCRM in a much more controlled manner, using a wide range of programming languages common to the web world. 

Leveraging the API gives us greater control than the auto-generated form by allowing us full control over which fields are to be populated. Further to this, it allows us to access any part of SugarCRM, opening up the possibility of performing additional tasks at the time the lead enters the system, such as scheduling a follow up call, attaching a document or numerous other things. Lastly, it is also makes it possible for us to build the form using whichever method is already in place for creating the web site and simply tie it to the API -- it is automatically seamless.

So, how do we go about creating a lead via SOAP? Lets take a look. 

This example will assume we are needing to use PHP to write the data to SugarCRM. Three files are involved in the process: lead_soap.php, nusoap.php and soap_config.php. 

All of the files are available for download from my personal site. You should download them now and open the PHP files contained in the zip archive using your text editor of choice. The rest of this post will discuss the role of each file and how to use them.

lead_soap.php:

This file is the heart of it all. It contains the code that connects to SugarCRM via SOAP and inserts the data into the system. It is important to understand the manner in which one establishes a connection to SugarCRM as well as the manner in which the data is to be prepared. You can see this in line 27 and 36 - 49 respectively. 

Should you wish to modify the code to insert the data into a different module (yet another example of the greater control the API gives us), you can do so by changing the module name in line 38. Module names are case sensitive in some scenarios, so always use the matching case. Also, note that he field list defined in line 36 may also need to be updated to correspond with field names from whichever other module to which you choose to write the data.  

Most of your edits will likely be applied to the section that begins on line 31, where the data is captured from the form, as well as the aforementioned section of code beginning on line 36 that prepares the data for delivery to SugarCRM.

nusoap.php

This is a commonly used SOAP client for PHP. More information is available at the official project page on Sourceforge. For our purposes, all we need to know about this file is that it is used to provide the communication layer to SOAP. There is no need to modify this file.

soap_config.php

This file contains the information pertaining to the SugarCRM instance we wish to connect to, such as the user name and password to use. Update all three variables it contains with those corresponding to your specific needs.

Once you have made the necessary updates to the files, you are ready to put them into action. 

To do so, simply place all three files into the same directory/folder within the file system structure of your web site. It does not matter where you put them, so long as all three are in the same directory/folder and they can be accessed by your web server. 

Lastly, the Submit action on the form that will be used to collect the data should be connected to the file lead_soap.php. Once everything is in place you should be able to visit the form on your web site, submit some data and have it appear in the Leads module as a new record.

Download away and try it out!