REGIONE LOMBARDIA
OSSERVATORIO REGIONALE DEI CONTRATTI PUBBLICI
C ONTRATTI PUBBLICI
Acquisizione contratti in formato XML
Manuale Tecnico
Revisione del Documento: 1.7
Data revisione: 28-10-2021
Cronologia delle Revisioni
Revisione Data Descrizione
1.0 09-11-2009 Prima Emissione
1.1 01-03-2010 Aggiunta tabella con i collegamenti ad altri documenti. In questa tabella si fa riferimento all'archivio con relativa versione e data di emissione della versione contenente
1.2 11-10-2010 Adeguamento controlli per allineamento all’online
1.3 20-10-2010 Adeguamento alle specifiche 3.0.2 emesse da AVCP (Autorità per la Vigilanza sui Contratti Pubblici di Lavori, Servizi e Forniture)
1.4 20-01-2011 Adeguamento alle specifiche 3.0.2 emesse da AVCP (Autorità per la Vigilanza sui Contratti Pubblici di Lavori, Servizi e Forniture) – Introduzione gestione contratti sotto soglia esclusi e contratti quadro convenzione
1.5 24-03-2011 Aggiunto controllo su campo MOD_RIAGG_AFFID ed eliminato il controllo di obbligatorietà sul campo IMPORTO_AGGIUDICAZIONE, per Aggiudicazioni Sopra Soglia e Sotto Soglia.
1.6 16-09-2013 Aggiunte nuove categorie in CategoriaType
1.7 28-10-2021 Rimozione controlli delle singole Fasi ed Eventi (per le quali si rimanda alla documentazione ufficiale di ANAC).
Inserimento dei controlli formali effettuati sul file XML.
Allegati
Collegamenti con altri documenti
Codice Riferimento Data emissione
Descrizione
[RIF01] 28/10/2021 TrasferimentoContratti.xsd
[RIF01] 28/10/2021 TipiDati.xsd
[RIF01] 28/10/2021 FeedBackTrasferimento.xsd
IN I N DI D IC CE E G GE EN N ER E RA A LE L E
1 PREMESSA ... 1
2 PRODUZIONE DEL FILE XML ... 1
2.1 XSD SCHEMA ... 1
2.1.1 TrasferimentoContratti.xsd... 1
2.1.1.1 Elemento “InfoTrasferimento” ... 1
2.1.1.2 Elemento “Contratti” ... 2
2.1.1.3 Elemento "Responsabili" ... 2
2.1.1.4 Elemento "Aggiudicatari" ... 3
3 GESTIONE ESITO RICHIESTA ... 3
3.1 XSD SCHEMA ... 3
3.1.1 FeedBackTrasferimento.xsd ... 4
3.1.1.1 Elemento "InfoFlusso" ... 4
3.1.1.2 Elemento "Esito" ... 4
4 CONTROLLI SUL FILE XML ... 5
4.1 Caricamento del file XML ... 5
4.1.1 Dati Obbligatori ... 5
4.1.2 Utente ... 5
4.1.3 File ... 5
4.2 Job di Elaborazione ... 6
4.2.1 CIG ... 6
4.2.2 Contratto ... 6
5 ESITO DEI CONTROLLI SUL FILE XML ... 6
5.1 Esito Negativo ... 6
5.1.1 Invio Mail... 6
5.2 Esito Positivo ... 6
5.2.1 Invio Mail... 7
6 REPORT DI IMPORTAZIONE DEL FILE XML ... 7
6.1.1 Invio Mail per Esito Negativo ... 7
7 APPENDICE ... 7
7.1 Tipologica degli stati del file XML ... 7
1 PREMESSA
Il presente documento ha l’obiettivo di presentare gli aspetti tecnici della funzionalità di acquisizione contratti pubblici in formato XML messa a disposizione per gli utenti del Sistema informativo online della Direzione Generale Casa e Opere Pubbliche della Regione Lombardia che sono registrati al servizio di Gestione Contratti Pubblici Lavori, Servizi e Forniture.
Si presta ad essere usato da guida per la scrittura dei files XML rappresentanti i contratti.
2 PRODUZIONE DEL FILE XML
Per la produzione del file XML, l’utente può usare qualsiasi sistema, più o meno automatico, a sua disposizione. Condizione necessaria per la produzione del file XML è che esso rispetti l’XSD (XML Schema Definition) messo a disposizione dell’utente e compili un set minimo di informazioni considerate obbligatorie.
Senza queste due condizioni il file XML inviato viene rigettato.
2.1 XSD SCHEMA
Schema di definizione della struttura del documento XML da produrre per l’invio dei contratti all’Osservatorio Lavori Pubblici attraverso la funzionalità oggetto di spiegazione. Di seguito è visualizzata la struttura master del file "TrasferimentoContratti.xsd".
Verranno descritti quelli che sono i dati salienti per una corretta scrittura del file XML.
Per l’XSD completo, anche della definizione dei tipi di dati, si rimanda agli allegati
"TrasferimentoContratti.xsd", "TipiDati.xsd", "FeedBackTrasferimento.xsd" contenuti nell’archivio [RIF01].
2.1.1 TrasferimentoContratti.xsd
Come si può notare, il file XML che si andrà a generare a partire dall’XSD dovrà avere un elemento radice
“TrasferimentoDati” che avrà come figli gli elementi “InfoTrasferimento” e “Contratti” obbligatoriamente e
“Responsabili” e “Aggiudicatari” non necessariamente presenti.
2.1.1.1 Elemento “InfoTrasferimento”
Tale elemento conterrà informazioni circa la data in cui viene inviato il file XML e il numero di contratti contenuti. Queste informazioni sono attributi dell’elemento InfoTrasferimento.
Essi sono:
2.1.1.2 Elemento “Contratti”
L’elemento “Contratti” è un elemento obbligatorio è può essere ripetuto tante volte quante sono il numero di contratti che si vuole inviare. Esso contiene il contratto che si vuole inviare ed è composto dai seguenti elementi:
• CODICE_UNICO_INTERVENTO: elemento opzionale, sarà nullo la prima volta che si invia la scheda di aggiudicazione. Sarà avvalorato tutte le volte successive che si inviano schede relative al contratto precedentemente inviato
• CIG: elemento obbligatorio che indica il Codice identificativo di gara.
• TIPO_CONTRATTO: elemento obbligatorio che indica il tipo di contratto con cui si ha a che fare (Lavori, Servizi, Forniture)
• TIPO_FLUSSO: elemento obbligatorio che indica la tipologia di flusso a cui il contratto deve appartenere. Può assumere tre valori: 1 (Contratti Esclusi), 2 (Sotto Soglia, <= 150.000 Euro) e 3 (Sopra Soglia, > 150.000 Euro).
• MISTO: elemento opzionale. Indica se si ha a che fare con un contratto misto oppure no.
• CODICE_SETTORE: elemento obbligatorio. Indica se il contratto appartiene ai settori ordinari o speciali.
• SCHEDE: elemento contenente le schede del contratto. Esso conterrà la scheda specifica oggetto di invio del contratto.
Per la composizione e definizione delle singole schede si rimanda alla documentazione ufficiale di ANAC.
• username: elemento obbligatorio che identifica l’utente che invia il contratto. Tale elemento va compilato con la stessa username usata sul sistema online di acquisizione contratti.
2.1.1.3 Elemento "Responsabili"
Elemento opzionale presente solo se nell’invio del contratto ci sono informazioni circa professionisti responsabili di qualche attività. Esso conterrà zero o più elementi “Responsabile” con l’anagrafica del professionista a cui si è fatto riferimento nella scheda del contratto inviato. Nello specifico tale elemento sarà avvalorato nell’invio della fase di aggiudicazione con i dati del responsabile unico del procedimento e di altri eventuali professionisti coinvolti. Nell’invio della fase di inizio di un contratto con i dati dei professionisti responsabili di tale fase. Nell’invio della fase di collaudo di un contratto con i dati dei professionisti coinvolti
nel collaudo dell’opera. Nell’invio delle altre schede del contratto l’elemento “Responsabili” non sarà avvalorato.
2.1.1.4 Elemento "Aggiudicatari"
Elemento opzionale presente solo se nell’invio del contratto ci sono informazioni circa imprese che si sono aggiudicate dei lavori. Esso conterrà zero o più elementi “Aggiudicatario” con l’anagrafica dell’impresa a cui si è fatto riferimento nella scheda del contratto inviato. Nello specifico tale elemento sarà avvalorato nell’invio della fase di aggiudicazione e della fase di inizio del contratto con i dati delle imprese aggiudicatarie.
Nell’invio delle altre schede del contratto l’elemento “Aggiudicatari” non sarà avvalorato.
3 GESTIONE ESITO RICHIESTA
Anche l’esito di una richiesta sarà in formato XML e avrà la struttura così come definita nell’XSD allegato FeedBackTrasferimento.xsd. Nell’esito della richiesta sarà presente l’identificativo del contratto (CODICE_UNICO_INTERVENTO) che il sistema di acquisizione contratti in formato XML produce alla prima trasmissione e che dovrà essere indicato "manualmente" nei sistemi proprietari per le trasmissioni delle successive schede (fasi/eventi) relative allo stesso contratto.
3.1 XSD SCHEMA
Di seguito è visualizzata la struttura master di un esito di una richiesta. Verranno descritti quelli che sono i dati salienti per una corretta interpretazione del file XML.
Per l’XSD completo, anche della definizione dei tipi di dati, si rimanda agli allegati
"TrasferimentoContratti.xsd", "TipiDati.xsd", "FeedBackTrasferimento.xsd".
3.1.1 FeedBackTrasferimento.xsd
Come si può notare in figura il file XML che si produrrà in seguito ad una richiesta di acquisizione di un contratto in formato XML avrà un elemento radice “FeedBack” che avrà come figli gli elementi “InfoFlusso” e
“Esito”.
3.1.1.1 Elemento "InfoFlusso"
Tale elemento conterrà informazioni circa la data in cui viene elaborato il file XML, il numero di contratti elaborati, il numero di errori, il numero di warning e il numero di contratti caricati.
Queste informazioni sono attributi dell’elemento InfoFlusso.
Essi sono:
• DATA_ELABORAZIONE
• NUM_ELABORATI
• NUM_ERRORE
• NUM_WARNING
• NUM_CARICATI
3.1.1.2 Elemento "Esito"
L’elemento “Esito” è un elemento che può essere ripetuto tante volte quante sono il numero di contratti che sono stati eleborati. Esso è costituito dai seguenti attributi ed eventualmente dall’elemeto “Anomalia” se sono state riscontrate delle anomalie durante l’elaborazione del file XML.
• CIG: codice identificativo di gara del contratto inviato in formato XML
• CODICE_UNICO_INTERVENTO: codice unico intervento del contratto inviato in formato XML
• SCHEDA: nome della scheda caricata
• PROGRESSIVO: eventuale progressivo della scheda caricata
• CARICATO: valore booleano (si/no).
4 CONTROLLI SUL FILE XML
Affinché il file XML inviato non venga rigettato dal sistema di acquisizione, oltre che rispettare la struttura così come definita nell'XSD, deve superare anche i controlli seguenti.
4.1 Caricamento del file XML
Al momento della chiamata del servizio di caricamento del file XML verranno effettuati i seguenti controlli.
Se verranno soddisfatti il file sarà caricato nel sistema.
4.1.1 Dati Obbligatori
Bisognerà inserire obbligatoriamente tutti i seguenti attributi:
- "fileUpload", percorso del file XML da caricare;
- "idente", id dell'Ente dell'utente;
- "mailUtente", indirizzo e-mail dell'utente;
- "nomeFile", nome da assegnare al file XML da caricare;
- "x-springline-fiscalcode", codice fiscale dell'utente;
4.1.2 Utente
L'utente che carica il file XML per l'importazione deve essere presente nell'anagrafica del sistema.
Sia il Codice Fiscale che l'id dell'Ente forniti devono corrispondere ad un utente già esistente, altrimenti verrà rilasciato un erorre per "Utente non autorizzato";
4.1.3 File
Il file che si cerca di caricare deve:
- avere l'estensione "xml";
- non superare le dimensioni massime di 100Kb;
- deve rispettare i canoni di un file XML ben formato (sintassi e logica);
4.2 Job di Elaborazione
Il job che si occupa di elaborare i file XML caricati nel sistema effettuerà i seguenti controlli dei dati presenti nell'XSD.
4.2.1 CIG
Del CIG verranno controllati sia il formato, sia il fatto che risulti libero e non già impegnato (in base al relativo CUI).
4.2.2 Contratto
In base al CUI fornito nell'XML viene rilevato il Contratto di riferimento già presente nel sistema e vengono effettuati i seguenti controlli:
- il Contratto deve esistere all'interno del sistema;
- il CIG contenuto nell'XML deve essere uguale a quello del Contratto di sistema;
- Il TipoFlusso deve essere uguale a quello del Contratto di sistema;
- Il TipoContratto deve essere uguale a quello del Contratto di sistema;
5 ESITO DEI CONTROLLI SUL FILE XML
Fin dal momento del caricamento del file XML verranno assegnati degli stati al record che lo contiene, in modo da poter identificare la situazione in cui si trova lo stesso, ed anche al termine dei controlli verrà assegnato lo stato relativo.
La relativa tabella di decodifica è visibile nel capitolo "" dell'"Appendice".
5.1 Esito Negativo
Se i controlli sul file XML trovano qualche tipo di errore, gli viene assegnato uno degli stati seguenti:
- 1 Rilevati errori sintattici nel file XML;
- 2 Rilevati errori logici nel file XML;
- 3 Errore durante Inserimento;
- 6 Eccezione generica;
5.1.1
Invio Mail
Dato che una Scheda o un Evento potrebbero essere stati bloccati rispetto ad un operazione di update, e che in tal caso deve essere richiesto anticipatamente uno sblocco, è stato previsto di inviare una mail all'utente (con nell'oggetto il nome e l'id assegnato al file XML) nella quale viene segnalato che l'aggiornamento non è andato a buon fine e che deve essere richiesta un'azione di sblocco dell'update sul soggetto da modificare.
5.2 Esito Positivo
Se tutti i controlli sul file XML sono positivi ed il file viene correttamente importato nel sistema, oltre all'asegnamento dello stato "0" (cioè "Inserimento Dati da XML Effettuato con Successo") viene anche inviata una mail.
5.2.1
Invio Mail
La mail viene inviata all'utente che ha effettuato il caricamento del file XML e contiene, nell'oggetto, Il nome e l'ID assegnato al file, e nel testo la dichiarazione di richiesta evasa con successo.
6 REPORT DI IMPORTAZIONE DEL FILE XML
Per ogni tentativo di importazione di un file XML verrà generato un report composto: o dalla segnalazione di esito positivo, o dall'elenco degli eventuali errori presenti nell'XML che non ne hanno permesso l'importazione.
Nel secondo caso verrà inviata una mail all'assistenza per segnalare gli eventuali problemi riscontrati.
6.1.1
Invio Mail per Esito Negativo
In caso di esito negativo verrò inviata una mail all'assistenza per segnalare gli errori registrati durante il processo di importazione dell'XML.
7 APPENDICE
7.1 Tipologica degli stati del file XML
Nella tabella seguente sono descritti gli stati in cui si può trovare un file XML che è stato caricato per l'importazione.
