Přeskočit na hlavní obsah
Všechny sbírkyDokumentace REST APIPřizpůsobení aplikace
Dávkové operace
Dávkové operace

Batch API - serverová administrace

Petr Pech avatar
Autor: Petr Pech
Aktualizováno před více než 3 lety

Pro partnerská řešení, která potřebují spravovat instance ABRA Flexi v cloudu, jsme připravili API, které to umožňuje. Jeho stav je zatím beta a tento dokument popisuje plánovaný stav. Vše si důkladně před použitím ověřte.

Autentifikace požadavků vůči ABRA Flexi

ABRA Flexi podporuje několik způsobů tzv. serverové autorizace:

  • serverovým jménem a heslem – při zadání speciálního jméne a hesla je akceptována serverová autorizace. Toto řešení není použitelné v cloudu.

  • klientským certifikátem – umožňuje, abychom pro každého partnera nebo instanci měli certifikát, který umožňuje administraci. Toto řešení zatím není použitelné mimo cloud.

Serverové jméno a heslo

Pro tento typ autorizace je nutné upravit /etc/flexibee/server-auth.xml a doplnit:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
<properties>
  <comment>WinStrom server configuration</comment>
  <entry key="username">winstrom-server-admin</entry>
  <entry key="password">velmi-tajne-a-hodne-dlouhe-heslo</entry>
</properties>

Po restartu serveru se již jméno a heslo akceptuje.

Poznámka: heslo musí být minimálně 15 znaků dlouhé. Toto heslo umožní přístup ke všem datům na dané instalaci. Bezpečně jej ukládejte!

Klientským certifikátem

Bezpečnějším způsobem je použití certifikátu. Lze se jím autorizovat pro získání administrátorského přístupu. Pro komunikaci je nutné použít protokol HTTPS a připojovat se na port 7000. Na serveru je uložen pouze otisk certifikátu (SHA1 fingerprint).

Otisk certifikátu lze získat takto:

openssl x509 -noout -in cert.pem -fingerprint

Tento otisk je nutné zaslat na podporu a bude nastaven do dané instance resp. stromu instancí (jejich seskupení).

Impersonifikace uživatele

V některých případech je nutné, aby se server přihlásil a následně se prohlásil za jednoho z uživatelů.

To lze provést doplněním hlavičky:

X-FlexiBee-Authorization: jmeno.

Od té chvíle budou všechny změny včetně práv provedeny pod tímto uživatelem.

Scénáře použití API

Celé ABRA Flexi REST API vždy pracuje nad jednou databází s daty firmy. Vyjímkou je správa uživatelů a firem. Ta je z firmy vyjmuta a uložena jiným způsobem. Informace o uživatelích jsou u běžné instalace v databázi centralServer. Firmy jsou v jednotlivých databázích. V případě cloudového provozu jsou informace ve vysoce replikované databázi CouchDB.

Pokud by se zpracování dělalo ve více požadavcích, je možné, že při přidělování práv uživatele do firmy nebude obsluhující server vědět, že je firma nebo uživatel již založen. Proto vzniklo toto dávkové API, kdy se předá seznam operací a vykoná je jeden server a tím je zajištěna konzistence.

Protože požadavek může selhat (ať už např. při dočasně nedostupnosti jedné z komponent), je možné požadavek zopakovat. Pak se provede vše tak jak je uvedeno znovu. Pokud již nějaká změna byla provedena, operace se přeskočí (operace jsou idempotentní).

Založení účtu administrátora ABRA Flexi instance a výchozí účetní firmy

Se založením ADMIN účtu v ABRA Flexi se založí výchozí účetní firma podle údajů z objednávky (budeme mít název firmy, IČO).

Není možné založit firmu bez administrátorského uživatele.

<flexibee-batch id="abc-1"> 
  <user action="create-update"> 
    <username>admin</username> 
    <password hash="sha256" salt=”123”>f86vs6vds66</password> 
    <email>admin@firma.cz</email> 
    <givenName>Roman</givenName> 
    <familyName>Skamene</familyName> 
   <ssoIdentifier>admin@firma.cz</ssoIdentifier> 
   <defaultRole>ADMIN</defaultRole> 
   <permissions> 
      <manageAll>true</manageAll> 
      <createCompany>false</createCompany> 
      <deleteCompany>false</deleteCompany>
      <createUser>false</createUser> 
      <changePassword>false</changePassword> 
      <grantPermission>false</grantPermission> 
      <licenseManagement>false</licenseManagement> 
   </permissions> 
  </user> 
  <company action="create-update"> 
    <id>digitalni_media_s_r_o_</id> 
    <name>Digitalní media s.r.o.</name>
    <country>CZ</country> 
    <regNo>966664322</regNo><!-- IČ -->
    <type>PODNIKATELE</type> 
    <adminUser role="ADMIN">admin</adminUser> 
  </company> 
