Spôsob vytvorenia programových blokov
Každá operácia v sekcii Definition predstavuje samostatné API volanie voči systému CDESK. Tieto operácie je možné vytvárať na základe existujúcich endpointov, ktoré sú dostupné v Swagger (OpenAPI) dokumentácii CDESK servera.
Odporúčaný postup
Pred samotným vytvorením operácie v Power Automate je vhodné:
- Otestovať API volanie v nástroji Postman
Testovanie v Postmane umožňuje overiť správanie endpointu, jeho vstupných parametrov a analyzovať návratové dáta bez nutnosti úprav konektora. - Overiť autentifikáciu a oprávnenia
Uistite sa, že API používateľ, pod ktorým sa volanie vykonáva, má dostatočné oprávnenia na danú operáciu. Nedostatočné oprávnenia sa môžu prejaviť chybami 401 Unauthorized alebo 403 Forbidden. - Získať funkčný vzorový URL (sample URL)
Po úspešnom otestovaní volania v Postmane je vhodné použiť funkčný request URL ako základ pre definíciu operácie v Power Automate. - Importovať alebo manuálne nakonfigurovať operáciu v konektore
V sekcii Definition sa následne vytvorí nová operácia, do ktorej sa prenesie URL, HTTP metóda, hlavičky, parametre a očakávaná odpoveď.
Získanie API endpointu pomocou Dev Tools (F12)
Ďalšou možnosťou, ako identifikovať správny API endpoint, je využiť vývojárske nástroje priamo v rozhraní CDESK.
Postup je nasledovný:
- Prihláste sa do CDESK v prehliadači.
- Otvorte vývojársku konzolu pomocou klávesy F12.
- Prepnite sa na záložku Network.
- V rozhraní CDESK vykonajte požadovanú akciu (napr. vyhľadanie požiadaviek, otvorenie detailu, uloženie požiadavky a pod.).
- V zozname sieťových volaní vyhľadajte API request, ktorý danú akciu vyvolal.
Po identifikovaní správneho volania je možné:
- skontrolovať použitý API endpoint
- overiť HTTP metódu
- pozrieť si query parametre, hlavičky a telo požiadavky
Overenie volania v Postmane
Identifikované API volanie sa odporúča následne otestovať v nástroji Postman, kde je možné overiť jeho funkčnosť, správanie a návratové dáta mimo Power Automate. Až po úspešnom otestovaní sa odporúča použiť toto volanie pri vytváraní operácie v sekcii Definition Custom Connectora.
Filtrovanie požiadaviek pomocou SB filtra
Týmto spôsobom je možné získať aj API volania, ktoré využívajú SB filter na strane CDESK. SB filter sa nachádza ako parameter v URL a umožňuje filtrovať dáta už na backendovej strane.
Napríklad pri vyhľadávaní požiadaviek:
- API endpoint vráti iba tie requesty, ktoré spĺňajú podmienky definované v SB filtri
- namiesto spracovania celého zoznamu požiadaviek vo flowe
- Prejdite do sekcie, v ktorej je dostupné vyhľadávanie, napríklad Requests, a kliknite na ikonu Advanced filter
- V poli filter si vytvoríte vlastný filter na strane CDESK, následne otvoríte Dev console prehliadača (F12)
- Prejdete do sekcie Network v Dev console, spustíte nahrávanie akcií, a kliknete v CDESK na tlačidlo Hľadať.
- V sekcii Network sa zobrazia API volania vykonané na základe vašej akcie. Identifikujte volanie, ktoré zodpovedá vyhľadávaniu, a kliknite naň.
V hlavičke volania sa nachádza parameter sb, ktorý má na backendovom API rovnakú funkciu ako filter nastavený v Advanced filter. To znamená, že pri zavolaní API endpointu s daným sb parametrom vráti API iba tie dáta, ktoré vyhovujú zvolenému filtru.
Týmto spôsobom je možné nastaviť filtrovanie pre API endpointy, ktoré podporujú vyhľadávanie, ako napríklad Requests, Work Orders, Address Book, Contacts a ďalšie. Vo všetkých prípadoch, kde je možné nastaviť filter v používateľskom rozhraní, je možné rovnaké filtrovanie použiť aj na úrovni API volania.
Vytvorenie a testovanie vlastných programových blokov
Pre vytvorenie vlastných programových blokov je potrebné pridať Action v tabe 3. Definition Custom Connectora. Action predstavuje jednu operáciu konektora, ktorá mapuje konkrétne API volanie voči systému CDESK. Každá Action definuje:
- cieľový API endpoint
- použitú HTTP metódu
- vstupné parametre (URL, query, headers, body)
Z pohľadu Power Automate sa Action správa ako samostatný funkčný blok, ktorý je možné použiť v cloudových flowoch rovnako ako natívne konektory.
V rozhraní Custom Connectora prejdite do záložky 3. Definition. Kliknite na tlačidlo New action.
Je potrebné vyplniť nasledovné informácie o Programovom bloku:
- Summary – výstižný popis bloku, zobrazuje sa pri používaní vo Flow
- Description – Jednoduchý interný popis, vhodné ak viac blokov používa rovnaké API volanie
- Operation ID – Interné operation ID pre power automate, musí byť jedinečné, začína veľkým písmenom
Následne pre nastavenie API volania kliknite na 4. Import from sample.
1. HTTP metóda (Verb)
V tejto časti sa vyberá HTTP metóda, ktorá určuje typ vykonávanej operácie voči CDESK API. Zvolená metóda musí zodpovedať definícii endpointu v Swagger dokumentácii CDESK.
2. URL
Pole URL obsahuje úplnú adresu API endpointu, ktorý bude volaný.
V prípade potreby dynamickej práce s URL volania je možné v adrese definovať premenné, s ktorými je následne možné pracovať v rámci Power Automate flow. Tieto premenné sú pri použití operácie vyplňované dynamickým obsahom alebo hodnotami získanými z predchádzajúcich krokov.
Napríklad pri práci s konkrétnou požiadavkou je potrebné, aby bolo v URL dynamicky priradené ID požiadavky. Z tohto dôvodu je pri vytváraní operácie potrebné definovať URL v nasledujúcom tvare:
https://cdesk_address.xx/api/request/{requestId}
Pri takejto definícii je možné s premennou requestId ďalej pracovať vo flow, napríklad iterovať zoznamom viacerých požiadaviek a volať každú z nich samostatne.
3. Headers
V tejto časti sa definujú HTTP hlavičky odosielané spolu s požiadavkou.
Napríklad:
- Content-Type: application/json
Autorizačná hlavička (Authorization) sa neuvádza manuálne, keďže je automaticky spravovaná mechanizmom OAuth 2.0 a upravená pomocou vlastného kódu v konektore.
Po importovaní sa vami zadané údaje zobrazia v tabuľke Request. Ak sú údaje správne, kliknite na tlačidlo Update Connector, následne sa presuňte do tabu 5. Test.
1. Vytvorenie a výber Connection
V hornej časti obrazovky je potrebné vytvoriť alebo vybrať Connection, ktorá sa používa na autentifikáciu voči CDESK serveru. Ak ešte neexistuje žiadna connection, je možné ju vytvoriť kliknutím na New connection.
V prípade, že je dostupných viacero connections, je vhodné zvoliť najnovšiu connection podľa času vytvorenia, aby sa predišlo používaniu neaktuálnych alebo neplatných prihlasovacích údajov.
2. Výber operácie
V ľavej časti obrazovky sa nachádza zoznam dostupných API volaní konektora. V tomto prípade API volanie Profile.
3. Spustenie testu
Po výbere operácie je možné spustiť jej testovanie kliknutím na tlačidlo Test operation. Power Automate v tomto kroku vykoná reálne API volanie na CDESK server pomocou zvolenej connection.
4. Vyhodnotenie odpovede
Výsledok testu je zobrazený v spodnej časti obrazovky v sekcii Response. Status 200 indikuje úspešné vykonanie operácie. Zobrazené sú HTTP hlavičky aj telo odpovede. Zelený krúžok pri operácii potvrdzuje, že volanie prebehlo úspešne a konektor funguje správne.
V tomto prípade sme zavolali API endpoint Profile, ktorý nám vrátil informácie o aktuálnom prihlásenom používateľovi. V response môžete nahliadnuť do poľa Body, kde bude zobrazené aktuálne ID používateľa a overiť si že konektor vykonáva API volania pod správnym CDESK účtom.
V prípade chyby je možné detailne analyzovať odpoveď servera a prípadné chyby v záložke Code Logs.