.. include:: /icons.rst

.. _ug_ap_synchronization:

============================
Synchronizace entit
============================

Záznamy archivních entit v Elza je možné stahovat, odesílat nebo
uvádět do souladu s jinými informační systémy (zejména CAM).

Instance Elza může komunikovat s více :ref:`externími systémy <ug_admin_external-systems>` najednou,
ale jednotlivé záznamy archivních entit mohou být za účelem
sjednocení (synchronizace) aktivně napojené pouze na jeden externí systém,
který je označen v :ref:`administraci <ug_admin_external-systems>` jako prioritní.

Synchronizace probíhá automaticky dle nastavení
:ref:`integrace <cam_settings>` nebo ručně pomocí uživatelského rozhraní
v modulu *Archivní entity*.

Dostupné akce z menu v :ref:`horním panelu <ug_ap_screen_menu>`:

 |cloud-download| Import ze systému
  - Umožňuje vyhledat entity podle různých kritérií a převzít je do zvolené :ref:`oblasti <ug_ap_scopes>`.

 |link1| Fronta synchronizace
  - Nabízí přehled o aktualizaci, stažení nebo odeslání konkrétních entit, které je možné vyhledávat dle externího systému, :ref:`oblasti <ug_ap_scopes>` a stavu ve :ref:`frontě synchronizace <ug_ap_synchronization_queue>`.

Dostupné akce ze :ref:`záhlaví entity <ug_ap_screen_main_head>`:

 |cloud-upload| Zápis entity do externího systému
  - Umožňuje zapsat entitu do :ref:`externího systému <ug_admin_external-systems>`. 

 |floppy-o| Zapsat změny
  - Zapíše lokální změny entity v instanci Elza do :ref:`externího systému <ug_admin_external-systems>`. 


.. _ug_ap_synchronization_ID_UUID:

Každá entita v systému CAM má jedinečné ID a UUID,
které mimo jiné brání opětovnému stažení do Elza a vzniku :ref:`duplicitních záznamů <ug_ap_duplications>`.


.. image:: resources/vyhledavani_v_ext_sys.png
      :align: center

.. note::
   Některé situace, kdy v jedné instanci Elza existují entity napojené
   na více :ref:`externích systémů <ug_admin_external-systems>` a není možné
   je vzájemně :ref:`synchronizovat <ug_ap_synchronization>` a jednoduše :ref:`deduplikovat <ug_ap_duplications>`,
   lze řešit pomocí funkcionality :ref:`Kopie entity <ug_ap_copies>`.


.. _ug_ap_connected:

Napojené entity
=================

V případě napojení archivní entity na jiný systém je v jejím :ref:`záhlaví <ug_ap_screen_main_head>`
k dispozici citace zdroje včetně ID, UUID a identifikace zapisovatele poslední změny do externího systému,
a dále funkční tlačítko |dots| pro jednotlivé akce synchronizace.

.. image:: resources/zahlavi.png
      :align: center

S napojenými entitami je možné v závislosti na jejich obsahu a
:ref:`stavu synchronizace <ug_ap_synchronization_state>` provádět tyto **akce**:

*Aktualizace údajů z externího systému*
 - Převezme změny z externího systému do instance Elza.

*Zápis změn do externího systému*
  - Zapíše lokální změny entity v instanci Elza do externího systému.

*Převzetí napojených entit*
  - Převezme z externího systému :ref:`související entity <ug_ap_edit_related>` napojené k dané entitě a založí jejich záznamy v instanci Elza, pokud nebyly již dříve staženy.

Oprávnění uživatelů k výše popsaným akcím se přidělují v :ref:`administraci <ug_admin_perms>`.

Vazbu archivní entity na externí systém nelze zrušit.
Řešením je vytvoření entity nové v instanci Elza a
:ref:`zneplatnění <ug_ap_invalidations>` té napojené.
Případné odeslání takovéto entity do stejného externího systému může
být zablokováno kontrolou bránící vzniku :ref:`duplicitních záznamů <ug_ap_duplications>`.

U entit, které jsou zapsány v systému CAM, není možné měnit :ref:`třídu a podtřídu entity <ug_ap_access_point_class>`.


.. _ug_ap_synchronization_state:

Stavy synchronizace
=====================

