# Client Open Source per la Smart City Platform ENEA Oggetto di questa attività è l'ingegnerizzazione di un client Open Source che permetta l'invio o la richiesta di UrbanDataset a una generica SCP implementata secondo le specifiche SCPS Communication di ENEA disponibili al seguente link: https://smartcityplatform.enea.it/#/it/specification/communication/2.0/ ## Introduzione alle Specifiche SCPS Le [Smart City Platform Specification][1] (SCPS) for Interoperability Layer sono specifiche pubbliche definite dai laboratori TERIN-ICER-CROSS e TERIN-ICER-SCC di ENEA per permettere una comunicazione interoperabile tra sistemi in ambito Smart City. Scopo delle SCPS è permettere a una Piattaforma ICT di gestione della città (o del distretto) di adottare un approccio condiviso per comunicare con le diverse Piattaforme Verticali che insistono sullo stesso tessuto urbano e così fornire uno strumento alle municipalità, svincolandosi da soluzioni proprietarie chiuse. La "SmartCityPlatform" (SCP) è un software prototipale sviluppato da ENEA per dimostrare l'usabilità e l'applicabilità delle specifiche SCPS sviluppate dagli stessi laboratori di ENEA per favorire l'interoperabilità delle applicazioni verticali in ambito Smart City con una piattaforma centrale di monitoraggio su scala cittadina, denominata SCP. ## Obiettivo dell'attività Al momento lo sviluppo di client compatibili con le SCPS in grado di comunicare con una SCP è lasciato a chi voglia utilizzare le specifiche. Con questa attività si vuole sviluppare un Client Open Source da mettere a disposizione, insieme agli altri [strumenti già disponibili][2] per favorire la diffusione delle SCPS. [1]: https://smartcityplatform.enea.it/#/it/specification/index.html [2]: https://smartcityplatform.enea.it/#/it/tools/index.html ### Specifiche tecniche Il client finale dovrà: * essere compatibile con le specifiche SCPS Communication di ENEA * essere multipiattaforma: Linux / Windows * essere realizzato in linguaggio Python * essere strutturato in modo da poter mettere il codice a disposizione come Open Source (e corredato di adeguata licenza) * essere disponibile in forma di eseguibile facilmente installabile anche per chi non conosce Python su diverse piattaforme * produrre log di attività ed errori in apposito file di log dettagliato * essere configurabile tramite file di testo, p.es. scp-ws-client.properties che conterrà, tra le altre, le seguenti proprietà: scp.name=SCP-DARE client.name=Solution-1_CounterReading-2.0 gui.url=https://scp.dare-ravenna.eu:8445/enea-gui/ udg.endpoint= https://scp.dare-ravenna.eu:8443/webservices/rest/UrbanDatasetGateway/ user.name=[username] user.password=[password] Si vedano nel testo seguente altre proprietà configurabili. * essere istanziabile più volte. Per esempio, si potrà avere lo stesso client, configurato in modo diverso, in diverse directory quali: \opt\scp-ws-client\Solution-1_Whatever-2.0\ \opt\scp-ws-client\Solution-1_CounterReading-2.0\ ### Implementazione della chiamata al metodo push Il client finale dovrà: * effettuare il login e salvare il token, riutilizzandolo finché valido, si veda best practice B1 https://smartcityplatform.enea.it/#/it/specification/communication/2.0/index.html#bestpracticeclientws * essere un processo in esecuzione in attesa di UrbanDataset (UD) nella cartella "Outbox", dove verranno depositati gli UD che devono essere inviati. Proprietà configurabili: outbox.dir=Outbox inbox.dir=Inbox * i file UD da inviare devono rispettare la seguente convenzione: [resource_id]_-_[timestampUD].json p.es. `SCP-99_TestSolution-1_Whatever-2.0_20221104000000_-_20230216123600.json` utilizzando la prima parte `resource_id` direttamente nella push, mentre la seconda parte serve solo per rendere univoco l'UD generato evitando errate sovrascritture; * mantenere una copia degli UD inviati (codice "02") in "OKSent" per un certo periodo configurabile, dopo il quale periodo il file viene cancellato. Proprietà configurabile: oksent.dir=OKSent * gestire i tentativi non riusciti di invio alla SCP nella cartella "NOSent". Proprietà configurabile: nosent.dir=NOSent * dentro la cartella NOSent ci saranno tante cartelle quanti i codici di errore ritornati, questo permetterà un facile riepilogo nel report periodico, p.es. "10", "11", ecc. si veda https://smartcityplatform.enea.it/#/it/specification/communication/2.0/index.html#codicidiritorno * gestire il re-invio, parametrizzabile. Proprietà configurabili: # Directory interne a NOSent, soggette a retry retry.dirs=10,11,12 # Numero di tentativi di re-invio retry=4 # Frequenza, espressa in minuti, tra un invio e l'altro in caso di retry retry_frequency=9 N.B. sarebbe più efficace una frequenza variabile crescente, p.es. avendo retry=4, retry_frequency=9, potremmo avere - retry1 dopo 9 minuti; - retry2 dopo 9*9 =81 minuti (1h 21m); - retry3 dopo 9*9*9 =729 minuti (circa 12h 09m); - retry4 dopo 9*9*9 *9 =6.561 minuti (4g 13h 21m) * effettuare validazione JSON e schematron di UD in uscita (le librerie JAVA per la validazione schematron dei JSON potranno essere fornite da ENEA) ### Implementazione delle chiamate ai metodi lastRequest e searchingRequest Tutti i parametri della chiamata saranno configurati nel file di properties; gli UD recuperati saranno salvati nella cartella Inbox, come per il metodo push, i file UD da inviare devono rispettare la seguente convenzione: [resource_id]_-_[timestampUD].json p.es. `SCP-99_TestSolution-1_Whatever-2.0_20221104000000_-_20230216123600.json` la prima parte è il `resource_id`, mentre la seconda parte che è il timestamp dell'UD, serve per rendere univoco l'UD recuperato evitando errate sovrascritture. ### Invio report periodico via mail Il client finale dovrà inviare report periodico via mail (con periodicità espressa in giorni e indirizzo email configurabili). Proprietà configurabili: email.address=angelo.frascella@enea.it email.frequency=7 p.es. 1 email ogni 7 giorni di questo tipo: ----------- REPORT Client: Solution-1_CounterReading-2.0 Frequenza email: 7 giorni SCP: SCP-DARE GUI URL: https://scp.dare-ravenna.eu:8445/enea-gui/ UDG Endpoint: https://scp.dare-ravenna.eu:8443/webservices/rest/UrbanDatasetGateway/test/ UrbanDataset Outbox: 0 Inbox: 0 OKSent: 2345 NOSent: 3 SE NOSent!=0, mandiamo il dettaglio delle cartelle interne NOSent/10: 3 NOSent/11: 5 NOSent/12: 0 ecc. Codici di Ritorno: https://smartcityplatform.enea.it/#/it/specification/communication/2.0/index.html#codicidiritorno Questa è un e-mail automatica inviata dal modulo software "SCP UDG WS Client", progettato e commissionato da ENEA, sviluppato da Kerberos Srl, di proprietà di ENEA. ----------- ### Know-how e supporto * documentazione per developer * manuale di utilizzazione Il codice sorgente del software è di proprietà di ENEA, sotto la supervisione dei laboratori TERIN-SEN-CROSS e TERIN-SEN-SCC. ## Installazione ed uso ### pip install Se il pacchetto python è ospitato su un repository, puoi installarlo direttamente usando: ```sh pip install git+https://crossserv.bologna.enea.it/gitlab/cross/scp_udg_client_python_app.git ``` (potresti dover eseguire `pip` con i permessi di root: `sudo pip install git+https://crossserv.bologna.enea.it/gitlab/cross/scp_udg_client_python_app.git`) Quindi esegui il comando: ```sh scp-udg-client-app ```