3.4. Změny a tvorba entit

API poskytuje sadu funkcí, které umožňují do systému přidávat nové entity, aktualizovat stávající a obohacovat je o další informace. Rozhraní je koncipováno tak, že požadavky na změny či vytvoření záznamu entity se do systému nahrávají ve formě dávek. Dávka může obsahovat jednu nebo více změn.

V REST rozhraní je k dispozici metoda pro vložení nové dávky. Současně jsou k dispozici metody pro zjištění stavu zpracování dávky.

V rámci dávkových operací je možné:

vložit nový záznam entity

vložit část záznamu entity, například: jméno, další identifikátor

přidat prvky popisu do části záznamu

aktualizovat hodnoty prvků popisu

vymazat část záznamu entity nebo jeho prvky popisu

změnit stav záznamu

změnit preferované jméno

změnit třídu/podtřídu entity

3.4.1. Princip dávkového API

Dávkové API umožňuje vložení aktualizační dávky pro provedení změn. Každá dávka je identifikována svým UUID, které je její součástí. Pomocí tohoto UUID je možné zjistit stav zpracování dávky. Pokud byla dávka úspěšně zpracována tak, není možné shodné UUID opakovaně použít pro jinou dávku. Dávka je vždy zpracována jako celek nebo jako celek odmítnuta.

Jednotlivé operace v rámci dávky pracují s právě jedním záznamem entity. Součástí zápisu operace je identifikátor měněné entity a současně lokální identifikátor entity platný v rámci dávky. Pokud se pracuje s již existujícím záznamem, tak se uvádí jeho identifikátor a identifikátor poslední verze tohoto záznamu entity. Úprava stávajícího záznamu entity je možná jen v případě shody identifikátoru poslední verze s aktuálně platnou verzí.

Výsledkem úspěšné dávkové operace je provedení transakce v databázi. Identifikátor proběhlé transakce se vrací jako součást odpovědi. Součástí úspěšné odpovědi jsou identifikátory nově zapsaných entit, pro každý změněný záznam se vrací identifikátor jeho verze po provedení změny.

V případě, kdy se u záznamu entity v rámci jedné dávky provádí více změn, tak se u prvního výskytu uvede jeho identifikátor, číslo revize a jeho relativní ID. Pro další odkazy se použije relativní ID. Příklad použití relativního ID je v části Vymazání části záznamu entity.

3.4.2. Vložení entity

Záznam entity se vkládá pomocí struktury CreateEntity dle XSD schématu.

Příklad založení entity

<?xml version="1.0"?>
<!-- Zdroj: https://digi.ceskearchivy.cz/407075-Hluboka-nad-Vltavou-Ceske-Budejovice-Cesko -->
<c:bu xmlns:c="http://cam.tacr.cz/2019">
 <c:inf bid="36bfb401-3def-477f-9990-de029e2d54db">
   <c:usr>Jan Novák</c:usr>
 </c:inf>
 <c:ce lid="ap1" et="GEO_UNIT">
   <c:prts>
     <c:p t="PT_NAME" pid="09834567-65b3-4b29-aaec-08b49b4f43a6">
       <c:itms>
         <c:si t="NM_MAIN">Hluboká nad Vltavou</c:si>
         <c:si t="NM_SUP_GEO">České Budějovice, Česko</c:si>
         <c:ei t="LANG" s="LNG_cze"/>
       </c:itms>
     </c:p>
     <c:p t="PT_NAME" pid="d0f6ebd1-ec9e-42ee-9145-711baf54f3f3">
       <c:itms>
         <c:si t="NM_MAIN">Frauenberg</c:si>
         <c:si t="NM_SUP_GEO">České Budějovice, Česko</c:si>
         <c:ei t="LANG" s="LNG_ger"/>
       </c:itms>
     </c:p>
     <c:p t="PT_IDENT" pid="34fff909-2075-45d4-b77d-03f7a6768c19">
       <c:itms>
         <c:ei t="IDN_TYPE" s="INTERPI"/>
         <c:si t="IDN_VALUE">n000129262</c:si>
       </c:itms>
     </c:p>
     <c:p t="PT_IDENT" pid="bab5dbf0-d209-4ca6-84ec-e0490f21f88b">
       <c:itms>
         <c:ei t="IDN_TYPE" s="RUIAN"/>
         <c:si t="IDN_VALUE">544485</c:si>
       </c:itms>
     </c:p>
     <c:p t="PT_BODY">
       <c:itms>
         <c:ei t="GEO_TYPE" s="GT_MUNIP"/>
         <c:si t="COORD_POINT">49.0513N, 14.4336E</c:si>
         <c:si t="BRIEF_DESC">obec v okrese České Budějovice</c:si>
       </c:itms>
     </c:p>
   </c:prts>
 </c:ce>
