Využití API v rámci Sofa

Základní informace

Co je to API – je to zkratka označení Application Programming Interface, kterou se v informatice označuje rozhraní pro programování aplikací. Úkolem API bude v našem případě zprostředkovat komunikaci dvou aplikací – tedy nějaké vaší aplikace s aplikací Sofa – a umožnit jejich vzájemnou výměnu dat.

Co je externí informační systém – jedná se vlastně o nějakou vaši aplikaci, která potřebuje komunikovat se Sofa, aniž byste museli zajišťovat návaznost v průběhu práce ručně. K tomu využívá rozhraní API.

Co je GraphQL – jedná se dotazovací jazyk pro tvorbu API vytvořený v roce 2012 společností Facebook. Od roku 2015 je GraphQL k dispozici jako open-source.

Co jsou dotazy – v GraphQL je nutné rozlišovat dva základní typy dotazů.

Prvním je query, obdoba SELECT z SQL. Jedná se typ dotazu, který se čistě dotazuje na uložená data a tato data žádným způsobem nemění. Spouštění query je tedy bezpečné, protože nemůže data žádným způsobem poškodit.
Druhým typem je mutation, což je obdoba SQL operací pro změnu dat a jejich struktury (INSERT, ALTER, DELETE, UPDATE…). U provádění mutací je tedy nutné dbát na zvýšenou opatrnost a vědět, jak se daná mutace zachová. V případě spuštění špatné mutace lze nenávratně rozbít data.

Co je to JSON – jedná se o zkratku JavaScript Object Notation a jde o formát pro vzájemnou komunikaci a výměnu dat aplikací prostřednictvím rozhraní API. Proměnné, které budeme používat v GraphQL dotazech budou předávány právě ve tvaru objektů JSON.

Proměnné jsou definované v kulatých závorkách za názvem dotaz a značí se symbolem $. Je nutné uvést název proměnné a její typ. Povinné proměnné jsou označené vykřičníkem.
Příklad dotazu s definovanou povinnou proměnnou typu string: query findUserById($userIdent: String!). Příklady konkrétních dotazů i s proměnnými jsou uvedeny v kapitole Příklady jednoduchých GraphQL dotazů.

V GraphQL dotazu lze používat aliasy, je tedy možné si část příchozího JSON objektu pojmenovat podle potřeb. Toto může být velmi praktické například u vyhodnocování výsledku v rámci PAJS. Konkrétní příklad využití v Sofa bude popsán níže.

Externí informační systém

Vytvoření nového externího informačního systému

Nejprve je nutno ve vaší organizaci v Sofa vytvořit externí informační systém. Jde vlastně o systém přístupu k nějaké vaší aplikaci, která potřebuje komunikovat se Sofa, aniž byste museli zajišťovat vzájemný kontakt v průběhu práce ručně. K tomu se právě využívá rozhraní API.

V okně Administrace klepněte na tlačítko API.

Pokud tlačítko API nevidíte, klepněte na pravém konci lišty na tlačítko se třemi tečkami; zbytek ovladačů se zobrazí ve svislé nabídce.
Na nástrojové liště okna API klepněte na tlačítko +Přidat externí IS.
Otevře se okno Nový externí IS se dvěma kartami – Nastavení a Oprávnění.
Na kartě Nastavení vyplňte základní údaje o systému, tj. pole Název a Popis (zobrazují se pouze v rámci Sofa). Údaj v poli Identifikátor se vytvoří automaticky z řetězce zadaného do pole Název, lze ho ale v případě potřeby upravit.

Důležité je heslo zapsané do pole Heslo. To použijete při úpravách tohoto externího informačního systému, ale poslouží i při vygenerování tokenu pro přístup pomocí vytvořeného externího systému.

