1 of 13

Integrazione con Protocollo Informatico

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.

Requisiti per l'integrazione

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:

invio di una pratica da parte del cittadino
invio di una richiesta di integrazioni da parte di un operatore
invio di una integrazione da parte del cittadino
approvazione/rifiuto di una pratica

Altre azioni possibili, mediante configurazioni avanzate del servizio:

creazione di una pratica da parte di un operatore per conto di un cittadino
ritiro di una pratica da parte del cittadino
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:

Ricerca di un documento per Numero di protocollo
Invio di un Documento principale
Invio di allegati al documento principale
Protocollazione di un documento e dei suoi allegati: se disponibile, preferiamo avere una chiamata atomica, che protocolla il documento principale e i suoi allegati.
Ricerca di un fascicolo per Numero di fascicolo
Creazione di un fascicolo
Aggiunta di un documento ad un fascicolo esistente

Processo di integrazione

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

Test delle chiamate al sistema di protocollo effettuate in modo manuale
Validazione della protocollazione manuale da parte dell’Ente
Implementazione e rilascio dell’integrazione in ambiente di Quality Assurance
Validazione su un servizio di test
Rilascio in ambiente di produzione
(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.

Esempio documento con allegati non protocollato

Esempio documento con allegati protocollato

Esempio documento con campo retry_meta prodotto dal protocol proxy

Il campo "retry_meta" è stato creato dal protocol proxy e contiene il topic di origine ed eventuali campi utili al protocol proxy per tenere lo stato della protocollazione

Esempio documento con campo retry_meta modificato dal sistema di retry

Il campo "retry_meta" contiente le informazioni inserite dal sistema di retry. Queste dovrebbero essere ignorate da protocol proxy

Usecase: Il Documento originato dalle pratiche dai servizi digitali

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:

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

Architettura del sistema di protocollazione

Questa pagina descrive l'architettura impiegata per attuare il processo di protocollazione di una pratica

Seguendo l'approccio del C4Model 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.

Invio di una pratica da parte del cittadino
Invio di una richiesta di integrazioni da parte di un operatore
Invio di una integrazione da parte del cittadino
Approvazione/rifiuto di una pratica

Altre azioni possibili, mediante configurazioni avanzate del servizio:

Creazione di una pratica da parte di un operatore per conto di un cittadino
Ritiro di una pratica da parte del cittadino
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.

WorkFlow sistema di protocollazione

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 #struttura) 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"
	}
   ],
}

Configurazione tenant e servizi

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

Protocol Proxy: Specifiche Implementative

Requisiti Generali - controllare pagina standard e convenzioni

Ogni microservizio deve rispettare gli standard della piattaforma
Ogni proxy deve soddisfare i requisiti suggeriti dal 12 factors manifest
Esposizione di un endpoint/status per l'healthcheck: esso deve essere restituire 200 se il sistema è "healthy" e 503 in caso si presentino un problemi di connessione con kafka
Esposizione delle metriche mediante l'endpoint /metrics con Prometheus utilizzando la convenzione da loro suggerita
Terminazione pulita del servizio (timeout di 15 secondi)
Esposizione di un endpoint /docs per la consultazione della documentazione delle API esposte dal servizio secondo lo standard OpenAPI
Integrazione con Sentry per l'error reporting
Il sistema di logging deve rispettare il formato Apache e descrivere nei tre livelli debug, error e info. Ogni log, quando possibile, deve loggare il remote_id e l'id del documento processato
Il README deve seguire le linee guida della pubblicazione del software open source
il nome del progetto e del servizio devono essere nella seguente forma : "Protocol Proxy <Nome del Protocollo Specifico>"
Inserire il file .gitlab-ci.yml riportando in esso questa pipeline

Metriche in dettaglio

Il Protocol Proxy deve esporre le seguenti metriche:

Metrica

Labels

Descrizione

Requisiti normativi

