Systems Consciousness

If you use SugarCRM, one thing that you’ll inevitably need in this time of integrating web services, platforms and devices is the ability to send data from a web form into SugarCRM. You can use SOAP for this, and it works well, for the most part. But you’ll find there are very few good examples out there on the web to really clarify and demystify a clean SugarCRM/SOAP implementation.

The best example I have found is here: http://www.lornajane.net/posts/2008/SugarCRM-SOAP-API-Examples. LornaJane’s examples were an excellent start, and I thought I’d go ahead and provide you some more details. The upside of these examples is that you won’t need to install nusoap in order for them to work. If you like what you see, and you want to see more, please consider visiting one of our sponsors. Each click makes us a few cents.

Setup: LAMP web server running the latest version of WordPress with tons of plugins and customization. I also use cForms. It’s not important that you are using WordPress or that you have cForms installed. I just happen to like cForms, and I think it’s a fun challenge to integrate all these different systems. If you do use WP and cForms, just follow the instructions in the cForms documentation for customizing my-functions.php in your plugins/cforms-custom directory. The only real difference will be that you will use $POSTdata['varname'] instead of the regular $_POST['varname']. You’ll also need to use stripslashes() and pay attention to the variable names that cForms passes. I won’t be going into the specific details of cForms-to-SugarCRM here, but you should be able to infer how to implement that from this explanation.

This example uses a simple web form POST calling a PHP document as an action. For simplicity, let’s assume you have a web form with the following fields: first_name, last_name, email_address, phone_number and message.

When you submit the form, it calls “form-action.php”. You will implement the examples here in this PHP file.

Getting Started

To get started, let’s just get a basic example going. Copy and paste the following code in your form-action.php document. If you want to look at the SugarCRM documentation for these SOAP calls, go here: http://sugarcrm.openapp.org/2006/04/24/using-sugarcrm-soap/ Part of the reason I’m writing this post is because they don’t provide any examples for these calls. Once you get the hang of it though, that link will be quite helpful to you.

<?php

// set up options array
$options = array(
“location” => ‘http://your.website.here/sugarcrm/soap.php’,
“uri” => ‘http://www.sugarcrm.com/sugarcrm’,
“trace” => 1
);

//user authentication array
$user_auth = array(
“user_name” => ‘YOUR_SUGAR_USERNAME’,
“password” => MD5(’YOUR_SUGAR_PASSWORD’),
“version” => ‘.01′
);

// connect to soap server
$client = new SoapClient(NULL, $options);

// Login to SugarCRM
$response = $client->login($user_auth,’test’);

$session_id = $response->id;

// look what modules sugar exposes
$response = $client->get_available_modules($session_id);

// look in more detail at the fields in a module
//$response = $client->get_module_fields($session_id, ‘Accounts’);

var_dump($response);

?>

So what’s going on here? Your options array is storing some variables that you’ll use a few lines later in the SoapClient call. The options array is where you specify the connection parameters to the server that has your SugarCRM installation. Naturally, you’ll want to make sure you enable port 80 access through your router/firewall because that’s the default port for HTTP and also SOAP. The next array of interest is $user_auth, which is where you specify your user name, password and SOAP version. After that you pass the connection options into the SoapClient() call and then log in via the login() call. The ‘test’ parameter is a required application name, which can be most anything you want to call it. Once you pass the authentication, the $session_id variable grabs the session id for your current SOAP connection. You’ll need this with most, if not all, calls that you make from this point forward.

The next few lines of code are the fun part. The “$response = $client->get_available_modules($session_id);” line is grabbing all of the modules in your SugarCRM installation. This is very useful, for instance, when you want to know if the particular module you are attempting to write to is exposed. It’s also helpful when you’re trying to debug your SOAP calls and you’ve used the wrong module name, and so on. Below that is another example call that, if you uncomment the line, will return all of the fields that are exposed in a specific module, in this example–Accounts. Finally, var_dump($response) echos out whatever your $response variable has collected above.

