Astuces:SOAP

Un article de Wiki CRM-France.

Jump to: navigation, search

Sommaire

Fonctionnement de SOAP pour développer de nouveaux connecteurs

Descriptif du document

Ce document décrit le fonctionnement de la couche SOAP au sein de SugarCRM et permettra aux développeurs de mieux appréhender celle-ci afin de réaliser des connecteurs pour échanger à partir de flux XML. Tout langage peut être utilisé du moment qu’il est capable de réaliser une connexion distante ainsi que de traiter les résultats en XML. Ce document n’a pas pour but d’être exhaustif mais uniquement de présenter quelques fonctions permettant de réaliser une connexion SOAP puis de demander un listing.

Pré-requis

  • Disposer de SugarCRM installé sur votre machine ou sur un serveur
  • Disposer d’une classe qui gère le XML tel nuSOAP en PHP est un plus qui facilitera grandement le travail du développeur.

Vérifier la disponibilité du serveur SugarCRM

Soap_test.xml

Fichier XML envoyé pour connaître l’état du serveur et ainsi tester sa disponibilité. En paramètre(s) d’entrée :

  • <string> : « Server Available »
Agrandir

Soap_testResponse.xml

Fichier XML reçu En paramètre(s) de sortie :

  • <return> : « Server Available »
Agrandir

Identification sur le serveur SugarCRM

Soap_login.xml

Fichier XML envoyé pour ouvrir une session sur l’application. En paramètre(s) d’entrée :

  • <user_auth>
    • <user_name> : login utilisateur
    • <password> : mot de passe utilisateur (MD5)
    • <version> : .1
  • <application_name> : SugarWap (En fait le nom de votre appli)
Agrandir

Soap_loginResponse.xml

Fichier XML reçu En paramètre(s) de sortie :

  • <id> : ID de session
Agrandir

Récupération de l’identifiant de l’utilisateur

Soap_get_user_id.xml

Fichier XML envoyé pour récupérer l’ID de l’utilisateur En paramètre(s) d’entrée :

  • <session> : ID de session
Agrandir

Soap_get_user_idResponse.xml

Fichier XML reçu En paramètre(s) de sortie :

  • <return> : ID de l’utilisateur
Agrandir

Listing d’un module trié et filtré

Soap_get_entry_list_Search.xml

Fichier XML envoyé pour récupérer une liste d’enregistrement pour un module donné En paramètre(s) d’entrée :

  • <session> : ID de session
  • <module_name> : Nom du module (contacts)
  • <query> : Condition « where » de la requête que Sugar va opérer sur la base
  • <order_by> : Champ « order by » de la requête pour trier les résultats
  • <offset> : Correspond au « LIMIT x, 10 » du SQL
  • <select_fields> <item> : Champs à retourner
  • <max_results> : Nombre max d’enregistrements à retourner
  • <deleted> : enregistrements supprimés à retourner 0 ou 1
Agrandir

Soap_get_entry_listResponse_Search.xml

Fichier XML reçu En paramètre(s) de sortie :

  • Les paramètres de sortie sont dépendants de ce que vous avez demandé en entrée
Agrandir

Exemple des fichiers XML envoyés/reçus

Si vous avez besoin de ces fichiers d’exemple vous pouvez contacter Synolia directement ou faire une demande sur le forum http://forum.crm-france.com.

Que se passe t’il réllement pour les puristes

Vous pouvez tester en telnet sur le port 80 afin de mieux visualiser l’échange de données. Contenu XML envoyé : 

$ telnet sugarcrm.crm-france.com 80
POST /soap.php HTTP/1.1
Host: sugarcrm.crm-france.com
Content-Length: 510
Content-Type: text/xml; charset=ISO-8859-1
  
<?xml version="1.0" encoding="ISO-8859-1"?><SOAP-ENV:Envelope SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body><ns6606:test xmlns:ns6606="http://tempuri.org">
<string xsi:type="xsd:string">Hello SynoliaUser</string></ns6606:test></SOAP-ENV:Body></SOAP-ENV:Envelope>

En premier lieu il y a donc connexion au serveur, puis nous précisons qu’il s’agit de la méthode POST sur l'url /soap.php du serveur et en HTTP 1.1. Les normes du protocole http demandent alors de préciser au moins un host, la taille du contenu qui suit, et le charset (type de codage des caractères).

Contenu XML reçu : 

HTTP/1.1 200 OK
Date: Wed, 10 May 2006 10:07:20 GMT
Server: Apache
X-Powered-By: PHP/4.3.10-16
X-SOAP-Server: NuSOAP/0.7.2 (1.16)
Content-Length: 514
Content-Type: text/xml; charset=ISO-8859-1

<?xml version="1.0" encoding="ISO-8859-1"?><SOAP-ENV:Envelope SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body><ns1:testResponse xmlns:ns1="http://tempuri.org">
<return xsi:type="xsd:string">Hello SynoliaUser</return></ns1:testResponse></SOAP-ENV:Body></SOAP-ENV:Envelope>

Connection closed by foreign host.

On peut voir qu’il y a bien eu réponse à la demande de test de connexion. La réponse se fait en HTTP 1.1, le code 200 indique que le serveur web (Apache) n’a rencontré aucun problème pour le traitement de cette demande, quelques infos supplémentaires sont données et surtout la taille en octet de la réponse, ainsi que le charset.

La connexion se ferme au bout d'une seconde d'inactivité car nous sommes sur un protocole http donc déconnecté.

Si vous avez besoin d’aide

Le site CRM-France et le forum sont là pour vous aider : http://www.crm-france.com

Liens utiles :

Sources :

Initialisation du document par http://www.go-mobile.at

