3.5. 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.5.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.

Uložení s varováním

Při zpracování změnové dávky může dojít k situaci, kdy zaslaná změna není v souladu s pravidly, avšak přesto se nejedná o chybu. Odpovědí na takovou změnu je její neuložení a předání s varování. Změnovou dávku je možné uložit přes uvedené varování a to opakovaným zasláním identické dávky s parametrem forceKey='hodnota z odpovědi'.

Podrobnější informace o zjištěních a varováních je popsáno v části Zjištění v rámci změn.

Uživatelé

Při ukládání změn do systému je možné u každé změny uvést uživatele, který změnu provedl. Uživatel je identifikován svým identifikátorem v rámci zdrojového systému z něhož je záznam odesílán. Pokud shodný uživatel provede více změn, vždy je nutné ho identifikovat shodným způsobem a to i napříč různými dávkami včase. U uživatele se dále uvede jeho jméno v souladu s provozním řádem systému. Pokud jedno komunikační rozhraní slouží pro více archivů (institucí), tak je nutné také uvést identifikátor archivu, který změnu provedl. Dalším volitelnými údaji jsou:

• odkaz na archivní entitu uživatele

• UUID uživatele pro jeho identifikaci v rámci systému

Uživatelé mohou vystupovat v rolích:

• odesílatel dávky (změny)

• autor změny

• schvalovatel změny

3.5.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"?>
<batchUpdate xmlns="http://cam.tacr.cz/2025">
 <info uuid="36bfb401-3def-477f-9990-de029e2d54db">
  <sender>
    <id>9987</id>
    <name>Jan Novák</name>
  </sender>
 </info>
 <createEntity localId="ap1" entityType="GEO_UNIT">
   <parts>
     <part type="PT_NAME" partUuid="09834567-65b3-4b29-aaec-08b49b4f43a6">
       <items>
         <string type="NM_MAIN">Hluboká nad Vltavou</string>
         <string type="NM_SUP_GEO">České Budějovice, Česko</string>
         <enum type="LANG" spec="LNG_cze"/>
       </items>
     </part>
     <part type="PT_NAME" partUuid="d0f6ebd1-ec9e-42ee-9145-711baf54f3f3">
       <items>
         <string type="NM_MAIN">Frauenberg</string>
         <string type="NM_SUP_GEO">České Budějovice, Česko</string>
         <enum type="LANG" spec="LNG_ger"/>
       </items>
     </part>
     <part type="PT_IDENT" partUuid="34fff909-2075-45d4-b77d-03f7a6768c19">
       <items>
         <enum type="IDN_TYPE" spec="INTERPI"/>
         <string type="IDN_VALUE">n000129262</string>
       </items>
     </part>
     <part type="PT_IDENT" partUuid="bab5dbf0-d209-4ca6-84ec-e0490f21f88b">
       <items>
         <enum type="IDN_TYPE" spec="RUIAN"/>
         <string type="IDN_VALUE">544485</string>
       </items>
     </part>
     <part type="PT_BODY">
       <items>
         <enum type="GEO_TYPE" spec="GT_MUNIP"/>
         <string type="COORD_POINT">49.0513N, 14.4336E</string>
         <string type="BRIEF_DESC">obec v okrese České Budějovice</string>
       </items>
     </part>
   </parts>
 </createEntity>
</batchUpdate>

Odpověď na založení:

<batchChangeSuccess xmlns="http://cam.tacr.cz/2025" transaction="3d8608cd-8f68-41d3-860c-56ee51b8e334">
  <revision localId="ap1" entityId="982" enityUuid="04993189-fa20-48b7-bb18-81a50a02d7e1" rev="7c04837b-3ff2-4ece-8f2c-e20fceb4d619" />
</batchChangeSuccess>

3.5.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"?>
<batchUpdate xmlns="http://cam.tacr.cz/2025">
 <info uuid="36bfb401-3def-477f-9990-de029e2d54db">
  <sender>
    <id>9987</id>
    <name>Jan Novák</name>
  </sender>
 </info>
 <updateEntity>
  <!-- Přidání k entitě, č. 982 -->
  <entity entityId="982" rev="7c04837b-3ff2-4ece-8f2c-e20fceb4d619" localId="e1"/>
  <!-- Přidání variantního jména -->
  <newPart type="PT_NAME" partUuid="d0f6ebd1-ec9e-42ee-9145-711baf54f3f3">
   <items>
    <string type="NM_MAIN">Frauenberg</string>
    <string type="NM_SUP_GEO">České Budějovice, Česko</string>
    <enum type="LANG" spec="LNG_ger" uuid="350fad04-2d6b-459f-9471-4f02b79070d7" />
   </items>
  </newPart>
 </updateEntity>
</batchUpdate>