Play around with it and get a feel for how it works. Notice that any custom modules you create show up in the list of available modules. Notice also that some modules, like Users, don’t return any available fields at all.

Inserting a Record

Now that you’ve made your first SOAP call to SugarCRM, you’ll want to try to insert a record or two into a module. This, like the previous example, is pretty simple and straight forward, but there are a few quirks like anything else in SugarCRM.

Let’s take the previous example to the next level. Under your $session_id variable declaration, add this line: “$user_id = $client->get_user_id($session_id);” You’ll need this eventually to assign a given record to a user. In this case we’re going to use the authenticated user’s id. Now the fun part! Remove or comment out the get_available_modules and get_module_fields lines and replace them with this:

$response = $client->set_entry($session_id, ‘Leads’, array(
array(”name” => ‘first_name’,”value” => $_POST['first_name']),
array(”name” => ‘last_name’,”value” => $_POST['last_name']),
array(”name” => ‘email1′,”value” => $_POST['email_address']),
array(”name” => ‘work_phone’,”value” => $_POST['phone_number']),
array(”name” => ‘description’,”value” => $_POST['message']),
array(”name” => ‘assigned_user_id’,”value” => $user_id)
));

Here, we’re inserting the data passed from our form into the Leads module in SugarCRM. One thing you may notice instantly is that some of the variable names for the SugarCRM module have different names than the POSTed variables from our form. The email address, for instance, gets inserted into the email1 field for SugarCRM. This is because SugarCRM has its own way of dealing with multiple (primary, secondary, etc.) email addresses. The $_POST['message'] variable is being inserted into the description field in the Leads module for simplicity because SugarCRM includes a description field in this module by default. The last line inserts the authenticated user’s id into the record and associates your new Lead with this user. This can be really helpful, say, if you have a team of people using SugarCRM to correspond with clients, and each person deals with a different type of incomming Lead. Your form-action.php file should now look something like this:

<?php

// set up options array
$options = array(
“location” => ‘http://your.website.here/sugarcrm/soap.php’,
“uri” => ‘http://www.sugarcrm.com/sugarcrm’,
“trace” => 1
);

//user authentication array
$user_auth = array(
“user_name” => ‘YOUR_SUGAR_USERNAME’,
“password” => MD5(’YOUR_SUGAR_PASSWORD’),
“version” => ‘.01′
);

// connect to soap server
$client = new SoapClient(NULL, $options);

// Login to SugarCRM
$response = $client->login($user_auth,’test’);

$session_id = $response->id;
$user_id = $client->get_user_id($session_id);

// write our form data to the Leads module
$response = $client->set_entry($session_id, ‘Leads’, array(
array(”name” => ‘first_name’,”value” => $_POST['first_name']),
array(”name” => ‘last_name’,”value” => $_POST['last_name']),
array(”name” => ‘email1′,”value” => $_POST['email_address']),
array(”name” => ‘work_phone’,”value” => $_POST['phone_number']),
array(”name” => ‘description’,”value” => $_POST['message']),
array(”name” => ‘assigned_user_id’,”value” => $user_id)
));

var_dump($response);

?>

When you execute this code, you get something that looks like this:

object(stdClass)#61 (2) { ["id"]=> string(36) “7e084ce3-8ccb-1a73-4e82-49df645ff06a” ["error"]=> object(stdClass)#58 (3) { ["number"]=> string(1) “0″ ["name"]=> string(8) “No Error” ["description"]=> string(8) “No Error” } }

Believe it or not, this means it worked. More evidence that it worked will be when the record pops up in your SugarCRM Leads module and you scream eureka and everyone in your office turns around to stare at you. When you’re ready to publish your form to a live website, just comment out the var_dump line and add something like, echo “Your form worked, and I’m awesome.”;.

Relating Two Records in Different Modules

