Indice articolo

In questo articolo mostreremo come poter esporre una Fun tramite un Web Service. La nuova funzionalità, disponibile in Sme.UP ERP, permette a sistemi terzi, che quindi non implementano un connettore nativo con il nostro gestionale, di interagire con l’applicativo Sme.UP ERP tramite protocollo HTTP esposto via Web Service pubblicati da uno Sme.UP Provider. Alla fine dell’articolo avremo gli elementi di conoscenza per predisporre il seguente URL

http://indirizzo-provider/A39Service?FUN=SAMPLEJSON&COD.ESE=A.001

in modo che venga in realtà chiamata la seguente Fun

F(EXB;B£SER_46;GEN.COM) 1(J1;GRA;EXB) 2(MB;SCP_SET;SIM_SER_46) 3(;;A.001)

Il risultato sarà un XML

<?xml version="1.0" encoding="UTF-8"?>
 <UiSmeup Testo="EXB  - ">
 <Service Funzione="F(EXB;B£SER_46;GEN.COM) 1(J1;GRA;EXB) 2(MB;SCP_SET;SIM_SER_46) 3(;;A.001) INPUT()"/>
 <Griglia>
 <Colonna Cod="OGG" Txt="Oggetto" Lun="20" IO="O" Ogg="TAV§P" Fill="ASSE"/>
 <Colonna Cod="DES" Txt="Descrizione" Lun="20" IO="O"/>
 <Colonna Cod="NUM" Txt="Numero" Lun="20" IO="O" Ogg="NR" Fill="SERIE"/>
 <Colonna Cod="DAT" Txt="Data" Lun="10" IO="O" Ogg="D8*YYMD"/>
 <Colonna Cod="ORA" Txt="Ora" Lun="10" IO="O" Ogg="I12"/>
 </Griglia>
 <Righe>
 <Riga Fld="TA|Taranto|33|20170310|"/>
 <Riga Fld="TA|Taranto|43|20170312|"/>
 [...] 
 </Righe>
 </UiSmeup>

I protagonisti

I Web Service

Uno dei meccanismi più pratici per permettere a due sistemi di interagire fra di loro è quello che comunemente va sotto il nome di Web Service. In questa categoria di servizi si possono distinguere due macro famiglie: RESTful ( Representational state transfer) e SOAP (Simple Object Access Protocol)

In questo articolo ci concentreremo sui primi e, di seguito riportiao una delle tante definizioni:

“Un Web Service RESTful è custode di un insieme di risorse sulle quali un client può chiedere le operazioni canoniche del protocollo HTTP. Per brevità spesso si fa riferimento a RESTful semplicemente con REST”, e così faremo anche noi.

Le Fun in Sme.UP ERP

Introducendo il concetto di Fun, in Sme.UP ERP si è voluto definire una sintassi che permetta di richiamare i servizi del nostro ERP in maniera uniforme. Il limite principale di questa sintassi è che si tratta di una sintassi proprietaria, quindi tendenzialmente “indigesta” a chi, dall’esterno, necessita di utilizzarla.

F(EXB;B£SER_46;GEN.COM) 1(J1;GRA;EXB) 2(MB;SCP_SET;SIM_SER_46) 3(;;A.001)

Per abbassare il più possibile il gradino per permettere ad un sistema terzo di sfruttare la potenza applicativa del nostro gestionale, si è pensato ad un meccanismo configurabile ed estendibile per esporre le FUN tramite un Web Service REST. Tale meccanismo prende il nome di Costruttore A39 (amichevolemente LOA39)

I costruttori in Sme.UP ERP

In Sme.UP ERP i costruttori sono insiemi di funzionalità di alto livello, siano esse grafiche o meno. Questi insiemi sono definiti sulla base di un argomento: gestione invio mail, gestione dei flussi di funzioni, gestione delle query SQL, gestione dell’interfaccia con il campo, etc.

Il costruttore A39

Il costruttore LOA39 è il connettore che permette di collegare i due mondi precedentemente descritti: i servizi REST e le funzioni Sme.UP. Vale a dire che tramite il LOA39 è possibile esporre tramite un Web Service REST di nome A39Service, quindi su protocollo HTTP, i servizi presenti nel gestionale.

