Dotyczy wersji 2020.1.3.x autor: Franciszek Sakławski
Wstęp
Jedną z funkcjonalności w znaczący sposób rozszerzającą potencjał systemu WEBCON BPS jest możliwość korzystania z interfejsu REST API. W tym artykule opisana została funkcjonalność umożliwiająca skonfigurowanie źródła danych opartego na informacjach zwracanych przez zewnętrzne serwisy udostępniające swoje API.
Przykładem wykorzystania źródła danych typu REST może być źródło danych Kontrahentów. Podpięcie źródła z zewnętrznego systemu może nam zapewnić aktualność danych. Innym przykładem jest użycie API udostępnionego przez WEBCON, aby umożliwić wyświetlenie tabeli danych na podstawie raportu z Portalu.
Zalety skorzystania ze źródła danych typu REST:
- Aktualność danych
- Oddelegowanie zarządzania słownikiem do innego systemu
Wady wynikające z użycia tego typu źródła danych:
- Przerwa w działaniu usługi uniemożliwia korzystanie z formularza,
- Wydajność i responsywność – długi czas odpowiedzi interfejsu będzie miał bezpośrednie przełożenie na jakość użytkowania formularza.
Konfiguracja
Przykładem, którym posłużymy się w tym artykule jest skorzystanie z jednego z darmowych API, które przechowuje informacje dotyczące państw świata. Na początku zestawić należy połączenie do serwisu, wykonuje się to w zakładce „Połączenia”, pozycja „REST Web Service”:
Efekt końcowy wygląda jak na poniższym zrzucie. Po wybraniu wartości pola wyboru „Państwo”, automatycznie uzupełniane są informacje na jego temat.
Rys.1. Wyświetlanie informacji o danym kraju w obiegu
Konfigurację rozpoczynamy od utworzenia połączenia. Przy definiowaniu połączenia należy wskazać rodzaj autentykacji i w zależności od wybranej opcji uzupełnić pola konfiguracyjne poniżej. Dostępne są następujące rodzaje autentykacji:
- Anonimowa,
- NT,
- Microsoft Dynamics 365,
- Salesforce,
- WEBCON BPS,
- Microsoft Graph,
- Microsoft Dynamics 365 on-Premises
Rys.2. Tworzenie połączenia typu REST Web Service
Ostatni wiersz w oknie konfiguracji, służy do wprowadzania adresu instancji bazowej serwisu.
Rys. 3. Konfiguracja źródła typu REST Web Service
Kolejnym krokiem jest utworzenie źródła danych typu REST Web Service. W konfiguracji należy wybrać połączenie, z którego źródło ma korzystać, a także podać adres URL pożądanego zasobu (suffix) – zostanie on dodany do bazowego adresu usługi. Jeśli wybrane przez nas API tego wymaga (bądź na to zezwala), suffix może zostać sparametryzowany. Dalej należy wybrać metodę HTTP – obsługiwanymi metodami są GET, POST, PUT, PATCH oraz DELETE. Pobranie danych o państwach odbywać się będzie przy wykorzystaniu metody GET. W sekcji poniżej istnieje możliwość wprowadzenia dodatkowych parametrów nagłówków – zgodnie z wymaganiami zawartymi w dokumentacji wybranego przez nas API (w tym przypadku jest to host oraz klucz API). Dokumentacja API jest udostępniania przez jego autora, a konfigurację połączenia oraz zapytania należy przeprowadzać w zgodności z nią.
W tym miejscu możemy również ustawić sposób filtrowania: po stronie BPS lub usługi. Filtrowanie po stronie BPS spowoduje, że najpierw zostanie pobrana cała kolekcja danych a dopiero później znaleziona zostanie szukana wartość (np. kontrahent o podanym NIPie). Filtrowanie może być wykonywane po stronie Web Serwisu lecz zależy to od odpowiedniego przygotowana usługi (np. usługa musi przyjmować dodatkowe parametry). Sposób filtrowania ma wpływ na wydajność wyszukiwana wartości w źródle danych.
W drugiej zakładce można skonfigurować obsługę komunikatu odpowiedzi.
Rys. 4. Wczytana struktura odpowiedzi
W oknie z odpowiedzią po wybraniu przycisku „Wczytaj” pojawi się struktura danych zwracanych przez usługę. Checkboxem w kolumnie „Result” należy zaznaczyć tę kolekcję, na podstawie której zostanie utworzona tabela danych. Wczytanie struktury wymaga wywołania usługi. W przypadku, gdy nie jest to możliwe drugim sposobem jest kliknięcie przycisku „Wczytaj z wzorca” co otworzy nowe okno, w którym możemy wprowadzić schemat gotowej już odpowiedzi – stworzony na przykład na podstawie dokumentacji usługi. Po wklejeniu odpowiedzi, WEBCON BPS Studio odwzoruje listę pól, które zwracane są w danym zasobie.
Rys. 5. Wklejenie treści odpowiedzi do okna w konfiguracji odpowiedzi
Zakładka z odpowiedzią została uzupełnione według wczytanego schematu:
Rys. 6. Pola odpowiedzi uzupełnione na podstawie schematu
W przykładowym procesie konfigurujemy pole wyboru, ze źródłem, które wcześniej skonfigurowaliśmy. Sposób konfiguracji atrybutu nie różni się od konfiguracji z użyciem innego typu źródła danych.
Rys. 7. Atrybut korzystający z nowo utworzonego źródła
Wartości z pola wyboru wstawiane są do atrybutów przechowujących informacje o stolicy, powierzchni i populacji miasta.
Rysunek 8. Przenoszenie danych z atrybutu pola wyboru
Podsumowanie
Źródła typu REST Web Service są przydatnym sposobem na pobieranie danych z zewnętrznych systemów. Standardowe funkcjonalności BPS pozwalają na ich konfigurację i wykorzystanie bez konieczności znajomości języków programowania, co usprawnia tworzenie nowych aplikacji.
