.. _ug_admin_import:

=======================
Import
=======================

Obrazovka *Import* slouží k **dávkovému importu** dat do aplikace. Umožňuje najednou importovat více archivních souborů
z datových souborů ve formátu EDX2 nebo hromadně doplnit prvky popisu k existujícím jednotkám popisu ze souboru CSV.

.. figure:: resources/admin-import.png
    :align: center

    Importy

Import probíhá prostřednictvím **importních dávek**. Každá dávka má své nastavení, obsahuje jednu nebo více
**položek** (vstupních souborů) a během zpracování prochází různými :ref:`stavy <ug_admin_import-states>`.

Na obrazovce je možné založit dva druhy dávek:

  - **Nová EDX2 dávka** – import archivních souborů z datových souborů ve formátu EDX2 (XML)
  - **Nová CSV dávka** – :ref:`import (doplnění) prvků popisu <ug_arr_table_view_import>` k existujícím jednotkám popisu ze souboru CSV

Pod tlačítky pro založení dávky je zobrazen :ref:`přehled importních dávek <ug_admin_import-list>`.

.. note::
  Obrazovka je dostupná pouze uživatelům s :ref:`oprávněním <ug_admin_perms_other>` **Superuživatel**.


Postup importu
=================

  1. Založte novou dávku tlačítkem *Nová EDX2 dávka* nebo *Nová CSV dávka* a vyplňte její nastavení.
  2. Po stisknutí tlačítka *Založit* se dávka vytvoří ve stavu ``PREPARATION`` a zobrazí se její **detail**.
  3. V detailu dávky vložte vstupní soubory pomocí jedné z akcí:

     - *Nahrát soubor* – nahrání jednoho souboru,
     - *Nahrát ZIP* – nahrání archivu ZIP, ve kterém se každý soubor stane samostatnou položkou dávky,
     - *Ze složky na serveru* – výběr souborů ze složky na serveru (dostupné pouze tehdy, pokud je na serveru nakonfigurována složka pro import).

  4. Volitelně spusťte **testovací běh** tlačítkem *Testovací běh*, který ověří vstupní soubory bez provedení importu.
  5. Spusťte **import** tlačítkem *Spustit*. Průběh zpracování dávky i jednotlivých položek je průběžně zobrazován.
  6. Pokud zpracování některé položky skončí chybou, je možné zobrazit detail chyby, problematickou položku odstranit
     nebo opravit a dávku spustit znovu.

V detailu dávky je dále možné běžící dávku **pozastavit**, **přerušit** nebo ji **smazat**.
Po dokončení importu je možné z položky přímo otevřít vytvořený nebo aktualizovaný archivní soubor.


.. figure:: resources/admin-import-detail.png
    :align: center

    Detail importní dávky

.. note::
  **Testovací běh** u dávky EDX2 ověří formální správnost vstupních souborů (validace proti XML schématu).
  U dávky CSV se testovací běh neprovádí.


.. _ug_admin_import-edx2:

Nová EDX2 dávka
=================

Dávka EDX2 slouží k importu jednoho nebo více archivních souborů z datových souborů ve formátu **EDX2**.
Každý vstupní soubor dávky odpovídá jedné položce, která je importována samostatně.

.. figure:: resources/admin-import-edx2.png
    :align: center

    Nový import – EDX2


Nastavení dávky
-----------------


Název *
   - libovolný název dávky, pod kterým bude dávka zobrazena v přehledu importů

Strategie importu fondu *
   - určuje, zda importovaná data vytvoří nový archivní soubor, nebo budou vložena do již existujícího archivního souboru:

     - ``ALWAYS_NEW`` – každá položka dávky vždy vytvoří **nový archivní soubor**, párování s existujícími archivními soubory se neprovádí
     - ``ALWAYS_PAIR`` – každá položka musí být **spárována s existujícím archivním souborem**, do kterého jsou data importována;
       pokud odpovídající archivní soubor neexistuje, zpracování položky skončí chybou
     - ``PAIR_AND_CREATE`` – položka je **spárována s existujícím archivním souborem**, pokud existuje;
       v opačném případě je vytvořen nový archivní soubor