3.5.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"?>
<batchUpdate xmlns="http://cam.tacr.cz/2025">
 <info uuid="36bfb401-3def-477f-9990-de029e2d54db">
  <sender>
    <id>9987</id>
    <name>Jan Novák</name>
  </sender>
 </info>
 <updateEntity>
  <!-- Přidání k entitě, č. 982 -->
  <entity entityId="982" rev="7c04837b-3ff2-4ece-8f2c-e20fceb4d619" localId="e1"/>
  <!-- Přidání jazyku k variantnímu jménu -->
  <newItems type="PT_NAME" partUuid="d0f6ebd1-ec9e-42ee-9145-711baf54f3f3">
    <enum type="LANG" spec="LNG_ger" uuid="350fad04-2d6b-459f-9471-4f02b79070d7" />
  </newItems>
 </updateEntity>
</batchUpdate>

3.5.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"?>
<batchUpdate xmlns="http://cam.tacr.cz/2025">
 <info uuid="36bfb401-3def-477f-9990-de029e2d54db">
  <sender>
    <id>9987</id>
    <name>Jan Novák</name>
  </sender>
 </info>
 <updateEntity>
  <!-- Aktualizace entity, č. 982 -->
  <entity entityId="982" rev="7c04837b-3ff2-4ece-8f2c-e20fceb4d619" localId="e1"/>
  <!-- Změna jazyku u variantního jména -->
  <updateItems type="PT_NAME" partUuid="d0f6ebd1-ec9e-42ee-9145-711baf54f3f3">
    <enum type="LANG" spec="LNG_cze" uuid="350fad04-2d6b-459f-9471-4f02b79070d7" />
  </updateItems>
 </updateEntity>
</batchUpdate>

3.5.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"?>
<batchUpdate xmlns="http://cam.tacr.cz/2025">
 <info uuid="36bfb401-3def-477f-9990-de029e2d54db">
  <sender>
    <id>9987</id>
    <name>Jan Novák</name>
  </sender>
 </info>
 <updateEntity>
  <!-- Vymazání části entity, č. 982 -->
  <entity entityId="982" rev="7c04837b-3ff2-4ece-8f2c-e20fceb4d619" localId="e1"/>
  <!-- Vymazání jazyku u variantního jména -->
  <deleteItems type="PT_NAME" partUuid="d0f6ebd1-ec9e-42ee-9145-711baf54f3f3">
    <itemRef type="LANG" uuid="350fad04-2d6b-459f-9471-4f02b79070d7" />
  </deleteItems>
 </updateEntity>
 <updateEntity>
  <!-- Vymazání části entity, č. 982, ref na e1 -->
  <entityRef>e1</entityRef>
  <!-- Vymazání variantního jména -->
  <deletePart type="PT_NAME" partUuid="d0f6ebd1-ec9e-42ee-9145-711baf54f3f3" />
 </updateEntity>
</batchUpdate>

3.5.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"?>
<batchUpdate xmlns="http://cam.tacr.cz/2025">
 <info uuid="36bfb401-3def-477f-9990-de029e2d54db">
  <sender>
    <id>9987</id>
    <name>Jan Novák</name>
  </sender>
 </info>
 <updateEntity>
  <!-- Změna stavu AP, č. 982 -->
  <entity entityId="982" rev="7c04837b-3ff2-4ece-8f2c-e20fceb4d619" localId="e1"/>
  <!-- Schválení entity -->
  <setState>
    <state>ERS_APPROVED</state>
  </setState>
 </updateEntity>
</batchUpdate>

3.5.8. Změna preferovaného jména

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

<?xml version="1.0"?>
<batchUpdate xmlns="http://cam.tacr.cz/2025">
 <info uuid="36bfb401-3def-477f-9990-de029e2d54db">
  <sender>
    <id>9987</id>
    <name>Jan Novák</name>
  </sender>
 </info>
 <updateEntity>
  <!-- Změna preferovaného jména entity, č. 982 -->
  <entity entityId="982" rev="7c04837b-3ff2-4ece-8f2c-e20fceb4d619" localId="e1"/>
  <!-- Nastavení preferovaného jména -->
  <setPrefferedName>d0f6ebd1-ec9e-42ee-9145-711baf54f3f3</setPrefferedName>
 </updateEntity>
</batchUpdate>

3.5.9. Změna třídy/podtřídy

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

<?xml version="1.0"?>
<batchUpdate xmlns="http://cam.tacr.cz/2025">
 <info uuid="36bfb401-3def-477f-9990-de029e2d54db">
  <sender>
    <id>9987</id>
    <name>Jan Novák</name>
  </sender>
 </info>
 <updateEntity>
  <!-- Změna třídy/podřídy entity, č. 982 -->
  <entity entityId="982" rev="7c04837b-3ff2-4ece-8f2c-e20fceb4d619" localId="e1"/>
  <!-- Nastavení podtřídy -->
  <setEntityType>ARMY</setEntityType>
 </updateEntity>
</batchUpdate>