.. Zdroj: docs/admin-guide/source/08-digital-repositories.rst, elza 18b7804099

.. _admin_digital_repositories:

==========================================
Úložiště digitalizátů a digitální archiv
==========================================

Digitální objekty - skeny, digitálně vzniklé soubory, archivní informační
balíčky (AIP) - se v Elze neukládají. Zůstávají v úložišti a Elza je
napojuje na jednotky popisu. Každé úložiště se nastavuje v *Administrace* >
*Externí systémy* jako externí systém třídy *Uložiště digitalizátů*. Jeho
nastavení se ukládá do databáze a platí bez restartu; v :file:`elza.yaml`
se pro úložiště nenastavuje nic.

Zakládání a změny úložišť vyžadují oprávnění administrátora.

Typy úložišť
============

Typ se volí při založení úložiště a později jej nelze změnit.

================= ==========================================================
Typ               Použití
================= ==========================================================
Digitální archiv  Digitální archiv (DA) uchovávající AIP. Elza čte balíčky
                  přes rozhraní REST archivu a posílá do něj změny zpět
                  (viz :ref:`admin_da_repository`).
Souborový systém  Adresář na serveru Elzy nebo připojené síťové úložiště.
                  Soubory zpřístupňuje sama Elza (viz
                  :ref:`admin_fs_repository`).
WSDL              Úložiště připojené přes starší rozhraní SOAP, které
                  digitální objekty do Elzy posílá (viz
                  :ref:`admin_wsdl_repository`).
================= ==========================================================

Společná nastavení
==================

Kód
   Jednoznačný identifikátor úložiště. Později jej nelze změnit.
   U digitálního archivu je součástí vstupní URL AIP
   (``<ELZA_URL>/da/<kód>/aip/<AIP_ID>``, viz :ref:`impl_entryurl_aip`);
   úložiště WSDL se jím identifikuje.
Název
   Název zobrazovaný uživatelům.
URL
   Adresa úložiště; její význam závisí na typu.
Kód ELZA
   Identifikátor této instance Elzy vůči úložišti. Posílá se úložišti
   WSDL a lze jej použít v cestách a šablonách URL jako ``{repoCode}``.
Vícenásobné napojení
   Zda smí být jeden digitální objekt současně napojen na více jednotek
   popisu. Při *Ne* se druhé napojení odmítne. V digitálním archivu je
   objektem celý AIP nebo jeho část.

.. _admin_da_repository:

Digitální archiv
================

Elza komunikuje s digitálním archivem přes jeho rozhraní REST a přes
protokol File Transfer, který je vhodný pro velké balíčky:

- rozhraní REST hlásí změněné AIP, připravuje balíčky ke stažení a hlásí
  výsledek přijatého exportu,
- File Transfer přenáší každý export a, je-li tak nastaveno, i stahování.

Připojení
---------

URL
   Základní adresa rozhraní REST digitálního archivu, například
   ``https://da.archiv.example/api``. Koncové lomítko se ignoruje.
File Transfer URL
   Adresa endpointu File Transfer. Pokud je prázdná, odvodí se z URL jako
   ``<URL>/ws/ft``; formulář odvozenou adresu zobrazí jako nápovědu a detail
   úložiště zobrazí používanou adresu. Vyplňte ji, jen pokud archiv
   provozuje File Transfer jinde.
ApiKey - ID, ApiKey - hodnota
   API klíč pro rozhraní REST. Jsou-li vyplněny oba údaje, Elza každý
   požadavek klíčem podepíše (``Authorization: NDA-HMAC-SHA256``); bez nich
   požadavky nenesou žádnou autentizaci.
Username, Heslo
   Přihlašovací údaje pro File Transfer (HTTP Basic). Bez uživatelského
   jména se File Transfer připojuje bez autentizace.
