La piattaforma ANTEA prevede due principali tipologie di utenti: l’Istituto Superiore di Sanità (ISS) e i Gestori Idropotabili. Ogni utente gestisce la propria filiera di dati, assicurando che l’accesso sia regolato in base alla responsabilità di ciascuno. Gli utenti hanno la possibilità di delegare l’accesso a una serie di persone all’interno della loro filiera, includendo consulenti e collaboratori temporanei, per la gestione e il monitoraggio dei dati. L’accesso ai dati nel cloud è suddiviso in permessi di lettura e scrittura, secondo le necessità operative e la responsabilità dei vari utenti. Il gestore, sotto la sua responsabilità, può autorizzare la sua filiera di persone ad accedere al cloud per leggere e scrivere i dati. Questo sistema di autorizzazione garantisce che solo personale qualificato e autorizzato possa eseguire operazioni critiche, riducendo il rischio di errori e migliorando l’integrità dei dati.

L’amministratore del cloud ha un ruolo cruciale nel gestire le chiavi di accesso e nel garantire che tutte le operazioni siano monitorate e tracciabili. Gli amministratori possono concedere permessi di sola lettura a specifici reparti o collaboratori, garantendo che l’accesso ai dati sia limitato alle necessità operative. Quindi la responsabilità del caricamento dei dati su AnTea è distribuita tra gli utenti principali (ISS e gestori), che possono delegare l’accesso all’interno della loro filiera, mantenendo un controllo rigoroso e sicuro su chi può accedere e modificare i dati, garantendo così la riservatezza e l’integrità delle informazioni gestite.

L’autorizzazione degli utenti sulla piattaforma Antea di produzione avverrà tramite una richiesta di accesso, che dovrà essere presentata dal responsabile della regione. Questa richiesta sarà validata e autorizzata dal Censia. Una volta ottenuta l’autorizzazione, l’utente potrà autenticarsi tramite SPID (Sistema Pubblico di Identità Digitale) e CIE (Carta d’Identità Elettronica).

Il responsabile della regione avrà inoltre la possibilità di delegare altri dipendenti della stessa azienda o di altre aziende al caricamento dei punti di campionamento. In base ai permessi e alle autorizzazioni fornite, sarà possibile operare nelle proprie aree di competenza. Questo sistema garantisce che solo gli utenti autorizzati possano accedere e gestire le funzionalità della piattaforma Antea, assicurando al contempo la tracciabilità e la sicurezza delle operazioni svolte.

Per accedere all’ambiente di test si veda paragrafo Ambiente di Test.

I programmi di controllo da inserire nella piattaforma corrispondono all’insieme di tutti i punti di campionamento con tutte le informazioni relative e necessarie, ovvero le sedi designate per i prelievi finalizzati ai controlli delle acque.

Le opzioni disponibili per l’inserimento dei programmi di controllo includono:

• Interfaccia Grafica Utente (GUI):
  • Inserimento Singolo : attraverso l’interfaccia della piattaforma, gli utenti possono aggiungere i punti manualmente, uno alla volta.
  • Caricamento tramite file Excel: permette l’importazione di dati in massa utilizzando fogli di calcolo Excel. Il formato del file è definito tra gli allegati.
• API:
  • Caricamento tramite JSON (Elaborazione in Batch): permette agli enti di inserire i piani di controllo all’interno della piattaforma attraverso un unico file JSON contenente tutti i dati.
  • Caricamento Singolo: questa modalità offre la flessibilità di aggiungere dati uno per volta attraverso API, adatta per l’integrazione di sistemi informatici esterni avanzati.

Nelle sezioni successive del documento, verranno fornite specifiche dettagliate e linee guida sui formati accettati per l’inserimento dei dati.

Illustriamo di seguito lo schema dei dati che saranno inviati in piattaforma dai vari attori coinvolti nel processo. Il Modello Entità Relazione (ER) del sistema e la relativa descrizione granulare dei dati in esso contenuti forniranno una struttura dati chiara per guidare la raccolta, l’inserimento e l’analisi dei parametri rilevanti per i Programmi di Controllo.

Il modello ER illustrato di seguito fornisce un quadro strutturato per la gestione dei dati nel contesto della piattaforma AnTeA. In esso si nota che i Programmi di controllo sono composti da N punti di campionamento e ad ognuno di essi sono collegati N “Risultati dei Controlli” Interni o Esterni.

Lo scopo del seguente documento è soltanto il caricamento dei Piani di controllo, mentre per i Risultati dei Controlli si rimanda ad un’altra RFC.

