Koordinační středisko pro resortní zdravotnické informační systémy

Aplikace pro Národní onkologický registr na KSRZIS Koordinační středisko pro resortní zdravotnické informační systémy Národní onkologický registr webová služba pro posílání dávek dat do DB NOR a stažení zpětné dávky Uživatelská - technická příručka Stav k : 21.2.2008

Stránka 2 z 13 Verze 1.2 AUTORIZACE DOKUMENTU NÁZEV DOKUMENTU Národní onkologický registr webová služba pro posílání POČET VÝTISKŮ 0 DATUM TISKU DALŠÍ OZNAČENÍ Interní/Externí ČÍSLO DOKUMENTU VERZE DATUM 20080221 21/12/2008 29.04.2008 AUTOR JMÉNO PODPIS DATUM SCHVÁLIL PŘEVZAL Omezující podmínky pro zveřejnění: Tento dokument obsahuje informace důvěrného charakteru a je určen výhradně pověřeným pracovníkům, jako takový nesmí být bez předchozího souhlasu autora kopírován nebo předán třetí fyzické nebo právnické osobě. Upozornění Všechny známky a názvy produktů uvedené v tomto materiálu jsou nebo mohou být registrované obchodní značky, obchodní značky nebo ochranné známky jejich vlastníků. 2008 KSRZIS, všechna práva vyhrazena.

Stránka 3 z 13 Verze 1.2 Obsah : 1. Legislativní podklady... 4 2. Metodické podklady... 4 3. Fungování NORu... 4 4. Popis webových služeb pro import dat do centrální DB NOR... 4 5. Instalace a prostředí... 7 6. Definice rozhraní WSDL (NorWS.wsdl)... 7 7. Příklad nastaveni NorWS.properties... 10 8. Příklad použití webové služby NorWS pro odeslání nové dávky - metoda uploaddata... 11 9. Příklad použití webové služby NorWS pro získání zpětné dávky - metoda getbackbatch.. 12

Stránka 4 z 13 Verze 1.2 1. Legislativní podklady Přehled platné legislativy a platných metodických pokynů, které se přímo dotýkají informačního systému: Zákon č. 20/1966 Sb., o péči o zdraví lidu, ve znění zákona č. 156/2004 Sb. Vyhláška č. 552/2004 Sb., o předávání osobních a dalších údajů do Národního zdravotnického informačního systému pro potřeby vedení národních zdravotních registrů. Zákon č. 101/2000 Sb., o ochraně osobních údajů a o změně některých zákonů, ve znění pozdějších předpisů, Závazné pokyny NZIS Národní onkologický registr - 051-20060101/2 Pokyny k obsahu datové struktury 2. Metodické podklady Nový formulář Incidence a léčba zhoubného novotvaru (dále Hlášení ZN), Metodika NOR Závazné pokyny NZIS - Národní onkologický registr 1/2006, ÚZIS ČR, Datové rozhraní NOR - viz. Datový standard Ministerstva zdravotnictví ČR Zdravotnické klasifikace : o MKN 10 o MKN O 3 o TNM - 6.revize 3. Fungování NORu Přesný popis fungování NORu je uveden v metodice NOR - Závazné pokyny NZIS - Národní onkologický registr 1/2006, ÚZIS ČR. Původní fungování bylo založeno na předávání stanovených podkladů v papírové formě na příslušná územní pracoviště NOR podle trvalého bydliště pacienta. Pověření pracovníci NOR podle podkladů údaje na formuláři NOR verifikovali a tyto údaje vkládali do centrální DB NOR. Záměrem správce dat NOR ÚZIS ČR je, aby byla zdravotnická zařízení, která mají povinnost hlásit, přímo předávala data v elektronické formě do centrální databáze NOR. K uložení dat do centrální DB NOR dojde jen v případě ověření uživatele, provedení všech kontrol bez chyb a v případě, že je možné automaticky rozhodnout o uložení těchto dat. K tomuto účelu bylo vytvořeno datové rozhraní NORu pro předávání dat NOR a vlastní import dat je možné realizovat pomocí technologie webových služeb. 4. Popis webových služeb pro import dat do centrální DB NOR Pro webovou službu je použita technologie SOAP Apache Tomcat 5.5 Axis2. Axis2 podporuje SOAP ve verzích 1.1. a 1.2.

