Costruire un client Java per SugarCRM

Antonio Musarras Blog The ideal solution for a problem Blog: http://musarra.wordpress.com Mail: antonio.musarra@gmail.com 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 SoftwareFoundation, 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) 04/04/11 1 This document is issued with license Creative Commons Attribution-‐NonCommercial-‐ShareAlike

Antonio Musarras Blog The ideal solution for a problem Blog: http://musarra.wordpress.com Mail: antonio.musarra@gmail.com 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. 04/04/11 2 This document is issued with license Creative Commons Attribution-‐NonCommercial-‐ShareAlike

Antonio Musarras Blog The ideal solution for a problem Blog: http://musarra.wordpress.com Mail: antonio.musarra@gmail.com 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?wsdlListato 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?wsdlRetrieving 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 existsGenerating com/sugarcrm/www/sugarcrm/Return_search_result.javaGenerating com/sugarcrm/www/sugarcrm/Link_field.javaGenerating com/sugarcrm/www/sugarcrm/New_return_document_revision.javaGenerating com/sugarcrm/www/sugarcrm/New_return_note_attachment.javaGenerating com/sugarcrm/www/sugarcrm/Link_name_to_fields_array.javaGenerating com/sugarcrm/www/sugarcrm/New_note_attachment.javaGenerating com/sugarcrm/www/sugarcrm/Document_revision.javaGenerating com/sugarcrm/www/sugarcrm/Module_list.javaGenerating com/sugarcrm/www/sugarcrm/User_auth.javaGenerating com/sugarcrm/www/sugarcrm/Get_entry_result_version2.javaGenerating com/sugarcrm/www/sugarcrm/Entry_value.javaGenerating com/sugarcrm/www/sugarcrm/New_set_entry_result.javaGenerating com/sugarcrm/www/sugarcrm/Get_entry_list_result_version2.javaGenerating com/sugarcrm/www/sugarcrm/New_set_entries_result.javaGenerating com/sugarcrm/www/sugarcrm/New_set_relationship_list_result.javaGenerating com/sugarcrm/www/sugarcrm/New_module_fields.javaGenerating com/sugarcrm/www/sugarcrm/Field.javaGenerating com/sugarcrm/www/sugarcrm/Get_entries_count_result.javaGenerating com/sugarcrm/www/sugarcrm/Link_name_value.javaGenerating com/sugarcrm/www/sugarcrm/Name_value.javaGenerating com/sugarcrm/www/sugarcrm/Get_server_info_result.javaGenerating com/sugarcrm/www/sugarcrm/Sugarsoap.javaGenerating com/sugarcrm/www/sugarcrm/SugarsoapLocator.javaGenerating com/sugarcrm/www/sugarcrm/SugarsoapPortType.javaGenerating com/sugarcrm/www/sugarcrm/SugarsoapBindingStub.javaGenerating ./build.xmlListato 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. 04/04/11 3 This document is issued with license Creative Commons Attribution-‐NonCommercial-‐ShareAlike

Antonio Musarras Blog The ideal solution for a problem Blog: http://musarra.wordpress.com Mail: antonio.musarra@gmail.com 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”/> <pathelementlocation=”/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). 04/04/11 4 This document is issued with license Creative Commons Attribution-‐NonCommercial-‐ShareAlike

Antonio Musarras Blog The ideal solution for a problem Blog: http://musarra.wordpress.com Mail: antonio.musarra@gmail.com Buildfile: ~/Documents/Articoli/MyBlog/SugarCRM/JavaClient/src/build.xmlcompile: [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/classesBUILD SUCCESSFULListato 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/classescom/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. 04/04/11 5 This document is issued with license Creative Commons Attribution-‐NonCommercial-‐ShareAlike

Antonio Musarras Blog The ideal solution for a problem Blog: http://musarra.wordpress.com Mail: antonio.musarra@gmail.com 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. 04/04/11 6 This document is issued with license Creative Commons Attribution-‐NonCommercial-‐ShareAlike

Antonio Musarras Blog The ideal solution for a problem Blog: http://musarra.wordpress.com Mail: antonio.musarra@gmail.com 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. 04/04/11 7 This document is issued with license Creative Commons Attribution-‐NonCommercial-‐ShareAlike

Antonio Musarras Blog The ideal solution for a problem Blog: http://musarra.wordpress.com Mail: antonio.musarra@gmail.com 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. 04/04/11 8 This document is issued with license Creative Commons Attribution-‐NonCommercial-‐ShareAlike

