.. 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=``. 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 ``/api/v1``. Jeho definici OpenAPI lze procházet v nástroji Swagger UI na adrese ``/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 ``/services/``; WSDL vrací ``/services/?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: ``/node/`` Jednotka popisu podle jejího UUID. .. _impl_entryurl_entity: ``/entity/`` nebo ``/entity/`` Archivní entita podle UUID nebo databázového ID (rozpozná se automaticky). .. _impl_entryurl_entity_extid: ``/entity/-`` 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 /entity-create?response=&entity-class= ``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