Indice articolo

Smeup sta arricchendo le sue soluzioni con la creazione di una piattaforma di pubblicazione di servizi web che permettano di interagire con il sistema attraverso strumenti tecnologicamente avanzati, utilizzando i più moderni protocolli e standard (Rest API, GraphQL, Smeup API).
Il primo obiettivo di questa piattaforma è razionalizzare e standardizzare gli strumenti attualmente esistenti in tema di integrazione, a seguire la volontà è quella di estenderla per supportare le nuove funzionalità.
In questo articolo mostriamo il primo risultato di questo lavoro, l’A39Service API.

A39Service API

Come già sappiamo, grazie al precedente articolo, Il costruttore LOA39 è il connettore che permette di esporre tramite un Web Service REST di nome A39Service, quindi su protocollo HTTP, i servizi presenti in Smeup ERP. Tradizionalmente, questo servizio viene esposto dallo Smeup Provider. Nell’ambito dell’evoluzione delle nostre soluzioni, abbiamo deciso di rendere autonoma questa funzionalità portandola sotto forma di applicazione containerizzata per renderla di più facile installazione e manutenzione. A tale scopo abbiamo  portato l’A39Service all’interno di una applicazione autonoma, per non fare dipendere questa funzionalità dalla presenza di un Provider.

Nomenclatura

Facendo questo porting, si è deciso di rivedere anche la nomenclatura degli “oggetti” in azione. Vedremo infatti che le FUN vengono definite come delle azioni o actions, mentre quello che prima era definito come A39.SUBMET ora viene chiamato alias.

Endpoint esposti

Nel nuovo A39Service vengono esposti diversi endpoint che ci permettono di interagire con il costruttore LOA39 e i suoi script:

  • un primo endpoint ci permette di recuperare la lista di tutti gli alias e le corrispettive FUN definite all’interno degli script LOA39 presenti su AS400.
  • un altro ci restituisce il dettaglio di un singolo alias che andiamo a richiamare.
  • un terzo ricarica gli script presenti su AS400, utile quando creiamo un nuovo script o effettuiamo una modifica ad uno script esistente.
  • infine, il più importante, quello che permette di lanciare una FUN a tutti gli effetti, richiamando il suo alias. A questa chiamata va eventualmente poi passato un oggetto JSON, contenente in formato chiave-valore tutte le variabili della FUN che vanno risolte.

Sicurezza tramite API Key

Per questioni di sicurezza è stato inserito un sistema di autenticazione tramite API Key per l’accesso agli endpoint. API Key che verrà inserita nell’apposito file di configurazione dell’applicazione o definita come variabile d’ambiente, a seconda del tipo di deployment che decideremo di utilizzare. Questo ci permette di proteggere la nostra applicazione anche nel caso venisse pubblicata su rete pubblica.

Response

La response che arriva effettuando le chiamate agli endpoint ed eseguendo le actions sono di default in formato JSON, e non più in formato XML come in precedenza. Gli XML di albero e matrice generati come risposta delle FUN vengono infatti tradotti nei corrispettivi JSON prima di essere restituiti al client all’interno di una struttura di risposta predefinita che è la seguente:

{   
  "messages": [    
    {   
      "gravity": "INFO",   
      "text": "string",   
      "fulltext": "string",   
      "level": "string",   
      "type": "INFO",   
      "mode": "TN"   
    }   
  ],   
  "payload": {},    
  "model": {}
}

Dove nel parametro “messages” troviamo delle informazioni generali sulla risposta, le quali ci aiuteranno a capire anche eventuali errori applicativi, mentre la risposta effettiva della nostra chiamata la troveremo nel parametro “payload”.

Transformer

Per questo porting al momento abbiamo deciso di implementare solo il Post-Tranformer TransformerCDATAFromXML, il quale va  definito correttamente nello script SCP_SET LOA39_XX.

::A39.PSTTRS Name="Transformer Post" Value="com.smeup.api.apiservice.models.actions.TransformerCDATAFromXML"

Il set di Pre e Post Transformer è però in evoluzione e con il tempo, anche a fonte di richieste che ci perverranno, integreremo il pacchetto Pre e Post Transformer implementandone altri.

Installazione

Per poter installare questa applicazione sono disponibili due formati: immagine docker o la tradizionale Web Application (WAR file).

Deployment con Docker

Se scegliamo il deployment con docker, dovremo inizialmente lanciare uno script bash di setup (setup.sh), il quale andrà a preparare l’ambiente corretto per il deploy di questa applicazione. Lo script deve avere il seguente contenuto:

#!/bin/sh
mkdir logs
echo
smeup.system=
 smeup.user=
 smeup.pwd=
 smeup.env=
 smeup.ccsid=1144
 smeup.rowsPerPage=300
 smeup.minIdle=2
 smeup.maxIdle=8
 smeup.maxTotal=32
 smeup.a39Key=
 smeup.restApiKey=

