Akcja "Wywołaj REST Web service"

WEBCON Redaktor Akcje,Procesy
Facebooktwitterpinterestlinkedinmail
Dotyczy wersji 2020.1.3.x autor: Dawid Golonka

 

Wprowadzenie

Jedną z funkcjonalności, która w znaczący sposób rozszerza potencjał systemu WEBCON BPS  jest możliwość korzystania z interfejsu REST API. API jest podstawowym sposobem wymiany danych między dwoma systemami i jest ono często wykorzystywane, zarówno do pobierania, jak i przekazywania danych z WEBCON BPS do innych aplikacji (np. przekazanie danych do systemu urlopowego). Na naszym blogu technicznym znajduje się artykuł, który opisuje przykłady użycia API udostępnionego przez WEBCON (https://kb.webcon.pl/przyklady-uzycia-rest-api/). W tym artykule opisana zostanie akcja, która dostępna jest z poziomu Designer Studio i umożliwia korzystanie również z zewnętrznych serwisów udostępniających swoje API – akcja "Wywołaj REST Web service".

 

Konfiguracja

Jako przykład korzystania z zewnętrznych serwisów API, przedstawiona zostanie integracja obiegu z białą listą podatników VAT.  Dokumentacja API, udostępniona przez Ministerstwo Finansów znajduję się pod linkiem: https://www.gov.pl/web/kas/api-wykazu-podatnikow-vat.

W ramach prezentacji przygotowany został prosty obieg, który na podstawie NIPu zwróci dodatkowe informacje o firmie, takie jak jej numer KRS, czy adres przedsiębiorstwa.

Rys. 1. Schemat obiegu, w którym zostanie użyta akcja

 

W celu zwiększenia czytelności, obieg sprawdzania został rozbity na trzy kroki. Na kroku rejestracyjnym użytkownik podaje NIP przedsiębiorstwa, którego dane chce pozyskać. W kroku sprawdzającym, użytkownik sprawdza wprowadzone dane, gdy stwierdzi, że dane nie są prawidłowe może cofnąć element do kroku startowego. Dla prawidłowych danych następuje przejście ścieżką „Pobierz dane”, na której to wywołana zostaje akcja łączenia z restowym API Ministerstwa Finansów. Następnie użytkownik kieruje element do kroku końcowego, gdzie będą przechowywane informacje o firmie, wraz z datą ich pobrania.

Na poniższym zrzucie przedstawiony jest widok na formularz pierwszego kroku, należy wprowadzić tutaj NIP wybranej firmy.

Rys. 2. Krok rejestracyjny, podajemy w nim NIP przedsiębiorstwa

 

Po przejściu dalej element trafia do kroku, w którym można pobrać informacje z API ministerstwa. Aby to zrobić, należy przejść ścieżką „Pobierz dane”.

Rys. 3. Akcja wywołania Web serwisu wykonuje się na przycisk

 

Po wybraniu tego przycisku wywołana zostanie akcja typu „Wywołaj REST Web service”, jej konfiguracja została opisana poniżej.

 

Konfiguracja akcji

Rys. 4. Wybór akcji

 

Na karcie „Autentykacja” ustawiane są parametry dotyczące autentykacji, może się ona dokonywać na podstawie konfiguracji stworzonego wcześniej połączenia, bądź należy ją skonfigurować ręcznie w panelu „Niestandardowe”.

Rys. 5. Konfiguracja akcji, karta autentykacji

 

Wybierając rodzaj autentykacji, zmienia się liczba i rodzaj pól, które należy uzupełnić.

Rodzaj autentykacji Wymagane pola
Anonimowa brak
NT Użytkownik; Hasło
Microsoft Dynamics 365 –

Połączenie jako użytkownik

 Użytkownik; Hasło; Client ID
Microsoft Dynamics 365 –

Połączenie jako aplikacja

 URL bazowej instancji serwisu; Client ID; Client Secret
Salesforce Użytkownik; Hasło; URL bazowej instancji serwisu; Client ID; Client Secret
WEBCON BPS –

Połączenie jako użytkownik

 Użytkownik; Client ID; Client Secret
WEBCON BPS –

Połączenie jako aplikacja

 Client ID; Client Secret
Microsoft Graph Tenant ID lub URL serwisu uwierzytelniającego; App ID; App Secret
Microsoft Dynamics 365 on-Premises Użytkownik; Hasło; URL bazowej instancji serwisu; Client ID; Client Secret

 

Na dole panelu należy podać URL bazowej instancji serwisu, istnieje również możliwość wyłączenia sprawdzania certyfikatów HTTPS.

Rys. 6. Karta z danymi żądania

 

Na karcie z danymi żądania wprowadzić należy adres URL żądania REST, bądź jego sufix. W prezentowanym przykładzie podany jest sufix sparametryzowany o NIP (pobierany z formularza), a także dzisiejszą datę (zmienna systemowa).

W celu wczytania odpowiedzi dla późniejszego mapowania, zamiast atrybutów należy ręcznie wprowadzić przykładowe dane (NIP i datę), gdyż w chwili obecnej, przed utworzeniem pierwszego elementu obiegu, pola te nie zwracają żadnych wartości.

Do wyboru jest 5 metod HTTP:

  • GET
  • POST
  • PUT
  • PATCH
  • DELETE

Metody POST, PUT i PATCH wymagają dodatkowo uzupełnienia zawartości żądania na kolejnej z zakładek. W sekcji „Dodatkowe nagłówki żądania”, jak sama nazwa wskazuje, można dodać dodatkowe nagłówki żądania takie jak m.in. dane hosta czy klucza API.

W sekcji dotyczącej odpowiedzi możliwe jest zdefiniowanie mapowań tj. wskazanie atrybutów formularza, do których zostaną zapisane dane uzyskane z odpowiedzi na zdefiniowane żądanie HTTP.

Rys. 7. Mapowanie atrybutów

 

W prezentacyjnym przykładzie z uzyskanych danych, do formularza przekazane zostaną:

  • Nazwa firmy,
  • NIP,
  • REGON,
  • KRS,
  • Adres

Poniżej przedstawiony został rezultat wykonania akcji znajdującej się na ścieżce przejścia „Pobierz dane”, dla wybranego przez nas NIPu. Zwrócone wartości przeniosły się do formularza:

Rys. 8. Dane przeniesione do pól na formularzu

 

Dodany został również atrybut „Data sprawdzenia”, odkładający informację o tym, ze stanu na jaki dzień pobrane zostały dane. Teraz można już przesunąć dokument do kroku końcowego, gdzie dane będą przechowywane w trybie tylko do odczytu. Aby w przyszłości szybko uzyskać dostęp do danych, NIP spółki został umieszczony jako składowa sygnatury elementu.

 

Obsługa błędów

Opisywana akcja umożliwia również konfigurację obsługi błędnych odpowiedzi. Dostępne są dwa warianty obsługi kodów http:

  • Przerywaj wykonanie gdy status HTTP należy do grup 300, 400 lub 500,
  • Kontynuuj wykonanie gdy status HTTP należy do grup 300, 400 lub 500

Poniższy zrzut ekranu, został wykonany przy konfiguracji akcji ustawionej na przerywanie wykonania w przypadku napotkania błędu. Podany został NIP, pod którym nie figuruje żadne przedsiębiorstwo:

Rys. 9. Przy próbie pobrania danych dla błędnego NIPu pojawia się błąd

 

Jak widać został zwrócony błąd, który przerwał wykonanie akcji. Błąd o kodzie 400 według dokumentacji oznacza niepoprawny parametr na wejściu.

Drugi wariant umożliwia kontynuowanie wykonania żądania, pomimo wystąpienia kodu błędu. Taka możliwość jest szczególnie przydatna wtedy, gdy API z którego korzystamy ma wbudowaną obsługę wyjątków. API wykorzystane w tym artykule, przy pojawieniu się błędu może zwracać wartość z wiadomością dotyczącą błędu – aby sprawdzić działanie tej funkcjonalności zmapujemy tę wiadomość do atrybutu „Opis błędu”. Atrybut ten będzie wyświetlany tylko wtedy, gdy akcja wywołania serwisu REST będzie zwracała jakiś błąd. W takiej sytuacji, pozostałe pola na formularzu zostaną ukryte.

Rys. 10. Po podaniu błędnego NIPu otrzymujemy stosowny komunikat

 

Tym razem po pobraniu danych dla podanego NIPu, nie otrzymaliśmy komunikatu błędu pochodzącego z systemu BPS. O tym, że coś poszło nie tak, dowiadujemy się z atrybutu z opisem błędu, gdzie wprowadzony został komunikat zwrócony przez API. Informuje on o tym, że podano nieprawidłowy NIP.

Akcja wywołania Web serwisu umożliwia również zmapowanie wartości Code oraz Body odpowiedzi, zarówno w przypadku pozytywnego, jak i błędnego wywołania. W bardziej skomplikowanych przypadkach może to umożliwić obsługę błędów po stronie BPS.

Rys. 11. Code oraz Body odpowiedzi dla błędnego żądania, przeniesione do formularza