sugarcrm web services: build a apache cxf client

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

Mail: [email protected]

17/08/12 1 This document is issued with license Creative Commons Attribution-‐NonCommercial-‐ShareAlike

SugarCRM Web Services: Build a Apache CXF Client

SugarCRM[1] espone all’esterno il core delle proprie funzionalità pubblicandole come Web Services, quindi niente di più semplice che creare un client Java, C#, C++, PHP e chi più ne ha più ne metta per interagire con essi; non sempre però la questione è così semplice !!!

Chi lavora pesantemente con la tecnologia dei Web Services è cosciente del fatto che gli standard esistenti lasciano un notevole grado di libertà tale per cui possono essere interpretati diversamente dalle varie case produttrici di software, con la conseguenza di non garantire in alcuni casi l’interoperabilità.

Potrebbe cioè essere impossibile, ad esempio, accedere ad un web service creato con Axis (Java) utilizzando .NET (Microsoft). E’ stato creato un comitato denominato WS-‐I (Web Services Interoperability) con l’obiettivo di risolvere i problemi legati all’interoperabilità.

SugarCRM dichiara di essere compliant WS-‐I 1.0 Basic Profile[2] , ciò significa che dovremmo essere in grado d’interagire con i servizi web di SugarCRM attraverso client generati (a partire dal documento WSDL) con Apache Axis, JAX-‐WS, Apache CXF, etc…

Prima di andar sul pratico, desidero fare un breve refresh su style

binding e use. Il documento WSDL[3] descrive il servizio web, in particolare, l’elemento binding costituisce la specifica concreta di protocollo (in particolare il protocollo SOAP) e formato dati, relativo a un elemento portType. Il SOAP binding, che definisce il modello di messaging, che può essere:

• Remote Procedure Call (RPC) Style; • Document Style.

La regola di codifica dei dati specificata dall’attributo use, può

essere, encoded o literal. Sintetizzando, esistono quattro diverse combinazioni di stile e codifica, sulle quali entrambe le parti coinvolte devono convenire prima d’iniziare lo scambio d’informazioni: per esempio, un server che supporta soltanto la codifica letterale per lo scambio dei documenti non sarà mai in grado di comunicare con un client che utilizza il modello RPC con la codifica encoded.

L’elenco a seguire mostra un riepilogo delle possibili combinazioni: • Document/Literal; • Document/Encoded; • RPC/Literal; • RPC/Encoded.




Nelle successive figure ho evidenziato style e use nelle due combinazioni RPC. L’estratto mostrato fa riferimento al documento WSDL di SugarCRM (Community Edition versione 6.4).

Figura 1 WSDL Web Services di SugarCRM RPC/Encoded

Figura 2 WSDL Web Services di SugarCRM RPC/Literal

Dalla documentazione di SugarCRM risultano supportate le due combinazioni RPC, quella di default è RPC/Encoded. Le URL per accedere al documento WSDL per le due combinazioni sono:

• RPC/Encoded: http://<hostname>:<port>/service/v2/soap.php?wsdl • RPC/Literal: http://<hostname>:<port>/service/v2/soap.php?wsdl&sty

le=rpc&use=literal

Build del Client In precedenti articoli pubblicati su questo blog sono stati affrontati temi

circa lo sviluppo di client per i servizi web di SugarCRM, sia utilizzando il linguaggio Java (tramite il framework Apache Axis 1.4) sia utilizzando .NET Framework. In questo caso creeremo il client utilizzando Apache CXF[4].

I requisiti minimi per portar a casa il risultato sono:

• Installazione e Configurazione del framework Apache CXF 2.2.x (o 2.5.x) • Ant 1.7 • JDK 1.6




Qualora fosse necessario consiglio di fare riferimento alla documentazione ufficiale di ogni componente indicato nel precedente elenco.

Costruiremo il client a partire dal documento WSDL di SugarCRM, in particolare faremo riferimento alla versione 4 delle API di SugarCRM Community Edition 6.4. Nella successiva tabella sono indicate le versioni delle API e le relative versioni di SugarCRM.

API Version SugarCRM Version

V2 5.5.0

V3 6.1.0