Heslo musí být nejméně 8 znaků a nejvíce 64 znaků dlouhé, musí obsahovat minimálně jedno velké písmeno, jedno malé písmeno a jednu číslici. Povolené znaky jsou malá a velká písmena (a-z, A-Z), číslice (0-9) a speciální znaky (mezera ! # $ % & ( ) * + , - . : = ? @ [ ] _ { | } ~).

Heslo pro kontrolu zopakujte zápisem do pole Heslo znovu.
Úroveň zápisu informací o průběhu činnosti ExtIS nastavte pomocí voliče Úroveň logování nabízejícího možnosti Informace a Debug. Pro ladění problémů a chyb je vhodné nastavit si úroveň logování na Debug.

Tlačítkem Následující: Oprávnění > přejděte na kartu Oprávnění.

Pomocí zaškrtávacích políček nastavte oprávnění, která chcete externímu informačnímu systému přiznat. Budete-li chtít třeba externí IS využívat k dálkové správě uživatelů v Sofa, zaškrtněte políčko Může spravovat uživatele, skupiny a role.

Po vyplnění všech údajů klepněte na tlačítko Uložit externí IS.

Položka vytvořeného externího informačního systému se zobrazí v okně API spolu se zeleným pruhem se zprávou o úspěšném vytvoření.

Zjištění ID uživatele

ID uživatele je údaj, který budeme velmi často potřebovat v dalších částech výkladu.

V okně API klepněte na položku externího informačního systému, čímž ji označíte za vybranou a vytvoří se nástrojová lišta se skupinou tlačítek.

Klepněte na tlačítko Upravit externí IS. V okně s popisem externího informačního systému je na kartě Nastavení v poli Uživatelské jméno vygenerovaný needitovatelný údaj, který v kombinaci s heslem zadaným při založení externího informačního systému poslouží k autentizaci uživatele.

Úpravy údajů o externím IS

Na nástrojové liště jsou i další tlačítka pro servisní úkony nad položkou seznamu externích informačních systémů.

Po vytvoření je externí IS aktivní, o čemž svědčí zelené zatržítko ve sloupci Stav. Tlačítkem Deaktivovat externí IS se systém deaktivuje a symbol ve sloupci Stav se změní v červený křížek. Nápis na tlačítku se po potvrzení bezpečnostního dotazu změní na Aktivovat externí IS – pomocí tohoto tlačítka lze systém opět aktivovat.
Tlačítkem Změnit heslo můžete kdykoliv změnit přístupové heslo k externímu IS.
Pokud byste chtěli záznam o externím IS zrušit, klepněte na tlačítko Smazat externí IS.
Tlačítkem Logy se zobrazí seznam všech záznamů o systémových událostech.

Komunikace s externími IS pomocí webhooků

Sofa od verze 5.5 umožňuje při komunikaci s externími informačními systémy využívat tzv. webhooky. Jedná se o metodu, umožňující v reálném čase nechat jednu webovou aplikaci (u nás v Sofa) automaticky informovat druhou aplikaci (u nás v externím informačním systému), že bylo dosaženo určité události (nebo třeba určitého stavu). Tím pro externí aplikaci odpadá nutnosti neustálého opakování kontrol týkající se změn v Sofa.

Užití webhooků je v Sofa ve verzi 5.5 implementováno do procesní aplikace s využitím pro agendy, které při svém běhu postupně prochází určité stavy. To mohou být agendy typu SignPoint nebo třeba agendy pro hromadné podepisování.

Mějme například aplikaci v nějakém externím informačním systému (označme ji ExtAp), která spolupracuje s určitou aplikací v Sofa. Aplikace ExtAp například pošle do Sofa dokument k podpisu agendě SignPoint a potřebuje být informována, kdy bude podepisovací proces dokončen. Pokud by stále posílala dotazy na zjištění stavu procesu, působilo by to jí samé i aplikaci Sofa neustálou a nadbytečnou zátěž. Proto se situace řeší opačně – jakmile dojde k požadované události (třeba k podpisu dokumentu všemi podepisujícími), Sofa sama o tom ExtAp informuje. Proces je asynchronní – Sofa informaci odešle, ale nečeká na odpověď.

Teprve pak se aplikace ExtAp může do Sofa zaregistrovat a sama poslat konkrétní požadavek.

Konfigurace webhooků

Webhooků lze v rámci organizace v Sofa vytvořit libovolné množství. Předpokládáme, že administrátor dostane informace o „protějších“ aplikacích ExtAp, které jsou již hotové (systémové nebo je vytvořil na míru nějaký návrhář), takže již může využít známou hodnotu TdId. Napojení administrátor konfiguruje mimo procesní aplikaci, přímo v administraci aplikace Sofa, kde zadá příslušné parametry (tedy především URL externí aplikace a přihlašovací údaje).

Pro práci s webhooky se nastavují jednak přihlašovací údaje a jednak popisy způsobu připojení k ExtAp. Východiskem je okno Administrace a tlačítko API, kterým se otevře příkazová nabídka pro upřesnění požadované akce.

Příkazem Přihlášení otevřete okno vytváření sad přihlašovacích údajů.
Příkazem Webhooky otevřete okno pro popisnou specifikaci napojení na jednotlivé ExtAp pomocí webhooků (URL, přihlašovací jména a další).

Specifikace přihlašovacích údajů

Příkaz Přihlášení otevře pohled Přihlašovací údaje.

Po stisku tlačítka +Přidat přihlašovací údaje se otevře dialog Nové přihlašovací údaje, ve kterém vytvoříte přihlašovací údaje, pro autentizaci aplikace Sofa směrem k volanému externímu informačnímu systému.

Do polí Identifikátor, Název a Popis zapíšete obvyklé popisné údaje pro identifikaci vytvářeného přihlášení.

Identifikátor (což je hodnota označovaná jako TdId) musí začínat písmenem a smí obsahovat pouze písmena anglické abecedy (malá i velká), číslice a podtržítka.

K dispozici jsou dvě možnosti typu přihlášení – Basic a Bearer Token.

Pokud nastavíte přihlášení typu Basic, je pro přihlášení potřeba zadat uživatelské jméno a k němu příslušející heslo.
Při nastavení typu přihlášení Bearer Token je zapotřebí do stejnojmenného pole zadat řetězec s autentizačním tokenem.

Přihlašovací údaje se po stisku tlačítka OK uloží a zobrazí v okně Přihlašovací údaje. Úspěšné vytvoření je rovněž oznámeno zprávou v zeleném informačním pruhu.

Údaje lze pak dodatečně měnit i upravit co do obsahu i typu.

Klepnutím do kroužku na začátku řádku vyberte položku s přihlašovacími údaji. Zpřístupní se nástrojová lišta s trojicí tlačítek.

Tlačítkem Upravit přihlašovací údaje budete moci změnit název a popis přihlášení.
Tlačítkem Nastavit přihlašovací údaje budete moci změnit typ přihlášení a s ním spojené údaje.
Tlačítkem Smazat přihlašovací údaje lze celou položku přihlášení odebrat.

Specifikace nového webhooku

Webhooky se vytvářejí a upravují v pohledu Webhooky. Nový webhook vytvoříte po klepnutí na tlačítko +Přidat webhook. Otevře se okno Nový webhook, které se skládá ze tří karet – Nastavení, URL argumenty a Header argumenty.

Údaje na kartě Nastavení

V poli Přístupové údaje vyberte jednu položku z výčtu připravených přihlašovacích údajů (vytvořených postupem popsaným v předchozí kapitole).

Doplňte údaje do polí Název, Identifikátor a Popis – i zde musí Identifikátor začínat písmenem a smí obsahovat pouze písmena anglické abecedy (malá i velká), číslice a podtržítka.

Do pole URL zkopírujte URL adresu externí aplikace ExtAp.

V poli HTTP metoda vyberte metodu GET, PUT nebo POST.

U metody GET nelze posílat část body.
U metod PUT a POST část body posílat lze a je nutné vyplnit buď reálnou hodnotu Content-Type (nikoliv nějakou testovací hodnotu) nebo specifikaci souboru typu JSON s potřebnými údaji.

Políčko Povolit neznámé argumenty se týká dále popsaných URL argumentů a Header argumentů.

Maximální počet pokusů o provedení akce lze nastavit v rozmezí 1 až 3. Hodnota Timeout se nastavuje v rozmezí 1 až 5 sekund.

Údaje nastavované na kartě URL argumenty

Na kartě URL argumenty lze vkládat dodatkové argumenty. Tlačítkem +Přidat argument otevřete dialog, ve kterém argument pojmenujete, můžete připojit jeho popis a pomocí políčka Povinný rozhodnout, zda hodnota tohoto argumentu bude povinná. To se testuje při posílání procesů z aplikace nebo agendy.

Po stisku tlačítka Přidat argument jsou zadané hodnoty zařazeny do seznamu na kartě URL argumenty.

Pro argument vybraný pomocí políčka před jeho položkou se zobrazí nástrojová lišta s tlačítky pro úpravu a smazání argumentu.

Údaje nastavované na kartě Header argumenty

Na kartě Header argumenty lze vkládat dodatkové argumenty headeru. Tlačítkem +Přidat argument otevřete dialog, ve kterém argument pojmenujete. Dále platí totéž, co bylo uvedeno v předchozí kapitole.

V obou případech se uplatňuje vliv zaškrtnutí políčka Povolit neznámé argumenty.

Pokud na výše popsaných kartách nespecifikujete žádné argumenty a přesto pak z agendy nějaký argument dorazí (a není na seznamu), pak při zaškrtnutí políčka bude proces pokračovat.
Pokud políčko zaškrtnuté není a argument dorazí, bude další proces ukončen s tím, že argument není znám.

Po stisku tlačítka Uložit webhook se údaje uloží a v okně Webhooky se zobrazí nová položka. O tom je zobrazena zpráva v zeleném informačním pruhu.

Úpravy a testování existujících webhooků

Pokud v okně Webhooky vyberete některou z položek, zpřístupní se nástrojová lišta. Pomocí trojice tlačítek můžete webhook nejen upravit a vymazat, ale také otestovat.

Tlačítkem Upravit webhook se otevře okno Webhooky, ve kterém jsou načteny údaje o vybraném webhooku. Kromě hodnoty identifikátoru lze upravit všechny údaje, včetně změny http metody.
Tlačítkem Smazat webhook celý vybraný webhook po potvrzení bezpečnostního dotazu nevratně ze seznamu odeberete.
Tlačítko Testovat webhook umožní nastavený webhook otestovat – viz následující odstavce.

Tlačítkem Testovat webhook se otevře stejnojmenné okno určeno k otestování webhooku při aktuálním nastavení. Pokud máte v konfiguraci webhooku nastavený URL argument a/nebo Header argument, můžete zde zadat na zkoušku jejich hodnoty. Nemáte-li argumenty nastavené, pole pro jejich zadání v okně chybí.

Klepnutím na tlačítko Testovat webhook se funkce webhooku otestuje a výsledek zobrazí ve stejném okně. Úspěšný test oznamuje zelený informační pruh. Výsledek testu je vypsán v polích Stav, Stavový kód a Odpověď.

V případě neúspěšného vyhodnocení se zobrazí červený informační pruh se zprávou o chybě.

Chyba může být způsobena třeba chybným zadáním URL adresy nebo souboru JSON, případně může být chybná i celá aplikace ExtAp.