#acl TahitiAdminGroup:read,write All:read #pragma title-link FrontPage #pragma title Definice komunikacniho protokolu Tahiti/DAMIS Protokol je určen pro komunikaci mezi Tahiti a serverem DAMIS pro distribuci spisů k identifikaci a jejich následné předání na archivaci. Komunikace probíhá pomocí HTTP protokolu (RFC1945, RFC2616), všechny dotazy jsou z klienta na server přenášeny metodou POST. ||<#C0C0C0> Termín ||<#C0C0C0> Vysvětlení || || Document``Set || Sada společně naskenovaných dokumentů || == Změny == || 2012-06-20 || návratové kódy při Document``Set``Request || || 2010-11-18 || rozšíření popisu chybový stavů u Batch``Insert``Response || || 2010-10-26 || atribut extendedCheck u Batch``Insert``Request a Start``Sending``Request || || 2009-12-01 || Nová metoda Delete || || 2007-12-11 || Nové metody: Zahájení přenosu dávky, Přenos bloku dat dávky, Zjištění stavu přenosu || || 2007-11-13 || Přibyla metoda Alloc``Attributes || || 2007-08-02 || Seznam spisů ve stavu UNLOCKED pro konkrétního uživatele || || 2007-02-23 || Kontrola dávky před vložením do Damisu || || 2006-05-15 || Možnost odložení spisu pro pozdější zpracování || || 2005-11-23 || Definice metody pro vložení dávky || || 2005-10-11 || Rozšíření metody Processed o atribut differential || || 2005-09-29 || Rozšíření chybových stavů Lock``Request || || 2005-09-27 || Definice Resume``Request, přiznak pause u Processed``Request || || 2005-09-12 || Definice Reinsert``Request || || 2005-09-07 || Rozšíření Unlock``Request o důvod odemčení || == Formát DocumentSet == Document``Set je zazipovaný soubor, který obsahuje naskenované soubory a soubor docset.xml, který popisuje jejich atributy, příslušnost do dokumentů Popis formátu docset.xml je dostupný zde: http://frnk.lightcomp.cz/lcdevel/SpecifikaceTahitiDamisUlozeniDat, část '''Popis spisu''' == Identifikace DocumentSetu == Document``Set je identifikován názvem serveru a vlastním identifikátorem Document``Setu ( id ) Oba identifikátory jsou ascii Identifikator zámku (lockId) je textový retezec ASCII, ktery vraci server Typická komunikace mezi Tahiti a Skenovacím serverem: 1. Tahiti dostane z dispu id Document``Setu 2. Tahiti zamkne Document``Set ( při této akci získá lockId) 3. Tahiti si vyžádá data Document``Setu 4. Tahiti periodicky posílá oznámení, že má Document``Set stále zamčen 5. Tahiti odešle zpracovaný Document``Set Funkce poskytované serverem: * Uzamknutí Document``Setu * Oznámení, že Document``Set byl zpracován a odeslání zpracovaného Document``Setu ( zazipovaného ) * Oznámení, že Document``Set zpracovávat nebude ( odemkne ho ) * Vyžádání Document``Setu ( zazipované ) * Oznámení, že vyžádaný Document``Set je stále používán Data jsou přenášena pomocí http/post s content-type=text/xml Při odesílání zpracovaného Document``Set je použit http/post s multipart obsahem == Uzamknutí DocumentSetu == Klient odesílá * identifikátor Document``Setu * uživatelské jméno Vrátí OK, FAIL {{{ Request Response LOCKED - DocumentSet je uzamcen, lockId obsahuje identifikator zamku RACE - DocumentSet ma jiz nekdo jiny uzamcen FAIL - chyba NOTEXIST - DocumentSet s danym id neexistuje lockId - obsahuje přidělený kód zámku ( status == LOCKED) error - nepovinny atribut, obsahuje blizsi popis chyby (pravdepodobne v anglictine) }}} == Oznámení o zpracování spisu == Zde se odesílá multipart zpráva složená ze dvou částí 1. xml s níže popsaným příkazem, název "command" 2. zazipovaný Document``Set, název "batch1.zip" Odešle * identifikátor Document``Setu * zámek Document``Setu * jméno uživatele {{{ Request Response OK - DocumentSet byl oznacen jako zpracovany FAIL - DocumentSet se nepodarilo oznacit jako zpracovany }}} || Atribut || Povinnost || Význam || || id || ano || Identifikátor spisu || || lockId || ano || zámek spisu || || user || ano || uživatel pracující se spisem || || pause || ne || Může nabývat hodnot 0|1. V případě 1 je dokument pozdržen (není archivován) do doby než přijde požadavek ResumeRequest || || differential || ne || 0(default)-DocumentSet se ulozi do Damisu, 1-provede se merge Document``Setu s originaální verzí. Pokud je differential="1" je nutné, aby soubor docset.xml byl v zipovém archivu na prvním místě. || == Uvolnění spisu pro archivaci == Pokud byl spis uložen s atributem {{{pause=1}}} je nutno ho samostatným příkazem uvolnit pro další zpracování. Požadavek je označen jako {{{ResumeRequest}}} {{{ Request Response OK - DocumentSet byl oznacen jako znovuvlozeny FAIL - DocumentSet se nepodarilo oznacit jako znovuvložený }}} == Oznámení o znovuvložení spisu do Damisu == Zde se odesílá multipart zpráva složená ze dvou částí 1. xml s níže popsaným příkazem, název "command" 2. zazipovaný Document``Set, název "batch1.zip" Odešle * identifikátor Document``Setu * zámek Document``Setu * jméno uživatele {{{ Request Response OK - DocumentSet byl oznacen jako znovuvlozeny FAIL - DocumentSet se nepodarilo oznacit jako znovuvložený }}} ''Poznámka:'' Slouží pro znovuvložení opravených spisů po reklamaci == Oznámení o odmítnutí spisu == Odešle * identifikátor Document``Setu * zámek Document``Setu * jméno uživatele * důvod odemčení dokumentu || Hodnota || Popis || || BADCONTENT || Vrácení spisu na reklamaci, nečitelné, poškozené apod. || || UNABLETOPROCEED || Předání jiné osobě, není schopen identifikovat. || || POSTPONED || Odložení spisu pro pozdější zpracování. || {{{ Request Response OK - DocumentSet byl odemknut FAIL - DocumentSet se nepodarilo odemknout }}} == Vyžádání DocumentSetu == Odešle * identifikátor Document``Setu * zámek Document``Setu * jméno uživatele Vrátí soubor se zazipovaným Document``Setem. Pokud dojde k chybě vrací následující kódy: || 404 || neexistuje || || 409 || conflict - locked by another user || || 412 || precondition fail - not locked || || 500 || unknown problem || {{{ Request Response zazipovany soubor (batch.zip) s DocumentSetem }}} == Oznámení, že vyžádaný DocumentSet je stále používán == Odešle * jméno uživatele * seznam Document``Setu, ktere ma zamcene ( u každého Document``Setu posílá id, lockId) Vrátí seznam Document``Setu, pro ktere to opravdu plati (vrati podmnozinu toho co jsem odeslal) {{{ Request - poslu seznam DocumentSetu, ktere mam zamknute Response - vrati seznam DocumentSetu, pro ktere to stale plati }}} == Příklad komunikace == Příklad HTTP komunikace (žádost): {{{ POST /damis/DamisServlet HTTP/1.1 Host: 10.2.0.6:8080 Keep-Alive: Connection: TE, Keep-Alive TE: trailers Content-Type: text/xml Content-Length: 57 }}} Příklad HTTP komunikace (odpověď): {{{ HTTP/1.1 200 OK Server: Apache-Coyote/1.1 Content-Type: text/xml Transfer-Encoding: chunked Date: Mon, 05 Sep 2005 10:25:28 GMT }}} == Vložení dávky do Damisu == Příkaz vložení dávky do Damisu === Request === Odesílá se multipart zpráva složená ze dvou částí 1. xml s níže popsaným příkazem, název "command" 2. zazipovaná dávka, název "batch.zip", dávka je ve formátu pro vstup do Damisu bez příznakového souboru complete Formát souboru command {{{ }}} || Atribut || Význam || || id || identifikátor dávky, pokud je prázdný přidělí se na serveru náhodný || || user || jméno uživatele, který vkládá dávku || || domain || název vstupní domény Damisu, do které bude dávka vložena || || extendedCheck || 1 - provádí se rozšířená kontrola na vstupu, atribut je nepovinný || === Response === Jako odpověď přijde xml soubor {{{ }}} || Atribut || Význam || || id || identifikátor dávky, pokud byl odeslán prázdný vrací přidělenou hodnotu || || status || OK - dávka byla vložena na vstup Damisu, FAIL - dávku se nepodařilo vložit na vstup Damisu (obecná chyba), COLLISION - došlo ke kolizi identifikátorů || || error || Pokud je status=FAIL může být v atributu error popis chyby. Popis se posílá pouze u systémových chyb. Logické chyby jsou indikovány pomocí dále popsaných příznaků || příznak kolize čísla dávky, vyskytne se v odpovědi maximálně jednou a pouze když je nastaven status=COLLISION příznak kolize čísla spisu, jeden výskyt pro každé kolidující id, pouze když je nastaven status=COLLISION * id kolidující identifikátor příznak odmítnutí dávky vstupním pravidlem. Platné pouze pokud je nastaven status=FAIL. V atributu name je název pravidla. odmítnutí dávky kvůli nepodporovanému mimetypu. Platné pouze pokud je nastaven status=FAIL. V atributu je název mimetypu. == Kontrola dávky před vložením do Damisu == Příkaz pro kontrolu dávky před vložením do Damisu === Request === Odesílá se multipart zpráva složená ze dvou částí 1. xml s níže popsaným příkazem, název "command" 2. soubor, který obsahuje všechny soubory docset.xml z dávky. Jedná se o soubor ve formátu shodném jako při odesílání celé dávky jen bez datových souborů Formát souboru command {{{ }}} || Atribut || Význam || || id || nepovinný identifikátor dávky, pokud má být číslo dávky kontrolováno na kolizi, může být prázdný || || user || jméno uživatele, který vkládá dávku || || domain || název vstupní domény Damisu, do které bude dávka vložena || === Response === Jako odpověď přijde xml soubor {{{ }}} příznak kolize čísla dávky, vyskytne se v odpovědi maximálně jednou a pouze když je nastaven status=STRUCTURAL_FAIL příznak kolize čísla spisu, jeden výskyt pro každé kolidující id, pouze když je nastaven status=STRUCTURAL_FAIL * id kolidující identifikátor příznak neplatnosti spisu na základě rozhodnutí vstupních pravidel, jeden výskyt pro každý spis, který neprojde pravidly, pouze když je nastaven status=STRUCTURAL_FAIL * id číslo spisu, který neprošel pravidly * name název pravidla, které spis nesplňuje == Získání seznamu spisů v UNLOCKED stavu pro konkrétního uživatele == Příkaz pro získání id všech spisů v UNLOCKED stavu konkrétního uživatele === Request === {{{ }}} || Atribut || Význam || || user || jméno uživatele, jehož spisy chceme získat || === Response === Jako odpověď přijde seznam id spisů {{{ }}} || Atribut || Význam || || id || id spisu, který patří danému uživateli || == Alokace hodnot identifikátorů == Příkaz pro získání hodnot identifikátorů z číselné řady === Request === {{{ }}} || Atribut || Význam || || user || jméno uživatele, který atributy alokuje || || domain || název domény, pro kterou se hodnoty alokují || || numAttributes || po4et hodnot, které se mají alokovat || === Response === Jako odpověď přijde seznam hodnot atributů {{{ }}} || Atribut || Význam || || status || výsledek operace OK-hodnoty byly alokovány, FAIL-chyba || || value || hodnota atributu || == Zahájení přenosu dávky == Příkaz pro zahájení přenosu dávky === Request === {{{ }}} || Atribut || Význam || || user || Uživatel || || domain || Doména, do které dávku posílá || || size || Velikost dávky v bajtech || || id || Id dávky, pokud prázdné je id přiděleno || || extendedCheck || 1 - provádí se rozšířená kontrola na vstupu, atribut je nepovinný || === Response === {{{ }}} || Atribut || Význam || || status || Výsledek operace OK-přenos může začít, FAIL-něco selhalo || || handle || Handle přenášené dávky, platí pouze pokud byl status=OK || == Přenos bloku dat dávky == Příkaz pro přenos bloku dat dávky. Odesílá se multipart zpráva složená ze dvou částí 1. xml s níže popsaným příkazem, název "command" 2. blok dat zazipované dávky, název "batch.part" === Request === {{{ }}} || Atribut || Význam || || handle || handle přenášené dávky || || from || počáteční pozice přenášeného souboru || || size || velikost bloku || === Response === {{{ }}} || Atribut || Význam || || status || Výsledek operace COMPLETE-dávka byla kompletně přenesena, PARTIAL-blok byl úspěšně přenesen, dávka byla částečně přenesena, FAIL - chyba, dale uz neni mozne pokracovat, COLLISION - dávka byla celá přijata, ale při vkládání došlo ke kolizi|BADPOSITION-snaha o ulozeni bloku na spatnou pozici || || id || id dávky, platné pouze při status=COMPLETE || == Zjištění stavu přenosu (velikost již odeslaných dat) == === Request === {{{ }}} || Atribut || Význam || || handle || handle přenášené dávky || === Response === {{{ }}} || Atribut || Význam || || status || Výsledek operace COMPLETE-dávka byla kompletně přenesena, PARTIAL-dávka byla částečně přenesena, UNKNOWN - neznámý handle, COLLISION - collision of id || || from || odkud je možné pokračovat v přenosu, pokud status=PARTIAL || == Vymazání dokumentu == === Request === {{{ }}} || Atribut || Význam || || id || identifikátor Doc``Setu || || lockId || zámek || || user || uživatel, který vyvolal akci || === Response === {{{ }}} || Atribut || Význam || || status || Výsledek operace OK- spis byl smazán, FAIL - spis se nepodařilo smazat ||