e.Toscana Compliance 
Request for Comments: 142 rev 0 (prima versione)
Del: 23/11/2009
Categoria: Applicativa
Destinatari: Regione Toscana, ASL/AO

Flusso SPF ad eventi

Indice
================================================================================
1. Contesto di riferimento	
2. Obiettivi	
3. Analisi 
3.1. Casi d'uso
3.2. XML Schema[1] degli eventi
3.3. WSDL[2] dei servizi
4. Prodotti attesi
5. Bibliografia
6. Storico Versioni



1. Contesto di riferimento
==========================

Il documento RFC ha come oggetto la descrizione del processo di trasmissione 
e di registrazione dell'erogazione, su presentazione di ricetta medica, 
dei seguenti prodotti erogati dalle farmacie sia pubbliche che private:

-	specialita' medicinali 
-	preparati galenici
-	prodotti dietetici
-	dispositivi medici
-	presidi medico-chirurgici
-	altri prodotti sanitari

I prodotti erogati monitorati si intendono compresi nei limiti delle 
prestazioni erogabili a carico del S.S.N.
La rilevazione riguarda tutti i prodotti erogati ad utenti ovunque residenti.
	
La presente versione stabilisce le regole e le codifiche da utilizzare per la trasmissione 
del contenuto informativo dell'evento SPF (Scheda Prestazioni Farmaceutiche).
Viene inoltre illustrata, all'interno del presente documento, l'interfaccia (WSDL) del Web Service 
dedicato alla gestione degli eventi della tipologia descritta. 
Il Web Service in questione svolge il ruolo di interfaccia per il servizio di archiviazione e consolidamento 
delle schede di prestazione farmaceutiche all'interno di due differenti basi dati:

- database ODS(denominato DSPSODS) di Regione Toscana
- database anagrafico/prestazionale del nodo TIX


2. Obiettivi
============

Assunto il contesto di riferimento descritto nel precedente paragrafo, obiettivo
di questo documento RFC e' descrivere il modello organizzativo adottato, i suoi 
scenari e casi d'uso, la tipologia di informazioni e gli eventi al verificarsi 
dei quali tali informazioni sono generate e trasmesse dalle Aziende verso i 
destinatari (e.g. Regione Toscana).

L'obiettivo principale e' quello di permettere l'invio delle schede di 
prestazione farmaceutica ad eventi eliminando la necessit di invio massivo 
a flussi.
I vantaggi che questo meccanismo permette di raggiungere sono :
a. Invio in tempo reale delle prestazioni
b. Riduzione dell'intervento umano


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

Le funzionalit principali offerte dallapplicazione sono:

1)	accettazione del record SPF di test con conseguente consolidamento del record 
	in un area 	destinata a contenere record di questa tipologia.

2)	accettazione del record SPF e successivo consolidamento del record 
	all'interno della base dati configurata come destinazione per il servizio 
	erogatore.
	
3) 	accettazione del record SPF e relativo salvataggio, all'interno di una 
	base dati storicizzata, delle informazioni relative alla singola trasmissione 
	dell'evento (tempistiche di trasmissione e id_egov).

Per ogni SPF deve essere comunicato:

1)	La modalit di esecuzione del servizio (effettiva, o di test)
2)	Lanno di riferimento del flusso
3)	Tutte le informazione che compongono il record SPF, definite nel documento 
	Manuali dei Flussi DOC

I processi elaborativi implementati dall'applicazione consistono di:

1) 	ricezione di una chiamata al web service
2) 	verifica della validita' del documento XML trasmesso, verifica basata su schema XSD
3) 	consolidamento del record ricevuto (SPF) 
3) 	archiviazione, sulla base dati configurata per il servizio erogatore, in base alla modalita' 
	di trasmissione(test/noTest)

	
L'invio dell'informazione avviene attraverso messaggi XML e con l'utilizzo di 
servizi erogati da Regione Toscana ed esposti alle ASL dall'infrastruttura di 
cooperazione applicativa CART. Il dettaglio sulla modalita' di interfacciamento 
con la infrastruttura e' descritto in [3] e [4]. 
	
Gli schema XML che definiscono il formato dei messaggi scambiati dal client con 
i servizi esposti dal web-service,ovvero i documenti XML contenenti il record SPF, 
sono riportati di seguito.

L'attributo test del tag "PrestazioniFarmaceutiche" serve per discriminare 
la modalita' di test (validazione del record con consolidamento e salvataggio 
in un'area riservata della base dati) dalla modalita' canonica di esecuzione 
del processo di consolidamento e archiviazione.


