Preskoči na glavno vsebino

API Ninja: Tréning 6/7 - Používateľské tlačidlo a API

Posledný z tréningov API Ninja - implementácia používateľského tlačidla

Avtor: Petr Pech

Získané zručnosti:

  • znalosť užívateľského tlačidla

  • implementácia získaných znalostí priamo do ABRA Flexi

V predchádzajúcich tréningoch sme sa naučili základy REST API, rad šikovných chvatov, ako dáta získať, ako dáta do ABRA Flexi zaslať. Vždy sme museli použiť externé nástroje, cURL alebo aplikáciu Postman, alebo požiadavky na získanie dát kopírovať priamo do internetového prehliadača.

V tomto záverečnom tréningu si ukážeme, ako je možné všetky tieto chvaty implementovať priamo do ABRA Flexi, zobraziť si funkciu v aplikácii a dovoliť tak používateľovi pohodlne spustiť akciu ako každú inú priamo z aplikácie.

Pokiaľ teda pri svojej práci využívate rôzne systémy alebo webové portály, vďaka užívateľským tlačidlám k nim získate priamy prístup rovno z ABRA Flexi. Na základnej učňovskej úrovni si ukážeme jeho zavedenie do aplikácie a jednoduchý príklad s preklikom tlačidla na externú aplikáciu, napríklad na portál MFČR. Na úrovni bojovník si ukážeme implementáciu tlačidla na niektorý z poznaných chvatov v REST API. API Ninja sa oboznámi s príkladom, ako napojiť užívateľské tlačidlo na vlastný PHP skript. Finálny tréning je tu, pripravte sa, dáme sa do toho!

Úroveň: Učeň

Najprv k definícii tlačidla. Tlačidlo vychádza z dokumentácie ako XML Flexi, ktoré už poznáme. XML môžeme do aplikácie nahrať pomocou menu Nástroje > Import > Import XML, avšak študent API iste zvládne poslať ako požiadavku pomocou API a metódy POST:


​https://developer.flexibee.eu/c/ninja/custom-button.xml