Nella tabella 1, riportata di seguito, sono dettagliati tutti i parametri richiesti in fase di inserimento dei dati che compongono i punti di Campionamento.

Tabella 1 Parametri del Punto di Campionamento

Come si evidenzia dai campi sopra richiesti nel caricamento degli identificativi dei punti di campionamento in coerenza con le direttive ARERA, dovranno essere implementati elementi di caratterizzazione del sistema acquedottistico e dati di portata che dovranno essere congruenti con i dati di popolazione servita.

Ciascun punto di campionamento sarà identificabile mediante un codice di riferimento unico a livello nazionale (uuid), che integrerà diversi elementi informativi. Il codice univoco sarà costituito da quattro campi alfanumerici:

• Il Codice Istat relativo alla Regione;
• Il Codice Istat relativo al Comune;
• Un codice identificativo della specificità del punto di campionamento (Dettagliati nel paragrafo Tipologie dei Punti di Campionamento )
• Un Codice progressivo attribuito per ogni punto di controllo di un singolo Comune.

Questi dati saranno collegati tra loro tramite il simbolo “_”.

Ecco un esempio di codice punto di campionamento per un punto di interesse nella regione Lazio, specificamente per il Comune di Roma:

• Codice Istat Regione (es. Regione Lazio): 12 (Il campo deve essere formattato in modo da avere sempre due cifre, aggiungendo uno zero davanti se necessario);
• Codice Istat Comuni (es. Comune di Roma): 058091;
• Tipologia del Punto di prelievo (es. Serbatoio Interrato): D1;
• Numero del Punto di prelievo assegnato (alfanumerico max 32 char): 121;

Il Codice Univoco (uuid) risultante per il punto di campionamento esemplificativo sarà:

12_058091_SE_121

Tutti i dati presenti nei quattro campi dell’uuid dovranno essere soltanto caratteri alfanumerici maiuscoli e non sarà permesso alcun simbolo speciale.

Espressione regolare di riferimento:

^[A-Z0-9]+$

Al fine di supportare gli enti nella transazione e supporto della seguente RFC si rende disponibile un ambiente di test che permetterà agli interlocutori di testare il funzionamento del portale, i formati di interscambio e le API messe a disposizione.

Per accedere all’ambiente di test, è necessario richiedere le credenziali inviando una email con i seguenti dettagli:

• Codice Istat della Regione;
• Nome e Cognome del richiedente;
• PDF del documento d’identità;
• Email di riferimento, che deve appartenere al dominio dell’ente.

La richiesta deve essere inviata all’indirizzo email: registrazione.antea.test@we-com.it

In risposta, verranno forniti:

• Username
• Password

Quest’ultimi potranno essere utilizzati per accedere all’ambiente di test di AnTeA.

Per facilitare il processo di inserimento dei punti di campionamento, è possibile utilizzare un file Excel per il caricamento automatico all’interno della piattaforma. Questa operazione dovrà essere eseguita attraverso un’interfaccia grafica, progettata per garantire facilità e efficienza nel trasferimento delle informazioni.

Il file Excel deve essere preparato seguendo uno specifico formato, un esempio del quale è disponibile negli allegati al presente documento. È essenziale che la disposizione delle colonne nel file Excel rimanga invariata per assicurare un corretto riconoscimento ed elaborazione dei dati da parte del sistema.

La prima riga del file deve contenere le intestazioni di colonna, essenziali per mappare correttamente i dati ai rispettivi campi nella piattaforma. È importante notare che i parametri definiti come obbligatori nella tabella descrittiva dei campi devono essere presenti nel file Excel, altrimenti il caricamento potrebbe fallire o risultare incompleto.

Il file da caricare deve essere in formato .xlsx.

Il processo di caricamento attraverso API si conforma agli standard dei webservice REST, incorporando l’autenticazione OPENID per garantire la sicurezza. Questo implica l’uso di chiamate HTTPS, impiegando metodi specifici predefiniti, per ottenere le informazioni desiderate che dettaglieremo di seguito nel documento.

In ogni chiamata illustrata nel documento sarà utilizzata la variabile $API_SERVER$ che andrà sostituita con l’ambiente di riferimento specifico:

È reperibile al link https://antea.iss.it/api-per-caricamento-programmi-di-controllo/ la documentazione online in formato OpenAPI che permetterà agli sviluppatori di accedere agevolmente alle API.