Avere una specifica in formato OpenAPI v3
Rispettare la Linee Guida di interoperabilità: in particolare per quanto riguarda
- il formato dei dati (4.2)
- raccomandazioni sul naming (4.3) optando per la scelta di snake_case per i nomi degli attributi
- logging (4.4)
- risultare valido nel validatore ufficiale OA3

Documentazione API di Esempio - Swagger

Specifiche funzionali

Il servizio deve essere multi tentant e multi servizio: deve quindi essere in grado di gestire le confiugurazioni per più tenant a cui possono essere attribuiti più servizi con il corrente sistema di protocollazione.
Ogni richiesta sia essa appartenente alla fase 1 o alla fase 2 descritte nella sezione "workflow sistema di protocollazione" devono essere trattate in maniera atomica.
Lo storage deve essere compatibile con Aws s3, Azure e local file system.

Configurazione del microservizio (variabili d'ambiente)

Il servizio deve essere configurabile attraverso le seguenti variabili d'ambiente.

Se le varibili senza valore di default non vengono settate, il servizio deve notificare la mancata impostazione attraverso un log di livello error e terminare in maniera pulita la propria esecuzione.

Test

Protocol Proxy Tests Checklist

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 documento non protocollato nel topic documents e verificare che venga correttamente protocollato
- Inserire un esempio di documento protocollato nel topic documents e verificare che venga ignorato
- Inserire un esempio di documento non protocollato nel topic documents per cui non esiste una configurazione di tenant e/o di servizio e verificare che venga ignorato
Test flusso di errore
- Modificare la configurazione del servizio in modo che sia errata (mettendo ad esempio credenziali errate)
- Inserire un esempio di documento non protocollato nel topic documents e verificare che, a seguito del fallimento, venga prodotto un evento nel topic di retry
- Correggere la configurazione del servizio
- Inserire il documento prodotto nel topic di retry all'interno del topic documents e verificare che venga correttamente protocollato

Processo di sviluppo

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 : https://gitlab.com/opencity-labs/area-personale/protocol-proxy-sipal

Documento digitale

Descrizione in dettaglio di un documento generato dalla piattaforma

Contesto

Secondo l'AGID, il documento informatico è la “rappresentazione informatica di atti, fatti o dati giuridicamente rilevanti" in contrapposizione al documento analogico ("rappresentazione non informatica di atti, fatti o dati giuridicamente rilevanti")".

La piattaforma genera documenti informatici a partire da diversi tipi di servizi offerti.

Il documento informatico ci permette di avere un'unica struttura dati a partire da diverse tipologie di servizi. Questo ci dà il vantaggio di dover gestire un’unica entità durante il processo di protocollazione.

Struttura

Il documento generato dall’area personale del cittadino è stato progettato seguendo le linee guida suggerite dall’AGID. Esso è composto dai seguenti elementi:

Documento principale: descrive in dettaglio il servizio o l'oggetto a cui il documento si riferisce.
Allegati del documento principale: rappresentano l'insieme dei file che accompagnano la documento principale, fornendo ulteriori dettagli, dati o documentazione di supporto.
metadati: includono informazioni utili per la comprensione del contesto del documento informatico. Ci forniscono dettagli sulle informazioni di base, come la data di creazione, il mittente, il destinatario, e altri dettagli pertinenti. Alcuni di essi non possono mancare(vedi sezione seguente).

Specifiche funzionali del documento

Nella nostra piattaforma il documento è implementato in forma di evento Kafka, in formato JSON, descritto dal seguente JSON SCHEMA.

Per una migliore visualizzazione si consiglia di usare un viewer online.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema#",
  "$id": "https://schema.opencontent.io/document.schema#",
  "type": "object",
  "title": "Documento",
  "definitions": {
    "registration_info": {
      "type": "object",
      "title": "Informazioni sul protocollo del documento",
      "properties": {
        "transmission_type": {
          "title": "Tipo di trasmissione",
          "type": "string",
          "enum": [
            "inbound",
            "outbound",
            "internal"
          ],
          "examples": [
            "inbound"
          ]
        },
        "date": {
          "title": "Data protocollo",
          "type": "string",
          "format": "date-time",
          "examples": [
            "2022-08-24T11:59:57+02:00"
          ]
        },
        "document_number": {
          "title": "Numero di protocollo",
          "description": "Numero di protocollo assegnato dal sistema di protocollazione",
          "type": "string",
          "maxLength": 255,
          "examples": [
            "Prot-123-456-789",
            "123"
          ]
        }
      },
      "required": [
        "transmission_type",
        "date",
        "document_number"
      ]
    },
    "folder_info": {
      "type": "object",
      "title": "Informazioni sul fascicolo",
      "properties": {
        "title": {
          "title": "Oggetto del Fascicolo",
          "type": [
            "string",
            "null"
          ],
          "maxLength": 255
        },
        "id": {
          "title": "Numero di Fascicolo",
          "type": [
            "string",
            "null"
          ],
          "maxLength": 255
        }
      },
      "required": [
        "title",
        "id"
      ]
    },
    "file": {
      "title": "File",
      "type": "object",
      "properties": {
        "name": {
          "title": "Titolo del file",
          "type": "string"
        },
        "description": {
          "title": "Descrizione del file",
          "type": [
            "string",
            "null"
          ]
        },
        "mime_type": {
          "title": "Mime type del file",
          "type": "string"
        },
        "url": {
          "title": "Download url della risorsa",
          "type": "string",
          "format": "uri"
        },
        "md5": {
          "title": "Hash md5 del binario",
          "type": "string"
        },
        "filename": {
          "title": "Nome completo del file con estensione",
          "type": "string"
        },
        "internal_url": {
          "title": "Eventuale url interno della risorsa a disposizione dei sistemi dell'ente che sarà utilizzato per servire il binario se questo non viene salvato nello storage della piattaforma",
          "type": [
            "string",
            "null"
          ],
          "format": "uri"
        }
      },
      "required": [
        "name",
        "filename",
        "description",
        "mime_type",
        "url",
        "md5"
      ]
    },
    "image": {
      "type": "object",
      "title": "Risorsa immagine",
      "properties": {
        "name": {
          "title": "Titolo dell'immagine",
          "type": "string"
        },
        "filename": {
          "title": "Nome dell'immagine",
          "type": "string"
        },
        "description": {
          "title": "Descrizione dell'immagine",
          "type": "string"
        },
        "license": {
          "title": "Licenza di utilizzo",
          "type": "string",
          "enum": [
            "?",
            "??",
            "???"
          ]
        },
        "type": {
          "title": "Tipologia dell'immagine o mime-type",
          "type": "string"
        },
        "url": {
          "title": "Url della risorsa",
          "type": "string",
          "format": "uri"
        }
      },
      "required": [
        "name",
        "filename",
        "license",
        "type",
        "url",
        "description"
      ]
    },
    "author": {
      "type": "object",
      "title": "Autore",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "human",
            "legal"
          ]
        },
        "tax_identification_number": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "family_name": {
          "type": [
            "string",
            "null"
          ]
        },
        "street_name": {
          "type": [
            "string",
            "null"
          ]
        },
        "building_number": {
          "type": [
            "string",
            "null"
          ]
        },
        "postal_code": {
          "type": [
            "string",
            "null"
          ]
        },
        "town_name": {
          "type": [
            "string",
            "null"
          ]
        },
        "country_subdivision": {
          "type": [
            "string",
            "null"
          ]
        },
        "country": {
          "type": [
            "string",
            "null"
          ]
        },
        "email": {
          "type": "string",
          "format": "email"
        }
      },
      "required": [
        "type",
        "tax_identification_number",
        "name",
        "family_name",
        "street_name",
        "building_number",
        "postal_code",
        "town_name",
        "country_subdivision",
        "country",
        "email",
        "role"
      ]
    }
  },
  "properties": {
    "title": {
      "type": "string",
      "maxLength": 255,
      "title": "Titolo del documento",
      "description": "Nome del documento. Il nome del Documento deve essere facilmente comprensibile dai cittadini. Vincoli: massimo 160 caratteri spazi inclusi",
      "examples": [
        "Istanza di certificato anagrafico"
      ]
    },
    "id": {
      "type": "string",
      "format": "uuid",
      "title": "Identificativo interno del documento",
      "description": "Identificatore uuid ad uso interno",
      "examples": [
        "4a68415b-e1a8-4f3a-a229-3f6678fd81d1"
      ]
    },
    "app_id": {
      "title": "App ID",
      "type": "string",
      "examples": [
        "document-dispatcher:1.1.1"
      ]
    },
    "event_created_at": {
      "title": "Data di creazione dell'evento",
      "type": "string",
      "format": "date-time",
      "examples": [
        "2023-11-23T14:14:23+00:00"
      ]
    },
    "event_id": {
      "title": "ID dell'evento",
      "type": "string",
      "format": "uuid"
    },
    "event_version": {
      "type": "integer",
      "title": "Versione del documento",
      "description": "Versione del documento",
      "default": 1,
      "examples": [
        1
      ]
    },
    "external_id": {
      "type": [
        "string",
        "null"
      ],
      "title": "Identificativo del documento ad uso dell'ente",
      "description": "Un numero identificativo del documento (es DOI, ISBN)",
      "examples": [
        "Cert567-2023",
        "4a68415b-e1a8-4f3a-a229-3f6678fd81d1"
      ]
    },
    "registration_data": {
      "title": "Protocollo",
      "anyOf": [
        {
          "title": "Informazioni sul protocollo del documento",
          "$ref": "#/definitions/registration_info"
        },
        {
          "title": "Nessuna informazione sul protocollo",
          "type": "null"
        }
      ]
    },
    "folder": {
      "title": "Fascicolo",
      "anyOf": [
        {
          "title": "Informazioni sul fascicolo",
          "$ref": "#/definitions/folder_info"
        },
        {
          "title": "Nessuna informazione sul fascicolo",
          "type": "null"
        }
      ]
    },
    "status": {
      "title": "Stato del documento",
      "description": "Stato del documento: descrive lo stato di protocollazione del documento",
      "type": "string",
      "enum": [
        "DOCUMENT_CREATED",
        "REGISTRATION_PENDING",
        "REGISTRATION_FAILED",
        "PARTIAL_REGISTRATION",
        "REGISTRATION_COMPLETE"
      ]
    },
    "type": {
      "title": "Tipo di documento",
      "description": "Tipologia del documento: viene utilizzata una tassonomia custom che va intesa come sotto tassonomia di Istanza https://schema.gov.it/lodview/controlled-vocabulary/classifications-for-documents/government-documents-types/8",
      "type": "string",
      "enum": [
        "application-request",
        "integration-request",
        "integration-response",
        "application-outcome",
        "application-withdraw",
        "application-revocation"
      ]
    },
    "remote_id": {
      "title": "Pratica associata",
      "description": "Identificativo della pratica associata",
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "examples": [
        "842b37e7-d835-49f0-92e2-a393ecda2e53"
      ]
    },
    "remote_collection": {
      "title": "Servizio collegato",
      "anyOf": [
        {
          "title": "Servizio collegato",
          "description": "Se il documento non è collegato a una pratica è possibile indicare il servizio che ha generato il documento",
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "format": "uuid",
              "examples": [
                "842b37e7-12a4-49f0-92e2-a393ecda2e53"
              ]
            },
            "type": {
              "type": "string",
              "enum": [
                "service",
                "service-group",
                "subscription",
                "calendar"
              ],
              "examples": [
                "service"
              ]
            }
          },
          "required": [
            "id",
            "type"
          ]
        },
        {
          "title": "Nessuna servizio collegato",
          "type": "null"
        }
      ]
    },
    "topics": {
      "title": "Argomenti",
      "description": "Argomenti collegabili",
      "type": "array",
      "minItems": 0,
      "items": {
        "title": "Argomento",
        "type": "string",
        "minItems": 0
      }
    },
    "short_description": {
      "title": "Descrizione breve",
      "description": "Descrizione sintetica del documento (max 255 caratteri) utilizzando un linguaggio semplice che possa aiutare qualsiasi utente a identificare con chiarezza il documento. Non utilizzare un linguaggio ricco di riferimenti normativi",
      "type": "string",
      "maxLength": 255
    },
    "description": {
      "title": "Descrizione",
      "description": "L'oggetto del documento, utilizzando un linguaggio semplice che possa aiutare qualsiasi utente a identificare con chierazza il documento. Non utilizzare un linguaggio ricco di riferimenti normativi.",
      "type": [
        "string",
        "null"
      ]
    },
    "main_document": {
      "title": "URL documento",
      "$ref": "#/definitions/file"
    },
    "image_gallery": {
      "title": "Galleria di immagini",
      "type": "array",
      "items": {
        "$ref": "#/definitions/image"
      },
      "minItems": 0
    },
    "has_organization": {
      "title": "Ufficio responsabile del documento",
      "anyOf": [
        {
          "title": "Link alla scheda dell'ufficio responsabile del documento",
          "type": "string",
          "format": "uri",
          "examples": [
            "https://example.com/offices/1"
          ]
        },
        {
          "title": "Nessuna informazione sull'ufficio",
          "type": "null"
        }
      ]
    },
    "attachments": {
      "title": "Allegati",
      "description": "Altre risorse oltre alla principale",
      "type": "array",
      "minItems": 0,
      "items": {
        "$ref": "#/definitions/file"
      }
    },
    "distribution_license_id": {
      "title": "Licenza di distribuzione",
      "type": [
        "string",
        "null"
      ]
    },
    "related_public_services": {
      "title": "Servizi collegati",
      "description": "Servizi che usano questo documento come input",
      "type": "array",
      "items": {
        "type": "object",
        "title": "Servizio collegato",
        "properties": {
          "name": {
            "id": "Id del servizio",
            "type": "string"
          },
          "type": {
            "title": "Tipologia del servizio",
            "type": "string"
          },
          "url": {
            "title": "Descrizione del file",
            "type": "string",
            "format": "uri"
          }
        },
        "required": [
          "id",
          "type",
          "url"
        ]
      },
      "minItems": 0
    },
    "valid_from": {
      "title": "Data inizio validità",
      "description": "Data da cui il documento è valido",
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "examples": [
        "2022-08-24T11:59:57+02:00"
      ]
    },
    "valid_to": {
      "title": "Data fine validità",
      "description": "Data da cui il documento non è più valido",
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "examples": [
        "2022-08-24T11:59:57+02:00"
      ]
    },
    "removed_at": {
      "title": "Data ultima disponibilità",
      "description": "Data fino alla quale il documento sarà disponibile online",
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "examples": [
        "2022-08-24T11:59:57+02:00"
      ]
    },
    "expire_at": {
      "title": "Data scadenza",
      "description": "Solitamente uguale a fine validità, è la data entro la quale il documento deve essere eventualmente rinnovato",
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "examples": [
        "2022-08-24T11:59:57+02:00"
      ]
    },
    "more_info": {
      "title": "Ulteriori informazioni",
      "description": "Ulteriori informazioni sul documento",
      "type": [
        "string",
        "null"
      ]
    },
    "normative_requirements": {
      "title": "Riferimenti normativi",
      "description": "Lista di link con riferimenti normativi utili per il documento",
      "type": "array",
      "minItems": 0,
      "items": {
        "type": "string",
        "format": "uri"
      }
    },
    "related_documents": {
      "title": "Documenti collegati",
      "description": "Lista di documenti allegati: link a quelli strutturati a loro volta come documenti",
      "type": "array",
      "minItems": 0,
      "items": {
        "type": "string",
        "format": "uri"
      }
    },
    "life_events": {
      "title": "Life Events",
      "description": "Life Events collegabili",
      "type": "array",
      "minItems": 0,
      "items": {
        "type": "string"
      }
    },
    "business_events": {
      "title": "Business Events",
      "description": "Business Events collegabili",
      "type": "array",
      "minItems": 0,
      "items": {
        "type": "string"
      }
    },
    "allowed_readers": {
      "title": "Lista di identificatori di persone che possono accedere in lettura al documento",
      "description": "??? Vedi onotologia...",
      "type": "array",
      "minItems": 0,
      "items": {
        "type": "string"
      }
    },
    "tenant_id": {
      "title": "Ente",
      "type": "string",
      "format": "uuid",
      "description": "Uuid del tenant",
      "examples": [
        "842b37e7-d835-49f0-92e2-a393ecda2e53"
      ]
    },
    "owner_id": {
      "title": "Proprietario",
      "description": "Uuid del proprietario del documento",
      "type": "string",
      "format": "uuid"
    },
    "document_url": {
      "title": "Url pubblico del documento",
      "type": [
        "string",
        "null"
      ],
      "format": "uri"
    },
    "created_at": {
      "title": "Data di creazione",
      "type": "string",
      "format": "date-time",
      "examples": [
        "2022-08-24T11:59:57+02:00"
      ]
    },
    "updated_at": {
      "title": "Data ultima modifica",
      "type": "string",
      "format": "date-time",
      "examples": [
        "2022-08-24T11:59:57+02:00"
      ]
    },
    "author": {
      "title": "Autore/i",
      "description": "Persone che hanno redatto il documento",
      "type": "array",
      "minItems": 0,
      "items": {
        "$ref": "#/definitions/author"
      }
    },
    "source_type": {
      "title": "Tipologia del soggetto che ha generato il documento",
      "description": "In base a questo che si identifica la transmission type",
      "type": "string",
      "enum": [
        "tenant",
        "user"
      ]
    },
    "recipient_type": {
      "title": "Tipologia di destinatario del documento",
      "description": "In base a questo che si identifica la transmission type",
      "type": "string",
      "enum": [
        "tenant",
        "user"
      ]
    },
    "last_seen": {
      "title": "Data ultima visualizzazione da parte del destinatario",
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "examples": [
        "2022-08-24T11:59:57+02:00"
      ]
    }
  },
  "required": [
    "title",
    "id",
    "event_version",
    "app_id",
    "status",
    "event_created_at",
    "event_id",
    "type",
    "short_description",
    "main_document",
    "tenant_id",
    "owner_id",
    "created_at",
    "updated_at",
    "source_type",
    "recipient_type"
  ]
}

Struttura e mapping

Ecco una tabella che rappresenta il tuo JSON Schema con le colonne Campo, Tipo, Obbligatorio e Validazione.

Campo

Tipo

Obbligatorio

Validazione

`registration_data`

Campo

Tipo

Obbligatorio

Validazione

`folder`

Campo

Tipo

Obbligatorio

Validazione

`main_document`

Campo

Tipo

Obbligatorio

Validazione

`attachments`

Campo

Tipo

Obbligatorio

Validazione

`author`

Campo

Tipo

Obbligatorio

Validazione

WorkFlow sistema di protocollazione

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.

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)

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

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

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

Use case : protocollazione totalmente fallita

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

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

Interazione Protocol Proxy<--> Piattaforma Opencity

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

{
   "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"
	}
   ],
}