<?xml version="1.0"?>
<winstrom version="1.0">
  <custom-button>
    <id>code:MFCR-ARES</id>
    <url><![CDATA[
https://wwwinfo.mfcr.cz/cgi-bin/ares/darv_res.cgi?ico=${object.ic}&jazyk=cz&xml=1]]>
    </url>
    <title>Kontrola IČ</title>
    <description>Validace IČ z faktury vydané na ARES</description>
    <evidence>faktura-vydana</evidence>
    <location>detail</location>
    <browser>desktop</browser>
  </custom-button>
</winstrom>

Výborne! Po importe definície tlačidla je nutný reštart aplikácie a máme prvé tlačidlo pripravené.

Evidencia užívateľských tlačidiel sa volá custom-button, teraz si popíšeme štruktúru tela požiadavky:

  • ID už poznáme, identifikátor, pri vytváraní užívateľského tlačidla musí byť prvok uvedený s kódom (skratkou).

  • URL, je kľúčové, určuje URL webovej stránky či sieťového zdroja, ktoré bude po stlačení tlačidla otvárané.

    • URL musí byť uvedené v plnom, absolútnom tvare, t. j. musí obsahovať schému a doménovú adresu servera (ako náš príklad https://wwwinfo.mfcr.cz/)

    • URL odporúčame zadávať v <![CDATA[ ]]>, aby prítomnosť znaku '&' nespôsobila nevalidné XML.

    • V hodnote URL nie je podporovaná URI schéma file používaná na prístup k lokálne uloženým súborom. Definície užívateľských tlačidiel obsahujúce URL s file:// budú pri importe odmietnuté ako nepovolené.

    • Dôležitou súčasťou sú hodnoty z aplikácie odovzdávané v premennej. V našom príklade využívame IČO z faktúry vydanej. Premenné sú vyhodnotené FreeMarkerom pri behu aplikácie a zaisťujú odovzdanie hodnôt z aplikácie. Reťazec object je v názve premenných povinný, pomocou neho sa odkazuje na aktuálny záznam vybranej evidencie.

Kde sme zistili podobu URL na MFČR?

URL https://wwwinfo.mfcr.cz/cgi-bin/ares/darv_res.cgi?ico=63469588&jazyk=cz&xml=1 sme získali priamo z internetového prehliadača. Stačí na webe MFČR vyhľadať ľubovoľné IČO, potom pristúpiť do ARES a adresa sa nám zobrazí v adresnom riadku prehliadača.

Z adresy je zrejmé, že stránka MFČR odovzdáva vybrané IČO ako parameter v adrese, stačí teda nahradiť naším ${object.ic} z aplikácie a máme hotovo. Späť k ďalším poliam definície:

  • title a description popisujú tlačidlo, zobrazia sa aj používateľovi v aplikácii, title je názov, description je popis pri prejdení myšou nad tlačidlom

  • evidence je taktiež veľmi dôležitý údaj, uvádza, kde bude tlačidlo použité a zobrazené, obsahom je teda kód evidencie podľa evidence listu.

  • location, nám hovorí, či bude tlačidlo zobrazené v editačnom okne záznamu - detail, alebo bude zobrazené v prehľade záznamov evidencie - list

  • browser obsahuje informáciu, či sa po stlačení tlačidla URL otvorí v internom prehliadači ABRA Flexi - automatic, alebo v externom prehliadači v PC - desktop

    • aktuálne sa plánuje tvorba nového interného prehliadača, odporúčame teda vždy použiť voľbu desktop

Dobre - object je faktura-vydana a kde sme zistili, že môžeme použiť IČO, učedník?

Bystrý učeň si všimol, že sme použili premennú ${object.ic} a iste tuší aj ďalšie možnosti. Ako bolo uvedené, pomocou reťazca object máme prístup ku všetkým poliam evidencie, ale to nemôže byť všetko, však? Existujú ešte ďalšie premenné, ktoré je možné pri volaní použiť:

  • objectIds – zoznam ID vybraných záznamov oddelených čiarkou. Znamená to, že ak v aplikácii zaklikáte záznamy zaškrtávacími políčkami, budú odovzdané všetky ID. Dôležité upozornenie, premenné object a objectIds sa vzájomne vylučujú!

  • user – je možné odovzdať aj Meno a priezvisko aktuálne prihláseného používateľa

  • url – môžeme si odovzdať aj URL, odkiaľ bolo tlačidlo stlačené, teda napríklad pre nás https://developer.flexibee.eu/c/ninja/faktura-vydana/{ID faktury}.

  • companyUrl – adresa API rozhrania firmy, v ktorej je tlačidlo umiestnené, teda pre nás https://developer.flexibee.eu/c/ninja.

  • evidence – meno evidencie, na ktorej je tlačidlo umiestnené (faktura-vydana).

  • authSessionId – autentifikačný token k aktuálnemu sedeniu používateľa. Počas platnosti sedenia je možné ho využiť na autentifikáciu dotazov. S autentifikačným tokenom sme sa oboznámili v 3. tréningu na úrovni Ninja.

  • customerNo – číslo zákazníka zodpovedajúce licencii.

  • licenseId – identifikátor licencie.

Učeň, teraz vieš, ako použiť užívateľské tlačidlo. Iste vymyslíš ďalšie príklady použitia, napríklad zavolať chvaty z predchádzajúcich tréningov alebo tvoje vlastné externé weby? Hurá do toho, možností je neobmedzene!

Úroveň: Bojovník

Na učňovskej úrovni sme sa naučili definíciu tlačidla, jeho zavedenie do aplikácie a príklad, ako zavolať externý web. Teraz si ukážeme, ako nadefinovať niektorú zo zložitejších služieb REST API pomocou užívateľského tlačidla. Vo všeobecnosti bez vlastného skriptu môžeme používať iba služby a výstupy, ktoré sa posielajú metódou GET, keďže tlačidlom nevyvoláme požiadavku POST. Aké ďalšie tlačidlo pridať do aplikácie bez programovania skriptu, keď už služby a tlačidlá v aplikácii sú?

Najprv si ukážeme, ako na jedno kliknutie získať PDF faktúry. Tlačidlo umiestnime do evidencie vydanej faktúry na prehľad záznamov:

<?xml version="1.0"?>
 <winstrom version="1.0">
  <custom-button>
    <id>code:FAV-PDF</id>
    <url><![CDATA[${url}.pdf?report-name=NINJAFAV&report-sign=true]]>
    </url>
    <title>PDF</title>
    <description>Stáhnout PDF faktury<description>
    <evidence>faktura-vydana</evidence>
    <location>list</location>
    <browser>desktop</browser>
  </custom-button>
</winstrom>

Keď si prejdeme definíciu, všimneme si, že v poli <url> sme použili priamo premennú ${url}. Tento chvat nám umožní importovať do akéhokoľvek ABRA Flexi a vždy prevezme správnu adresu, odkiaľ doklad stiahnuť. Ďalej sme zapísali kód užívateľskej tlačovej zostavy NINJAFAV (musí existovať) a chceme tlačivo podpísané certifikátom (musí existovať). Na jedno kliknutie tak môžeme zobrazovať PDF faktúr v prehliadači.

Poďme hneď na ďalšie šikovné tlačidlo. Priamo z aplikácie si môžeme zobraziť aktuálne pracujúcich prihlásených používateľov. Definícia tlačidla vyzerá nasledovne:

<?xml version="1.0"?>
  <winstrom version="1.0">
    <custom-button>
      <id>code:SESSIONS</id>
      <url>
      <![CDATA[https://developer.flexibee.eu/status/session]]>
      </url>
      <title>Přihlášení uživatelé</title>
      <description>Seznam přihlášených uživatelů </description>
      <evidence>uzivatel</evidence>
      <location>list</location>
      <browser>desktop</browser>
    </custom-button>
</winstrom>

Informácie o prihlásených používateľoch sa nachádzajú na stránke /status/session. Tlačidlo môžeme opäť pridať na ľubovoľné miesto, teraz volíme evidenciu uzivatel - Osoby a užívatelia.

Bojovník, prídeš na to, prečo sme v url nepoužili premennú companyUrl? Nápoveda: dá sa vidieť z URL vs. obsah premennej.

Posledné šikovné tlačidlo kombinuje naše znalosti filtrácie dát a možnosti tlačidla. Uvažujme, že denne potrebujeme exportovať do XML faktúry, ktoré majú dátum splatnosti dnes a nie sú uhradené. Využijeme teda filtráciu, detail a tlačidlo:

<?xml version="1.0"?>
  <winstrom version="1.0">
    <custom-button>
      <id>code:NEUHRAZENEFAV</id>
      <url>
        <![CDATA[${companyUrl}${evidence}
           /(datSplat=now()%20and%20stavUhrK<>'stavUhr.uhrazeno').xml?    
           detail=custom:kod,sumCelkem,varSym&limit=0]]>
     </url>
     <title>FAV bez uhrady</title>
     <description>
       Faktury vydané se splatnostní dnes a bez úhrady
     </description>
     <evidence>faktura-vydana</evidence>
     <location>list</location>
     <browser>desktop</browser>
  </custom-button>
</winstrom>

Zápis definície tlačidla už poznáme. Zaujímavá je v tomto príklade URL. Pre ukážku používame premenné companyUrl aj evidence. Tlačidlo je teda možné použiť aj v iných evidenciách a firmách. Ďalej zápis tiež poznáme, filtrácia dokladov s dátumom splatnosti dnes a stav úhrady nie je uhradené. Posledné parametre určujú vlastný detail XML a nesmieme zabudnúť nastaviť limit=0, aby sme získali v XML všetky faktúry.

Bojovník, teraz poznáš množstvo možností, ako používateľom aplikáciu vylepšiť!

Úroveň: Ninja

Na úrovni Ninja si ukážeme, ako využiť užívateľské tlačidlo pre naše skripty. Príklad môžeme vidieť napríklad tu. Jedná sa o rozosielač užívateľských dotazov napísaný v PHP a vyvolaný užívateľským tlačidlom. Uvedieme si však vlastný príklad, čo povieš, Ninja?

Uvažujme príklad, že chceme faktúry so splatnosťou dnes a stále neuhradené zaslať šéfovi na preverenie. Definíciu tlačidla už poznáme, pre naše účely bude element URL vyzerať trochu odlišne:

<?xml version="1.0"?>
<winstrom version="1.0">
  <custom-button>
    <id>code:NEUHRAZENEFAV</id>
    <url><![CDATA[https://ninja.webserver.cz/PHP/neuhrazene-faktury.php]]></url>
    <title>Report neuhrazených FAV</title>
    <description>Odešle na email šéfovy neuhrazené faktury</description>
    <evidence>faktura-vydana</evidence>
    <location>list</location>
    <browser>desktop</browser>
  </custom-button>
</winstrom>

Všimni si, Ninja, URL element obsahuje cestu k PHP skriptu, pre jednoduchosť dokonca nepredávame žiadne informácie z Flexi. Všetko zariadi skript. Ideme na to!

Skript je v našom príklade veľmi jednoduchý, cieľom tréningu nie je naučiť sa PHP, ale pochopiť silu, ako mocný chvat pre každého API Ninju je užívateľské tlačidlo.

<?php
include('./httpful.phar');

$flexiLogin = 'ninja'; 
$flexiHeslo = 1234; 
$uri = 'https://developer.flexibee.eu/c/ninja/faktura-vydana/(datSplat=now()%20and%20stavUhrK<>"stavUhr.uhrazeno").csv?detail=custom:kod,sumCelkem,varSym,nazFirmy&limit=0';

$response = \Httpful\Request::get($uri) 
->expectsXML() 
->authenticateWith($flexiLogin, $flexiHeslo)
->send();

//případné další zpracování odpovědi z Flexi

// příprava zprávy
$to = 'velkysef@ninja.cz';
$subject = 'Nezaplacené faktury';$message = 'Dobrý den, šéfe, zasílám report neplatičů:\n' . $response->body;

//odeslání emailu
mail($to, $subject, $message);
?>

Kliknutím na tlačidlo v aplikácii môžeme kedykoľvek šéfovi odoslať prehľad neuhradených faktúr. Alebo tiež čokoľvek iné. Už poznáš všetky možnosti, Ninja, tvoja sila v API je neobmedzená. Môžeš sa vrhnúť na záverečný súboj a získať certifikát!

Sorodni članki
Ste s tem dobili odgovor na svoje vprašanje?