e.Toscana Compliance 
Request for Comments: 70 rev 6
Del: 7/1/2008
Categoria: Infrastrutturale
Destinatari: Servizi applicativi che devono trasmettere al centro servizi CART informazioni statistiche relative all'utilizzo dell'infrastruttura di cooperazione applicativa.


Servizio di Aggregazione Statistiche CART
	

Indice
======
1. Contesto di riferimento
2. Obiettivi
3. Analisi
4. Prodotti Attesi
5. Bibliografia
6. Note


1. Contesto di riferimento
==========================
L'architettura del CART prevede tre tipi di flussi di comunicazione:

a. comunicazioni fra le PdD dei NAL che utilizzano la PdD del CentroServiziCART come router
b. comunicazioni fra le PDD dei NAL che utilizzano il servizio di Gestore Eventi come Broker JMS
c. comunicazioni fra servizi applicativi che utilizzano in modo nativo il Broker JMS senza passare dalle PdD dei NAL

Nel caso a) tutte le tracce relative alle comunicazioni sono disponibili nel database di tracciamento della PdD del CentroServiziCART e vengono automaticamente aggregate dal sistema di reportistica del CART.

Lo scopo del servizio  di rendere disponibili informazioni analoghe per il sistema di statistiche anche nei casi b) e c) che attualmente non sono gestiti.


2. Obiettivi
============
Il servizio InviaStatisticheCART consente di inviare al sistema di reportistica del CART informazioni statistiche relative all'utilizzo  dell'infrastruttura di cooperazione applicativa. Tali informazioni saranno di complemento a quelle automaticamente estratte dal sistema di tracciamento della PdD del CentroServiziCART.


3. Analisi:
===========

3.1 Lista degli agenti coinvolti
================================
 i) "Servizi applicativi" che gestiscono comunicazioni che non transitano attraverso la PdD del CentroServiziCART (tipi b) e c))

ii) "Sistema di Reportistica del CART"


3.2 Ruoli:
==========
i) "Generatore di dati statistici": fruitore del servizio, invoca periodicamente il servizio InviaStatisticheCART per comunicare all'Aggregatore i dati statistici da esso raccolti.

ii) "Aggregatore di dati statistici": erogatore dl servizio, riceve i dati inviati dai generatori di dati statisticie, li aggrega agli altri dati gi presenti nel proprio database garantendo la consistenza e l'integrit delle informazioni inserite.


3.3 Ruoli/Agenti
================
- "Generatore di dati statistici" / "Servizi applicativi"
- "Aggregatore di dati statistici" / "Sistema di Reportistica del CART"


3.4 Interazioni Previste:
=========================
Il servizio al momento prevede un'unica azione "InviaNumeroRichieste" di tipo OneWay.


SPECIFICHE PER IL FRUITORE
Il nodo applicativo che utilizza questo servizio per inviare le informazioni al centro servizi CART, deve disporre di 
uno o pi file giornalieri contenenti i dati in formato CSV avente il seguente tracciato record:

   <data, tipo_mittente, mittente, tipo_destinatario, destinatario, tipo_servizio, servizio, azione, valore>

Dove la chiave primaria  rappresentata dall'ottupla <data, tipo_mittente, mittente, tipo_destinatario, destinatario, tipo_servizio, servizio, azione>.

Nei casi in cui almeno uno dei valori dei tre qualificatori di tipo non sia evincibile dal contesto locale, occorrer coordinarsi con il responsabile dell'infrastruttura per ottenere l'assegnazione di valori significativi ad hoc.

I valori riportati nei record dei file CSV devono essere conformi ai seguenti tipi di dato e alle specifiche SPCoop per quanto riguarda le ulteriori restrizioni sui valori di tali identificatori:

data			DATE /* Si tratta di una stringa di 10 caratteri che deve essere nel formato YYYY-MM-DD */
tipo_mittente		STRING(255)
mittente		STRING(255)
tipo_destinatario	STRING(255)
destinatario		STRING(255)
tipo_servizio		STRING(255)
servizio		STRING(255)
azione			STRING(255)
valore			INTEGER /* Una stringa che rappresenti un numero intero con MAXINT = 2147483647 */

I file CSV devono essere codificati secondo il charset ISO-8859-1 e NON devono contenere header come primo record.
Una volta creato ciascun file CSV deve essere compresso in formato gzip ed integrato come attachment al messaggio SOAP del servizio specificando il MIME Header <"Content-Type", "application/x-gzip">.