All’interno della piattaforma AnTeA , nella sezione “API KEY” dedicata agli utenti che hanno ricevuto le autorizzazioni necessarie attraverso un ruolo specifico o una delega, sarà reso disponibile un ambiente in cui sarà possibile generare un identificativo unico per il client (Client_id) e una chiave segreta (Client_Secret). Queste credenziali sono essenziali per l’accesso e l’utilizzo delle API del sistema. Ogni coppia di Client ID e Secret sarà univocamente associata all’utente che le ha generate, garantendo che solo gli utenti autorizzati possano effettuare operazioni tramite le API. È importante notare che tali credenziali dovranno essere inserite accuratamente nei software o applicativi di riferimento che effettueranno connessioni automatizzate con la piattaforma, al fine di stabilire un flusso di trasmissione dei dati efficiente e sicuro tra gli strumenti utilizzati dagli utenti esterni e il sistema AnTeA.

Seguendo lo standard di riferimento OpenID prima di poter accedere al dato è necessario ottenere un Token di sessione al server IAM. Si delineano quindi le due fasi di seguito:

1. Richiesta del Token:l’applicazione deve inviare una richiesta al server IAM per ottenere un token di autenticazione. Questa richiesta deve includere il client_id ed il client_secret ottenuti nella sezione API KEY una volta effettuato l’accesso con le proprie credenziali su AnTeA.
2. Uso del Token: una volta ottenuto il token, questo dovrà essere utilizzato per effettuare chiamate autenticate alle API protette, dovrà essere inserito nell’header della richiesta nell’apposito campo Bearer Token.

Per ottenere un token di autenticazione, l’applicazione client deve effettuare una richiesta HTTPS POST al server IAM. Di seguito è riportato un esempio di chiamata utilizzando cURL:

curl --location 'https://$IAM_SERVER$/realms/antea/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=$CLIENT_ID$' \
--data-urlencode 'client_secret=$CLIENT_SECRET$'

I seguenti valori dovranno essere sostituiti con i valori reali forniti durante la registrazione dell’applicazione con il sistema IAM:

• $IAM_SERVER$
• $CLIENT_ID$
• $CLIENT_SECRET$

Riportiamo di seguito un esempio di risposta alla chiamata precedente.

{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJTZzQxTlkyYkx5WkxXdGNsdC1SMGZad3p6RUxLSlJxZHF3UUVPQXNWZGJrIn0[……]T1r7vWCPOb5xYJcfERI86DB_S3mxJMYxAQ4sYQDa7GzRqtC8swxkl4EnHWTUd8ysPLcXgJCsZc1NBAXBn2juP2AUJnwMKtbjSmP-4i6BWShx8l_yASlw",
    "expires_in": 36000,
    "refresh_expires_in": 10800,
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJhODUzMjNiZC03MDI1LTRmOTctYjMxYS1jNTkzNDkyNWRiNjMifQ[……]R5pxLwC-utRWzjXQi8QkM0LIOL0Bq9ucgGMJLpC4jjY",
    "token_type": "Bearer",
    "not-before-policy": 1666728811,
    "session_state": "7420a438-a823-4583-b1cb-b7275231246b",
    "scope": "email profile"
}

Il server IAM restituirà un JSON contenente un token di autenticazione (campo access_token ), che dovrà essere utilizzato per effettuare chiamate alle API protette, includendolo nell’header delle richieste HTTP, come Authorization: Bearer .

È possibile utilizzare questa chiamata API per caricare un singolo punto di campionamento nel portale e ricevere una risposta puntuale dell’avvenuto inserimento.

1. Preparazione dei Dati: il gestore prepara un JSON contenente i dati del singolo punto di controllo secondo lo schema definito;
2. Invio dei Dati: il gestore invia i dati tramite una richiesta POST all’endpoint /puntoCampionamento;
3. Ricezione della Risposta: l’API valida i dati inviati e, se corretti, restituirà il codice HTTP 201, insieme a un messaggio di successo. In caso di errore nei dati inseriti sarà indicato l’errore riscontrato.

È possibile effettuare più volte la chiamata al fine di inserire tutti i punti di campionamento.

Nella documentazione online sono disponibili anche le chiamate per effettuare le GET e le PUT (aggiornamento) dei punti di campionamento.

Il caricamento in modalità batch consente di inviare grandi volumi di dati per l’elaborazione in un’unica operazione, ottimizzando l’efficienza e riducendo la necessità di multiple chiamate API.

Il file JSON per l’invio dei dati in modalità batch deve essere strutturato in modo da contenere tutti i dati necessari per l’elaborazione.  Sarà possibile caricare il file JSON  tramite API oppure dalla GUI del programma.