Aktuální stav synchronizace entity mezi instancí ELZA a externím systémem
je znázorněn jak v :ref:`záhlaví entity <ug_ap_screen_main_head>`, tak u jednotlivých prvků popisu
barevnými symboly s tímto významem a důsledky:

 |green| Aktivní synchronizace (zelený) = optimální stav
  - popis entity v instanci Elza i externím systému je shodný
  - probíhá automatická aktualizace z externího systému dle nastavení integrace / serveru

 |yellow| Existuje lokální změna (žlutý) = dočasný stav
  - **řešení**: akce :ref:`Zápis změn do externího systému <ug_ap_connected>`
  - v instanci Elza existuje novější verze entity se změněným popisem
  - automatická aktualizace z externího systému je zastavena a opětovně spuštěna až akcí :ref:`Zápis změn do externího systému <ug_ap_connected>` (při použití akce :ref:`Aktualizace údajů z externího systému <ug_ap_connected>` v této situaci k opětovné aktivaci synchronizace nedojde, pokud se lokální změny vyskytují u nově vytvořených částí popisu, a zároveň může dojít ke ztrátě případných lokálních změn u částí popisu, které jsou ruční aktualizací opětovně převzaty z externího systému)

 |red| Nesynchronizuje se (červený) = nechtěný stav
  - **řešení**: akce :ref:`Aktualizace údajů z externího systému <ug_ap_connected>`
  - v instanci Elza i externím systému existují novější verze entity se změněným popisem
  - automatická aktualizace z externího systému neprobíhá a spustí se znovu až akcí :ref:`Aktualizace údajů z externího systému <ug_ap_connected>` (akce :ref:`Zápis změn do externího systému <ug_ap_connected>` není možná)

.. warning::
  Části popisu (party) existující v Elza a následně změněné v externím systému jsou po
  provedení akce :ref:`Aktualizace údajů z externího systému <ug_ap_connected>` **převzaty z externího systému**.
  Případné změny těchto částí popisu provedené souběžně v Elza jsou aktualizací **ztraceny**
  (v Elza jsou zachovány původní části popisu, které nebyly po odeslání entity do externího systému změněny,
  a dále ty, které byly v Elza nově vytvořeny).


Po zneplatnění nebo nahrazení entity ve stavu *Aktivní synchronizace* provedeném v externím systému
dojde k jejímu :ref:`zneplatnění <ug_ap_invalidations>` nebo :ref:`nahrazení <ug_ap_duplications>` také v Elza.
Pokud v Elza není k dispozici nahrazující entita (ve stavu *Aktivní synchronizace*),
entita odstraněná v externím systému zůstane v Elza ve stavu *nahrazená*
a odstranění případné duplicity je třeba provést přímo v instanci Elza.

Podrobnější informace viz :ref:`Zneplatnění a externí systémy <ug_ap_invalidations_synchronization>` a :ref:`Odstraňování duplicit <ug_ap_duplications>`.


.. _ug_ap_synchronization_related:

Synchronizace a související entity
======================================

Při synchronizaci archivních entit je třeba věnovat zvláštní pozornost entitám,
které jsou napojeny k záznamům entit pomocí vztahů (:ref:`související entity <ug_ap_edit_related>`).

Pokud záznam archivní entity obsahuje :ref:`související entitu <ug_ap_edit_related>`,
která **je k dispozici** v daném externím systému,
je při akci :ref:`Zápis entity do externího systému <ug_ap_synchronization>`
odeslán záznam archivní entity včetně tohoto vztahu
a výsledkem je návazná entita ve stavu :ref:`Aktivní synchronizace <ug_ap_synchronization_state>`.

Pokud záznam archivní entity obsahuje :ref:`související entitu <ug_ap_edit_related>`,
která **není k dispozici** v daném externím systému,
je při akci :ref:`Zápis entity do externího systému <ug_ap_synchronization>`
odeslán záznam archivní entity bez tohoto vztahu
a výsledkem je návazná entita ve stavu :ref:`Lokální změna <ug_ap_synchronization_state>`.

Pro dosažení stavu :ref:`Aktivní synchronizace <ug_ap_synchronization_state>`
je třeba do externího systému odeslat také veškeré :ref:`související entity <ug_ap_edit_related>`
(akce :ref:`Zápis entity do externího systému <ug_ap_synchronization>`)
a v případě potřeby u návazných entit ve stavu :ref:`Lokální změna <ug_ap_synchronization_state>`
následně provést jejich **dodatečné odeslání** do externího systému
(akce :ref:`Zápis změn do externího systému <ug_ap_connected>`).


Postupy synchronizace
------------------------

**Entita A (návazná)**
  -> vztah k entitě B

**Entita B (související)**

Ideální postup:
 1.	:ref:`Zápis entity <ug_ap_synchronization>` **B** do externího systému => **Aktivní synchronizace entity B**
 2.	:ref:`Zápis entity <ug_ap_synchronization>` **A** do externího systému => **Aktivní synchronizace entity A**

Variantní postup:
 1.	:ref:`Zápis entity <ug_ap_synchronization>` **A** do externího systému => Lokální změna entity A
 2.	:ref:`Zápis entity <ug_ap_synchronization>` **B** do externího systému => **Aktivní synchronizace entity B**
 3.	:ref:`Zápis změny <ug_ap_connected>` entity **A** do externího systému => **Aktivní synchronizace entity A**


**Entita C (návazná + související)**
  -> vztah k entitě D

**Entita D (návazná + související)**
  -> vztah k entitě C