SYNOLIA, premier partenaire européen de SugarCRM et membre de l’équipe de développement SugarCRM, fournit des solutions CRM et e-business pour tous types d’entreprises. SYNOLIA accompagne les clients SugarCRM, quelque soit la version choisie, dans les phases de mise en place, développements de modules, formations (SYNOLIA est déclaré organisme de formation), maintenance... et propose également des solutions d'hébergement de SugarCRM. SYNOLIA accompagne déjà de nombreux clients SugarCRM en France et en Europe francophone. SYNOLIA a été fondé en 2004 par des professionnels du CRM et de l’ebusiness. La société a son siège à Lyon (France) et peut être jointe par mail à sugar@synolia.com ou par le biais de ses sites Internet http://www.synolia.com, http://ww.crm-france.com (site de la communauté SugarCRM en France) et http://www.businesshop.com

OVERVIEW OF USING SUGARCRM SOAP

The SugarCRM SOAP interface is designed with simplicity in mind. This document is an initial overview to using the SugarCRM SOAP API’s.


STEP 0: TEST

If you would like to make sure you can connect to the SugarCRM SOAP API’S, use this test call. This call will echo whatever you send to it.
call: test
arguments:

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

results:

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


STEP 1: LOGIN

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

complex-type:user_auth
string:application_name – this is a unique application name

results:

complex-type: set_entry_result

note:

in this case the id of set_entry_result is the SugarCRM SOAP API’s session_id. This will be used in all future calls. So you will want to store this in a session or application level


New complex types introduced in this step
user_auth

is a struct containing 3 parameters
parameter 1: string:user_name – this is the SugarCRM SOAP user name
parameter 2: string:password – this is an md5 of the SugarCRM SOAP user password
parameter 3: string:version – this is the version of soap you are expecting


set_entry_result

is a struct containing 2 parameters
parameter 1: string:id -this is the id for the result
parameter 2:complex-type:error(error_value) this is the error if any


error_value

is a struct containing 3 parameters
parameter 1: string:number - this is the error number
parameter 2: string:name – this is the error name
parameter 3: string:description – this is the error description


an error number of 0 indicates no errors were encountered


STEP 2: 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:

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

results:

strung:return – this is the user_id for the current SugarCRM SOAP user who logged in during step 1



STEP 3: GET THE LIST RESULTS FOR A MODULE

This will return a list of entries (results) for a list view of a module. Full row level security restrictions apply in terms of who can access what data in the system. It should also be noted that only the fields available in the module’s list view is available through the get_entry_list call.
Call: get_entry_list
arguments:

string:session – this is the session_id
string:module_name – this is the module you wish to get results for (e.g. 'Calls')
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())” )
string:order_by – this is what you would like to order by for the results
(e.g. “calls.name”)
complex-type:select_fields – these are the fields you want returend
(it is faster if you only retrieve the fields you need)
(e.g. Name, description, date_start, time_start)
int:max_results – this is the maximum number of results you want returned if set to 0 it will return the default SugarCRM SOAP API’s amount for listviews

results:

complex-type: get_entry_list_result



New complex types introduced in this step
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 5 parameters
parameter 1: int:result_count – the number of results returned
parameter 2: int:next_offset – the next offset to use in a request
parameter 3:complex-type:field_list – this is meta data of the fields returned
parameter 4:complex-type:entry_list – this is the acctual result data
parameter 5:complex-type:error (error_value) any errors that occurred


field_list

is an array of complex-type:field


field

is an struct containing 5 parameters
parameter 1: string:name – the db/sugar name for a field
parameter 2: string:type – the type of field (enum, text)
parameter 3:string:label – the translated label for the field
parameter 4: int:required – 1 for required 0 for not
parameter 5:complex-type:name_value_list – these are additional options such as for enumeration it would be the list of values for the enumeration.

name_value_list

an array of complex-type:name_value


name_value

a struct containing 2 parameters this is a name value pair
parameter 1: string:name – the name of the value (a.k.a key)
parameter 2: string:value – the value for the name


entry_list

an array of complex-type:entry_value


entry_value

a struct containing 3 parameters
parameter 1: string:id – the sugar id for the entry
parameter 2: string:module_name – the module this entry is from
parameter 3: complex-type:name_value_list – the field values for this entry



STEP 4: GET THE FULL RESULTS FOR AN ENTRY

So we retrieved a list of results for a module but you might need more details on a single 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:

string:session – the session_id
string:module_name – the module for the entry you want to retrieve
string:id – the id of the entry you want to retrieve
complex-type:select_fields - the fields you want to retrieve

results:

complex-type: get_entry_result


New complex types introduced in this step
get_entry_result

is a struct containing 3 parameters
parameter 1:complex-type:field_list – this is meta data of the fields returned
parameter 2:complex-type:entry_list – this is the acctual result data (in this case it will be an array of size 1)
parameter 3: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


STEP 5: SET THE VALUES FOR AN ENTRY

You may want to now modify or even create a new 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:

string:session – the session_id
string:module_name – the module for the entry you want to update/create
complex-type:name_value_list - the fields you want to set

results:

complex-type: get_entry_result




ass 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. It's that easy.


STEP 6: SET THE VALUES FOR AN ENTRY

If you want to create 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:

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

results:

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



New complex types introduced in this step
module_fields

is a struct containing 3 parameters
parameter 1:string:module_name– the module name for the fields
parameter 2:complex-type:module_fields(field_list) – these are the fields
parameter 3:complex-type:error (error_value) any errors that occurred


STEP 7: LOGOUT

You need to clean up your session after you’re done.
call: logout
arguments:

string:session – the session_id

results:

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


AUTRES SOURCES D'INFORMATIONS

Documentation externe sur les fonctions SOAP et leur utilisation.

Récupérée de « http://wiki.crm-france.com/index.php/Astuces:SOAP »