Il formato XML del messaggio, che costituisce il contenuto applicativo del servizio, deve aderire al seguente XML Schema:

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns="http://www.regione.toscana.it/aggregazioni_statistiche"
    targetNamespace="http://www.regione.toscana.it/aggregazioni_statistiche"
	xmlns:xsd="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">
	<xsd:element name="InvioStatisticheGiornaliere">
		<xsd:complexType>
			<xsd:sequence>
				<xsd:element 
					name="identificatoreNodo" 
					type="xsd:string" 
					minOccurs="1" 
					maxOccurs="1" />
				<xsd:element 
					name="giorno" 
					type="xsd:date" 
					minOccurs="1" 
					maxOccurs="1" />
			</xsd:sequence>
			<xsd:attribute 
				name="testMode" 
				type="xsd:boolean" 
				use="optional" 
				default="false" />
		</xsd:complexType>
	</xsd:element>
</xsd:schema>

Un esempio di file di richiesta:

<?xml version="1.0" encoding="UTF-8"?>
<tns:InvioStatisticheGiornaliere
    xmlns:tns="http://www.regione.toscana.it/aggregazioni_statistiche"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://www.regione.toscana.it/aggregazioni_statistiche/InvioStatistiche.xsd" testMode="true">
	<tns:identificatoreNodo>nal-provinciagrosseto</tns:identificatoreNodo>
	<tns:giorno>2007-10-21</tns:giorno>
</tns:InvioStatisticheGiornaliere>

Ricordandosi che  necessario allegare al messaggio, utilizzando SOAP with attachment [2], i file gzip creati in precedenza.


SPECIFICHE PER L'EROGATORE
Il sistema di elaborazioni statistiche deve gestire una "tabella" (log_ricevuti) avente come tracciato record
la coppia (giorno, identificatoreNodo), in tal modo potr mantenere uno storico degli ultimi N giorni (ad es. N=30)
delle richieste gi pervenute.

Il sistema di elaborazioni statistiche riceve le richieste con allegato relative al servizio InviaStatistiche e le processa
nel seguente modo:

	i) verifica che la data di riferimento delle tracce sia non pi vecchia di N giorni. Se la richiesta
	 riferita ad una data antecedente, la ignora e termina altrimenti prosegue.

	ii) verifica nella tabella log_ricevuti se la richiesta sia gi stata inviata in precedenza. In caso
	affermativo ignora la richiesta e termina, altrimenti prosegue.

	iii) decomprime i file gzip allegati e processa il testo in formato CSV [1] in essi contenuto.

	iv) per ciascun record, l'applicazione verificher la consistenza delle informazioni rispetto alla base di dati delle statische ed integrer conseguentemente il dato fornito alle statistiche preesistenti.

	v) inserisce nella tabella log_ricevuti il record con l'identificatore del nodo e la data di riferimento
	relativi ai dati appena processati.



4.Prodotti Attesi:
==================

i)  Il servizio erogatore sar implementato come estensione del sistema di reportistica.

ii) Verr realizzato un servizio fruitore generico, da installare su tutti i NAL, che sulla base delle informazioni contenute nel Registo Servizi del CART sar in grado generare i dati statistici relativi a tutte le comunicazioni SPCoop fra le PDD dei NAL che utilizzano il servizio di Gestore Eventi come Broker JMS e di inviarle periodicamente al sistema di reportistica.

iii) Per esportare i propri dati verso il sistema di reportistica i servizi applicativi che utilizzano in modo nativo il Broker JMS senza passare dalle PdD dei NAL dovranno implementare un proprio servizio fruitore.



5.Bibliografia
==================
[1] http://en.wikipedia.org/wiki/Comma-separated_values
[2] http://www.w3.org/TR/SOAP-attachments


6.Note
==================
La versione dello standard SOAP supportata dalla PdD del CART  la 1.1 in accordo ai requisiti espressi dalla specifica SPCoop (Requisito PD_UR-17 della specifica della Porta di Dominio). Per la gestione dei messaggi con allegati  necessario fare riferimento alla specifica "SOAP Messages with Attachments", W3C Note 11 December 2000, disponibile alla url http://www.w3.org/TR/SOAP-attachments.