Di seguito è fornito un esempio di come potrebbe essere strutturato il file per l’invio dei Programmi di Controllo contenente 3 punti di controllo distinti:

{
"puntiControllo":
 [
      {
         "uuid": "12_058091_F1_AU00123",
         "istatRegione": 12,
         "istatComune": 58091,
         "tipoPuntoCampionamento": "F1",
         "idPuntoCampionamento": "AU00123",
         "idAreraAto": 1202,
         "idAreraGestore": 13989,
         "codiceAcquedotto": "A1",
         "wsz": "PRIMAVALLE",
         "progressivoLineAcquedottistica": "1",
         "coordinate":
            {
              "epsg": "4326",
              "lat": 41.92916653825498,
              "lon": 12.398053271534483,
              "z": 85.76
            },
         "previsioneAbitantiServiti": 1500,
         "previsionePortata": 690,
         "descrizionePunto": "Fontanella Piazza Viale Indro Montanelli",
         "note": "Fontanella Piazza Viale Indro Montanelli, 00168 Roma RM",
         "numeroCampionamentoAnnuoInternoPrevisto": 0,
         "numeroCampionamentoAnnuoEsterniPrevisto": 10
       }, {
         "uuid": "12_058091_F1_AU00456",
         "istatRegione": 12,
         "istatComune": 58091,
         "tipoPuntoCampionamento": "F1",
         "idPuntoCampionamento": "AU00456",
         "idAreraAto": 1202,
         "idAreraGestore": 13989,
         "codiceAcquedotto": "A1",
         "wsz": "PRIMAVALLE",
         "progressivoLineAcquedottistica": "1",
         "coordinate":
            {
              "epsg": "4326",
              "lat": 41.92916653825498,
              "lon": 12.398053271534483,
              "z": 85.76
            },
         "previsioneAbitantiServiti": 1500,
         "previsionePortata": 690,
         "descrizionePunto": "Fontanella Largo Flanagan Edoardo Giuseppe",
         "note": "Fontanella Largo Flanagan Edoardo Giuseppe, 00168 Roma RM",
         "numeroCampionamentoAnnuoInternoPrevisto": 0,
         "numeroCampionamentoAnnuoEsterniPrevisto": 10
       }, {
         "uuid": "12_058091_FA_SC45",
         "istatRegione": 12,
         "istatComune": 58091,
         "tipoPuntoCampionamento": "FA",
         "idPuntoCampionamento": "SC45",
         "idAreraAto": 1202,
         "idAreraGestore": 13989,
         "codiceAcquedotto": "A1",
         "wsz": "PRIMAVALLE",
         "progressivoLineAcquedottistica": "1",
         "coordinate":
            {
              "epsg": "4326",
              "lat": 41.92916653825498,
              "lon": 12.398053271534483,
              "z": 85.76
            },
         "previsioneAbitantiServiti": 1500,
         "previsionePortata": 690,
         "descrizionePunto": "Fontanella Piazza Viale Indro Montanelli",
         "note": "Fontanella Piazza Viale Indro Montanelli, 00168 Roma RM",
         "numeroCampionamentoAnnuoInternoPrevisto": 0,
         "numeroCampionamentoAnnuoEsterniPrevisto": 10
       }
   ]
}

Per inviare il file JSON è necessario prima convertirlo in una stringa codificata in base64. Successivamente, si potrà utilizzare la chiamata API sotto l’endpoint /api/elaborazione-piani-controllo per inviare file al sistema.

Di seguito esempio cURL per l’invio del file dei piani di controllo:

ACCESS_TOKEN="your_access_token_here"
BASE64_ENCODED_JSON="base64_encoded_string_here"

curl -X POST 'https://$API_SERVER$/elaborazione-piani-controllo' \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H 'Content-Type: application/json' \
-d '{
"type": "application/json",
"base64": "${BASE64_ENCODED_JSON}"
}'

Come risposta alla chiamata si otterrà l’identificativo dell’elaborazione “idElaborazione” da utilizzare per le successive chiamate e capire lo stato dell’elaborazione:

{
   "idElaborazione": "743c071c-8721-451c-a5ae-b5c8b7964",
   "uuidFile": "6ecc6aad-823b-42b9-ba45-eda0e2000b1a",
   "type": "JSON",
   "content": "PIANI_CONTROLLO",
   "statoElaborazione": "SALVATO_SU_DATALAKE",
   "erroreElaborazione": null,
   "note": null,
   "error": null
}

