# Client Open Source per la Smart City Platform ENEA Oggetto di questo modulo è un client Open Source che permette l'invio o la richiesta da riga di comando 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/ ## Installazione Il pacchetto richiede [Python 3.8](https://www.python.org/) o superiore e [Git](https://git-scm.com/) per l'installazione da repository: ```sh pip install git+https://crossserv.bologna.enea.it/gitlab/cross/scp_udg_client_python_app.git ``` Potrebbe essere necessario eseguire `pip` con i permessi di root: ```sh sudo pip install git+https://crossserv.bologna.enea.it/gitlab/cross/scp_udg_client_python_app.git ``` ### Aggiornamento ```sh pip install --force-reinstall --no-deps git+https://crossserv.bologna.enea.it/gitlab/cross/scp_udg_client_python_app.git ``` ## Avvio rapido Se l'installazione è andata a buon fine sarà possibile eseguire il comando: ```sh python -m scp_udg_client_app.cli ``` L'output sarà simile a: ``` Usage: python -m scp_udg_client_app.cli [OPTIONS] COMMAND [ARGS]... Options: -v, --verbosity LVL Either CRITICAL, ERROR, WARNING, INFO or DEBUG --log-file FILE File where the logs are written to. --log-max-bytes INTEGER RANGE Maximum file size. [default: 10485760; x>0] --log-backup-count INTEGER RANGE Number of files to keep. [default: 10; x>0] --version Show the version and exit. --help Show this message and exit. Commands: last-request Fetch and save the last dataset from an UDG endpoint. push A command-line tool to poll directories and interact... report searching-request Fetch and save datasets from an UDG endpoint. test Test the connection to the UrbanDatasetGateway Web... ``` Per testare l'interazione con un UrbanDatasetGateway predefinito è sufficiente lanciare il comando: ```sh python -m scp_udg_client_app.cli -v DEBUG test ``` L'output sarà simile a: ``` warning: No configuration file found in [C:\Users\NomeCognome\AppData\Roaming\scp-udg-client\config.properties] Testing UrbanDatasetGatewayApi at https://scp-casaccia.bologna.enea.it:8443/webservices/rest/UrbanDatasetGateway debug: Starting new HTTPS connection (1): scp-casaccia.bologna.enea.it:8443 debug: https://scp-casaccia.bologna.enea.it:8443 "POST /webservices/rest/UrbanDatasetGateway/test HTTP/11" 200 None The response of UrbanDatasetGatewayApi->test: {'code': '00', 'message': 'Successful'} ``` Per ciascuno dei comandi `last-request`, `push`, `report`, `searching-request` e `test` si può ottenere aiuto, ad esempio: ```sh python -m scp_udg_client_app.cli test --help ``` Questo il risultato: ``` warning: No configuration file found in [C:\Users\NomeCognome\AppData\Roaming\scp-udg-client\config.properties] Usage: python -m scp_udg_client_app.cli test [OPTIONS] Test the connection to the UrbanDatasetGateway Web Service. Options: --config FILE Read configuration from a Java .properties FILE. [default: C:\Users\NomeCognome\AppData\Roaming\scp-udg- client\config.properties] --udg-endpoint URL URL endpoint for the Urban Dataset Gateway API. [env var: SCP_UDG_CLIENT_TEST_UDG_ENDPOINT; default: https://scp-casaccia.bologna.enea.it:8443/webservices/re st/UrbanDatasetGateway] --help Show this message and exit. ``` Si noti che se `--config FILE` non è specificato, allora il comando tenta di leggere un file di configurazione in formato Java .properties da un percorso predefinito: in assenza di tale file, le opzioni predefinite derivano dalle variabili d'ambiente riportate nel testo di aiuto (se impostate) o da valori di default codificati in modo rigido. Le opzioni dell'**interfaccia a riga di comando** (dall'inglese _command line interface_, in acronimo **CLI**) e dell'ambiente sovrascriveranno le opzioni del file di configurazione. Le opzioni del file di configurazione sovrascrivono le opzioni predefinite nel codice sorgente. Quindi l'ordine di risoluzione per una data opzione è: CLI > Ambiente > File di configurazione > Predefinito ## Opzioni del file di configurazione Per convenzione i nomi delle chiavi da utilizzare nel file di configurazione derivano dai nomi delle opzioni rimuovendo i trattini iniziali e sostituendo gli altri con trattini bassi. Per esempio `--udg-endpoint` diviene `udg_endpoint`. Un esempio di file di configurazione si può trovare qui: [config.properties.example](config.properties.example) ## 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. ----------- ### TODO: 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.