Spesso chi si occupa di informatica e di sviluppo software, quando finisce di combattere con hardware e software, si dedica alla cucina. Qualcuno potrebbe insinuare che si tratta di un inconscio “piano B” del programmatore: se il progetto software non ha successo, potrà sempre tentare miglior fortuna con una carriera come aiuto cuoco. In realtà le similitudini tra l’attività di programmazione e l’arte di cucinare sono molte: in entrambi i casi occorre creare un prodotto finale (il programma che deve essere pubblicato) partendo da una serie di materie prime (il linguaggio di programmazione con le sue librerie), spesso seguendo delle ricette (gli algoritmi o i “patterns” già utilizzati in passato).
Ci sono molte teorie sui motivi per cui spesso sviluppo software e cucina si accompagnano: sono ambedue attività creative, entrambe richiedono un certo livello di studio dell’argomento e sono attività che si prestano ad essere ottimizzate ed eseguite in parallelo (sono molti i piatti che richiedono di svolgere diverse attività contemporaneamente). Nel mio caso credo che cucinare sia una specie di “attività rifugio”, un surrogato dello sviluppo software. Nei momenti più difficili di un progetto, quando non riesco a vedere la fine e nulla funziona come dovrebbe, seguire una ricetta di cucina ed ottenere sempre (o quasi sempre) il risultato desiderato è una grande soddisfazione, e in modo indiretto mi dà speranza che anche il progetto software possa infine riuscire come il piatto che sto preparando.

Come avrete intuito dal titolo, in questo articolo voglio condividere con voi alcune ricette in cui l’ingrediente principale è Konga, in particolare la possibilità di Konga di interagire con  programmi esterni tramite i suoi “web service”.

In questo articolo utilizzeremo il termine “web service” per indicare genericamente la possibilità di interagire con Konga tramite il protocollo HTTP (in particolare utilizzando lo standard JSON-RPC), per una definizione più formale di che cosa si intende per web service rimandiamo alla definizione presente in wikipedia.

Utilizzando i web service di Konga è possibile collegarsi ai database, leggere, inserire, modificare e cancellare i dati avendo la certezza che Konga applicherà tutti i controlli di congruenza e gli eventuali aggiornamenti automatici dei dati definiti dalla “logica della gestione aziendale”. L’accesso via web service quindi è la soluzione più semplice quando si desidera sviluppare delle applicazioni esterne che devono condividere le informazioni della gestione aziendale.

È possibile abilitare i web service solo in Konga Pro, sia nella versione “stand-alone”, sia nella versione “server”. L’opzione per abilitare i web service è presente nella configurazione del server, alla voce “Servizio web”:

Spuntando l’opzione “Avvia il server integrato” e lasciando selezionato il servizio di gestione delle richieste “JSON-RPC” si predispone Konga per rispondere alle richieste all’indirizzo:

http://INDIRIZZO_IP_DEL SERVER:8080/jsonrpc

(ovviamente l’INDIRIZZO_IP_DEL SERVER può essere sostituito dal NOME_DEL_SERVER quando quest’ultimo è stato registrato in un sistema per la risoluzione dei nomi – DNS).

Come si può vedere in figura, la porta di default è la 8080, ma nel caso in cui la porta 8080 sia già utilizzata da altri programmi è possibile impostarne una diversa.

Le richieste a Konga dovranno soddisfare la versione 2.0 dello standard denominato JSON-RPC, si tratta di un protocollo per eseguire delle chiamate a procedure remote (RPC) e queste richieste devono essere eseguite utilizzando il protocollo HTTP.

Per poter utilizzare con profitto i web service di Konga occorre sapere quali sono le richieste che possono essere fatte e conoscere i nomi delle tabelle e dei campi del database di Konga. Questa è la documentazione di riferimento delle chiamate JSON-RPC:
http://public.easybyte.it/docs/current/technical/webservice/json_rpc.html.
In questa documentazione troverete la lista delle chiamate possibili, la descrizione della loro funzione ed i parametri di ingresso e di uscita. Come vedrete, le chiamate previste non sono molte – attualmente sono nove – comunque esse permettono di interagire con i dati di Konga in modo completo. Nel corso di questo articolo non analizzeremo tutte le chiamate, faremo invece qualche esempio pratico di utilizzo che, insieme alla documentazione di riferimento, dovrebbe essere sufficiente per permettere di utilizzare autonomamente tutte le chiamate previste.

Oltre a conoscere le chiamate possibili abbiamo detto che è anche necessario conoscere i nomi delle tabelle e i nomi dei campi del database che utilizza Konga, anche queste informazioni sono presenti nella documentazione tecnica che pubblichiamo on-line: http://public.easybyte.it/docs/current/technical/datadict/tables.html.