Interrogazione stato elaborazioni in batch

Una volta inviato il file per l’elaborazione in batch, è possibile verificare lo stato delle elaborazioni per controllare l’avanzamento e identificare eventuali errori.

Esempio

ACCESS_TOKEN="your_access_token_here"
curl -X GET "https://$API_SERVER$/elaborazione/743c071c-8721-451c-a5ae-b5c8b7964" \
     -H "Authorization: Bearer ${ACCESS_TOKEN}" \
     -H "Content-Type: application/json"

Sostituire “743c071c-8721-451c-a5ae-b5c8b7964” con l’identificativo unico del batch (idElaborazione) di cui si desidera verificare lo stato. La risposta fornirà informazioni dettagliate sullo stato dell’elaborazione, inclusi eventuali errori. Di seguito alcuni esempi di risposta:

Risposta per elaborazione iniziata

{
  "idElaborazione": "10dad3c8-5ffd-49b6-b7ce-c31ae1f02bff",
  "uuidFile": "b8ec8cc7-1a6b-4a44-b243-b6052517d787",
  "type": "JSON",
  "content": "PIANI_CONTROLLO",
  "statoElaborazione": "SALVATO_SU_DATALAKE",
  "erroreElaborazione": null,
  "note": null,
  "error": null
}

Risposta per Elaborazione Conclusa con il dettaglio delle risorse inserite

{
  "idElaborazione": "10dad3c8-5ffd-49b6-b7ce-c31ae1f02bff",
  "uuidFile": "b8ec8cc7-1a6b-4a44-b243-b6052517d787",
  "type": "JSON",
  "content": "PIANI_CONTROLLO",
  "statoElaborazione":"ELABORAZIONE_CONCLUSA",
  "erroreElaborazione": null,
  "note": "Elaborazione caricamento conclusa: aggiunte 23 entità",
  "error": null
}

Risposta per Elaborazione Conclusa ma andata in errore con il dettaglio delle risorse andate in errore

{
  "idElaborazione": "10dad3c8-5ffd-49b6-b7ce-c31ae1f02bff",
  "uuidFile": "b8ec8cc7-1a6b-4a44-b243-b6052517d787",
  "type": "JSON",
  "content": "PIANI_CONTROLLO",
  "statoElaborazione": "ERRORE",
  "erroreElaborazione": "ERRORE_SALVATAGGIO_NEL_DATABASE",
  "note": "(Errore alla riga 2) Punto campionamento già presente su database (PuntoCampionamento con uuid: 8_099013_F1_EZ123Z )",
  "error": null
}

In questa tabella sono disponibili i codici delle tipologie di prelievo utilizzabili:

Tabella 6 Caratterizzazione Punti di Campionamento

Per supportare gli enti e i gestori nel caricamento dei dati, è stato istituito un canale di assistenza dedicato. Gli utenti di tutti gli enti possono registrarsi per aprire segnalazioni e richiedere supporto in questi ambiti:

• Commento RFC: per inviare commenti e feedback sul seguente documento RFC;
• Problema con Sistema Test: per segnalare malfunzionamenti o difficoltà riscontrate durante l’utilizzo del sistema di test;
• Problemi di Accesso: per risolvere eventuali difficoltà di accesso alla piattaforma o ai sistemi correlati;
• Altro: per qualsiasi altra problematica non categorizzata nei punti precedenti;

Il sistema di assistenza è progettato per essere intuitivo e facilmente accessibile. Per accedere al servizio, è necessario registrarsi al seguente link:

https://anteawecom.freshdesk.com/support/login

Una volta registrati, gli utenti possono aprire nuove segnalazioni, monitorare lo stato delle richieste in corso, e ricevere aggiornamenti e risposte direttamente dal team di supporto. Questo canale punta a migliorare l’efficienza e la qualità del servizio al fine di supportare gli enti nel trasferimento dei dati su Antea.

Per favorire la partecipazione di tutti gli attori coinvolti nel processo di sviluppo del sistema, è possibile commentare questa RFC. I commenti costruttivi aiuteranno ad identificare eventuali modifiche o precisazioni necessarie.

I commenti possono essere inseriti alla fine della pagina o in corrispondenza dei singoli paragrafi utilizzando l’icona verde di commento. Tutti i commenti saranno moderati per garantire che il processo sia il più costruttivo possibile.

Si richiede inoltre di aprire un ticket sul canale di assistenza per fornire i recapiti di chi commenta, in modo da poter essere eventualmente contattati per ulteriori chiarimenti.