WorkFlow sistema di protocollazione
Last updated
Sviluppatori e partner tecnologici
Last updated
Documentazione Opencity Italia
Il Protocol Proxy interagisce con la piattaforma in due fasi distinte ma complementari:
Abilitazione e configurazione del sistema di protocollazione
Protocollazione dei documenti
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).
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.
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
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:
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.
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.
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.
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 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.
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.
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.
