6.2. ESM API

Modul ESM poskytuje několik integračních rozhraní.

6.2.1. ES1 (FT) Vložení přejímky

Rozhraní pro zápis přejímky z modulu Výběr. Rozhraní umožňuje zapsat nově vloženou přejímku. Přejímka je rozdělena do logických celků podle cílových archivních souborů a původců. Rozdělení je realizováno formou adresářů. Jméno adresáře slouží jako identifikátor příslušné části přejímky. Každý adresář s částí přejímky má následující strukturu:

prilohy:

Adresář obsahuje přílohy / průvodní soubory vnější změny.

sipy:

Adresář obsahuje SIPy tvořící přejímku. Pokud jde o přejímku, kde byly všechny archiválie skartovány, je adresář prázdný.

zarazeni.xml:

Soubor popisující přejímku. Soubor obsahuje identifikátor AS k němuž se váže vnější změna, ID přejímky v modulu Výběr, kompletní metadata přejímky (předávající, číslo jednací apod.)

Soubor zarazeni.xml je ve formátu dle schématu: zarazeni.xsd.

Výběr zasílá přejímku pomocí služby File Tranfser Service. ESM odpovídá Výběru ve dvou fázích. Nejprve skrze volání V2 (WSDL) Zahájení Uložení potvrdí příjem přejímky a následně voláním V3 (WSDL) Výsledek Uložení Přejimky potvrdí uložení AIPů. Parametry předání:

  • type="<PREJIMKA-SR-NSESSS|PREJIMKA-SR-SOUBORY|PREJIMKA-MSK|UPDATE>"

  • id="<id přejímky v modulu výběr>"

  • GenericDataType.binData=<id uzivatele jako pole bajtů v utf-8>

Typy předání:

  • PREJIMKA-SR-NSESSS - předání dat ze skartačního řízeni formou SIPů ze spisové služby

  • PREJIMKA-SR-SOUBORY - předání dat ze skartačního řízení ve formě volných souborů

  • PREJIMKA-MSK - předání dat z mimoskartačního řízení ve formě volných souborů

  • UPDATE - aktualizace SIPů, výsledek volání V1 (WSDL) Založení změny AIPů

Viz Formát SIPu pro ESM

ES3 (WSDL) ctiArchivniSoubor(asId) - vraci DB reprezentaci AS vcetne seznamu jeho priloh

ES4 (WSDL) ctiArchivniPomucku(aaId) - vraci DB reprezentaci AP vcetne seznamu jeji priloh

ES5 (WSDL) ctiVneZ(vnezId) - vraci DB reprezentaci vniZ vcetne seznamu jeji priloh

ES6 (WSDL) ctiVniZ(vnizId) - vraci DB reprezentaci vneZ vcetne seznamu jeji priloh

6.2.2. ES7 (FT) Zpřístupnění metadat AIPů

Funkce vrací metadata aktuálních verzí archiválií včetně souborové struktury a včetně EAD sekce. Funkce umožňuje vrátit metadata jednotlivého AIPu nebo celé množiny. Výsledek funkce je přenášen jako sada souborů v adresářích, kde každý adresář je pojmenován ID AIPu.

GetMetadata_XY(AIP_ID_list)

Data jsou přenášena pomocí FileTransfer.

Parametry požadavku

Parametry operace Begin pro vyžádání dat:

  • type=“GetMetadata_AS“|“GetMetadata_AP“|“GetMetadata_VniZ“|“GetMetadata_VneZ“

  • id=“<id AIPu>“, případně ID více AIPů (čárkou oddělený seznam)

6.2.3. ES8 (FT) Přidání průvodních dokumentů

K archivním entitám AS, VNěZ, VNiZ, AP je možné přidávat průvodní dokumenty formou samostatných souborů. Modul Výběr zasílá sadu přidávaných souborů.

Pokud je přidán soubor, který již v entitě existuje, tak se jedná o jeho aktualizaci. Zasílající modul musí toto vhodným způsobem vyznačit v uživatelském rozhraní (před voláním tohoto endpointu si nejprve vyžádá metadata archivní entity obsahující seznam souborů). Takový soubor musí mít identický název jako původní soubor (bez (1) na konci nebo jiného označení verze). V případě že se zaslaná verze nerovná nejnovější verzi, volání skončí chybou.