Ověřovat TLS certifikát
   *Ano* (výchozí) - certifikát archivu se ověřuje pro rozhraní REST
   i File Transfer. *Ne* - důvěřuje se jakémukoli certifikátu a nekontroluje
   se název serveru; pro interní servery s certifikátem podepsaným sám
   sebou (self-signed). Spojení pak není chráněno proti útoku
   man-in-the-middle; raději přidejte certifikát archivu do úložiště
   důvěryhodných certifikátů (truststore) Javy, pod kterou Elza běží.
   Výsledek *Vyzkoušet nastavení* upozorní, že se certifikát neověřuje.
FileURL
   Adresa prohlížeče komponent archivu. Elza ji otevře v rámu, když si
   uživatel prohlíží napojený digitální objekt. Ostatní pole URL
   (*DaoURL*, *ThumbnailURL*) digitální archiv nepoužívá.

Tlačítko *Vyzkoušet nastavení* v detailu úložiště požádá rozhraní REST
o první změněný AIP a ohlásí, zda archiv odpovídá. Zobrazí i adresu File
Transfer, spojení File Transfer však netestuje.

Synchronizace
-------------

Elza se digitálního archivu pravidelně ptá, které AIP byly od posledního
dotazu přidány, změněny nebo zneplatněny, a pro každý z nich zařadí do
fronty stažení. Zneplatněný AIP se stáhne zpět: jeho napojení se ukončí
a jeho lokální kopie se smaže.

Interval synchronizace (s)
   Počet sekund mezi dvěma dotazy; výchozí hodnota je 300 (pět minut).
   ``0`` synchronizaci zastaví. Uložení úložiště spustí synchronizaci
   okamžitě.

Stahování balíčků
-----------------

Digitální archiv připraví požadované balíčky jako dávku; Elza se ptá na
stav dávky, dokud není připravena, a pak ji stáhne.

Způsob stahování AIP
   *Standardní (HTTP)* stahuje dávku přes rozhraní REST. *File Transfer*
   používá endpoint File Transfer a hodí se pro velké balíčky. Archiv může
   standardní stažení velké dávky odmítnout s HTTP 413; stažení pak skončí
   chybou se zprávou, že je třeba přepnout úložiště na File Transfer.
Typ požadavku File Transfer při stahování
   Nabízí se jen při způsobu File Transfer. Volitelná hodnota posílaná
   s každým požadavkem na stažení jako typ požadavku (``type``
   v ``GenericDataType``, vedle identifikátoru dávky v ``id``). Archivy,
   které na jednom endpointu obsluhují více druhů stahování, podle ní volí
   zpracování; hodnotu dohodněte s provozovatelem archivu. Pokud je
   prázdná, typ se neposílá.
Interval dotazu na stav dávky (s)
   Pauza mezi dvěma dotazy na stav dávky, pro stahování i exporty; výchozí
   hodnota je 2 sekundy, minimum 1 sekunda.
Po přijetí AIP
   *Nic nedělat* - Elza stáhne jen základní informace o balíčku
   (PACKAGE-INFO); uživatelé AIP napojí sami.
   *Stáhnout metadata* - Elza stáhne také metadata každého přijatého AIP,
   jehož archivní soubor zná, sestaví jeho strukturu a automaticky jej
   napojí na popis: podle identifikátorů (UUID) balíčku nebo jeho částí,
   a pokud žádný neodpovídá, skriptem pro zařazení z pravidel archivního
   souboru, pokud jej pravidla mají. AIP, který nelze zařadit, zůstane
   nenapojený a zaznamená se u něj problém.

Exporty
-------

Uživatel odesílá změny napojených AIP do digitálního archivu ze seznamu AIP
(*Generování změnových AIP*). Elza pro každý AIP sestaví změnový balíček
a nahraje jej přes File Transfer; archiv ohlásí, zda balíček přijal. AIP
nenapojené na jednotku popisu se neexportují. Nic se neexportuje
automaticky.

Balíček nese kontextový archivní popis AIP
(``metadata/descriptive/EAD-CONTEXT.xml``, EAD3 podle českého profilu):
kořen archivního souboru, cestu ke každé jednotce napojené na AIP
a podstromy napojených jednotek, vygenerované šablonou EAD pravidel
ZP2015. Jednotky jednoho AIP musí patřit do jednoho archivního souboru.

