Version 5.2

Web Services

SugarCRM provides Web Services API’s via the NuSOAP PHP implementation of the SOAP protocol. SOAP stands for "Simple Object Access Protocol." It is used for making Remote Procedure Calls through the HTTP protocol by relaying messages in XML.

The SugarSoap API’s are built using the NuSOAP library and included in the Sugar Community Edition, Sugar Professional Edition and Sugar Enterprise Edition. You can view the SugarSoap API’s at:

http://www.example.com/sugar/soap.php

The SugarSoap WSDL (Web Services Description Language) is located at:

http://www.example.com/sugar/soap.php?wsdl

Thanks to a myriad of toolkits available, it is easy to make effective use of SOAP Web Services from a variety of programming languages, in particular with Sugar and its wide array of SOAP-based services that it offers.

For these exercises, we will use PHP in conjunction with the NuSOAP Toolkit. You could of course connect to SugarCRM via SOAP and write your application code in Java, C++ or a variety of other SOAP-enabled programming languages.

Note: If the Sugar config.php variables site_url is wrong, SugarSoap will not work. Be sure to verify this value before continuing.

Test Connection

If you would like to make sure you can connect to the SugarSoap API’S, use this test call. This call will echo whatever you send in.

•	Call: test

•	Arguments:

o	string:string – this is a string that you want to be echoed back to you

•

Results:

o	string:string – this is the string that was sent as an argument.

SugarSoap Login

First you will need to login to the SugarCRM system through the SOAP interface.

•	Call: login

•	Arguments:

o	complex-type:user_auth – contains the user credentials used to log in.

o	string:application_name – this is a unique application name(example: SugarCRM)

•

Results:

o	complex-type: set_entry_result - in this case the id of set_entry_result is the SugarSoap API’s session_id.

•	Note: This session id value is needed in all future SOAP calls. So you will want to store this in a session or application level variable.

New complex types introduced in this section.

•	user_auth is a struct containing three parameters:

o	string:user_name – this is the SugarSoap user name

o	string:password – this is an md5 of the SugarSoap user password

o	string:version – this is the version of SOAP you are expecting(at this point use 1.0)

•	set_entry_result is a struct containing two parameters.

o	string:id - this is the id for the result

o	complex-type:error (error_value) this is the error if any

•	error_value is a struct containing three parameters:

o	string:number - this is the error number. An error number of 0 indicates no errors were encountered

o	string:name – this is the error name

o	string:description – this is the error description

Get the Current User ID

Sometimes it is useful to know the current user id. To get this information returned, call get_user_id.

•	Call: get_user_id

•	Arguments:

o	string:session - this is the session_id retrieved during login that you should have stored in either the application or the session scope

•

Results:

o	string:return – this is the user_id for the current SugarSoap user who logged in

Get a list of records for a module

This will return a list of entries (results) for a list view of a module. Team-based security restrictions determine the resulting set of rows. It should also be noted that only the fields available in the module’s list view is available through the get_entry_list call. Note that restrictions to field access implemented via field-level ACLs (Professional and Enterprise Editions only) do not affect the fields returned.

•	Call: get_entry_list

•	Arguments:

o	string:session – this is the session_id

o	string:module_name – this is the module you wish to get results for (e.g. 'Calls')

o	string:query – this is the search query you wish to apply in retrieving the results (e.g. “(calls.name LIKE 'doctor appointment%' AND calls.date_start = CURDATE())” )

o	string:order_by – this is what you would like to order by for the results (e.g. the database column “calls.name”)

o	complex-type:select_fields – these are the fields you want returned. SugarSoap performance is better if you only retrieve the fields you need (e.g. name, description, date_start, time_start).

o	int:max_results – this is the maximum number of results you want returned if set to 0 it will return the default SugarSoap API’s amount for ListViews.

•

Results:

o	complex-type:get_entry_list_result

New complex types introduced in this section include:

•	select_fields is an array of strings (these are the names of fields for a given module)

•	get_entry_list_result is an struct containing five parameters.

