Webové služby ODOK - Univerzální komunikační rozhraní Speciální komunikační rozhraní slouží pro vzájemnou výměnu informací mezi eKLEP a aplikacemi třetích stran, zejména spisové služby. Komunikační rozhraní podporuje oboustrannou komunikaci směrem od eKLEP ke spisovým službám, a směrem od spisových služeb do eKLEP.
Obsah Webové služby ODOK - Univerzální komunikační rozhraní ..................................................................... 1 Odkaz na WSDL.................................................................................................................................... 1 Přístupová práva.................................................................................................................................. 1 Společné operace ................................................................................................................................ 2 Řízené slovníky .................................................................................................................................... 2 Operace pro komunikaci eKLEP -> Spisové služby .............................................................................. 3 Operace pro komunikaci Spisové služby -> eKLEP .............................................................................. 4 Chybové stavy operací webových služeb: ........................................................................................... 6 Obecné chybové stavy:.................................................................................................................... 6 Specifické chybové stavy: ................................................................................................................ 6 Popis formátu "resource" .................................................................................................................... 9 Příloha: Příklady................................................................................................................................. 11
Odkaz na WSDL Testovací verze: https://kormoran.vlada.cz/odoktest/eklep-ws-test.nsf/eklepWS?WSDL
Přístupová práva Pro přístup k webovým službám ODOK je nutné aplikaci třetích stran zaregistrovat správcem ODOK, svou žádost zašlete emailem na adresu
[email protected]. Při registraci aplikace správce vygeneruje přístupové údaje a rozsah povolených operací vzájemné komunikace. Komunikační rozhraní webové služby ODOK je postaveno na knihovnickém přístupu katalog-fond. Pro aplikace třetích stran je přístupný samotný katalog přístupný pro danou organizaci (operace: getCatalogueForReviewProcess) a fond eKLEPu (operace getSecondaryDocument, getPrimaryDocument). To znamená, že aplikace třetích stran musí pro získání dalších informací o zdroji znát identifikátor daného zdroje - materiál, připomínka. Tento identifikátor je možné získat prostřednictvím avizovací služby eKLEP, jejíž součástí je i xml soubor pro možné strojové zpracování. Pro zjednodušené poskytování webových služeb bylo nutné sjednotit datovou strukturu jak pro avizovací služby, tak i pro webové služby.
Společné operace Společnou operací pro obousměrnou komunikaci jsou seznamy řízených slovníků: • • • • • • •
seznam typů materiálu (requestTypeList) seznam typů připomínek (reviewTypeList) seznam možných stavů materiálu (statusList) seznam povinných připomínkových míst (mandatoryReviewerList) seznam dalších připomínkových míst (otherReviewerList) seznam klíčových slov (keywordList) seznam oblastí práva (lawAreaList)
Pro získání řízených slovníku slouží operace "getSubjectEntries" s jedním vstupním parametrem "subjectType". Tento parametr může obsahovat hodnoty (requestTypeList, reviewTypeList, mandatoryReviewers, otherReviewers, keywordList, lawAreaList). operace "getSubjectEntries" Vstupní parametr: název řízeného slovníku Výstup: seznam hodnot slovníku ve formátu kódu a hodnoty položky slovníku (code / value) Další technické podrobnosti volání operace "getSubjectEntries" lze najít v příloze.
Řízené slovníky Stavy materiálu Code 2 3 3ZV 4 5 6 7 8 9 A B C D Y Z 6PK 7PK 8PK 9PK
Value 2 - v připomínkovém řízení 3 - připomínkové řízení ukončeno 3ZV - k posouzení MZV 4 - odmítnuta verze pro jednání vlády 5 - pro jednání vlády 6 - přijato ÚV ke zpracování 7 - zařazeno do evidence 8 - zařazeno na jednání vlády 9 - projednáno A - zapracovány změny B - signováno C - zasláno PSP D - projednávání PSP Y - skartováno Z - odmítnuto ÚV 6PK - přijato ÚV ke zpracování 7PK - zařazeno do evidence OVL 8PK - zařazeno na jednání PK 9PK - projednáno PK
Typ materiálu Code
MSP MSR MSV
Value Mezinárodní smlouva prezidentská Mezinárodní smlouva resortní Mezinárodní smlouva vládní
NKZ NNV NV NVZZ NZ PNZ NLNV SNZ UZZ ZOS
Návrh krajského zastupitelstva Návrh nařízení vlády Návrh vyhlášky Návrh věcného záměru zákona Návrh zákona Návrh zákona předložený PS Nelegislativní materiál Senátní návrh zákona Úplné znění zákona Zákonné opatření Senátu
Typ připomínky Code
BP D Z
Typ příloh Code pd ob us up zp msc mso zpp ma zd pz Rt vp np pdo mp nup nus pdz uv uvp pr St ria
Value Bez připomínek Doporučující připomínka Zásadní připomínka
Value Průvodní dopis Obálka Návrh usnesení Příloha návrhu usnesení Předkládací zpráva Text v českém jazyce Text v cizím jazyce Předkládací zpráva pro parlament Materiál Důvodová zpráva Platné znění s vyznačením navrhovaných změn a doplnění Rozdílová tabulka Vypořádání připomínek Návrh prováděcích právních předpisů Přehled dopadů Další příloha materiálu Návrh usnesení - PSP Návrh usnesení - SEN Průvodní dopis změny Usnesení vlády Příloha usnesení vlády Připomínka Stanovisko Závěrečná zpráva RIA
Operace pro komunikaci eKLEP -> Spisové služby Aplikace třetích stran může získat prostřednictvím operace " getCatalogueForReviewProcess" seznam materiálů v připomínkovém řízení, tj. ve stavu "2 - přípomínkové řízení", kde je daná organizace
připomínkovým místem. Operace vrátí odpověď ve formátu katalogu, tj. seznam identifikátorů materiálů. Aplikace třetích stran mohou pomocí dvou operací získat údaje o materiálech dvoukrokově: Metadata k samotnému materiálu pomocí operace "getSecondaryDocument" Primární obsah (přílohy) pomocí operace "getPrimaryDocument". operace "getCatalogueForReviewProcess" Vstupní parametr: žádný Výstupní parametr: část katalogu eKLEPu odpovídající danému výběru operace "getSecondaryDocument" Vstupní parametr: PID sekundárního dokumentu (materiálu, připomínky) - jednoznačný identifikátor Výstup: metadata ve formátu objektu "resource" (viz kapitola o formátu "resource") operace "getPrimaryDocument" Vstupní parametr: identifikátor úložiště, název přílohy Výstup: obsah souboru ve formátu BASE64 sd ODOK Web serv ice interface EKLEP Application
ODOK WS
getCatalogueForReviewProcess()
getCatalogueForReviewProcess()
catalogueForReviewProcess()
catalogueForReviewProcess() getSecondaryDocument(PID)
getSecondaryDocument() secondaryDocument() secondaryDocument()
getPrimaryDocument(storageID, fileName) getPrimaryDocument() primaryDocument() primaryDocument()
Operace pro komunikaci Spisové služby -> eKLEP Spisové služby prostřednictvím operací "addSecondaryDocument", "addPrimaryDocument" mohou předpřipravit materiál anebo připomínku v eKLEP. Samotnou autorizaci materiálu anebo připomínky již musí uživatel s právy autorizace provést prostřednictvím webového rozhraní eKLEP.
Pomocí operace "addSecondaryDocument" lze vložit materiál anebo připomínku. Materiál lze vložit rovnou do připomínkového řízení (nutné vyplnit konec připomínkového řízení, a seznam připomínkových míst), anebo bez (bez data konce připomínkového řízení). Po úspěšném uploadu do eKLEP operace vrátí PID materiálu, který eKLEP přidělil. PID je vstupním parametrem operace "addPrimaryDocument" pro identifikaci materiálu, ke kterému budou přílohy vkládány. operace "addSecondaryDocument" Vstupní parametr: metadata ve formátu objektu "resource" (viz kapitola o formátu "resource") Výstup: PID sekundárního dokumentu (materiálu, připomínky) - jednoznačný identifikátor Operací lze vložit materiál do připomínkového řízení (PŘ), pro jednání vlády (bez připomínkového řízení), připomínku k materiálu. Při vkládání materiálu je nutné do parametru "documenttype" vložit hodnotu "request". Při vkládání připomínky je nutné vložit do parametru "documenttype" hodnotu "review". Autorizaci samotného dokumentu je nutné již dokončit v eKLEP pomocí webového rozhraní. Vložení materiálu Povinné atributy: - type / documenttype - identifier / idno_ext - subject / keywords - subject / law_areas - subject / type / code - description - title - mandate Vložení materiálu do PŘ Při vkládání materiálu do PŘ musí být vyplněny kromě obecných povinných atributů taky atributy: - review_process_finish - content / data / request / reviewers Vložení materiálu bez PŘ Při vkládání materiálu bez PŘ se atribut "review_process_finish" neuvádí. Vložení připomínky - type / documenttype - identifier / idno_ext - subject / review_type / code - ispartof / identifier / pid operace "addPrimaryDocument" Vstupní parametr: PID sekundárního dokumentu, Typ přílohy (viz seznam typů příloh), původní název přílohy, a samotný obsah přílohy (BASE64 formát) Výstup: výsledek uploadu
sd ODOK Web serv ice interface - Application->eKLEP EKLEP Application
ODOK WS
addSecondaryDocument()
addSecondaryDocument()
PID()
PID()
addPrimaryDocument()
addPrimaryDocument()
result()
result()
Chybové stavy operací webových služeb: Obecné chybové stavy: Nedostatečné oprávnění pro danou operaci vrátí chybovou hlášku: javax.naming.AuthenticationException Vysvětlení: Chybová hláška znamená, že buď soap message nemá správné přihlašovací údaje anebo aplikace nemá oprávnění k přístupu k dané operaci. Neoprávněný přístup je logován. Specifické chybové stavy: operace "getCatalogueForReviewProcess" - nemá specifické chybové stavy operace "getSecondaryDocument" - nenalezen dokument pod daným PID Kód chyby 400
Popis chyby No document with this PID found
Vysvětlení Nebyl nalezen dokument s daným PIDem
operace "getPrimaryDocument"
Kód chyby 6300
Popis chyby No parameter 'storageID' specified
Vysvětlení Chybí parametr storageID
6301 6302
No parameter 'fileName' specified Attachment with xxx in yyy not found
6306
Invalid replica ID of the storage:
Chybí parametr fileName Příloha pod názvem xxx v úložišti yyy nebyla nalezena Nevalidní identifikátor úložiště
operace "addSecondaryDocument"
Obecná chyba: Kód chyby 6000
Popis chyby Invalid document type:
Vysvětlení Chybí povinný údaj anebo je nevalidní typ dokumentu. Povolené hodnoty jsou "request" a "review"
Chyba při importu materiálu (documenttype = request) Kód chyby 6010
Popis chyby idno_ext value is empty
6011
Title value is empty
6012
Mandate value is empty
6013
Description value is empty
6014
Subject Type value is empty
6015
Keywords value is empty
6016
Law Areas value is empty
6017
Not supported subject type:
6018
Keyword doesnt exist in the directory:
6019
LawArea doesnt exist in the directory:
Vysvětlení Chybí povinný údaj - číslo jednací předkladatele, atribut "idno_ext" Chybí povinný údaj - název materiálu, atribut "Title" Chybí povinný údaj - důvod předložení, atribut "Mandate" Chybí povinný údaj - popis materiálu, atribut "Description" Chybí povinný údaj - typ materiálu, atribut "Subject / Type". Povolené hodnoty jsou výsledkem operace getSubjectEntries s parametrem "requestTypeList" Chybí povinný údaj - klíčové slovo, atribut "subject / keywords". Povolené hodnoty jsou výsledkem operace getSubjectEntries s parametrem "keywordList" Chybí povinný údaj - klíčové slovo, atribut "subject / law_areas". Povolené hodnoty jsou výsledkem operace getSubjectEntries s parametrem " lawAreaList" Hodnota atributu "subject / type / code" není povolená. Povolené hodnoty jsou výsledkem operace getSubjectEntries s parametrem " requestTypeList" Hodnota atributu "subject / keywords / code" není povolená. Povolené hodnoty jsou výsledkem operace getSubjectEntries s parametrem " keywordList" Hodnota atributu "subject / law_areas /
6020
Finish Date is in the past
6021
Reviewers are empty
6022
Reviewer doesnt exist with this code
code" není povolená. Povolené hodnoty jsou výsledkem operace getSubjectEntries s parametrem " lawAreaList " Hodnota atributu "review_process_finish", konec připomínkového řízení, je v minulosti. Zvolte datum odpovídající Legislativním pravidlům vlády, resp. jednacího řádu vlády. Konečná kontrola data konce připomínkového řízení bude při autorizaci. Seznam připomínkových míst je prázdny. Za předpokladu, že je vyplněný datum konce připomínkového řízení, je nutné vložit seznam připomínkových míst (jejich kódy). Připomínkové místo s daným kódem není platným připomínkovým místem. Seznam připomínkovým míst lze získat operací "getSubjectEntries" s parametry "mandatoryReviewList" (seznam povinných připomínkových míst" a "otherTypeList" (seznam nepovinných připomínkových míst"
Chyba při importu materiálu (documenttype = review) Kód chyby 6050 6051 6052 6053
Popis chyby Request PID is not set Relation/IsPartOf/Identifier/PID Request with this PID was not found Request with this PID is not in valid state: Not supported review type:
Vysvětlení Chybí PID materiálu, ke kterému je vkládána připomínka Nebyl nalezen materiál pod zadaným identifikátorem PID Materiál pod identifikátorem PID není ve stavu "2" Typ připomínky, atribut "Subject / review_type", není validní. Seznam validních hodnot typu připomínek lze získat operací "getSubjectEntries" s parametrem "reviewTypeList"
operace "addPrimaryDocument"
Kód chyby 6070
Popis chyby Request PID is not set
6071
Request with this PID was not found
6072
Request with this PID is not in valid state:
Vysvětlení Chybí PID materiálu, ke kterému je vkládána příloha Nebyl nalezen materiál pod zadaným identifikátorem PID Materiál pod identifikátorem PID není ve stavu "0", tj. neautorizováno
6073
This attachment type is not valid:
6074
Attachment with this type was already set Attachment with ending is not allowed
6075
Typ přílohy, atribut "type", není validní. Seznam validních hodnot typu připomínek lze získat operací "getSubjectEntries" s parametrem " attachmentTypeList" Již existuje příloha s daným typem, která byla vložena Povolený typ souboru je .doc (.docx), .xls (.xlsx), .pdf, .txt nebo .zip!
Popis formátu "resource" Typ "type" obsahuje základní atributy daného XML dokumentu: • • •
documenttype - typ záznamu category - kategorie dokumentu (je vždy "document") legislative - jedná se o legislativní typ dokumentu (true / false)
Typ "date" obsahuje seznam všech časových informací (všechny hodnoty jsou v ISO formátu - 8601) • • • • • • • • • • •
authorized - datum autorizace modified - datum poslední změny review_process_finish - konec připomínkového řízení review_process_start - začátek připomínkového řízení discarded - datum storna meeting - datum jednání vlády signed - datum signace premiéra registered_psp - datum evidence na PSP registered_senat - datum evidence v Senátu registered_coll - datum evidence ve SZ signed_president - datum signace prezidentem
Typ "identifier" obsahuje identifikační údaje o daném materiálu (připomínce): • • • • • •
idno - číslo jednací OVA idno_ext - číslo jednací předkladatele pid - jednoznačný identifikátor dokumentu psp - číslo sněmovního tisku meeting_no - číslo jednání schůze resolution_no - číslo usnesení
Typ "subject" obsahuje hodnoty ze základních číselníků: • • •
keywords - seznam klíčových slov law_areas - seznam oblastí práva review_type - typ připomínky
•
type - typ materiálu (ve formátu code / value)
Typ "comment" - poznámka k materiálu Typ "language" - cs Typ "description" - popis materiálu Typ "title" - název materiálu Typ "mandate" - důvod předložení materiálu Typ "content" - který obsahuje specifické údaje pro obsah dokumentů a informace o přílohách daného materiálu (připomínky). Rozděluje se na oblast "data" a "attachments". Typ "attachments" je seznam příloh k danému materiálu (připomínce) ve formátu: • • • • • • • • • •
date_created - datum vytvoření přílohy po přejmenování do úložiště eKLEP filename - název přílohy po přejmenování filesize - velikost přílohy guid - není podstatný, jde o speciální identifikátor úložiště old_filename - starý název přílohy (původní název přílohy vložený předkladatelem) pid - interní identifikátor přílohy storage - identifikátor úložiště type - typ přílohy / viz číselník typů příloh order - číselné pořadí přílohy v případě stejného typu přílohy url - url do úložiště pro přímý přístup
Typ "data" - obsahuje specifické údaje pro daný typ dokumentu: •
request - obsahuje základní údaje o materiálu • meeting - údaje o schůzi, na kterou je materiál zařazen item_number - číslo bodu jednání item_type - typ bodu jednání number - číslo schůze • novel - jestli se jedná o novelu (true / false) • review_address - emailová adresa pro připomínky v rámci připomínkového řízení • reviewers - seznam připomínkových míst, které byly osloveny v připomínkovém řízení ve formátu (code / value) • status - stav materiálu (ve formátu code / value)
Typ "creator" - předkladatel materiálu (připomínky), formát (code / value) Typ "relation" - vztahy mezi dokumenty; v případě připomínky jde o •
ispartof / identifier - PID materiálu, ke kterému se připomínka vztahuje
Příloha: Příklady Obecně request webové služby se skládá z hlavičky a těla. Příklad u operace "addSecondaryDocument" <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ekl="http://eklep.odok.sysnet.cz" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" > <soapenv:Header>
<username> <password> <soapenv:Body> <ekl:addSecondaryDocument> === objekt resource ===
Operace getSecondaryDocument Vstup: getSecondaryDocumentRequest.xml Výstup: getSecondaryDocumentResponse.xml Operace getPrimaryDocument Vstup: getPrimaryDocumentRequest.xml Výstup: getPrimaryDocumentResponse.xml Operace addSecondaryDocument Vstup: addSecondaryDocumentRequest.xml Výstup: addSecondaryDocumentResponse.xml Operace addPrimaryDocument Vstup: addPrimaryDocumentRequest.xml Výstup: addPrimaryDocumentResponse.xml Operace getSubjectEntries Vstup: getSubjectEntriesRequest.xml Výstup: getSubjectEntriesResponse.xml Operace getCatalogueForReviewProcess Vstup: getCatalogueForReviewProcessRequest.xml Výstup: getCatalogueForReviewProcessResponse.xml