ESM odpovídá Výběru skrze volání V4 (WSDL) Výsledek uložení průvodních dokumentů.

Soubory se předávají v adresáři obsahujícím:

prilohy:

Adresář, kde jsou zasílané soubory.

pridani.xml:

Soubor popisující entitu k níž jsou data přidána (typ entity, id entity), jméno uživatele, který soubory přidal. Viz Přidání průvodních dokumentů.

Parametry předání:

  • type="PRILOHY"

  • id="<id přejímky v modulu výběr>"

  • GenericDataType.binData=<id uzivatele jako pole bajtů v utf-8>

6.2.4. ES9 (FT/WSDL) Vložení XML s pomůckou

Funkce pro vložení zpracované pomůcky. Pomůcka se vkládá ve formátu XML. Pro přenos pomůcky se použije služba File Tranfser Service. Z pomůcky jsou na straně ESM vytažena metadata archiválií a popsané archiválie jsou updatovány (popis apod.).

Odpovědí na nahrání pomůcky je potvrzení jejího přijetí nebo odmítnutí s chybou.

Pomůcka je předávána službou s těmito parametry:

  • type = "POMUCKA"

  • id = "CISLO_NAD,CISLO_POMUCKY"

Soubory s pomůckou jsou předány v jednom adresáři, typ předávaného souboru je určen koncovkou v jeho názvu.

Příklad předávaných dat:

  • abc.xml - soubor ve formátu EAD

  • abc.pdf - soubor ve formátu PDF

ES10 (HTTP) ctiSeznamArchivnichSouboru(filterparams)

Podpora stránkování a filtru na název souboru. Vrací pouze soubory dostupné volajícímu uživateli (s oprávněním zakládat nové přejímky).

ES11 (URL) zobrazMetadataArchivalie(id archivalie)

ES12 (URL) zobrazSouborArchivalie(uuid souboru)

Přístupem na URL: …/esm/file/{uuid}

ES13 (HTTP) ziskejArchivare(idArchivnihoSouboru)

Vrátí seznam všech archivářů, pokud je specifikovaný AS pak pouze archivářů daného AS.

ES14 (WSDL) ulozObjednavku(Objednavka objednavka, String idArchivare, String emailObjednavatele, String emailSprávceBadatelny)

ES15 (WSDL) updateObjednavky(Objednavka objednavka)

ES16 (WSDL) CreateUser(userName, personId, permissionList)

ES17 (WSDL) DeleteUser(userName)

ES18 (WSDL) AddPermissions(userName, permissionList)

ES19 (WSDL) RemovePermissions(userName, permissionList)

ES20 (WSDL) ziskejPrazdneArchivalie(idAs,typEvj)

ES21 (URL) zobrazZmenyPrislusiciRizeni(id rizeni)

Přístupem na URL: …/esm/import-detail/{id}

Vrátí DB záznamy „prázdných“ archiválií, tedy takových které byly založeny především exportem z PEVA a mají k nim být nahrány digitalizáty + metadata.

6.2.5. Synchronizace s PEVA II

ESM HTTP API umožňuje synchronizaci Archivních entit (Archivní soubory [Listy NAD], Archivní pomůcky, Vnitřní změny, Vnější změny) do IS PEVA II skrze externí rozhraní PEVA II a naplňuje v tomto směru požadavky uvedené v dokumentaci: https://www.mvcr.cz/clanek/provoz-informacniho-systemu-evidence-narodniho-archivniho-dedictvi-na-narodnim-portalu.aspx

6.2.6. Formátová analýza a migrace

Pro komunikaci s moduly formátové migrace a formátové analýzy poskytuje model ESM níže uvedená rozhraní.

ES22 (WSDL) getBatchInfo(GetBatchInfoRequest)

Vrátí informace o dávce formátového vyhodnocení, formátové analýzy nebo formátové migrace.

