Diff for "SpecifikaceTahitiDamisProtokol" - LightComp Development Wiki

Differences between revisions 1 and 33 (spanning 32 versions)

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.

Termín	Vysvětlení
DocumentSet	Sada společně naskenovaných dokumentů

Změny

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ů LockRequest
2005-09-27	Definice ResumeRequest, přiznak pause u ProcessedRequest
2005-09-12	Definice ReinsertRequest
2005-09-07	Rozšíření UnlockRequest o důvod odemčení

Formát DocumentSet

DocumentSet 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

DocumentSet je identifikován názvem serveru a vlastním identifikátorem DocumentSetu ( 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:

Tahiti dostane z dispu id DocumentSetu
Tahiti zamkne DocumentSet ( při této akci získá lockId)
Tahiti si vyžádá data DocumentSetu
Tahiti periodicky posílá oznámení, že má DocumentSet stále zamčen
Tahiti odešle zpracovaný DocumentSet

Funkce poskytované serverem:

Uzamknutí DocumentSetu
Oznámení, že DocumentSet byl zpracován a odeslání zpracovaného DocumentSetu ( zazipovaného )
Oznámení, že DocumentSet zpracovávat nebude ( odemkne ho )
Vyžádání DocumentSetu ( zazipované )
Oznámení, že vyžádaný DocumentSet 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 DocumentSet je použit http/post s multipart obsahem

Uzamknutí DocumentSetu

Klient odesílá

identifikátor DocumentSetu
uživatelské jméno

Vrátí OK, FAIL

Request
<?xml version="1.0?>
<LockRequest id="" user=""/>

Response 
<?xml version="1.0?>
<LockResponse status="LOCKED|RACE|FAIL|NOTEXISTS" lockId="" error=""/>

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í

xml s níže popsaným příkazem, název "command"
zazipovaný DocumentSet, název "batch1.zip"

Odešle

identifikátor DocumentSetu
zámek DocumentSetu
jméno uživatele

Request
<?xml version="1.0?>
<ProcessedRequest id="" lockId="" user="" pause="0|1" differential="0|1"/>

Response
<?xml version="1.0?>
<ProcessedResponse status="OK|FAIL"/>

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 DocumentSetu 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
<?xml version="1.0?>
<ResumeRequest id="" user=""/>

Response
<?xml version="1.0?>
<ResumeRequestResponse status="OK|FAIL"/>

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í

xml s níže popsaným příkazem, název "command"
zazipovaný DocumentSet, název "batch1.zip"

Odešle

identifikátor DocumentSetu
zámek DocumentSetu
jméno uživatele

Request
<?xml version="1.0?>
<ReinsertRequest id="" lockId="" user=""/>

Response
<?xml version="1.0?>
<ReinsertResponse status="OK|FAIL"/>

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 DocumentSetu
zámek DocumentSetu
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
<?xml version="1.0?>
<UnlockRequest id="" lockId="" user="" reason=""/>

Response
<?xml version="1.0?>
<UnlockResponse status="OK|FAIL"/>

OK - DocumentSet byl odemknut
FAIL - DocumentSet se nepodarilo odemknout

Vyžádání DocumentSetu

Odešle

identifikátor DocumentSetu
zámek DocumentSetu
jméno uživatele

Vrátí soubor se zazipovaným DocumentSetem

Request
<?xml?>
<DocumentSetRequest id="" lockId="" user=""/>

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 DocumentSetu, ktere ma zamcene ( u každého DocumentSetu posílá id, lockId)

Vrátí seznam DocumentSetu, pro ktere to opravdu plati (vrati podmnozinu toho co jsem odeslal)

Request - poslu seznam DocumentSetu, ktere mam zamknute
<?xml version="1.0?>
<NotifyRequest user="">
 <LockedDocumentSet id="" lockId=""/>
 <LockedDocumentSet id="" lockId=""/>
<NotifyRequest/>


Response - vrati seznam DocumentSetu, pro ktere to stale plati 
<?xml version="1.0?>
<NotifyResponse>
 <LockedDocumentSet id="" lockId=""/>
 <LockedDocumentSet id="" lockId=""/>
</NotifyResponse>

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

<?xml version="1.0"?><LockRequest id="00000009" user=""/>

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

<?xml version="1.0" encoding="UTF-8"?><LockResponse lockId="10625d1a505-78a145df-be5e9dd8" status="LOCKED"/>

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í

xml s níže popsaným příkazem, název "command"
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

<?xml version="1.0"?>
<BatchInsertRequest id="" user="franta" domain="POJ_UDAL"/>

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

Response

Jako odpověď přijde xml soubor

<?xml version="1.0">
<BatchInsertResponse id="" status="OK|FAIL|COLLISION">
  <BatchIdCollision/>
  <IdCollision id=""/>
</BatchInsertResponse>

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ů

<BatchIdCollision> příznak kolize čísla dávky, vyskytne se v odpovědi maximálně jednou a pouze když je nastaven status=COLLISION

<IdCollision id=""/> 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

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í

xml s níže popsaným příkazem, název "command"
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

<?xml version="1.0"?>
<BatchCheckRequest user="franta" domain="POJ_UDAL"/>

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

<?xml version="1.0">
<BatchCheckResponse status="OK|FAIL|STRUCTURAL_FAIL">
  <BatchIdCollision/>
  <IdCollision id=""/>
  <IdRule id="" name=""/>
</BatchCheckResponse>

<BatchIdCollision> příznak kolize čísla dávky, vyskytne se v odpovědi maximálně jednou a pouze když je nastaven status=STRUCTURAL_FAIL

<IdCollision id=""/> 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

<IDRule id="" name=""> 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

<?xml version="1.0">
<DocumentSetsForUserRequest user=""/>

Atribut	Význam
user	jméno uživatele, jehož spisy chceme získat

Response

Jako odpověď přijde seznam id spisů

<?xml version="1.0">
<DocumentSetsForUserResponse>
  <DocumentSet id=""/>
  <DocumentSet id=""/>
</DocumentSetsForUserResponse>

Atribut	Význam
id	id spisu, který patří danému uživateli

-  ⇤ ← Revision 1 as of 2005-08-26 10:18:29 → 
  Size: 4186
  Editor: 10
  Comment:
+   ← Revision 33 as of 2007-08-02 11:30:15 → ⇥
  Size: 11656
  Editor: hercules
  Comment:
-Deletions are marked like this.
+Additions are marked like this.
 Line 1:
+#acl TahitiAdminGroup:read,write All:read
-Line 5:
+Line 6:
-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.
+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.
-Line 9:
+Line 10:
+== Změny ==
|| 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í ||
-Line 49:
+Line 60:
-<?xml?>
+<?xml version="1.0?>
-Line 53:
+Line 64:
-<?xml?>
<LockResponse status="LOCKED|RACE|FAIL" lockId=""/>
+<?xml version="1.0?>
<LockResponse status="LOCKED|RACE|FAIL|NOTEXISTS" lockId="" error=""/>
-Line 59:
+Line 70:
-lockId obsahuje přidělený kód zámku ( status == LOCKED)
 
}}}


