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

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

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

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:
```
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 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.

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