.. Zdroj: elza/docs/admin-guide/source/07-integrations.rst, elza e87a93d6d1

.. _admin_integrations:

=========
Integrace
=========

Napojení na další systémy se nastavuje v modulu *Administrace* >
*Externí systémy* (viz :ref:`ug_admin_external-systems`). Každý externí
systém má kód, název, URL a podle své třídy přístupové údaje a další
nastavení. Třídy jsou:

- **systémy pro archivní entity** - CAM a systémy se shodným rozhraním,
  pro sdílení archivních entit (viz :ref:`cam`),
- **úložiště digitalizátů** - úložiště digitálních objektů a digitální
  archivy (AIP),
- **systémy GIS** - mapové servery pro zobrazení a editaci souřadnic (viz
  :ref:`mapserver`),
- **poskytovatelé AI** - služba, na které stojí AI asistent.

Publikační systémy, do kterých se předává publikovaný archivní popis, se
spravují v modulu *Archivní soubory* (*Správa publikačních systémů*, viz
:ref:`ug_arr_publication_admin`).

.. todo::

   Úložiště digitalizátů a digitální archiv (synchronizace AIP, způsoby
   stahování, souborová úložiště), poskytovatelé AI a publikační systémy:
   nastavení a jejich význam. Doplnit nejprve v anglické příručce.

.. _cam:
.. _cam_settings:

CAM
===

Elza sdílí archivní entity s Centrálním archivním modulem (CAM)
Národního archivního portálu a s dalšími systémy, které implementují jeho
rozhraní.

Typy napojení
-------------

Typ se volí při zakládání externího systému:

- **CAM** - standardní rozhraní CAM; entity se párují podle číselného
  CAM ID. Lokálně se kopírují jen entity použité v Elze.
- **CAM kompletní** - jako CAM, ale všechny entity uložené v CAM se
  automaticky stahují a udržují jako lokální kopie. Vyžaduje oblast pro
  stažené entity.
- **CAM UUID** - pro jiné informační systémy s rozhraním CAM, které jako
  primární identifikátor používají UUID.

Každý typ existuje pro verzi 1 i verzi 2 rozhraní CAM (``CAM_V2``,
``CAM_COMPLETE_V2``, ``CAM_UUID_V2``). Verze 2 navíc poskytuje varování a
chyby hlášené CAM a historii revizí entity.

Typ nelze později změnit, protože na něm závisí uložené vazby. Jedinou
výjimkou je změna z CAM na CAM kompletní (viz níže).

Interval synchronizace
----------------------

Interval mezi kontrolami změn v CAM se nastavuje u externího systému
(v sekundách) a projeví se bez restartu. Vhodnou hodnotou pro testovací
i produkční instanci CAM je pět minut (300 sekund). Dřívější nastavení
v :file:`elza.yaml` (``elza.accesspoints.sync``) se již nepoužívá; jeho
hodnoty se při aktualizaci na verzi 3.4 přenesly do externích systémů.

Stav fronty synchronizace lze sledovat metrikami popsanými v kapitole
:doc:`08-monitorovani`.

.. _cam_changetype:

Změna CAM na CAM kompletní
--------------------------

#. V nastavení externího systému vyberte oblast pro ukládání entit.
#. Zastavte Elzu.
#. Změňte typ v databázi, například při existenci jediného externího
   systému:

   .. code-block:: sql

      UPDATE ap_external_system SET type = 'CAM_COMPLETE';

   U systému s rozhraním verze 2 použijte ``CAM_COMPLETE_V2``.
#. Pokud tabulka ``ap_binding_sync`` obsahuje záznam pro daný externí
   systém, nastavte jeho poslední transakci na výchozí hodnotu
   ``91812cb8-3519-4f78-b0ec-df6e951e2c7c``, aby se stáhly všechny entity.
   Bez záznamu není nutné nic měnit.
#. Spusťte Elzu.

Java a starší certifikáty
-------------------------

Současné distribuce Javy odmítají certifikáty podepsané staršími
algoritmy. Pokud spojení s CAM selže s chybou::

   java.security.cert.CertPathValidatorException: Algorithm constraints check failed on signature algorithm: SHA1withRSA

povolte algoritmus v bezpečnostním nastavení Javy: v souboru
:file:`java.security` instalace Javy, nebo v jeho lokální kopii předané
parametrem ``-Djava.security.properties=<soubor>``. V distribucích
s celosystémovými kryptografickými politikami (Red Hat a odvozené
distribuce, openSUSE; existuje adresář
:file:`/etc/crypto-policies/back-ends/`) se algoritmus obvykle povolí
příkazem ``update-crypto-policies --set DEFAULT:SHA1``; ověřte
v dokumentaci distribuce.

.. _mapserver:

Mapové servery
==============

