MANUALE UTENTE XML-SAIA

Transcript

Revisione 2.1.1
15/10/2007
Pag. 1 di 37
SAIA
Sistema di Accesso Interscambio Anagrafico
MANUALE UTENTE
XML-SAIA
Revisione 2.1.1
15/10/2007
Pag. 2 di 37
SAIA
Introduzione .................................................................................................................. 3
1
XML-SAIA ............................................................................................................... 4
1.1
Installazione Applicazione client XML-SAIA ............................................... 4
1.2
Configurazione XML-SAIA Client .................................................................. 4
1.3
Esecuzione del client XML-SAIA ................................................................... 7
1.4
Funzioni di servizio del client XML-SAIA...................................................... 7
1.5
Errori generati da XML-SAIA Client. ............................................................. 8
1.6
Utilizzo come libreria.................................................................................... 11
1.6.1
Scenari di integrazione ............................................................................ 12
1.7
Aggiornamento automatico del software ................................................... 17
1.7.1
Aggiornamento del software XML-SAIA Client ........................................ 17
1.7.2
Aggiornamento tabella codici Istat........................................................... 18
2
Modulo JDBC2AP5 .............................................................................................. 19
2.1
Descrizione del modulo ............................................................................... 19
2.2
Configurazione XML-SAIA Client JDBC2AP5............................................. 19
2.3
Esecuzione del client XML-SAIA JDBC2AP5 ............................................. 20
3
Funzionalità e tracciati del Client XML-SAIA..................................................... 21
3.1
Funzionalità e tracciati per la versione 1 del client XML-SAIA ................. 21
3.2
Funzionalità e tracciati per la versione 2 del client XML-SAIA ................. 23
3.3
Funzionalità e tracciati per la versione 2.1.0.0 del client XML-SAIA ........ 27
3.4
3.5
3.6
3.7
4
Predisposizione del file di input e lettura del file di output ............................. 33
5
Java Runtime Environment (JRE) ...................................................................... 34
5.1
Installazione JRE .......................................................................................... 34
5.2
Installazione JRE su piattaforma Windows................................................ 34
5.3
Installazione JRE su piattaforma GNU/Linux ............................................. 36
Revisione 2.1.1
15/10/2007
Pag. 3 di 37
SAIA
INTRODUZIONE
XML-SAIA (Sistema di Accesso e Interscambio Anagrafico) è il nuovo software prodotto
da Ancitel per consentire ai Comuni Italiani di comunicare con il SAIA.
Pur con la garanzia di retrocompatibilità rispetto ai tracciati “JJ”, il sistema SAIA è stato
esteso ed è in grado di gestire un nuovo formato XML rispettando le linee guida definite
nell’AP5, la nuova struttura dati per i flussi di comunicazione dalle Anagrafi Comunali al
Centro Nazionale Servizi Demografici.
La caratteristica principale del software XML-SAIA è quella di introdurre il supporto del
formato XML per l’interscambio di informazioni anagrafiche tra Comuni Italiani,
Ministero degli Interni e ulteriori enti interessati.
Un file XML (eXtensible Markup Language) è un file in formato testo in cui si trovano
dati strutturati seguendo delle linee guida definite in uno schema di definizione, un file
XSD (XML Schema Definition) contenente le regole da rispettare durante la
generazione di un file XML ad esso associato.
XML facilita la generazione dei dati tramite un computer, la comprensione all’operatore
umano e il controllo sulla struttura in modo che non sia ambigua.
XML risolve alcune tra le pecche più comuni dei linguaggi: è estensibile, indipendente
dalla piattaforma e supporta i parametri internazionali e locali.
SAIA
Revisione 2.1.1
15/10/2006
Pag. 4 di 37
1 XML-SAIA
1.1 Installazione Applicazione client XML-SAIA
Il software XML-SAIA Client è un’applicazione scritta in Java.
La comunicazione tra il Client distribuito ai Comuni e la “Porta di Accesso”, avviene
mediante protocollo standard TCP/IP.
In quanto scritto in Java, il software impone come prerequisito la presenza di un JRE
(Java Runtime Environment), versione 1.4.0 o superiori già installato sulla macchina da
utilizzare.
Nel caso in cui sulla macchina non sia presente un JRE già installato, si rimanda alla
sezione JAVA RUNTINE ENVIRONMENT (JRE).
Il
software
XML-SAIA
è
prelevabile
dal
sito
del
CNSD
(http://www.servizidemografici.interno.it/) alla sezione download cliccando sul link
Download software INA-SAIA.
Seguendo le indicazioni del sito sopraindicato, prelevare il pacchetto xml-saia.
Decomprimendo il pacchetto, per esempio con WinZip se si sta operando su piattaforma
Windows, si verrà a creare sul sistema la cartella d’installazione del client XML-SAIA.
Al termine dell’esecuzione dei passi appena descritti, il software XML-SAIA sarà installato
sulla macchina e potrà essere utilizzato dopo un’opportuna configurazione.
1.2 Configurazione XML-SAIA Client
Nella precedente versione del software XML-SAIA (denominato PCCSA), per operare una
corretta configurazione, era necessario editare i seguenti file:
Path.def=Path dei file di configurazione.
Defcli.cfg=Nomi degli altri file di configurazione.
Defsrv.cfg=Configurazione di Rete per il colloquio con il Server.
Default.drt=File per il logon, file con i dati da trasferire e file di output.
In questa nuova versione del software è stata effettuata una semplificazione per la quale è
presente un solo file di configurazione, di default configuration.ini (il nome del file è un
parametro a runtime, quindi configurabile), di cui esiste già un esempio contenuto
all’interno del pacchetto xml-saia.zip.
4/37
SAIA
Revisione 2.1.1
15/10/2006
Pag. 5 di 37
Editando il file configuration.ini, con un qualsiasi editor di testo ad esempio notepad, si
nota la presenza delle seguenti direttive che l’utente può adattare alle proprie esigenze:
# Generale
- formatoDati: indica il formato dei dati che si utilizza per comunicare con XML-SAIA v.1.
Può essere valorizzato con uno dei due seguenti valori:
1. JJ se si intende utilizzare i tracciati piatti in formato JJ.
2. XML-V1 se si intende utilizzare il formato XML descritto al capitolo 2.1 del presente
documento.
3. AP5-XML se si intende utilizzare il formato XML AP5
Per attivare la possibilità di impiegare file XML nel tracciato AP5, descritto al capitolo 2.2
del presente documento, è necessario richiedere l’abilitazione tramite l’assistenza tecnica.
- inputFile: Percorso assoluto e nome del file contenente i tracciati da inviare al server
Porta di Dominio, ad esempio C:\Percorso\inputFile.in;
- outputFile: Percorso assoluto e nome del file in cui il software XML-SAIA andrà a
scrivere risposte ricevute dalla Porta di Dominio, ad esempio C:\Percorso\outputFile.out;
- encoding: Encoding dei file di input e output. p.e. UTF-8;
# Sicurezza
- pathCertificatoClient: Percorso assoluto e nome del file contenente il Certificato Client
per lo scambio dei dati. Es.: C:\Percorso\cert_1.pfx;
- pathCertificatoServer: Percorso assoluto e nome del file contenente il Certificato Server
per lo scambio dei dati. Es.: C:\Percorso\ pacert.pem;
Al fine di ottenere il certificato client seguire le indicazioni riportate al capitolo 5 (Il
programma di gestione QSAC) del Manuale QSAC.
Al fine di ottenere il certificato server accedere alla macchina sulla quale è installata la
Porta di Accesso e prelevarlo dalla cartella C:\ssclitmp e posizionarlo nella cartella indicata
dal parametro pathCertificatoServer.
# Mittente
- istat: Codice ISTAT del Comune;
- ufficio: Identificativo dell’ufficio responsabile del Sistema Comunale;
- identificativoRete: Identificativo di rete del Sistema Comunale;
- responsabile: Identificativo del responsabile della richiesta;
# Destinatario
- istatPortaAccesso: Codice ISTAT del Comune presso cui è installata la Porta di
Accesso Comunale;
5/37
SAIA
Revisione 2.1.1
15/10/2006
Pag. 6 di 37
- identificativoPortaAccesso: Identificativo di rete della Porta di Accesso Comunale cui è
diretta la comunicazione;
Notiamo che, rispetto al precedente software PCCSA, non è presente il file di
configurazione dove memorizzare user e password applicative. Questo al fine di garantire
uno standard di sicurezza superiore. I valori suddetti sono da passare come parametri
all’esecuzione dell’applicazione.
Sono inoltre presenti altri parametri utili soprattutto per l’integrazione con un software
utilizzando XML-SAIA come libreria
# Altri parametri di Configurazione
- istatDataDir: Indica il path in cui vengono scaricati i file contenenti l’anagrafica per il
controllo dei codici istat (solo per invio dati in formato JJ). Se non valorizzato assume il
valore “./istat”.
- resumeDir: Indica il path in cui memorizzare il file di recovery con il quale il client riesce
a ricostruire gli inoltri interrotti per problemi tecnici (solo per invio dati in formato JJ). Se
non valorizzato assume il valore “./resume”.
- overrideDir: Indica il path in cui è presente il file driverOverride.ini. in cui sono impostate
le Url del server a cui connettersi attraverso la porta di accesso. Il file è presente nella
distribuzione del client nella direcotory “override” e aggiorna il file driverOverride.ini in
automatico nel path indicato. Se non valorizzato assume il valore “./override”.
- errorDir: Indica il path in cui è presente il file di tracciamento degli errori client ad uso
diagnostico. Se non valorizzato assume il valore “./error”.
- log4j.properties: Indica il percorso completo del file log4j.properties in cui sono definite
le impostazioni relative ai file di log prodotti dal client. Se non valorizzato assume il valore
“./conf/log4j.properties”.
- root.driver.dir: Indica la cartella di lavoro dove il client scarica gli aggiornamenti del
proprio software e traccia
- dumpInvio: Indica se scrivere i file di dump delle richieste e delle risposte ricevute dal
server (accetta true/false) . Se non valorizzata si assume il valore false. Da utilizzare per
esigenze di test/debug.
- xml.dump.dir: Indica il path in cui scrivere i file di dump delle richieste e delle risposte
ricevute dal server. Se non valorizzata si assume il valore ./dump.
- ssl.need.startup: Indica se avviare il servizio ssl con i certificati client e server necessari
per lo scambio dati (accetta true/false). Se non valorizzata si assume il valore false.
- log4j-1.2.8.jar.download: Indica al client di non effettuare il download della libreria di
log4j (accetta true/false). Se non valorizzata si assume il valore true.
6/37
SAIA
Revisione 2.1.1
15/10/2006
Pag. 7 di 37
1.3 Esecuzione del client XML-SAIA
Per eseguire il Client XML-SAIA è sufficiente aprire un terminale e spostarsi
all’interno della cartella di installazione del software.
Su un sistema di tipo Windows digitare:
xml-saia.bat --cfg <file di configurazione> --login <nome utente> --pwd
<password> --certpwd <password del certificato>
Su un sistema di tipo GNU/Linux digitare:
xml-saia.sh --cfg <file di configurazione> --login <nome utente> --pwd <password>
--certpwd <password del certificato>
Si noti che nel caso in cui non venga specificato nessun file di configurazione tramite la
direttiva cfg, verrà considerato di default il file conf/configuration.ini che si trova
all’interno della directory d’installazione di XML-SAIA.
1.4 Funzioni di servizio del client XML-SAIA
A partire dalla versione 1.1.0.3 del client XML-SAIA, sono disponibili le seguenti funzioni di
servizio:
•
Versione del software XML-SAIA Client – Digitando:
su un sistema di tipo Windows:
xml-saia.bat --version
oppure
xml-saia.bat –v
o su un sistema di tipo GNU/Linux:
xml-saia.sh --version
oppure
xml-saia.sh -v
si ottiene la versione del software XML-SAIA Client che si sta utilizzando.
•
Versione del software XML-SAIA Client-Worker – Digitando:
xml-saia.bat --version
oppure
xml-saia.bat –w
xml-saia.sh --worker
oppure
xml-saia.sh -w
7/37
SAIA
Revisione 2.1.1
15/10/2006
Pag. 8 di 37
si ottiene la versione del software XML-SAIA Client-Worker che si sta utilizzando
per comunicare con il SAIA.
•
Aggiornamento del software XML-SAIA Client-Worker – Digitando:
xml-saia.bat --update –l “login” –p “password” –t “password del certificato”
oppure
xml-saia.bat –u –l “login” –p “password” –t “password del certificato”
xml-saia.sh --update –l “login” –p “password” –t “password del certificato”
oppure
xml-saia.sh –u –l “login” –p “password” –t “password del certificato”
si avvia la procedura di autoaggiornamento del software XML-SAIA ClientWorker che si può utilizzare per comunicare con il SAIA.
•
Diagnostica – Digitando:
xml-saia.bat --diagnostica –l “login” –p “password” –t “password del certificato”
oppure
xml-saia.bat –d –l “login” –p “password” –t “password del certificato”
xml-saia.sh --diagnostica –l “login” –p “password” –t “password del certificato”
oppure
xml-saia.sh –d –l “login” –p “password” –t “password del certificato”
si avvia la procedura di diagnostica della connessione.
1.5 Errori generati da XML-SAIA Client.
Codice Descrizione
1
File di configurazione non trovato
Possibili risoluzioni
1. Assicurarsi di aver creato il
file di configurazione avente il
nome indicato nel parametro
di esecuzione --cfg.
2. Assicurarsi che il percorso del
file indicato nel parametro di
esecuzione --cfg sia corretto.
8/37
SAIA
Revisione 2.1.1
15/10/2006
Pag. 9 di 37
2
Problema con il file di configurazione
1.
Assicurarsi che nel file di
configurazione
siano
presenti tutti i parametri
indicati nel paragrafo 1.2.
3
Errore nel caricamento del client
1.
Cancellare le cartelle client,
clientDescriptor,
override,
repository e rilanciare il
client.
4
Problema nell'aggiornamento del client
1. Verificare che nel proprio
DNS il nome “prtaccom” sia
risolto con l’indirizzo corretto.
2. Cancellare le cartelle client,
clientDescriptor,
override,
repository e rilanciare il client
con l’opzione -u.
5
Problema con il pacchetto client
1.
clientDescriptor,
override,
client.
6
Problema nella creazione del pacchetto
client
1.
clientDescriptor,
override,
client.
7
Parametro Login non presente
1. Lanciare il client con i
parametri
corretti,
come
indicato nel paragrafo 1.3
8
Parametro Password non presente
parametri
corretti,
come
9
Parametro Password del Certificato non
presente
parametri
corretti,
come
10
Problema di connessione con il server
1. Verificare che nel proprio
DNS il nome “prtaccom” sia
risolto con l’indirizzo corretto.
2. Verificare di aver configurato
correttamente
ogni
componente dell’architettura
di rete.
9/37
SAIA
Revisione 2.1.1
15/10/2006
Pag. 10 di 37
11
Autenticazione fallita
parametri login e password
valorizzati correttamente.
12
Problema con il file di input
1. Assicurarsi di aver creato il
file di input avente il nome
indicato
nella
proprietà
inputFile
del
file
di
configurazione.
file di input indicato nella
proprietà inputFile del file di
configurazione sia corretto.
13
Problemi con il caricamento del certificato
1. Assicurarsi
che
il
file
contenente
il
certificato
avente il nome indicato nella
proprietà pathCertificatoClient
del file di configurazione sia
presente.
certificato
indicato
nella
proprietà pathCertificatoClient
del file di configurazione sia
corretto.
14
Password del certificato errata
15
Driver disabilitato per il formato dati AP5.
Usare nuova versione
1. Lanciare il client con il
parametro
password
del
certificato
valorizzato
correttamente.
1. Scaricare la nuova versione
del client xml-saia dal sito del
CNSD.
16
17
Destinato ad usi futuri
E' stato aggiornato il software. E'
necessario il riavvio.
Errore di sistema
18
19
20
1. Effettuare
una
nuova
invocazione del client.
1. Verificare l’istallazione del
client, cancellare le cartelle
client,
clientDescriptor,
override,
repository
e
rilanciare il client.
10/37
SAIA
Revisione 2.1.1
15/10/2006
Pag. 11 di 37
1.6 Utilizzo come libreria
Il Client XML-SAIA può essere utilizzato come libreria da invocare direttamente da un’altra
applicazione.
La comunicazione avviene attraverso l’invocazione di alcune API messe a dispostone dal
Client XML-SAIA.
Il contenuto informativo utilizza gli stessi formati definiti per l’invocazione batch.
Attraverso le property inputFile e outputFile è possibile definire i file di scambio da
utilizzare per l’invio dei messaggi al SAIA e la ricezione delle risposte.
Il client può essere configurato per non effettuare l’avvio del servizio ssl se già avviato
all’interno dell’applicazione chiamante attraverso la property ssl.need.startup.
Tale opzione può essere utilizzata anche per l’accesso nell’ambiente di test pubblico.
Se l’applicazione chiamante ha già configurato e attivato il framework Log4j con la
definizione dei “logger”, il client non tenterà di caricare la propria configurazione di log4j.
In questo caso è importante che vengano definiti i logger coerentemente con quanto
distribuito nel pacchetto client (vedi file di configurazione log4j.properties).
Per utilizzare il Client XML-SAIA da un altro applicativo è necessario:
o configurare la variabile di ambiente CLASSPATH in modo che siano visibili
all’interprete java le seguenti librerie:
-
xml-saia-driver.jar
commons-cli-1.0.jar
log4j-1.2.8.jar
o predisporre i seguenti file di configurazione:
- configuration.ini: file di configurazione del client (come descritto nel paragrafo §1.2)
- log4j.prpoperties: file di configurazione del framework log4j (vedi documentazione
specifica in riferimento ad Apache Log4J)
- driverOverride.ini: file di configurazione dei puntamenti verso il CNSD (fornito nel
pacchetto di istallazione)
o predisporre l’alberatura esecutiva configurata attraverso i parametri di configurazione
descritti nel paragrafo §1.2
o integrare la chiamata del client attraverso i metodi descritti in formato JavaDoc nel
seguente allegato:
[xml-saia-client_JavaDoc.zip]
11/37
SAIA
Revisione 2.1.1
15/10/2006
Pag. 12 di 37
1.6.1 Scenari di integrazione
Sono state testate alcune configurazioni utilizzabili per alcune delle integrazioni più
comuni: in particolare sono stati predisposti degli esempi di configurazioni per
- integrazione da applicazione JAVA Stand Alone
- integrazione con applicazione Web Java istallata su Container Tomcat 5.0
Per ogni esempio è descritta l’alberatura ipotizzata, la configurazione necessaria e la
modalità di invocazione della libreria.
1.6.1.1 Integrazione in applicazione stand alone
L’esempio in questione prevede un’istallazione del software di anagrafe in cui vengono
integrate le librerie di xml-saia, i suoi file di configurazione e i certificati per il colloquio con
protocollo HTTPS. Il file di configurazione è caricato dall’applicazione chiamante e
passato in memoria al client.
1.6.1.1.1 Alberatura
Di seguito un esempio di alberatura esecutiva dove:
- application-home indica il path di istallazione dell’applicazione di anagrafe
- xml-saia-work è un path di lavoro in cui possono essere movimentati dati, log e file di
lavoro del client.
12/37
SAIA
Revisione 2.1.1
15/10/2006
Pag. 13 di 37
Alberatura esecutiva
application-home
|---- configuration
|---- driverOverride.ini
|---- log4j.properties
|---- v1-configuration.ini
|---- driver-libs
|---- changelog.txt
|---- client-parameters.ini
|---- commons-cli-1.0.jar
|---- info.dat
|---- log4j-1.2.8.jar
|---- xml-saia-driver.jar
|---- ssl-tv
|---- cert_1.pfx
|---- pacert.pem
|---- …..
changelog.txt
xml-saia-work
|---- istat
|---- logs
|---- ….
|-----resume
|---- tracciati
|---- default.in.txt
|---- default.out.txt
|---- xml-saia-client
|---- xml-saia-driver
1.6.1.1.2 Configurazione
Di seguito le impostazioni che consentono la gestione dell’alberatura sopra descritta.
v1-configuration.ini
log4j.properties=./configuration/log4j.properties
dumpInvio=true
root.driver.dir=../xml-saia-work
istatDataDir=../xml-saia-work/istat
resumeDir=../xml-saia-work/resume
overrideDir=./configuration
xml.dump.dir=../xml-saia-work/dump
13/37
SAIA
Revisione 2.1.1
15/10/2006
Pag. 14 di 37
1.6.1.1.3 Modalità di esecuzione
Di seguito un esempio di invocazione della libreria con il passaggio in memoria del file di
configurazione senza specificarne uno su file system
Codice di esempio
Properties prop=new Properties();
prop.load(new FileInputStream("configuration/v1-configuration.ini"));
int ret=Client.getInstance(prop).start(null, "XXXXXX", "YYYYYY", “zzzzzz”);
if (ret != ClientWorker.RET_OK)
{
System.out.println("Errore : " + ret);
}
1.6.1.2 Integrazione in applicazione Web (Tomcat 5.0.x)
L’esempio in questione presuppone la presenza di un’istallazione del software di anagrafe
in una web application Tomcat 5.0. E’ prevista quindi l’integrazione con xml-saia (tramite
libreria) mediante una condivisione dei file di configurazione e dei certificati per il colloquio
con protocollo HTTPS. Il file di configurazione di XML-SAIA è caricato dall’applicazione
chiamante e passato in memoria al client.
Alcune property vengono rivalorizzate sulla base del path di istallazione di Tomcat.
Si presuppone inoltre che la webapp abbia già attiva una condifurazione di log4j.
14/37
SAIA
Revisione 2.1.1
15/10/2006
Pag. 15 di 37
1.6.1.2.1 Alberatura
Di seguito un esempio di alberatura esecutiva dove:
- tomcat-home indica il path di istallazione del server Tomcat in cui è pubblicata
l’applicazione di anagrafe.
- xml-saia-work è un path di lavoro in cui possono essere movimentati dati, log e file di
lavoro del client.
Alberatura esecutiva
tomcat-Home
|---- conf
|---- log4j.properties
|---- v2-configuration.ini
|---- ssl-tv
|---- cert_1.pfx
|---- pacert.pem
|---- webapps
|---- anagrafe
|---- WEB-INF
|---- lib
|---- changelog.txt
|---- client-parameters.ini
|---- commons-cli-1.0.jar
|---- info.dat
|---- log4j-1.2.8.jar
|---- xml-saia-driver.jar
|---- …..
|---- …..
|---- …..
|---- …..
changelog.txt
xml-saia-work
|---- logs
|---- ….
|---- tracciati
|---- default.in.txt
|---- default.out.txt
|---- xml-saia-client
|---- xml-saia-driver
15/37
SAIA
Revisione 2.1.1
15/10/2006
Pag. 16 di 37
1.6.1.2.2 Configurazione
Di seguito le impostazioni che consentono la gestione dell’alberatura sopra descritta.
V2-configuration.ini
log4j.properties=
dumpInvio=true
root.driver.dir=/xml-saia-work
istatDataDir=/xml-saia-work/istat
resumeDir=/xml-saia-work/resume
overrideDir=/configuration
xml.dump.dir=/xml-saia-work/dump
1.6.1.2.3 Modalità di esecuzione
Di seguito un esempio di invocazione della libreria con il passaggio in memoria del file di
configurazione senza specificarne uno su file system e con la ridefinizione a run time di
alcune impostazioni.
Codice di esempio
Properties prop=new Properties();
prop.load(
new FileInputStream(
System.getProperty("catalina.home") +“/v2-configuration.ini"));
prop.setProperty("overrideDir", System.getProperty("catalina.home")+”/conf”);
File fSSL=new File(System.getProperty("catalina.home"),"ssl-tv");
prop.setProperty("pathCertificatoClient",new File(fSSL,"cert_1.pfx").toURI().getPath());
prop.setProperty("pathCertificatoServer",new
File(fSSL,"pacert.pem").toURI().getPath());
PropertyConfigurator.configure(
System.getProperty("catalina.home") +“/log4j.properties"));
int ret=Client.getInstance(prop).start(null, "XXXXXX", "YYYYYY", “zzzzzz”);
if (ret != ClientWorker.RET_OK)
{
System.out.println("Errore : " + ret);
}
16/37
SAIA
Revisione 2.1.1
15/10/2006
Pag. 17 di 37
1.7 Aggiornamento automatico del software
Il client XML-SAIA dispone di una nuova funzionalità che lo rende particolarmente adatto
ad essere distribuito sul territorio: l’aggiornamento automatico delle versioni del software
rilasciato.
1.7.1 Aggiornamento del software XML-SAIA Client
Ad ogni avvio del software XML-SAIA Client la versione locale dell’applicazione viene
confrontata con quella pubblicata sul server XML-SAIA. Se la versione client, disponibile
presso il Comune, risulta essere precedente a quella pubblicata sul server questa verrà
automaticamente istallata sulla postazione comunale e quindi eseguita per l’invio delle
comunicazioni.
La procedura di auto-aggiornamento funziona nel modo seguente:
1. Download del Client Descriptor – Il Client Descriptor è un file che consente di
identificare librerie e files di configurazione necessari al XML-SAIA Client per poter
comunicare con il server SAIA. La procedura di autoaggiornamento prevede come
primo passo di ottenere dalla Web-Utility di SAIA il Client Descriptor.
2. Confronto del Client Descriptor appena scaricato con il vecchio Client
Descriptor presente sulla macchina comunale – Dopo aver scaricato
l’aggiornamento del Client Descriptor, il software XML-SAIA Client effettua un
confronto tra tale Client Descriptor e quello già presente sulla macchina del
comune, per verificare se ci sono differenze tra i files del software XML-SAIA Client
presenti sulla macchina comunale e i files presenti sulla macchina in cui è installata
la Web-Utility di SAIA.
3. Confronto di coerenza tra il Client Descriptor scaricato e i files costituenti il
software XML-SAIA Client presenti sulla macchina del comune – Se i Client
Descriptors confrontati al punto 2 sono identici, si provvede ad effettuare un
ulteriore controllo di coerenza tra il Client Descriptor scaricato ed i files del software
che compongono il Client XML-SAIA presenti localmente sulla macchina del
comune. Tale controllo consiste nel verificare che le librerie e i files di
configurazione di cui il software è costituito siano esattamente gli stessi che sono
descritti nel Client Descriptor. In caso affermativo la procedura di
autoaggiornamento termina, in quanto si è certi che il software presente sulla
macchina del comune è l’ultima versione del XML-SAIA Client disponibile.
4. Download dei files più aggiornati – Nel caso in cui i Client Descriptors non
abbiano lo stesso contenuto o i files costituenti il Client XML-SAIA non siano
coerenti con quelli descritti nel Client Descriptor (ovvero nel caso in cui almeno uno
dei confronti descritti al punto 2 e al punto 3 termini con risultato negativo), la
procedura di autoaggiornamento continua, scaricando dal repository della WebUtility di SAIA solo le librerie e i files di configurazione del Client XML-SAIA che
sono più aggiornati di quelli già presenti sulla macchina del comune.
17/37
SAIA
Revisione 2.1.1
15/10/2006
Pag. 18 di 37
Figura 1.7-1 UML Sequence diagram che illustra la procedura di auto-aggiornamento
1.7.2 Aggiornamento tabella codici Istat
Lo stesso meccanismo di aggiornamento automatico è previsto per la tabella dei codici
Istat che permette al software comunale di verificare l’esattezza di tali codici direttamente
sulla macchina comunale evitando di inviare file le cui informazioni, qualora non fossero
corrette, sarebbero comunque scartate in un secondo momento.
18/37
SAIA
Revisione 2.1.1
15/10/2006
Pag. 19 di 37
2 MODULO JDBC2AP5
2.1 Descrizione del modulo
JDBC2AP5 è un modulo di XML-SAIA (Sistema di Accesso e Interscambio Anagrafico)
che consente ai Comuni Italiani di interfacciarsi con XML-SAIA. Permette Comuni di
comunicare tramite XML-SAIA con il SAIA semplicemente trasferendo dati dal database
dell’anagrafe comunale al database del modulo JDBC2AP5, delegando al modulo stesso
la gestione del formato AP5 e la comunicazione di dati in tale formato con XML-SAIA.
Il modulo fornisce la possibilità di utilizzare diversi tipi di database (es. Oracle, Mysql,
PostgreSQL, Access…). Il software comunale inserisce nel database dell’applicativo i dati
relativi alle comunicazioni anagrafiche da inviare; il modulo JDBC2AP5 si occupa della
loro trasformazione in file XML formato AP5, dell’invio di tali dati al SAIA tramite
XML_SAIA e di inserire nel suddetto database i dati ricavati dalle risposte ricevute in
conseguenza dell’operazione eseguita, sia essa un invio di comunicazioni anagrafiche,
una richiesta di stato code o di presa in carico.
Tramite il modulo JDBC2AP5 è quindi possibile per il software comunale interagire con
SAIA (tramite XML-SAIA) focalizzando l’attenzione sui dati da scrivere e leggere dal
database del modulo stesso, tralasciando sia l’aspetto legato alla generazione e gestione
dei dati in formato AP5 che quello legato alla comunicazione con XML-SAIA.
2.2 Configurazione XML-SAIA Client JDBC2AP5
Editare il file configuration.ini, impostando le seguenti proprietà:
-application: indica il tipo di applicazione da eseguire. Per utilizzare JDBC2AP5 inserire
connector
Nella sezione AP5Connector
# AP5-Connector
- connector.in.archive.format: indica il formato di archiviazione dei dati ricevuti dal SAIA.
Può essere valorizzato con uno ZIP se si intende comprimere il file prima di archiviarlo;
lasciare senza valore altrimenti;
- connector.richieste.per.lotto: numero massimo di comunicazioni per richiesta. Lasciare
vuoto per non impostare alcun limite massimo;
- connector.db.type: indica il tipo di database utilizzato Può assumere i seguenti valori:
1. Oracle9i;
2. PostgreSQL81;
3. MySQL5;
4. Access2000.
19/37
SAIA
Revisione 2.1.1
15/10/2006
Pag. 20 di 37
- connector.db.url: l'indirizzo IP del database;
- connector.db.port: la porta del database;
- connector.db.alias: l'alias del database;
- connector.db.usr: l'utenza con cui accedere al database;
- connector.db.pwd: la password associata all'utenza per il database impostata;
- connector.mittente.codiceistat: il codice istat del comune mittente;
- connector.mittente.nomecomune: il nome del comune mittente;
- connector.mittente.siglaprovincia: la sigla della provincia del comune mittente;
2.3 Esecuzione del client XML-SAIA JDBC2AP5
Per eseguire il Client XML-SAIA JDBC2AP5 è sufficiente aprire un terminale e
spostarsi all’interno della cartella di installazione del software.
Su un sistema di tipo Windows digitare:
xml-saia.bat --cfg <file di configurazione> --login <nome utente> --pwd
<password> --certpwd <password del certificato> -jconn_op <azione da eseguire> jconn_cf <codice fiscale dell’utente>
Su un sistema di tipo GNU/Linux digitare:
xml-saia.sh --cfg <file di configurazione> --login <nome utente> --pwd <password>
--certpwd <password del certificato>
Il parametro -jconn_op può assumer uno dei seguenti tre valori.
1. ca : invio di comunicazioni anagrafiche;
2. sc : richiesta di stato code;
3. pic : richiesta di presa in carico.
20/37
SAIA
Revisione 2.1.1
15/10/2006
Pag. 21 di 37
3 FUNZIONALITÀ E TRACCIATI DEL CLIENT XML-SAIA
3.1 Funzionalità e tracciati per la versione 1 del client XML-SAIA
La versione 1 di XML-SAIA mette a disposizione dei comuni la possibilità di inviare le
seguenti comunicazioni anagrafiche al sistema SAIA istallato presso il Centro Nazionale
Servizi Demografici:
•
•
•
•
•
•
•
Comunicazioni di Nascita (CA01)
Annullamento comunicazioni di nascita (CA01)
Comunicazione di Cambio di Residenza (CA01)
Dati della patente per MCTC (MC11)
Dati dei veicoli per MCTC (MC12)
Comunicazione di Decesso (CA01)
Funzioni di Ripetizione (CA16)
Presa in Carico (ITPC)
Stato delle Code (ITSC)
Le risposte previste per le comunicazioni sopraelencate sono:
•
•
•
•
•
•
•
•
•
Documento Accettato (ITAC)
Messaggio Generico (ITMS)
Errore Fatale (ITFE)
Errore dal Centro (EXnn)
Esito comunicazione anagrafica per Anagrafe Tributaria (AT54)
Esito comunicazione anagrafica per INPS (IN54)
Esito comunicazione anagrafica per MCTC (MC64)
Fine invio (ITDT)
Stato Invio (ITLS)
Nell’implementazione di queste funzionalità si è posta particolare attenzione alla
retrocompatibilità con la precedente versione di SAIA.
Con questa versione, sarà possibile utilizzare due tipologie di file di input per il SAIA le cui
differenze sono sotanzialmente il formato delle informazioni utilizzate dai comuni.
Le due alternative sono:
1. L’utilizzo dei vecchi tracciati record denominati JJ;
Le specifiche di produzione dei vecchi tracciati JJ+ non sono in alcun modo
cambiate e sono consultabili all’indirizzo:
http://www.servizidemografici.interno.it/cnsd/settori/ina-saia/
competenze/documentazioneOperativa/documentazioneOperativa.htm
per le funzionalità sopra esposte. In particolare le specifiche dei tracciati sono
disponibili nei documenti ‘Tracciati record pccsa_1’, ‘Tracciati record pccsa_2’,
‘Tracciati record pccsa_3’.
21/37
SAIA
Revisione 2.1.1
15/10/2006
Pag. 22 di 37
Anche i tracciati previsti per le risposte generate dal Server SAIA sono
completamente compatibili con specifiche della versione precedente e sono
reperibili presso il sito del CNSD all’hyperlink ‘Schema funzionale del pccsa’.
Esempio:
JJ+;CA01+321+1+1+++CAZORANI+MANUELE+M+18102005+085022+VIA+CAN
NOLI+22+93010+++++++S+N+;
JJ+;CA01+322+1+1+++PELUSI+GIUSEPPE+M+06112005+085022+VIA+TORO+3
3+93010+++++++S+N+;
2. La riformulazione degli stessi contenuti informativi adattati alla specifica XML-V1.
Le regole sulla struttura dei tracciati XML-V1 sono contenute nello schema di
definizione RichiestaSaia.xsd, contenuto in xsd-v1-0.98.zip, reperibile presso il sito
web della Direzione Centrale dei servizi demografici nell’area privata alla voce
DOWNLOAD.
Esempio:
<?xml version="1.0" encoding="UTF-8"?>
<richiestaSaia tipoRecord="CA01">
<versione>1.0</versione>
<utente>
<login>X</login>
<password>X</password>
</utente>
<dataRichiesta>2005-11-22T16:22:49.281+01:00</dataRichiesta>
<richieste>
<richiesta>
<CA01 protocolloSaia="X">
<protocolloMittente>321</protocolloMittente>
<tipoInoltro>1</tipoInoltro>
<tipoComunicazione>1</tipoComunicazione>
<cognome>CAZORANI</cognome>
<nome>MANUELE</nome>
<sesso>M</sesso>
<dataDiNascita>2005-10-18</dataDiNascita>
<codIstatSiglaStatoEstero>085022</codIstatSiglaStatoEstero>
<prefissoToponomastico>VIA</prefissoToponomastico>
<indirizzo>CANNOLI</indirizzo>
<numeroCivico>22</numeroCivico>
<cap>93010</cap>
<cittadinanzaItaliana>S</cittadinanzaItaliana>
<AIRE>N</AIRE>
</CA01>
</richiesta>
<richiesta>
22/37
SAIA
Revisione 2.1.1
15/10/2006
Pag. 23 di 37
<CA01 protocolloSaia="X">
<protocolloMittente>322</protocolloMittente>
<tipoInoltro>1</tipoInoltro>
<tipoComunicazione>1</tipoComunicazione>
<cognome>PELUSI</cognome>
<nome>GIUSEPPE</nome>
<sesso>M</sesso>
<dataDiNascita>2005-11-06</dataDiNascita>
<codIstatSiglaStatoEstero>085022</codIstatSiglaStatoEstero>
<prefissoToponomastico>VIA</prefissoToponomastico>
<indirizzo>TORO</indirizzo>
<numeroCivico>33</numeroCivico>
<cap>93010</cap>
<cittadinanzaItaliana>S</cittadinanzaItaliana>
<AIRE>N</AIRE>
</CA01>
</richiesta>
</richieste>
</richiestaSaia>
Per utilizzare i tracciati in formato testo, si deve impostare a “JJ” la variabile formatoDati
nel file di configurazione (configuration.ini).
Per utilizzare i tracciati in formato xml, si deve impostare a “XML-V1” la variabile
formatoDati nel file di configurazione (configuration.ini).
3.2 Funzionalità e tracciati per la versione 2 del client XML-SAIA
Per quanto riguarda la versione 2 dell’XML-SAIA, si mette a disposizione dei comuni la
possibilità di inviare le seguenti comunicazioni anagrafiche al sistema SAIA installato
presso il Centro Nazionale Servizi Demografici:
•
Comunicazione Anagrafica
Comunicazione di Nascita
Comunicazione di Immigrazione da altro comune
Comunicazione di Immigrazione dall’estero
Comunicazione di Iscrizione per mancata iscrizione in un altro comune
Comunicazione di Morte
Comunicazione di Emigrazione in altro comune
Comunicazione di Emigrazione all’estero
Comunicazione di Cancellazione per irreperibilità
Comunicazione per Cancellazione per omessa dichiarazione di dimora
abituale
Comunicazione di Cambio di abitazione
Comunicazione di Matrimonio
Comunicazione di Vedovanza
Comunicazione di Divorzio
Comunicazione di Annullamento Matrimonio
23/37
SAIA
Revisione 2.1.1
15/10/2006
Pag. 24 di 37
Comunicazione di Variazione di nome o cognome
Comunicazione di Variazione di sesso
Comunicazione di Variazione di cittadinanza
Comunicazione di Variazione di Permesso di Soggiorno
Comunicazione di Variazione di Paternità o Maternità
Comunicazione di Rettifica
Comunicazione di Annullamento di una Comunicazione Anagrafica
•
Stato delle code
•
Presa in carico
•
Consultazione
Le risposte previste per le comunicazioni sopraelencate sono:
•
•
•
•
•
Comunicazioni Anagrafiche
Documento Accettato
Documento Non Accettato
Stato delle Code
Presa in Carico
Consultazione
Errore
Il sistema, una volta configurato per inviare dati secondo il tracciato AP5, non potrà più
inviare dati nel tracciato piatto JJ, o XML-V1.
Le regole sulla struttura dei tracciati AP5 sono contenute nello schema di definizione
RichiestaSAIA.xsd, contenuto nell’allegato [AP5-XSD V2], reperibile presso il sito web
del CNSD .
Esempio:
<?xml version="1.0" encoding="UTF-8"?>
<richiestaSAIA
versione="1.0"
versioneXMLSAIA="1.0"
xsi:schemaLocation="http://saia.ancitel.it/xmlmanager/ap5
http://172.18.10.5/ap5/RichiestaSAIA.xsd
"
xmlns="http://saia.ancitel.it/xmlmanager/ap5"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<mittente>
<comuneDiComunicazione>
<nomeComune>Castel Gandolfo</nomeComune>
<codiceComuneIstat>058022</codiceComuneIstat>
<siglaProvinciaIstat>rm</siglaProvinciaIstat>
</comuneDiComunicazione>
<codiceFiscaleOperatore>CCCMZZ19C78E432A</codiceFiscaleOperatore>
</mittente>
<utente>
24/37
SAIA
Revisione 2.1.1
15/10/2006
Pag. 25 di 37
<login>xxx</login>
<password>xxx</password>
</utente>
<applicazioneAnagrafe>
<nome>nome</nome>
<versione>versione</versione>
<fornitore>fornitore</fornitore>
</applicazioneAnagrafe>
<richiesta versione="1.0">
<comunicazione
dataOraRichiesta="2006-03-01T16:22:49"
protocolloAnagrafe="00000000000000000321">
<causale>
<tipoComunicazione>variazione</tipoComunicazione>
<motivoComunicazione>1</motivoComunicazione>
<dataValidita>2006-01-01</dataValidita>
</causale>
<generalita>
<cognome>CAZODANI</cognome>
<nome>MANUELE</nome>
<luogoNascita>
<comune>
<nomeComune>Castel
Gandolfo</nomeComune>
</comune>
</luogoNascita>
<dataNascita>2006-03-01</dataNascita>
<sesso>M</sesso>
<cittadinanza>
<descrizioneStato>Italia</descrizioneStato>
<codiceStato>ITA</codiceStato>
</cittadinanza>
<statoCivile>1</statoCivile>
</generalita>
<iscrizioneAPR>
<motivoIscrizione>1</motivoIscrizione>
<dataIscrizioneAPR>2006-03-01</dataIscrizioneAPR>
<flagResidenteDallaNascita>S</flagResidenteDallaNascita>
</iscrizioneAPR>
<indirizzo>
<cap>93010</cap>
<comune>
25/37
SAIA
Revisione 2.1.1
15/10/2006
Pag. 26 di 37
</comune>
<toponimo>
<specie>via</specie>
<denominazione>CANNOLI</denominazione>
</toponimo>
<numeroCivico>
<numero>22</numero>
</numeroCivico>
</indirizzo>
</comunicazione>
<comunicazione
dataOraRichiesta="2006-03-01T16:22:49"
protocolloAnagrafe="00000000000000000321">
<causale>
<tipoComunicazione>variazione</tipoComunicazione>
<motivoComunicazione>1</motivoComunicazione>
<dataValidita>2006-01-01</dataValidita>
</causale>
<generalita>
<cognome>PELUSI</cognome>
<nome>GIUSEPPE</nome>
<luogoNascita>
<comune>
<nomeComune>Castel
Gandolfo</nomeComune>
</comune>
</luogoNascita>
<dataNascita>2006-03-01</dataNascita>
<sesso>M</sesso>
<cittadinanza>
<descrizioneStato>Italia</descrizioneStato>
<codiceStato>ITA</codiceStato>
</cittadinanza>
<statoCivile>1</statoCivile>
</generalita>
<iscrizioneAPR>
<motivoIscrizione>1</motivoIscrizione>
<dataIscrizioneAPR>2006-03-01</dataIscrizioneAPR>
<flagResidenteDallaNascita>S</flagResidenteDallaNascita>
</iscrizioneAPR>
<indirizzo>
<cap>93010</cap>
<comune>
26/37
SAIA
Revisione 2.1.1
15/10/2006
Pag. 27 di 37
</comune>
<toponimo>
<specie>via</specie>
<denominazione>TORO</denominazione>
</toponimo>
<numeroCivico>
<numero>33</numero>
</numeroCivico>
</indirizzo>
</comunicazione>
</richiesta>
</richiestaSAIA>
Le specifiche di produzione dei tracciati AP5 sono consultabili nel documento “INA-SAIA–
Allegato tecnico 2– Struttura Dati AP5” .
Le regole di validazione applicativa da seguire durante la compilazione di una richiesta da
inviare con la versione 2 del client XML-SAIA sono consultabili nel documento “INASAIA–Allegato tecnico 3–Schema di validazione applicativa”. Questi ultimi file sono
anch’essi disponibili sul sito della Direzione Centrale dei Servizi Demografici.
3.3 Funzionalità e tracciati per la versione 2.1.0.0 del client XMLSAIA
La versione 2.1.0.0 del client permette la gestione del modello APR4 per i trasferimenti di
residenza. Il trasferimento di residenza è iniziato dal comune di immigrazione che richiede
al comune di provenienza del cittadino la cancellazione di quest’ultimo dall’anagrafe. Per
effettuare la cancellazione il comune di immigrazione deve fornire dei dati del cittadino e
dei familiari coinvolti nel trasferimento di residenza sulla base del modello APR4. Il
comune di emigrazione, ricevuta la richiesta ed effettuati gli opportuni controlli, completa il
modello APR4 ricevuto e lo restituisce al comune di immigrazione. Le due operazioni di
invio e di completamento del modello avvengono attraverso i seguenti servizi forniti dal
server SAIA:
•
•
•
•
Invio modello APR4
Completamento modello APR4
Stato modello
Presa in carico
I servizi sono accessibili tramite richieste in formato XML trasmesse via HTTP. Le richieste
XML devono essere valide ovvero devono rispettare una grammatica formalizzata
attraverso alcuni file XML Schema illustrati di seguito nel paragrafo e devono superare i
controlli di validazione applicativa. Ad ogni richiesta valida segue una risposta sincrona
del SAIA secondo il seguente modello:
•
•
•
•
Risposta Comunicazione APR4 – modello accettato / modello non accettato
Risposta Comunicazione APR4 – modello accettato / modello non accettato
Risposta Stato modello
Risposta Presa in carico
27/37
SAIA
•
Revisione 2.1.1
15/10/2006
Pag. 28 di 37
Errore
In caso di richiesta di invio o completamento non valida viene restituita una risposta di
modello non accettato. Se la richiesta è mal formata il SAIA restituisce un messaggio di
errore. Le strutture dei messaggi scambiati tra il client e il server per le comunicazioni
APR4, richieste e risposte, insieme alle informazioni per la validazione applicativa sono
descritte nei documento riportati nella tabella seguente:
Struttura
APR4
Titolo
Dati
Comunicazioni
File
INA-SAIA
Struttura
Comunicazioni APR4. doc
Dati
Descrizione
Il
documento
fornisce
una
descrizione
generale
dei
messaggi e delle strutture dati
dettagliate nei documenti di
specifica insieme alle regole di
validazione applicativa
La versione 2.2.0.0 del client XML-SAIA permette lo scambio delle informazioni
anagrafiche tra i comuni. Il SAIA mette a disposizione dei comuni i messaggi per il
trasporto delle richieste di consultazione dal comune di origine al comune di destinazione
e delle risposte da quest’ultimo al primo. I messaggi sono definiti attraverso degli schema
XML. L’invio della richiesta e la ricezione della risposta attraverso il SAIA prevedono lo
scambio di messaggi tra i comuni coinvolti e il SAIA e tra il SAIA e l’INA. Il comune di
origine della richiesta invia un messaggio al SAIA contenente una o più consultazioni
riguardanti i cittadini di altri comuni. Il SAIA riceve la richiesta, verifica la validità delle
comunicazioni e restituisce una risposta di accettazione per ciascuna di queste. Se le
comunicazioni sono accettate, il SAIA restituisce nella risposta il numero di protocollo di
ciascuna comunicazione ricevuta per permette al comune di recuperare successivamente
la risposta del comune destinatario se disponibile. Se il comune di destinazione della
singola comunicazione non è fornito il SAIA richiede all’INA l’informazione utilizzando i dati
anagrafici del cittadino oggetto della consultazione. Un comune destinatario di una
comunicazione di consultazione può riceverne la notifica inviando al SAIA una richiesta di
stato code per il servizio di consultazione anagrafica. Successivamente può ottenere la
richiesta stessa con la funzione di presa in carico delle comunicazioni di consultazione
anagrafica. Una volta inoltrata la comunicazione al destinatario il SAIA aggiorna lo stato
della stessa da accettata a presa in carico. Il comune destinatario popola la risposta alla
richiesta di consultazione con i dati del cittadino, se disponibili, e invia i dati al SAIA
attraverso una richiesta contenente la comunicazione di risposta. Il SAIA, ricevuta la
comunicazione di risposta, aggiorna lo stato della consultazione da presa in carico a
completata. Il comune originario della richiesta può a questo punto ottenere la risposta
inviando una richiesta di presa in carico delle consultazioni anagrafiche. Prima ancora lo
stesso comune può verificare lo stato delle comunicazioni inviando una richiesta di stato
code per il servizio di consultazione anagrafica. Le richieste che possono essere inviate al
SAIA nell’ambito del servizio di consultazione anagrafica sono dunque:
•
Interrogazione Anagrafe del comune di origine al comune destinatario
28/37
SAIA
•
•
•
Revisione 2.1.1
15/10/2006
Pag. 29 di 37
Risposta Anagrafe del comune destinatario al comune di origine
Stato code delle comunicazioni di interrogazione e delle comunicazioni di risposta
Presa in carico delle comunicazioni di interrogazione e delle comunicazioni di
risposta
Ad ogni richiesta il SAIA risponde con una risposta sincrona
•
•
•
•
•
Risposta Interrogazione Anagrafe – richiesta accettata / richiesta non accettata
Risposta Anagrafe – richiesta accettata / richiesta non accettata
Risposta Stato comunicazioni di consultazione
Risposta Presa in carico comunicazioni di consultazione
Errore
In caso di richiesta di interrogazione o di risposta anagrafe non valida viene restituita una
risposta di comunicazione non accettata. Se la richiesta è mal formata il SAIA restituisce
un messaggio di errore. Le strutture dei messaggi scambiati tra il client e il server per le
consultazioni anagrafiche, richieste e risposte, insieme alle informazioni per la validazione
applicativa sono descritte nel documento riportato nella tabella seguente:
Titolo
Struttura
Dati
Anagrafica
Consultazione
File
INA-SAIA
Struttura
Dati
Consultazione Anagrafica.doc
Descrizione
Il
documento
fornisce
una
descrizione
generale
dei
La versione 2.3.0.0 del client XML-SAIA permette di allineare le anagrafi comunali con la
base dati INA. I comuni possono inviare attraverso il servizio di popolamento del SAIA i
dati anagrafici richiesti dall’INA riguardanti i propri cittadini residenti o emigrati all’estero o
deceduti. I popolamenti sono inviati al SAIA utilizzando i messaggi basati sul modello AP5.
I comuni, dopo aver inviato le comunicazioni contenenti i dati dei cittadini per i popolamenti
nella base dati INA, possono verificare lo stato dei popolamenti e prendere in carico gli
esiti dei popolamenti completati inviando al SAIA le richieste previste per il servizio:
•
•
•
Richiesta popolamento INA
Richiesta stato code
Richiesta presa in carico
Le richieste sono trasmesse via http in formato XML. Le richieste XML devono essere
valide ovvero devono rispettare una grammatica formalizzata con il linguaggio XML
Schema definita sulla base del modello AP5. Ad ogni richiesta valida segue una risposta
sincrona del SAIA secondo il seguente modello:
•
Risposta popolamento INA – modello accettato / modello non accettato
29/37
SAIA
•
•
•
Revisione 2.1.1
15/10/2006
Pag. 30 di 37
Risposta Stato modello
Risposta Presa in carico
Errore
In caso di richiesta di invio o completamento non valida viene restituita una risposta di
modello non accettato. Se la richiesta è mal formata il SAIA restituisce un messaggio di
errore. Le strutture dei messaggi scambiati tra il client e il server per il popolamento INA,
richieste e risposte, insieme alle informazioni per la validazione applicativa sono descritte
nei documenti riportati nella tabella seguente:
Titolo
Struttura Dati Popolamento INA
File
INA-SAIA
Struttura
Popolamento INA.doc
Dati
Descrizione
Il
documento
fornisce
una
descrizione
generale
dei
specifica indicati nei riferimenti
La versione 2.4.0.0 del client XML-SAIA permette agli Enti di richiedere informazioni
anagrafiche ai Comuni. Il SAIA mette a disposizione degli Enti i messaggi per il trasporto
delle richieste di consultazione. I messaggi sono definiti attraverso schema XML. Questa
funzionalità non differisce molto, nella struttura dei messaggi, rispetto alla funzionalità
implementata per le consultazioni anagrafiche tra Comuni descritta nel paragrafo
precedente. La maggiore differenza consiste nel fatto che gli Enti accedono al servizio
tramite web services e solo i Comuni destinatari delle richieste di consultazione
anagrafiche utilizzano il client XML-SAIA. L’Ente che richiede la consultazione anagrafica
invia la richiesta attraverso un web service del SAIA contenente una o più consultazioni
riguardanti i cittadini di uno o più Comuni. Il SAIA riceve la richiesta, verifica la validità
delle comunicazioni e restituisce una risposta di accettazione per ciascuna di queste. Se le
comunicazioni sono accettate, il SAIA restituisce nella risposta il numero di protocollo di
ciascuna comunicazione ricevuta per permette all’Ente di recuperare successivamente la
risposta del Comune destinatario se disponibile. Se il Comune di destinazione della
singola comunicazione non è fornito il SAIA richiede all’INA l’informazione utilizzando i dati
anagrafici del cittadino oggetto della consultazione. Un comune destinatario di una
comunicazione di consultazione può riceverne la notifica inviando al SAIA una richiesta di
stato code per il servizio di consultazione anagrafica. Successivamente può ottenere la
richiesta stessa con la funzione di presa in carico delle comunicazioni di consultazione
anagrafica. Una volta inoltrata la comunicazione al destinatario il SAIA aggiorna lo stato
della stessa da accettata a presa in carico. Il Comune destinatario popola la risposta alla
richiesta di consultazione con i dati del cittadino, se disponibili, e invia i dati al SAIA
attraverso una richiesta contenente la comunicazione di risposta. Il SAIA, ricevuta la
comunicazione di risposta, aggiorna lo stato della consultazione da presa in carico a
completata. L’Ente può a questo punto ottenere la risposta utilizzando un web service per
la presa in carico delle consultazioni anagrafiche. L’Ente può verificare lo stato delle
comunicazioni utilizzando un altro web service per la richiesta di stato code. In caso di
richiesta di interrogazione o di risposta anagrafe non valida per formato errato o a causa di
informazioni mancanti il SAIA restituisce una risposta di comunicazione non accettata. Le
30/37
SAIA
Revisione 2.1.1
15/10/2006
Pag. 31 di 37
strutture dei messaggi scambiati per le consultazioni anagrafiche da Ente a Comune,
richieste e risposte, insieme alle informazioni per la validazione applicativa sono descritte
nel documento riportato nella tabella seguente:
Titolo
Struttura
Dati
Anagrafica
Consultazione
File
INA-SAIA
Struttura
Dati
Consultazione Anagrafica.doc
Descrizione
Il
documento
fornisce
una
descrizione
generale
dei
La versione 2.5.0.0 del client XML-SAIA permette ai Comuni di gestire le anomalie
prodotte in seguito ad una richiesta di variazione anagrafica, in modalità automatica per
alcuni casi limitati. Le anomalie gestite dal SAIA riguardano:
1) date della residenza di un cittadino dichiarate da due Comuni contradditorie
2) dati anagrafici diversi da quelli già registrati in INA forniti dallo stesso Comune o da un
Comune diverso
Un Comune riceve la notifica della presenza di un anomalia attraverso una richiesta di
presa in carico e attraverso un servizio di notifica per posta elettronica indirizzato ad un
utente del Comune registrato sul SAIA. Il Responsabile dell’Anagrafe Comunale invia una
comunicazione per ciascuna anomalia pendente del tipo descritto precedentemente.
•
•
•
conferma i dati forniti durante la variazione anagrafica
annulla la variazione anagrafica
rettifica la variazione anagrafica fornendo nuovamente i dati anagrafici
Il SAIA riceve le comunicazioni e dopo la validazione dei messaggi restituisce una risposta
con l’esito della validazione.
Se il Comune che ha originato l'anomalia sull'INA conferma i dati, il SAIA inoltra la notifica
dell'anomalia al Comune che ha fornito i dati in possesso dell'INA. Quest'ultimo Comune
può a sua volta inviare una comunicazione per:
•
•
confermare i dati anagrafici forniti all'INA
modificare i dati
Il trattamento automatico di un'anomalia riguardante i dati anagrafici o la data di residenza
di un cittadino di un Comune può essere interrotta da un operatore del Call Centre in
qualsiasi momento, in seguito ad una richiesta di intervento del Comune che ha generato
l'anomalia o di un Comune coinvolto. Le strutture dei messaggi scambiati per la gestione
31/37
SAIA
Revisione 2.1.1
15/10/2006
Pag. 32 di 37
delle anomalie, richieste e risposte, insieme alle informazioni per la validazione applicativa
sono descritte nel documento riportato nella tabella seguente:
Titolo
Struttura Dati Gestione Anomalie
File
INA-SAIA Struttura Dati Gestione
Anomalie.doc
Descrizione
Il
documento
fornisce
una
descrizione
generale
dei
32/37
SAIA
Revisione 2.1.1
15/10/2006
Pag. 33 di 37
4 PREDISPOSIZIONE DEL FILE DI INPUT E LETTURA DEL FILE DI
OUTPUT
Per l’invio delle comunicazioni con l’uso di XML-SAIA è necessario predisporre il file
contenente i tracciati delle comunicazioni da inviare nella directory specificata nel file di
configurazione configuration.ini con il valore dell’attributo inputFile.
I risultati dell’invio delle configurazioni saranno contenuti in un file delle risposte generato
automaticamente dal client XML-SAIA alla fine del processo di invio, tale file sarà
reperibile nella posizione specificata nel file configuration.ini per l’attributo outputFile.
Per utilizzare i tracciati in formato testo, si deve impostare a “JJ” la variabile formatoDati
nel file di configurazione (configuration.ini).
Per utilizzare i tracciati in formato xml, si deve impostare a “XML-V1” la variabile
formatoDati nel file di configurazione (configuration.ini).
Per attivare la possibilità di impiegare file XML nel tracciato AP5 è necessario richiedere
l’abilitazione tramite l’assistenza tecnica.
33/37
SAIA
Revisione 2.1.1
15/10/2006
Pag. 34 di 37
5 JAVA RUNTIME ENVIRONMENT (JRE)
5.1 Installazione JRE
Il JRE, per le piattaforme Windows/GNU/Linux, è prelevabile gratuitamente dal sito Web
della Sun Microsystem.
Per spiegare come installare il software JRE, in questo documento è stata usata l’ultima
versione disponibile al momento della stesura: la 1.4.2_09. Comunque qualunque JRE
appartenente alla serie 1.4.* andrà bene al corretto funzionamento dell’applicazione XMLSAIA.
5.2 Installazione JRE su piattaforma Windows
Dopo aver prelevato il software necessario, lanciamo l’installazione facendo doppio click
sul file appena scaricato, in questo esempio il pacchetto :
j2re-1_4_2_09-windows-i586-p.exe.
Si inizia così con la procedura d’installazione guidata, che dopo pochi secondi
presenta una schermata come quella di Figura 4.2-1, per l’accettazione del contratto di
licenza d’uso.
Figura 5.2-1 – Inizio della procedura di installazione guidata
Dopo aver letto il contratto, se s’intende accettarlo fare click sul pulsante Si.
Se non si accetta il contratto, non è possibile installare il JRE.
34/37
SAIA
Revisione 2.1.1
15/10/2006
Pag. 35 di 37
In seguito è richiesto con quale tipologia d’installazione procedere:
Tipica (consigliata)
Personalizzata (utente esperto)
(Vedi Figura 4.2-2).
Figura 5.2-2 – Scelta il tipo di installazione
L’ultima schermata (Figura 4.2-3), indica la fine del processo di installazione del JRE.
Figura 5.2-3 – Fine dell’installazione
35/37
SAIA
Revisione 2.1.1
15/10/2006
Pag. 36 di 37
5.3 Installazione JRE su piattaforma GNU/Linux
Per installare il software JRE su un sistema GNU/Linux generico, è necessario aprire un
terminale (può essere utile anche un terminale grafico per esempio xterm), e spostarsi
dentro la cartella in cui il sistema ha “montato” il lettore ottico CD/DVD, per esempio
“/mnt/cdrom” su Linux Red Hat o “/cdrom” su Debian:
bash# cd /mnt/cdrom
Copiare il file autoscompattante j2re-1_4_2_09-linux-i586.bin nella cartella in cui si vuole
installare il software JRE, e spostarsi in tale cartella.
bash# cp j2re-1_4_2_09-linux-i586.bin <cartella d’installazione>
Spostarsi nella cartella in cui è stato copiato il file autoscompattante e digitare il seguente
comando: ./j2re-1_4_2_09-linux-i586.bin, attenersi alle istruzione che verranno generate a
video dal comando appena lanciato.
E’ necessario accettare la licenza dettata dalla Sun Microsystems
Al termine del processo di installazione, nella stessa cartella di destinazione
dell’autoscompattante sarà presente un’ulteriore cartella, j2re-1_4_2_09, che costituisce la
cartella di installazione del software JRE.
Per rendere noto al sistema la presenza del software appena installato, è necessario
aggiornare la variabile d’ambiente PATH, perché includa la cartella di installare del JRE.
Quindi:
Editare il file /etc/profile, con un edito qualsiasi, messo a disposizione dal sistema, per
esempio vi:
bash# vi /etc/profile
All’interno del file appena editato è già presente la dichiarazione della variabile PATH, per
esempio:
PATH=“/bin:/sbin:/usr/bin:/usr/sbin/:/usr/X11R6/bin”
Digitare “i” e spostarsi con i tasti freccia, subito sotto la dichiarazione della variabile
appena descritta.
Supponendo che la cartella di installazione del JRE, si trovi dentro la cartella /opt, scrivere:
PATH=”$PATH:/opt/j2re-1_4_2_09/bin”
Digitare il testo di escare <esc>, digitare in ordine la sequenza “:wq!” e digitare il tasto
<return> per salvare le modifiche apportate e uscire dall’editor vi.
36/37
SAIA
Revisione 2.1.1
15/10/2006
Pag. 37 di 37
A questo punto è necessario aggiornare le variabili d’ambiente del terminale usato fino a
questo momento, quindi sarà necessario digitare il seguente comando:
bash# source /etc/profile.
37/37

MANUALE UTENTE XML-SAIA

Transcript

Documenti analoghi

Progettazione del Software Analisi Diagramma delle Attività

course programme - Ordine Avvocati Milano

Istruzioni per installazione HOD

LTSP - RELug

affidamento alla ditta per fornitura abbigliamento anno 2012

Saia PCD® Web Panel CE PCD7.D51xxTL010 Pannello di controllo in

Implementare client e server UDP in grado di realizzare un classico

CONFIGURAZIONE ACCOUNT DI POSTA ELETTRONICA entecra

Per assumere il controllo del dominio client rapidamente grazie a