La piattaforma OpenCity Italia semplifica la realizzazione e la gestione di servizi digitali per cittadini e imprese, anche da smartphone (art. 7 CAD).

OpenCity Italia è open source, scaricabile da Developers Italia o disponibile come servizio pronto all'uso (Software as a Service).

La piattaforma è sviluppata con l'obiettivo di erogare servizi per centinaia di Enti contemporaneamente da una singola installazione, per questo motivo il codice della piattaforma è organizzato in microservizi indipendenti tra loro e il dialogo tra gli stessi è realizzato mediante stream di eventi piuttosto che mediante chiamate dirette alle API.

Per queste scelte l'installazione e la gestione della piattaforma in un ambiente di produzione richiede un ampio ventaglio di conoscenze:

• Sistema Operativo GNU/Linux e uso della command line (CLI)

• database PostgresQL, MongoDB, Redis

• Docker e sistemi di orchestrazione di container

• Kafka e KsqlDB

Per contribuire alla piattaforma, a seconda dell'area su cui si desidera sviluppare sono necessarie cometenze nei seguenti linguaggi di programmazione:

• PHP

• NodeJS

• Python

• Golang

Infine la piattaforma è in costante evoluzione e nuovi componenti vengono aggiunti o prendono il posto di componenti esistenti divenuti obsoleti.

Ogni servizio è autonomo e deve implementa una singola funzionalità all'interno di un contesto delimitato. Un contesto delimitato è una divisione naturale all'interno di un Ente e fornisce un limite esplicito all'interno del quale esiste un modello di dominio.

Ogni microservizio della piattaforma è distribuito come docker container, ha un proprio versionamento ed espone una o più porte per comunicare con l'esterno.

I microservizi sono esposti all'esterno da un web router che assolve solitamente anche il ruolo di terminatore di SSL.

Ad ogni release della piattaforma vengono aggiornati uno o più microservizi.

Per ulteriori dettagli si veda https://gitlab.com/groups/opencity-labs/-/milestones

La piattaforma può offrire sia una esperienza completa al cittadino o all'impresa, che consente l'invio di pratiche e la loro gestione nel backend, sia farsi carico di uno solo di questi aspetti, lasciando ad altri sistemi il ruolo di interfaccia con il cittadino o a sistemi verticali il compito di gestire pratiche (pratiche edilizie o in ambito sociale)

In presenza di questa esigenza è importante che la piattaforma e il sistema terzo siano in grado di instaurare e mantenere nel tempo la relazione tra le pratiche, mantenere aggiornati lo stato della pratica o di un pagamento pendente per la stessa.

Vari strumenti nella piattaforma consentono di mantenere aggiornate le informazioni e ricevere aggiornamenti:

1. API ReST

2. Webhook

Prima di entrare nei dettagli di questi strumenti merita avere uno sguardo di insieme del flusso della pratica e di tutti gli stati che può attraversare. Nel grafico che segue il tratto continuo più forte rappresenta il flusso più frequente di una pratica, il tratto punteggiato rappresenta i flussi alternativi. I cerchi costituiscono gli stati finali di una pratica

Per una visione generale di tutti gli stati che una pratica può assumere e quali sono i cambi di stato ammessi segue un grafico più generale. Nel grafico sono evidenziati in azzurro gli stati fondamentali della pratica, mentre in grigio gli stati deprecati.

Core

Il componente principale, il core, è ovviamente il frutto del lavoro dei primi anni di sviluppo della piattaforma, ed assolve ai compiti principali della stessa:

1. Definizione e organizzazione dei Servizi Digitali

2. Definizione dei Moduli on-line

3. Gestione delle Pratiche inviate dai cittadini e dei messaggi

4. Gestione degli utenti

5. Gestione Uffici e appuntamenti on-line su slot di tempo e orari di apertura.

6. Gestione Sale pubbliche e altre risorse a prenotazione flessibile

Il core assolve anche al compito di interfaccia utente, sia per i cittadini che per gli operatori e gli amministratori degli Enti.

Il core è costituito dai seguenti microservizi:

• Caddy / Symfony App (dal 2023 i due servizi sono distribuiti in una immagine unica: registry.gitlab.com/opencontent/stanza-del-cittadino/core/app) Nota

• Form Server, implementazione del server di Form.IO: registry.gitlab.com/opencontent/stanza-del-cittadino/form-server

• Form Builder, un editor multi-tenant con accesso riservato agli amministratori della piattaforma per l'editing dei componenti condivisi dei form degli Enti: registry.gitlab.com/opencontent/stanza-del-cittadino/formbuilderjs

• Varnish, un cache proxy server che incrementa l'affidabilità e la scalabilità del formserver e del catalogo dei servizi: registry.gitlab.com/opencontent/varnish:latest

• Gotenberg, a Docker-powered stateless API for PDF files: gotenberg/gotenberg:7

• Payment Updates, ascolta gli eventi relativi ai pagamenti e aggiorna le pratiche di conseguenza: registry.gitlab.com/opencontent/stanza-del-cittadino/payment-updater

• Signature Check, api usata dal componente sdc_upload di form.io per validate le firme dei documenti firmati .p7m: geopartner/signcheckwebapi:latest

Per un esempio completo di deploy dei microservizi si veda il file nel repositoy del core, che fornisce una configurazione funzionante della piattaforma.

Utilizza inoltre i seguenti servizi di persistenza:

• PostgreSQL, per la gestione di tutti i dati e delle configurazioni della piattaforma, ad eccezione delle form. La versione usata in sviluppo è la 11 e comprende anche l'estensione PostGIS: postgis/postgis:11-3.3-alpine

• MongoDB, per la persistenza dei moduli realizzati con l'editor di Form.IO: mongo:4.2

• Redis, per la gestione delle sessioni degli utenti e della cache applicativa: redis:5-alpine.

Introduzione

L’area personale di OpenCity Italia è progettata per integrarsi con vari intermediari di pagamento utilizzati da Comuni ed enti pubblici. Questa sezione descrive i requisiti tecnici necessari per sviluppare e implementare l'integrazione tra la piattaforma e l'intermediario di pagamento PagoPA.

Le interazioni avvengono in seguito ad alcune azioni da parte dei cittadini e degli operatori:

• Invio di una pratica da parte del cittadino

• Approvazione di una pratica da parte di un operatore nel caso di un pagamento posticipato

• Importazione di dovuti da parte dell'operatore mediante API file csv

• Pagamento di un dovuto da parte del cittadino a seguito dell'importazione di quest'ultimo

Requisiti Generali

Per sviluppare l'integrazione con l'intermediario di pagamento PagoPA, sono richiesti i seguenti elementi:

• Documentazione Tecnica: Manuali, guide e riferimenti API.

• Endpoint/Ambiente di Test: URL degli endpoint e accesso a un ambiente di test per effettuare chiamate API.

• Modalità di Verifica dello Stato del Pagamento: Specifiche delle modalità di verifica dello stato del pagamento, tramite polling o notifica.

Dettagli Tecnici dell'Integrazione

Per integrare OpenCity Italia Area Personale con l’intermediario di PagoPA, sono necessari i seguenti parametri minimi:

Creazione di un Pagamento

• Parametri per la creazione di un pagamento

• Parametri per la creazione di una Marca da Bollo Digitale

• Restituzione del numero IUV e/o del numero avviso in fase di creazione del pagamento

Scaricamento Documenti

• Parametri per scaricare l’avviso di pagamento cartaceo

• Parametri per scaricare la ricevuta telematica una volta effettuato il pagamento

Dovuto

• API per il download degli importi dovuti (se disponibile)

Specifiche delle API

L’intermediario di pagamento deve fornire documentazione dettagliata delle API, comprensiva di:

• Endpoint

• Metodi supportati (GET, POST, etc.)

• Parametri richiesti e facoltativi

• Formato dei dati (JSON, XML)

• Esempi di richieste e risposte

Configurazione di Rete

Per garantire le comunicazioni fra la piattaforma e l’intermediario di pagamento, è necessario sbloccare gli IP delle chiamate entranti verso gli endpoint dell’intermediario di pagamento. Gli IP di OpenCity da sbloccare sono:

• 93.41.234.251/32

• 78.47.94.152/32

• 54.220.150.231/32

• 63.33.155.248/32

• 37.186.144.203/32

Supporto Tecnico

Per risolvere eventuali complicazioni, errori o bug durante l'integrazione, è fondamentale avere un contatto tecnico dedicato. Si prega di fornire i seguenti dettagli del contatto tecnico:

• Nome

• Email

• Telefono

• Disponibilità (orari di lavoro)

La piattaforma è responsabile della gestione della protocollazione dei documenti derivanti dai diversi processi burocratici che essa offre. Il documento generato è conforme alle linee guida stabilite dall'AGID(si veda la sezione Documento digitale). Esso è soggetto a protocollazione in determinati casi. Tale processo viene eseguito attraverso l’integrazione con un sistema di protocollazione esterno. Nella seguente sezione verrà esaminato in dettaglio come tale integrazione deve essere fatta, descrivendo gli attori, i componenti coinvolti e le loro interazioni.

La generazione di documenti varia a seconda del tipo di pratica che deve essere registrata o gestita. Ci sono diverse tipologie di pratica, ognuna delle quali corrisponde a uno stato specifico della procedura:

1. Creazione di una pratica da parte o per conto di un cittadino (application-request): questo si riferisce alla creazione iniziale di una pratica da parte di un cittadino o da parte di qualcuno agendo per conto del cittadino.

2. Invio di una richiesta di integrazioni da parte di un operatore (integration-request): questo si verifica quando un operatore richiede ulteriori informazioni o documenti relativi a una pratica.

3. Invio di un'integrazione da parte del cittadino (integration-response): In questo caso, il cittadino risponde alle richieste di integrazione inviando ulteriori documenti o informazioni.

4. Approvazione/rifiuto di una pratica da parte di un operatore (application-outcome, application-revocation): questo rappresenta l'atto di approvare o rifiutare una pratica da parte di un operatore.

5. Ritiro di una pratica da parte di un cittadino (application-withdraw): un cittadino può ritirare una pratica in qualsiasi momento.

Queste tipologie rappresentano diversi stati o fasi attraverso cui una pratica può passare durante il suo ciclo di vita. Poiché una pratica può attraversare più di uno di questi stati, ciò significa che saranno generati diversi documenti associati alla stessa pratica, ognuno dei quali corrisponderà a una fase specifica del processo.

Streaming eventi: gli eventi vengono scritti in un log. Gli eventi sono rigorosamente ordinati (in una partizione) e durevoli. I client non sottoscrivono il flusso, ma un client può invece leggere da qualsiasi parte del flusso. Il client è responsabile di far avanzare la propria posizione nel flusso. Questo significa che un client può aggiungersi in qualsiasi momento e può riprodurre gli eventi.

Elaborazione del flusso di eventi. Usare una piattaforma di flussi di dati come Apache Kafka, come pipeline per inserire gli eventi e fornirli agli elaboratori di flussi. Gli elaboratori di flussi intervengono per elaborare o trasformare il flusso. Possono essere presenti più elaboratori di flussi per sottosistemi diversi nell'applicazione.

Una API ReST, nota anche come API RESTful, è un'interfaccia di programmazione delle applicazioni (API o API web) conforme ai vincoli dello stile architetturale ReST, che consente l'interazione con servizi web RESTful. Il termine REST, coniato dall'informatico Roy Fielding, è l'acronimo di REpresentational State Transfer.

La documentazione delle API ReST della piattaforma è pubblicamente disponibile in ogni Ente all'indirizzo:

Ad esempio per il comune demo della piattaforma è possibile consultarle alla pagina:

Autenticazione

Alcune API richiedono un'autenticazione prima di essere chiamate, in questo caso un cittadino o un operatore possono usare le proprie credenziali per ottenere un token di autenticazione come segue:

Richiesta token di autenticazione

POST https://servizi.comune.bugliano.pi.it/lang/api/auth

Con questa chiamata si riceve un token di autenticazione in formato JWT, che dovrà essere inviato per tutte le successive chiamate che richiedono autenticazione come bearer token nell'header Autorization

Request Body

Alcuni esempi di chiamate

Esempio di chiamata da linea di comando con il client Httpie:

echo '{ "username": "my-api-user", "password": "xxxx" }' | \
http post https://servizi.comune.bugliano.pi.it/lang/api/auth

Esempio di chiamata da linea di comando con il client curl:

curl \
--header 'Content-Type: application/json' \
--data $'{\n "username": "my-api-user",\n "password": "xxxx"\n}' \
https://servizi.comune.bugliano.pi.it/lang/api/auth 