Stránka 5 z 13 Verze 1.2 Obr. 1 Architektura řešení Obr. 2 Schéma komunikace klienta s webovou službou Pro řešení je použita 1 webová služba se 2 metodami : 1.metoda : zajistí autentizaci vůči LDAP KSRZIS pošle dávku na validaci, ke kontrolám dávky a detailním kontrolám pošle zpět výsledek validace a kontrol 2.metoda : zajistí autentizaci vůči LDAP KSRZIS stáhne zpětnou dávku informaci o stažení zapíše do tabulek centrální DB

Stránka 6 z 13 Verze 1.2 Komunikace probíhá prostřednictvím protokolu SOAP. K datům ve formátu XML musí být doplněna SOAP hlavička, která obsahuje informaci o tom, která konkrétní akce se má na serveru provést. Podrobný popis rozhraní je uveden v kapitole č.6 tohoto dokumentu. Přehled akcí: Činnost (akce) Použitá WS Nahrání nové dávky do databáze Použitá metoda WS Vstupní parametr Vstup NorWS uploaddata Ps_data Dávka NOR ve formátu XML Návratové hodnoty Textová zpráva s popisem výsledku operace (popř. popisem chyby) Načtení zpětné dávky z databáze NorWS getbackbatch Ps_data Identifikátor dávky Zpětná dávka ve formátu XML nebo textová zpráva s popisem chyby Popis činnosti WS pro jednotlivé akce : Nahrání nové dávky provede webová služba NorWS metoda uploaddata s parametrem Ps_data. Pro přístup na webový server je nutno autorizovat uživatele. Je zobrazena výzva k zadání uživatelského jména a hesla. Následně je provedena autorizace proti LDAP serveru. Zadané uživatelské jméno (login) je rozhodující pro přístup do databáze. Dojde k načtení rolí uživatele a následně i k identifikaci jednotlivých ZZ, k jejichž dávkám má uživatel přístup. Není-li v databázi nalezen odpovídající záznam, veškerá činnost WS končí a jako návratová hodnota je předána chybová zpráva. Vlastní zpracování dávky tedy začíná provedením kontrol správnosti obsahu dávky validace vzhledem k datovému standardu DASTA. Validní dávka je zapsána do databáze a je zařazena do fronty ke zpracování. Po skončení procesu zpracování dávky je vrácena textová zpráva s popisem výsledku operace popř. popisem chyby. Současně je po ukončení zpracování dávky odeslán informativní mail na adresu uživatele, který dávku nahrál. Obecně jsou nové dávky řazeny do fronty a jsou zpracovávány automatickým mechanizmem v pevně daném časovém intervalu. Pokud tedy ke zpracování dávky nedojde ihned po nahrání (tzv. individuální zpracování), zůstává ve frontě a je zpracována společně s ostatními dávkami. Stejně tak, pokud dojde během zpracování dávky k neočekávanému problému (na straně serveru), bude dávka zařazena k novému zpracování v následujícím cyklu. Informativní mail o výsledku zpracování tedy může být doručen později. Načtení zpětné dávky provede webová služba NorWs metoda getbackbatch s parametrem Ps_data obahuje identifikátor dávky. V případě neexistence dávky, odepření přístupu k dávce nebo stavu, kdy dávka dosud nebyla zpracována je návratová hodnota nastavena touto informací. V opačném případě je vrácena textová hodnota, obsahující xml strukturu zpětné dávky. URL pro uvedené WS : testovací prostředí https://snzr.ksrzis.cz/ntsnzr/nor/axis2/services/norws.