Stahované a exportované balíčky se uchovávají v adresáři :file:`aip`
v ``elza.workingDir``.

Fronta požadavků
----------------

Každé stažení a export je požadavkem ve frontě digitálního archivu,
*Administrace* > *Fronta digitálního archivu* (odkaz je i v detailu
úložiště). Fronta přežije restart: dávka, kterou archiv připravuje, se
převezme znovu.

=========================== ================================================
Stav                        Význam
=========================== ================================================
Ke stažení, K aktualizaci   Čeká na vyžádání z archivu.
DA připravuje ke stažení    Archiv připravuje dávku; Elza kontroluje její
                            stav.
Aktualizováno/Staženo       Hotovo.
Chyba stažení               Balíček dorazil, ale nepodařilo se jej
                            zpracovat; problém se zaznamená i u AIP.
K exportu                   Čeká na nahrání.
Odesláno, DA zpracovává     Nahráno; archiv jej zpracovává.
Exportováno                 Archiv přijal.
Chyba exportu               Archiv odmítl nebo nepotvrdil.
=========================== ================================================

Požadavek nahrazený novějším požadavkem na tentýž AIP nebo zrušený se
označí jako *neaktivní*. Požadavky se nemažou.

Pokud archiv není dostupný nebo odpoví chybou serveru, požadavek se zopakuje
po rostoucí pauze: interval dotazu na stav dávky, zdvojnásobený po každém
selhání, nejvýše pět minut. Počet pokusů a čas dalšího pokusu jsou ve
frontě zobrazeny. Stahování se nikdy nevzdává.

Akce nad vybranými požadavky:

Zkusit znovu teď
   Vezme čekající požadavek hned, bez čekání na další pokus.
Zrušit požadavek
   Zruší požadavek, který archiv ještě nepřijal.
Opakovat
   Neúspěšné stažení vyžádá znovu; u neúspěšného exportu sestaví nový
   změnový balíček z aktuálního popisu a odešle jej.

.. _admin_fs_repository:

Úložiště v souborovém systému
=============================

URL je cesta na serveru Elzy, například ``/mnt/digi/{fundCode}``. Může
obsahovat proměnné, takže každý archivní soubor má vlastní adresář:

===================== ===============================================
Proměnná              Hodnota
===================== ===============================================
``{repoId}``          ID úložiště
``{repoCode}``        kód ELZA úložiště
``{fundId}``          ID archivního souboru
``{fundNumber}``      číslo archivního souboru
``{fundCode}``        interní kód archivního souboru
``{fundMark}``        značka archivního souboru
``{institutionId}``   ID instituce archivního souboru
``{institutionCode}`` interní kód instituce
===================== ===============================================

Účet, pod kterým běží služba Elza, musí mít k adresáři právo čtení.
*Vyzkoušet nastavení* ověří, že cesta existuje a lze ji číst, a vypíše
její první položky; u cesty s proměnnými se ověřuje jen pevná část.

.. _admin_wsdl_repository:

Úložiště WSDL
=============

Úložiště WSDL posílá digitální objekty do Elzy přes službu SOAP
``DaoCoreService`` (viz :doc:`07-integrace`) a identifikuje se kódem
úložiště. Elza volá zpět služby úložiště ``DaoRequests``
a ``DaoNotifications`` na URL, za které přímo připojí název služby; URL
proto musí končit lomítkem, například ``https://dms.archiv.example/ws/``.
Pro tato volání se použijí Username a Heslo.

Zasílání upozornění
   *Ano* - Elza upozorní úložiště, když uživatel některý z jeho objektů
   napojí nebo odpojí.
DaoURL, FileURL, ThumbnailURL
   Šablony odkazů na digitální objekt, na soubor a na náhled v prohlížeči
   úložiště. Proměnné: ``{code}`` (kód objektu nebo souboru),
   ``{repoId}``, ``{repoCode}``, ``{id}``, ``{label}``, ``{nodeId}``
   a ``{nodeUuid}`` (napojená jednotka popisu) pro objekt, ``{fileName}``
   pro soubor.

Nové instalace napojují místo úložiště WSDL digitální archiv.
