Wtyczka „Przycisk” jako narzędzie do pobierania zewnętrznych danych

10.04.2024

W systemie Dew-X integracje z innymi systemami, czy źródłami danych są możliwe za sprawą tzw. webhook-ów. Do niedawna pewnych trudności nastręczała kwestia wywołania i korzystania z zewnętrznych danych przed zamknięciem formularza i przesłania go dalej.

Dzięki nowej wtyczce o nazwie „Przycisk” możliwości integracyjne zostały znacznie rozszerzone

W poniższym, dość nieskomplikowanym przykładzie, zademonstrowano użycie Przycisku do wywołania funkcji, która na podstawie danych z formularza odpytuje zewnętrzną bazę danych i na podstawie uzyskanych wyników uzupełnia inne pole tego samego formularza.

Biznesowo sytuacja wyglądała następująco – klient posiada obieg faktur gdzie na kroku rejestracji, za sprawą wtyczki GUS, bardzo łatwo pozyskuje dane nabywcy na podstawie NIP-u. Problematyczna okazała się kwestia integracji z systemem księgowym na ostatnim kroku procesu, gdzie wymagany był numer księgowy kontrahenta. Zastosowany skrypt sprawdza na bazie NIP-u, czy taki kontrahent istnieje w bazie danych systemu księgowego i zwraca jego numer bądź komunikat o konieczności założenia takowego dostawcy w bazie.

Do wykonania takiej integracji konieczne stało się umieszczenie Przycisku na formularzu. Ten krok jest dość trywialny i podobnie jak w przypadku innych wtyczek wymaga jedynie dodania jej na formularz oraz skonfigurowania poprzez podanie kilku informacji.

Najważniejszą z nich jest adres, w którym umieściliśmy skrypt, gdzie zaszyta jest logika operacji. W prezentowanym przykładzie jest to skrypt check_supplier który wykonaliśmy przy użyciu frameworku Laravel. Oczywiście Twój skrypt może być napisany w dowolnym języku.

Aby Twój skrypt wpływał na to co posiadasz na formularzu bądź w procesie musi zawierać trzy podstawowe właściwości:

Przyjmować dane z żądania (wysyłane są za pomocą POST)
Wykonywać właściwą operację (np. pobrać dane z zewnętrznej bazy albo innego procesu w Dew-X, wykonać bardziej złożone operacje)
Dokonać aktualizacji danych w aktualnej instancji, z której wywołano żądanie.

Poniżej znajduje się obrazek ilustrujący konfigurację Przycisku do integracji.

Widok formularza (przykład)

Po uruchomieniu procesu, Przycisk jest częścią większej całości – widzimy tu wtyczkę GUS, sekcję opisu, sam Przycisk i pole które Przycisk ma uzupełnić. Pól, czy tabel jakie uzupełnia Przycisk (np. pobierz wartości zamówienia po wskazaniu numeru zamówienia) może być dowolnie wiele. W podanym przykładzie chodzi o uzupełnienie jednego pola.

Najpierw użytkownik wypełnia pole NIP i klika szukaj w GUS. Za sprawą tej wtyczki pobierają się dane kontrahenta.

Następnie, do akcji wchodzi utworzony przez nas Przycisk, pod którym podczepiono link do napisanego i opublikowanego skryptu. Po jego naciśnięciu do pola “Nr księgowy kontrahenta” pobierana jest wartość z systemu księgowego klienta. Zanim to się stanie, następują dwa działania, będące immanentnymi cechami uruchomienia każdego Przycisku – zapis danych przed i odświeżenie formularza po wykonaniu się skryptu.

Widok skryptu (przykład)

Oczywiście by nasz skrypt zadziałał oraz wpłynął na to co znajduje się na formularzu, wymagane jest by był dostępny w otwartej sieci, przyjmował żądanie typu POST, a wewnątrz znajdowały się odwołania pozwalające pobrać i/lub edytować dane instancji za pomocą funkcji CURL (Call to URL). Dla celów tego ćwiczenia nasz skrypt został oparty o framework Laravel – możecie użyć dowolnego języka, czy frameworku spełniającego powyższe kryteria.

Najpierw osadziliśmy nasz skrypt w routingu instancji Laravela – użyliśmy do tego celu pliku api.php znajdującego się w katalogu routes

Serwer i instalacja klienta zamknięte są w wewnętrznej sieci, dlatego nie było konieczności stosowania żadnych dodatkowych metod autoryzacji. Jeżeli jednak Twój serwer, na którym umieszczasz swoje skrypty działa w otwartej sieci, bądź korzystasz z bezpłatnej wersji systemu Dew-X powinieneś zabezpieczyć routing przynajmniej poprzez akceptowanie żądań jedynie z naszego serwera Dew-X.

Gdy już ustaliliśmy routing, a nasz skrypt zaczął być osiągalny, zbudowaliśmy funkcje checkSupplier w ramach kontrolera.

W ramach działania Przycisku wysyłane są dwie kluczowe informacje:

token – pozwalający wykonać operacje API zakończone frazą system (jak pobranie danych instancji, czy aktualizacja danych)
instance – mówiące z jakiej unikalnej instancji procesu pochodzi żądanie

Uwaga: jeżeli chcesz wykorzystać inne metody API musisz posłużyć się kluczem konkretnego użytkownika (najczęściej własnym). Wygenerujesz go z interfejsu Dew-X.

W naszej funkcji oprócz pobierania danych z żądania mamy odwołanie do prywatnej funkcji getSupplierNumber, w której używamy zarówno tokena jak i instancji. Używamy ich by w pierwszej kolejności pobrać dane instancji za sprawą API systemu Dew-X, w której wywołano skrypt Przyciskiem

Uwaga: w większości funkcji konieczne jest podanie id organizacji by wiedzieć w jakim kontekście chcemy korzystać z API.

Po pobraniu dekodujemy dane zamieniając je w tablice, gdzie za sprawą funkcji foreach znajdujemy potrzebne nam dane instancji – w naszym wypadku jest to NIP wskazanego przedsiębiorcy z pola NIP wtyczki GUS, którą nazwaliśmy “Dane firmy” oraz id pola o kluczu “nr_ksiegowy_kontrahenta”.

Uwaga: nie zalecamy szukania po id pól gdyż te ulegają zmianie przy każdej aktualizacji wersji procesu. Znacznie bezpieczniej szukać po nazwie pola (label) a najlepiej, tam gdzie to możliwe, po kluczu (key).

Gdy już mamy potrzebne dane pytamy bazę danych naszego systemu księgowego o kod kontrahenta. Użyjemy go na końcu procesu do integracji, teraz zaś potrzebny nam jest do uzupełnienia pola “Nr księgowy kontrahenta”