Documentazione della procedura di Importazione di file esterni

Documentazione della procedura di Importazione di file esterni.
Documentazione della procedura di Importazione di file esterni. _________________________ 1
Impostazione della tipologia e della locazione del Database e configurazione dell’ambiente di
esecuzione __________________________________________________________________________ 3
1.
2.
3.
Installazione monoutente ________________________________________________________________ 3
Installazione multi-utente non concorrente __________________________________________________ 4
Installazione server ____________________________________________________________________ 4
Importazione o Diagnostico File XBRL da riga di comando: ________________________________ 5
Formato data “-fd” _________________________________________________________________________
Blocco Importazione al verificarsi del primo errore “-be” ___________________________________________
Blocco Importazione al verificarsi del primo warning “-bw” _________________________________________
Cancella segnalazioni preesistenti “-cs” _________________________________________________________
Sovrascrivi contesti duplicati “-sc” _____________________________________________________________
Importa (eventualmente sovra scrivi) anagrafica segnalante “-is” _____________________________________
Importa (eventualmente sovra scrivi) anagrafica referente “-ir” _______________________________________
Importa identificativi partecipazione in rubrica “-ii” _______________________________________________
Solo diagnostico “-sd”_______________________________________________________________________
Path locale per il log “-pl” ____________________________________________________________________
6
6
6
6
6
6
7
7
7
7
Importazione File XML da riga di comando: _____________________________________________ 8
Formato data “-fd” _________________________________________________________________________ 9
Blocco Importazione al verificarsi del primo errore “-be” __________________________________________ 10
Blocco Importazione al verificarsi del primo warning “-bw” ________________________________________ 10
Cancella segnalazioni preesistenti “-cs” ________________________________________________________ 10
Sovrascrivi contesti duplicati “-sc” ____________________________________________________________ 10
Importa (eventualmente sovra scrivi) anagrafica segnalante “-is” ____________________________________ 10
Importa (eventualmente sovra scrivi) anagrafica referente “-ir” ______________________________________ 10
Importa identificativi partecipazione in rubrica “-ii” ______________________________________________ 11
Path locale per il log “-pl” ___________________________________________________________________ 11
Importazione File CSV da riga di comando: _____________________________________________ 11
Formato data “-fd” ________________________________________________________________________
Blocco Importazione al verificarsi del primo errore “-be” __________________________________________
Blocco Importazione al verificarsi del primo warning “-bw” ________________________________________
Cancella segnalazioni preesistenti “-cs” ________________________________________________________
Sovrascrivi contesti duplicati “-sc” ____________________________________________________________
Importa (eventualmente sovra scrivi) anagrafica segnalante “-is” ____________________________________
Importa (eventualmente sovra scrivi) anagrafica referente “-ir” ______________________________________
Importa identificativi partecipazione in rubrica “-ii” ______________________________________________
Separatore di campo “-se” ___________________________________________________________________
Path locale per il log “-pl” ___________________________________________________________________
12
13
13
13
13
13
13
13
14
14
Diagnosi ed invio di un file XBRL al sito BDI da riga di comando: __________________________ 15
Utilizzo delle API di importazione da codice Java ________________________________________ 15
Configurazione dell’ambiente Dati ____________________________________________________________
Interfaccia ImportMonitor ___________________________________________________________________
Utilizzo classe ImportXml __________________________________________________________________
Utilizzo classe ImportXbrl __________________________________________________________________
Utilizzo classe ImportCvs ___________________________________________________________________
Utilizzo classe ImportXbrl (per diagnostico) ____________________________________________________
Codice classe ImportXml DiagnosticaTrasmettiXbrl2SitoBDI ______________________________________
15
16
16
17
18
19
19
Questo documento descrive l’utilizzo delle API del PSDR per l’esecuzione delle seguenti funzioni:
 importazione dei file XBRL, XML, CSV prodotti esternamente, all’interno del database del
PSDR (DIRDEDB);
 diagnostica con i relativi controlli dei soli file XBRL;
 inoltro dei questionari compilati all’ambiente di raccolta dati della Banca d’Italia.
Le librerie coinvolte in questi processi sono le seguenti:
1. Config.jar (Libreria per il settaggio e la conservazione dei parametri di configurazione
dell’applicazione, dalla tipologia di accesso al DB ai parametri di connessione e
autenticazione con il sito BDI);
2. Controlli.jar (Libreria contenete i controlli specifici dei sei questionari relativi alle sei
rilevazioni attese dalla Banca);
3. Schemi.jar (Libreria contenete gli schemi xbrl/xml dei sei questionari relativi alle sei
rilevazioni attese dalla Banca);
4. DataDB.jar (Libreria contenete le Api per la gestione del DataBase JavaDB, nel quale
vengono registrati i dati relativi alle segnalazioni e in generale tutti i dati utili
all’applicazione);
5. Importazioni.jar (Libreria per la gestione delle Importazioni delle tre tipologie di file
stabilite XBRL, XML, CSV all’interno del Database locale);
6. Messages.jar (Libreria contenente la messaggistica)
L’applicazione si avvale anche di due database readonly utilizzati per i controlli di congruenza dei
valori importati, incapsulati in altrettanti jar che sono:
7. domini.jar (Libreria contenete il database dei Domini)
8. isin.jar (Libreria contenete il database dell’Anagrafe Titoli)
L’applicazione comunque si avvale di una serie di altre librerie di cui una parte saranno fornite dalla
Banca: librerie utilizzate per la diagnostica dei files XBRL,
1. xbrlBase.jar ();
2. xbrlJaxpExt.jar ();
3. xbrlTest.jar ();
e una seconda parte è stata fornita da Librerie freeware di cui si allega diagramma con le varie
tipologie di licenza:
4. derby.jar (ASL 2.0 ); (Libreria driver per l’accesso al database JavaDb in modalità
dedicata)
5. derbyclient.jar (ASL 2.0) (Libreria driver per l’accesso al database JavaDb in modalità
client-server)
6. derbynet.jar (ASL 2.0)
7. derbytools.jar (ASL 2.0) (Libreria, opzionale, contenete delle funzionalità aggiuntive del
Database, ad esempio per uso da console)
8. log4j-1.2.4.jar (ASL 2.0) (Libreria per la gestione del log applicativo)
Per un totale di 16 librerie, qui sotto riportate con le loro dipendenze:
Nella libreria Importazioni.jar esistono tre classi dalle quali sarà possibile invocare i metodi di
importazione, sia da una applicazione esterna, sia da riga di comando, come qui di seguito riportato.
 it/uic/dirde/importazioni/ImportXbrl
 it/uic/dirde/importazioni/ImportXml
 it/uic/dirde/importazioni/ImportCsv
