ATTO INTEGRATIVO II
ACCORDO DI PROGRAMMA QUADRO (APQ) IN MATERIA DI SOCIETÀ DELL’INFORMAZIONE
ATTO INTEGRATIVO II
Procedura aperta sottosoglia comunitaria per la fornitura di un sistema informatico in modalità ASP di gestione degli Atti Amministrativi dei Comuni
Allegato D al capitolato tecnico
Specifiche dei Web Services per gli Atti Amministrativi
Xxx Xxxxxx, xxx - 00000 XXXXXXXX - XX tel. 000.0000000 - fax 000.0000000
Sommario
1.Premessa 3
2.Macroaree 4
3.Specifiche generali 5
3.1.Codifica 5
3.2.Struttura dell'xml 5
3.3.Tipologia di dati 6
3.4.Suddivisione dei web services 7
3.5.Protocollo di comunicazione 7
3.5.1.Chiamata tipo ad un Web Service 7
3.5.2.Risposta tipo di un Web Service 10
3.6.Autenticazione e riservatezza dei dati 11
4.Specifiche Web Services e metodi 12
4.1.Macroarea atti amministrativi 12
4.1.1.AA_Indice_Completo 12
4.1.2.AA_Delibere 13
5.Testing 16
SIAI202-COMUNAS – Sistema in ASP per Atti Amministrativi Allegato D al capitolato tecnico
1.Premessa
Il presente documento costituisce parte dell’Allegato Tecnico richiamato dall’Avviso Pubblico, pubblicato in data 10 Maggio 2007, per la qualificazione delle imprese verso la piattaforma Comunas e definisce le specifiche tecniche per i web services necessari a interfacciare i software di back-office, per l'area atti amministrativi, utilizzati presso le pubbliche amministrazioni comunali con i servizi del progetto Comunas.
2.Macroaree
I web services per l'avviso pubblico, pubblicato in data 10 Maggio 2007, sono relativi alle macroaree e ai servizi sotto indicati :
- Servizi demografici: movimenti demografici, prenotazione certificati, dichiarazioni
- Servizi tributari: visura situazioni storiche tributarie, ruoli, denunce, variazioni, calcolo presuntivo di TARSU, ICI, TOSAP
- Servizi finanziari: visura fatture emesse e movimenti per rapporti di fornitura
- Atti amministrativi: albi di pubblicazione di delibere, appalti, concorsi
- Polizia municipale: visione delle contravvenzioni
- Ufficio tecnico: visione iter concessioni/autorizzazioni per l'edilizia privata
Macroarea | Servizio |
Servizi demografici | Anagrafe |
Stato Civile | |
Servizi tributari | ICI |
TARSU | |
TOSAP | |
Servizi finanziari | Visura fatture emesse |
Movimenti per rapporti di fornitura | |
Atti amministrativi | Gestione Deliberazioni |
Gestione Determinazioni | |
Polizia municipale | Visualizzazione contravvenzioni |
Ufficio tecnico | Autorizzazioni e concessioni |
Il presente documento riporta solo la descrizione dei web services per l'area Atti Amministrativi.
3.Specifiche generali
3.1.Codifica
La codifica utilizzata sarà UTF-8.
I nomi da attribuire ai web services e ai metodi seguiranno la seguente codifica:
- Un prefisso di due lettere che indica il nome della macroarea a cui appartiene il web service secondo la seguente convenzione:
- AA: Atti amministrativi
- Un nome parlante che indica la funzionalità del web service.
3.2.Struttura dell'xml
I web service dovranno restituire un dato di tipo stringa che conterrà i dati incapsulati all'interno di un xml, che rispetti la seguente convenzione:
- Un nodo radice <comunas-data>
- Un nodo <list> che includerà la lista di uno o più oggetti (items)
- Uno o più nodi <item> che rappresentano un singolo oggetto e che includono uno o più proprietà (element).
- Uno o piu nodi <element> che rappresentano le proprietà di un oggetto, essi contengono le unità informative, rappresentare dagli attributi key e value, che rappresentano rispettivamente il nome della proprietà ed il valore della proprietà stessa.
- Uno o più nodi <file> che contengono dei file allegati portati sul formato base64. Nell' attributo key viene passato il nome della proprietà.
L'xml avrà quindi una struttura descritta dallo schema:
<?xml version="1.0" encoding="utf-8"?>
<xs:schema xmlns:ts="xxxx://xxx.xxxxxxx.xx/xxxxxxx/XXXxxx" targetNamespace="xxxx://xxx.xxxxxxx.xx/xxxxxxx/XXXxxx" xmlns:xs="xxxx://xxx.x0.xxx/0000/XXXXxxxxx">
<xs:element name="comunas-data">
<xs:complexType>
<xs:sequence>
<xs:element minOccurs="1" name="list">
<xs:complexType>
<xs:sequence>
<xs:element minOccurs="0" maxOccurs="unbounded" name="item">
<xs:complexType>
<xs:sequence>
<xs:element minOccurs="0" name="file">
<xs:complexType>
<xs:simpleContent>
<xs:extension base="xs:base64Binary">
<xs:attribute name="key" type="xs:string" use="required" />
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
<xs:element minOccurs="0" maxOccurs="unbounded" name="element">
<xs:complexType>
<xs:attribute name="key" type="xs:string" use="required" />
<xs:attribute name="value" type="xs:string" use="required" />
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
<xs:attribute name="version" type="xs:string" use="optional" />
</xs:complexType>
</xs:element>
</xs:schema>
3.3.Tipologia di dati
I dati contenuti all'interno dell'attributo “value” devono necessariamente appartenere ad uno dei seguenti tipi primitivi:
- stringa
- intero: intero a 32 bit
- data: data nel formato “gg-mm-aaaa” (es. <element key=”data_nascita” value=”20-02-1985”>)
- ora: ora nel formato: “hh:mm” (es. <element key=”ora_infrazione” value=”10:55”>)
- double: numero a 64 bit con precisione a virgola mobile (es. <element key=”importo_totale” value=”156,23”>).
3.4.Suddivisione dei web services
I web services, per ogni area, possono essere divisi in due categorie:
- web services di indicizzazione
- web services del portale
I web services di indicizzazione vengono utilizzati per popolare delle tabelle di indice sul database del portale. Queste verranno utilizzate dal portale per sapere da quali comuni richiedere i dati dei vari cittadini che si connettono al servizio. Le operazioni di indicizzazione vengono schedulate giornalmente durante la notte.
I web services del portale invece, vengono utilizzati per la visualizzazione dei dati sulle pagine richieste dai cittadini-utenti del portale.
3.5.Protocollo di comunicazione
Il protocollo di comunicazione prevede la necessità di invocare uno o più web service per ogni macroarea tramite l'utilizzo di protocollo soap.
Di seguito vengono presentate le specifiche tecniche riguardanti i web-service che permettono l’integrazione tra l’application server e la presentation, costituita dal portale.
3.5.1.Chiamata tipo ad un Web Service
Per contattare un web-service è sufficiente eseguire una richiesta in protocollo soap specificando nel tag body i parametri di ingresso del metodo. A titolo di esempio viene riportata la descrizione (WSDL) del web service AA_Indice_Completo :
<?xml version="1.0" encoding="utf-8"?>
<wsdl:definitions xmlns:soap="xxxx://xxxxxxx.xxxxxxx.xxx/xxxx/xxxx/" xmlns:tm="xxxx://xxxxxxxxx.xxx/xxxx/xxxx/xxxxXxxxxxxx/" xmlns:soapenc="xxxx://xxxxxxx.xxxxxxx.xxx/xxxx/xxxxxxxx/" xmlns:mime="xxxx://xxxxxxx.xxxxxxx.xxx/xxxx/xxxx/" xmlns:tns="xxxx://xxx.xxxxxxx.xx/XX_Xxxxxxxx/XX_Xxxxxx_Xxxxxxxx" xmlns:s="xxxx://xxx.x0.xxx/0000/XXXXxxxxx" xmlns:soap12="xxxx://xxxxxxx.xxxxxxx.xxx/xxxx/xxxx00/" xmlns:http="xxxx://xxxxxxx.xxxxxxx.xxx/xxxx/xxxx/" targetNamespace="xxxx://xxx.xxxxxxx.xx/XX_Xxxxxxxx/XX_Xxxxxx_Xxxxxxxx" xmlns:wsdl="xxxx://xxxxxxx.xxxxxxx.xxx/xxxx/">
<wsdl:types>
<s:schema elementFormDefault="qualified" targetNamespace="xxxx://xxx.xxxxxxx.xx/XX_Xxxxxxxx/XX_Xxxxxx_Xxxxxxxx">
<s:element name="AA_GetListaSedute">
<s:complexType />
</s:element>
<s:element name="AA_GetListaSeduteResponse">
<s:complexType>
<s:sequence>
<s:element minOccurs="0" maxOccurs="1" name="AA_GetListaSeduteResult" type="s:string" />
</s:sequence>
</s:complexType>
</s:element>
<s:element name="AA_GetListaDelibere">
<s:complexType />
</s:element>
<s:element name="AA_GetListaDelibereResponse">
<s:complexType>
<s:sequence>
<s:element minOccurs="0" maxOccurs="1" name="AA_GetListaDelibereResult" type="s:string" />
</s:sequence>
</s:complexType>
</s:element>
<s:element name="AA_GetFileDelibera">
<s:complexType />
</s:element>
<s:element name="AA_GetFileDeliberaResponse">
<s:complexType>
<s:sequence>
<s:element minOccurs="0" maxOccurs="1" name="AA_GetFileDeliberaResult" type="s:string" />
</s:sequence>
</s:complexType>
</s:element>
</s:schema>
</wsdl:types>
<wsdl:message name="AA_GetListaSeduteSoapIn">
<wsdl:part name="parameters" element="tns:AA_GetListaSedute" />
</wsdl:message>
<wsdl:message name="AA_GetListaSeduteSoapOut">
<wsdl:part name="parameters" element="tns:AA_GetListaSeduteResponse" />
</wsdl:message>
<wsdl:message name="AA_GetListaDelibereSoapIn">
<wsdl:part name="parameters" element="tns:AA_GetListaDelibere" />
</wsdl:message>
<wsdl:message name="AA_GetListaDelibereSoapOut">
<wsdl:part name="parameters" element="tns:AA_GetListaDelibereResponse" />
</wsdl:message>
<wsdl:message name="AA_GetFileDeliberaSoapIn">
<wsdl:part name="parameters" element="tns:AA_GetFileDelibera" />
</wsdl:message>
<wsdl:message name="AA_GetFileDeliberaSoapOut">
<wsdl:part name="parameters" element="tns:AA_GetFileDeliberaResponse" />
</wsdl:message>
<wsdl:portType name="AA_Indice_CompletoSoap">
<wsdl:operation name="AA_GetListaSedute">
<wsdl:input message="tns:AA_GetListaSeduteSoapIn" />
<wsdl:output message="tns:AA_GetListaSeduteSoapOut" />
</wsdl:operation>
<wsdl:operation name="AA_GetListaDelibere">
<wsdl:input message="tns:AA_GetListaDelibereSoapIn" />
<wsdl:output message="tns:AA_GetListaDelibereSoapOut" />
</wsdl:operation>
<wsdl:operation name="AA_GetFileDelibera">
<wsdl:input message="tns:AA_GetFileDeliberaSoapIn" />
<wsdl:output message="tns:AA_GetFileDeliberaSoapOut" />
</wsdl:operation>
</wsdl:portType>
<wsdl:binding name="AA_Indice_CompletoSoap" type="tns:AA_Indice_CompletoSoap">
<soap:binding transport="xxxx://xxxxxxx.xxxxxxx.xxx/xxxx/xxxx" />
<wsdl:operation name="AA_GetListaSedute">
<soap:operation soapAction="xxxx://xxx.xxxxxxx.xx/XX_Xxxxxxxx/XX_Xxxxxx_Xxxxxxxx/XX_XxxXxxxxXxxxxx" style="document" />
<wsdl:input>
<soap:body use="literal" />
</wsdl:input>
<wsdl:output>
<soap:body use="literal" />
</wsdl:output>
</wsdl:operation>
<wsdl:operation name="AA_GetListaDelibere">
<soap:operation soapAction="xxxx://xxx.xxxxxxx.xx/XX_Xxxxxxxx/XX_Xxxxxx_Xxxxxxxx/XX_XxxXxxxxXxxxxxxx" style="document" />
<wsdl:input>
<soap:body use="literal" />
</wsdl:input>
<wsdl:output>
<soap:body use="literal" />
</wsdl:output>
</wsdl:operation>
<wsdl:operation name="AA_GetFileDelibera">
<soap:operation soapAction="xxxx://xxx.xxxxxxx.xx/XX_Xxxxxxxx/XX_Xxxxxx_Xxxxxxxx/XX_XxxXxxxXxxxxxxx" style="document" />
<wsdl:input>
<soap:body use="literal" />
</wsdl:input>
<wsdl:output>
<soap:body use="literal" />
</wsdl:output>
</wsdl:operation>
</wsdl:binding>
<wsdl:service name="AA_Indice_Completo">
<wsdl:port name="AA_Indice_CompletoSoap" binding="tns:AA_Indice_CompletoSoap">
<soap:address location="xxxx://xxxxxxx0:00/xxxxxxx_xx/xxxx_xxxxxxxxxxxxxx/XX_Xxxxxx_Xxxxxxxx.xxxx" />
</wsdl:port>
</wsdl:service>
</wsdl:definitions>
Questa invece sarà la chiamata da parte del servizio di indicizzazione di comunas ad un metodo del web-service AA_Indice_Completo che restituisce la lista presente all'anagrafe.
POST xxxx://xxxxxxx0:00/xxxxxxx_xx/xxxx_xxxxxxxxxxxxxx/XX_Xxxxxx_Xxxxxxxx.xxxx HTTP/1.1 SOAPAction: "xxxx://xxx.xxxxxxx.xx/XX_Xxxxxxxx/XX_Xxxxxx_Xxxxxxxx/XX_XxxXxxxxXxxxxxxx" User-Agent: Axis2
Host: localhost:8081
X-Transfer-Encoding: chunked Content-Type: text/xml; charset=UTF-8
Authorization: Basic Y29tdW5ldXNlcjpjb211bmVwYXNz Content-length: 272
<?xml version='1.0' encoding='UTF-8'?>
<soapenv:Envelope xmlns:soapenv="xxxx://xxxxxxx.xxxxxxx.xxx/xxxx/xxxxxxxx/">
<soapenv:Header />
<soapenv:Body>
<ns1:AA_GetListaDelibere xmlns:ns1="xxxx://xxx.xxxxxxx.xx/XX_Xxxxxxxx/XX_Xxxxxx_Xxxxxxxx" />
</soapenv:Body>
</soapenv:Envelope>
3.5.2.Risposta tipo di un Web Service
Per coerenza con la richiesta, descriviamo di seguito il formato della risposta, successivamente il risultato dello specifico web service realmente invocato.
HTTP/1.1 200 OK
Date: Wed, 06 Aug 2008 14:18:48 GMT
Server: Microsoft-IIS/6.0 X-Powered-By: XXX.XXX
X-AspNet-Version: 2.0.50727 Cache-Control: private, max-age=0
Content-Type: text/xml; charset=utf-8 Content-length: 1548
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="xxxx://xxxxxxx.xxxxxxx.xxx/xxxx/xxxxxxxx/" xmlns:xsi="xxxx://xxx.x0.xxx/0000/XXXXxxxxx- instance" xmlns:xsd="xxxx://xxx.x0.xxx/0000/XXXXxxxxx">
<soap:Body>
<AA_GetListaDelibereResponse xmlns="xxxx://xxx.xxxxxxx.xx/XX_Xxxxxxxx/XX_Xxxxxx_Xxxxxxxx">
<AA_GetListaDelibereResult>XML CON DATI</AA_GetListaDelibereResult>
</AA_GetListaDelibereResponse>
</soap:Body>
</soap:Envelope>
Il web-service risponderà alle richieste con un dato di tipo stringa che conterrà l’XML sopra descritto. Di seguito si riporta l'esempio di risposta del metodo AA_GetListaDelibere:
<si:comunas-data version="1" xmlns:si="xxxx://xxx.xxxxxxx.xx/xxxxxxx/XXXxxx" >
<list>
</list>
</si:comunas-data>
<item>
</item>
<item>
</item>
<element key="codice_delibera" value="5472" />
<element key="codice_seduta" value="234123" />
<element key="data_inizio_pubblicazione" value="15-01-2007" />
<element key="data_fine_pubblicazione" value="30-01-2007" />
<element key="oggetto" value="Oggetto ancora da valutare" />
<element key="numero_delibera" value="547839" />
<element key="importo_delibera" value="221,85" />
<element key="data_esecutivo" value="01-02-2007" />
<element key="codice_delibera" value="5478" />
<element key="codice_seduta" value="284123" />
<element key="data_inizio_pubblicazione" value="10-07-2007" />
<element key="data_fine_pubblicazione" value="25-07-2007" />
<element key="oggetto" value="questo e un oggetto di esempio" />
<element key="numero_delibera" value="489123" />
<element key="importo_delibera" value="521,70" />
<element key="data_esecutivo" value="02-08-2006" />
3.6.Autenticazione e riservatezza dei dati
I web services esposti dovranno richiedere un autenticazione di tipo “basic access authentication”.
La riservatezza delle credenziali di accesso sarà garantita dal protocollo https. Per questo motivo i server dei comuni dovranno essere dotati di certificati in corso di validità e firmati da Certification authority esistenti.
4.Specifiche Web Services e metodi
4.1.Macroarea atti amministrativi
I web service da realizzare per gli atti amministrativi sono: AA_Indice_Completo
AA_Delibere
I metodi compresi da questo web service di indicizzazione sono:
AA_GetListaSedute
Descrizione : restituisce la lista delle sedute comunali
Parametri di ingresso : nessuno
Parametri presenti sull'XML in uscita:
Nome campo | Tipo campo | Descrizione |
codice_seduta | stringa | codice identificativo seduta |
tipologia | intero | tipologia seduta (1=Consiglio comunale, 2=Giunta comunale, 3=Commissario prefettizio) |
data | data | data in cui si è tenuta la seduta |
AA_GetListaDelibere
Descrizione : restituisce la lista delle delibere comunali
Parametri di ingresso : nessuno
Parametri presenti sull'XML in uscita:
Nome campo | Tipo campo | Descrizione |
codice_delibera | stringa | identificativo delibera |
codice_seduta | stringa | identificativo seduta |
data_inizio_pubblicazione | data | data inizio pubblicazione albo pretorio |
data_fine_pubblicazione | data | data fine pubblicazione albo pretorio |
oggetto | stringa | oggetto della delibera |
numero_delibera | stringa | numero della delibera |
importo_delibera | double | importo della delibera |
data_esecutivo | data | data esecutività |
AA_GetFileDelibera
Descrizione : restituisce un file con il testo della delibera comunale.
Parametri di ingresso :
Nome campo | Tipo campo | Descrizione |
codice_delibera | stringa | Codice della delibera |
Parametri presenti sull'XML in uscita:
Nome campo | Tipo campo | Descrizione |
file_delibera | file in formato base64 | file contenente il file pdf della delibera |
I metodi compresi da questo web service sono:
AA_GetListaDelibere
Descrizione : restituisce tutte le delibere che rispondono ai valori passati in ingresso come filtro (i campi passati vuoti non vengono applicati al filtro).
Parametri di ingresso :
Nome campo | Tipo campo | Descrizione |
oggetto | stringa | oggetto della delibera |
numero_delibera | stringa | numero della delibera |
data_inizio_filtro | data | data di inizio filtro (per data di seduta) |
data_fine_filtro | data | data fine filtro (per data di seduta) |
tipo_seduta | intero | tipo seduta (1=consiglio , 2=giunta comunale , 3=commissario) |
Parametri presenti sull'XML in uscita:
Nome campo | Tipo campo | Descrizione |
importo_delibera | double | importo della delibera |
Nome campo | Tipo campo | Descrizione |
oggetto | stringa | oggetto della delibera |
data_inizio_pubblicazione | data | data di inizio della pubblicazione |
data_fine_pubblicazione | data | data fine pubblicazione |
data_esecutivo | data | data esecutività della delibera |
codice_file_delibera | stringa | codice di riferimento al file della delibera |
data_seduta | data | data della seduta |
descrizione_tipo_seduta | stringa | descrizione del tipo della seduta (“Consiglio”, “Giunta”, “Commissario”, “Nessuna”) |
AA_GetDeliberaDettaglio
Descrizione : dato il codice identificativo della delibera, restituisce il dettaglio della stessa.
Parametri di ingresso :
Nome campo | Tipo campo | Descrizione |
codice_delibera | stringa | Codice della delibera |
Parametri presenti sull'XML in uscita:
Nome campo | Tipo campo | Descrizione |
importo_delibera | double | importo della delibera |
oggetto | stringa | oggetto della delibera |
data_inizio_pubblicazione | data | data di inizio della pubblicazione |
data_fine_pubblicazione | data | data fine pubblicazione |
data_esecutivo | data | data esecutività della delibera |
codice_file_delibera | stringa | codice di riferimento al file della delibera |
data_seduta | data | data della seduta |
descrizione_tipo_seduta | stringa | descrizione del tipo della seduta (“Consiglio”, “Giunta”, “Commissario”, “Nessuna”) |
AA_GetSedutaDettaglio
Descrizione : dato il codice della seduta e l'anno in cui è avvenuta, restituisce il dettaglio della stessa.
Parametri di ingresso :
Nome campo | Tipo campo | Descrizione |
codice_seduta | stringa | Codice identificativo della seduta |
anno_seduta | intero | anno della seduta |
Parametri presenti sull'XML in uscita:
Nome campo | Tipo campo | Descrizione |
descrizione_tipo_seduta | stringa | descrizione del tipo della seduta (“Consiglio”, “Giunta”, “Commissario”, “Nessuna”) |
data_seduta | data | data in cui si è svolta la seduta |
5.Testing
Per portare a termine l'iter di validazione, i web service realizzati dovranno superare alcuni test. Per effettuarli l'azienda richiedente dovrà predisporre una piattaforma funzionante con la propria applicazione installata e fornire i dati di accesso ai web service.
I test si divideranno in due categorie:
- controllo formale dei dati
- controllo basato sugli standard WS-I (xxxx://xxx.xx-x.xxx)
Per quanto riguarda i controlli formali sui dati, verranno testati tutti i metodi presenti nei web service e verificati singolarmente tutti i dati restituiti in uscita. I controlli riguarderanno:
- il tipo dei dati (stringa, intero, data, booleano)
- il formato dei dati (es. formato della data)
- il range dei dati (dimensione massima per tipo)
Inoltre ci saranno controlli sul comportamento dei web service in casi limite; ovvero verranno passati in ingresso valori ai limiti o esterni al range del dato specifico. Per questi test verranno utilizzati dei tool automatici che verranno distribuiti sul sito xxxx://xxxxxxxxx.xxxxxxx.xx/xxxxxxxxxxxxxx_xxxxxxx .
Il controllo basato sugli standard WS-I invece, andrà a verificare che i web service sviluppati rispettino le specifiche dettate dal WS-I (xxxx://xxx.xx-x.xxx/Xxxxxxxx/XxxxxXxxxxxx-0.0.xxxx). Per questo test verrà utilizzato il software direttamente sviluppato dall'organizzazione scaricabile da xxxx://xxx.xx- x.xxx/xxxxxxxxxxxx/xxxxxxxxxxxx.xxxx?xxxxxxxxxxxxxxx