Versioni delle API

Le API sono disponibili in due versioni, la "1" e la "2". Le capacità delle API sono le stesse per le due versioni, nella versione 2 c'e' una migliore gestione del formato JSON, quindi si consiglia l'uso della versione più recente.

È possibile specificare la versione delle Api che si vanno ad interrogare, questo è possibile in 2 modi differenti:

• tramite parametro version da passare come parametro delle GET

• tramite parametro X-Accept-Version da specificare nell' header della richiesta

La versione di default è per retrocompatibilità la 1

Dalla versione 2 le chiavi dei valori del campo data delle applications non sono più restituite come un insieme di strighe piatto separato dal punto (.) ma come campo json con le chiavi esplose.

Nota bene: si raccomanda di specificare sempre la versione di API utilizzata, anche se è il default (1), perche' in futuro il default potrebbe cambiare.

Le API non sono sufficienti per realizzare una buona integrazione tra due sistemi. Se due o più sistemi si devono aggiornare reciprocamente in base agli eventi che avvengono al proprio interno, è necessario che periodicamente ogni sistema interroghi gli altri per sapere se il loro stato è cambiato: questo approccio si chiama anche polling. Questo è molto oneroso e introduce un ritardo nell'aggiornamento che è tanto maggiore quanto maggiore è l'intervallo con cui un sistema interroga gli altri. D'altra parte se di intensifica la frequenza del polling si avranno maggiori costi a fronte di aggiornamenti magari poco frequenti.

Un modo più efficiente di far dialogare due sistemi è avviare una comunicazione in occasione di cambiamenti rilevanti per il sistema in ascolto e per ottenere questo, eliminando del tutto la necessità di fare polling, è possibile usare i Webhook.

Ogni webhook consente di inviare un aggiornamento a una API di un altro sistema che sta ascolto, in base agli eventi che si desidera comunicare.

Per fare test sui webhook si consiglia di utilizzare un servizio come Request Inspector.

1. Installazione

Aggiungi dentro il tag <head> della tua pagina questi riferimenti:

2. Utilizzo del tag <widget-formio>

Posiziona <widget-formio> nel punto della pagina in cui vuoi mostrare il form:

Attributi

3. Storybook & Demo

Tutte gli esempi dei servizi sono documentati in Storybook:

4. Configurazione Servizi Built-in Personalizzati

Per aggiungere o personalizzare un servizio built-in esistente (Richiedi assistenza, Prenota appuntamento, ecc.), è necessario configurare il campo identifier come amministratore nella sezione dettaglio del servizio.

• Il valore di identifier deve seguire il formato: <nome-servizio>-custom dove:

  • <nome-servizio> è obbligatorio e corrisponde al servizio di base (helpdesk, bookings, ecc.)

  • -custom è suffisso libero a scelta per distinguere la versione personalizzata

Esempi:

• helpdesk-custom per una versione custom di Richiedi assistenza

• bookings-custom per una versione custom di Prenota appuntamento

Questa configurazione permette al widget di riconoscere e caricare il servizio personalizzato attraverso il tag <widget-formio>.

Test delle chiamate SOAP/REST dell'intermediario

Le API fornite nella documentazione dell'intermediario vengono generalmente testate in prima battuta via Postman/Insomnia nel caso di chiamate REST o via SoapUI nel caso di chiamate SOAP

Test in ambiente locale

A seguito dei test delle chiamate, si procede con l'implementazione del microservizio. Per l'ambiente di sviluppo viene utilizzato Docker e Docker compose come da esempio nel seguente repository :

Panoramica

La configurazione dei pagamenti avviene interrogando delle API apposite fornite dal proxy di riferimento. Quest'ultimo fornisce inoltre un form come json schema sviluppato con form.io mediante il quale l'utente inserisce tali configurazioni.

Per creare un form utilizzare il seguente builder: https://formio.github.io/formio.js/app/builder

Creazione di un pagamento

Un pagamento nasce da una interazione con il cittadino: il cittadino presenta una pratica per la quale l'Ente richiede un pagamento.

Il cuore dell'integrazione con un intermediario di pagamento è un microservizio apposito che dialoga con l'intermediario da un lato, implementando le chiamate specifiche in protocollo ReST o SOAP, e con il core della piattaforma dall'altro lato, mediante la lettura e la scrittura su un topic di Kafka.

Componenti coinvolte

Componenti del core della piattaforma

In questo momento i pagamenti hanno una relazione 1 a 1 con le pratiche, di conseguenza ci sono due servizi che fanno da intermediari tra le pratiche e i pagamenti, ovvero il payment dispatcher e il payment updater.

Core

È l’interfaccia dalla quale l’utente usufruisce di un servizio digitale, inserendo i dati di una pratica attraverso un modulo: se il servizio prevede un pagamento, i dati di questo sono presenti nella descrizione JSON della pratica e saranno utilizzati dal dispatcher per creare il pagamento.

Payment dispatcher

È il microservizio che, a partire dall'evento di una pratica nel topic applications, crea l'evento del pagamento nel topic payments.

Payment dispatcher API

È il microservizio che sostituirà il Payment Dispatcher, esso, anziche leggere l'evento di una pratica dal topic applications, esporrà un API che, quando chiamata, crea l'evento del pagamento nel topic payments. Questo permette di avere una soluzione unica per gestire tutti i flussi di pagamento della piattaforma, quindi sia pagamenti creati a partire dalle pratiche, che i pagamenti importati tramite csv o API esterne.

Payment updater

Il microservizio legge gli eventi dal topic payments e contestualmente aggiorna lo stato della pratica cambiando lo stato da Payment pending a Inviata.

Sottosistema dei pagamenti

Payment proxy

E' il microservizio che gestisce la comunicazione e l’aggiornamento della posizione debitoria con l'Intermediario di pagamento di riferimento. Esso gestisce inoltre il salvataggio delle configurazioni tramite le quali può interagire con l'intermediario di pagamento di riferimento. Queste configurazioni sono inserite dall'operatore mediante l'interfaccia del Core, il quale comunica con il payment proxy mediante delle apposite API che quest'ultimo serve.

Ksql

E' un microservizio che ascolta dal topic payments e crea un database interrogabile con SQL contenente tutti i pagamenti in stati non definitivi.

Payments poller

E' il microservizio che monitora lo stato dei pagamenti: periodicamente legge su KSQL l'elenco dei pagamenti aperti e invia per ognuno di questi una chiamata alla "update.url" specificata nel pagamento stesso: questa url è una url del proxy stesso che consente al proxy di interrogare l'Intermediario per avere lo stato aggiornato del pagamento.

Checkout pagoPA API

Questo microservizio si occupa di centralizzare il pagamento online dei dovuti in un'unica API, ovvero quella del checkout di pagoPA, in questo modo si astrae dall'intermediario con cui ci si deve integrare facilitando quindi lo sviluppo dell'integrazione e omogeneizzando l'esperienza di pagamento del cittadino, che diventa quindi indipendente dall'intermediario tramite qui andrà a pagare.

Seguendo l'approccio del viene descritta l'architettura utilizzata per attuare il processo di protocollazione. Partendo da una panoramica ad alto livello si va sempre più in dettaglio nell'architettura fino a raggiungere il secondo livello del C4 model.

1 System Context

Per poter attuare il processo di protocollazione, l'area personale del cittadino si avvale dei sistemi di protocollazione esterni utilizzati dai diversi tenant. È fondamentale notare che la piattaforma è un servizio SaaS di tipo multi-tenant.

L’area personale del cittadino effettua diverse interazioni con il sistema di protocollo, ma tutte seguono una logica comune. Le interazioni avvengono in seguito ad alcune azioni da parte cittadini e degli operatori:

1. Invio di una pratica da parte del cittadino

2. Invio di una richiesta di integrazioni da parte di un operatore

3. Invio di una integrazione da parte del cittadino

4. Approvazione/rifiuto di una pratica

Altre azioni possibili, mediante configurazioni avanzate del servizio:

1. Creazione di una pratica da parte di un operatore per conto di un cittadino

2. Ritiro di una pratica da parte del cittadino

3. Annullamento di una pratica da parte di un operatore

Per ognuna di queste operazioni viene prodotto un documento. A partire dall'entità documento si costruiscono le richieste per i sistemi di protocollazioni esterni.

2 Container Diagram

Il processo di protocollazione è stato realizzato seguendo i principi del Domain Driven Design utilizzando il pattern Event Sourcing.

Di conseguenza si è scelto di separare il dominio dei servizi dal dominio dei documenti. In questo modo, i documenti sono indipendenti dalla loro fonte di origine e possono essere generati sia per esempio dalle pratiche, sia da altre strutture dati diverse senza che il sistema di protocollazione debba subire modifiche o integrazioni.

La piattaforma è multi tenant e multi servizio: ogni tenant può selezionare un diverso sistema di protocollazione per ogni diverso servizio che offre. Questo significa che da qualche parte la piattaforma deve tenere traccia delle configurazioni di protocollo scelte per un determinato tenant e i servizi abilitati per il sistema scelto. Inoltre va tenuta traccia anche delle configurazioni specifiche di ogni sistema di protocollazione.

Per tenere traccia di tali configurazioni è necessario un meccanismo di storage persistente(il cui tipo è da definire a seconda dei casi), mentre la scelta su chi detiene la responsabilità di gestire tali configurazioni è stata attribuita al Protocol Proxy.

Questa decisione è stata dettata dal fatto che ogni sistema di protocollazione funziona in maniera diversa, e quindi ognuno di essi necessita di una configurazione specifica. Affidando la responsabilità di gestire le configurazioni al Protocol Proxy, si evita di dover modificare, per ogni nuova integrazione, il Core Application, aggirando inoltre il problema di uno sviluppo coordinato con un terzo sistema come il Protocol Proxy.

Si può dedurre quindi che esiste un mapping 1:1 tra i Protocol proxy e i sistemi di protocollazione esterni.

Struttura Eventi

Producers

Nella piattaforma si fa ampio uso del pattern Event Sourcing, perciò è fondamentale che il formato degli eventi sia stabile, versionato e documentato.

Tutti i producer DEVONO includere obbligatoriamente i seguenti campi in ogni evento:

Nota importante: Se si genera un nuovo evento a partire da uno esistente, NON vanno ricopiati i campi event_id, event_created_at, event_version, app_id. Si tratta di una nuova entità, quindi deve avere nuovi valori.

Consumers

Chi consuma eventi deve:

• Gestire esplicitamente le versioni supportate.

• Scartare eventi con versioni non supportate.

• Non generare errori per versioni non gestite:

  • È corretto loggare in DEBUG la ricezione di una versione non supportata.

  • In condizioni normali, un consumer emette un log a livello INFO solo se:

    • ha processato con successo l’evento.

    • ha eseguito un'azione concreta.

Questo approccio evita rumore nei log e rende evidenti solo le operazioni significative.

Sistema di Retry

Obiettivo

La piattaforma è dotata di un componente, detto RetryOrchestrator, responsabile della gestione automatica dei retry per eventi temporaneamente non processabili. In caso di errore temporaneo, consente di riprogrammare la consegna dell’evento al consumer in base a una politica configurabile, evitando la perdita di messaggi e riducendo l'intervento manuale.

Funzionamento

1. Quando un servizio X fallisce nel processare un messaggio, questo viene inviato nel Failed Message Topic (FMT).

2. Il RetryOrchestrator legge i messaggi dal FMT e, sulla base della politica di retry, li ripropone al servizio X.

3. Se il messaggio esaurisce i tentativi previsti, viene inviato in una Dead Letter Queue (DLQ).

Politica di Retry

La politica di retry viene definita tramite due variabili d’ambiente principali:

Esempio

Con la configurazione:

• KAFKA_DISPATCHER_POLICY=2x1m,1x2m,3x3m

• KAFKA_RETRY_QUEUE_PREFIX=retryQueue_

Il servizio si aspetta i seguenti topic di retry:

• retryQueue_1m

• retryQueue_2m

• retryQueue_3m

Un messaggio attraverserà quindi una sequenza di 6 tentativi: 2 tentativi a distanza di 1 minuto, 1 tentativo dopo 2 minuti, 3 tentativi dopo 3 minuti ciascuno.

Standard Date

Formato delle date

Tutte le date all’interno della piattaforma devono essere rappresentate nel formato ISO 8601, con la seguente struttura:

YYYY-MM-DDTHH:MM:SS+HH:MM

Esempio:

2025-03-12T00:00:00+01:00