3.1. Casi d'uso
================================================================================

3.1.1. Ev01 - Trasmissione evento SPF 
--------------------------------------------------------------------------------
L'evento si verifica quando viene emessa,modificata o cancellata, dalla ASL di riferimento 
della farmacia erogante,  una scheda SPF.

Al verificarsi dell'evento, la ASL invia a Regione Toscana un messaggio XML che 
contiene le seguenti informazioni rilevanti:

- 	anno di riferimento   
- 	codice ASL di riferimento 
-	codice della ricetta (denominato "chiave" nel Manuale Flussi DOC) 

 
Questi campi costituiscono la chiave logica dell'evento SPF della quale deve essere 
garantita l'univocita'. Eventi SPF arrivati con la stessa combinazione di valori sui campi 
chiave si intendono avere natura di inserimento, modifica, e cancellazione di una 
stessa scheda di prestazione farmaceutica.

Il formato del messaggio e' definito in sezione 3.2 utilizzando la notazione
XML Schema.


3.2. XML Schema degli eventi
================================================================================

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="unqualified">
	<xs:element name="PrestazioniFarmaceutiche">
		<xs:annotation>
			<xs:documentation>Record validato</xs:documentation>
		</xs:annotation>
		<xs:complexType>
			<xs:sequence>
				<xs:element name="Testata" type="TestataType" minOccurs="0"/>
				<xs:element name="PrestazioniFarmaceutiche1" type="PrestazioniFarmaceutiche1Type" minOccurs="0"/>
				<xs:element name="PrestazioniFarmaceutiche2" type="PrestazioniFarmaceutiche2Type" minOccurs="0" maxOccurs="unbounded"/>
			</xs:sequence>
			<xs:attribute name="test" type="xs:boolean" use="optional" default="false"/>
			<xs:attribute name="annoRiferimento" type="xs:int" use="required"/>
		</xs:complexType>
	</xs:element>
	<xs:complexType name="PrestazioniFarmaceutiche1Type">
		<xs:annotation>
			<xs:documentation>Intero record SPF1 validato</xs:documentation>
		</xs:annotation>
		<xs:sequence>
			<xs:element name="Meta" type="MetaType"/>
			<xs:element name="Body" type="BodySPF1Type"/>
		</xs:sequence>
	</xs:complexType>
	<xs:complexType name="PrestazioniFarmaceutiche2Type">
		<xs:annotation>
			<xs:documentation>Intero record SPF2 validato</xs:documentation>
		</xs:annotation>
		<xs:sequence>
			<xs:element name="Meta" type="MetaType"/>
			<xs:element name="Body" type="BodySPF2Type"/>
		</xs:sequence>
	</xs:complexType>
	<xs:complexType name="BodySPF1Type">
		<xs:annotation>
			<xs:documentation>Campi specifici SPF1</xs:documentation>
		</xs:annotation>
		<xs:sequence>
			<xs:element name="TipoRecord" type="xs:string"/>
			<xs:element name="TipoOp" type="xs:string"/>
			<xs:element name="TipoRice" type="xs:string"/>			
			<xs:element name="Chiave" type="xs:string"/>
			<xs:element name="Suggeri" type="xs:string"/>
			<xs:element name="DataPres" type="xs:string"/>
			<xs:element name="TipoIndu" type="xs:string"/>
			<xs:element name="CodIndu" type="xs:string"/>
			<xs:element name="Sesso" type="xs:string"/>
			<xs:element name="DataNascita" type="xs:string"/>
			<xs:element name="Cittadinanza" type="xs:string"/>
			<xs:element name="RgnResidenza" type="xs:string"/>
			<xs:element name="PrvResidenza" type="xs:string"/>
			<xs:element name="CmnResidenza" type="xs:string"/>
			<xs:element name="USLResidenza" type="xs:string"/>
			<xs:element name="ZonaSanResidenza" type="xs:string"/>
			<xs:element name="RgnIscrSan" type="xs:string"/>
			<xs:element name="USLIscrSan" type="xs:string"/>
			<xs:element name="CFMedicoProponente" type="xs:string"/>
			<xs:element name="RgnMedicoProponente" type="xs:string"/>
			<xs:element name="USLMedicoProponente" type="xs:string"/>
			<xs:element name="ZonaSanMedicoProponente" type="xs:string"/>
			<xs:element name="TipoMedicoProponente" type="xs:string"/>
			<xs:element name="RegFarma" type="xs:string"/>
			<xs:element name="ProFarma" type="xs:string"/>			
			<xs:element name="ComFarma" type="xs:string"/>			
			<xs:element name="UslFarma" type="xs:string"/>			
			<xs:element name="ZonFarma" type="xs:string"/>			
			<xs:element name="Farmacia" type="xs:string"/>			
			<xs:element name="ImpNetto" type="xs:string"/>			
			<xs:element name="ImpTick" type="xs:string"/>			
			<xs:element name="Compensa" type="xs:string"/>
			<xs:element name="IdUniUtente" type="xs:string"/>
			<xs:element name="IdUniMedico" type="xs:string"/>
			<xs:element name="IdUniAzienda" type="xs:string" minOccurs="0"/>
			<xs:element name="IdUniFarmacia" type="xs:string" minOccurs="0"/>
			
			
		</xs:sequence>
	</xs:complexType>
	<xs:complexType name="BodySPF2Type">
		<xs:annotation>
			<xs:documentation>Campi specifici SPF2</xs:documentation>
		</xs:annotation>
		<xs:sequence>
			<xs:element name="TipoRecord" type="xs:string"/>
			<xs:element name="Chiave" type="xs:string"/>
			<xs:element name="DataErog" type="xs:string"/>
			<xs:element name="CodFarm" type="xs:string"/>
			<xs:element name="NumFarm" type="xs:string"/>
			<xs:element name="Tariffa" type="xs:string"/>
			<xs:element name="Sconto" type="xs:string"/>
			<xs:element name="Impfarm" type="xs:string"/>
			<xs:element name="Ticket" type="xs:string"/>
			<xs:element name="EsenTick" type="xs:string"/>
		</xs:sequence>
	</xs:complexType>
	<xs:complexType name="TestataType">
		<xs:annotation>
			<xs:documentation>Meta informazioni di testata</xs:documentation>
		</xs:annotation>
		<xs:sequence>
			<xs:element name="ID" type="xs:string"/>
			<xs:element name="DAcq" type="xs:string"/>
			<xs:element name="CodModAcq" type="xs:string"/>
			<xs:element name="CodNodOri" type="xs:string"/>
			<xs:element name="CodNodDes" type="xs:string"/>
			<xs:element name="CodTipHdr" type="xs:string"/>
			<xs:element name="CodMotTrs" type="xs:string"/>
			<xs:element name="NRec" type="xs:string"/>
			<xs:element name="DTra" type="xs:string"/>
			<xs:element name="CodSta" type="xs:string"/>
			<xs:element name="TDes" type="xs:string"/>
			<xs:element name="NRecWrn" type="xs:string"/>
			<xs:element name="NRecErr" type="xs:string"/>
			<xs:element name="NRecRes" type="xs:string"/>
			<xs:element name="BEsp" type="xs:string"/>
			<xs:element name="TNomefile" type="xs:string"/>
			<xs:element name="DFinAcq" type="xs:string"/>
			<xs:element name="DExe" type="xs:string"/>
			<xs:element name="IdUniOriCmp" type="xs:string"/>
			<xs:element name="DImport" type="xs:string"/>
			<xs:element name="DInvio" type="xs:string"/>
			<xs:element name="DInvioGrouper" type="xs:string"/>
			<xs:element name="CodStaExp" type="xs:string"/>
		</xs:sequence>
	</xs:complexType>
	<xs:complexType name="HeaderType">
		<xs:annotation>
			<xs:documentation>Meta informazioni</xs:documentation>
		</xs:annotation>
		<xs:sequence>
			<xs:element name="Contatore" type="xs:string" />
			<xs:element name="ID" type="xs:string" />
			<xs:element name="IDHdr" type="xs:string" />
			<!-- ID uni del record madre se presente, non presente per SPF1-->
			<xs:element name="IDMadre" type="xs:string" minOccurs="0" maxOccurs="1"/>
		</xs:sequence>
	</xs:complexType>
	<xs:complexType name="FooterType">
		<xs:annotation>
			<xs:documentation>Meta informazioni </xs:documentation>
		</xs:annotation>
		<xs:sequence>
			<xs:element name="refTimestamp" type="xs:dateTime"/>
			<xs:element name="AnnoRiferimento" type="xs:string"/>
			<xs:element name="NrErr" type="xs:string"/>
			<xs:element name="NrWrn" type="xs:string"/>
			<xs:element name="CodASLResidenza" type="xs:string"/>
			<xs:element name="CodRgnResidenza" type="xs:string"/>
			<xs:element name="CodASLInv" type="xs:string"/>
			<xs:element name="FlagErr" type="xs:string"/>
			<xs:element name="FlagErrTot" type="xs:string"/>
			<xs:element name="CodStaRec" type="xs:string"/>
			<xs:element name="DataImport" type="xs:date" />
			<xs:element name="DataInvio" type="xs:date"/>
			<xs:element name="DataSpedizioneRecord" type="xs:dateTime" minOccurs="0"/>								
		</xs:sequence>
	</xs:complexType>
	<xs:complexType name="MetaType">
		<xs:annotation>
			<xs:documentation>Meta informazioni </xs:documentation>
		</xs:annotation>
		<xs:sequence>
			<xs:element name="Header" type="HeaderType"/>
			<xs:element name="Footer" type="FooterType"/>
		</xs:sequence>
	</xs:complexType>