== Oznámení, že DocumentSet byl zpracován ==
+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 ==
-Line 77:
+Line 90:
-<?xml?>
<ProcessedRequest id="" lockId="" user=""/>

Response
<?xml?>
+<?xml version="1.0?>
<ProcessedRequest id="" lockId="" user="" pause="0|1" differential="0|1"/>

Response
<?xml version="1.0?>
-Line 88:
+Line 101:
-== Oznámení, že DocumentSet zpracovávat nebude ==
+|| 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
<?xml version="1.0?>
<ResumeRequest id="" user=""/>

Response
<?xml version="1.0?>
<ResumeRequestResponse status="OK|FAIL"/>

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"
-Line 96:
+Line 138:
-<?xml?>
<UnlockRequest id="" lockId="" user=""/>

Response
<?xml?>
+<?xml version="1.0?>
<ReinsertRequest id="" lockId="" user=""/>

Response
<?xml version="1.0?>
<ReinsertResponse status="OK|FAIL"/>

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
<?xml version="1.0?>
<UnlockRequest id="" lockId="" user="" reason=""/>

Response
<?xml version="1.0?>
-Line 135:
+Line 204:
-<?xml?>
+<?xml version="1.0?>
-Line 143:
+Line 212:
-<?xml?>
+<?xml version="1.0?>
-Line 149:
+Line 218:
+== 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

<?xml version="1.0"?><LockRequest id="00000009" user=""/>
}}}

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

<?xml version="1.0" encoding="UTF-8"?><LockResponse lockId="10625d1a505-78a145df-be5e9dd8" status="LOCKED"/>

}}}

== 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
{{{
<?xml version="1.0"?>
<BatchInsertRequest id="" user="franta" domain="POJ_UDAL"/>
}}}

|| 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 ||

=== Response ===
Jako odpověď přijde xml soubor 
{{{
<?xml version="1.0">
<BatchInsertResponse id="" status="OK|FAIL|COLLISION">
  <BatchIdCollision/>
  <IdCollision id=""/>
</BatchInsertResponse>
}}}

|| 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ů ||

<Batch``Id``Collision> příznak kolize čísla dávky, vyskytne se v odpovědi maximálně jednou a pouze když je nastaven status=COLLISION

<Id``Collision id=""/> 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 

== 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
{{{
<?xml version="1.0"?>
<BatchCheckRequest user="franta" domain="POJ_UDAL"/>
}}}

|| 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

{{{
<?xml version="1.0">
<BatchCheckResponse status="OK|FAIL|STRUCTURAL_FAIL">
  <BatchIdCollision/>
  <IdCollision id=""/>
  <IdRule id="" name=""/>
</BatchCheckResponse>
}}}

<Batch``Id``Collision> příznak kolize čísla dávky, vyskytne se v odpovědi maximálně jednou a pouze když je nastaven status=STRUCTURAL_FAIL

<Id``Collision id=""/> 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 

<ID``Rule id="" name=""> 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 ===
{{{
<?xml version="1.0">
<DocumentSetsForUserRequest user=""/>
}}}

|| Atribut || Význam ||
|| user || jméno uživatele, jehož spisy chceme získat ||


=== Response ===
Jako odpověď přijde seznam id spisů
{{{
<?xml version="1.0">
<DocumentSetsForUserResponse>
  <DocumentSet id=""/>
  <DocumentSet id=""/>
</DocumentSetsForUserResponse>
}}}

|| Atribut || Význam ||
|| id || id spisu, který patří danému uživateli ||

Wiki

Page

User

Změny

Formát DocumentSet

Identifikace DocumentSetu

Uzamknutí DocumentSetu

Oznámení o zpracování spisu

Uvolnění spisu pro archivaci

Oznámení o znovuvložení spisu do Damisu

Oznámení o odmítnutí spisu

Vyžádání DocumentSetu

Oznámení, že vyžádaný DocumentSet je stále používán

Příklad komunikace

Vložení dávky do Damisu

Request

Response

Kontrola dávky před vložením do Damisu

Request

Response

Získání seznamu spisů v UNLOCKED stavu pro konkrétního uživatele

Request

Response