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  l'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, relativa a un elemento portType. Il SOAP binding, che definisce il modello di messaging, può essere:

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

mentre la modalità 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 di 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.

WSDL Web Services di SugarCRM RPC/Encoded

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&style=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 la relative versioni di SugarCRM.

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 un 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=literal

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:
  SugarCRM Server Info...
  Version 6.4.0
  Flavor CE
  Invoking login...
  Login Successfully for admin
  Your session Id: 98b439d68141cf38fe2441382fb6513b
  Invoking getUserId...
  Your UserId is: 1
  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 questo articolo è stato pubblicato sul mio 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