Antonio Musarras Blog The ideal solution for a problem Blog: http://musarra.wordpress.com Mail: antonio.musarra@gmail.com 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 clientURL 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 configurationServiceFactory 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. 04/04/11 9 This document is issued with license Creative Commons Attribution-‐NonCommercial-‐ShareAlike

Antonio Musarras Blog The ideal solution for a problem Blog: http://musarra.wordpress.com Mail: antonio.musarra@gmail.com 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 stubSugarsoapBindingStub 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 passwordMessageDigest messageDiget = MessageDigest.getInstance("MD5");messageDiget.update(USER_PASSWORD.getBytes());// 2. Prepare a User Auth objectUser_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. 04/04/11 10 This document is issued with license Creative Commons Attribution-‐NonCommercial-‐ShareAlike

Antonio Musarras Blog The ideal solution for a problem Blog: http://musarra.wordpress.com Mail: antonio.musarra@gmail.com /** * 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", "antonio.musarra@gmail.com");// Creating a new Name_value array and adding each map entry as name and valueName_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 entryNew_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. 04/04/11 11 This document is issued with license Creative Commons Attribution-‐NonCommercial-‐ShareAlike

Antonio Musarras Blog The ideal solution for a problem Blog: http://musarra.wordpress.com Mail: antonio.musarra@gmail.com /** * 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 entrytry { 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. 04/04/11 12 This document is issued with license Creative Commons Attribution-‐NonCommercial-‐ShareAlike

Antonio Musarras Blog The ideal solution for a problem Blog: http://musarra.wordpress.com Mail: antonio.musarra@gmail.com 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 URLis inaccessible)!javax.xml.rpc.ServiceException: Error processing WSDL document:java.io.IOException: WSDL2Java emitter timed out (this often means the WSDL at the specified URLis 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 existsService created successfullyService Name:{http://www.sugarcrm.com/sugarcrm}sugarsoapService WSDL:http://sugarcrm-fe-1.local/crm-6.1/service/v2/soap.php?wsdlStub created successfully!Login Successfully for willYour session Id: a8e97vgnvfhrtcq3hb5midmp32Set entry was successful! Contacts Id: 69ff87e9-758d-30f5-0acd-4d2e3fa5b513Get entry was successful! Response:Attribute Name: modified_by_name Attribute Value: Will WestinAttribute Name: created_by_name Attribute Value: Will WestinAttribute Name: id Attribute Value: 69ff87e9-758d-30f5-0acd-4d2e3fa5b513Attribute Name: date_entered Attribute Value: 2011-01-12 23:55:29Attribute Name: date_modified Attribute Value: 2011-01-12 23:55:29Attribute Name: modified_user_id Attribute Value: seed_will_idAttribute Name: created_by Attribute Value: seed_will_idAttribute Name: description Attribute Value: Contatto creato dal Client SOAP JavaAttribute Name: deleted Attribute Value: 0Attribute Name: first_name Attribute Value: AntonioAttribute Name: last_name Attribute Value: MusarraAttribute Name: title Attribute Value: IT Senior ConsultantAttribute Name: do_not_call Attribute Value: 0Attribute Name: email1 Attribute Value: antonio.musarra@gmail.comLogout Successfully for will Listato 15 Esecuzione del Client SugarCRMSOAPClient. 04/04/11 13 This document is issued with license Creative Commons Attribution-‐NonCommercial-‐ShareAlike

Antonio Musarras Blog The ideal solution for a problem Blog: http://musarra.wordpress.com Mail: antonio.musarra@gmail.com 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. 04/04/11 14 This document is issued with license Creative Commons Attribution-‐NonCommercial-‐ShareAlike

Antonio Musarras Blog The ideal solution for a problem Blog: http://musarra.wordpress.com Mail: antonio.musarra@gmail.com 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. 04/04/11 15 This document is issued with license Creative Commons Attribution-‐NonCommercial-‐ShareAlike

Antonio Musarras Blog The ideal solution for a problem Blog: http://musarra.wordpress.com Mail: antonio.musarra@gmail.com 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. 04/04/11 16 This document is issued with license Creative Commons Attribution-‐NonCommercial-‐ShareAlike

Antonio Musarras Blog The ideal solution for a problem Blog: http://musarra.wordpress.com Mail: antonio.musarra@gmail.com 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/ 04/04/11 17 This document is issued with license Creative Commons Attribution-‐NonCommercial-‐ShareAlike

Costruire un client Java per SugarCRM

by Antonio Musarra

Accessibility

Categories

Upload Details

Usage Rights

Statistics