Funzioni di base Introduzione
E' ormai quasi una regola, quando si propone un progetto a potenziali clienti, la parte che li affascina di più è il CRM. Di solito non ne hanno alcun bisogno, ma si comportano come se non potessero farne a meno. E' così!! Oppure già ce l'hanno e l'applicativo proposto deve assolutamente interfacciarvisi. Va bene, bandiera bianca. Vogliono l'integrazione con un CRM, diamogliela!
Sugar è un CRM open source piuttosto noto. Ciò che ci interessa è la sua interfaccia SOAP. Per suo tramite possiamo integrare applicativi esterni con Sugar. Questa volta esploreremo alcune funzionalità di ricerca per ottenere liste di contatti dal crm.
Nel prossimo articolo di questa serie ci concentreremo invece sull'utilizzo di sugar come sistema di autenticazione per i nostri applicativi web.
Panoramica
L'interfaccia SOAP di Sugar espone tutto ciò che ci serve per il nostro scopo. Posto che la vostra installazione di Sugar sia a http://mysugar/, è possibile ottenere il file wsdl da http://mysugar/soap.php?wsdl, mentre http://mysugar/soap.php punta alla documentazione circa i metodi SOAP esposti.
Questa volta, i metodi SOAP che ci interessano sono: - login, per autenticarci in sugar
- get_entry_list per ottenere liste di Contatti,Aziende,Note etc.
Per accedere alle funzionalità SOAP da PHP utilizziamo la libreria nusoap, che non richiede particolari estensioni del PHP.
Costruiamo ora una classe PHP che incapsuli le funzionalità che ci servono. Negli articoli a venire espanderemo questa classe con nuovi metodi. Il codice
La maggior parte dei metodi SOAP esposti richiede un id di sessione come parametro, per assicurarsi che siamo utenti autenticati. Possiamo ottenere un id di sessione chiamando il metodo login.
Ma prima di tutto creaiamo la classe base con un costruttore:
<?php
require_once("nusoap.php");
class SugarSoap{
var $proxy;
var $sess;
function SugarSoap($soap_url,$login=true){
$soapclient = new soapclient($soap_url,true);
$this->proxy = $soapclient->getProxy();
if($login) $this->login();
}
}
?>
La variabile di istanza $sess è l'id di sessione di cui abbiamo bisogno per la maggior parte dei metodi, $proxy è un'istanza del proxy soap creato da nusoap che ci permette di chiamare i metodi richiesti.
Nel costruttore, $soap_url è http://mysugar/soap.php?wsdl, cambiando mysugar con la vera url della nostra installazione di sugar, e $login è di default a 'true', implicando così un login automatico.
Semplicemente istanziamo un client soap (il 'true' come secondo parametro significa che utilizziamo un file wsdl), ne otteniamo un oggetto proxy e, se richiesto, ci autentichiamo.
Ora il metodo login (da aggiungere dentro alla classe SugarSoap). Eccolo:
function login(){
$params = array(
'user_name' => 'myuser',
'password' => md5('mypassword'),
'version' => '.01'
);
$result = $this->proxy->login($params,'MyApp');
$this->sess= $result['error']['number']==0 ? $result['id'] : null;
return $this->sess;
}
Facile! Usiamo il proxy del client soap per chiamare il metodo login, passandogli i parametri necessari.
Più precisamente:
- user_name è un utente sugar valido
- password è la corrispondente password(da passare encodata md5)
- version , un numero di versione, non sono sicuro che serva a qualcosa
Il secondo parametro del metodo è una stringa libera(secondo la documentazione è il nome dell'applicativo).
Ora abbiamo il risultato della chiamata in $result, una struttura di array. Avremo sempre un array $result['error'] , e $result['error']['number']==0 significa nessun errore. Se tutto è andato bene abbiamo un id di sessione valido in $result['id'], e lo salviamo per le successive chiamate.
Interrogare Sugar
A questo punto abbiamo il nostro id di sessione, quindi siamo autenticati in sugar, e possiamo "interrogarlo". Focalizziamoci sul metodo get_entry_list. I parametri che richiede sono:
- session_id, il nostro id di sessione
- module_name, cioè Contacts,Accounts,Notes,Cases etc
- query, una query tipo sql
- order_by, una clausola order_by tipo sql
- offset, per paginare
- select_fields, un array di campi da richiedere
- max_result, massimo numero di elementi da restituire
- deleted, se includere o no anche elementi cancellati
Ecco il nostro metodo getContacts(da aggiungere alla classe SugarSoap):
function getContacts($query='',$maxnum=0,$orderby=' contacts.last_name asc'){
$result = $this->proxy->get_entry_list(
$this->sess,
'Contacts',
$query,
$orderby,
0,
array(
'id',
'first_name',
'last_name',
'account_name',
'account_id',
'email1',
'phone_work',
),
$maxnum,
false
);
return $result;
}
Il solito schema di chiamata, niente di nuovo. Da notare che il nome del modulo ha la prima lettera maiuscola.
Una nota sulla lista dei campi; si puo' ottenere la lista di tutti i campi presenti in un modulo tramite il metodo get_module_fields. Lo vedremo nel prossimo articolo, assieme all'utilizzo di campi personalizzati. Manipolare i risultati
Prima di tutto una regola generale: se una chiamata soap a sugar restituisce vuoto(nessun array), possiamo stare certi che c'e' un problema con la sintassi della query o con la clausola order_by. Un cosiglio, usare sempre la notazione "modulo.campo"(es. "contacts.email1"). Questo credo sia dovuto al fatto che in sugar, per ogni modulo esiste sul db una corrispondente tabella "_cstm" per i campi personalizzati(per "Contacts" esiste una tabella "contacts_cstm"), e anche i campi di questa vengono presi in considerazione durante le interrogazioni.
Dopo aver chiamato il nostro metodo getContacts, il risultato che otteniamo è di nuovo una struttura di array.
Ecco un esempio:
Array
(
[result_count] => 3
[next_offset] => 3
[field_list] => Array
(
[0] => Array
(
[name] => id
[type] => id
[label] => ID:
[required] => 0
[options] => Array
(
)
)
[1] .........
)
[entry_list] => Array
(
[0] => Array
(
[id] => 83567303-7aad-db69-0d7e-44bde634c3f7
[module_name] => Contacts
[name_value_list] => Array
(
[0] => Array
(
[name] => id
[value] => 83567303-7aad-db69-0d7e-44bde634c3f7
)
[1] => Array
(
[name] => first_name
[value] => Mauro
)
[2] => Array
(
[name] => last_name
[value] => Molino
)
[3] ........
)
)
[1] ........
)
[error] => Array
(
[number] => 0
[name] => No Error
[description] => No Error
)
)
Abbiamo già incontrato l'array [error], [result_count] e [next_offset] sono semplici e ovvi valori.
[field_list] contiene un array multi-dimensionale con dati circa i campi richiesti, ma ciò che ci interessa veramente è la struttura dell'array [entry_list]. E' di nuovo un array multi-dimensionale contenente i singoli elementi frutto della ricerca. Ogni elemento contiene un paio di campi e un array [name_value_list], che a sua volta contiene i dati dell'elemento in coppie di campi name/value. Normalmente è più comodo avere questi dati sotto forma di array associativo chiave/valore, per cui implementiamo il sequente metodo, come al solito da mettere dentro la classe SugarSoap:
function nameValuePairToSimpleArray($array){
$my_array=array();
while(list($name,$value)=each($array)){
$my_array[$value['name']]=$value['value'];
}
return $my_array;
}
Passando per esempio l'array [entry_list][0][name_value_list] al metodo di cui sopra, otteniamo qualcosa tipo:
Array
(
[id] => 83567303-7aad-db69-0d7e-44bde634c3f7
[first_name] => Mauro
[last_name] => Molino
)
Un piccolo esempio
Ora abbiamo tutto il necessario per scrivere un piccolo esempio. Eccolo:
require_once "SugarSoap.php";
$soap=new SugarSoap('http://mysugar/soap.php?wsdl'); // we automatically log in
$result=$soap->getContacts(" contacts.email1<>'' ",5," contacts.last_name desc");
if($result['result_count']>0){
foreach($result['entry_list'] as $record){
$array= $soap->nameValuePairToSimpleArray($record['name_value_list']);
echo $array['first_name'] . " " . $array['last_name'] . " - " . $array['email1']. "<br>";
}
} else {
echo "No contacts found";
}
Stiamo richiedendo solo contatti la cui email non sia vuota, un massimo di 5 record, ordinati per cognome decrescente.
Il ciclo foreach ci restituisce i singoli elementi che convertiamo in più utilizzabili array associativi.
La visualizzaione è ottenuta mediante un semplice echo. Con i risultati in array associativi è semplice passarli a sistemi di templating tipo Smarty, per ottenere visualizzazioni più decenti.
Note
Non siate troppo severe/i sulla qualità del codice. A parziale giustificazione, considerate che per andare il più possibile dritto al punto, ignoro bellamente cose tipo gestione degli errori. Penso, ma è solo la mia opinione, che per sviluppatori di esperienza intermedia/avanzata del codice essenziale sia più facilmente digeribile.
Considerazioni finali
Abbiamo visto solo le basi per l'integrazione di Sugar crm, ma già abbiamo del materiale sul quale lavorare.
Il prossimo articolo punterà su livelli di integrazione più profonda tra sugar e applicativi personali; in particolare vedremo come utilizzare sugar come sistema di autenticazione e gestione utenti per i nostri applicativi, evitando il carico di doverli implementare da zero, e allo stesso tempo fornendoci un buono strumento da mostrare ai nostri clienti.
Non esitate a contattarmi per domande/dubbi/consigli.
Risorse
Integrare SugarCRM con applicativi PHP (I) - Sugar come sistema di autenticazione
Il secondo articolo di questa serie. Si focalizza sull'utilizzo di sugar come sistema di autenticazione e gestione utenti per applicativi PHP.
|
Articoli 