Per loro natura i web service non sono legati ad uno specifico ambiente di sviluppo: possono ovviamente essere utilizzati da un’applicazione web, ma nulla osta al loro utilizzo dall’interno di un’applicazione sviluppata per l’ambiente “desktop” o, ad esempio, da una soluzione sviluppata con FileMaker. Per gli esempi di utilizzo che seguiranno utilizzeremo un ambiente di sviluppo che tutti utilizzate quotidianamente: il web browser, tenete bene a mente però che le stesse cose che faremo utilizzando il web browser possono essere fatte anche nella maggior parte dei linguaggi di programmazione e/o framework di sviluppo.

Il nostro “ambiente di sviluppo”
Per fare le richieste web service a Konga utilizzeremo Firefox insieme ad una estensione denominata “RESTClient”, grazie a questa estensione di Firefox saremo in grado di preparare le richieste HTTP, inviarle al Konga server, ricevere la risposta e analizzarne il suo contenuto.

Come potete vedere nella figura qui sopra (cliccare per vedere l’immagine nella dimensione reale), per inviare una richiesta HTTP con il RESTClient è necessario:

1. il metodo HTTP che vogliamo utilizzare, per le richieste a Konga dovremo indicare il metodo POST

2. l’indirizzo a cui inviare la richiesta (URL), nel nostro caso invieremo la richiesta al Konga server che è stato attivato sullo stesso PC nel quale stiamo eseguendo Firefox, quindi l’indirizzo sarà

http://127.0.0.1:8080/jsonrpc/

3. il contenuto della richiesta (Body), per questa prima richiesta utilizzeremo il metodo list_databases per ottenere la lista dei database che possono essere aperti dal Konga server. La richiesta deve essere preparata secondo le regole del formato JSON:

{ "jsonrpc": "2.0", "method": "list_databases", "params": [ ] }

l’elemento “jsonrpc”: “2.0” specifica che la richiesta segue le regole della versione 2.0 di JSON-RPC, il parametro “method” contiene il nome della funzione che desideriamo eseguire (list_databases) e l’argomento “params” in questo caso è una lista vuota perché il metodo “list_databases” non prevede parametri.

Premendo SEND la richiesta viene inviata al server e se tutto è stato configurato correttamente il server risponderà immediatamente. Per visualizzare il contenuto della risposta clicchiamo nella sezione “Response Body”:

Come potete vedere anche la risposta è in formato JSON, l’elemento che più ci interessa nella risposta è “error” che in questo caso è stato valorizzato a null, cioè nessun errore, nel caso in cui Konga ci risponda con un errore, l’elemento “error” conterrà uno o più codici di errore (“code”) e la corrispondente descrizione dell’errore, ad esempio se avessimo specificato un metodo inesistente avremmo ottenuto questa risposta:

Quando non ci sono errori il server restituisce la lista dei database disponibili, in questo caso sul server sono presenti due database: Konga4Ever e Kongademo; per ogni database vengono restituiti alcuni attributi significativi che dovrebbero essere auto-esplicativi, tra questi il più interessante per noi è l’elemento “driver” che ci sarà indispensabile per eseguire la prossima chiamata: “open_database”, che esegue l’apertura del database.

Il metodo open_database

open_database(driver, dbname, username, password)

Ora che conosciamo i nomi dei database ospitati dal Konga server, possiamo decidere di aprirne uno, ad esempio Kongademo. Per poter aprire un database dobbiamo conoscere oltre al suo nome anche il nome del driver del DB (SQLite o MySQL) e le credenziali per l’accesso, cioè il nome utente e la password. Come potete vedere nella figura il metodo open_database prevede proprio questi quattro parametri: driver (SQLite), nome del database (Kongademo), nome dell’utente (admin) e password (stringa vuota – ovvero nessuna password).

La risposta alla chiamata open_database restituisce la cosiddetta “id di sessione”, cioè un identificatore che dovrò utilizzare come primo parametro per le chiamate successive, esso mi permette di non specificare ogni volta le credenziali per la connessione e abbinerà le mie future richieste ad una specifica sessione che rimane aperta sul server per almeno 15 minuti. In questo caso la nostra id di sessione è “e763191990b557f6beaecb6b61ec8957”.

La scadenza della sessione può essere configurata sul server (il valore di default è 15 minuti) e la scadenza verrà rinnovata ogni volta che eseguirò una chiamata al server, quindi la sessione scadrà dopo che non avrò eseguito nessuna chiamata al server per 15 minuti.

Un esempio di lettura: select_data

select_data(sid, tablename[, fieldnamelist, where_expr, order_by, order_desc, offset, limit])

Uno dei metodi disponibili per la lettura dei dati di Konga è “select_data”, questo metodo è molto simile ad una query di tipo SELECT di un database SQL: oltre alla id di sessione questo metodo prevede di specificare un nome tabella e opzionalmente la lista dei nomi dei campi da restituire, una condizione di ricerca (where_expr), le modalità di ordinamento (order_by e order_desc) e di restituire solo un sottoinsieme dei risultati (offset e limit).