Impostazione della tipologia e della locazione del Database e
configurazione dell’ambiente di esecuzione
Il primo passo da fare per la definizione dell’ambiente fruito dalle librerie, è la configurazione del
Database, ossia decidere la tipologia di connessione e il percorso dello stesso.
Le tipologie di utilizzo del Database sono tre come da documentazione:
1. Installazione monoutente (database embedded). Si tratta di una modalità di
installazione completamente automatica.
Tramite un link attivabile dal sito della Banca d’Italia, l’utente effettua il download
dell’applicazione.
Ogni volta che si entra nell’applicazione, in presenza di connessione ad Internet, vengono
aggiornate tavole di dominio e software.
E’ richiesto l’inserimento delle credenziali (username e password) dell’ambiente di raccolta
dati per poter eseguire gli aggiornamenti dei dati specifici dei segnalanti e la trasmissione
delle segnalazioni. Tali credenziali sono immagazzinate, criptate, in un file residente
nell’ambiente utente (USER HOME).
Il database destinato all’immagazzinamento dei dati delle segnalazioni è posto
automaticamente nell’ambiente utente (USER HOME).
E’ impedito automaticamente un utilizzo concorrente del database (con esplicito lock del
database).
2. Installazione multi-utente non concorrente (database embedded). Si tratta di una
modalità di installazione completamente automatica.
Tramite un link attivabile dal sito della Banca d’Italia, il primo utente effettua il download
dell’applicazione. Il database destinato all’immagazzinamento dei dati delle segnalazioni
viene installato in una directory, anche di rete, scelta da lui. Altri utenti potranno scaricare,
installare ed utilizzare l’applicazione referenziando lo stesso database.
Ogni volta che un utente avvia l’applicazione, in presenza di connessione ad Internet,
vengono aggiornate le tavole di dominio ed il software del suo ambiente di lavoro.
Ciascun utente può inserire le proprie credenziali (username e password) relative
all’ambiente di raccolta dati per poter eseguire gli aggiornamenti dei dati specifici dei
segnalanti e/o la trasmissione delle segnalazioni. Non è necessario che tutti gli utenti
dispongano di credenziali relative alla raccolta dati. Infatti gli aggiornamenti dei dati
specifici dei segnalanti effettuati da un utente sono disponibili anche agli altri che
condividono la base dati. E’ invece necessario che ogni utente che voglia effettuare l’inoltro
delle segnalazioni alla Banca d’Italia inserisca le suddette credenziali.
E’ impedito automaticamente un utilizzo concorrente del database (con esplicito lock del
database).
3. Installazione server (database in modalità client-server). Si tratta di una modalità di
installazione quasi completamente automatica.
Tramite un link attivabile dal sito della Banca d’Italia, il primo utente effettua il download
dell’applicazione. Il database destinato all’immagazzinamento dei dati delle segnalazioni
viene installato in una directory, scelta dall’utente sulla macchina che fungerà da db server.
Altri utenti potranno scaricare, installare ed utilizzare l’applicazione condividendo lo stesso
database destinato all’immagazzinamento dei dati delle segnalazioni.
A differenza dell’installazione 2, è necessario avviare, nella macchina che funge da db
server, il processo software che gestisce il database. L’avvio sarà effettuato tramite una
utility (shell script) fornita e documentata dalla Banca.
Per quanto riguarda gli aggiornamenti delle tavole di dominio e del software, nonché per ciò
che riguarda l’interazione con l’ambiente di raccolta dati, vale quanto descritto
nell’installazione 2.
In questa modalità di lavoro è consentito l’uso concorrente del prodotto da parte di più
utenti.
L'ambiente run time delle API prevede la disponibilità del database del PSDR e del file di
configurazione, config.dat, in cui è definita la tipologia e la locazione del Database. Tale file deve
essere presente nella directory %USER_HOME%/Bdi dell'utente che esegue l'API. Quindi
qualora tale utente sia diverso da quello che ha eseguito l'installazione, lo si dovrà copiare nella
relativa directory.
In alternativa il file config.dat potrà essere creato eseguendo da riga di comando il metodo main()
della classe Configurazione, seguendone le istruzioni.
Esempio:
java –classpath [inserendo tutti i percorsi dove trovare le librerie sopra indicate]
it/uic/dirde/config/Configurazione
quindi seguire le indicazioni fornite.
Importazione o Diagnostico File XBRL da riga di comando:
Per una prima visualizzazione dei parametri e delle opzioni che si possono passare alla classe main,
potrà visualizzare l’Help attraverso l’opzione “-h”:
Ossia dopo aver dato il comando di esecuzione java –classpath [inserendo tutti i percorsi
dove trovare le librerie sopra indicate] it/uic/dirde/importazioni/ImportXbrl,
digitare il parametro “-h” (Help), si visualizzerà il seguente output:
Quindi per far eseguire una importazione da riga di comando è necessario inserire almeno i primi
quattro parametri nella corretta successione, ossia:
1. Il Codice Segnalante (Numerico di 6 caratteri);
2. Il Codice della Rilevazione (Stringa da 3 caratteri: OMF, OTF, EMF, TTN, CAF, SAC);
3. La Data di Riferimento ([dd/MM/yyyy], comunque successiva al 31/12/2007);
4. Il percorso del file da importare (Stringa);
quindi:
java -classpath ./*;./domini/*;./lib/*;./Helplib/*;
it/uic/dirde/importazioni/ImportXbrl 583559 OMF 31/01-2008 "C:\
XBRL-BDI\istanza_OMF_R5.xml"
ai quattro parametri iniziali è possibile aggiungere una serie di opzioni che caratterizzano
l’importazione e sono le seguenti:
-fd:
-be:
Formato data
Blocca importazione primo errore
- default: ‘dd/MM/yyyy’;
- default: S
-bw:
-cs
-sc
-is
-ir
-ii
-sl
-pl
Blocca importazione primo warning
- default: N
Cancella segnalazioni preesistenti
- default: N
Sovra scrivi contesti duplicati
- default: N
Importa anagrafica segnalante
- default: N
Importa anagrafica referente
- default: N
Importa identificativi partecipazione in rubrica
- default: N
Solo diagnostico
- default: N
Path locale per il log -default: %USER_HOME%/Bdi/Log Importazione/
Formato data “-fd”
Utilizzato qualora si abbia la necessità di passare la data di riferimento in un formato diverso da
quello di default (‘dd/MM/yyyy’), ovvero yyyyMMdd, yyyy-MM-dd, dd-MM-yyyy ecc.
Blocco Importazione al verificarsi del primo errore “-be”
Con questa opzione sarà possibile scegliere se bloccare l’importazione al verificarsi di un errore,
oppure continuare l’importazione, inserendo comunque le segnalazioni con errori, ma associando
loro lo stato ad ERR anziché a OK.
Blocco Importazione al verificarsi del primo warning “-bw”
Con questa opzione sarà possibile scegliere se bloccare l’importazione al verificarsi di un warning,
oppure continuare l’importazione, inserendo comunque le segnalazioni con warning, ma associando
loro lo stato ad WAR anziché a OK.
Cancella segnalazioni preesistenti “-cs”
Con questa opzione sarà possibile cancellare preventivamente tutte le eventuali segnalazioni
presenti per l’istanza attiva1 di quella terna (segnalante, rilevazione, data riferimento).
Sovrascrivi contesti duplicati “-sc”
Il alternativa all’opzione precedente, può essere utilizzata questa, che consente di sovra-scrivere le
segnalazioni che hanno le variabili di contesto (vedi schemi matriciali di BDI) identico. Se viene
data l’opzione “S”, le eventuali segnalazioni che hanno variabili di contesto duplicate presenti nel
DB, saranno aggiornate con quelle presenti nel file XBRL, altrimenti se viene data l’opzione “N”, le
segnalazioni presenti sul file XBRL che trovano una segnalazione con identico contesto, verranno
scartate durante l’importazione.
Importa (eventualmente sovra scrivi) anagrafica segnalante “-is”
Attraverso questa opzione saranno importate le segnalazioni relative al segnalante, ossia le:
 32#010000000001;
 32#010000000002;
 32#010000000003;
Istanza Attiva: è l’istanza più recente di un questionario, relativamente alla terna segnalante, rilevazione, data
riferimento. Qualora l’ultima istanza di un questionario si trovi in uno stato finale, ne verrà creata una nuova
relativamente all’importazione in corso.
1
 32#010000000004;
 32#010000000005;
si noti che i segnalanti non vengono aggiornati solamente nei questionari, bensì poiché hanno un
trattamento centralizzato, tali modifiche avranno riscontri in tutti quei questionari prodotti per quel
segnalante.
Importa (eventualmente sovra scrivi) anagrafica referente “-ir”
Attraverso questa opzione saranno importate le segnalazioni relative al segnalante, ossia le:
 32#010000000006;
Importa identificativi partecipazione in rubrica “-ii”
Attraverso questa opzione sarà possibile importare, esclusivamente per i questionari che hanno
questa prerogativa: (quelli relativi alle rilevazioni CAF, SAC, EMF), importare i dati relativi agli
identificativi di partecipazione, anche in una rubrica interna, utilizzabile successivamente per la
compilazione di successivi questionari che referenziassero gli stessi identificativi.
Solo diagnostico “-sd”
Attraverso questa opzione sarà possibile eseguire solamente i:
 controlli di struttura del file XBRL
 controlli di presenza variabili obbligatorie
 controlli di contesto duplicato
 controlli di appartenenza ai domini
 controlli relativi alle singole variabili di ogni segnalazione
 controlli globali trans-segnalazione;
senza però inserire nulla nel Database DIRDEDB che non subirà cambiamenti.
Path locale per il log “-pl”
L’applicazione scrive un log in formato html in una cartella di default: %USER_HOME%/Bdi/Log
Importazione/ , qualora si volesse reindirizzare la scrittura del log in una diversa locazione si dovrà
utilizzare questa opzione scrivendo il relativo percorso.
Esempio di invocazione da riga di comando:
Il log relativo ad una importazione avrà una struttura del tipo quella riportata qui sotto:
Inizio Importazione
(commento). Controllo di corrispondenza del Segnalante contenuto nel file con quello relativo all'invio selezionato.
(commento). Cancellazione preventiva di tutte le segnalazioni dell'invio corrente: ESEGUITA!
(Segnalazione Importata). 326000000013410 Segnalazione Corretta
(Segnalazione Importata). 326000000013430 Segnalazione Corretta
(Segnalazione Importata). 326000000013430 Segnalazione Corretta
(Segnalazione Importata). 326000000013440 Segnalazione Corretta
(Segnalazione Importata). 326000000013530 Segnalazione Corretta
(Segnalazione Importata). 326000000023410 Segnalazione Corretta
(Segnalazione Importata). 326000000023420 Segnalazione Corretta
(Segnalazione Importata). 326000000023440 <V01067=ZZZ>: Variabile non in dominio!
(Segnalazione Importata). 326000000023520 Segnalazione Corretta
(Segnalazione Importata). 326000000044620 Segnalazione Corretta
(commento). I rimanenti controlli hanno dato esito positivo
Fine Importazione
Mentre il log relativo al solo diagnostico avrà una struttura tipo:
Inizio Controlli
Controllo di corrispondenza del Segnalante contenuto nel file con quello relativo all'invio selezionato.
322010000000001 Segnalazione Anagrafica Segnalante In Elaborazione
322010000000002 Segnalazione Anagrafica Segnalante In Elaborazione
322010000000004 Segnalazione Anagrafica Segnalante In Elaborazione
322010000000005 Segnalazione Anagrafica Segnalante In Elaborazione
Complesso Segnalazioni Anagrafica Segnalante, Corretto!
322010000000006 Segnalazione Referente Corretta.
322000000010020 La segnalazione è stata aggiornata con i dati presenti in rubrica identificativi partecipazione. (id.
=123456)
322000000010020 <V00032>:
EMF2A: Attenzione ! Titolo non presente nella base dati attualmente in linea. Se si è certi della correttezza
confermare e chiedere codifica del codice isin alla Banca d'Italia
Controlli globali passati con esito positivo!
Controlli Terminati.
Importazione File XML da riga di comando:
Molto simile alla struttura precedente è quella per l’importazione dei file di tipologia XML.
Per una prima visualizzazione dei parametri e delle opzioni che si possono passare alla classe main,
potrà visualizzare l’Help attraverso l’opzione “-h”:
Ossia dopo aver dato il comando di esecuzione java –classpath [inserendo tutti i percorsi
dove trovare le librerie sopra indicate] it/uic/dirde/importazioni/ImportXml,
digitare il parametro “-h” (Help), si visualizzerà il seguente output:
Quindi per far eseguire una importazione da riga di comando è necessario inserire almeno i primi
quattro parametri nella corretta successione, ossia:
5. Il Codice Segnalante (Numerico di 6 caratteri);
6. Il Codice della Rilevazione (Stringa da 3 caratteri: OMF, OTF, EMF, TTN, CAF, SAC);
7. La Data di Riferimento ([dd/MM/yyyy], comunque successiva al 31/12/2007);
8. Il percorso del file da importare (Stringa);
quindi:
java -classpath ./*;./domini/*;./lib/*;./Helplib/*;
it/uic/dirde/importazioni/ImportXbrl 583559 OMF 31/01-2008 "C:\
XBRL-BDI\istanza_OMF_R5.xml"
ai quattro parametri iniziali è possibile aggiungere una serie di opzioni che caratterizzano
l’importazione e sono le seguenti:
-fd:
-be:
-bw:
-cs
-sc
-is
-ir
-ii
-pl
Formato data
- default: ‘dd/MM/yyyy’;
Blocca importazione primo errore
- default: S
Blocca importazione primo warning
- default: N
Cancella segnalazioni preesistenti
- default: N
Sovra scrivi contesti duplicati
- default: N
Importa anagrafica segnalante
- default: N
Importa anagrafica referente
- default: N
Importa identificativi partecipazione in rubrica
- default: N
Path locale per il log -default: %USER_HOME%/Bdi/Log Importazione/
Formato data “-fd”
Utilizzato qualora si abbia la necessità di passare la data di riferimento in un formato diverso da
quello di default (‘dd/MM/yyyy’), ovvero yyyyMMdd, yyyy-MM-dd, dd-MM-yyyy ecc.
Blocco Importazione al verificarsi del primo errore “-be”
Con questa opzione sarà possibile scegliere se bloccare l’importazione al verificarsi di un errore,
oppure continuare l’importazione, inserendo comunque le segnalazioni con errori, ma associando
loro lo stato ad ERR anziché a OK.
Blocco Importazione al verificarsi del primo warning “-bw”
Con questa opzione sarà possibile scegliere se bloccare l’importazione al verificarsi di un warning,
oppure continuare l’importazione, inserendo comunque le segnalazioni con warning, ma associando
loro lo stato ad WAR anziché a OK.
Cancella segnalazioni preesistenti “-cs”
Con questa opzione sarà possibile cancellare preventivamente tutte le eventuali segnalazioni
presenti per l’istanza attiva2 di quella terna (segnalante, rilevazione, data riferimento).
Sovrascrivi contesti duplicati “-sc”
Il alternativa all’opzione precedente, può essere utilizzata questa, che consente di sovra-scrivere le
segnalazioni che hanno le variabili di contesto (vedi schemi matriciali di BDI) identico. Se viene
data l’opzione “S”, le eventuali segnalazioni che hanno variabili di contesto duplicate presenti nel
DB, saranno aggiornate con quelle presenti nel file XBRL, altrimenti se viene data l’opzione “N”, le
segnalazioni presenti sul file XBRL che trovano una segnalazione con identico contesto, verranno
scartate durante l’importazione.
Importa (eventualmente sovra scrivi) anagrafica segnalante “-is”
Attraverso questa opzione saranno importate le segnalazioni relative al segnalante, ossia le:
 32#010000000001;
 32#010000000002;
 32#010000000003;
 32#010000000004;
 32#010000000005;
si noti che i segnalanti non vengono aggiornati solamente nei questionari, bensì poiché hanno un
trattamento centralizzato, tali modifiche avranno riscontri in tutti quei questionari prodotti per quel
segnalante.
Importa (eventualmente sovra scrivi) anagrafica referente “-ir”
Attraverso questa opzione saranno importate le segnalazioni relative al segnalante, ossia le:
 32#010000000006;
Istanza Attiva: è l’istanza più recente di un questionario, relativamente alla terna segnalante, rilevazione, data
riferimento. Qualora l’ultima istanza di un questionario si trovi in uno stato finale, ne verrà creata una nuova
relativamente all’importazione in corso.
2
Importa identificativi partecipazione in rubrica “-ii”
Attraverso questa opzione sarà possibile importare, esclusivamente per i questionari che hanno
questa prerogativa: (quelli relativi alle rilevazioni CAF, SAC, EMF), importare i dati relativi agli
identificativi di partecipazione, anche in una rubrica interna, utilizzabile successivamente per la
compilazione di successivi questionari che referenziassero gli stessi identificativi.
Path locale per il log “-pl”
L’applicazione scrive un log in formato html in una cartella di default: %USER_HOME%/Bdi/Log
Importazione/ , qualora si volesse reindirizzare la scrittura del log in una diversa locazione si dovrà
utilizzare questa opzione scrivendo il relativo percorso.
Esempio di invocazione da riga di comando:
Il log relativo ad una importazione avrà una struttura del tipo quella riportata qui sotto:
Inizio Importazione
(commento). Controllo di corrispondenza del Segnalante contenuto nel file con quello relativo all'invio selezionato.
(Segnalazione Importata). 326000000013410 Segnalazione Corretta
(Segnalazione Importata). 326000000013430 Segnalazione Corretta
(Segnalazione Importata). 326000000013430 Segnalazione Corretta
(Segnalazione Importata). 326000000013440 Segnalazione Corretta
(Segnalazione Importata). 326000000013530 <V00032=XS0123456789>: Variabile non in dominio!
(Non Importata).326000000023410 Contesto Duplicato:
non è ammessa più di una segnalazione 326000000023410
(Segnalazione Importata). 326000000023420 Segnalazione Corretta
(Segnalazione Importata). 326000000023440 Segnalazione Corretta
(Non Importata).326000000023440 <V00995,V01067,V01068> Contesto Duplicato:
le variabili non possono assumere gli stessi valori per più segnalazioni 326000000023440
(Segnalazione Importata). 326000000023520 Segnalazione Corretta
(Segnalazione Importata). 326000000044620 Segnalazione Corretta
(commento). I rimanenti controlli hanno dato esito positivo
Fine Importazione
Importazione File CSV da riga di comando:
Per una prima visualizzazione dei parametri e delle opzioni che si possono passare alla classe main,
potrà visualizzare l’Help attraverso l’opzione “-h”:
Ossia dopo aver dato il comando di esecuzione java –classpath [inserendo tutti i percorsi
dove trovare le librerie sopra indicate] it/uic/dirde/importazioni/ImportCsv,
digitare il parametro “-h” (Help), si visualizzerà il seguente output:
Quindi per far eseguire una importazione da riga di comando è necessario inserire almeno i primi
quattro parametri nella corretta successione, ossia:
9. Il Codice Segnalante (Numerico di 6 caratteri);
10. Il Codice della Rilevazione (Stringa da 3 caratteri: OMF, OTF, EMF, TTN, CAF, SAC);
11. La Data di Riferimento ([dd/MM/yyyy], comunque successiva al 31/12/2007);
12. Il percorso del file da importare (Stringa);
quindi:
java -classpath ./*;./domini/*;./lib/*;./Helplib/*;
it/uic/dirde/importazioni/ImportXbrl 583559 OMF 31/01-2008 "C:\
XBRL-BDI\istanza_OMF_R5.xml"
ai quattro parametri iniziali è possibile aggiungere una serie di opzioni che caratterizzano
l’importazione e sono le seguenti:
-fd:
-be:
-bw:
-cs
-sc
-is
-ir
-ii
-se
-pl
Formato data
- default: ‘dd/MM/yyyy’;
Blocca importazione primo errore
- default: S
Blocca importazione primo warning
- default: N
Cancella segnalazioni preesistenti
- default: N
Sovra scrivi contesti duplicati
- default: N
Importa anagrafica segnalante
- default: N
Importa anagrafica referente
- default: N
Importa identificativi partecipazione in rubrica
- default: N
Separatore
- default: “;”
Path locale per il log -default: %USER_HOME%/Bdi/Log Importazione/
Formato data “-fd”
Utilizzato qualora si abbia la necessità di passare la data di riferimento in un formato diverso da
quello di default (‘dd/MM/yyyy’), ovvero yyyyMMdd, yyyy-MM-dd, dd-MM-yyyy ecc.
Blocco Importazione al verificarsi del primo errore “-be”
Con questa opzione sarà possibile scegliere se bloccare l’importazione al verificarsi di un errore,
oppure continuare l’importazione, inserendo comunque le segnalazioni con errori, ma associando
loro lo stato ad ERR anziché a OK.
Blocco Importazione al verificarsi del primo warning “-bw”
Con questa opzione sarà possibile scegliere se bloccare l’importazione al verificarsi di un warning,
oppure continuare l’importazione, inserendo comunque le segnalazioni con warning, ma associando
loro lo stato ad WAR anziché a OK.
Cancella segnalazioni preesistenti “-cs”
Con questa opzione sarà possibile cancellare preventivamente tutte le eventuali segnalazioni
presenti per l’istanza attiva3 di quella terna (segnalante, rilevazione, data riferimento).
Sovrascrivi contesti duplicati “-sc”
Il alternativa all’opzione precedente, può essere utilizzata questa, che consente di sovra-scrivere le
segnalazioni che hanno le variabili di contesto (vedi schemi matriciali di BDI) identico. Se viene
data l’opzione “S”, le eventuali segnalazioni che hanno variabili di contesto duplicate presenti nel
DB, saranno aggiornate con quelle presenti nel file XBRL, altrimenti se viene data l’opzione “N”, le
segnalazioni presenti sul file XBRL che trovano una segnalazione con identico contesto, verranno
scartate durante l’importazione.
Importa (eventualmente sovra scrivi) anagrafica segnalante “-is”
Attraverso questa opzione saranno importate le segnalazioni relative al segnalante, ossia le:
 32#010000000001;
 32#010000000002;
 32#010000000003;
 32#010000000004;
 32#010000000005;
si noti che i segnalanti non vengono aggiornati solamente nei questionari, bensì poiché hanno un
trattamento centralizzato, tali modifiche avranno riscontri in tutti quei questionari prodotti per quel
segnalante.
Importa (eventualmente sovra scrivi) anagrafica referente “-ir”
Attraverso questa opzione saranno importate le segnalazioni relative al segnalante, ossia le:
 32#010000000006;
Importa identificativi partecipazione in rubrica “-ii”
Attraverso questa opzione sarà possibile importare, esclusivamente per i questionari che hanno
questa prerogativa: (quelli relativi alle rilevazioni CAF, SAC, EMF), importare i dati relativi agli
Istanza Attiva: è l’istanza più recente di un questionario, relativamente alla terna segnalante, rilevazione, data
riferimento. Qualora l’ultima istanza di un questionario si trovi in uno stato finale, ne verrà creata una nuova
relativamente all’importazione in corso.
3
identificativi di partecipazione, anche in una rubrica interna, utilizzabile successivamente per la
compilazione di successivi questionari che referenziassero gli stessi identificativi.
Separatore di campo “-se”
Con questa opzione sarà possibile definire il campo separatore di colonna del file CSV.
Path locale per il log “-pl”
L’applicazione scrive un log in formato html in una cartella di default: %USER_HOME%/Bdi/Log
Importazione/ , qualora si volesse reindirizzare la scrittura del log in una diversa locazione si dovrà
utilizzare questa opzione scrivendo il relativo percorso.
Il log relativo ad una importazione avrà una struttura del tipo quella riportata qui sotto:
Inizio Importazione
(commento). Cancellazione preventiva di tutte le segnalazioni dell'invio corrente: ESEGUITA!
(Segnalazione Importata). 326000000013410 Segnalazione Inserita. (Riga: 5)
(Segnalazione Importata). 326000000013430 Segnalazione Inserita. (Riga: 6)
(Segnalazione Importata). 326000000013440 Segnalazione Inserita. (Riga: 7)
(Segnalazione Importata). 326000000013530 <V00032>: . (Riga: 8)
OM21A: Attenzione ! Titolo non presente nella base dati attualmente in linea. Se si è certi della correttezza confermare
e chiedere codifica del codice isin alla Banca d'Italia
(Segnalazione Importata). 326000000023410 Segnalazione Inserita. (Riga: 9)
Importazione Annullata, effettuato Rollback!
Diagnosi ed invio di un file XBRL al sito BDI da riga di comando:
E’ stata esposta la possibilità di inviare un file XBRL previa diagnosi dello stesso, attraverso tutta la
serie di controlli abilitati per ognuna delle rilevazioni esistenti.
Questa funzione prevede la corretta configurazione del database DIRDEDB che in questo caso
serve esclusivamente come appoggio per l’esecuzione del diagnostico. Quindi bisognerà avere
precedentemente installato il prodotto PSDR o avere comunque configurato il database (vedi
procedura Configurazione Database).
La Classe DiagnosticaTrasmettiXbrl2SitoBDI permette di inviare un file XBRL dopo averne
diagnosticato il contenuto e se questa verifica risultasse positiva, provvederà alla trasmissione dello
stesso al sito BDI.
I parametri da passare al metodo main sono:
1. pathFileXbrl – il percorso in cui prelevare il file XBRL da controllare e inviare;
2. codiceSegnalante – il codice del segnalante per il quale si sta eseguendo l’invio.
NB. Se dovesse esserci una discrepanza tra i valori dichiarati e quelli presenti nello
xbrl, l’invio sarà bloccato dal sito con conseguente codice di errore;
3. codiceRilevazione – (EMF, OMF, OTF, TTN, CAF, SAC);
4. dataRiferimento – la data di riferimento in formato dd/MM/yyyy;
5. utenzaSito – la username dell’operatore con la quale ci si autentica per
l’applicazione Direct Reporting nel sito della Banca
http://uif.bancaditalia.it/DIRDGU;
6. password – la password.
La comunicazione con il sito BDI avviene sotto protocollo https, quindi le informazioni viaggiano
crittografate.
Come prima cosa il sito verificherà se l’operatore che sta effettuando la trasmissione, è autenticato e
se è abilitato ad operare per quello specifico Segnalante dichiarato.
Il sito verificherà se il file XBRL era effettivamente atteso. Quindi lo registrerà nella propria base
dati, ritornando una stringa di corretta esecuzione e il protocollo con cui è stato registrato il file.
Il comando di esecuzione da shell sarà:
java –classpath [inserendo tutti i percorsi dove trovare le librerie sopra indicate]
it/uic/dirde/importazioni/DiagnosticaTrasmettiXbrl2SitoBDI
D:\files\OMF_06.xbrl 512364 OMF 30/06/2008 utenza1 pwd12345
Utilizzo delle API di importazione da codice Java
Configurazione dell’ambiente Dati
Il codice di esempio sotto riportato può essere utilizzato per eseguire questa necessaria
configurazione, almeno la prima volta, poiché questa verrà salvata (criptata) sul file config.dat nella
%USER_HOME%/Bdi/ dell’utente connesso.
public static void configura(){
Configurazione config = Configurazione.getInstance();
// Questi Username e password servono esclusivamente per la connessione e
// autenticazione sul sito BDI, non hanno niente a che vedere con la tipologia
// di installazione del DB, quindi possono essere omessi in questa sede, per poi
// essere inseriti all’uopo prima della connessione al sito
config.setProperty(Configurazione.USERNAME, "USERPROVA1");
config.setProperty(Configurazione.PASSWORD, "ABCD-1234");
config.setProperty(Configurazione.DB_TYPE, Configurazione.DB_TYPE_EMBEDDED);
// config.setProperty(Configurazione.DB_TYPE, Configurazione.DB_TYPE_FILE);
// config.setProperty(Configurazione.DB_TYPE, Configurazione.DB_TYPE_SERVER);
if (Configurazione.isDatabaseTypeFile()) {
config.setProperty(Configurazione.DB_PATH, "\\\\nomeServerDB\\nomeCartella1");
}
if (!Configurazione.isDatabaseTypeEmbedded()) {
config.setProperty(Configurazione.DB_SERVER, "NOME_SERVER");
// Inserire il path per i files prodotti (Logs e XBRL dei questionari)"
config.setProperty(Configurazione.PATH_PRODOTTI, "\\\\nome server\\inserire percorso
cartella di lavoro");
}
config.salva();
}
Interfaccia ImportMonitor
Per quanto riguarda l’utilizzo della libreria di importazione da codice java, di seguito saranno
indicate delle strade per l’utilizzo.
In particolare è stata definita una interfaccia per il monitoraggio degli eventi che si susseguono
durante l’importazione. Tale interfaccia (ImportMonitor.java) è stata implementata nell’esempio
qui presentato dalla classe ImportLogger.java, ma potrà essere benissimo implementata da terze
classi a seconda delle esigenze dell’applicazione, essa presenta i seguenti metodi da implementare:
public interface ImportMonitor {
public void segnalazioneImportata(Messaggio messaggio)throws BloccoImportazioneException;
public void segnalazioneNonImportata(Messaggio messaggio)throws BloccoImportazioneException;
public void segnalazioneImportata(Vector<Messaggio> messaggi)throws BloccoImportazioneException;
public void segnalazioneNonImportata(Vector<Messaggio> messaggi)throws
BloccoImportazioneException;
public void commento(Messaggio messaggio)throws BloccoImportazioneException;
public void errore(Exception ex);
public void apri();
public void chiudi();
public void rollback();
// metodi necessari solamente se si gestisce una User Interface
public ImportParam getPatametriImportazione();
public void notifica(Messaggio messaggio) throws BloccoImportazioneException;
public void setProgressbarSize(int size);
}
Si ricorda che comunque è prevista la possibilità di passare al metodo importa anche il valore null,
ma in questo caso l’importazione non sarà bloccata a seguito di errori sulle segnalazioni, bensì esse
saranno comunque scritte nel DB con stato ERR piuttosto che WAR o OK.
Utilizzo classe ImportXml
Questo è un esempio di come si può utilizzare la libreria ImportXml.java per eseguire una
importazione di un file XML nel Database DIRDEDB dopo essere passati per tutti i controlli di
struttura, di dominio e di segnalazione. In questo caso la corretta esecuzione dell’importazione è
gestita con una semplice variabile booleana.
…
boolean importazioneRiuscita = false;
Invio invio = new Invio("561277", "OTF", "30/06/2008", "dd/MM/yyyy");
ImportParam importParam = new ImportParam();
importParam.setPathFile(("D:/FilesXML/OTF_2TRIMESTRE.xml");
importParam.setBloccaErrore(true);
importParam.setBloccaWarning(false);
importParam.setSovrascriviSegnalante(true);
importParam.setSovrascriviReferente(true);
importParam.setSovrascriviIdPartecipazione(false);
importParam.setScriviLog(true);
try {
ImportXml impo = new ImportXml(invio, importParam);
BaseDB.beginTransaction();
impo.importa(null);
BaseDB.commitTransaction();
importazioneRiuscita = true;
} catch (FileNotFoundException fnfe) {
importazioneRiuscita = false;
fnfe.printStackTrace();
} catch (Exception e) {
importazioneRiuscita = false;
try {
BaseDB.ensureConsistentConnection();
e.printStackTrace();
} catch (Exception e1) {
e1.printStackTrace();
}
}
…
Utilizzo classe ImportXbrl
In questo esempio è stata utilizzata la classe ImportLogger.java per monitorare gli eventi e per
avere il livello di errore massimo raggiunto nell’importazione. Si badi che una importazione, poiché
può essere eseguita su di un questionario con segnalazioni pre-esistenti, necessita di una ulteriore
verifica globale, infatti ad esempio la variabile livelloErrore dell’ImportLogger è indicativa del
livello massimo di errore raggiunto nella sola importazione.
…
Invio invio = new Invio("561277", "OMF", "30/06/2008", "dd/MM/yyyy");
ImportParam importParam = new ImportParam();
importParam.setPathFile(("D:/FilesXBRL/OMF_GIUGNO.xbrl");
importParam.setBloccaErrore(false);
importParam.setBloccaWarning(false);
importParam.setSovrascriviSegnalante(true);
importParam.setSovrascriviReferente(true);
importParam.setSovrascriviIdPartecipazione(false);
importParam.setScriviLog(true);
ImportLogger log = null;
try {
ImportXbrl impo = new ImportXbrl(invio, importParam);
log = new ImportLogger(TipologiaLog.Importazione, logPath);
BaseDB.beginTransaction();
impo.importa(log);
BaseDB.commitTransaction();
} catch (BloccoImportazioneException bie) {
try {
BaseDB.rollbackTransaction();
log.rollback();
} catch (Exception e) {
log.errore(e);
e.printStackTrace();
}
} catch (FileNotFoundException fnfe) {
fnfe.printStackTrace();
} catch (Exception e) {
e.printStackTrace();
try {
if (BaseDB.ensureConsistentConnection()) {
log.rollback();
}
e.printStackTrace();
} catch (Exception e1) {
log.errore(e1);
e1.printStackTrace();
}
}
LivelloErrore livelloErrore = log.getLivelloErrore(); //(OK, WAR, ERR)
…
Utilizzo classe ImportCvs
Stessa cosa per quanto riguarda l’importazione di file di formato CSV:
…
Invio invio = new Invio("561277", "OMF", "30/06/2008", "dd/MM/yyyy");
ImportParam importParam = new ImportParam();
importParam.setPathFile(("D:/FilesCSV/OMF_GIUGNO.csv");
importParam.setBloccaErrore(false);
importParam.setBloccaWarning(false);
importParam.setSovrascriviSegnalante(true);
importParam.setSovrascriviReferente(true);
importParam.setSovrascriviIdPartecipazione(false);
importParam.setScriviLog(true);
ImportLogger log = null;
try {
ImportCsv impo = new ImportCsv (invio, importParam);
log = new ImportLogger(TipologiaLog.Importazione, logPath);
BaseDB.beginTransaction();
impo.importa(log);
BaseDB.commitTransaction();
} catch (BloccoImportazioneException bie) {
try {
BaseDB.rollbackTransaction();
log.rollback();
} catch (Exception e) {
log.errore(e);
e.printStackTrace();
}
} catch (FileNotFoundException fnfe) {
fnfe.printStackTrace();
} catch (Exception e) {
e.printStackTrace();
try {
if (BaseDB.ensureConsistentConnection()) {
log.rollback();
}
e.printStackTrace();
} catch (Exception e1) {
log.errore(e1);
e1.printStackTrace();
}
}
LivelloErrore livelloErrore = log.getLivelloErrore(); //(OK, WAR, ERR)
Utilizzo classe ImportXbrl (per diagnostico)
Invece per quanto riguarda la sola diagnostica di un file XBRL esterno, senza importazione, si
eseguirà comunque l’importazione, ma alla fine eseguirà il rollback ripristinando la situazione
iniziale:
…
Invio invio = new Invio("561277", "OMF", "30/06/2008", "dd/MM/yyyy");
ImportParam importParam = new ImportParam();
importParam.setPathFile(("D:/FilesXBRL/OMF_GIUGNO.xbrl");
importParam.setBloccaErrore(false);
importParam.setBloccaWarning(false);
importParam.setSovrascriviSegnalante(true);
importParam.setSovrascriviReferente(true);
importParam.setSovrascriviIdPartecipazione(false);
importParam.setControlloXbrlEsterno(true);
importParam.setScriviLog(true);
ImportLogger log = null;
try {
ImportXbrl impo = new ImportXbrl(invio, importParam);
log = new ImportLogger(TipologiaLog.Importazione, logPath);
BaseDB.beginTransaction();
impo.importa(log);
BaseDB.rollbackTransaction ();
} catch (FileNotFoundException fnfe) {
fnfe.printStackTrace();
} catch (Exception e) {
e.printStackTrace();
try {
if (BaseDB.ensureConsistentConnection()) {
log.rollback();
}
e.printStackTrace();
} catch (Exception e1) {
log.errore(e1);
e1.printStackTrace();
}
}
LivelloErrore livelloErrore = log.getLivelloErrore(); //(OK, WAR, ERR)
…
Codice classe ImportXml DiagnosticaTrasmettiXbrl2SitoBDI
public static String esegui(String pathFileXbrl, String codiceSegnalante, String codiceRilevazione,
String dataRiferimento, String utenzaSito, String password)
throws Exception {
Invio invio = new Invio(codiceSegnalante, codiceRilevazione, dataRiferimento, "dd/MM/yyyy");
invio = InvioServizi.createInvio(invio.getSegnalante(), invio.getRilevazione(),
invio.getDataRiferimento());
boolean controlliOK = false;
ImportParam importParam = new ImportParam();
importParam.setBloccaErrore(true);
importParam.setBloccaWarning(false);
importParam.setSovrascriviSegnalante(true);
importParam.setSovrascriviReferente(true);
importParam.setSovrascriviIdPartecipazione(false);
importParam.setControlloXbrlEsterno(true);
importParam.setScriviLog(true);
importParam.setPathFile(pathFileXbrl);
ImportLogger log = null;
try {
Document dom = Xbrl2XmlFactory.getXmlDocument(pathFileXbrl, invio.getRilevazionePardis());
ImportXml impo = new ImportXml(invio, dom);
impo.setImportParam(importParam);
impo.setTipologiaCaricamento("XBRL");
log = new ImportLogger(TipologiaLog.Controlli);
BaseDB.beginTransaction();
impo.importa(log);
BaseDB.rollbackTransaction();
controlliOK = (log.getLivelloErrore()!=LivelloErrore.ERR);
} catch (BloccoImportazioneException bie) {
try {
BaseDB.rollbackTransaction();
log.rollback();
System.err.println("Operazione bloccata (File non trasmesso).");
} catch (Exception e) {
log.errore(e);
e.printStackTrace();
}
} catch (FileNotFoundException fnfe) {
fnfe.printStackTrace();
} catch (Exception e) {
System.err.println("Operazione non riuscita (File non trasmesso).");
e.printStackTrace();
try {
if (BaseDB.ensureConsistentConnection()) {
log.rollback();
}
e.printStackTrace();
} catch (Exception e1) {
log.errore(e1);
e1.printStackTrace();
}
}
String rispostaSito = null;
if (controlliOK) {
File file = new File(pathFileXbrl);
FileInputStream fis = new FileInputStream(file);
byte[] xbrl = new byte[fis.available()];
fis.read(xbrl);
fis.close();
rispostaSito = new ClientUpload(utenzaSito, password).upload(xbrl,
invio.getRilevazionePardis(), file.getName());
} else return "Controlli falliti! Il file "+pathFileXbrl+" non è stato trasmesso. Controllare il
file di log "+ImportParam.pathLog;
return rispostaSito;
}