SOAP Intro and Practical Examples

From SugarCRM Wiki

Jump to: navigation, search

Contents

Introduction to SOAP

SOAP stands for "Simple Object Access Protocol." It is used for making Remote Procedure Calls through the HTTP protocol by relaying messages in XML.

Even if you don't necessarily understand all of the acronyms and terminology involved, 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, I am going to assume that we're using PHP in conjunction with the NuSOAP Toolkit...

ATENTION! If your variable site_url in config.php is wrong, soap will not work! Verify it!

Example One - 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");
?>
Example One - Line by Line

Include the NuSOAP code to allow us to construct the soapclient object. 

  require_once('nusoap/nusoap.php');

Instantiate the object with two parameters, the Sugar instances WSDL location and (FIXME)??? 

  $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");


Example Two - Inserting a Lead via SOAP calls using PHP
 <?php
 define('sugarEntry', TRUE);
 //Use the NuSOAP files
 require_once('nusoap/nusoap.php');
 
 $soapclient = new nusoapclient('http://www.example.com/sugar/soap.php?wsdl',true);
 
 $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']);
 
 ?>
Example Three- Login with Error Checking
<? 
function wsLogin($userName, $Password)
{
	
echo "including 
";
require_once('includes/nusoap/nusoap.php');
  
$Connectionstring = 'http://localhost/sugar45f/soap.php?wsdl';
$wsdl="http://localhost/sugar45f/soap.php?wsdl";

$sugar_client = new soapclient($wsdl, true);
echo "get the client 
";
$proxy =  $sugar_client->getProxy();

echo "proxy 
";
$ret =  $proxy->test('OK');
echo "test is: $ret 
";
echo "password conded is: ". md5($Password) . "
";
  
$user_auth = array('user_name' => $userName,
                             'password' => md5($Password),
	                       'version' => "1",    		
	 		      );
			  			
$login_results=  $proxy->login($user_auth, "pipo");
if($login_results['error']['name']=="No Error")
{
         return   $session_id =  $login_results['id'];
}
else
{
         return $login_results['error']['name'];
}

?>

Retrieved from "http://www.sugarcrm.com/wiki/index.php?title=SOAP_Intro_and_Practical_Examples"
Personal tools