Systems Consciousness

This is my third tutorial on the SugarCRM SOAP API. It’s slightly more advanced than the last two, so if you are new to the SOAP API, you should probably start with this one. If you are looking for more tutorials on SugarCRM SOAP API, (as always) LornaJane’s blog is a great intro, and the Sugar Developer Forum is tops. Enough plugs. Let’s get started! (And if you find the post useful, please visit one of my sponsors!)

Today I’m going to write about sending a file attachment to SugarCRM via the SOAP API. The setup, as in previous posts, is a LAMP web server running our main web site on WordPress–and the cForms plugin to process form input data. You don’t need cForms, but it’s a great plugin that will help you manage multiple types of forms on your WordPress site. It also has its own API, which allows you to run PHP code when a form is submitted. If you’re not using WordPress or cForms, that’s ok, too.

I’m going to skew the code for the non-WordPress users. But it will be almost identical if you are using WordPress/cForms. You’ll just need to substitute in the cForms variables. For easy setup, create a simple POST form with text fields of my_form_firstname and my_form_lastname, and with a file field.

We’re going to send a document through the web form on our web server to a Sugar server (which is also a web server, but you get the idea).

To begin, we’ll need to initialize our SOAP connection. This means connect to the Sugar server from our web server with our IP, username and password. The code (again) looks like this:

$location = ‘http://YOUR.SUGARSERVER.WEB.ADDRESS/yoursugarcrmdirectory/soap.php’;

// set up options array with SugarCRM location, etc
$options = array(
“location” => $location,
“uri” => ‘http://www.sugarcrm.com/sugarcrm’,
“trace” => 1
);

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

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

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

$session_id = $response->id;

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

print_r($response);

The last line can be commented out. It’s just there to indicate to you that your connection was successful. If it wasn’t successful, make sure:

• Your username and password are correct.
• The URL for your Sugar server is correct.
• Your user has access to write to the Contacts and Notes modules.
• Your firewall has a web port open.

If it worked, great! Let’s move on to the next step. (If not, hit up Google!) Let’s add data to a module. In this case, we’re going to use the Contacts module because it already has a built-in many-to-many relationship to the Notes module, where our attachment will ultimately reside–linked to our Contact! Here’s the code to write some data to the Contacts module:

$response = $client->set_entry($session_id, ‘Contacts’, array(
array(”name” => ‘first_name’,”value” => $_POST['my_form_firstname']),
array(”name” => ‘last_name’,”value” => $_POST['my_form_lastname']),
array(”name” => ‘assigned_user_id’,”value” => $user_id)
));

Simple enough. When you run this code, combined with the code above, you should find a new contact in your Contacts module. If you get in trouble, var_dump() and print_r() will be your best friends. Our next step will be to grab the uploaded document and insert it into the Notes module:

$insert_contact_id = $response->id;

// create the note
$response = $client->set_entry($session_id, ‘Notes’, array(
array(’name’=>’name’,'value’=>$_POST['my_form_firstname'].’ ‘.$_POST['my_form_lastname'].’ Document’),
array(’name’=>’description’,'value’=>’An attachment for ‘.$_POST['my_form_firstname'].’ ‘.$_POST['my_form_lastname']),
array(’name’=>’parent_type’,'value’=>’Contacts’),
array(’name’=>’parent_id’,'value’=>$insert_contact_id)
));

$note_id = $response->id;

Note the first and last lines. Every time you issue a $response call, that is, when you reference your SoapClient class, you get a new $response->id. This way you can interact with SOAP at different stages in your application. In this instance, first we wrote a new Contact to Sugar, then we’re getting the $response->id of this call to create and attach a Note to the Contact. This occurs in this little bit above:

array(’name’=>’parent_type’,'value’=>’Contacts’),
array(’name’=>’parent_id’,'value’=>$insert_contact_id)

Then, likewise, we get the $note_id, which is the $response->id for the Note attachment.

What we’ve yet to do at this point is get our file from our form and upload it as an attachment to the Notes record that we just created. If you’re not familiar with uploading documents via PHP and forms, then you’ll want to brush up on that. If you’re using cForms especially this will be very helpful because cForms requires you to be a little bit more strict with how you work with files than, say, if you’re just working with your own ground-up app. What I mean is–you need to know what the difference is between tmp_name, name and so forth.

Here we go… we’re going to get the target path of the file, open it to get its content, and then close it:

// get the path from of your file
$target_path = $_FILES['my_form_file']['tmp_name'][0];

// Un-comment this code to see if the file exists
//if (file_exists($target_path)) {
//echo “The file “.$_FILES['my_form_file']['name'][0].” exists”;
//} else {
//echo “The file “.$_FILES['my_form_file']['name'][0].” does NOT exist”;
//}$fp = fopen($target_path, ‘rb’);
$file = base64_encode(fread($fp, filesize($target_path)));
fclose($fp);

Our final step is going to be to attach (and relate) the file to the new record in the Notes module. See what we’re doing? Creating a Contact, relating a Note to it, and relating an attachment to that Note. Exciting! This code is simple. If you are convinced the above is working, proceed by adding this:

//create the attachment that you will put into sugar
$attachment=array(
‘id’=>$note_id,
‘filename’=>$_FILES['my_form_file']['name'][0],
‘file’=>$file
);

$response = $client->set_note_attachment($session_id,$attachment);

By now you should be getting the hang of it. We’re creating an attachment just like we created the other two records. The $note_id variable will tell the attachment record which Note to relate to. The Note, remember, is already attached to our Contact. Then we’re using the set_note_attachment() function to put the attachment on the server.

That’s all there is to it!