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í
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_syncobsahuje záznam pro daný externí systém, nastavte jeho poslední transakci na výchozí hodnotu91812cb8-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 |
URL |
například |
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:
attachmentObjekt se připojí ke stávající jednotce popisu.
levelObjekt 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>
responseURL, na které se prohlížeč vrátí po dokončení. Může obsahovat proměnné
{status}(SUCCESSneboCANCEL),{entityUuid}a{entityId}(prázdné, pokud entita nebyla založena). Hodnota musí být zakódována pro URL.entity-classNepovinné; 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)
}
}