Successivamente basterà scaricare l’immagine docker dal docker-registry di smeup e lanciare l’esecuzione del container, seguendo questi passi:

  • Eseguire un docker pull dell’immagine:
    > docker pull docker-registry.smeup.cloud/smeup/a39-api
  • Lanciare poi il docker run, andando a specificare l’ApiKey, se non l’abbiamo già messa nel file di configurazione:
    > docker run -dp 6090:8080 --name api-container -e A39KEY="<a39-apikey>" -v $(pwd)/smeup.properties:/opt/payara/etc/smeup-rest-api/smeup.properties -v $(pwd)/logs:/opt/payara/var/smeup-rest-api/api/log docker-registry.smeup.cloud/smeup/a39-api

Per effettuare cambiamenti al file di configurazione (cambiare API keys, ambiente o utente per la connessione ad AS400), basterà eliminare il vecchio container (se presente), cambiare le configurazioni nel file smeup.properties, ed eseguire nuovamente il comando docker run scritto qua sopra.

Deployment tradizionale

Con il deployment tradizionale invece sarà necessario deployare il file .war (scaricabile a questo link) in un application Server Payara, ma solo dopo aver creato e compilato il file di configurazione dell’applicazione sotto il path: {USER-HOME}/etc/smeup-rest-api/smeup.properties.

Log

Una parte fondamentale nella gestione di un’applicazione è sicuramente il recupero dei log per andare ad analizzare eventuali problemi o errori. Per questa applicazione, la modalità di fruibilità dei log varia a seconda del tipo di deployment che abbiamo scelto. Se abbiamo utilizzato docker, troveremo i log nella cartella di installazione (quella dove abbiamo lanciato lo script di setup), grazie ad un mount che viene fatto in fase di avvio del container. Al contrario se usiamo la tradizionale Web Application, i log vanno recuperati all’interno dei log dell’application server Payara.

Swagger

Per testare gli endpoint e per verificare che l’applicazione sia funzionante, viene messa a disposizione anche un interfaccia Swagger, tramite la quale è possibile effettuare in effettivo le chiamate agli endpoint esposti e vedere la risposta che viene restituita.

L’indirizzo per accedere all’interfaccia swagger è: http://address:port/apiservice/swagger/index.html


smeup.system=\nsmeup.user=\nsmeup.pwd=\nsmeup.env=\nsmeup.ccsid=1144\nsmeup.rowsPerPage=300\nsmeup.minIdle=2\nsmeup.maxIdle=8\nsmeup.maxTotal=32\nsmeup.restApiKey=api\nsmeup.a39Key=a39' > smeup.properties Dopo aver lanciato il file di setup dovremo compilare correttamente il file di configurazione (smeup.properties) che si presenta così:

Successivamente basterà scaricare l’immagine docker dal docker-registry di smeup e lanciare l’esecuzione del container, seguendo questi passi:

  • Eseguire un docker pull dell’immagine:

  • Lanciare poi il docker run, andando a specificare l’ApiKey, se non l’abbiamo già messa nel file di configurazione:

Per effettuare cambiamenti al file di configurazione (cambiare API keys, ambiente o utente per la connessione ad AS400), basterà eliminare il vecchio container (se presente), cambiare le configurazioni nel file smeup.properties, ed eseguire nuovamente il comando docker run scritto qua sopra.

Deployment tradizionale

Con il deployment tradizionale invece sarà necessario deployare il file .war (scaricabile a questo link) in un application Server Payara, ma solo dopo aver creato e compilato il file di configurazione dell’applicazione sotto il path: {USER-HOME}/etc/smeup-rest-api/smeup.properties.

Log

Una parte fondamentale nella gestione di un’applicazione è sicuramente il recupero dei log per andare ad analizzare eventuali problemi o errori. Per questa applicazione, la modalità di fruibilità dei log varia a seconda del tipo di deployment che abbiamo scelto. Se abbiamo utilizzato docker, troveremo i log nella cartella di installazione (quella dove abbiamo lanciato lo script di setup), grazie ad un mount che viene fatto in fase di avvio del container. Al contrario se usiamo la tradizionale Web Application, i log vanno recuperati all’interno dei log dell’application server Payara.

Swagger

Per testare gli endpoint e per verificare che l’applicazione sia funzionante, viene messa a disposizione anche un interfaccia Swagger, tramite la quale è possibile effettuare in effettivo le chiamate agli endpoint esposti e vedere la risposta che viene restituita.

L’indirizzo per accedere all’interfaccia swagger è: http://address:port/apiservice/swagger/index.html