Klíč pro párování
   - určuje, podle jakých údajů je importovaná položka párována s existujícím archivním souborem
   - ``INSTITUTION_AND_FUND_NUMBER`` – párování podle **kódu instituce** a **čísla archivního souboru**,
     které jsou uvedeny v importovaném souboru EDX2
   - nastavení je nutné u strategií ``ALWAYS_PAIR`` a ``PAIR_AND_CREATE``, u strategie ``ALWAYS_NEW`` se nepoužije

Ignorovat kořenové úrovně
   - zaškrtnuto: kořenové úrovně z importovaného souboru nejsou vytvořeny
     a jejich podřízené úrovně jsou vloženy přímo pod kořenovou úroveň spárovaného archivního souboru
   - volbu lze využít pouze v kombinaci s párováním na existující archivní soubor

Oblast entit *
   - :ref:`oblast <ug_ap_scopes>`, do které budou založeny nové archivní entity obsažené v importovaném souboru

Pokračovat po chybě položky
   - nezaškrtnuto: zpracování dávky se **zastaví při první chybě** a dávka přejde do stavu ``FAILED``
   - zaškrtnuto: po chybě se pokračuje ve zpracování dalších položek; dávka však i v tomto případě
     skončí ve stavu ``FAILED``, pokud alespoň jedna položka skončila chybou

Zachovat vstupní soubory
   - nezaškrtnuto: vstupní soubory dokončené, chybové nebo přerušené dávky jsou automaticky **odstraněny po 30 dnech**
     od poslední změny jejího stavu; takovou dávku již nelze znovu spustit
   - zaškrtnuto: vstupní soubory dávky jsou zachovány trvale

(*) = povinný údaj

.. note::
  - Soubory EDX2 (XML) je možné získat též pomocí `konverze z jiných datových zdrojů <https://docs.lightcomp.cz/elza-convert/cs/index.html#>`_.
  - Výsledek **párování** musí odpovídat právě jednomu archivnímu souboru. Pokud odpovídá více archivním souborům, zpracování položky skončí chybou.
  - Při importu do existujícího (spárovaného) archivního souboru se importovaná data vloží pod kořenovou úroveň **neuzavřené verze** archivního souboru.
  - **Archivní entity** obsažené v importovaném souboru jsou automaticky **párovány** podle UUID s existujícími archivními entitami.



.. _ug_admin_import-csv:

Nová CSV dávka
=================

Dávka CSV slouží k hromadnému **importu prvků popisu** a doplnění jejich hodnot k již existujícím jednotkám popisu.
Jednotky popisu jsou v souboru identifikovány pomocí svého **UUID**.
Prvky popisu jsou k jednotce popisu vždy přidány, stávající hodnoty nejsou nahrazovány.

Srov. :ref:`Tabulkové zobrazení: Import prvků popisu <ug_arr_table_view_import>`

.. figure:: resources/admin-import-csv.png
    :align: center

    Nový import – CSV


Nastavení dávky
-----------------

Název *
   - libovolný název dávky, pod kterým bude dávka zobrazena v přehledu importů

Oddělovač *
   - znak, kterým jsou v souboru CSV odděleny jednotlivé hodnoty
   - na výběr jsou:

     -  ``;`` (středník, výchozí hodnota),
     -  ``,`` (čárka),
     -  ``tabulátor``,
     -  ``|`` (svislítko)

Kódování *
   - kódování znaků vstupního souboru CSV
   - na výběr jsou:

     - *Windows-1250 (středoevropské)* (výchozí hodnota),
     - *UTF-8*,
     -  *ISO-8859-2 (Latin-2)*,
     -  *Windows-1252 (západoevropské)*

Pokračovat po chybě položky
   - význam je shodný s :ref:`dávkou EDX2 <ug_admin_import-edx2>`

Zachovat vstupní soubory
   - význam je shodný s :ref:`dávkou EDX2 <ug_admin_import-edx2>`

(*) = povinný údaj

Formát souboru CSV
--------------------