</flexibee-batch>

Standardní uživatelské role ve ABRA Flexi

  • ADMIN

  • SUPERUZIVATEL

  • MZDOVYUCETNI

  • UCETNI

  • OBCHODNIK

  • SKLADNIK

  • SKLADNIKSPOKLADNOU

  • UZIVATEL

  • JENCIST

  • ZABLOKOVAN

Typ organizace + evidence

Podvojné účetnictví je výchozí pro všechny typy organizací.

  • PODNIKATELE

  • PODNIKATELE+PU (podvojné účetnictví)

  • PODNIKATELE+DE (daňová evidence)

  • ROZPOCTOVE

  • NEZISKOVE

  • PODNIKATELIA (pouze pro Slovensko)

Podporované hash funkce pro ukládání hesel

  • sha256 (výchozí pro ukládání hesel poslaných v plain textu)

  • sha512

  • sha1

  • md5

  • pbkdf2 (nejbezpečnější, ale také nejpomalejší metoda – bez používání session u REST API je pak nepoužitelná – je záměrně příliš pomalá).

Ukázka programu pro výpočet otisku hesla pro ABRA Flexi.

import org.apache.commons.codec.binary.Hex; public static final String SHA256 = "sha256"; public static final String SEPARATOR = ":"; protected static String encryptPasswordSHA256(String plain, String salt) { String toDigest = salt + SEPARATOR + plain; try { MessageDigest md = MessageDigest.getInstance("SHA-256"); byte[] result = md.digest(toDigest.getBytes("utf-8")); return SHA256 + SEPARATOR + salt + SEPARATOR + new String(Hex.encodeHex(result)); } catch (UnsupportedEncodingException e) { throw new RuntimeException(e); } catch (GeneralSecurityException e) { throw new RuntimeException(e); } } public static String getRandomSalt() { byte[] b = new byte[10]; new Random().nextBytes(b); return new String(Hex.encodeHex(b)).substring(10); } String plain = "moje heslo"; String result = encryptPasswordSHA256(plain, getRandomSalt());

Založení dalších „běžných“ uživatelů

Tito uživatelé se budou zakládat již z Admin portálu jako noví uživatelé správcem tenanta. Bude voláno i hromadně pro více uživatelů při změně profilu na Admin portálu.

<?xml version="1.0"?>
<flexibee-batch id="abc-12">
  <user action="create-update">
    <username>anna.mlada</username>
    <password hash="sha256" salt="123">f86vs6vds66</password>
    <email>anna.mlada@firma.cz</email>
    <givenName>Anna</givenName>
    <familyName>Mlad&#xE1;</familyName>
    <defaultRole>UZIVATEL</defaultRole>
    <permissions>
      <manageAll>true</manageAll>
    </permissions>
  </user>
</flexibee-batch>

Lze uložit i heslo bez saltu, ale důrazně to nedoporučujeme!

Změna hesla existujícího uživatele

<?xml version="1.0"?>
<flexibee-batch id="abc-123">
  <user action="create-update">
    <username>anna.mlada</username>
    <password hash="sha256" salt="123">f86vs6vds66</password>
  </user>
</flexibee-batch>

Smazání existujícího uživatele

Smazání uživatele z Admin portálu = uvolnění licence. Bude voláno i hromadně pro více uživatelů při změně profilu.

<?xml version="1.0"?>
<flexibee-batch id="abc-12345">
  <user action="delete">
    <username>anna.mlada</username>
  </user>
</flexibee-batch>

Poznámka: pokud byl uživatel smazán a později nastavím create-update, měl by se znovu obnovit.

Obnovení uživatele

<?xml version="1.0"?>
<flexibee-batch id="abc-123456">
  <user action="create-update">
    <username>anna.mlada</username>
  </user>
</flexibee-batch>

Poznámka: při create-update uživatele se nejprve zkouší recyklovat záznamy s příznakem “vymazáno”. Veškeré nastavení přístupů a rolí zůstane zachováno.

Blokace existujícího uživatele

Zablokování uživatele z Admin portálu = nemůže se přihlásit.

<?xml version="1.0"?>
<flexibee-batch id="abc-123456">
  <user action="create-update">
    <username>anna.mlada</username>
    <blocked message="Blocked from external system">true</blocked>
  </user>
</flexibee-batch>

Odblokování uživatele

<?xml version="1.0"?>
<flexibee-batch id="abc-123456">
  <user action="create-update">
    <username>anna.mlada</username>
    <blocked>false</blocked>
  </user>
</flexibee-batch>

Přidání role ADMIN existujícímu uživateli

Přidání atomické role „ERP administrátor“ na Admin portálu. Může být voláno i hromadně pro více uživatelů při změně profilu na Admin portálu.