ES23 (WSDL) getBatchFiles(GetBatchFilesRequest)

Vrátí soubory dávky fromátové analýzy či formátové migrace. Vrácení souborů dávky formátového vyhodnocení není podporováno.

  • Parametr from udává od jakého indexu, 0 od začátku.

  • Parametr count udává počet požadovaných souborů.

ES24 (WSDL) analysisStarted(AnalysisStartedRequest)

Formátový modul informuje modul ESM o zahájení formátové analýzy. Předává mu identifikaci procesu a název použitého workflow. Příslušná dávka formátové analýzy musí být ve stavu Vytvořená a je tímto přepnuta do stavu Probíhá.

ES25 (WSDL) migrationStarted(MigrationStartedRequest)

Formátový modul informuje modul ESM o zahájení formátové migrace. Předává mu identifikaci procesu a název použitého workflow. Příslušná dávka formátové migrace musí být ve stavu Vytvořená a je tímto přepnuta do stavu Probíhá.

ES26 (WSDL) modifyAIP(ModifyAIPRequest)

Provede změnu AIP balíčku formátové migrace/analýzy ve workspace. Příslušná dávka formátové analýzy/migrace musí být ve stavu Probíhá.

  • batchType - zda se jedná o zpracování dávky formátové analýzy nebo migrace.

  • batchNumber - číslo dávky formátové analýzy nebo migrace.

  • userName - kdo změnu provádí.

  • aipId - identifikace měněného balíčku.

  • dataVersion, metadataVersion - očekávaná verze balíčku, pokud se nejedná o poslední verzi balíčku, modifikace se neprovede.

  • changes - seznam změn, které je třeba v balíčku provést.

  • events - seznam nových událostí. Vedle těchto událostí ESM vždy zapíše událost modifikace AIP.

Při neúspěchu může funkce vrátit chybu s uživatelsky srozumitelným popisem. Například „Nedostatek místa na pracovním prostoru.“.

ES27 (WSDL) analysisFinished(AnalysisFinishedRequest)

Formátový modul informuje modul ESM o dokončení formátové analýzy. Modul ESM zahájí ingest dávky. Příslušná dávka formátové analýzy musí být ve stavu Probíhá a je tímto přepnuta do stavu Zpracovává se. Selže-li úvodní fáze zpracování, je dávka přepnuta do stavu Přijatá. Uživatel s příslušným oprávněním může následně spustit ingest dávky v ESM UI, čímž se dávka přepíná do stavu Zpracovává se. Po úspěchu úvodní fáze zpracování je spuštěna ingest dávka.

ES28 (WSDL) migrationFinished(MigrationFinishedRequest)

Formátový modul informuje modul ESM o dokončení migrace. Modul ESM zahájí ingest dávky. Příslušná dávka formátové analýzy musí být ve stavu Probíhá a je tímto přepnuta do stavu Přijatá. Uživatel s příslušným oprávněním může spustit ingest dávky v ESM UI, čímž se dávka přepíná do stavu Zpracovává se. Selže-li úvodní fáze zpracování, je dávka opět přepnuta do stavu Přijatá. Po úspěchu úvodní fáze zpracování je spuštěna ingest dávka.

ES29 (URL) vytvorDavkuFmVyhodnoceni(UUID davky)

Přístupem na URL: …/esm/format-evaluation/{id} je v ESM zobrazen detail příslušné dávky.

ES30 (URL) zobrazDavkuVyhodnoceni(UUID davky)

Přístupem na URL: …/esm/format-evaluation/create?format={uuid1}&format={uuid2} je v ESM otevřen formulář pro tvorbu dávky formátového vyhodnocení s předvyplněným omezením na konkrétní formáty.

ES31 (URL) zobrazDavkuAnalyzy(UUID davky)

Přístupem na URL: …/esm/format-analysis/{id} je v ESM zobrazen detail příslušné dávky.

ES32 (URL) zobrazDavkuMigrace(UUID davky)

Přístupem na URL: …/esm/format-migration/{id} je v ESM zobrazen detail příslušné dávky.