Stránka 7 z 13 Verze 1.2 5. Instalace a prostředí Apache Tomcat 5.5 Nainstalovat webový aplikační server Apache Tomcat 5.5. Popis instalace aplikačního serveru není předmětem této příručky. Podrobnosti lze nalézt na adrese http://tomcat.apache.org/. Umístění aplikačního serveru určuje nastavení proměnné prostředí TOMCAT_HOME. Uživatelům, kteří budou mít právo správce Tomcat, je nutné přidělit uživatelskou roli NOR_TOMCAT_ADMIN. Axis2 Do kontejneru aplikací nainstalovat Apache Axis2. Podrobný popis instalace Axis2 není předmětem této příručky. Podrobnosti lze nalézt na adrese http://ws.apache.org/axis2/1_3/installationguide.html. NorWS Provést deploy archívu NorWS.aar do kontejneru webových služeb. xsd Vytvořit adresář $TOMCAT_HOME\webapps\xsd a umístit do něj soubory použité pro validaci zasílaných dat podle DASTA. Jedná se o tyto soubory: ds_cisidu-1.0.xsd ds_cistype-1.0.xsd ds_dasta-1.0.xsd ds_idu-1.0.xsd ds_type-1.0.xsd nulltr.xsl NorWS.properties Do adresáře $TOMCAT_HOME\webapps umístit soubory NorWS.properties. V tomto souboru upravit nastavení všech hodnot. Příklad pro testovací prostředí ntsnzr je uveden v kapitole č.7 tohoto dokumentu. 6. Definice rozhraní WSDL (NorWS.wsdl) <?xml version="1.0" encoding="utf-8"?> <wsdl:definitions xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:axis2="http://cz.i.nor.ws/" xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/" xmlns:ns0="http://cz.i.nor.ws/xsd" xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/" xmlns:http="http://schemas.xmlsoap.org/wsdl/http/" xmlns:ns1="http://org.apache.axis2/xsd" xmlns:wsaw="http://www.w3.org/2006/05/addressing/wsdl" xmlns:xs="http://www.w3.org/2001/xmlschema" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" targetnamespace="http://cz.i.nor.ws/"> <wsdl:types> <xs:schema xmlns:ns="http://cz.i.nor.ws/xsd" attributeformdefault="qualified" elementformdefault="qualified" targetnamespace="http://cz.i.nor.ws/xsd"> <xs:element name="getbackbatch"> <xs:complextype> <xs:sequence>

Stránka 8 z 13 Verze 1.2 <xs:element minoccurs="0" name="ps_data" nillable="true" type="xs:string"/> </xs:sequence> </xs:complextype> </xs:element> <xs:element name="getbackbatchresponse"> <xs:complextype> <xs:sequence> <xs:element minoccurs="0" name="return" nillable="true" type="xs:string"/> </xs:sequence> </xs:complextype> </xs:element> <xs:element name="uploaddata"> <xs:complextype> <xs:sequence> <xs:element minoccurs="0" name="ps_data" nillable="true" type="xs:string"/> </xs:sequence> </xs:complextype> </xs:element> <xs:element name="uploaddataresponse"> <xs:complextype> <xs:sequence> <xs:element minoccurs="0" name="return" nillable="true" type="xs:string"/> </xs:sequence> </xs:complextype> </xs:element> </xs:schema> </wsdl:types> <wsdl:message name="uploaddatarequest"> <wsdl:part name="parameters" element="ns0:uploaddata"/> </wsdl:message> <wsdl:message name="uploaddataresponse"> <wsdl:part name="parameters" element="ns0:uploaddataresponse"/> </wsdl:message> <wsdl:message name="getbackbatchrequest"> <wsdl:part name="parameters" element="ns0:getbackbatch"/> </wsdl:message> <wsdl:message name="getbackbatchresponse"> <wsdl:part name="parameters" element="ns0:getbackbatchresponse"/> </wsdl:message> <wsdl:porttype name="norwsporttype"> <wsdl:operation name="uploaddata"> <wsdl:input message="axis2:uploaddatarequest" wsaw:action="urn:uploaddata"/> <wsdl:output message="axis2:uploaddataresponse" wsaw:action="urn:uploaddataresponse"/> <wsdl:operation name="getbackbatch"> <wsdl:input message="axis2:getbackbatchrequest" wsaw:action="urn:getbackbatch"/> <wsdl:output message="axis2:getbackbatchresponse" wsaw:action="urn:getbackbatchresponse"/> </wsdl:porttype>