Souřadnice archivních entit a souřadnice v archivním popisu se zobrazují
na mapě. Základní náhled využívá OpenStreetMap. Pokročilejší funkce
poskytuje mapový server, který implementuje mapové rozhraní Elzy
(https://geoedit.lightcomp.cz/doc), a to ve dvou režimech: zobrazení mapy
se souřadnicemi a editace souřadnic s jejich uložením zpět do Elzy. Každý
režim se nastavuje jako samostatný externí systém třídy GIS:

========= =============================================
Pole      Hodnota
========= =============================================
Typ       Zobrazení nebo Editace
Název     například ``mapview``
URL       například ``https://geoedit.lightcomp.cz``
API klíč  volitelně, podle pokynů provozovatele serveru
========= =============================================

Mapové podklady nabízené v editoru souřadnic se nastavují v
``elza.map.layers`` (viz :doc:`04-konfigurace`). Mapové podklady mapy.cz
jsou z licenčních důvodů k dispozici jen jako samostatná služba.

Rozhraní REST
=============

Rozhraní REST je dostupné na adrese ``<ELZA_URL>/api/v1``. Jeho definici
OpenAPI lze procházet v nástroji Swagger UI na adrese
``<ELZA_URL>/swagger``. Popis funkcí je v kapitole :ref:`impl_rest_api`.

Integrace by se měly ověřovat osobním API klíčem v hlavičce
``X-API-Key``, nikoli heslem uživatele (viz :doc:`05-zabezpeceni`).

Webové služby SOAP
==================

Služby SOAP jsou dostupné na adrese ``<ELZA_URL>/services/<služba>``;
WSDL vrací ``<ELZA_URL>/services/<služba>?wsdl``. Definice ke stažení
jsou v kapitole :ref:`impl_wsdl_api`. Služby jsou:

- ``DaoCoreService`` - digitální objekty,
- ``ExportService`` - export archivního popisu,
- ``ImportService`` - import,
- ``FundService`` - archivní soubory a jejich správci,
- ``StructuredObjectService`` - strukturované objekty,
- ``UserService`` - uživatelé.

Digitální objekt zaslaný do Elzy uvádí v atributu ``daoType``, jaký má
vztah k popisu:

``attachment``
   Objekt se připojí ke stávající jednotce popisu.
``level``
   Objekt je sám jednotkou popisu. Jeho připojení k jiné jednotce vytvoří
   novou podřízenou jednotku popisu, která může nést prvky popisu zaslané
   s objektem.

Při aktualizaci archivního souboru službou ``FundService`` se zaslaní
správci přidají ke stávajícím
(``elza.webservice.fonds.adminPermissionMode``, viz :doc:`04-konfigurace`).

.. _impl_entryurl:

Vstupní URL
===========

Záznamy lze otevřít přímo pomocí URL:

.. _impl_entryurl_node:

``<ELZA_URL>/node/<UUID>``
   Jednotka popisu podle jejího UUID.

.. _impl_entryurl_entity:

``<ELZA_URL>/entity/<UUID>`` nebo ``<ELZA_URL>/entity/<ID>``
   Archivní entita podle UUID nebo databázového ID (rozpozná se
   automaticky).

.. _impl_entryurl_entity_extid:

``<ELZA_URL>/entity/<KOD_EXT_SYSTEMU>-<EXT_ID>``
   Archivní entita podle identifikátoru v externím systému, například
   ``/entity/CAM-100``.

.. _impl_entryurl_createentity:

Jiná aplikace může Elzu požádat o založení nové archivní entity:

.. code-block:: text

   <ELZA_URL>/entity-create?response=<návratové URL>&entity-class=<kód třídy>

``response``
   URL, na které se prohlížeč vrátí po dokončení. Může obsahovat proměnné
   ``{status}`` (``SUCCESS`` nebo ``CANCEL``), ``{entityUuid}`` a
   ``{entityId}`` (prázdné, pokud entita nebyla založena). Hodnota musí
   být zakódována pro URL.
``entity-class``
   Nepovinné; omezí novou entitu na třídu, například ``PARTY_GROUP``.

Příklad (před zakódováním pro URL):

.. code-block:: text

   https://elza.archiv.example/entity-create?entity-class=PARTY_GROUP&response=https://is.archiv.example/entity-response?status={status}&entity={entityUuid}

.. _impl_integ_script:

Integrační skript
=================

Pomocí integračního skriptu lze na každou stránku aplikace doplnit vlastní
záhlaví a zápatí:

.. code-block:: yaml

   elza:
     integrationScriptUrl: https://intranet.archiv.example/elza/integrace.js

Skript může definovat funkce ``renderIntegrationHeader(headerElement)`` a
``renderIntegrationFooter(footerElement)``. Elza je volá s prázdným
elementem ``div``, do kterého funkce vykreslí svůj obsah. Skript má
k dispozici globální proměnné ``versionNumber`` (verze Elzy) a
``serverContextPath`` (cesta k aplikaci).

Příklad funkce pro záhlaví:

.. literalinclude:: examples/renderIntegrationHeader.js
   :language: js

Příklad funkce pro zápatí:

.. literalinclude:: examples/renderIntegrationFooter.js
   :language: js