Questo formato garantisce coerenza, leggibilità e interoperabilità tra i diversi sistemi e microservizi, soprattutto in contesti distribuiti.

Fuso orario

Tutte le date devono essere espresse nel fuso orario Europe/Rome, che gestisce automaticamente l’ora solare (+01:00) e l’ora legale (+02:00).

Non utilizzare UTC o altri fusi orari, salvo esplicita eccezione documentata.

Linee guida

• Le date devono includere l’offset del fuso orario (+01:00 o +02:00) come parte della stringa.

• Le librerie utilizzate per serializzazione/deserializzazione devono essere configurate per usare Europe/Rome come timezone di default.

• Il formato deve essere rispettato sia in input che in output per tutte le API e gli eventi.

Applicazioni

Validazioni e test

• Ogni data deve essere validata secondo il pattern ISO8601 con timezone Europe/Rome.

• I test automatici devono includere:

  • Verifica del formato in fase di creazione e lettura degli eventi.

  • Verifica dell’offset corretto (+01:00 o +02:00) in base alla data.

  • Gestione corretta dell’ora legale.

API Standards

Principi di riferimento

Le API della piattaforma seguono i principi di:

• Zalando RESTful API Guidelines

• Linee guida di interoperabilità della PA (AgID)

Comportamento dei servizi

• I servizi DEVONO esporre solo i verbi HTTP previsti e restituire errore per metodi non supportati.

• I metodi seguenti devono essere idempotenti, come da RFC 7231:

  • DELETE, GET, HEAD, OPTIONS, PUT, TRACE

• I percorsi (path) delle risorse devono:

  • Essere al plurale per rappresentare collezioni

  • Usare kebab-case (es. user-preferences)

Esempi di endpoint

POST    /tenants
GET     /tenants/{tenant_id}
PUT     /tenants/{tenant_id}
PATCH   /tenants/{tenant_id}
DELETE  /tenants/{tenant_id}

Le URL nelle risposte devono essere sempre espresse in forma assoluta.

GET e Navigazione

Per le risorse collezione, le risposte devono includere una struttura di meta-informazioni e link di navigazione:

{
  "meta": {
    "page": {
      "offset": 5000,
      "limit": 20,
      "sort": "creationTime"
    },
    "total": 46561
  },
  "links": {
    "self": "https://api.example.it/items?offset=5000&limit=20&sort=creationTime",
    "prev": "https://api.example.it/items?offset=4980&limit=20&sort=creationTime",
    "next": "https://api.example.it/items?offset=5020&limit=20&sort=creationTime"
  },
  "data": [
    { "id": "..." },
    { "id": "..." },
    { "id": "..." }
  ]
}

Paginazione

I parametri di paginazione da usare nei GET, ove applicabile, sono:

Per endpoint con elevata numerosità di dati, si può usare la cursor-based pagination, ad esempio:

GET /payments?created_since=2024-12-01T00:00:00+01:00

Gestione degli errori

Tutti gli errori devono seguire lo standard RFC 7807 - Problem Details for HTTP APIs:

{
  "type": "/errors/incorrect-user-pass",
  "title": "Incorrect username or password.",
  "status": 401,
  "detail": "Authentication failed due to incorrect username or password.",
  "instance": "/login/log/abc123"
}

Ogni errore può includere:

• type: URL che identifica il tipo di errore

• title: breve descrizione dell’errore

• status: HTTP status code (opzionale)

• detail: descrizione dettagliata (opzionale)

• instance: identificatore specifico dell’occorrenza (opzionale)

Flusso di Integrazione e Fruizione

Processo di Adesione e Configurazione (Lato Ente/PDND e OpenCity):

• L'ente (es. Comune) deve prima abilitarsi sulla piattaforma PDND (procedura di PagoPA tramite SPID).