Postup:
 1.	:ref:`Zápis entity <ug_ap_synchronization>` **C** do externího systému => Lokální změna entity C
 2.	:ref:`Zápis entity <ug_ap_synchronization>` **D** do externího systému => **Aktivní synchronizace entity D**
 3.	:ref:`Zápis změny <ug_ap_connected>` entity **C** do externího systému => **Aktivní synchronizace entity C**


.. note::
  Pro vyhodnocení :ref:`stavu synchronizace <ug_ap_synchronization_state>` návazné entity hraje roli to,
  zda je :ref:`související entita <ug_ap_edit_related>` aktuálně dostupná v externím systému,
  nikoli stav synchronizace související entity v Elza.
  Související entita ve stavu :ref:`Lokální změna <ug_ap_synchronization_state>` proto nebrání aktivní synchronizaci návazné entity,
  pokud byla úspěšně :ref:`zapsána <ug_ap_synchronization>` do externího systému.

.. warning::
  Akce :ref:`Zápis entity do externího systému <ug_ap_synchronization>` skončí :ref:`chybou <ug_ap_synchronization_queue>`,
  pokud záznam odesílané entity obsahuje :ref:`související entitu <ug_ap_edit_related>`,
  která není k dispozici v cílovém externím systému a popis jejího vztahu k odesílané entitě uvádí další prvky popisu
  (*Datace vztahu od*, *Datace vztahu do*, *Poznámka*).
  Řešením je předchozí odeslání souvisejících entit dle postupu výše.



.. _ug_ap_synchronization_limit:

Omezení synchronizace dle stavů entit
=======================================

Výše zmíněné akce synchronizace jsou omezeny :ref:`stavy <ug_ap_state>` příslušných entit. 

Záznamy entit ve stavu *ke schválení* a záznamy entit s :ref:`vytvořenou revizí <ug_ap_revisions_editor-create>`
nelze aktualizovat z externího systému (:ref:`Aktualizace údajů z externího systému <ug_ap_connected>`),
a to ani v rámci automatické aktualizace.

Do :ref:`externího systému <ug_admin_external-systems>` je možné zapsat záznamy entit (:ref:`Zápis entity do externího systému <ug_ap_synchronization>`),
popřípadě jejich změny (:ref:`Zápis změn do externího systému <ug_ap_connected>`)
pouze v případě entit ve stavu *nová*, *k doplnění* a *schválená*.

Entity ve stavu *ke schválení* (:ref:`Zápis entity do externího systému <ug_ap_synchronization>`)
nebo nepotvrzené změny záznamů entit, uskutečněné
v :ref:`režimu revize <ug_ap_revisions_editor>` (:ref:`Zápis změn do externího systému <ug_ap_connected>`)
není možné odeslat do externího systému.

V :ref:`administraci <ug_admin_external-systems-edit>` lze volitelně nastavit,
aby byly do externího systému odesílány pouze entity ve stavu *schválená*.

.. _ug_ap_synchronization_queue:

Fronta synchronizace s externími systémy
=========================================

Informace o stavu komunikace s externími systémy,
stažení, odeslání nebo aktualizaci konkrétních entit
jsou k dispozici v přehledu *Fronta synchronizace*
v nabídce :ref:`horního panelu <ug_ap_screen_menu>`.

Rozlišují se následující stavy entit ve frontě (příklady ve vztahu k CAM):

*K aktualizaci*
 - entita existující v Elza i CAM, čekající na aktualizaci do Elza

*Ke stažení*
 - entita existující v CAM, čekající na stažení do Elza

*Aktualizováno / Staženo*
 - informace o úspěšném načtení záznamu o entitě z CAM
 - v závislosti na :ref:`omezení synchronizace dle stavů entit <ug_ap_synchronization_limit>` se může jednat o případy:
  
   - entita existující v Elza i CAM, úspěšně aktualizovaná do Elza
   - entita existující v CAM, úspěšně stažená do Elza

*K odeslání*
 - entita existující pouze v Elza, čekající na odeslání do CAM
 - entita existující v Elza i CAM, čekající na aktualizaci do CAM

*Odesláno*
 - entita existující pouze v Elza, úspěšně odeslaná do CAM
 - entita existující v Elza i CAM, úspěšně aktualizovaná do CAM

*Chyba*
 - entity, kde došlo k technickému selhání komunikace s externím systémem (při aktualizaci, stažení nebo odeslání entity)

.. image:: resources/synchronizace_s_ext_sys.png
      :align: center


.. note::
  Bezprostředně po odeslání entity nebo zápisu jejích změn do CAM (stav *Odesláno*)
  dochází v závislosti na nastavení integrace s externím systémem
  ke zpětnému stažení informací o zápisu entity do CAM (stav *Aktualizováno / Staženo*).
  Příslušnou entitu lze proto najít ve frontě synchronizace v důsledku jednoho požadavku pod oběma stavy.
  Stav *Aktualizováno / Staženo* obecně zahrnuje případy úspěšného načtení informace o záznamu entity
  z CAM bez ohledu na to, zda došlo ke stažení nebo aktualizaci (změně) záznamu entity.
