README.md

# 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.