Architettura della soluzione
Introduzione
Ogni installazione di Gestione Interventi si compone di tre elementi:
- il prodotto gestionale (ESOLVER)
- il servizio REST che consente alla app di comunicare con il prodotto gestionale
- la app che viene installata sui dispositivi portatili
Il servizio REST viene eseguito da un server web (Microsoft IIS); può essere installato sullo stesso server in cui si trova il prodotto gestionale, oppure su un server dedicato. La app viene installata sui dispositivi portatili e comunica esclusivamente con il servizio REST; la app non può accedere direttamente al database o alla direttiva base del prodotto gestionale.
Servizio REST
La modalità di funzionamento di un servizio REST è assimilabile a quella di un sito web, dove il client contatta il server per esplorare le pagine del sito. La connessione tra il client e il server avviene grazie ad un indirizzo (URL) che contiene informazioni circa il protocollo, il server, la porta e la pagina da contattare (per es. https://www.emmebit.com:443/index.aspx).
Anche nel caso di un servizio REST, il server web pubblica un sito (il servizio REST) su una determinata porta; il client (la app) contatta il server web tramite un indirizzo e può accedere alle funzioni esposte dal servizio. Ogni funzione esposta dal servizio REST è raggiungibile grazie ad un indirizzo specifico (per es. https://fw.emmebit.com:44300/GestioneInterventiWS/api/UnitaMisura), esattamente come avviene per le pagine di un sito web.
Il servizio REST consente alla app di:
- leggere i dati contenuti nel database del prodotto gestionale
- aprire eventuali file allegati alle entità del prodotto gestionale (per es. gli allegati di un impianto o di un ordine)
- scrivere eventuali allegati nel file system del server. Per esempio le foto allegate ad un rapportino
- scrivere i rapportini registrati tramite la app nelle tabelle di frontiera
App
Gestione Interventi è un'applicazione Android dedicata alla consuntivazione delle prestazioni ed è ottimizzata per l'uso di tablet e smartphone Android.
Maggiori dettagli circa i requisiti di sistema possono essere reperiti in questo articolo.
Connettività
La comunicazione tra la app e il servizio REST può avvenire tramite una qualunque delle connessioni presenti sul dispositivo. Nella maggior parte dei casi i dispositivi si collegano ad un server remoto tramite una rete mobile (per es. 3G, 4G, ...) ma, allo stesso modo, potrebbero collegarsi ad un server locale grazie ad una connessione Wi-Fi. Questa architettura offre una grande flessibilità e permette di installare Gestione Interventi sia on-premises (ovvero in locale), che in cloud.
Gestione Interventi è disponibile anche in SIR.
L'unico requisito essenziale è che i dispositivi possano raggiungere la porta TCP sulla quale il servizio REST si trova in ascolto (per impostazione predefinita la porta 44300). La mancata comunicazione tra la app e il servizio REST è una delle principali cause di malfunzionamento di Gestione Interventi; in questo articolo è possibile trovare maggiori dettagli circa gli errori di connessione più frequenti.
Integrazione con il prodotto gestionale
Nei paragrafi precedenti abbiamo approfondito il ruolo del servizio REST che, in sintesi, rappresenta un'interfaccia di comunicazione tra la app e il prodotto gestionale.
Dal prodotto gestionale a Gestione Interventi
Grazie al servizio REST, le informazioni possono "uscire" dal prodotto gestionale ed essere lette dalla app. La app può leggere, in particolare, i dati anagrafici (per es. articoli, impianti, clienti, ...), gli ordini di lavoro e l'agenda della risorsa, ovvero tutte le informazioni necessarie alla consuntivazione delle prestazioni erogate dall'azienda.
Da Gestione Interventi al prodotto gestionale
Sempre tramite il servizio REST, la app "invia" al prodotto gestionale i rapportini registrati dall'operatore (ed eventuali allegati). Questi documenti non risultano immediatamente visibili in ESOLVER, ma transitano da alcune tabelle di frontiera. Il contenuto di queste tabelle viene interrogato ad intervalli regolari da appositi processi automatici che svolgono specifiche funzioni.
L'intero flusso di trasmissione dei rapportini si articola nei seguenti passaggi:
- la app contatta il servizio REST e invia il rapportino (inclusi eventuali allegati)
- il servizio REST riceve il rapportino e aggiorna le tabelle di frontiera. Le tabelle di frontiera principali sono GestIntTestate (testate dei rapportini), GestIntRighe (righe dei rapportini), GestIntAllegati (allegati dei rapportini e/o degli impianti associati ai rapportini), GestIntMatricole (impianti e/o matricole dei materiali associati ai rapportini)
- il processo GI03, ad intervalli regolari, elabora la tabella GestIntTestate e produce il PDF del rapportino. Se previsto, il PDF viene recapitato per email al cliente
- il processo GI01, ad intervalli regolari, elabora la tabella GestIntTestate e crea il file TXT che verrà acquisito da ESOLVER
- il processo EACQDATI importa il file TXT generato dal processo GI01
- se l'importazione operata dal processo EACQDATI è andata a buon fine, il processo GI01 esegue altri aggiornamenti non gestiti dall'acquisizione documenti di ESOLVER
Nell'immagine sottostante è possibile vedere i tre processi schedulati che caratterizzano qualunque installazione di Gestione Interventi.
Nei prossimi paragrafi verrà descritto in modo più approfondito il ruolo di ogni processo schedulato.
Analizziamo il flusso di trasmissione dal punto in cui il servizio REST ha popolato le tabelle di frontiera (punto n. 2). In particolare, ha aggiornato la tabella GestIntTestate valorizzando queste colonne:
- IdDocumento. Questo ID è un riferimento interno alle tabelle di frontiera e non ha nulla a che vedere con l'IdDocumento che verrà attribuito da ESOLVER al momento dell'importazione (vedi passaggio n. 5 del flusso di trasmissione). La relazione tra la colonna IdDocumento della tabella GestIntTestate e la colonna IdDocumento della tabella OrdLavoroTestata è memorizzata nella tabella GestIntLegami. Il pannello di controllo di Gestione Interventi mostra l'IdDocumento della tabella GestIntTestate quale chiave univoca del rapportino all'interno delle tabelle di frontiera
- Stato. Questa colonna rappresenta lo stato di elaborazione del documento e, in questa fase del flusso, può assumere i seguenti valori:
- 50
. Indica che il documento verrà inviato per email e, successivamente, importato in ESOLVER
- 60
. Indica che il documento verrà solo inviato per email. Al termine dell'elaborazione il documento verrà cancellato dalle tabelle di frontiera e non verrà importato in ESOLVER
- 65
. Indica che la app ha chiesto l'anteprima del documento. Al termine dell'elaborazione il documento verrà cancellato dalle tabelle di frontiera e non verrà importato in ESOLVER
- 70
. Indica che il documento verrà importato in ESOLVER, ma non verrà inviato per email al cliente
GI03, emissione report PDF
Il processo GI03, ad intervalli regolari, controlla se la tabella GestIntTestate contiene uno o più documenti in uno stato tra quelli descritti nel paragrafo precedente (50, 60, 65, 70). Per ogni documento rilevato esegue il report configurato nel pannello di controllo (default = GI_ODL) e produce il rispettivo file PDF. Per gli stati 50 e 70 il PDF del rapportino viene sempre generato e associato al documento; verrà, inoltre, acquisito in ESOLVER nei prossimi passaggi del flusso (come allegato del documento importato).
Al termine della sua elaborazione, il processo GI03 aggiorna la colonna Stato della tabella GestIntTestate scrivendo:
- 0
=> l'elaborazione è andata a buon fine
- 3
=> si è verificata un'anomalia. La colonna DesAnomalie della tabella GestIntTestate contiene la descrizione dell'anomalia. Questa descrizione è visibile anche dal pannello di controllo, lasciando il mouse sull'icona
GI01, elaborazione interventi
Il processo GI01, ad intervalli regolari, controlla se la tabella GestIntTestate contiene uno o più documenti in stato 0 . Per ogni documento rilevato:
- esegue una serie di controlli preliminari:
- in caso di anomalia imposta a 3
- in caso di esito positivo imposta a 1
la colonna Stato di GestIntTestate e prosegue
- crea il file TXT che verrà acquisito da ESOLVER
- attende (per circa 60 secondi) che il file TXT venga importato da ESOLVER. Possono verificarsi queste situazioni:
- il file non viene elaborato (perché il processo di importazione è arrestato o configurato in modo errato) => il file viene rinominato con estensione DAELIMINARE e la colonna Stato della tabella GestIntTestate viene impostata a 2
- il file viene elaborato con esito negativo => vedi paragrafo successivo
- il file viene importato con esito positivo => vedi paragrafo successivo
EACQDATI, importazione OdL/RdI
È importante comprendere che, prima dell'acquisizione operata dal processo EACQDATI, il rapportino inviato dalla app non è ancora visibile tra i documenti di ESOLVER. L'unico programma che può mostrare il rapportino è il pannello di controllo di Gestione Interventi, che legge i dati dalle tabelle di frontiera.
Il modulo EACQDATI deriva dalla funzione standard Acquisizione dinamica documenti di ESOLVER; a questa sono state aggiunte alcune personalizzazioni per assecondare l'integrazione con Gestione Interventi.
Il processo EACQDATI, ad intervalli regolari, controlla la presenza di file TXT nella cartella di scambio. Il percorso della cartella e il nome del file sono definiti nel modello di acquisizione al quale il processo fa riferimento.
Al termine dell'elaborazione di ogni file TXT posso verificarsi due condizioni:
- il file viene elaborato con esito negativo => la colonna Stato della tabella GestIntTestate viene aggiornata a 2
. Il file TXT si troverà con estensione ERR
- il file viene importato con esito positivo => la colonna Stato della tabella GestIntTestate viene aggiornata a 5
Quando l'importazione del file TXT avviene correttamente, il flusso di trasmissione torna in carico al processo GI01 che scrive i dati non gestiti dall'importazione standard (punto n. 6 del flusso).
I file TXT non devono mai essere rinominati con l'obiettivo di farli elaborare nuovamente dal processo EACQDATI. Per rielaborare un rapportino è necessario aprire il pannello di controllo, click destro sul rapportino da rielaborare, infine selezionare la voce Esporta su gestionale.