This example was a little tricky to figure out, but ultimately it’s pretty simple. You will inevitably need to relate a record with another record, say, for example, if you’re using the ITHelpDesk module created by the good folks at StoryCorps. You could easily create a web form for your users to enter a support request on your company’s intranet site and have it go straight into the ITHelpDesk module. You’d just need to backtrack through these examples a bit to get the right module and field names, and then tweak the examples provided herein to write the appropriate data to the appropriate places. Then you could append the following bit of code to associate, say, the Support record with the Inventory record as its entered into SugarCRM.

But for simplicity sake, we’re just going to create an Account record and a Contact record and relate them instead of creating a Lead. Start by adding another field to your form, called organization_name. Then refer back to the previous example and edit the Leads insert example to insert into the Contacts table instead. Copy and paste the Contacts $response insert lines and modify it to add a record to the Accounts table. For this part, just add the organization_name variable to the Accounts module, which is stored as the “name” field in SugarCRM. If you stop at this point, you’ll just have a new account and a new contact in SugarCRM, but they won’t be related. They also won’t be related if you just put the organization_name in as the associated account in your Contacts $response insert. Don’t waste your juice trying to do this. Instead, you’ll need this little bit of code, which you’ll insert after your two $response inserts:

$relationship = array(
‘module1′ => ‘Contacts’,
‘module1_id’ => “$contact_id”,
‘module2′ => ‘Accounts’,
‘module2_id’ => “$account_id”,
);

// call set_relationship()
$response = $client->set_relationship($session_id, $relationship);

Pretty simple, right? This won’t work without the $contact_id and $account_id variables though, so you’ll need to call $contact_id = $response->id and $account_id = $response->id after each of your $response inserts. The final result will look something like this:

<?php

// set up options array
$options = array(
“location” => ‘http://your.website.here/sugarcrm/soap.php’,
“uri” => ‘http://www.sugarcrm.com/sugarcrm’,
“trace” => 1
);

//user authentication array
$user_auth = array(
“user_name” => ‘YOUR_SUGAR_USERNAME’,
“password” => MD5(’YOUR_SUGAR_PASSWORD’),
“version” => ‘.01′
);

// connect to soap server
$client = new SoapClient(NULL, $options);

// Login to SugarCRM
$response = $client->login($user_auth,’test’);

$session_id = $response->id;
$user_id = $client->get_user_id($session_id);

// write our form data to the Contacts module
$response = $client->set_entry($session_id, ‘Contacts’, array(
array(”name” => ‘first_name’,”value” => $_POST['first_name']),
array(”name” => ‘last_name’,”value” => $_POST['last_name']),
array(”name” => ‘email1′,”value” => $_POST['email_address']),
array(”name” => ‘work_phone’,”value” => $_POST['phone_number']),
array(”name” => ‘description’,”value” => $_POST['message']),
array(”name” => ‘assigned_user_id’,”value” => $user_id)
));

$contact_id = $response=>id;

// write our form data to the Accounts module
$response = $client->set_entry($session_id, ‘Contacts’, array(
array(”name” => ‘name’,”value” => $_POST['organization_name']),
array(”name” => ‘assigned_user_id’,”value” => $user_id)
));

$account_id = $response=>id;

$relationship = array(
‘module1′ => ‘Contacts’,
‘module1_id’ => “$contact_id”,
‘module2′ => ‘Accounts’,
‘module2_id’ => “$account_id”,
);

// call set_relationship()
$response = $client->set_relationship($session_id, $relationship);

//var_dump($response);

?>

Now if neither of us has made any blunders you should have a working web-to-SugarCRM form that creates a related Account record and a Contact record, both of which are assigned to the authenticated user. Clearly this is very useful technology because it allows your team to respond to web inquiries directly from SugarCRM. With creative use of such modules as the Google Calendar connector (which works, but you can’t uninstall it after you run a Repair or upgrade), you can do some pretty creative stuff to cut down on extraneous software and procedures.

Long live integration! And good luck!