In questo modo è possibile fornire a sistemi esterni i dati presenti in Sme.UP, veicolando questa “fornitura” attraverso i servizi che contengono la logica di business, ed in ultima istanza tramite le funzioni.

Passando attraverso le funzioni del gestionale, è possibile passare quindi i dati già in una forma aggregata.

A39Service

A39Service è il Web Service REST che viene attivato dallo Sme.UP Provider se è stato configurato correttamente il costruttore LOA39

 La definizione di una Sezione A39

Attraverso lo script di esempio di seguito riportato, tramite il LOA39, definiamo una Sezione che stabilisce il nome di un metodo del Web Service, cui associamo una Fun, per far sì che quest’ultima possa essere richiamata. Le variabili inserite nella Fun vengono automaticamente associate a parametri HTTP, che quindi possono essere valorizzati nella chiamata HTTP stessa.

::SEZ Cod="S00" Txt="Funzioni di esempio, esempio servizi Smeup usati dall'esterno"
::SUB Cod="A00" Txt="Matrice in formato JSON" Timeout="300"
-- Alias della Funzione associata
::A39.SUBMET Value="SAMPLEJSON" Txt="Nome che identifica la funzione"
::A39.SUBFUN Name="Funzione" Value="F(EXB;B£SER_46;GEN.COM) 1(J1;GRA;EXB) 2(MB;SCP_SET;SIM_SER_46) 3(;;[COD.ESE])" Txt="Funzione" NoAuth="1"

La Sezione sopra riportata dichiara un metodo SAMPLEJSON, cui è associata

F(EXB;B£SER_46;GEN.COM) 1(J1;GRA;EXB) 2(MB;SCP_SET;SIM_SER_46) 3(;;[COD.ESE])

Il funzionamento

Cosa accade quando un client HTTP richiama il Web Service A39Service?

  1. Viene svegliato il servizio HTTP A39Service, fornendogli il nome del metodo richiesto
    http://indirizzo-provider/A39Service?FUN=SAMPLEJSON&COD.ESE=A.001
  2. Il servizio A39Service legge il metodo richiesto
    SAMPLEJSON
  3. Sulla base di tale metodo capisce quale Fun vi sia associata
    F(EXB;B£SER_46;GEN.COM) 1(J1;GRA;EXB) 2(MB;SCP_SET;SIM_SER_46) 3(;;[COD.ESE])
  4. Veicola i parametri HTTP nelle variabili Sme.UP omonime
    COD.ESE viene sostituito da A.001
  5. Esegue la Fun identificata al punto 3
  6. Restituisce al client HTTP che lo ha richiamato il risultato della Fun

Come richiamare il Web Service

Ipotizzando la presenza di uno script come quello precedentemente illustrato, Smeup Provider esporrà il Web Service A39Service, richiamabile tramite GET o POST indifferentemente, tramite il seguente URL:

http://indirizzo-provider/A39Service?FUN=SAMPLEJSON&COD.ESE=A.001

Questo richiamo originerà la seguente richiesta verso il servizio B£SER_43

F(EXB;B£SER_46;GEN.COM) 1(J1;GRA;EXB) 2(MB;SCP_SET;SIM_SER_46) 3(;;A.001)

Come gestire l’autenticazione al servizio

La richiesta HTTP esemplificata al punto precedente può avvenire con o senza la necessità di autenticarsi. Come default l’accesso alla funziona pubblicata avviene solo previa autenticazione al sistema, nei modi previsti e documentati nell’apposita documentazione tecnica dell’ AuthenticateService

Qualora si voglia invece rendere l’accesso alla funzione possibile senza autenticazione, perché si garantisce la sicurezza ad un altro livello, es: VPN, servizi intranet, etc., è possibile impostare il parametro NoAuth=”1″ nella specifica ::A39.SUBFUN. In questo modo, se fra i parametri di chiamata all’A39Service, si aggiunge *AUTH=NULL, l’accesso non sarà condizionato ad un preventivo processo di autenticazione, e la richiesta avverrà utilizzando l’utente di connessione impostato nel Provider.