Stránka 9 z 13 Verze 1.2 <wsdl:binding name="norwssoap11binding" type="axis2:norwsporttype"> <soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="document"/> <wsdl:operation name="uploaddata"> <soap:operation soapaction="urn:uploaddata" style="document"/> <wsdl:input> <soap:body use="literal"/> </wsdl:input> <wsdl:output> <soap:body use="literal"/> </wsdl:output> <wsdl:operation name="getbackbatch"> <soap:operation soapaction="urn:getbackbatch" style="document"/> <wsdl:input> <soap:body use="literal"/> </wsdl:input> <wsdl:output> <soap:body use="literal"/> </wsdl:output> </wsdl:binding> <wsdl:binding name="norwssoap12binding" type="axis2:norwsporttype"> <soap12:binding transport="http://schemas.xmlsoap.org/soap/http" style="document"/> <wsdl:operation name="uploaddata"> <soap12:operation soapaction="urn:uploaddata" style="document"/> <wsdl:input> <soap12:body use="literal"/> </wsdl:input> <wsdl:output> <soap12:body use="literal"/> </wsdl:output> <wsdl:operation name="getbackbatch"> <soap12:operation soapaction="urn:getbackbatch" style="document"/> <wsdl:input> <soap12:body use="literal"/> </wsdl:input> <wsdl:output> <soap12:body use="literal"/> </wsdl:output> </wsdl:binding> <wsdl:binding name="norwshttpbinding" type="axis2:norwsporttype"> <http:binding verb="post"/> <wsdl:operation name="uploaddata"> <http:operation location="norws/uploaddata"/> <wsdl:input> <mime:content type="text/xml" part="uploaddata"/> </wsdl:input> <wsdl:output> <mime:content type="text/xml" part="uploaddata"/> </wsdl:output>

Stránka 10 z 13 Verze 1.2 <wsdl:operation name="getbackbatch"> <http:operation location="norws/getbackbatch"/> <wsdl:input> <mime:content type="text/xml" part="getbackbatch"/> </wsdl:input> <wsdl:output> <mime:content type="text/xml" part="getbackbatch"/> </wsdl:output> </wsdl:binding> <wsdl:service name="norws"> <wsdl:port name="norwssoap11port_http" binding="axis2:norwssoap11binding"> <soap:address location="http://localhost:8080/axis2/services/norws"/> </wsdl:port> <wsdl:port name="norwssoap12port_http" binding="axis2:norwssoap12binding"> <soap12:address location="http://localhost:8080/axis2/services/norws"/> </wsdl:port> <wsdl:port name="norwshttpport" binding="axis2:norwshttpbinding"> <http:address location="http://localhost:8080/axis2/services/norws"/> </wsdl:port> </wsdl:service> </wsdl:definitions> 7. Příklad nastaveni NorWS.properties INITIAL_CONTEXT_FACTORY=com.sun.jndi.ldap.LdapCtxFactory PROVIDER_URL=ldap://ldap.ksrzis.cz:389/dc=snzr,dc=cz SECURITY_CREDENTIALS=******** SECURITY_AUTHENTICATION=simple SECURITY_PRINCIPAL=cn=Directory Manager ROLE_SUFFIX=!ou=*,dc=snzr,dc=cz CONNECTION_URL=jdbc:oracle:thin:@tsnzr.ksrzis.cz:1526:TSNZ CONNECTION_USER=nox CONNECTION_PASSWORD=****** ROOT_LOGGER_LEVEL= ALL DEBUG=false NorWS_HOME=/opt/icz/apache-tomcat-5.5.20/webapps/ntsnzr/nor/axis2/WEB-INF/services/ XSD_HOME=../xsd/ AXIS_HOME=/opt/icz/apache-tomcat-5.5.20/webapps/ntsnzr/nor/axis2 CATALINA_HOME=/opt/icz/apache-tomcat-5.5.20 TOMCAT_HOME=/opt/icz/apache-tomcat-5.5.20 NorWS_VERSION=1.00