</xs:schema>






3.3. WSDL dei servizi
================================================================================


3.3.1 SPFService.wsdl
--------------------------------------------------------------------------------

<definitions name='SPFService' targetNamespace='http://www.regione.toscana.it/ws/2008/ods/' 
xmlns='http://schemas.xmlsoap.org/wsdl/' xmlns:ns1='http://ws.common.dsh.sys.eng.it/' 
xmlns:ns2='http://www.openspcoop.org/pdd/services/PD' xmlns:soap='http://schemas.xmlsoap.org/wsdl/soap/' 
xmlns:tns='http://www.regione.toscana.it/ws/2008/ods/' xmlns:xsd='http://www.w3.org/2001/XMLSchema'>
 <import location='SpfPort.wsdl' namespace='http://ws.common.dsh.sys.eng.it/'></import>
 <service name='SPFService'>
  <port binding='ns1:ODSServiceBinding' name='SPFServicePort'>
   <soap:address location='http://localhost:8080/dsh-consumer/SPFService'/>
  </port>
 </service>
</definitions>


3.3.2 SPFPort.wsdl
--------------------------------------------------------------------------------

<definitions name='SPFService' targetNamespace='http://ws.common.dsh.sys.eng.it/' 
xmlns='http://schemas.xmlsoap.org/wsdl/' xmlns:ns1='http://ws.common.dsh.sys.eng.it/' 
xmlns:soap='http://schemas.xmlsoap.org/wsdl/soap/' xmlns:tns='http://www.regione.toscana.it/ws/2008/ods/' 
xmlns:xsd='http://www.w3.org/2001/XMLSchema'>
 <types>
  <xs:schema targetNamespace='http://ws.common.dsh.sys.eng.it/' version='1.0' 
  xmlns:tns='http://ws.common.dsh.sys.eng.it/' xmlns:xs='http://www.w3.org/2001/XMLSchema'>
   <xs:element name='Exception' type='tns:Exception'/>
   <xs:element name='processMessage' nillable='true' type='xs:string'/>
   <xs:complexType name='Exception'>
    <xs:sequence>
     <xs:element minOccurs='0' name='message' type='xs:string'/>
    </xs:sequence>

   </xs:complexType>
  </xs:schema>
 </types>
 <message name='ODSService_processMessageResponse'></message>
 <message name='Exception'>
  <part element='ns1:Exception' name='Exception'></part>
 </message>
 <message name='ODSService_processMessage'>
  <part element='ns1:processMessage' name='processMessage'></part>

 </message>
 <portType name='ODSService'>
  <operation name='processMessage' parameterOrder='processMessage'>
   <input message='ns1:ODSService_processMessage'></input>
   <output message='ns1:ODSService_processMessageResponse'></output>
   <fault message='ns1:Exception' name='Exception'></fault>
  </operation>
 </portType>
 <binding name='ODSServiceBinding' type='ns1:ODSService'>

  <soap:binding style='document' transport='http://schemas.xmlsoap.org/soap/http'/>
  <operation name='processMessage'>
   <soap:operation soapAction=''/>
   <input>
    <soap:body use='literal'/>
   </input>
   <output>
    <soap:body use='literal'/>
   </output>

   <fault name='Exception'>
    <soap:fault name='Exception' use='literal'/>
   </fault>
  </operation>
 </binding>
</definitions>




4. Prodotti attesi
==================

NN.


5. Bibliografia
===============

[1] XML Schema http://www.w3.org/XML/Schema
[2] Web Services Description Language (WSDL) 1.1 http://www.w3.org/TR/wsdl
[3] "Manuale d'Uso Infrastruttura CART", Regione Toscana, 
Versione 1.01 del 03/12/2007 
[4] "SDK-CART", Regione Toscana, Versione 1.1 del 20/04/2008 

6. Storico versioni
================================================================================

[rev 0 - 23/11/2009]
 - Prima versione pubblicata.



