Costruire un client Java per SugarCRM

Antonio Musarra's Blog The ideal solution for a problem Blog: http://musarra.wordpress.com

Mail: [email protected]

04/04/11 1 This document is issued with license Creative Commons Attribution-‐NonCommercial-‐ShareAlike

Costruire un client Java per SugarCRM Nel corso di quest’articolo vedremo come realizzare un client Java per

accedere alle informazioni registrate sul sistema di CRM, vedremo inoltre come realizzare una semplice applicazione Java che utilizzerà il client per eseguire una serie di operazioni elementari come: login, creazione di un nuovo contatto e recupero dati. Il sistema SugarCRM (SugarCRM Inc., 2004) espone all’esterno delle interfacce per l’accesso ai dati, queste interfacce supportano il protocollo SOAP e REST (SugarCRM Inc., 2010). La versione di SugarCRM cui faremo riferimento durante l’intero articolo è la 6.1 Community Edition (SugarCRM Inc., 2010).

La scelta del protocollo ricade su SOAP, esistono modi diversi per creare un client SOAP Java in grado di colloquiare con un servizio web, la via più semplice è quella di utilizzare l’ormai maturo framework Apache Axis (The Apache Software Foundation, 2011).

Apache Axis è un framework Open Source che implementa un SOAP Engine, utile per creare, pubblicare e consumare Web Service in Java (ma in realtà supporta anche C/C++). Apache Axis ci sarà d’aiuto per creare il Service SOAP Stub + Data Type partendo dal documento WSDL distribuito da SugarCRM.

Esistono due versioni di Apache Axis, per il nostro client utilizzeremo la versione meno recente (Apache Axis1 1.4) perché quella consigliata e che funziona senza problemi con l’attuale WSDL fornito con SugarCRM. I passi da seguire per raggiungere l’obiettivo sono i seguenti:

• Generazione Stub Java con Apache Axis; • Compilazione dello Stub Java come libreria Java (jar); • Creazione del progetto Java SugarCRMSOAPClient.

1. Generazione del Client Java Prima di procedere con la generazione del client, occorre completare con

successo i seguenti punti: • Download di Apache Axis dall’indirizzo

http://ws.apache.org/axis/java/releases.html . Ricordo che la versione da scaricare è la 1.4;

• Configurazione del framework Apache Axis.

La configurazione di Apache Axis è limitata alla registrazione nel proprio ambiente operativo (sia Windows sia Unix/Linux) delle seguenti variabili di ambiente:

• AXIS_HOME: Directory d’installazione (esempio: /opt/axis, c:\axis) • AXIS_LIB: Directory delle librerie (esempio: $AXIS_HOME/lib) • AXISCLASSPATH: Java class path (esempio:

$AXIS_LIB/axis.jar:$AXIS_LIB/commons-‐loggins.jar)




Affinché Apache Axis funzioni correttamente, è necessario verificare l’impostazione della variabile di ambiente JAVA_HOME, questa rappresenta la directory d’installazione della vostra Java Virtual Machine.

Nel caso di ambienti Unix/Linux (e in modo analogo anche su ambienti Windows) occorre procedere nel modo seguente per impostare le variabili di ambiente illustrate in precedenza:

$ export AXIS_HOME="/opt/axis-1_4" $ export AXIS_LIB="$AXIS_HOME/lib" $ export JAVA_HOME="/System/Library/Frameworks/JavaVM.framework/Versions/1.6.0/Home" $ AXISCLASSPATH=$AXIS_LIB/axis-ant.jar:$AXIS_LIB/axis.jar:$AXIS_LIB/commons-discovery-0.2.jar:$AXIS_LIB/commons-logging-1.0.4.jar:$AXIS_LIB/jaxrpc.jar:$AXIS_LIB/log4j-1.2.8.jar:$AXIS_LIB/saaj.jar:$AXIS_LIB/wsdl4j-1.5.1.jar:$AXIS_LIB/mail-1.4.1.jar:$AXIS_LIB/activation.jar $ export AXISCLASSPATH="$AXIS_HOME":"$JAVA_HOME/lib/tools.jar":"$AXISCLASSPATH":"$CLASSPATH" Listato 1 Export variabili di ambiente.