Soubor CSV neobsahuje řádek se záhlavím. Každý řádek odpovídá jedné jednotce popisu a má následující strukturu,
pokud je oddělovačem středník:

  ``UUID jednotky popisu;[kód prvku];[kód specifikace];[hodnota];[kód prvku];[...]``

  - první hodnotou na řádku je **UUID jednotky popisu**, ke které budou prvky popisu doplněny
  - následuje libovolný počet dvojic **kód prvku** a **hodnota**
  - u prvků popisu se specifikací se mezi kódem prvku a hodnotou uvádí **kód specifikace**
  - u prvků :ref:`datového typu: <ZP2015_PP_Datove_typy>` *ENUM* se uvádí pouze kód specifikace, který je současně hodnotou
  - u prvků :ref:`datového typu: <ZP2015_PP_Datove_typy>` *RECORD_REF* se jako hodnota uvádí **ID archivní entity**

Kódy prvků a specifikací jsou k dispozici v :ref:`seznamu prvků popisu: <ZP2015_PP_Seznam>` a souvisejících kapitolách.

Podporované :ref:`datové typy <ZP2015_PP_Datove_typy>`:

 - DECIMAL [bude doplněno]
 - ENUM
 - INT
 - RECORD_REF
 - STRING
 - TEXT
 - UNITID
 - URI_REF [bude doplněno]

Ostatní datové typy zatím nejsou podporovány.

.. note::
  - Mezery na začátku a konci hodnot jsou ignorovány. Řádky bez UUID jednotky popisu jsou přeskočeny.
  - Hodnoty prvků popisu se importují do **neuzavřené verze** archivního souboru.


.. _ug_admin_import-list:

Přehled importů
=================

V přehledu je zobrazen seznam všech importních dávek seřazených od nejnověji založené.
Kliknutím na řádek se otevře **detail dávky**. Přehled se při změně stavu dávky automaticky aktualizuje.

Seznam obsahuje tyto sloupce:

Název
   - název dávky zadaný při jejím založení

Druh
   - druh importní dávky:

     - ``EDX2`` – import archivních souborů ze souborů EDX2
     - ``ADD_DESC_ITEMS_CSV`` – import prvků popisu ze souboru CSV

Stav
   - aktuální :ref:`stav <ug_admin_import-states>` dávky

Spuštěno
   - datum a čas posledního spuštění dávky (včetně testovacího běhu)

Dokončeno
   - datum a čas ukončení zpracování dávky
   - údaj je zobrazen pouze u dávek ve stavu ``FINISHED``, ``FAILED`` nebo ``CANCELLED``

V zápatí seznamu je možné přecházet mezi stránkami pomocí tlačítek *Předchozí* a *Další*
a nastavit počet zobrazených záznamů na stránku (10, 25 nebo 50).


.. note::
    U importu spuštěného z modulu :ref:`Archivní soubory: Import ze souboru <ug_arr_intro_import>`
    je dávka založena automaticky a jejím názvem je název importovaného souboru.


.. _ug_admin_import-states:

Stavy dávky
-------------

.. list-table::
 :header-rows: 1

 * - Stav
   - Význam
 * - ``PREPARATION``
   - Dávka je založena a připravena k vložení vstupních souborů a ke spuštění.
 * - ``TEST_IN_PROGRESS``
   - Probíhá testovací běh dávky.
 * - ``TEST_FINISHED``
   - Testovací běh byl dokončen. Dávku je možné spustit nebo do ní vložit další soubory (dávka se tím vrátí do stavu ``PREPARATION``).
 * - ``IN_PROGRESS``
   - Probíhá import dávky.
 * - ``PAUSED``
   - Import byl pozastaven uživatelem nebo restartem serveru. Zpracování je možné znovu spustit, pokračuje se nezpracovanými položkami.
 * - ``FINISHED``
   - Import všech položek dávky byl úspěšně dokončen.
 * - ``FAILED``
   - Zpracování alespoň jedné položky skončilo chybou. Dávku je možné znovu spustit, zpracovány budou chybové a dosud nezpracované položky.
 * - ``CANCELLED``
   - Dávka byla přerušena uživatelem a nelze ji znovu spustit.

.. note::
  - Pozastavení i přerušení dávky se projeví až po dokončení právě zpracovávané položky.
  - Dávku ve stavu ``IN_PROGRESS`` nebo ``TEST_IN_PROGRESS`` nelze smazat. Smazáním dávky jsou odstraněny i její vstupní soubory.