</c:bu>

Odpověď na založení:

<c:bus xmlns:c="http://cam.tacr.cz/2019" trns="3d8608cd-8f68-41d3-860c-56ee51b8e334">
  <c:rev lid="ap1" eid="982" euid="04993189-fa20-48b7-bb18-81a50a02d7e1" rev="7c04837b-3ff2-4ece-8f2c-e20fceb4d619" />
</c:bus>

3.4.3. Vložení části popisu

Částí popisu entity se rozumí označení, další identifikátor, vztah apod. Část popisu se vkládá pomocí struktury Part.

Příklad vložení části

<?xml version="1.0"?>
<!-- Zdroj: https://digi.ceskearchivy.cz/407075-Hluboka-nad-Vltavou-Ceske-Budejovice-Cesko -->
<c:bu xmlns:c="http://cam.tacr.cz/2019">
 <c:inf bid="36bfb401-3def-477f-9990-de029e2d54db">
   <c:usr>Jan Novák</c:usr>
 </c:inf>
 <c:ue>
  <!-- Přidání k entitě, č. 982 -->
  <c:e eid="982" rev="7c04837b-3ff2-4ece-8f2c-e20fceb4d619" lid="e1"/>
  <!-- Přidání variantního jména -->
  <c:nip t="PT_NAME" pid="d0f6ebd1-ec9e-42ee-9145-711baf54f3f3">
   <c:itms>
    <c:si t="NM_MAIN">Frauenberg</c:si>
    <c:si t="NM_SUP_GEO">České Budějovice, Česko</c:si>
    <c:ei t="LANG" s="LNG_ger" uuid="350fad04-2d6b-459f-9471-4f02b79070d7" />
   </c:itms>
  </c:nip>
 </c:ue>
</c:bu>

3.4.4. Přidání prvků popisu

Pomocí struktury NewItems je možné přidat prvky popisu do dané části záznamu entity.

Příklad vložení prvků popisu

<?xml version="1.0"?>
<!-- Zdroj: https://digi.ceskearchivy.cz/407075-Hluboka-nad-Vltavou-Ceske-Budejovice-Cesko -->
<c:bu xmlns:c="http://cam.tacr.cz/2019">
 <c:inf bid="36bfb401-3def-477f-9990-de029e2d54db">
   <c:usr>Jan Novák</c:usr>
 </c:inf>
 <c:ue>
  <!-- Přidání k entitě, č. 982 -->
  <c:e eid="982" rev="7c04837b-3ff2-4ece-8f2c-e20fceb4d619" lid="e1"/>
  <!-- Přidání jazyku k variantnímu jménu -->
  <c:nis t="PT_NAME" pid="d0f6ebd1-ec9e-42ee-9145-711baf54f3f3">
    <c:ei t="LANG" s="LNG_ger" uuid="350fad04-2d6b-459f-9471-4f02b79070d7" />
  </c:nis>
 </c:ue>
</c:bu>

3.4.5. Aktualizace hodnot prvků popisu

Pomocí struktury UpdateItems je možné aktualizovat hodnoty prvků popisu. Aktualizovat je možné hodnoty jen u existujících prvků popisu. Pomocí aktualizace hodnot je možné také k prvku popisu přidat jeho UUID. Pro změnu hodnot opakovatelných prvků popisu musí být vždy nastaveno jejich UUID.

Pokud je prvku popisu přiděleno UUID, tak toto UUID je pevné a dále neměnné.

Příklad aktualizace prvků popisu

<?xml version="1.0"?>
<!-- Zdroj: https://digi.ceskearchivy.cz/407075-Hluboka-nad-Vltavou-Ceske-Budejovice-Cesko -->
<c:bu xmlns:c="http://cam.tacr.cz/2019">
 <c:inf bid="36bfb401-3def-477f-9990-de029e2d54db">
   <c:usr>Jan Novák</c:usr>
 </c:inf>
 <c:ue>
  <!-- Aktualizace entity, č. 982 -->
  <c:e eid="982" rev="7c04837b-3ff2-4ece-8f2c-e20fceb4d619" lid="e1"/>
  <!-- Změna jazyku u variantního jména -->
  <c:uis t="PT_NAME" pid="d0f6ebd1-ec9e-42ee-9145-711baf54f3f3">
    <c:ei t="LANG" s="LNG_cze" uuid="350fad04-2d6b-459f-9471-4f02b79070d7" />
  </c:uis>
 </c:ue>
