4.7. Integrace

Napojení na další systémy se nastavuje v modulu Administrace > Externí systémy (viz Externí systémy). 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 CAM),

  • úložiště digitalizátů - úložiště digitálních objektů a digitální archivy (AIP) (viz Úložiště digitalizátů a digitální archiv),

  • systémy GIS - mapové servery pro zobrazení a editaci souřadnic (viz Mapové servery),

  • 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 Správa publikačních systémů).

Todo

Poskytovatelé AI a publikační systémy: nastavení a jejich význam. Doplnit nejprve v anglické příručce.

4.7.1. 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 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 Monitorování.

TLS certifikát

Volba Ověřovat TLS certifikát externího systému určuje, jak se kontroluje certifikát CAM:

  • Ano (výchozí pro nový systém) - certifikát i název serveru se ověřují obvyklým způsobem.

  • 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). Podepsané požadavky pak nejsou chráněny proti útoku man-in-the-middle; raději přidejte certifikát serveru do úložiště důvěryhodných certifikátů (truststore) Javy, pod kterou Elza běží.

Externím systémům založeným před verzí Elza 3.4.12 nastaví aktualizace Ne, protože certifikát CAM se dříve nikdy neověřoval. Má-li CAM platný certifikát, přepněte volbu na Ano.

Změna CAM na CAM kompletní

  1. V nastavení externího systému vyberte oblast pro ukládání entit.

  2. Zastavte Elzu.

  3. Změňte typ v databázi, například při existenci jediného externího systému:

    UPDATE ap_external_system SET type = 'CAM_COMPLETE';
    

    U systému s rozhraním verze 2 použijte CAM_COMPLETE_V2.

  4. 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.

  5. 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 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ář /etc/crypto-policies/back-ends/) se algoritmus obvykle povolí příkazem update-crypto-policies --set DEFAULT:SHA1; ověřte v dokumentaci distribuce.

4.7.2. 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 Konfigurace aplikace). Mapové podklady mapy.cz jsou z licenčních důvodů k dispozici jen jako samostatná služba.

4.7.3. 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 API (REST).

Integrace by se měly ověřovat osobním API klíčem v hlavičce X-API-Key, nikoli heslem uživatele (viz Autentizace a zabezpečení).

4.7.4. 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 API (WSDL). 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 Konfigurace aplikace).

4.7.5. Vstupní URL

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

<ELZA_URL>/node/<UUID>

Jednotka popisu podle jejího UUID.

<ELZA_URL>/entity/<UUID> nebo <ELZA_URL>/entity/<ID>

Archivní entita podle UUID nebo databázového ID (rozpozná se automaticky).

<ELZA_URL>/entity/<KOD_EXT_SYSTEMU>-<EXT_ID>

Archivní entita podle identifikátoru v externím systému, například /entity/CAM-100.

<ELZA_URL>/da/<KOD_DA>/aip/<AIP_ID>

AIP podle kódu digitálního archivu (kódu externího systému v ELZA) a identifikátoru, který mu přidělil digitální archiv, ne podle ID v ELZA. UUID se přijme s předponou uuid- i bez ní. Je-li na AIP (nebo jeho část) napojena právě jedna jednotka popisu, otevře se ona. Jinak se otevře balíček v jeho archivním souboru, kde jsou napojené jednotky vypsány a balíček lze napojit. AIP, jehož archivní soubor ELZA nezná, se otevře v seznamu AIP. Pokud ELZA AIP ještě nepřijala, uživatel dostane zprávu, že v ELZA není.

Nepovinné ?part=<ID> vybere část balíčku, například úroveň jeho logické struktury: otevře se jednotka popisu napojená na tuto část, nemá-li část vlastní, pak jednotka napojená na celý balíček. Jinak se část vybere ve struktuře balíčku.

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

<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):

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

4.7.6. Integrační skript

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

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í:

function renderIntegrationHeader(headerElement){
    if(versionNumber){
        headerElement.style.backgroundColor = "#f00";
        headerElement.style.color = "#fff";
        headerElement.style.padding = "0.5em";
        headerElement.style.fontWeight = "bold";
        headerElement.style.fontSize = "2em";
        headerElement.style.lineHeight = "1em";

        const footerContent = document.createElement("span");
        footerContent.textContent = "TEST";
        headerElement.appendChild(footerContent);
    }
}

Příklad funkce pro zápatí:

function renderIntegrationFooter(footerElement){
    if(versionNumber){
        footerElement.style.backgroundColor = "#333";
        footerElement.style.color = "#fff";
        footerElement.style.padding = "0.5em";
        footerElement.style.textAlign = "right";
        footerElement.style.fontWeight = "bold";
        footerElement.style.fontSize = "1em";
        footerElement.style.lineHeight = "1em";

        const footerContent = document.createElement("span");
        footerContent.textContent = "Verze aplikace: " + versionNumber;
        footerElement.appendChild(footerContent)
    }
}