<?xml version="1.0"?>
<flexibee-batch id="abc-1234567">
  <user action="create-update">
    <username>anna.mlada</username>
    <defaultRole>ADMIN</defaultRole>
  </user>
  <access role="ADMIN"/>
</flexibee-batch>

Odebrání role ADMIN existujícímu uživateli

Odebrání atomické role „ERP administrátor“ na Admin portálu. Může voláno i hromadně pro více uživatelů při změně profilu na Admin portálu.

<?xml version="1.0"?>
<flexibee-batch id="abc-12345678">
  <user action="create-update">
    <username>anna.mlada</username>
    <defaultRole>UZIVATEL</defaultRole>
  </user>
  <access role="UZIVATEL"/>
</flexibee-batch>

Změna jména, příjmení existujícího uživatele

<?xml version="1.0"?>
<flexibee-batch id="abc-123456789">
  <user action="create-update">
    <username>anna.mlada</username>
    <givenName>Ani&#x10D;ka</givenName>
    <familyName>Star&#x161;&#xED;</familyName>
  </user>
</flexibee-batch>

Skrytí / zobrazení firmy (odpojení)

<?xml version="1.0"?>
<flexibee-batch id="abc-123">
  <company action="create-update">
    <id>digitalni_media_s_r_o_</id>
    <show>false</show>
    <!-- true pro zobrazení -->
  </company>
</flexibee-batch>

Smazání firmy

<?xml version="1.0"?>
<flexibee-batch id="abc-123">
  <company action="delete">
    <id>digitalni_media_s_r_o_</id>
  </company>
</flexibee-batch>

Použití API

Platné pro první zvěřejněnou testovací verzi s funkčním zakládáním uživatelů v centrální databázi.

Volání

HTTP PUT na URL = http://server:7000/admin/batch

Požadavek musí být autorizován.

XML s požadavkem lze odeslat pomocí curl takto:

curl -3 'https://server:7000/admin/batch' -T batch.xml -E cert.pem

Ukázkový požadavek

batch.xml

<?xml version="1.0"?>
<flexibee-batch id="abc-123">
  <!-- ID by mělo unikátně označovat dávku -->
  <user>
    <username>anna.mlada</username>
    <password hash="sha256" salt="xyz987">af123bd35</password>
    <email>anna.mlada@firma.cz</email>
    <givenName>Anna</givenName>
    <familyName>Mlad&#xE1;</familyName>
    <permissions>
      <manageAll>true</manageAll>
      <createCompany>true</createCompany>
      <deleteCompany>true</deleteCompany>
      <createUser>false</createUser>
      <changePassword>false</changePassword>
      <grantPermission>true</grantPermission>
      <licenseManagement>false</licenseManagement>
    </permissions>
    <defaultRole>UZIVATEL</defaultRole>
  </user>
  <company action="create-update">
    <!-- action="create-update" je výchozí akce -->
    <id>moje_firma_s_r_o_</id>
    <name>Moje Firma s.r.o.</name>
    <country>CZ</country>
    <!-- aktuálně podporované jsou CZ a SK -->
    <regNo>123</regNo>
    <!-- IČO -->
    <vatId>CZ123</vatId>
    <!-- DIČ -->
    <type>PODNIKATELE</type>
    <adminUser>anna.mlada</adminUser>
  </company>
  <company action="delete">
    <id>demo_a_s_</id>
  </company>
  <access role="ADMIN">anna_mlada_s_r_o_</access>
  <access role="UZIVATEL">moje_firma_s_r_o_</access>
  <access>demo_a_s_</access>
  <access role="ADMIN"/>
  <access>demo_a_s_</access>
</flexibee-batch>

Odpověď

Při úspěchu (HTTP 200) je odesláno XML v tomto formátu:

<?xml version="1.0" encoding="UTF-8"?>
<flexibee-batch-result id="abc-12345678">
  <entry>
    <id>moje_firma_s_r_o_</id>
    <entity>COMPANY</entity>
    <action>DELETE</action>
    <result>
      <status>SKIPPED</status>
      <message>Not implemented yet.</message>
    </result>
  </entry>
  <entry>
    <id>anna.mlada@firma.cz</id>
    <entity>USER</entity>
    <action>CREATE_UPDATE</action>
    <result>
      <status>CREATED</status>
    </result>
  </entry>
</flexibee-batch-result>

Výčet typu entit

  • USER

  • COMPANY

  • ACCESS_LIST

Výčet typu akcí

  • CREATE_UPDATE

  • DELETE

Výčet stavových kódů

  • CREATED

  • UPDATED

  • DELETED

  • FAILED (popis důvodu chyby bude v elementu <message>)

  • SKIPPED (může být doplněno elementem <message>)

Související články
Dávkové operace
Workflow a procesy
Serverová autorizace přes REST API
Dávkové zpracování pomocí nástroje Flexi2XML
Externí autorizace
Dostali jste odpověď na svou otázku?