V3_1 6.1.0

V4 6.2 e successive

Tabella 1. Versioni delle API L’URL di accesso ai servizi rispetta il pattern

http://<hostname>:<port>/service/vX/soap.php dove X indica la versione delle API indicata in Tabella 1 (prima colonna).

Per generare il client utilizzeremo il tool wsdl2java locato in

$CXF_HOME/bin, specificando l’URL del documento WSDL e una serie di altri parametri. E’ utile ricordare che Apache CXF supporta la combinazione RPC/Literal e non quella di default di SugarCRM RPC/Encoded. Per questo motivo, l’URL del WSDL da fornire a Apache CXF è il seguente:

• http://<hostname>:<port>/service/v4/soap.php?wsdl&style=rpc&use=li

teral Qualora forniate l’URL non corretta ad Apache CXF in fase di generazione del client, riceverete il seguente errore: WSDLToJava Error: Rpc/encoded wsdls are not supported with CXF Il comando per generare il client è il seguente: wsdl2java -d /Users/amusarra/SugarCRMCE64v4SOAPLibray \ -client -ant -exsh false -dns true -dex true \ -verbose \ "http://<hostname>:<port>/service/v4/soap.php?wsdl&style=rpc&use=literal"

Il tool creerà all’interno della directory specificata dal parametro -‐d tutti i sorgenti Java del client + il file build.xml di Ant che potrete utilizzare per fare il build e test del client. Se non diversamente specificato, il client sarà creato utilizzando JAX-‐WS come FrontEnd e JAX-‐B come DataBinding, il vantaggio di questa soluzione è rappresentato dal fatto che sarete in grado di eseguire il client senza la necessità di librerie aggiuntive, basta la sola JDK/JRE.




Apache CXF, oltre a creare tutte le classi Java a supporto, crea inoltre una

classe di test da completare oltre che a poter eseguire la classe stessa via Ant. Il nome della classe di test è:

• com.sugarcrm.sugarcrm.SugarsoapPortType_SugarsoapPort_Client.java

una volta che avrete completato la classe con qualche prova di chiamata a uno o più metodi esposti dal servizio, potrete verificare il risultato eseguendo il comando: ant SugarsoapPortTypeClient ottenendo (come nel mio caso) un risultato del genere: SugarsoapPortTypeClient: [java] SugarCRM Server Info... [java] Version 6.4.0 [java] Flavor CE [java] Invoking login... [java] Login Successfully for admin [java] Your session Id: 98b439d68141cf38fe2441382fb6513b [java] Invoking getUserId... [java] Your UserId is: 1 [java] Invoking logout... BUILD SUCCESSFUL Total time: 3 seconds

Ho completato la classe test in modo da eseguire le operazioni di ServerInfo, Login, GetUserId e Logout. A questo punto il gioco è fatto. Consiglio di realizzare un bel jar del client appena creato per utilizzarlo ovunque sia necessario accedere ai dati del CRM di Sugar.

Risorse Quanto realizzato per la stesura di quest’articolo è stato pubblicato sul Repository GitHub raggiungibile all’indirizzo:

https://github.com/amusarra/SugarCRMCE64v4SOAPLibrary Il repository contiene:

• Il progetto Eclipse chiamato SugarCRMCE64v4SOAPLibray • Il documento WSDL (RPC/Literal) del servizio (in resources/wsdl) • Il documento XSD del servizio (in resources/xsd) • Il Jar SugarCRMCE64v4SOAPLibrary.jar del client (in build)




Riferimenti David A. Chappell, T. J. (2002). Java Web Services. O’REILLY. Antonio Musarra. (4 Aprile 2011). Costruire un client Java per SugarCRM Antonio Musarra. (15 Novembre 2011). Building a Client .NET for SugarCRM [1] SugarCRM Web Service Overview [2] Chris Ferris. (1 Ottobre 2002). First look at the WS-‐I Basic Profile 1.0 [3] Russell Butek. (31 Ottobre 2003). Which style of WSDL should I use? [4] The Apache Software Foundation. Apache CXF: An Open-‐Source Services Framework

sugarcrm web services: build a apache cxf client

Documents