o	int:result_count – the number of results returned

o	int:next_offset – the next offset to use in a request

o	complex-type:field_list – this is meta data of the fields returned

o	complex-type:entry_list – this is the acctual result data

o	complex-type:error (error_value) any errors that occurred

•	field_list is an array of complex-type:field

o	field is a struct containing five parameters.

	string:name – the db/sugar name for a field

	string:type – the type of field (enum, text)

	string:label – the translated label for the field

	int:required – 1 for required 0 for not

•	complex-type:name_value_list – these are additional options such as for enumeration it would be the list of values for the enumeration.

o	name_value_list is an array of complex-type:name_value

	name_value is a struct containing two parameters. This is a name value pair.

•	string:name – the name of the value (a.k.a key)

•	string:value – the value for the name

•	entry_list is an array of complex-type:entry_value

o	entry_value is a struct containing three parameters:

	string:id – the sugar id for the entry

	string:module_name – the module this entry is from

	complex-type:name_value_list – the field values for this entry

Get the values of a record

So we retrieved a list of results for a module but you might need more details on a single record (entry) since get_entry_list is limited to what is available in the list view. You can get this information by retrieving a single entry using get_entry.

•	Call: get_entry

•	Arguments:

o	string:session – the session_id

o	string:module_name – the module for the entry you want to retrieve

o	string:id – the id of the entry you want to retrieve

o	complex-type:select_fields - the fields you want to retrieve

•

Results:

o	complex-type:get_entry_result

 

get_entry_result is a new complex type introduced in this section. It is a struct containing three parameters:

•	complex-type:field_list – this is metadata of the fields returned

•	complex-type:entry_list – this is the actual result data (in this case it will be an array of size 1)

•	complex-type:error (error_value) any errors that occurred

The reason for including entry_list in the same manner as get_entry_list_result is so that the same function can create data structures for both calls.

Set the values for a record

You may want to now modify or even create a new record (entry). This is where set_entry comes into place. Both modifying and creating a record are done from the same function call.

•	Call: set_entry

•	Arguments:

o	string:session – the session_id

o	string:module_name – the module for the entry you want to update/create

o	complex-type:name_value_list - the fields you want to set

•

Results:

o	complex-type:get_entry_result

Pass in the primary id of a record in the name_value_list complex field if you have a field called id otherwise to update a specific record. Otherwise if this field is empty, the system will create a new entry.

Get the fields for a module

If you want to create a record (an entry) but don't have any fields to work with and there are no results in the database, you can get a list of the available fields for a module. You use get_module_fields.

•	Call: get_module_fields

•	Arguments:

o	string:session – the session_id

o	string:module_name – the module that you want a list of fields for

•

Results:

o	complex-type: module_fields – these are the fields to use

module_fields is a new complex type introduced in this section. It is a struct containing three parameters:

•	string:module_name – the module name for the fields

•	complex-type:module_fields - (field_list) – these are the fields

•	complex-type:error (error_value) - any errors that occurred

Logout

You need to clean up your session after you’re done.

•	Call: logout

•	Arguments:

o	string:session – the session_id

•

Results:

o	complex-type:error (error_value) – any errors (not logged in?)

SugarSoap Examples

Every Sugar installation comes with a series of SugarSoap examples located in the examples/ directory of the application installation. There you will find several examples that go beyond those outlined in this section.

Logging in via SOAP and getting a Sugar user's GUID

<?php

require_once('nusoap/nusoap.php');

$client = new soapclient('http://www.example.com/sugar/soap.php?wsdl',true);

$auth_array = array(

'user_auth' => array(

'user_name' => 'bob',

'password' => md5('mysecretpassword'),

)

);

 

$login_results = $client->call('login',$auth_array);

$session_id = $login_results['id'];

$user_guid = $client->call('get_user_id',$session_id);

printf("\n".$auth_array['user_auth']['user_name'].' has a GUID of ' . $user_guid . "\n\n");

?>

 

Now let’s step this example line by line. Including the NuSOAP code sets up the soapclient object.