Di seguito lo stesso esempio precedentemente riportato modificato per effettuare una richiesta non autenticata, possibile solo perché impostato NoAuth=”1″ nella definizione del metodo SAMPLEJSON

http://indirizzo-provider/A39Service?FUN=SAMPLEJSON&COD.ESE=A.001&*AUTH=NULL

A39Client

Per facilitare l’interazione con l’A39Service, oltre a rendere disponibili pubblicamente le specifiche per l’implementazione dell’algoritmo di autenticazione applicativa e richiesta dati al Web Service, abbiamo realizzato in due differenti linguaggi (java e php) le librerie contenenti un A39Client che permette di richiamare comodamente il nostro servizio download.

Conclusione

Tutto quanto illustrato finora è utilizzabile sia in un ottica di pubblicazione Web Service con autenticazione applicativa o meno. Vale a dire che è possibile decidere se esporre un metodo in maniera che sia richiamabile pubblicamente o solamente dopo aver assolto alla procedura di autenticazione applicativa.

Lo sforzo che sta alla base di realizzazioni come il LOA39 (ma anche di altri costruttori come il LOA37 ed il LOA38) è quello di rendere sempre più agevole interagire con il mondo esterno, sia in qualità di Service Provider, sia di Service Consumer. E’ uno sforzo fondamentale per l’oggi e per il domani.

Appendice

I Transformer

La caratteristica che rende A39Service qualcosa di più di una servizio HTTP che richiama una Fun Sme.UP è la possibilità di inserirsi, tramite la configurazione, fra i punti 4 e 5, e poi fra i punti 5 e 6 del paragrafo “Il funzionamento” e fare “qualcosa”. Questo “qualcosa” viene eseguito da pezzi di codice java che chiamiamo Transformer.

Per la precisione i Transformer si distinguono in Transformer Pre o Transformer Post a seconda che possano essere eseguiti prima o dopo aver eseguito la Fun Sme.UP associata al metodo della sezione.

Ad esempio, nella configurazione precedentemente, inserendo la riga:

::A39.PSTTRS Name="Transformer Post" Value="Smeup.smeui.loa39.interaction.transformer.TransformerGridToJSON" Txt="Classe per post trasformazione"

Il valore dell’attributo Value identifica una classe di tipo Transformer. Questi Transformer infatti sono delle classi java che implementano delle interfacce, definite nel provider, per poter essere agganciati a tempo di esecuzione e eseguire compiti specifici.

E’ possibile dichiarare Transformer che eseguano qualcosa anche prima dell’esecuzione della Fun. Ciò si dichiara con una specifica come la seguente

::A39.PRETRS Name="Transformer Pre" Value="Smeup.smeui.loa39.interaction.transformer.TransformerDataUpload" Txt="Classe per pre trasformazione"

Con questa specifica si è dichiarato un Transformer che analizza la richiesta HTTP e, se contiene dei file allegati, li estrae e li mette a disposizione della Fun che verrà eseguita subito dopo.

Il risultato ottenuto dal Provider, prima di essere restituito al client Http che l’ha invocato, subirà un ultimo trattamento da parte del Transformer Post. In questo caso il Transformer Post dichiarato

TransformerGridToJSON

trasformerà l’XML di matrice restituito dal servizio nell’equivalente in JSON (un formato dati alternativo a XML).

Le interfacce per creare Transformer personalizzati sono pubblicate in librerie disponibili tramite Maven con i seguenti riferimenti

<groupId>com.smeup</groupId>
<artifactId>wspspi</artifactId>

Con questi riferimenti qualunque sviluppatore java può agilmente sviluppare Transfomer personalizzati, installarli in uno Sme.UP Provider e agganciarli attraverso una definizione di una Sezione del costruttore.

Controllo e test

Tutte le funzioni esposte e le loro propietà sono raggiungibili dalla scheda del costruttore LOA39. Dalla stessa è possibile testare le funzioni in termini di performance e dati.