Stránka 11 z 13 Verze 1.2 8. Příklad použití webové služby NorWS pro odeslání nové dávky - metoda uploaddata Obsah SOAP komunikace pro případ odeslání nové dávky na server. Dávka má identifikaci Batch- 2008/02/20_01. Request: POST /axis2/services/norws HTTP/1.1 Content-Type: text/xml; charset=utf-8 SOAPAction: "urn:uploaddata" User-Agent: Axis2 Authorization: Basic bglib3i6dg9ty2f0 Host: localhost:8080 Transfer-Encoding: chunked 8c8 <?xml version='1.0' encoding='utf-8'?> <soapenv:envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> <soapenv:body> <uploaddata xmlns="http://cz.i.nor.ws/xsd"> <Ps_data xmlns="http://cz.i.nor.ws/xsd"><?xml version="1.0" encoding="utf-8"?><ds:dasta xmlns:ds="urn:mzcr:dasta:xml:ns:ds_dasta-1.0" xmlns:dsidu="urn:mzcr:dasta:xml:ns:ds_idu-1.0" xmlns:xsi="http://www.w3.org/2001/xmlschema-instance" xsi:schemalocation="urn:mzcr:dasta:xml:ns:ds_dasta-1.0 ds_dasta-1.0.xsd urn:mzcr:dasta:xml:ns:ds_idu-1.0 ds_idu-1.0.xsd" id_soubor="icz EHLF6022.5500023833" verze_ds="04.01.01" verze_nclp="02.10.01" bin_priloha="t" ur="t" typ_odesm="nn" ozn_soub="tnn11" dat_vb="2008-02-20t12:46:45"><ds:zdroj_is kod_firmy=" SW602" kod_prog="f602" verze_prog="2.55" liccis_prog="1"/><ds:pm ico="00023833"><ds:as typ="i"><ds:vnitrni>nzis</ds:vnitrni></ds:as><ds:a typ="p"><ds:jmeno>ustav ZDRAVOTNICKYCH INFORMACI A STATISTIKY CR</ds:jmeno><ds:adr>NZIS</ds:adr> <ds:mesto>praha</ds:mesto><ds:stat>000</ds:stat></ds:a></ds:pm><ds:is ico="65269705"><ds:as typ="i"><ds:vnitrni>111</ds:vnitrni></ds:as><ds:a typ="o"><ds:jmeno>nemocnice</ds:jmeno><ds:adr>husova 123</ds:adr><ds:dop1>xxx</ds:dop1><ds:mesto>11111 Brno</ds:mesto><ds:stat>000</ds:stat></ds:a><dsidu:idu><dsidu:nr><dsidu:nor><dsi du:nor_hla hl_ic="65269705" dat_od="2008-02-20t12:46:45" davka_zz="batch-2008/02/20_01" davka_pz="1"/><dsidu:nor_vstup><dsidu:nor_cast1 id_zz="f602_1" h1_zar="65269705000000" h1_odd="40" dat_h1="2008-02-04" rodcis="511203666" pohl="1" dat_na="1951-12-03" obec="582786" socpost="1" stav="1" zjipri="2" kour="2" lateral="4" zeme="061" dat_1n="2008-02-01" dat_dg="2008-02-01" dgstan="01" dg_sl="c000 - ZN- horn[0xc4][0x82][0xc2][0xad] ret, zevn[0xc4][0x82][0xc2][0xad]" dg_kod="c000" topo_kod="c000" morfo_sl="80103 Karcinom, NS" morfo_m="h" morfo_kod="80103" grading="1" tnm_t="1" tnm_n="0" tnm_m="0" ptnm_t="x" ptnm_n="x" ptnm_m="x" klstaon="1" nemoc="1"/><dsidu:nor_cast2/></dsidu:nor_vstup></dsidu:nor></dsidu:nr></dsidu:idu></d s:is></ds:dasta></ps_data> </uploaddata> </soapenv:body> </soapenv:envelope> Response:

Stránka 12 z 13 Verze 1.2 HTTP/1.1 200 OK Server: Apache-Coyote/1.1 Content-Type: text/xml;charset=utf-8 Transfer-Encoding: chunked Date: Wed, 20 Feb 2008 12:26:07 GMT 143 <?xml version='1.0' encoding='utf-8'?> <soapenv:envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> <soapenv:body> <ns:uploaddataresponse xmlns:ns="http://cz.i.nor.ws/xsd"> <ns:return>v[0xc3][0xbd]sledek individu[0xc3][0xa1]ln[0xc3][0xad]ho zpracov[0xc3][0xa1]n[0xc3][0xad] d[0xc3][0xa1]vky: Bez chyby</ns:return> </ns:uploaddataresponse> </soapenv:body> </soapenv:envelope> 9. Příklad použití webové služby NorWS pro získání zpětné dávky - metoda getbackbatch Obsah SOAP komunikace pro případ stažení zpětné dávky s identifikátorem Batch-2008/02/20_01. Request: POST /axis2/services/norws HTTP/1.1 Content-Type: text/xml; charset=utf-8 SOAPAction: "urn:getbackbatch" User-Agent: Axis2 Authorization: Basic bglib3i6dg9ty2f0 Host: localhost:8080 Transfer-Encoding: chunked 123 <?xml version='1.0' encoding='utf-8'?> <soapenv:envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> <soapenv:body> <getbackbatch xmlns="http://cz.i.nor.ws/xsd"> <Ps_data xmlns="http://cz.i.nor.ws/xsd">batch-2008/02/20_01</ps_data> </getbackbatch> </soapenv:body> </soapenv:envelope> 0 Response: HTTP/1.1 200 OK Server: Apache-Coyote/1.1 Content-Type: text/xml;charset=utf-8 Transfer-Encoding: chunked

Stránka 13 z 13 Verze 1.2 Date: Wed, 20 Feb 2008 12:28:17 GMT 634 <?xml version='1.0' encoding='utf-8'?> <soapenv:envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> <soapenv:body> <ns:getbackbatchresponse xmlns:ns="http://cz.i.nor.ws/xsd"> <ns:return><?xml version="1.0" encoding="utf-8" standalone="no"?> <ds:dasta xmlns:ds= "urn:mzcr:dasta:xml:ns:ds_dasta-1.0" xmlns:dsidu="urn:mzcr:dasta:xml:ns:ds_idu-1.0" xmlns:xsi="http://www.w3.org/2001/xmlschema-instance" xsi:schemalocation="urn:mzcr:dasta:xml:ns:ds_dasta-1.0 ds_dasta-1.0.xsd urn:mzcr:dasta:xml:ns:ds_idu-1.0 ds_idu-1.0.xsd" id_soubor="icz,nor.nox,v01,2008-02-20t13:26:06" verze_ds="04.01.01" verze_nclp="02.16.01" bin_priloha="t" ur="r" typ_odesm="xx" ozn_soub="01597" dat_vb="2008-02-20t13:26:06"> <ds:zdroj_is kod_firmy="icz " kod_prog="nor.nox"/> <ds:pm> <ds:as typ="i"> <ds:vnitrni>nor.nox</ds:vnitrni> </ds:as> </ds:pm> <ds:is> <ds:as typ="i"> <ds:vnitrni>nor.nox</ds:vnitrni> </ds:as> <dsidu:idu> <dsidu:nr> <dsidu:nor> <dsidu:nor_hla hl_ic="65269705" dat_od="2008-02-20t13:26:07" davka_zz="batch- 2008/02/20_01" davka_pz="1"/> <dsidu:nor_vystup id_zz="f602_1" evidc="000021" stav="1"> </dsidu:nor_vystup> </dsidu:nor> </dsidu:nr> </dsidu:idu> </ds:is> </ds:dasta> </ns:return> </ns:getbackbatchresponse> </soapenv:body> </soapenv:envelope> 0