</c:bu>

3.4.6. Vymazání části záznamu entity

Vymazat je možné část záznamu entity nebo jeho vybrané prvky popisu.

Příklad vymazání části

<?xml version="1.0"?>
<!-- Zdroj: https://digi.ceskearchivy.cz/407075-Hluboka-nad-Vltavou-Ceske-Budejovice-Cesko -->
<c:bu xmlns:c="http://cam.tacr.cz/2019">
 <c:inf bid="36bfb401-3def-477f-9990-de029e2d54db">
   <c:usr>Jan Novák</c:usr>
 </c:inf>
 <c:ue>
  <!-- Vymazání části entity, č. 982 -->
  <c:e eid="982" rev="7c04837b-3ff2-4ece-8f2c-e20fceb4d619" lid="e1"/>
  <!-- Vymazání jazyku u variantního jména -->
  <c:dis t="PT_NAME" pid="d0f6ebd1-ec9e-42ee-9145-711baf54f3f3">
    <c:ir t="LANG" uuid="350fad04-2d6b-459f-9471-4f02b79070d7" />
  </c:dis>
 </c:ue>
 <c:ue>
  <!-- Vymazání části entity, č. 982, ref na e1 -->
  <c:lid>e1</c:lid>
  <!-- Vymazání variantního jména -->
  <c:dp t="PT_NAME" pid="d0f6ebd1-ec9e-42ee-9145-711baf54f3f3" />
 </c:ue>
</c:bu>

3.4.7. Změna stavu záznamu entity

U záznamu entity je možné změnit její stav. Stavy entity jsou popsané v části Stavy. Přechod mezi stavy je možný v závislosti na nastavení oprávnění uživatele.

Příklad změny stavu

<?xml version="1.0"?>
<!-- Zdroj: https://digi.ceskearchivy.cz/407075-Hluboka-nad-Vltavou-Ceske-Budejovice-Cesko -->
<c:bu xmlns:c="http://cam.tacr.cz/2019">
 <c:inf bid="36bfb401-3def-477f-9990-de029e2d54db">
   <c:usr>Jan Novák</c:usr>
 </c:inf>
 <c:ue>
  <!-- Změna stavu AP, č. 982 -->
  <c:e eid="982" rev="7c04837b-3ff2-4ece-8f2c-e20fceb4d619" lid="e1"/>
  <!-- Schválení entity -->
  <c:srs>
    <c:rs>ERS_APPROVED</c:rs>
  </c:srs>
 </c:ue>
</c:bu>

3.4.8. Změna preferovaného jména

Příklad změny preferovaného jména

<?xml version="1.0"?>
<!-- Zdroj: https://digi.ceskearchivy.cz/407075-Hluboka-nad-Vltavou-Ceske-Budejovice-Cesko -->
<c:bu xmlns:c="http://cam.tacr.cz/2019">
 <c:inf bid="36bfb401-3def-477f-9990-de029e2d54db">
   <c:usr>Jan Novák</c:usr>
 </c:inf>
 <c:ue>
  <!-- Změna preferovaného jména entity, č. 982 -->
  <c:e eid="982" rev="7c04837b-3ff2-4ece-8f2c-e20fceb4d619" lid="e1"/>
  <!-- Nastavení preferovaného jména -->
  <c:spfn>d0f6ebd1-ec9e-42ee-9145-711baf54f3f3</c:spfn>
 </c:ue>
</c:bu>

3.4.9. Změna třídy/podtřídy

Příklad změny podtřídy entity

<?xml version="1.0"?>
<!-- Zdroj: https://digi.ceskearchivy.cz/407075-Hluboka-nad-Vltavou-Ceske-Budejovice-Cesko -->
<c:bu xmlns:c="http://cam.tacr.cz/2019">
 <c:inf bid="36bfb401-3def-477f-9990-de029e2d54db">
   <c:usr>Jan Novák</c:usr>
 </c:inf>
 <c:ue>
  <!-- Změna třídy/podřídy entity, č. 982 -->
  <c:e eid="982" rev="7c04837b-3ff2-4ece-8f2c-e20fceb4d619" lid="e1"/>
  <!-- Nastavení podtřídy -->
  <c:set>ARMY</c:set>
 </c:ue>
</c:bu>