Nell’esempio in figura vogliamo leggere ragione sociale e indirizzo di un cliente di cui conosciamo il codice (C00100), quindi eseguiamo una select_data indicando “EB_ClientiFornitori” come nome tabella; “Codice”, “RagioneSociale” e “Indirizzo” come lista dei nomi dei campi e “Codice = ‘C00100′” come condizione di ricerca. Come si può intuire, la sintassi delle condizioni di ricerca è la stessa delle condizioni di ricerca di SQL.

Eseguendo la richiesta, questo è il risultato che viene restituito:

Il risultato consiste di una lista di righe, dove la prima riga contiene i nomi dei campi richiesti, seguita da zero o più righe con i dati dei clienti-fornitori che soddisfano la condizione di ricerca. Nel caso in cui avessi cercato un codice inesistente, la chiamata sarebbe comunque andata a buon fine: sarebbe stata restituita la sola riga con i nomi dei campi e nessun dato a seguire.

Un esempio di scrittura: insert_record

insert_record(sid, tablename, code_azienda, num_esercizio, data)

In maniera molto simile alla lettura è anche possibile utilizzare i web service per inserire dei nuovi dati nel database di Konga. A scopo dimostrativo potete vedere qui sotto un esempio di inserimento di un ordine da cliente. Per evitare di complicare troppo l’esempio, ho indicato solo i campi strettamente obbligatori, ottenendo così un ordine cliente sicuramente incompleto per un uso “reale”, ad esempio ho omesso i prezzi nelle righe e quindi otterrò un ordine cliente con valore totale uguale a zero, ma in compenso posso mostrarvi un esempio decisamente più leggibile.

Come già visto nella select_data i primi due parametri sono l’id della sessione e il nome della tabella, seguiti dal codice dell’azienda (“00000001”), dal codice dell’esercizio (“00000001”) e dai dati che compongono l’ordine cliente che vogliamo inserire. Il codice dell’azienda è necessario perché Konga può gestire più aziende nello stesso database e quindi dobbiamo specificare in quale azienda vogliamo inserire l’ordine. Il codice dell’esercizio è necessario quando la tabella oggetto della chiamata contiene dei dati che sono separati in base agli esercizi contabili, nel caso degli ordini da cliente non sarebbe obbligatorio e potremmo passare “null”, ma nulla osta a specificare un codice esercizio anche quando non è necessario e, così facendo, si evita di dimenticarsene nei casi in cui serve.

I dati dell’ordine da inserire sono composti da una serie di elementi con i nomi dei campi della testata abbinati ai rispettivi valori, quindi un elemento convenzionale denominato “@rows” che contiene la lista delle righe dell’ordine.

Nei dati specificati per la testata dell’ordine è bene notare una particolarità, si tratta del nome dei campi che iniziano con “code_”. Questi sono campi che non troverete documentati nella lista campi di Konga, troverete invece documentati i campi corrispondenti che iniziano con “ref_” al posto di “code_”. Se un nome campo inizia con “ref_” significa che si tratta di una id di una tabella collegata (foreign key in termini SQL), sostituendo la premessa “ref_” con “code_” si richiede al Konga server di decodificare – al posto nostro – i codici delle tabelle e trasformarli nelle corrispondenti id, in tal modo chi esegue la chiamata potrebbe essere facilitato. L’utilizzo dei campi “code_” è spesso un vantaggio perché un codice rimane costante tra un database e un altro (ad esempio dopo un ripristino di un back-up), mentre la corrispondente id potrebbe variare con il database. La scelta di specificare il codice o la id di una tabella collegata dipende spesso dal contesto dell’operazione che si sta eseguendo, in ogni caso Konga semplifica le cose accettando entrambi i valori.

Vorrei anche farvi notare questi due campi obbligatori: “EB_OrdiniClienti.code_Valuta” e “EB_OrdiniClienti.code_Azienda”. Il codice della valuta è sempre obbligatorio, nel dubbio specificate il valore “EUR” che normalmente corrisponde alla valuta di conto. Il campo “code_Azienda” non lo avevamo già indicato tra i paramentri della chiamata? Sì, ma Konga desidera che venga ribadito anche nei dati che vengono passati… ogni tanto è necessario accontentare i programmi senza porsi troppe domande.

Nelle due righe dell’ordine vengono specificati, a scopo esemplificativo, solo i campi obbligatori: Codice articolo, unità di misura e quantità.

Eseguendo la chiamata, otterremo una risposta simile a questa:

L’elemento “id” sarà l’id dell’ordine nel database, mentre “code” sarà il numero interno che è stato assegnato dal Konga server all’ordine appena inserito: l’ordine da cliente numero 11.

Questo era l’ultimo esempio per questo articolo, gli argomenti tecnici come questo non sono semplici né da leggere, né da descrivere, ed è probabile che leggendo questo articolo nascano dei dubbi e delle domande su argomenti che non ho affrontato… come al solito siamo a disposizione per tutti i chiarimenti: scrivete nei commenti del blog oppure inviate un messaggio email a <supportosw@converge.it>.