Nel precedente listano sono mostrati i vari export (i comandi sono validi su sistemi Unix/Linux) delle variabili di ambiente indicate in precedenza. Sul listato ho evidenziato in rosso l’export della JAVA_HOME (non necessario se già disponibile sul vostro ambiente) e le due aggiuntive librerie Java necessarie per il supporto al trasferimento di dati binari. E’ possibile scaricare queste due librerie direttamente dal sito ufficiale (Oracle) o utilizzare il servizio online FindJar (http://www.findjar.com).

• activation.jar: Java Beans Activation Framework (http://www.oracle.com/technetwork/java/jaf11-‐139815.html);

• mail-‐1.4.1.jar: Java Mail API (http://www.oracle.com/technetwork/java/javamail/index.html)

1.1 Generazione dello Stub Java In questo paragrafo vedremo come utilizzare gli strumenti di Apache Axis

per generare Stub + Data Type. Partendo dal WSDL di SugarCRM, utilizzando lo strumento WSDL2Java sarà realizzato il nostro client che consisterà di:

• Stub • Data Type • Locator • Port Type

Senza scendere troppo nei dettagli, tutti i precedenti elementi sono il

risultato dell’analisi delle definizioni specificate nel documento WSDL, è necessario quindi avere la locazione esatta del WSDL, tale posizione può essere remota (URI) oppure locale (file system). In questo esempio ipotizziamo che il documento WSDL sia reperibile all’indirizzo: http://sugarcrm-‐fe-‐1.local/crm-‐6.1/service/v2/soap.php?wsdl.




Potreste eseguire una veloce verifica di raggiungibilità del documento WSDL specificando il vostro indirizzo (quello dell’istanza SugarCRM) su un qualunque browser internet oppure utilizzando strumenti come curl o wget. $ java -cp $AXISCLASSPATH org.apache.axis.wsdl.WSDL2Java –v -B http://sugarcrm-fe-1.local/crm-6.1/service/v2/soap.php?wsdl Listato 2 Esecuzione del tool WSDL2Java

Il tool WSDL2Java eseguito in modo verboso (vedi Listato 2), crea tutti gli elementi necessari a colloquiare con l’interfaccia SOAP di SugarCRM. Tutte le classi generate (partendo dalla directory da cui è stato eseguito il tool) sono disponibili all’interno della directory com/sugarcrm/www/sugarcrm/. Nel mio caso la directory ~/Documents/Articoli/MyBlog/SugarCRM/JavaClient/src è la mia working-‐dir, in altre parole, la directory dalla quale è stato eseguito il tool e dove risederanno sorgenti e binari del client SOAP. Parsing XML file: http://sugarcrm-fe-1.local/crm-6.1/service/v2/soap.php?wsdl Retrieving schema at 'http://schemas.xmlsoap.org/soap/encoding/', relative to 'http://sugarcrm-fe-1.local/crm-6.1/service/v2/soap.php?wsdl'. Retrieving schema at 'http://schemas.xmlsoap.org/soap/encoding/', relative to 'http://sugarcrm-fe-1.local/crm-6.1/service/v2/soap.php?wsdl'. {http://schemas.xmlsoap.org/soap/encoding/}Struct already exists Generating com/sugarcrm/www/sugarcrm/Return_search_result.java Generating com/sugarcrm/www/sugarcrm/Link_field.java Generating com/sugarcrm/www/sugarcrm/New_return_document_revision.java Generating com/sugarcrm/www/sugarcrm/New_return_note_attachment.java Generating com/sugarcrm/www/sugarcrm/Link_name_to_fields_array.java Generating com/sugarcrm/www/sugarcrm/New_note_attachment.java Generating com/sugarcrm/www/sugarcrm/Document_revision.java Generating com/sugarcrm/www/sugarcrm/Module_list.java Generating com/sugarcrm/www/sugarcrm/User_auth.java Generating com/sugarcrm/www/sugarcrm/Get_entry_result_version2.java Generating com/sugarcrm/www/sugarcrm/Entry_value.java Generating com/sugarcrm/www/sugarcrm/New_set_entry_result.java Generating com/sugarcrm/www/sugarcrm/Get_entry_list_result_version2.java Generating com/sugarcrm/www/sugarcrm/New_set_entries_result.java Generating com/sugarcrm/www/sugarcrm/New_set_relationship_list_result.java Generating com/sugarcrm/www/sugarcrm/New_module_fields.java Generating com/sugarcrm/www/sugarcrm/Field.java Generating com/sugarcrm/www/sugarcrm/Get_entries_count_result.java Generating com/sugarcrm/www/sugarcrm/Link_name_value.java Generating com/sugarcrm/www/sugarcrm/Name_value.java Generating com/sugarcrm/www/sugarcrm/Get_server_info_result.java Generating com/sugarcrm/www/sugarcrm/Sugarsoap.java Generating com/sugarcrm/www/sugarcrm/SugarsoapLocator.java Generating com/sugarcrm/www/sugarcrm/SugarsoapPortType.java Generating com/sugarcrm/www/sugarcrm/SugarsoapBindingStub.java Generating ./build.xml Listato 3 Output del tool WSDL2Java.

Al Listato 3 è mostrato l’output generato dal tool WSDL2Java che mostra in modo del tutto evidente le operazioni che eseguite. Volutamente ho specificato l’opzione -‐B nella riga di comando, questa opzione è responsabile della creazione dell’Ant Buildfile (buld.xml), in seguito utilizzato per compilare il client e generare il Jar.




Il tool supporta innumerevoli altre scelte di configurazione che potrebbero essere di supporto in altre situazioni, per maggiori informazioni consiglio di consultare la documentazione ufficiale di Apache Axis.

1.2 Compilazione del client SOAP In questo paragrafo vedremo come compilare il client SOAP utilizzando sia

il tool Ant (The Apache Software Foundation, 2011) sia il metodo classico. <?xml version=”1.0”?> <project basedir=”.” Default=”jar”> <property name=”src” location=”.”/> <property name=”build.classes” location=”classes”/> <path id=”classpath”> <pathelement location=”/opt/axis-1_4”/> <pathelement location=”/System/Library/Frameworks/JavaVM.framework/Versions/1.6.0/Home/lib/tools.jar”/> <pathelement location=”/opt/axis-1_4/lib/activation.jar”/> <pathelement location=”/opt/axis-1_4/lib/axis-ant.jar”/> <pathelement location=”/opt/axis-1_4/lib/axis.jar”/> <pathelement location=”/opt/axis-1_4/lib/commons-discovery-0.2.jar”/> <pathelement location=”/opt/axis-1_4/lib/commons-logging-1.0.4.jar”/> <pathelement location=”/opt/axis-1_4/lib/jaxrpc.jar”/> <pathelement location=”/opt/axis-1_4/lib/log4j-1.2.8.jar”/> <pathelement location=”/opt/axis-1_4/lib/mail-1.4.1.jar”/> <pathelement location=”/opt/axis-1_4/lib/saaj.jar”/> <pathelement location=”/opt/axis-1_4/lib/wsdl4j-1.5.1.jar”/> </path> <target name=”compile”> <mkdir dir=”${build.classes}”/> <javac destdir=”${build.classes}” debug=”on”> <classpath refid=”classpath” /> <src path=”${src}”/> </javac> </target> <target name=”jar” depends=”compile”> <copy todir=”${build.classes}”> <fileset dir=”.” Casesensitive=”yes” > <include name=”**/*.wsdd”/> </fileset> </copy> <jar jarfile=”sugarcrm-soap-client-bin-1.0.0.jar” basedir=”${build.classes}” > <include name=”**” /> <manifest> <section name=”org/apache/ws4j2ee”> <attribute name=”Implementation-Title” value=”Apache Axis”/> <attribute name=”Implementation-Vendor” value=”Apache Web Services”/> </section> </manifest> </jar> <delete dir=”${build.classes}”/> </target> </project> Listato 4 Ant Buldfile generato dal tool WSDL2Java.

Al Listato 4 è mostrato il contenuto del file build.xml generato dal tool WSDL2Java, ho evidenziato l’unica modifica apportata al file, il nome del jar, da soap.jar a sugarcrm-‐soap-‐client-‐bin-‐1.0.0.jar.

La compilazione del client SOAP è davvero semplice, basta eseguire dalla console il comando ant, il Listato 5 mostra l’output ricevuto (per ragioni di spazio e pulizia è stata omessa qualche riga).




Buildfile: ~/Documents/Articoli/MyBlog/SugarCRM/JavaClient/src/build.xml compile: [mkdir] Created dir: ~/Documents/Articoli/MyBlog/SugarCRM/JavaClient/src/classes [javac] Compiling 25 source files … jar: [jar] Building jar: ~/Documents/Articoli/MyBlog/SugarCRM/JavaClient/src/sugarcrm-soap-client-1.0.0.jar [delete] Deleting directory ~/Documents/Articoli/MyBlog/SugarCRM/JavaClient/src/classes BUILD SUCCESSFUL Listato 5 Output del comando ant.

Se sulla vostra macchina non fosse installato il tool Ant, vedremo come sia comunque possibile compilare i sorgenti java e generare la libreria Jar del nostro client SOAP utilizzando il metodo classico. Nel Listato 6 è mostrata la sequenza di comandi che sono necessari per ottenere la libreria sugarcrm-‐soap-‐client-‐bin-‐1.0.0.jar. $ mkdir ~/Documents/Articoli/MyBlog/SugarCRM/JavaClient/src/classes $ javac –cp $AXISCLASSPATH –d ~/Documents/Articoli/MyBlog/SugarCRM/JavaClient/src/classes com/sugarcrm/www/sugarcrm/*.java $ cd ~/Documents/Articoli/MyBlog/SugarCRM/JavaClient/src/classes $ jar cvf sugarcrm-soap-client-1.0.0.jar com/ Listato 6 Compilazione sorgenti Java e creazione del jar.

2. Creazione del progetto Java SugarCRMSOAPClient In questo paragrafo vedremo come creare e configurare correttamente il

progetto Java che chiameremo SugarCRMSOAPClient. Sfruttando la libreria SOAP creata in precedenza, il nostro obiettivo è scrivere del codice Java che esegua le seguenti operazioni su una generica istanza di SugarCRM:

• Login; • Creazione di un nuovo contatto; • Lettura del contatto inserito in precedenza.

L’ambiente IDE utilizzato per la creazione del nostro progetto Java è Eclipse

Helios 3.6, è comunque possibile utilizzare l’IDE a voi più adatto. Di seguito sono illustrati i passi essenziali per creare e impostare il progetto Java.

Figura 1 Step 1 – Creazione di un nuovo progetto Java.




Figura 2 Step 2 – Configurazione iniziale progetto Java.

A meno di esigenze particolari, consiglio di lasciare le impostazioni predefinite per la creazione del nuovo progetto Java.




Figura 3 Step 3 – Configurazione Java building.

Questa parte di creazione del progetto prevede la configurazione dei path per i sorgenti, binari e librerie addizionali. Per quanto riguarda la configurazione mostrata in Figura 3 è consigliabile lasciarla inalterata, occorre invece configurare le dipendenze del progetto, ovvero, le librerie. Le dipendenze che devono essere aggiunte al progetto sono:

• Tutti i file jar di Apache Axis, per intenderci quelli presenti in $ANT_LIB; • La libreria che implementa il Client SOAP SugarCRM, quella che abbiamo

creato in precedenza (sugarcrm-‐soap-‐client-‐bin-‐1.0.0.jar).

Per aggiungere le dipendenze basta semplicemente cliccare sulla sezione “Libraries” della finestra illustrata in Figura 3. In Figura 4 è invece illustrata la finestra con la lista delle dipendenze appena importate.




Figura 4 Step 4 -‐ Import della libreria SugarCRM SOAP Client + Axis.

Terminata l’importazione delle dipendenze, cliccando sul pulsante OK, sarà

portata a termine la creazione del progetto. Dopo la creazione del progetto SugarCRMSOAPClient è possibile visionare l’intera struttura del progetto tramite il Package Explorer, in Figura 5 è illustrata l’espansione del Package com.sugarcrm.www.sugarcrm, in altre parole, la libreria SOAP che utilizzeremo per la connessione a SugarCRM.

Figura 5 Package Explorer dopo la creazione del progetto.




2.1 Scrittura del codice del Client A questo punto siamo finalmente pronti a scrivere il codice Java che

utilizzerà il client SOAP (realizzato in precedenza) per eseguire le azioni indicate nel precedente paragrafo. I passi da seguire per portare a termine l’obiettivo sono:

• Creazione della classe SugarCRMSOAPClient (con il metodo statico main); • Impostazione di una serie di costanti di configurazione; • Creazione End Point URL e Service; • Creazione dello Stub Java; • Esecuzione della Login su SugarCRM; • Creazione di un nuovo Contatto su SugarCRM; • Lettura dei dati del Contatto appena inserito su SugarCRM; • Logout da SugarCRM.

Al Listato 7 le dichiarazioni di alcune costanti che saranno poi utilizzate in seguito. E’ necessario però sostituire i valori delle costanti END_POINT_URL, USER_NAME e USER_PASSWORD con i vostri (della vostra installazione di SugarCRM). public class SugarCRMSoapClient { private static final String END_POINT_URL = "http://crm-6.1/service/v2/soap.php?wsdl"; private static final String USER_NAME = "will"; private static final String USER_PASSWORD = "will"; private static final String APPLICATION_NAME = Class.class.getName(); private static final Integer TIMEOUT = 6000; public static void main(String[] args) throws Exception { …. } } Listato 7 Dichiarazione delle costanti.

// Create a URL end point for the client URL wsdlUrl = null; if (END_POINT_URL.isEmpty()) { wsdlUrl = new URL(new SugarsoapLocator().getsugarsoapPortAddress() + "?wsdl"); } else { wsdlUrl = new URL(END_POINT_URL); } System.out.println("URL endpoint created successfully!"); // Create Service for test configuration ServiceFactory serviceFactory = ServiceFactory.newInstance(); Service service = serviceFactory.createService(wsdlUrl, new SugarsoapLocator().getServiceName()); System.out.println("Service created successfully"); Listato 8 Configurazione URL dell’end point e Service SugarSOAP.




Le operazioni indicate nel Listato 8 potrebbero lanciare delle eccezioni, questa sezione di codice dovrebbe essere racchiusa all’interno di un blocco try…catch, per ragioni spazio è stato omesso. Le eccezioni che potrebbero essere lanciate sono: MalformedURLException e ServiceException. // Trying to create a stub SugarsoapBindingStub binding = new SugarsoapBindingStub(wsdlUrl, service); binding.setTimeout(TIMEOUT); System.out.println("Stub created successfully!"); Listato 9 Creazione dello Stub.

Al Listato 9 la creazione dello stub. Il costruttore dell’oggetto ha bisogno dell’end point del servizio e dell’oggetto service (javax.xml.rpc.Service) creato in precedenza. Lo stub comprende tutte le operazioni per interagire con il servizio web di SugarCRM. Anche questa sezione di codice dovrebbe essere racchiusa all’interno di un blocco try…catch, la creazione dell’oggetto stub e la chiamata di operazioni dello stub, potrebbero lanciare l’eccezione di tipo AxisFault. /** * Try to login on SugarCRM * * 1) Prepare a MD5 hash password * 2) Prepare a User Auth object * 3) Execute login */ // 1. Prepare a MD5 hash password MessageDigest messageDiget = MessageDigest.getInstance("MD5"); messageDiget.update(USER_PASSWORD.getBytes()); // 2. Prepare a User Auth object User_auth userAuthInfo = new User_auth(); userAuthInfo.setUser_name(USER_NAME); userAuthInfo.setPassword((new BigInteger(1, messageDiget.digest())).toString(16)); try { // 3. Execute login Entry_value loginResult = binding.login(userAuthInfo, APPLICATION_NAME, null); System.out.println("Login Successfully for " + USER_NAME); System.out.println("Your session Id: " + loginResult.getId()); sessionID = loginResult.getId(); } catch (RemoteException ex) { System.out.println("Login failed. Message: " + ex.getMessage()); ex.printStackTrace(); } Listato 10 Esecuzione del processo di login su SugarCRM.

A questo punto è tutto pronto per eseguire il login su SugarCRM. L’operazione di login richiede tre parametri, ma dei tre è fondamentale solo il primo, trascuriamo quindi gli ultimi due. Il primo parametro che deve essere preparato è l’oggetto User_auth che contiene il nome utente e la password, ricordo che quest’ultima deve essere l’hash MD5. L’operazione di login restituisce l’identificativo della sessione utente, questo valore sarà utilizzato in seguito per le rimanenti operazioni.




/** * Create a new Contact * * 1) Setting a new entry * 2) Setting up parameters for set_entry call * 3) Creating a name value list array from a hash map. This is not necessary * just more elegant way to initialize and add name values to an array */ HashMap<String, String> nameValueMap = new HashMap<String, String>(); nameValueMap.put("first_name", "Antonio"); nameValueMap.put("last_name", "Musarra"); nameValueMap.put("title", "IT Senior Consultant"); nameValueMap.put("description","Contatto creato dal Client SOAP Java"); nameValueMap.put("email1", "[email protected]"); // Creating a new Name_value array and adding each map entry as 'name' and 'value' Name_value nameValueListSetEntry[] = new Name_value[nameValueMap.size()]; int i = 0; for (Entry<String, String> entry : nameValueMap.entrySet()) { Name_value nameValue = new Name_value(); nameValue.setName(entry.getKey()); nameValue.setValue(entry.getValue()); nameValueListSetEntry[i] = nameValue; i++; } // Trying to set a new entry New_set_entry_result setEntryResponse = null; try { setEntryResponse = binding.set_entry(sessionID, "Contacts", nameValueListSetEntry); } catch (RemoteException e) { System.out.println("Set entry failed. Message: " + e.getMessage()); e.printStackTrace(); } System.out.println("Set entry was successful! Contacts Id: " + setEntryResponse.getId()); Listato 11 Creazione di un nuovo contatto.

Una volta che il login è avvenuto con successo, procediamo con la creazione di un nuovo contatto. L’operazione set_entry permette l’inserimento di un nuovo record su SugarCRM, questo, opera prendendo in input la sessione dell’utente, il nome del modulo (in questo caso Contacts) e un array di oggetti di tipo Name_value che definiscono nomi e valori per il contatto da creare (vedi Listato 11).

L’operazione set_entry restituisce l’identificativo dello SugarBean appena inserito, questo valore sarà utilizzato per il recupero dei dati del contatto utilizzando l’operazione get_entry.

L’operazione get_entry richiede in input la sessione dell’utente, il nome del modulo (in questo caso Contacts), l’identificativo dello SugarBean, un array con i campi che desideriamo avere restituiti e infine un array per collegare i campi restituiti a nomi specifici (opzionale). L’operazione restituisce un entry_list che contiene un array di oggetti Name_value contenente le informazioni del contatto. Il Listato 12 mostra il codice responsabile del recupero delle informazioni del contatto inserito dalla precedente operazione set_entry.




/** * Getting an Contacts Entry (the one we just set) */ Link_name_to_fields_array[] link_name_to_fields_array = null; String[] select_fields = null; Get_entry_result_version2 getEntryResponse = null; // Trying to get entry try { getEntryResponse = binding.get_entry(sessionID,"Contacts", setEntryResponse.getId(), select_fields , link_name_to_fields_array); } catch (RemoteException e) { System.out.println("Get entry failed. Message: " + e.getMessage()); e.printStackTrace(); } System.out.println("Get entry was successful! Response: "); // Getting the fields for entry we got. Entry_value[] entryList = getEntryResponse.getEntry_list(); for (int k=0; k < entryList.length; k++){ Entry_value entry = entryList[k]; Name_value[] entryNameValueList = entry.getName_value_list(); for (int j=0; j< entryNameValueList.length; j++){ Name_value entryNameValue = entryNameValueList[j]; //Outputting only non empty fields if (!entryNameValue.getValue().isEmpty()){ System.out.println("Attribute Name: '" + entryNameValue.getName() + "' Attribute Value: '" + entryNameValue.getValue() + "'"); } } } Listato 12 Recupero dei dati del Contatto inserito su SugarCRM.

/** * Logout */ try { binding.logout(sessionID); System.out.println("Logout Successfully for " + USER_NAME); sessionID = null; } catch (RemoteException ex) { System.out.println("Login failed. Message: " + ex.getMessage()); ex.printStackTrace(); } Listato 13 Operazione di logout da SugarCRM.

Dopo aver eseguito con successo tutte le operazioni, è comunque consigliabile ma non obbligatorio eseguire l’azione di logout da SugarCRM, così come mostrato nel Listato 13.

Nei due listati a seguire (Listato 14 e Listato 15) sono mostrati gli output generati a fronte dell’esecuzione dell’applicazione Java appena realizzata.

Il primo listato (vedi Listato 14) indica un problema nella creazione del servizio a causa di un problema di raggiungibilità del documento WSDL di SugarCRM.




Il secondo listato (vedi Listato 15), mostra invece la situazione attesa: login, creazione nuovo contatto, recupero dati del contatto appena creato e logout.

In Figura 6 è illustrata la scheda del contatto (vista da SugarCRM) creato dall’applicazione Java attraverso il client SOAP.

URL endpoint created successfully! Service creation failed. Message: Error processing WSDL document: java.io.IOException: WSDL2Java emitter timed out (this often means the WSDL at the specified URL is inaccessible)! javax.xml.rpc.ServiceException: Error processing WSDL document: java.io.IOException: WSDL2Java emitter timed out (this often means the WSDL at the specified URL is inaccessible)! at org.apache.axis.client.Service.initService(Service.java:250) at org.apache.axis.client.Service.<init>(Service.java:165) at org.apache.axis.client.ServiceFactory.createService(ServiceFactory.java:198) at it.lab.shirus.sugarcrm.client.soap.SugarCRMSoapClient.main(SugarCRMSoapClient.java:65) Listato 14 Errore nella creazione del servizio.

URL endpoint created successfully! {http://schemas.xmlsoap.org/soap/encoding/}Struct already exists Service created successfully Service Name:{http://www.sugarcrm.com/sugarcrm}sugarsoap Service WSDL:http://sugarcrm-fe-1.local/crm-6.1/service/v2/soap.php?wsdl Stub created successfully! Login Successfully for will Your session Id: a8e97vgnvfhrtcq3hb5midmp32 Set entry was successful! Contacts Id: 69ff87e9-758d-30f5-0acd-4d2e3fa5b513 Get entry was successful! Response: Attribute Name: 'modified_by_name' Attribute Value: 'Will Westin' Attribute Name: 'created_by_name' Attribute Value: 'Will Westin' Attribute Name: 'id' Attribute Value: '69ff87e9-758d-30f5-0acd-4d2e3fa5b513' Attribute Name: 'date_entered' Attribute Value: '2011-01-12 23:55:29' Attribute Name: 'date_modified' Attribute Value: '2011-01-12 23:55:29' Attribute Name: 'modified_user_id' Attribute Value: 'seed_will_id' Attribute Name: 'created_by' Attribute Value: 'seed_will_id' Attribute Name: 'description' Attribute Value: 'Contatto creato dal Client SOAP Java' Attribute Name: 'deleted' Attribute Value: '0' Attribute Name: 'first_name' Attribute Value: 'Antonio' Attribute Name: 'last_name' Attribute Value: 'Musarra' Attribute Name: 'title' Attribute Value: 'IT Senior Consultant' Attribute Name: 'do_not_call' Attribute Value: '0' Attribute Name: 'email1' Attribute Value: '[email protected]' Logout Successfully for will Listato 15 Esecuzione del Client SugarCRMSOAPClient.




Figura 6 Vista del contatto creato con il client SOAP.

La consultazione della documentazione delle API esposte da SugarCRM come servizi web può aiutarvi a comprendere meglio gli esempi di codice Java visti fino a questo momento. Sono sicuro che illustrare lo schema di parte del Data Model (XSD) esposto dall’interfaccia di SugarCRM vi aiuterà a comprendere meglio gli esempi appena mostrati.

Figura 7 Modello della classe User_auth.

Figura 8 Modello della classe Entry_value.




Figura 9 Modello della classe Name_Value_List.

Figura 10 Modello della classe Name_Value.

Figura 11 Modello della classe New_Set_Entry_List.

Figura 12 Modello della class Get_Entry_List_Result_Version2.




Figura 13 Modello della classe Entry_List.

La documentazione in questo momento disponibile di SugarCRM riguardo al Data Model esposto dall’interfaccia non è molta chiara o meglio del tutto assente. Dato che ritengo utile avere la documentazione di alto livello del Data Model, ho estratto dal documento WSDL lo schema XSD e reso disponibile sul mio blog all’indirizzo:

http://musarra.files.wordpress.com/2011/04/sugacrm-‐6-‐1ce-‐xsd.pdf

Ho ritenuto opportuno creare un repository pubblico (GitHub Inc., 2011) contenente quanto prodotto durante la stesura di questo articolo. Il repository è raggiungibile all’indirizzo:

https://github.com/amusarra/SugarCRMJavaSOAPClient e contiene quanto segue:

• JavaApplication: Contiene il progetto Eclipse Java della nostra applicazione che colloquia con SugarCRM utilizzando il client SOAP;

• SOAPClient: Contiene (sorgenti e binari) della client SOAP generato con il framework Apache Axis;

• SugaCRM-‐6.1CE-‐WSDL.wsdl: Documento WSDL della versione 6.1 Community Edition di SugarCRM;

• SugaCRM-‐6.1CE-‐XSD.xsd: Documento XSD estratto dal documento WSDL di SugarCRM;

• SugaCRM-‐6.1CE-‐XSD.pdf: Documentazione del data model utilizzato dall’interfaccia esposta da SugarCRM.

Figura 14 Vista web del repository (git) SugarCRMJavaSOAPClient.




3. Conclusioni In quest’articolo ho cercato di fare “un po’ di luce” su come impostare e

scrivere un client SOAP Java basato sul framework Apache Axis. Qualcuno di voi più attento, avrà notato il disaccoppiamento che ho mantenuto tra il client SOAP Java e l’applicazione Java che nelle sue logiche di business utilizza il client per interagire con SugarCRM: questa è una best practice.

L’ausilio di alcuni esempi base di codice (login, set_entry e get_entry), ha dimostrato come possa essere semplice interagire con i servizi web esposti da SugarCRM, rendendo più facile per chi è interessato la costruzione di un client Java per i servizi web di SugarCRM.

Sono ben accetti i vostri commenti per ogni genere questione in merito al tema trattato. I commenti possono essere lasciati all’indirizzo:

http://musarra.wordpress.com/2011/04/04/costruire-‐un-‐client-‐java-‐per-‐sugarcrm

Bibliography GitHub Inc. (2011). Git Reference. Tratto da GitHub Social Coding: http://gitref.org/ SugarCRM Inc. (2010). Sugar Community Edition Documentation. Tratto da Sugar Community Edition Documentation | SugarCRM -‐ Commercial Open Source CRM: http://www.sugarcrm.com/crm/support/documentation/SugarCommunityEdition SugarCRM Inc. (2010). Sugar Community Edition Documentation. Tratto da Sugar Community Edition Documentation: http://www.sugarcrm.com/crm/support/documentation/SugarCommunityEdition/6.1/-‐docs-‐Developer_Guides-‐Sugar_Developer_Guide_6.1.0-‐Chapter%202%20Application%20Framework.html#9000244 SugarCRM Inc. (2004). SugarCRM -‐ Commercial Open Source CRM. Tratto da SugarCRM -‐ Commercial Open Source CRM: http://www.sugarcrm.com/crm/ The Apache Software Foundation. (2005). Web Service -‐ Axis. Tratto da Apache <Web Services \> Project: http://axis.apache.org/axis/ The Apache Software Foundation. (2011). Apache Ant. Tratto da The Apache Ant Project: http://ant.apache.org/

Costruire un client Java per SugarCRM

Technology

Transcript of Costruire un client Java per SugarCRM