Popis egon služby E165 - robvydejdat Název dokumentu: Popis egon služeb Verze: 01.01 Autor: Správa základních registrů Datum aktualizace: Účel: Popis egon služeb v rámci základních registrů Počet stran: 10 26. 12.2016
Obsah 1 Účel dokumentu... 3 2 Funkcionalita služby... 3 3 Základní informace o službě... 3 4 Historie služby... 3 5 Účel služby - detailní popis... 4 5.1 Podporované procesy 4 5.1.1 Volby 4 6 Věcná pravidla vztahující se ke zpracování služby... 4 7 Rozpad egon služby na primitivní služby... 4 7.1 Seznam a popis využívaných primitivních služeb 4 7.2 Workflow zpracování služby 5 8 Vstupní údaje... 5 8.1 ZadostInfo 5 8.2 AutorizaceInfo 5 8.2.1 Proces Volby 5 8.3 Zadost 5 8.3.1 Proces Volby 5 9 Kontroly při volání služby... 6 10 Příklad volání služby... 6 11 Výstupní údaje... 7 11.1 OdpovedInfo 7 11.1.1 Stavy 7 11.2 RobOdpoved 7 11.2.1 VydejVystupniData 8 12 Příklad odpovědi... 9 12.1 Odpověd na asynchronní volání služby robvydejdat 9 12.2 Odpověď na službu E100 čtení fronty 9 13 Notifikace změn... 10 14 Chybová hlášení... 10 15 Odkazy na další dokumenty... 10 15.1 Definice služby 10 15.2 Egon služby 10 Na Vápence 14 Strana 2 z 10 www.szrcr.cz
1 Účel dokumentu Účelem tohoto dokumentu je především poskytnout orgánům veřejné moci, obecně uživatelům Základních registrů, jednoduchý a srozumitelný popis jak používat příslušnou egon službu, včetně informací pro IT pracovníky orgánů veřejné moci. Změny provádí SZR. 2 Funkcionalita služby Služba slouží pro výdej dat z ROB pro podpůrné procesy související se systémem základních registrů podle zákona. Obsah vydávaných dat je závislý na typu procesu, který je určen vstupními parametry služby. Jde o neveřejnou službu. Konzumentem služby je ISZR/FAIS. Slouží pro výdej dat za účelem přípravy volebních seznamů. 3 Základní informace o službě Název služby Označení služby Verze služby Publikována v katalogu služeb od verze robvydejdat E165 Platnost od 1. 1. 2014 Platnost do Stav služby Nahrazena službou Nahrazuje službu Třída služby Dostupnost služby, potřebná oprávnění Režim služby SLA služby V1 Aktivní S4 Neveřejná služba, ověření dle registrace. Pouze asynchronní SLA-05 4 Historie služby Verze služby Aktuální stav verze Publikovaná v produkčním prostředí Od V1 aktivní 1. 1. 2014 Prvotní verze Do Popis změn oproti předchozí verzi Na Vápence 14 Strana 3 z 10 www.szrcr.cz
5 Účel služby - detailní popis Služba E165 robvydejdat slouží pro výdej dat z ROB pro podporu specifických procesů implementovaných specializovanými AIS. Součástí vstupních dat služby je specifikace procesu, pro který se data vybírají. Na základě specifikace tohoto procesu jsou z ROB vydána data určená pro příslušný proces. Služba má obecnou množinu vstupních parametrů. Pro každý z podporovaných procesů se využívají pouze některé z těchto vstupních parametrů. Výstupní data jsou vydávána prostřednictvím výstupních souborů ve specifickém formátu závislém na typu podporovaného procesu. Specializované AIS využívající tuto službu mohou realizovat výdej dat v zastoupení. Tj. volající AIS může zprostředkovávat čtení ROB pro jinou definovanou agendu. AIS tedy může fungovat v agendě, která zabezpečuje výdej výpisů ze ZR na základě zákona, ovšem vlastní data mohou být takto vydána pro účely jiné agendy podle jiného zákona. Služba umožňuje specifikovat při volání toto zastoupení tak, aby při výdeji dat o využití z ROB bylo patrné, pro jaké účely byl výdej dat realizován. Volající AIS je povinen zabezpečit správné naplnění vstupních parametrů, Přístup ke službě je umožněn pouze důvěryhodným systémům. 5.1 Podporované procesy 5.1.1 Volby Služba implementuje proces výdeje dat pro volby. Na základě zadaných vstupních parametrů jsou z ROB vydána data pro volby. Výstupem je zašifrovaný soubor dat určený pro příjemce ISZR/FAIS (ROB šifruje soubor pro příjemce ISZR/FAIS). 6 Věcná pravidla vztahující se ke zpracování služby Služba je dostupná pouze v asynchronním režimu. Po zahájení zpracování je zkontrolováno, zda jde o povolený proces. V případě úspěšného ověření je zavolána služba robvydejdat na interním rozhraní ROB. Po vytvoření odpovědi v ROB jsou z ROB načteny výstupní data a ta jsou připravena na výstup pro AIS, který zabezpečí předání dat na příslušné OVM využívající data (subjekt specifikovaný ve vstupních parametrech služby tento subjekt OVM - bude uveden v provozních záznamech ROB). 7 Rozpad egon služby na primitivní služby 7.1 Seznam a popis využívaných primitivních služeb V rámci zpracování jsou využívány následující interní služby: O23 robvydejdat služba pro výdej dat z ROB Na Vápence 14 Strana 4 z 10 www.szrcr.cz
7.2 Workflow zpracování služby 8 Vstupní údaje Vstupní údaje obsahují standardní položky, definované v datovém typu IszrRobVydejDatType. Bez správného vyplnění vstupních údajů nelze transakci zpracovat. 8.1 ZadostInfo Položka ZadostInfo představuje standardní hlavičku datové zprávy dotazu, která je odesílána ke zpracování. Struktura a obsah hlavičky zprávy jsou dány datovým typem ZadostInfoType. Obsahuje údaje, které ISZR vyžaduje pro ověření přístupu ke službě. Povinné položky musí být vyplněny. 8.2 AutorizaceInfo Položka AutorizaceInfo obsahuje v elementu SeznamUdaju atributy, které mají být ze ZR vydávány. Zda je tento seznam při výdeji použit nebo ignorován závisí na konkrétním implementovaném procesu (některé procesy mohou mít pevně danou množinu výstupních údajů, některé procesy mohou mít rozsah údajů ještě interně omezen v ROB). 8.2.1 Proces Volby Pro proces voleb je validní seznam údajů (interní kontrola v ROB): Jmeno Prijmeni AdresaPobytu DatumNarozeni Obcanstvi 8.3 Zadost Položka Zadost slouží k detailní specifikaci požadavků na službu. Vstupní parametry jsou uvedeny v elementu RobVydejDatData. V tomto elementu se uvádí: v elementu Zadatel informace o žadateli o data (pro účely zastoupení, tato informace bude zapsána v logu ROB). V elementu NazevVydeje specifikace typu výdeje. V elementech KodUzemnihoCelku a TypUzemnihoCelku se uvádí geografické omezení výdeje. Další vstupní parametry jsou specifické pro jednotlivé procesy. 8.3.1 Proces Volby Pro proces výdeje dat pro účely tvorby volebních seznamů se v elementu NazevVydeje musí uvést konstanta Volby. Dále se uvádí podmínky pro zpracování výdeje dat a to v elementu TypVolby typ voleb, pro který je výdej sestavován a v elementu RozhodneDatum pak rozhodné datum voleb, podle kterého je posuzován výdej s ohledem na datum narození vedené v ROB. Na Vápence 14 Strana 5 z 10 www.szrcr.cz
Uvedené vstupní parametry jsou předány do ROB, který zajistí výdej dat v definovaném rozsahu. - V RozhodneDatum musí být voličům 18 let - Adresa pobytu geograficky spadá do oblasti vymezené parametry TypUzemnihoCelku (obec nebo městský obvod/městská část) a KodUzemnihoCelku - Jsou vydávány pouze osoby se státním občanstvím ČR - Jsou vydány pouze živé osoby o Osoba nemá zapsané datum úmrtí o Osoba má zapsané datum úmrtí ve stavu N (úmrtí není jisté) 9 Kontroly při volání služby Na vstupu je prováděna kontrola způsobu volání služby a povoleného typu procesu. Kontroly vstupních dat jsou prováděny interně ve službě ROB. 10 Příklad volání služby <s:envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"> <s:header> <Action s:mustunderstand="1" xmlns="http://schemas.microsoft.com/ws/2005/05/addressing/none">iszrrobvydejdat</action> </s:header> <s:body xmlns:xsi="http://www.w3.org/2001/xmlschema-instance" xmlns:xsd="http://www.w3.org/2001/xmlschema"> <RobVydejDat xmlns="urn:cz:isvs:iszr:schemas:iszrrobvydejdat:v1"> <ZadostInfo xmlns="urn:cz:isvs:iszr:schemas:iszrabstract:v1"> <CasZadosti xmlns="urn:cz:isvs:reg:schemas:regtypy:v1">2014-01- 21T14:57:43.0944162+01:00</CasZadosti> <Agenda xmlns="urn:cz:isvs:reg:schemas:regtypy:v1">axxx</agenda> <AgendovaRole xmlns="urn:cz:isvs:reg:schemas:regtypy:v1">crxxx</agendovarole> <Ovm xmlns="urn:cz:isvs:reg:schemas:regtypy:v1">ovm</ovm> <Ais xmlns="urn:cz:isvs:reg:schemas:regtypy:v1">1</ais> <Subjekt xmlns="urn:cz:isvs:reg:schemas:regtypy:v1">subjekt</subjekt> <Uzivatel xmlns="urn:cz:isvs:reg:schemas:regtypy:v1">uzivatel</uzivatel> <DuvodUcel xmlns="urn:cz:isvs:reg:schemas:regtypy:v1">duvod</duvoducel> <AgendaZadostId xmlns="urn:cz:isvs:reg:schemas:regtypy:v1">1d1fff1e-69cb-4568-b2b2-8362c0cf3f4e</agendazadostid> </ZadostInfo> <AutorizaceInfo xmlns="urn:cz:isvs:iszr:schemas:iszrabstract:v1"> <SeznamUdaju>Aifo </SeznamUdaju> </AutorizaceInfo> <Zadost> <RobVydejDatData> <Zadatel xmlns="urn:cz:isvs:rob:schemas:robdotazydataint:v1"> <CasZadosti xmlns="urn:cz:isvs:rob:schemas:robtypyint:v1">2014-01- 21T14:57:43.0944162+01:00</CasZadosti> <Agenda xmlns="urn:cz:isvs:rob:schemas:robtypyint:v1">axxx</agenda> <AgendovaRole xmlns="urn:cz:isvs:rob:schemas:robtypyint:v1">crxxx</agendovarole> <Ovm xmlns="urn:cz:isvs:rob:schemas:robtypyint:v1">ovm</ovm> <Ais xmlns="urn:cz:isvs:rob:schemas:robtypyint:v1">1</ais> <Subjekt xmlns="urn:cz:isvs:rob:schemas:robtypyint:v1">subjekt</subjekt> <Uzivatel xmlns="urn:cz:isvs:rob:schemas:robtypyint:v1">uzivatel</uzivatel> <DuvodUcel xmlns="urn:cz:isvs:rob:schemas:robtypyint:v1">duvoducel</duvoducel> <AgendaZadostId xmlns="urn:cz:isvs:rob:schemas:robtypyint:v1">1d1fff1e-69cb-4568- b2b2-8362c0cf3f4e</agendazadostid> <IszrZadostId xmlns="urn:cz:isvs:rob:schemas:robtypyint:v1">00000000-0000-0000-0000- 000000000000</IszrZadostId> </Zadatel> <NazevVydeje xmlns="urn:cz:isvs:rob:schemas:robdotazydataint:v1">volby</nazevvydeje> Na Vápence 14 Strana 6 z 10 www.szrcr.cz
<KodUzemnihoCelku xmlns="urn:cz:isvs:rob:schemas:robdotazydataint:v1">517437</koduzemnihocelku> <TypUzemnihoCelku xmlns="urn:cz:isvs:rob:schemas:robdotazydataint:v1">obec</typuzemnihocelku> <KriteriaVolby xmlns="urn:cz:isvs:rob:schemas:robdotazydataint:v1"> <TypVolby xmlns="urn:cz:isvs:rob:schemas:robtypyint:v1">volbaprezidentarepubliky</typvolby> <RozhodneDatum xmlns="urn:cz:isvs:rob:schemas:robtypyint:v1">2014-01- 22T00:00:00+01:00</RozhodneDatum> </KriteriaVolby> </RobVydejDatData> </Zadost> </RobVydejDat> </s:body> </s:envelope> 11 Výstupní údaje Služba je vykonávána asynchronně. Výsledek tedy AIS získává dotazem do výstupní fronty ISZR službou E100 iszrodpovedzfronty. Zde popsané výstupní údaje popisují vlastní odpověď na službu, která je celá vnořena v oběžné obálce služby iszrodpovedzfronty. Výstupní údaje obsahují položky definované v datovém typu IszrRobVydejDatResponseType. 11.1 OdpovedInfo Struktura položky OdpovedInfo obsahuje údaje, které ISZR ale i AIS očekává k dokončení vyřízení požadavku. Struktura a obsah hlavičky zprávy jsou dány datovým typem OdpovedInfoType. 11.1.1 Stavy Stav provedení služby je uveden v elementu Status/VysledekKod: - OK služba byla zpracována v pořádku - VAROVANI při zpracování nastala situace, na kterou je vhodné upozornit. - CHYBA zpracování není možné provést Pokud skončí služba stavem VAROVANI, jsou podrobnosti uvedeny v aplikační části odpovědi, v elementu RobOdpoved. Stav VAROVANI nastává v situacích: - Výstup je prázdný, na základě vstupních podmínek nebyla vybrána žádná data. Stav, kdy zpracování není možné provést, nastane v situaci, kdy službu nebylo možné z nějakého závažného důvodu vykonat nebo sestavit odpověď. Příkladem situace, ve které vzniká tato chyba je například chybný vstup služby, nedostupnost ROB, vyčerpaná kapacita systémových zdrojů a podobně. 11.2 RobOdpoved Položka je vyplněna, pokud nedojde k systémové chybě při vykonání služby. Obsahem položky je aplikační status ROB v elementu RobAplikacniStatus, jako vykonavatele služby a dále informace o způsobu přístupu k datům v elementu VydejVystupniData. Pokud dojde k systémové chybě, tento element není vyplněn. Na Vápence 14 Strana 7 z 10 www.szrcr.cz
11.2.1 VydejVystupniData V elementu VydejVystupniData je uvedena kolekce výstupních souborů. Ke každému souboru mohou být uvedeny následující informace v příslušných elementech: - IdSouboru identifikace souboru - Heslo zašifrované heslo pro dešifrování souboru - Otisk otisk výstupního souboru - TypSouboru způsob šifrování, komprese a podobně - UcelSouboru pro rozlišení účelu, pokud jeden výdej vydává více souborů - DostupnyOd počáteční datum a čas dostupnosti souboru - DostupnyDo koncový datum a čas dostupnosti souboru - Umistění URL nebo část URL, na které je výstupní soubor dostupný V elementu VydejVystupniData může být dále uvedena informace o snímku dat, ze kterého byl výstup vytvořen. Tato informace je obsazena v elementech SnimekRob a SnimekRuian. 11.2.1.1 Způsob šifrování hesla Pro šifrování hesla je navrženo schéma využívající šifrování dat symetrickým algoritmem, přičemž symetrický klíč je verzován a je k dispozici v ROB a ve specifickém AIS. Přenášené heslo v zašifrované podobě před base64 transformací vznikne zřetězením následujících položek (zde symbolem rozumíme pouze operaci zřetězení, nejedná se o znak vkládaný do řetězce) PH = VK ZH Kde platí: Položka Popis Velikost Formát/hodnota PH Přenášené heslo v binární podobě 17B VK Verze klíče verzovaná od čísla 1 1B Byte ZH Zašifrované heslo 16B Binární blob dat Zašifrované heslo (ZH) je výsledkem zašifrování otevřeného hesla (OH) pomocí algoritmu AES s následujícími parametry: je použit algoritmus AES-128 v CBC módu s PKCS7 paddingem (délka paddingu bude 1B), vstupem do šifrování je OH o délce 15B, klíčem pro šifrování je 16B klíč popsaný v kapitole 5 a IV (inicializační vektor) je prvních 16B z položky AgendaZadostId v RAW formátu. Výstupem šifrování je ZH o délce 16B. Na Vápence 14 Strana 8 z 10 www.szrcr.cz
12 Příklad odpovědi 12.1 Odpověd na asynchronní volání služby robvydejdat <soapenv:envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:autocont1="urn:cz:isvs:iszr:services:iszrorgprihlasaifo:v1" xmlns:abs="urn:cz:isvs:iszr:schemas:iszrabstract:v1" xmlns:autocont2="urn:cz:isvs:iszr:schemas:iszrrobvydejdat:v1" xmlns:reg="urn:cz:isvs:reg:schemas:regtypy:v1"> <soapenv:header /> <soapenv:body> <autocont2:robvydejdatresponse> <abs:odpovedinfo> <!--60E865930E64FB4E97515DF279BD2675--> <reg:casodpovedi>2014-01-21t10:14:29.8538786+01:00</reg:casodpovedi> <reg:status> <reg:vysledekkod>ok</reg:vysledekkod> </reg:status> <reg:agendazadostid>11b030e4-1859-4e23-8b8c-68a0e22bcc2b</reg:agendazadostid> <reg:iszrzadostid>9365e860-640e-4efb-9751-5df279bd2675</reg:iszrzadostid> </abs:odpovedinfo> </autocont2:robvydejdatresponse> </soapenv:body> </soapenv:envelope> 12.2 Odpověď na službu E100 čtení fronty <soapenv:envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:odpf="urn:cz:isvs:iszr:schemas:iszrasyncodpovedzfronty:v1" xmlns:reg="urn:cz:isvs:reg:schemas:regtypy:v1" xmlns:autocont1="urn:cz:isvs:iszr:schemas:iszrrobvydejdat:v1" xmlns:abs="urn:cz:isvs:iszr:schemas:iszrabstract:v1" xmlns:xlinl="http://www.w3.org/1999/xlink" xmlns:autocont2="urn:cz:isvs:rob:schemas:robdotazydataint:v1" xmlns:rob="urn:cz:isvs:rob:schemas:robtypy:v1"> <soapenv:header /> <soapenv:body> <odpf:iszrasyncodpovedzfrontyresponse> <odpf:kodasyncsluzby>iszrrobvydejdat</odpf:kodasyncsluzby> <odpf:odpovedinfo> <reg:casodpovedi>2014-01-21t10:19:31.7736540+01:00</reg:casodpovedi> <reg:status> <reg:vysledekkod>ok</reg:vysledekkod> </reg:status> <reg:agendazadostid>1b728f47-a038-467e-8b38-24182dd250e8</reg:agendazadostid> <reg:iszrzadostid>64635837-902b-4f03-a295-3622689af1d0</reg:iszrzadostid> </odpf:odpovedinfo> <odpf:iszrodpoved> <odpf:iszrasyncodpovedzfrontydataresponse> <odpf:asyncdotazdataresponse> <autocont1:robvydejdatresponse> <abs:odpovedinfo> <reg:casodpovedi>2014-01-21t10:16:09.3417940</reg:casodpovedi> <reg:status> <reg:vysledekkod>ok</reg:vysledekkod> <reg:vysledekdetail> <reg:vysledeksubkod>specifikace V POPISU</reg:VysledekSubKod> <reg:vysledekpopis>iszrextop</reg:vysledekpopis> </reg:vysledekdetail> </reg:status> <reg:agendazadostid>11b030e4-1859-4e23-8b8c-68a0e22bcc2b</reg:agendazadostid> <reg:iszrzadostid>9365e860-640e-4efb-9751-5df279bd2675</reg:iszrzadostid> </abs:odpovedinfo> <autocont1:robodpoved> <autocont1:robvydejdatdataresponse> <autocont2:robaplikacnistatus> <rob:vysledekrobkodtype>ok</rob:vysledekrobkodtype> </autocont2:robaplikacnistatus> <autocont2:vydejvystupnidata> <reg:soubory> Na Vápence 14 Strana 9 z 10 www.szrcr.cz
<reg:idsouboru>bc288a28-d9c5-4700-a161-982b8fa328c7</reg:idsouboru> <reg:heslo>azorxyqdwd0bh637ksy1qhm=</reg:heslo> <reg:otisk>f3tfgxqojmau2wndogig/z+l/58=</reg:otisk> <reg:typsouboru>7zaes256</reg:typsouboru> <reg:ucelsouboru>data</reg:ucelsouboru> <reg:dostupnyod>2014-01-21t10:15:20</reg:dostupnyod> <reg:dostupnydo>2014-01-22t10:15:20</reg:dostupnydo> <reg:umisteni>https://...</reg:umisteni> </reg:soubory> </autocont2:vydejvystupnidata> <autocont2:snimekrob>2014-01-21t00:00:00</autocont2:snimekrob> <autocont2:snimekruian>2013-07-01t00:00:00</autocont2:snimekruian> </autocont1:robvydejdatdataresponse> </autocont1:robodpoved> </autocont1:robvydejdatresponse> </odpf:asyncdotazdataresponse> </odpf:iszrasyncodpovedzfrontydataresponse> </odpf:iszrodpoved> </odpf:iszrasyncodpovedzfrontyresponse> </soapenv:body> </soapenv:envelope> 13 Notifikace změn Služba není editační, notifikace změn pro ni není relevantní. 14 Chybová hlášení Služba neobsahuje specifická chybová hlášení. 15 Odkazy na další dokumenty 15.1 Definice služby WSDL služby: egon/wsdl/iszrrobvydejdat.wsdl XSD služby: egon/xsd/iszrrobvydejdat.xsd 15.2 Egon služby SZR_popis_eGON_služeb_E100_iszrAsyncOdpovedZFronty.doc Na Vápence 14 Strana 10 z 10 www.szrcr.cz