• Sulla piattaforma PDND (spesso guidati o fatti da noi per l'ente):

  • Si crea un Client.

  • Si richiede la Fruizione degli e-service desiderati (es. ANPR stato famiglia). Questa richiesta deve essere approvata dall'ente erogatore.

  • Si crea una Finalità per ogni e-service richiesto, specificando le motivazioni e l'analisi del rischio. Anche questa finalità deve essere approvata.

  • Si associa la Finalità approvata e la Chiave Pubblica al Client sulla PDND.

• Sulla Piattaforma OpenCity:

  • Si crea un Client corrispondente a quello creato sulla PDND.

  • Si genera una Chiave Pubblica (tramite un'API del PDND Connector) e la si associa al Client sulla PDND.

  • Si inseriscono gli identificativi ottenuti dalla PDND: Client ID, KID e Purpose ID (ParID).

  • Si abilitano gli E-service (configurati con il Client e la Finalità) a livello di "tenant" (per tutti i servizi compatibili) o di "singolo servizio".

  • Si configura il Nested Form sul frontend per ricevere i dati da quello specifico e-service.

Ulteriori Dettagli e Supporto

Documentazione

• Le slide OpenCity_Richiesta di fruizione dati via PDND_public link.pdf sono ottime per gli step lato Ente/PDND.

• Le registrazioni video sono essenziali per vedere il flusso pratico:

  • La "Videolezione 1: Formazione Pdnd" per il contesto generale, gli attori, e la demo di configurazione/fruizione;

  • La "Videolezione 2: Revisione codice PDND" per il funzionamento interno del Connector (flusso GET/POST, struttura codice).

Ambiente di Lavoro

Serve l'accesso alla piattaforma PDND (test/collaudo) con permessi adeguati (amministratore è meglio). Richiedere i permessi per comuni di test come Asolo o Vicopisano. Configurare un ambiente locale per testare il PDND Connector, magari copiando le configurazioni esistenti da S3 (richiedere credenziali).

Processo di Lavoro

Seguire la Guida Passo Passo per l'Integrazione della PDND: identificare l'e-service (con PMs), studiarlo (dati vs form), e creare una issue dettagliata che includa lo studio, la mappatura, e la definizione della risposta del Connector.

Problemi Noti

Ci sono aree in miglioramento: lo Swagger del Connector potrebbe non funzionare nell'ambiente QA, la gestione degli ambienti collaudo/produzione sulla UI della Stanza ha delle criticità (è stata aperta una issue per questo), la strategia di caching nel Connector ha delle criticità.

L’area personale del cittadino effettua diverse interazioni con il sistema di protocollo, ma tutte seguono una logica comune. Le interazioni avvengono in seguito ad alcune azioni da parte cittadini e degli operatori:

1. invio di una pratica da parte del cittadino

2. invio di una richiesta di integrazioni da parte di un operatore

3. invio di una integrazione da parte del cittadino

4. approvazione/rifiuto di una pratica

Altre azioni possibili, mediante configurazioni avanzate del servizio:

1. creazione di una pratica da parte di un operatore per conto di un cittadino

2. ritiro di una pratica da parte del cittadino

3. annullamento di una pratica da parte di un operatore

Metadati utilizzati

Per ognuna di queste operazioni viene prodotto un documento principale dotato di eventuali allegati.

Per ogni documento ci aspettiamo di poter sempre specificare:

• Un oggetto

• Un mittente (il soggetto che ha formato il documento)

• Un destinatario (solitamente l’ufficio che deve prendere in carico la richiesta)

• Data di registrazione della pratica

• Tipo di trasmissione (in entrata, in uscita, interno)

• Classificazione (solitamente sotto forma di indice di classificazione nell’albero del titolario, es 6.3.4)

Per ogni documento protocollato ci aspettiamo di ricevere i seguenti dati:

• Il Numero di protocollo (un identificativo unico e persistente)

• Data di registrazione nel protocollo

• (opzionale) Una impronta digitale del documento protocollato

Tutti i documenti di una pratica sono raccolti in un fascicolo per il quale ci aspettiamo di poter specificare

• L’oggetto

• (opzionale) La classificazione

Flusso di interazione tra Area Personale e sistema di protocollo

Per ogni integrazione sono necessarie solitamente le seguenti chiamate API o webservice:

1. Ricerca di un documento per Numero di protocollo

2. Invio di un Documento principale

3. Invio di allegati al documento principale

4. Protocollazione di un documento e dei suoi allegati: se disponibile, preferiamo avere una chiamata atomica, che protocolla il documento principale e i suoi allegati.

5. Ricerca di un fascicolo per Numero di fascicolo

6. Creazione di un fascicolo

7. Aggiunta di un documento ad un fascicolo esistente

Processo di integrazione

1. Condivisione documentazione:

• Documentazione delle API o dei WebService

• ambiente di test (endpoint, credenziali di accesso)

• Esempio di chiamate necessarie per fare una protocollazione di un documento e dei suoi allegati

1. Test delle chiamate al sistema di protocollo effettuate in modo manuale

2. Validazione della protocollazione manuale da parte dell’Ente

3. Implementazione e rilascio dell’integrazione in ambiente di Quality Assurance

4. Validazione su un servizio di test

5. Rilascio in ambiente di produzione

6. (opzionale) Validazione su un servizio di produzione e annullamento della protocollazione effettuata

L’ultimo test effettuato in ambiente di produzione non è strettamente necessario, ma nella nostra esperienza può rivelare differenze nella configurazione del sistema di protocollo che possono diventare bloccanti.

Contesto Generale e Obiettivi

Cos'è la PDND e a Cosa Serve:

• E’ l'infrastruttura digitale italiana che facilita l'interoperabilità tra sistemi informativi delle Pubbliche Amministrazioni.

• Il suo scopo primario è condividere dati in modo sicuro, standard e trasparente.

• E' uno dei due approcci adottati da Opencity Italia per implementare il principio del (o one-time entry), evitando di chiedere al cittadino dati già in possesso di altre PA (es. residenza, stato famiglia da ANPR).

Attori Principali Coinvolti:

• PDND: La piattaforma centrale che gestisce le interazioni e la sicurezza.

• Erogatori: Gli enti che mettono a disposizione i dati tramite e-service (es. ANPR, INPS).

• Fruitori: Gli enti (come i Comuni, che usano OpenCity) che hanno bisogno di accedere a questi dati.

• La Piattaforma (OpenCity): L'interfaccia lato ente e cittadino dove i dati vengono visualizzati e usati.

• PDND Connector: Il microservizio chiave che funge da ponte tra OpenCity e l’ecosistema PDND (compresi gli enti erogatori). Ha il compito di:

  • Gestire le configurazioni e il materiale crittografico degli enti fruitori;

  • Interagire con la PDND, per conto dei fruitori, al fine di ottenere i voucher di sicurezza;

  • Utilizzare i voucher per accedere in modo sicuro agli e-service esposti via API dagli enti erogatori, garantendo che ogni cittadino acceda a tutti e soli i dati di sua pertinenza.

  • Garantire la conservazione dei voucher secondo le linee guida.

  In sintesi, il PDND Connector centralizza la logica di integrazione e sicurezza, permettendo a OpenCity di comunicare con la PDND in modo trasparente, conforme e scalabile.

Requisiti per l'integrazione

E-service

Non sono generici servizi API, ma specifici servizi erogati dagli enti che forniscono dati ben definiti (es. "C021 - Accertamento Stato Famiglia" da ANPR). Possono avere diverse versioni, per poter essere utilizzati bisogna farne richiesta e in seguito associarli ad una finalità.

Client

Un oggetto di configurazione fondamentale sulla PDND e su OpenCity. Raggruppa le informazioni necessarie per gestire e amministrare gli e-service che un ente (fruitore) vuole usare. L'ente, configurando il client di Opencity Italia, può accedere a tutti gli e-service che si vogliono integrare nei servizi digitale. Per poter utilizzare gli e-service, il client deve essere associato alle relative finalità.

Finalità

Il motivo (anche legale) per cui un ente richiede l'accesso a un determinato e-service. È strettamente legata a uno o più e-service e richiede una specifica "Analisi del rischio". Per ampliare l'adozione della PDND, la piattaforma consente di creare tanti servizi digitali utilizzando una singola finalità.

Voucher

Un token di sicurezza temporaneo che il PDND Connector ottiene dalla PDND. Questo voucher è essenziale perché funge da credenziale per autenticarsi e autorizzarsi direttamente presso l'ente erogatore quando si chiede il dato tramite l'e-service. Il voucher è relativo ad uno specifico client, una specifica finalità e una specifica coppia chiavi di crittografia.

Nested Form

Il componente sulla nostra piattaforma che riceve e visualizza i dati ottenuti tramite la PDND. Alcune proprietà nel suo codice definiscono quale e-service utilizzare e quali campi specifici riceveranno i dati PDND certificati.

ID Chiave (KID), ID Client (Client ID), ID Finalità (Purpose ID / ParID)

Sono gli identificativi cruciali ottenuti dalla piattaforma PDND dopo aver configurato Client, Chiave Pubblica e Finalità. Vanno copiati dalla PDND e inseriti nella configurazione del Client corrispondente sulla nostra piattaforma.

Una autenticazione con SSO tra Opencity Italia e un applicativo in uso allo stesso Ente può essere agevolmente realizzata se può essere garantito il supporto per il protocollo oAuth2.

Vediamo uno schema generale degli attori in gioco:

Vediamo un flusso di autenticazione di un cittadino che fa login prima sull'area personale e successivamente sull'applicativo di terze parti:

L'applicativo di terze parti dovrà essere dotato di un opportuno client oAuth2. Ipotiziamo che le url coinvolte siano le seguenti e mostriamo una tipica configurazione del client.

Per attivare un nuovo client è necessario fornire:

• La URL da autorizzare come redirct uri del client

• La URL di logout

L'attivazione comprende i seguenti dati

redirect_url: http://servizi.comune.bugliano.pi.it/lang/auth/login-oauth
url_authorize: http://login.comune.bugliano.pi.it/authorize
url_access_token: http://login.comune.bugliano.pi.it/token
url_resource_owner_details: http://login.comune.bugliano.pi.it/api/profile
url_logout: http://login.comune.bugliano.pi.it/logout?redirect=http://servizi.comune.bugliano.pi.it/lang
client_id: {client_id} fornito da Opencity Labs
client_secret: {client_secret} fornito da Opencity Labs

Come creare un MR per aggiungere un tema

Step preparativi alla modifica:

• Clonare il repository https://gitlab.com/opencity-labs/area-personale/core

• Posizionarsi sul branch master

• Creare un nuovo branch di nome add-theme-$themename e spostarsi sul nuovo branch con il comando git checkout -b "add-theme-$themename" sostituendo con il nome del nuovo tema che si vuole creare (per le indicazioni sui nomi dei temi vedere sotto)

• Creare una MR sul branch che effettui squash di tutti i commit del branch ed elimini il branch una volta mergiato come di seguito:

Successivamente creare un nuovo file in ./assets/styles copiando il contenuto di seguito che dovrebbe coincidere con il file default.scss. Il nome del file deve coincidere con il nome che avrà il tema e avere l'estensione .scss (l nome del tema può contenere solo lettere e il carattere `-`, deve rispondere cioè alla espressione regolare [a-z][a-z0-9-]+. Es: se si vuole creare il tema "amaranto" aggiungiamo un file amaranto.scss):

@charset "UTF-8";

$primary: #3478bd;

$primary-a5: $primary;
$primary-a6: $primary;
$primary-a7: $primary;

// Header
$header-slim-bg-color: #2b649e;     // Colore di background del top header
$header-slim-button-color: #2b649e; // Colore di background del bottone di accesso all'area personale
$header-slim-button-hover-color: $primary; // Colore di background del bottone di accesso all'area personale su hover

$header-center-bg-color: #3478bd;       // Colore di background del header centrale
//$header-center-text-color: #fff; // Colore del testo del header centrale

// Footer
$bg-footer: #16334f; // Colore di background del footer

// Content
$card-link-color: $primary; // Colore link all'interno delle card

@import "core";

• Nel file cambiare le opzioni ed i colori a proprio piacimento

• Si compila il nuovo tema su webpack aggiungendo nel file webpack.config.js StyleEntry come di seguito: .addStyleEntry('amaranto', './assets/styles/amaranto.scss') (Il nome deve coincidere con il nome del file creato in precedenza). I colori devono tenere conto della linea guida Accessibilità.

• Si aggiunge alla piattaforma il nuovo tema aggiornando nel file src/Model/Tenant/ThemeOptions.php la costante THEMES e inserendo il nuovo tema come di seguito: 'Amaranto' => 'amaranto'

API privata, che si intende esporre mediante GovWay:

https://192.168.1.111:8000/conti-correnti

L'API risponde un dato privato se viene correttamente inserito un parametro in get tax_code che identifica il codice fiscale del cittadino che esegue la richiesta:

https://192.168.1.111:8000/items/conti-correnti?tax_code=AAABBBXX...

L'API non ha un controllo interno che permette di rispondere ad ogni cittadino solo con i suoi dati, l'API è aperta e risponde a qualunque chiamata.

In questo esempio si desidera esporre l'API privata su un indirizzo pubblico e filtrare le chiamate in modo che ogni cittadino possa consultare l'API solo per i propri dati.

L'API esposta è la seguente:

https://govway-qa-out.boat.opencontent.io/govway/Ente/directus/v1

Quando viene chiamata quest'ultima url si desidera imporre un controllo sulla la presenza del token JWT e sul parametro della chiamta. La chiamata deve raggiungere l'API privata SOLO se:

1. il token è presente

2. il token è validato mediante la chiave pubblica esposta in JWKS

3. viene passato il parametro tax_code in GET

4. il parametro tax_code corrisponde al valore username del token

Quest'ultimo punto è il più importante perché ci da la certezza che il cittadino che sta facendo la richiesta è lo stesso che si è autenticato.

Configurazione

E' necessario creare una token policy, che poi verrà assegnata all'erogazione delle API

Il file jwks è stato scaricato da https://servizi.comune-qa.bugliano.pi.it/.well-known/jwks.json e inserito in un path raggiungibile da GovWay: nel nostro caso essendo GovWay installato con Docker abbiamo fatto uso della direttiva volumes per condividere il file con il container di GovWay.

Fare attenzione inoltre che il kid della chiave pubblica è specifico per ogni tenant e deve essere quello corretto.

Predisposta la policy deve essere applicata all'Erogazione API

Il controllo del contenuto viene fatto imponendo che l'informazione riportata nel token (${tokenInfo:username}) e quella inserita come parametro GET della chiamata (${query:filter[tax_code]}) abbiano lo stesso valore. Resta inteso che il valore nel token è vincolato dalla piattaforma, mentre il parametro tax_code è scelto da chi ha progettato l'API che viene protetta.

A questo punto la configurazione è completa.

Come descritto nella sezione precedente tramite le API dei jobs è possibile creare un processo di importazione dovuti.

Questa operazione può essere fatta tramite interfaccia nella sezione admin, il servizio creato dovrà essere di tipo "Servizio di pagamento dovuti"

Per il servizio appena creato dovrà essere configurato anche il gateway di pagamento

Creazione di un Job per l'importazione dovuti

Per poter creare un Job di importazione dovuti bisogna eseguire una chiamata POST all' endpoint api/jobs

Il payload per la creazione di un Job è così composto

{
  "attachment": {
    "name": "dovuti.csv",
    "mime_type": "text/csv",
    "file": "bm90aWNlX251bWJlsYW1vdW50LHJlYXNvbixjcmVhdGVkX2F0LGV4cGlyZV9hdCxjcmV..."
  },
  "args": {
    "service_id": "a5a9bf9f-7b5c-4aed-b020-5bf2d1ca75ab"
  },
  "type": "import_dovuti"
}

Dove:

attachments -> è il file csv contenente i dovuti da importare

Il file csv deve acere un template specifico di questo tipo:

service_id -> è un parametro specifico del tipo di job import_dovuti ed indica su quale servizio devono essere agganciati i dovuti importati

Questo consente di usare l'autenticazione senza necessariamente usare lo stesso cookie:

1. integrarsi con altri applicativi di terze parti che possono usare un client JWT;

2. fare chiamate cross-origin (CORS) autenticate dove non è semplice o possibile sfruttare lo stesso cookie di autenticazione;

Il Cookie di Sessione

Come molti applicativi web anche Opencity Italia usa i cookie per implementare la sessione utente, il cookie si ottiene semplicemente l'indirizzo di accesso degli utenti: ad esempio per il nostro Ente di demo è

In base alla , si viene rediretti su un provider di autenticazione (tipicamente un sistema che permette il login con Spid/CIE), si eseguono tutti gli step necessari e infine si torna sull'area personale con una sessione valida.

A questo punto nel proprio brower è possibile rintracciare facilmente il cookie della piattaforma.

Il token JWT

Il cookie di sessione viene inviato in modo trasparente all'utente dal browser al sito che lo ha generato, e questo garantisce che l'utente abbia sempre una sessione valida quando naviga nella sua area personale.

Per fare chiamate alle API però è necessario convertire il Cookie in Token JWT, per farlo esiste una apposita API, nel nostro esempio:

Per simulare la chiamata con Postman ad esempio:

Il token JWT può essere usato adesso per fare chiamate alle API che richiedono una autenticazione, ad esempio posso usare l'interfaccia Swagger delle API come segue.

Faccio click in alto a destra sul comando Authorize

A questo punto posso chiamare le API che richiedono autenticazione come la /applications

Anatomia di un Token

All'interno del token sono presenti le seguenti informazioni:

Header

Payload

La piattaforma consente la possibilità da parte di sistemi esterni di creare/modificare/visualizzare ed eliminare oggetti Job

Ad esempio nel nostro ambiente di demo è possibile consultare le API dedicate a questo scopo:

https://servizi.comune-qa.bugliano.pi.it/lang/api/doc#jobs

Questi speciali oggetti sono dei processi onerosi che vengono creati e poi eseguiti in modo asincrono dalla piattaforma.

Esempio di interazione tra un sistema esterno e le API dei jobs:

In fase di creazione del Job viene specificato tramite il parametro type il tipo di processo (type) che verrà eseguito dal sistema.

Creazione di un Job

Per poter creare un Job bisogna eseguire una chiamata POST all' endpoint api/jobs

Il payload per la creazione di un Job è così composto

{
  "attachment": {
    "name": "string",
    "mime_type": "text/csv",
    "file": "ZXNlbXBpbw== OR www.example.com"
  },
  "type": "string",
  "args": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  }
}

Dove:

attachment -> è il file in base64 che verrà processato

type -> è il tipo di processo che deve essere eseguito

args -> sono dei parametri necessari al tipo di processo

L' API rispondere con un codice HTTP 201 e con l'id del Job creato

Recupero delle informazioni di un Job

Per poter recuperare informazioni su Job bisogna eseguire una chiamata GET all' endpoint api/jobs/{id}

Il payload di risposta delle API è così composto:

{
    "attachment": {
      "name": "string",
      "mime_type": "text/csv"
    },
    "id": "string",
    "type": "string",
    "status": "string",
    "args": {
      "additionalProp1": "string",
      "additionalProp2": "string",
      "additionalProp3": "string"
    },
    "output": "string",
    "running_output": "string",
    "started_at": "2024-05-31T09:19:18.779Z",
    "terminated_at": "2024-05-31T09:19:18.779Z",
    "created_at": "2024-05-31T09:19:18.779Z",
    "updated_at": "2024-05-31T09:19:18.779Z"
}

Dove:

status -> è lo stato attuale del job e può assumere i seguenti valori pending, cancelled, running, finished, failed

output -> l'output finale del processo, può contenere un errore in caso di processo failed

running_output -> l'output corrente (Es. la riga del file che si sta processando)

Uno degli utilizzi più significativi che si può fare con i Job è l'importazione di contenuti come ad esempio l'importazione dei dovuti

Dataset e micro servizi esterni alla piattaforma possono essere facilmente integrati tramite il flusso di autenticazione basato su JWT (JSON Web Token) e JWKS (JSON Web Key Set)

Questo flusso di autenticazione prevede alcuni passaggi chiave e interazioni tra:

• client (browser dell'utente)

• area personale

• micro servizio esterno

Di seguito il processo punto per punto:

1. Il client richiede il token

Il client invia una richiesta all'area personale per ottenere un JWT, spesso includendo le credenziali dell'utente o altre forme di autorizzazione.

Come descritto nella sezione è possibile per un utente autenticato richiedere un token di autenticazione per la propria sessione.

Questa operazione può essere effettuata facendo una chiamata alle API:

oppure come utente non autenticato effettuando una chiamata POST alle API

2. L'area personale rilascia il token

L'area personale autentica il client, genera un JWT e lo firma con una chiave privata.

Il token viene quindi restituito al client.

3. Il client richiede la risorsa al micro servizio esterno:

Il client invia una richiesta al micro servizio esterno per accedere a una risorsa protetta, includendo il JWT nell'intestazione Authorization.

4. Il micro servizio esterno convalida il token

Per verificare la validità del token il micro servizio esterno deve:

• Estrarre il JWT dalla richiesta

• Recuperare il JWKS dall'area personale, il JWKS contiene le chiavi pubbliche necessarie per verificare la firma del JWT.

• Verificare la firma del JWT e convalidare le sue richieste

5. Accesso concesso/negato:

In base alla validità del JWT il micro servizio esterno concede o nega l'accesso alla risorsa richiesta.

Oltre alla validità del token si possono verificare le affermazioni in esso contenute.

Il payload del token prodotto dall'area personale presenta delle informazioni utili a capire se quello specifico utente oltre ad avere un token valido ha i permessi per ottenere la risorsa richiesta.

Di seguito un esempio di payload del token

Cosa permette di fare la piattaforma con l’integrazione in questione

La piattaforma consente la creazione di servizi digitali che prevedono l'associazione di uno o più pagamenti, gestiti in modo integrato con il sistema pagoPA o tramite registrazione manuale di marche da bollo.

I pagamenti possono avvenire in due modalità:

Pagamento tramite marche da bollo

In questo caso non è prevista alcuna integrazione con sistemi esterni. Il cittadino registra i dati delle marche da bollo acquistate autonomamente (numero identificativo e data), a corredo della pratica che sta presentando.

Pagamento tramite circuito pagoPA

La piattaforma gestisce in modo integrato i pagamenti elettronici tramite l’infrastruttura pagoPA, attraverso l’interazione con uno degli intermediari accreditati.

La creazione del pagamento avviene automaticamente durante l’invio della pratica o a seguito di un'azione dell’operatore, che può:

• generare posizioni debitorie direttamente tramite configurazione della pratica;

• importare manualmente pagamenti pendenti da sistemi esterni tramite file CSV, rendendoli disponibili al cittadino nell’Area Personale.

L’integrazione consente quindi:

• la creazione, la gestione e l’aggiornamento dei pagamenti;

• la ricezione automatica delle notifiche di esito da parte del nodo pagoPA;

• l’allineamento in tempo reale dello stato della pratica all'interno dell’Area Personale.

Nota: È attualmente in fase di sperimentazione l’introduzione della Marca da Bollo Digitale, che permetterà il pagamento del bollo direttamente tramite pagoPA, superando la modalità manuale tradizionale.

Benefici dell’integrazione

L’integrazione dei pagamenti nella piattaforma porta numerosi vantaggi operativi e strategici per gli enti:

• Automazione dei processi di incasso: La generazione automatica delle posizioni debitorie e la ricezione dell’esito del pagamento riducono il carico di lavoro manuale per gli operatori.

• Migliore esperienza per il cittadino: Il cittadino può completare i pagamenti online in autonomia, in un contesto centralizzato (Area Personale), senza dover interagire con sistemi esterni o recarsi fisicamente presso l’ente.

• Tracciabilità e trasparenza amministrativa: Tutti i pagamenti vengono registrati con ID univoci, ricevute elettroniche e cronologia completa, garantendo sicurezza, conformità normativa e facilità di riconciliazione.

Esempi di utilizzo dell’integrazione per i pagamenti

Di seguito alcuni casi d’uso reali in cui l’integrazione dei pagamenti viene utilizzata all’interno della piattaforma:

Pagamenti pagoPA generati automaticamente dalla piattaforma

In questi scenari, la piattaforma crea autonomamente una posizione debitoria pagoPA in seguito a un’azione del cittadino o alla configurazione di un servizio digitale:

Domanda di occupazione suolo pubblico

Al termine della compilazione dell’istanza, un pagamento di €20 per i diritti di segreteria. Il cittadino può pagare direttamente dall’Area Personale.

Pagamenti pagoPA importati da file CSV

In alcuni casi, l’ente può caricare manualmente un file contenente posizioni debitorie provenienti da altri sistemi (es. tributi, multe, TARI):

Pagamenti Canone CUP

Il comune importa le posizioni già determinate nel gestionale tributi. Il cittadino visualizza e paga queste richieste direttamente dalla propria Area Personale.

Pagamento tramite marche da bollo cartacee

Alcuni servizi non richiedono l’integrazione con pagoPA, ma prevedono il pagamento tramite marche da bollo acquistate dal cittadino:

Istanza di residenza

Il modulo richiede l’inserimento del numero identificativo e della data di una marca da bollo da €16 acquistata autonomamente. Il cittadino la registra all’interno della pratica.

Processo di integrazione

L’integrazione con il sistema di pagamento si sviluppa in diverse fasi operative. Di seguito una descrizione dettagliata del processo.

Fasi Principali

Raccolta e validazione della documentazione e dell’ambiente di test

In questa fase iniziale viene contattato il fornitore dell’intermediario di pagamento per ottenere:

• La documentazione tecnica delle API, contenente le specifiche delle operazioni fondamentali:

  • creazione del pagamento;

  • generazione dell’avviso cartaceo;

  • ottenimento del link per il pagamento online (checkout);

  • recupero dello stato del pagamento;

  • download della ricevuta telematica (RT).

• Le informazioni sull’ambiente di test, in particolare:

  • l’URL del web service (WSDL per chiamate SOAP o documentazione Postman/Swagger per REST);

  • le credenziali di accesso e i dati fittizi da usare per i test (codici tipo dovuto, codice esercente, identificativi utente, ecc.).

Sviluppo dell’integrazione

Questa fase prevede lo sviluppo vero e proprio dell’integrazione, seguendo:

• la documentazione fornita dall’intermediario;

• la documentazione tecnica della piattaforma Opencity;

• gli standard architetturali e funzionali adottati internamente.

L’integrazione viene generalmente realizzata tramite un proxy che standardizza la comunicazione tra la piattaforma e l’intermediario.

Test dell’integrazione in ambiente di collaudo

Completato lo sviluppo, si procede alla validazione funzionale nell’ambiente di collaudo.

I test previsti includono:

• Test automatici delle API di configurazione del pagamento;

• Test manuale della configurazione del pagamento tramite form (interfaccia admin);

• Test di creazione del pagamento a partire da una pratica compilata da un cittadino;

• Test del completamento del pagamento attraverso il checkout pagoPA;

• Test di scaricamento della ricevuta telematica a pagamento avvenuto.

• Test di importazione mediante file csv di un pagamento pendente creato esternamente alla piattaforma

Test dell’integrazione in ambiente di produzione

Una volta superata la fase di collaudo, si procede con il test in ambiente di produzione, in collaborazione con un cliente pilota.

Questa fase è fondamentale perché:

• emergono spesso comportamenti specifici o difformità rispetto all’ambiente di test;

• si rilevano dettagli contestuali noti solo al cliente, che può accedere al backoffice dell’intermediario e fornire informazioni utili;

• si verificano disallineamenti tra test e produzione dovuti a configurazioni, dati o logiche specifiche dell’ente.

Prima di procedere, è necessario concordare la tempistica e la modalità di test con il cliente coinvolto.

Criticità comuni nelle integrazioni di pagamento

Durante lo sviluppo e la messa in produzione dell’integrazione con i sistemi di pagamento, possono emergere alcune criticità ricorrenti. Di seguito le principali:

Connettività in ambienti segregati (firewall, VPN, ecc.)

In alcuni casi, le API degli intermediari sono accessibili solo tramite VPN o da indirizzi IP autorizzati, sia in ambiente di test che in ambiente di produzione.

Per usufruire delle API, è necessario comunicare al fornitore gli indirizzi IP fissi da autorizzare. Questo vincolo può essere particolarmente rilevante quando lo sviluppo dell’integrazione è affidato a un’azienda esterna.

In questi casi si possono adottare due strategie:

• Configurare l’accesso alla VPN di Opencity Labs per consentire lo sviluppo in modo controllato e sicuro.

• Richiedere lo sblocco dell’IP dell’azienda esterna (se disponibile) da parte del fornitore dell’integrazione, insieme a quelli di Opencity Labs.

Documentazione tecnica errata o incompleta

La documentazione fornita dai fornitori del sistema di pagamento può presentare, in alcuni casi, ambiguità, imprecisioni o mancanze. Questo può ostacolare:

• la corretta progettazione dell’integrazione;

• lo sviluppo in ambiente di test;

• la validazione finale in produzione.

In presenza di dubbi o problemi tecnici, è fondamentale contattare tempestivamente il supporto tecnico del fornitore e fornire esempi concreti del comportamento anomalo riscontrato.

Ambiente di test instabile o non funzionante

Gli ambienti di test – sia del fornitore intermediario, sia di pagoPA – possono presentare frequenti disservizi. Le criticità più comuni si verificano nei seguenti punti del flusso:

1. Ambiente di test dell’intermediario di pagamento I problemi più frequenti includono:

• errori nella creazione del pagamento;

• mancato download dell’avviso o della ricevuta telematica;

• errori di aggiornamento dello stato del pagamento;

• malfunzionamenti nel redirect verso il portale di pagamento.

In questi casi è necessario contattare il supporto tecnico dell’intermediario, fornendo tutti i dettagli tecnici (endpoint, parametri inviati, timestamp, codice esercente, ecc.).

2. Ambiente di test di pagoPA I problemi si manifestano generalmente dopo il redirect al portale pagoPA, in particolare:

• nella schermata di inserimento dei dati della carta;

• nel flusso di conferma o ricezione dell’esito.

Per queste problematiche è necessario contattare il supporto tecnico di pagoPA via email all’indirizzo: [email protected]

Requisiti funzionali

Sono requisiti che dipendono da nostre scelte implementative, possono cambiare man mano che evolviamo la piattaforma, per supportare nuovi casi d'uso (pagamento dei dovuti) oppure perché ci accorgiamo che abbiamo commesso qualche errore nella progettazione.

1. Gestione di pagamenti spontanei

2. Gestione di pagamenti con bilancio

3. Gestione della notifica dello stato del pagamento da parte dell'IdP - se disponibile - o del polling se non è disponibile la notifica

4. Se è implementato il polling, questo deve avvenire con un esponenziale che assicuri alcuni check nel giro di pochi minuti e poi si diradi fino a un massimo di un check al giorno fino alla scadenza del pagamento o 1 anno se la scadenza è inferiore.

5. Gestione delle configurazioni a livello di Tenant e di Servizio

Requisiti normativi

• Avere una specifica in formato OpenAPI v3

• Rispettare la : in particolare per quanto riguarda

  • (4.2)

  • (4.3) optando per la scelta di snake_case per i nomi degli attributi

  • logging (4.4)

  • risultare valido nel

Requisiti per l'ambiente di produzione

• Sappiamo che in molti topic ci sono diversi eventi mal formati, per vari errori e assenza di uno schema registry, quindi è necessario validare gli eventi in input e opzionalmente in output (lo fanno le nostre prime implementazioni in python, ma è un requisito?)

• Ci aspettiamo che se di dovesse aggiornare il formato dell'evento nel topic payments gestiremo eventi anche in parallelo con versioni distinte, quindi ogni proxy deve Interpretare solo gli eventi che riportano il formato più recente dell'evento nel topic payments: event_version: 2.0

• Integrarsi con per la gestione degli errori

• Esporre metriche di monitoraggio in , in particolare:

  • counter sul numero di pagamenti creati

  • counter sul numero di errori durante il processamento di pagamenti, differenziando gli errori interni (errori di formato dati in ingresso o validazione) da errori esterni (errori di dialogo con l'IdP)

  • latenza delle chiamate fatte all'IdP

  Di seguito la tabella contenente le specifiche di ogni metrica

Inoltre il servizio deve rispettare gli in particolare per quanto riguarda la gestione dello storage: non possiamo avere vendor-lockin sulle tecnologie, quindi dobbiamo essere compatibili con file-system posix tradizionale, NFS share e almeno i due cloud-storage più diffusi S3 e Azure Blob.

Documentazione API di Esempio - Swagger

Esempi di proxy da cui si può prendere spunto

EFIL:

IRIS:

MYPAY:

PMPAY:

Questi proxy condividono alcune scelte implementative grazie a un apposito python-sdk sviluppato in parallelo ai proxy stessi:

• le configurazioni sono salvate su disco locale o s3 secondo un albero ben definito tenant->servizio

• i singoli pagamenti vengono salvati su storage fino a che il pagamento è pendente, così da poter fare il polling in autonomia.

Altri riferimenti utili

Panoramica

La configurazione di tenant e servizi avviene interrogando delle API apposite fornite dal Protocol Proxy di riferimento. Quest'ultimo fornisce inoltre un form come json schema sviluppato con form.io mediante il quale l'utente inserisce tali configurazioni.

Per creare un form utilizzare il seguente builder: https://formio.github.io/formio.js/app/builder

Configurazione Servizio

L'admin, dall'interfaccia di configurazione dei protocolli della piattaforma compila la configurazione mediante una form, il cui json schema è servito dall'API /v1/schema del Protocol Proxy

Lo schema della form sopra riportata è il seguente:

{
  "display": "form",
  "settings": null,
  "components": [
    {
      "label": "UUID dell'ente",
      "placeholder": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
      "applyMaskOn": "change",
      "hidden": true,
      "tableView": true,
      "validate": {
        "required": true
      },
      "key": "tenant_id",
      "type": "textfield",
      "input": true
    },
    {
      "label": "UUID del Servizio",
      "placeholder": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
      "applyMaskOn": "change",
      "hidden": true,
      "tableView": true,
      "validate": {
        "required": true
      },
      "key": "id",
      "type": "textfield",
      "input": true
    },
    {
      "label": "Descrizione del servizio",
      "placeholder": "Comune di Bugliano",
      "applyMaskOn": "change",
      "hidden": true,
      "tableView": true,
      "validate": {
        "required": true
      },
      "key": "description",
      "type": "textfield",
      "input": true,
      "defaultValue": "test"
    },
    {
      "label": "Impostazioni specifiche del protocollo",
      "tableView": false,
      "validate": {
        "required": false
      },
      "key": "registry",
      "type": "container",
      "input": true,
      "components": [
        {
          "label": "URL Protocollazione",
          "placeholder": "http://www.example.com/",
          "tableView": true,
          "validate": {
            "required": true
          },
          "key": "url",
          "type": "textfield",
          "input": true
        },
        {
          "label": "Gerarchia di Classificazione",
          "placeholder": "1.2.3",
          "tableView": true,
          "validate": {
            "required": false
          },
          "key": "classification_hierarchy",
          "type": "textfield",
          "input": true
        },
        {
          "label": "Numero Fascicolo",
          "placeholder": "1",
          "tableView": true,
          "validate": {
            "required": false
          },
          "key": "folder_number",
          "type": "textfield",
          "input": true
        },
        {
          "label": "Anno Fascicolo",
          "placeholder": "2022",
          "tableView": true,
          "validate": {
            "required": false
          },
          "key": "folder_year",
          "type": "textfield",
          "input": true
        }
      ]
    },
    {
      "label": "Attivo",
      "tableView": false,
      "validate": {
        "required": false
      },
      "key": "is_active",
      "type": "checkbox",
      "input": true,
      "defaultValue": false
    },
    {
      "label": "Salva",
      "tableView": false,
      "validate": {
        "required": false
      },
      "key": "submit",
      "type": "button",
      "input": true,
      "disableOnInvalid": true
    }
  ]
}

Premendo poi il bottone Salva, viene eseguita una POST /services servita dal Protocol Proxy, con payload

{
    "data": {
        "tenant_id": "",
        "id": "",
        "description": " ",
        "registry": {
            "url": "url.protocollo.it",
            "classification_hierarchy": "1.2.3",
            "folder_number": "1",
            "folder_year": "2023"
        },
        "is_active": true,
        "submit": false
    },
    "metadata": {}
}

Per modificare una configurazione esistente, il proxy serve l'API PUT /services/{service_id} e PATCH /services/{service_id}

Per eliminare una configurazione esistente, il proxy serve l'API DELETE /services/{service_id} . In questo caso l'eliminazione è una soft-delete, ovvero la configurazione viene semplicemente disattivata settando il parametro active a false.

Configurazione del tenant

la configurazione del tenant avviene in maniera nascosta durante la configurazione del servizio. Sarà la piattaforma a chiamare le API del Protocol Proxy. La loro implementazione è descritta nella sezione seguente

Alberatura configurazioni sullo storage

Le configurazioni di tenant e servizi vengono salvate con la seguente alberatura

root |____tenants | |____tenantid1.json | |____tenantid2.json | |____tenantid3.json | |____..... | |____tenantidn.json |____services | |____serviced1.json | |____serviced2.json | |____serviced3.json | |____..... | |____servicedn.json

Endpoint del pdnd-connector

Il pdnd-connector espone endpoint specifici per ciascun e-service integrato, con diverse operazioni supportate tramite verbi HTTP.

Endpoint di Chiamata

Gli endpoint seguono una struttura che identifica l'erogatore e il servizio specifico. Ad esempio, per gli e-service ANPR (ANPR è l'erogatore), si utilizzano path come /e-services/anpr/<nome-e-service>. Esempi di <nome-e-service> includono accertamento-cittadinanza, stato-famiglia, accertamento-residenza.

Verbi HTTP Utilizzati

• GET: Utilizzato per la fruizione degli e-service, ovvero per richiedere e ottenere i dati dal pdnd-connector, che a sua volta li recupera dagli enti erogatori (es. ANPR, INPS).

• POST: Utilizzato per la validazione dei dati precedentemente ottenuti tramite GET. Questa operazione verifica che i dati non siano stati alterati prima di essere inviati dal Core.

• Parametri Richiesti (Payload per POST, URL per GET):

  • Per GET (Fruizione): I parametri sono inclusi nella URL (query parameters). Esempi includono:

    • fiscalCode: Il codice fiscale dell'utente di cui si richiedono i dati.

    • format: Un parametro che specifica il formato in cui i dati devono essere restituiti dal pdnd-connector. Questo formato deve essere compatibile con il Nested Form di OpenCity che riceverà i dati.

    • Esempio URL: GET /e-services/anpr/stato-famiglia?fiscalCode=ABCDEF01G23H456I&format=statoFamigliaArchetipo

  • Per POST (Validazione): Il payload della richiesta POST deve contenere due campi principali:

    • data: L'oggetto JSON contenente i dati esatti (incluso il loro formato) così come ricevuti dalla risposta GET precedente, senza i metadati di isFromPdnd, isReadonly, isUpdatedToday.

    • meta: Un oggetto contenente la firma digitale (signature) dei dati, così come restituita dalla risposta GET.

• Header Necessari: Per tutte le chiamate agli endpoint del pdnd-connector, è necessario includere un token JWT nell'header Authorization.

  • Authorization: Bearer <JWT_TOKEN>. Il pdnd-connector effettua una validazione del token. Per le API di configurazione (non direttamente usate da OpenCity per fruizione), è richiesto un admin token. Per le API di fruizione e validazione, è richiesto un user token, e il codice fiscale contenuto nel token viene verificato con quello eventualmente presente nella URL.

Esempi di chiamate API

Di seguito, alcuni esempi di richieste e risposte per chiarire il flusso di integrazione.

Accertamento Residenza

Richiesta:

Risposta:

È disponibile anche il formato "residenza_archetipo" che include campi aggiuntivi:

Stato Famiglia

Richiesta:

Risposta (esempio con coniuge e figli):

Validazione delle risposte

Per validare l'autenticità di una risposta, si utilizza il relativo l'endpoint di validazione:

Richiesta:

Risposta:

Definizione OpenAPI

Test delle chiamate SOAP/REST dell'intermediario

Le API fornite nella documentazione dell'intermediario vengono generalmente testate in prima battuta via Postman/Insomnia nel caso di chiamate REST o via SoapUI nel caso di chiamate SOAP

Test in ambiente locale

A seguito dei test delle chiamate, si procede con l'implementazione del microservizio. Per testarlo localmente fare riferimento al seguente docker-compose.yml

version: '2'

services:
  zookeeper:
    image: confluentinc/cp-zookeeper:7.0.0
    hostname: zookeeper
    ports:
      - "2181:2181"
    environment:
      ZOOKEEPER_CLIENT_PORT: 2181
      ZOOKEEPER_TICK_TIME: 2000

  kafka:
    image: confluentinc/cp-kafka:7.0.0
    hostname: kafka
    depends_on:
      - zookeeper
    ports:
      - "29092:29092"
    environment:
      KAFKA_BROKER_ID: 1
      KAFKA_ZOOKEEPER_CONNECT: 'zookeeper:2181'
      KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: PLAINTEXT:PLAINTEXT,PLAINTEXT_HOST:PLAINTEXT
      KAFKA_ADVERTISED_LISTENERS: PLAINTEXT://kafka:9092,PLAINTEXT_HOST://localhost:29092
      KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
      KAFKA_GROUP_INITIAL_REBALANCE_DELAY_MS: 0
      KAFKA_TRANSACTION_STATE_LOG_MIN_ISR: 1
      KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR: 1
      KAFKA_CREATE_TOPICS: "applications,payments_cache"

  kafka-ui:
    image: provectuslabs/kafka-ui:latest
    ports:
      - "8080:8080"
    depends_on:
      - kafka
    environment:
      KAFKA_CLUSTERS_0_NAME: local
      KAFKA_CLUSTERS_0_BOOTSTRAPSERVERS: kafka:9092
      # KAFKA_CLUSTERS_0_ZOOKEEPER: zookeeper:2181
      KAFKA_CLUSTERS_0_KSQLDBSERVER: ksqldb-server:8088

  topic-init:
    image: lorello/alpine-bash:1.4.0    
    depends_on:      
      - kafka    
    volumes:      
      - ./init.d:/data    
    command:      
      - /bin/bash      
      - -c      
      - |          
          wait-for-it kafka:9092          
          kaf config add-cluster local -b kafka:9092 && \          
          kaf config use-cluster local          
          set -ex          
          for I in /data/payment*.json; do            
            echo "Importing $$I"            
            cat $$I | jq -c | kaf produce payments          
          done

  # la configurazione varia in base al proxy da implementare
  iris-proxy:
    build:
      context: .
    ports:
      - "8000:8000"
    environment:
      CANCEL_PAYMENT: "false"
      KAFKA_TOPIC_NAME: "payments"
      KAFKA_BOOTSTRAP_SERVERS: "kafka:9092"
      KAFKA_GROUP_ID: "iris_payment_proxy"
      IRIS_OTF_PAYMENT_URL: "https://apistage.regione.toscana.it/C01/ComunicazionePosizioniDebitorieOTF/v3/IdpAllineamentoPendenzeEnteOTF"
      IRIS_IUV_URL: "https://iristest.rete.toscana.it/IdpBillerNdpServices/GenerazioneIUVService"
      IRIS_OUTCOME_URL: "https://apistage.regione.toscana.it/C01/InvioNotificaPagamentoEsito/v3/IdpInformativaPagamento.Esito"
      IRIS_VERIFY_URL: "https://apistage.regione.toscana.it/C01/VerificaStatoPagamento/v3/IdpVerificaStatoPagamento"
      IRIS_NOTICE_URL: "https://iristest.rete.toscana.it/IdpBillerNdpServices/GenerazioneAvvisiService"
      BASE_PATH_CONFIG: "sdc-payments/iris/tenants/"
      BASE_PATH_EVENT: "sdc-payments/iris/payments/"
      STORAGE_TYPE: "MINIO"
      STORAGE_KEY: "AKIAIOSFODNN7EXAMPLE"
      STORAGE_SECRET: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
      STORAGE_BUCKET_NAME: "payments"
      STORAGE_ENDPOINT: "minio:9000"
    depends_on:
      - createbuckets
      - kafka

  # storage dove vengono salvate le configurazioni del tenant, del servizio e lo stato dei vari pagamenti
  minio:
    image: minio/minio
    command: server /data --console-address ":9001"
    restart: unless-stopped
    volumes:
      - ./bucket:/data
    ports:
      - 9000:9000
      - 9001:9001
    environment:
      MINIO_ACCESS_KEY: AKIAIOSFODNN7EXAMPLE
      MINIO_SECRET_KEY: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

  createbuckets:
    image: minio/mc
    depends_on:
      - minio
    entrypoint: >
        /bin/sh -c "
        while ! /usr/bin/mc config host add minio http://minio:9000 AKIAIOSFODNN7EXAMPLE wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY;
        do echo 'Wait minio to startup...' && sleep 0.1; done;
        /usr/bin/mc mb minio/payments;
        /usr/bin/mc policy set public minio/payments;
        exit 0;
        "

Test pre-deploy

Se si sta facendo il deploy di un nuovo microservizio per la prima volta o si sta aggiungendo una nuova API o una nuova pagina a una interfaccia esistente, è necessario aggiungere alcuni controlli di qualità minima prima del rilascio.

Controlli

• Test automatici delle API nella CI (usare hurl, qui un esempio di utilizzo e qui un esempio di integrazione nelle CI)

• Test flusso standard

  • Inserire la configurazione del tenant

  • Inserire la configurazione del servizio

  • Inserire un esempio di pagamento in stato CREATION_PENDING nel topic payments e verificare che venga correttamente creato il debito

    • Chiamare l'API /offline-payment/{id} e verificare che venga scaricato correttamente l'avviso di pagamento cartaceo

    • Chiamare l'API /online-payment/{id} e verificare che si venga rediretti al portale di pagamento

    • Una volta arrivati in fondo al pagamento online, verificare che premendo il bottone "Torna alla Home" venga chiamata correttamente l'API /landing/{id}

    • Chiamare l'API /update/{id} e verificare che venga correttamente controllato lo stato del pagamento ed eventualmente aggiornato e prodotto un evento sul topic payments

    • Chiamare l'API /receipt/{id} e verificare che, a pagamento avvenuto, venga scaricata correttamente la ricevuta telematica

    • Inserire un esempio di pagamento in stato PAYMENT_PENDING che è già stato processato precedentemente dal proxy e verificare che venga ignorato

    • Inserire un esempio di pagamento in stato PAYMENT_PENDING che non è già stato processato precedentemente dal proxy e per cui esiste una configurazione sullo storage, e verificare che venga salvato correttamente sullo storage (caso importazione dovuti)

• Test flusso di errore

  • Modificare la configurazione del servizio in modo che sia errata (mettendo ad esempio credenziali errate)

  • Inserire un esempio di pagamento in stato CREATION_PENDING nel topic payments e verificare che, a seguito del fallimento, venga prodotto un evento in stato CREATION_FAILED nel topic payments

Test in ambiente QA

I pagamenti sono testabili sul nostro ambiente di qa: https://servizi.comune-qa.bugliano.pi.it/.

Si potrà accedere come utente SPID utilizzando l'utente AGID TEST DEMO.

Si potrà accedere come admin per eventualmente modificare il servizio di test e la relativa configurazione di pagamento

Si potrà accedere come operatore per testare pagamenti posticipati, i quali richiedono la presa in carico della pratica e l'approvazione di quest'ultima affinchè l'utente possa procedere con il pagamento.

Il Protocol Proxy interagisce con la piattaforma in due fasi distinte ma complementari:

• Abilitazione e configurazione del sistema di protocollazione

• Protocollazione dei documenti

Fase 1 - abilitazione di un nuovo servizio di protocollazione per il servizio X(happy path)

In questa fase l'amministratore della piattaforma configura un servizio, decidendo quale sistema di protocollazione abilitare per la protocollazione dei relativi servizi.

Cliccando sul bottone "abilita" la piattaforma contatta il Protocol proxy relativo tramite chiamate REST API. Con la prima chiamata, la piattaforma richiede la configurazione del form schema che verrà presentato all'Amministratore. Attraverso tale form è possibile inserire le configurazioni relative al tenant e al servizio corrente. Tali configurazioni verranno inviate via REST HTTPS al Protocol Proxy che si occuperà della persistenza di tali configurazioni.

Una volta che tale processo si è concluso, il Protocol Proxy è in grado, sfruttando tali configurazioni, di interagire con il sistema di protocollazione esterno.

Le configurazioni di protocollazione possono essere create, modificate e disabilitate. Per questo motivo il Protocol Proxy deve esporre chiamate API CRUD (dettagliate nella pagina seguente).

Fase 2 - Protocollazione dei documenti (happy path)

Prima di eseguire qualsiasi operazione, il protocollo proxy deve verificare la versione dell'evento (event_version) ed elaborare esclusivamente la versione 1, per la quale è abilitato. La versione dell'evento da considerare deve essere un valore fissato nel codice. Tutti gli eventi con event_version diversa da 1 devono essere scartati.

In questo diagramma, viene descritto il workflow di una pratica (ma il processo è uguale per qualsiasi altro tipo di richiesta) presentata da un utente e presa in carico da un operatore(le altre casistiche descritte nella pagina "Architettura del sistema di protocollazione" seguono lo stesso processo).

Una volta che la pratica è stata presa in carico dell'operatore essa deve essere protocollata. La piattaforma produce un evento di tipo documento sul topic "documents". Il Protocol Proxy, consuma tale evento:

• Per poter protocollare correttamente il documento, è fondamentale verificare l'esistenza delle configurazioni relative al tenant e al servizio pertinenti. Questa operazione può essere eseguita attraverso la verifica del campo document.RemoteCollection.ID, che identifica il servizio, e document.tenantId, che identifical'ID del tenant. Questi campi dovrebbero essere confrontati con gli ID delle configurazioni corrispondenti precedentemente salvate nello storage. Nel caso in cui tali configurazioni non siano disponibili, il documento dovrà essere semplicemente ignorato, procedendo all'evento successivo.

• Una volta assicuratosi di dover protocollare il documento in esame, il Protocol Proxy deve verificare che il documento non sia già stato protocollato. Un evento è protocollato quando l'oggetto "document_number" è valorizzato con almeno il numero di protocollo. Nel caso il documento sia già stato protocollato, l'evento va semplicemente ignorato.

• Una volta verificato che il documento sia da protocollare, è necessario modificare il campo status da DOCUMENT_CREATED o REGISTRATION_FAILED o PARTIAL_REGISTRATION a REGISTRATION_PENDING, poi si produce l'evento sul topic documents

• Una volta che si rilegge lo stesso evento prodotto allo step precedente, e una volta superate le precedenti verifiche, Protocol Proxy può interagire con il sistema di protocollazione esterno per la protocollazione del documento.

• Se la protocollazione va a buon fine, il documento verrà modificato con i dati di protocollazione (vedi sezione successive), verrà inoltre sovrascritto il campo stato settandolo a REGISTRATION_COMPLETE , infine, sarà necessario aggiornare anche il campo updated_at con il timestamp corrente (time.now()) in formato ISO 8601 (es: 2023-11-10T10:54:44+00:00).

• Il Protocol Proxy produce un nuovo evento di tipo document sul topic documents con in aggiunta le informazioni di protocollazione (valorizzando l'oggetto registration_data).

• A questo punto la piattaforma, in ascolto sullo stesso topic, provvederà ad aggiornare il suo stato interno.

Altri campi da popolare quando si produce un evento

Quando viene generato un evento, il protocollo proxy deve assegnare i seguenti valori:

• app_id: <nome del servizio>:<versione corrente del servizio>. Es: protocol-proxy-fake:1.1.1

• event_created_at: es: 2023-11-23T14:14:23+00:00

• event_id: stringa UUID autogenerata che identifica univocamente l'evento

Casi di errore - sistema di retry

In un sistema a eventi che utilizza il pattern event sourcing, è possibile che alcuni eventi non vengano processati correttamente a causa di errori temporanei come per esempio una comunicazione interrotta tra il Protocol Proxy e il sistema di protocollazione esterno. In questo caso basterebbe tentare nuovamente il consumo dello stesso evento più volte finché il problema non viene risolto.

La piattaforma offre questo tipo di possibilità attraverso l'implementazione di un meccanismo di retry che legge da un topic (retry_queue) specifico tutti gli eventi falliti e li reinserisce nei vari topic di origine in base a una politica di retry scelta a monte.

Il servizio che si occupa di questo meccanismo è in grado di gestire eventi eterogenei provenienti da diversi topic. Questo è possibile solo se il servizio è a conoscenza del topic di origine in cui reinserire gli eventi da processare nuovamente.

Per questo motivo, qualsiasi servizio si voglia avvalere del meccanismo di retry, deve modificare l'evento fallito inserendo il topic in cui si vuole che sia reinserito e poi produrre l'evento nel topic di retry impostato tramite variabile d'ambiente.

I metadati da inserire nell'evento sono nella seguente forma:

{   
   "retry_meta": {
     "original_topic": "documents"
   }
}

Quando l'oggetto sarà reinserito nel topic "document" dal Retry Orchestrator, l'oggetto "retry_meta" avrà dei campi aggiuntivi utili per attuare la politica di retry. Tali campi, sono gestiti e utili unicamente al Retry Orchestrator. Il Protocol Proxy non si deve quindi preoccupare di tale oggetto una volta inserito l'oggetto "retry_meta" con il campo "original_topic" valorizzato una tantum.

Use case : protocollazione totalmente fallita

Nel caso in cui non si riesca a protocollare la pratica per un errore da parte del provider per esempio, o nel caso in cui nessuno delle chiamate al protocollo vadano a buon fine, è necessario sovrascrivere il campo status a REGISTRATION_FAILED.

Use case : protocollazione avvenuta a metà e deve essere ripresa da do dove è stata interrotta

Nel caso in cui la protocollazione richieda diversi step (come per esempio protocollazione del documento principale e a seguito la protocollazione dei vari allegati) e questa venga interrotta a metà, l'evento dovrà essere inserito nella coda di retry assime alle informazioni relative allo stato corrente in modo da riprendere la protocollazione da dove è stata interrotta. Specificamente il documento va messo nello stato PARTIAL_REGISTRATION.

In tale circostanza, è possibile inserire liberamente tutti i campi rilevanti per il monitoraggio dello stato all'interno dell'oggetto retry_meta. Questa flessibilità consente di adattare i dati alle specifiche esigenze, garantendo un controllo accurato del processo di protocollazione e prevenendo duplicazioni delle operazioni.

Solitamente la protocollazione di un documento digitale è accompagnata anche dalla protocollazione dei relativi allegati(menzionati nel paragrafo ) e dalla fascicolazione degli stessi. Dal punto di vista del Protocol Proxy, la protocollazione del documento, di tutti i suoi allegati e la fascicolazione è considerata come un unica operazione atomica. Questo implica che il processo di protocollazione è considerato completo solo quando tutte le chiamate relative al documento principale, agli eventuali allegati e alla eventuale fascicolazione si concludono con successo. Se anche solo una chiamata dovesse fallire, questo costituirà una condizione sufficiente per interrompere il processo di protocollazione e avviare il meccanismo di retry descritto nel paragrafo precedente.

Schema degli stati di un documento

Il documento può avere i seguenti stati:

• DOCUMENT_CREATED : stato iniziale in cui si trova il documento quando viene prodotto dal document dispatcher

• REGISTRATION_PENDING : stato in cui viene prodotto il documento dal protocol proxy non appena viene trovato in stato DOCUMENT_CREATED, PARTIAL_REGISTRATION o REGISTRATION_FAILED e presenta una configurazione attiva per esso

• REGISTRATION_COMPLETE : stato in cui viene prodotto il documento dal protocol proxy dopo essere stato protocollato correttamente

• PARTIAL_REGISTRATION : stato in cui viene prodotto il documento dal protocol proxy nel caso in cui si ha molteplici chiamate da fare e una di questa fallisce (per esempio non vengono caricati tutti gli allegati)

• REGISTRATION_FAILED : stato in cui viene prodotto il documento dal protocol proxy nel caso in cui la protocollazione fallisce totalmente

Di seguito la rappresentazione grafica

La fascicolazione dei documenti protocollati

La Fascicolazione di un documento rappresenta l'attribuzione dello stesso ad una unità archivistica – “il fascicolo” - che raggruppa un insieme di documenti appartenenti al medesimo procedimento. Non tutti i sistemi di protocollazione offrono questa funzionalità. In questo caso la valorizzazione del campo "folder_number" deve essere discussa e definita a seconda dei casi.

Interazione Protocol Proxy<--> Piattaforma Opencity

Durante la fase di protocollazione, è possibile che il Protocol Proxy debba utilizzare le API della piattaforma per ottenere le informazioni necessarie per eseguire il processo di protocollazione. Un esempio pratico di ciò riguarda la protocollazione degli allegati. Il sistema di protocollazione richiede che il base64 del file allegato sia incluso nel payload della chiamata. Tuttavia, nel documento digitale sono presenti solo i link per scaricare i file. Pertanto, sarà compito del Protocol Proxy autenticarsi sulla piattaforma per recuperare il Token JWS e successivamente chiamare l'API specifica per ottenere il file necessario da cui calcolare il Base64.

Il token può essere recuperato con la seguente chiamata:

• Username : admin

• Password: admin

• Basepath: estratto dal campo "Url" di ogni allegato

• Endpoint : /lang/api/auth

• method: POST

• header Content-Type: application/json

• payload : { "username": "admin", "password": "admin" }

• Response: 200 -> {"token": "eyDIJeiojf...."}

• Response: 401 -> { "code": 401, "message": "Credenziali non valide." }

• Response 400 -> HTML body

Le API della piattaforma sono documentate al seguente link: https://servizi.comune-qa.bugliano.pi.it/lang/api/doc Calcolo del basepath per recuperare il token L'url per API auth deve essere estratta da campo url di ogni attachment: quindi dal seguente documento avremo una post auth all'endpoint https://servizi.comune-di-vicenza.it/lang/api/auth con credenziali fornite tramite variabili d'ambiente(utente e password). Mentre nel secondo caso avremo una post auth all'endpoint https://servizi.comune-di-bugliano.it/lang/api/auth con credenziali fornite tramite variabili d'ambiente(utente e password).

NOTA BENE: nel seguente esempio abbiamo un array di attachments in cui due url appartengono a due comuni diversi. Questo nel mondo reale non può succedere. Il base url è lo stesso per tutto il documento(cioè un documento appartiene ad un solo comune). Sono stati utilizzati due comuni diversi allo scopo di sottolineare la parte di url che cambia nella costruzione dell'endpoint della API di autenticazione.

{
   "attachments": [
	{
		"name": "dummy.pdf",
		"description": "Allegato - dummy.pdf",
		"mime_type": "application/pdf",
		"url": "https://servizi.comune-di-vicenza.it/lang/api/applications/1a30529e-9c41-4352-9198-1fac44c5e911/attachments/a4c81464-ee91-449a-b2a3-7010c59fdee7?version=1",
		"md5": "",
		"filename": "dummy.pdf"
	},
	{
		"name": "dummy2.pdf",
		"description": "Allegato - dummy2.pdf",
		"mime_type": "application/pdf",
		"url": "https://servizi.comune-di-bugliano.it/lang/api/applications/1a30529e-9c41-4352-9198-1fac44c5e911/attachments/d284be8a-2700-48a9-aa4b-fc0136674548?version=1",
		"md5": "",
		"filename": "dummy2.pdf"
	}
   ],
}   

Tutti i servizi devono rispettare i 12factor, descritti in modo anche più dettagliato nell'articolo An illustrated guide to 12 Factor Apps

Packaging

Obiettivo

Ogni microservizio deve poter essere eseguito facilmente in locale, anche da chi non conosce a fondo il progetto. L’obiettivo del packaging è:

• facilitare l’avvio dell’applicativo;

• semplificare lo sviluppo e il debugging;

• rendere accessibile un ambiente funzionante con un semplice docker-compose up.

Struttura del repository

Nella root del repository devono essere presenti i seguenti file:

Principi e buone pratiche

• Il file docker-compose.yml deve essere autosufficiente: chi lo scarica deve poter eseguire il servizio senza dover clonare l’intero repository.

• Le immagini Docker utilizzate devono essere:

  • disponibili su un registry pubblico (es. DockerHub, GitHub Container Registry ecc.);

  • oppure facilmente costruibili in locale tramite override.

⚠️ Non includere la chiave build: nel docker-compose.yml principale, per evitare conflitti nei contesti di esecuzione remota (es. CI/CD).

Sviluppo locale

Per lo sviluppo in locale:

1. Copia o rinomina il file docker-compose.dev.yml in docker-compose.override.yml

2. Esegui:

   Copy

   docker-compose up

3. Docker gestirà automaticamente il merge tra docker-compose.yml e docker-compose.override.yml (vedi: Docker Docs – Multiple Compose Files).

✅ In questo modo, chiunque può avviare l’ambiente di sviluppo senza modificare i file originali.

Esempio di uso dei file

docker-compose.yml (semplificato)

version: "3.9"
services:
  myservice:
    image: registry.gitlab.com/opencity-labs/myservice:1.2.3
    ports:
      - "8080:8080"

docker-compose.dev.yml

version: "3.9"
services:
  myservice:
    build:
      context: .
      dockerfile: Dockerfile
    volumes:
      - ./:/app
    environment:
      - ENVIRONMENT=local

Dopo aver rinominato docker-compose.dev.yml in docker-compose.override.yml, il comando:

docker-compose up

...utilizzerà in automatico l’immagine build locale con i volumi montati per lo sviluppo.

Terminazione Pulita

Obiettivo

Ogni microservizio deve essere in grado di gestire correttamente la terminazione, in modo da:

• garantire la consistenza dei dati;

• evitare la perdita di eventi o operazioni incomplete;

• chiudere le risorse in uso in maniera sicura (DB, Kafka, file, socket...).

La gestione corretta della terminazione è essenziale sia in ambiente Docker che in Kubernetes, dove il segnale di terminazione (SIGTERM) viene inviato prima di un restart o di un downscaling.

Segnali da gestire

✅ Il servizio DEVE catturare SIGTERM e avviare una sequenza di terminazione controllata.

Comportamento atteso

Alla ricezione di SIGTERM, il servizio deve:

• smettere di accettare nuove richieste o eventi;

• completare le operazioni critiche in corso;

• liberare risorse (connessioni, file, lock...);

• loggare la terminazione a livello INFO;

• uscire con exit code 0 entro un tempo ragionevole.

Checklist – Terminazione Pulita

Esempio Python – uvicorn + asyncio

import asyncio
import signal
import uvicorn
from myservice import app

APP_HOST = "0.0.0.0"
APP_PORT = 8080

def run_server():
    """Esegue il server intercettando SIGINT e SIGTERM per uno shutdown pulito"""
    config = uvicorn.Config(
        app,
        host=APP_HOST,
        port=int(APP_PORT),
        proxy_headers=True,
        forwarded_allow_ips='*',
        access_log=False,
    )
    server = uvicorn.Server(config)

    loop = asyncio.get_event_loop()

    for sig in (signal.SIGINT, signal.SIGTERM):
        loop.add_signal_handler(sig, lambda: asyncio.create_task(server.shutdown()))

    try:
        loop.run_until_complete(server.serve())
    except asyncio.CancelledError:
        pass  # Evita traceback in console

if __name__ == '__main__':
    run_server()

Esempio Go – signal.NotifyContext

package main

import (
    "context"
    "log"
    "net/http"
    "os"
    "os/signal"
    "syscall"
    "time"
)

func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("/ping", func(w http.ResponseWriter, r *http.Request) {
        w.Write([]byte("pong"))
    })

    srv := &http.Server{
        Addr:    ":8080",
        Handler: mux,
    }

    ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
    defer stop()

    go func() {
        log.Println("Server in avvio su :8080")
        if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
            log.Fatalf("Errore durante l'avvio del server: %v", err)
        }
    }()

    <-ctx.Done()
    log.Println("SIGTERM ricevuto, avvio terminazione...")

    shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
    defer cancel()

    if err := srv.Shutdown(shutdownCtx); err != nil {
        log.Fatalf("Errore durante la terminazione: %v", err)
    }

    log.Println("Terminazione completata.")
}

Script di test automatico

Usare questo script per validare la terminazione pulita in locale o integrarlo nella CI.

#!/bin/bash
set -euo pipefail

SERVICE_NAME="test_shutdown_service"
IMAGE_NAME="your-image-name"
LOG_FILE="shutdown_test.log"

echo "▶️ Avvio container..."
docker run --rm --name "$SERVICE_NAME" -d "$IMAGE_NAME" > /dev/null

sleep 2  # attesa minima per stabilità

echo "🛑 Invio SIGTERM..."
docker kill --signal=SIGTERM "$SERVICE_NAME"

sleep 2

echo "🔍 Verifica terminazione..."
if docker ps -a --format '{{.Names}}' | grep -q "$SERVICE_NAME"; then
  echo "❌ Il container è ancora in esecuzione"
  exit 1
else
  echo "✅ Terminazione completata correttamente"
fi

• Se si usa docker-compose, si può integrare il test nel CI lanciando:

  Copy

  docker-compose -f docker-compose.yml -f docker-compose.override.yml up -d
  docker-compose kill -s SIGTERM

Configurazione

Principi

La configurazione dei microservizi deve avvenire:

• principalmente tramite variabili d’ambiente;

• opzionalmente tramite:

  • file .env (per ambienti locali);

  • parametri CLI (per job schedulati o debug interattivo).

Best practice

❗ Le configurazioni non devono essere hardcoded nel codice. Utilizzare sempre default sicuri e sovrascrivibili.

Healthcheck

Obiettivo

Permettere al sistema di orchestrazione (Docker/Kubernetes) di verificare che il servizio sia vivo e funzionante.

HTTP microservizi

• Deve esporre un endpoint /status:

  • 200 OK se tutto è funzionante;

  • codice diverso in caso di errore.

Altri microservizi

• Se il servizio non è HTTP, l’healthcheck può essere:

  • la presenza di un file di stato;

  • la verifica di un processo in esecuzione.

✅ L’healthcheck DEVE essere incluso nel Dockerfile.

Logging

Principi generali

• Tutti i microservizi devono implementare un sistema di log coerente, strutturato e facilmente aggregabile.

• Riferimento normativo: Allegato 4 delle Linee Guida di Interoperabilità AgID.

• I log devono supportare almeno i livelli: DEBUG, INFO, ERROR. Una gestione completa prevede sei livelli (vedi sotto).

• Ogni log di errore o anomalia deve essere su una singola riga, facilmente parsabile (plaintext key=value o JSON).

• Evitare log verbosi e non strutturati: ostacolano il monitoraggio e la correlazione cross-microservizio.

⚠️ Non mischiare log di tipo HTTP e stacktrace multilinea.

• Scrivere i log a singola riga su stdout.

• Scrivere stacktrace (se necessario) separatamente su stderr.

Formato e contenuto dei log

• Preferibile l’uso di log in formato JSON puro, ma solo se interamente strutturato.

• È vietato:

  • Mischiare testo libero e JSON nello stesso log.

  • Includere payload JSON grezzi come stringa in un campo JSON (es. loggare interamente l’evento Kafka).

Campi richiesti in ogni log rilevante

All’avvio, ogni servizio DEVE loggare la versione in esecuzione e l’ambiente (es. local, boat-qa, boat-prod).

Livelli di log

✅ Ogni anomalia deve generare una e una sola riga di log a INFO, i dettagli vanno a DEBUG.

Esempi di log ben formattati

JSON strutturato

{
  "level": "ERROR",
  "timestamp": "2025-04-18T10:27:52Z",
  "environment": "boat-prod",
  "event_id": "abcd-1234",
  "event_type": "PaymentRequestReceived",
  "topic": "pagopa-incoming-events",
  "version": "1.3.2",
  "environment": "boat-prod",
  "tenant": "9bee12a4-...",
  "application": "50b4f598-...",
  "service": "0a28427f-...",
  "provider": "sicraweb-wsprotocollodm",
  "client_ip": "10.12.3.1",
  "user_id": "user_92348",
  "status": "error",
  "message": "Impossibile trovare dati di logon validi per l'utente"
}

Plaintext key=value

ERROR 2025-04-18T10:27:52Z event_id=abcd-1234 tracker=252603771125040 provider=sicraweb-wsprotocollodm tenant=9bee12a4 application=50b4f598 service=0a28427f topic=pagopa-incoming-events microservice=payment-handler version=1.3.2 environment=boat-prod client_ip=10.12.3.1 user_id=user_92348 error="Impossibile trovare dati di logon validi per l'utente; nested exception: Connection aborted (Connection reset by peer)"

Checklist di qualità per log ERROR

Usare questa checklist in review e PR:

• Il log è su una singola riga?

• Include event_id, event_type, topic, microservice, error?

• I dati personali sono esclusi?

• Il messaggio è leggibile e utile senza stacktrace?

• È facilmente aggregabile da dashboard/log viewer?

Monitoring errori

Obiettivo

Raccogliere centralmente gli errori per individuare rapidamente problemi in produzione.

Requisiti

• Ogni microservizio DEVE integrare Sentry.

• Una volta configurato:

  • abilitare l’integrazione con Sentry;

  • definire regole di alert personalizzate, se quelle standard non bastano.

📬 Usare SENTRY_DSN come variabile d’ambiente per collegare il servizio a Sentry.

Monitoring metriche

Obiettivo

Esportare metriche di stato e performance per il monitoraggio continuo.

Endpoint Prometheus

• Se HTTP, il microservizio DEVE esporre un endpoint /metrics in formato Prometheus.

Cosa monitorare

Cron

Principio

Non reinventare un sistema di schedulazione dentro l’applicazione. Usare invece l’orchestratore.

Linee guida

• NON implementare schedulatori interni (es. cron manuale, loop time-based).

• Il servizio deve essere idempotente: rieseguibile sugli stessi dati senza effetti collaterali.

Esecuzione corretta

Implementare task cron come comandi CLI, eseguibili con la stessa immagine Docker:

docker run your-image-name python cron_jobs/protocol_batch.py

Il job verrà poi schedulato tramite clustered cron (es. crazy-max/cronjob).

Parametri e file di configurazione

Principio

Niente overengineering: Docker impone già un mapping tra esterno e interno.

Best practice