require_once('nusoap/nusoap.php');

 

Instantiate the object with two parameters, the Sugar instances WSDL location and a flag that you are passing in a WSDL.

$client = new soapclient('http://www.example.com/sugar/soap.php?wsdl',true);

 

Set up a data structure with the data needed to login.

$auth_array = array(

'user_auth' => array(

'user_name' => 'bob',

'password' => md5('mysecretpassword'),

);

 

We know the previous is needed because of the following WSDL snippets (from http://www.example.com/sugar/soap.php?wsdl):

<message name="loginRequest">

<part name="user_auth" type="tns:user_auth"/>

<part name="application_name" type="xsd:string"/>

</message>

 

---and---

<xsd:complexType name="user_auth">

<xsd:all>

<xsd:element name="user_name" type="xsd:string"/>

<xsd:element name="password" type="xsd:string"/>

<xsd:element name="version" type="xsd:string"/>

</xsd:all>

</xsd:complexType>

 

Here is where we actually send the data. We are calling the 'login' SOAP method

$login_results = $client->call('login',$auth_array);

 

Now we grab a session id number

$session_id = $login_results['id'];

 

We know that we should look in 'id' because of the following WSDL snippet:

<message name="loginResponse">

<part name="return" type="tns:set_entry_result"/>

</message>

 

---and---

 

<xsd:complexType name="set_entry_result">

<xsd:all>

<xsd:element name="id" type="xsd:string"/>

<xsd:element name="error" type="tns:error_value"/>

</xsd:all>

</xsd:complexType>

Now that we have a session ID, we can call another SOAP function, get_user_id:

$user_guid = $client->call('get_user_id',$session_id);

And print out some meaningful output with our findings:

printf("\n".$auth_array['user_auth']['user_name'].' has a GUID of ' . $user_guid . "\n\n");

Inserting a Lead via SOAP calls using PHP

This example includes the PHP code necessary to log into the Sugar installation and insert a new Lead record.

<?php

define('sugarEntry', TRUE);

//Use the NuSOAP files

require_once('nusoap/nusoap.php');

// change the URL here to point to your Sugar installation

$soapclient = new nusoapclient('http://www.example.com/sugar/soap.php?wsdl',true);

// change the user credentials below to be a valid user id and password for the Sugar

// installation defined above

$user_auth = array(

'user_auth' => array(

'user_name' => 'bob',

'password' => md5('mysecretpassword'),

'version' => '0.1'

),

'application_name' => 'soapleadcapture');

 

 

 

$result_array = $soapclient->call('login',$user_auth);

$session_id = $result_array['id'];

 

$user_guid = $soapclient->call('get_user_id',$session_id);

// Up until now, we have not introduced anything new

// The following lines will use the set_entry SOAP call to add

// a Lead from a mixture of POST variables and hard coded

// values, then assign to the authenticated Sugar user...

$set_entry_params = array(

'session' => $session_id,

'module_name' => 'Leads',

'name_value_list'=>array(

array('name'=>'first_name','value'=>$_POST['first_name']),

array('name'=>'last_name','value'=>$_POST['last_name']),

array('name'=>'status', 'value'=>'New'),

array('name'=>'phone_work', 'value'=>$_POST['phone']),

array('name'=>'phone_fax', 'value'=>$_POST['fax']),

array('name'=>'account_name','value'=>$_POST['companyname']),

array('name'=>'lead_source','value'=>'Web Site'),

array('name'=>'description','value'=>$_POST['prod_desc']),

array('name'=>'assigned_user_id', 'value'=>$user_guid)));

 

$result = $soapclient->call('set_entry',$set_entry_params);

// this redirects to a page specified in the previous page...

header("Location: " . $_POST['redirect']);

?>

 

 

Note: it is also possible to create a NuSOAP client as follows without requiring the WSDL:

$ soapclient = new nusoapclient('http://www.example.com/sugar/soap.php’,false);

 

This actually speeds up processing since downloading the WSDL before invoking the method is time intensive.