Dotyczy wersji: 2021 R1 i powyżej; autor: Agnieszka Burda
Wprowadzenie
W WEBCON BPS istnieje możliwość korzystania z interfejsu API. W artykule dostępnym pod adresem https://kb.webcon.pl/akcja-wywolaj-rest-web-service/ opisano akcję „Wywołaj REST Web service” dostępną w Designer Studio, która umożliwia korzystanie z zewnętrznych serwisów udostępniających własne API. W niniejszym artykule omówiono nowości, jakie wprowadzono we wspomnianej akcji w wersji BPS 2021.
JSON – grid
Na potrzeby prezentacji skonfigurowano prosty obieg, którego zadaniem jest pobieranie średnich kursów walut z NBP.
Formularz kursu walut
W górnej belce dodano przycisk „Pobierz kursy walut” wykonujący akcję „Wywołaj REST Web Service”.
Pierwsza zmiana dotyczy dodania opcji „JSON – grid” w polu „Typ zawartości” (akcja „Wywołaj REST Web service” → przycisk wielokropka pionowego → „Konfiguracja” → zakładka „Zawartość żądania” → „Typ zawartości”) dla metody POST. Po przejściu do konfiguracji akcji i zakładki „Dane żądania” w polu „Typ metody http” należy wybrać opcję „POST”.
Konfiguracja zakładki „Dane żądania”
Następnie po przejściu do zakładki „Zawartość żądania” na liście rozwijanej dostępna będzie opcja „JSON – grid”. Opcja ta umożliwia wygodne mapowanie wartości, które mają zostać przesłane. W kolumnie „Nazwa” należy podać nazwę mapowanej wartości, natomiast w kolumnie „Pole źródłowe” nazwę atrybutu, z którego pobierana jest wartość.
Konfiguracja zakładki „Zawartość żądania”
Reguły biznesowe w JSON – grid
Kolejną zmianą jest dodanie kolumny „Reguła biznesowa” widocznej w zakładce „Zawartość żądania” dla żądania typu „JSON – grid” oraz w zakładce „Odpowiedź”. Dzięki temu istnieje możliwość modyfikacji wysyłanych lub odbieranych danych. Jeżeli w danym wierszu ikona w kolumnie „Reguła biznesowa” jest wyszarzona, oznacza to, że nie jest ona wykorzystywana.
Konfiguracja zakładki „Odpowiedź”
Po kliknięciu na wyszarzoną ikonę otwiera się okno konfiguracji reguły, w którym domyślnie wstawiona jest wartość „Input value”, która oznacza odpowiednio dla:
- zakładki „Zawartość żądania” – wartość wysyłaną;
- zakładki „Odpowiedź” – wartość odbieraną.
Wykorzystując ten parametr, można edytować dane tuż przed ich wysłaniem lub odebraniem. Przykładowo, gdy odebrana zostaje wartość, która przed zapisem w bazie wymaga pomnożenia przez wartość 0,01, należy stworzyć regułę, która wykona takie działanie. Ponadto można określić format zwracanej wartości, co zostanie omówione w późniejszym rozdziale.
Edycja reguły biznesowej
Dopiero po wykonaniu obliczeń, wartość zostanie przypisana do wskazanego pola na formularzu. W przypadku wartości wysyłanych sytuacja jest podobna: mapowany atrybut zostaje przekształcony zgodnie z utworzoną regułą biznesową, a dopiero potem zostaje wysłany.
Możliwość zmiany typu danych
W wersji WEBCON BPS 2021 wprowadzono możliwość zmiany typu mapowanej wartości. Dotychczas typ wartości konwertowano do typu atrybutu wskazanego w zakładce „Odpowiedź”, przy czym była to konwersja stringowa w danej kulturze serwera. W wersji 2021 zachowano mechanizm, za sprawą którego wszystkie dane konwertowane na string są konwertowane w kulturze bieżącego serwera. Dodatkowo użytkownik ma możliwość wskazania formatu danych poprzez wybór z listy rozwijanej jednej z poniższych wartości:
- int
- decimal
- boolean
- date
- datetime
Zmiana typu wartości w zakładce „Odpowiedź”
Przykładowo, gdy wartość zmiennoprzecinkowa (decimal) ma zostać przepisana do atrybutu typu decimal, wówczas w konfiguracji mapowania wartości możliwe jest wybranie odpowiedniego typu. W efekcie unika się niepotrzebnej konwersji danych. Typy danych pojawiły się także w konfiguracji reguły biznesowej.
Zmiana typów w regule biznesowej
Dodatkowo podczas konfiguracji reguły istnieje możliwość zmiany typu parametru, który jest w niej wykorzystywany. Po kliknięciu prawym przyciskiem myszy na parametrze i wybraniu opcji „EDYTUJ” z menu rozwijanego otwiera się okno konfiguracji.
Zmiana typu parametru „Input value”
Dostępne typy parametru są takie same, jak te w oknie konfiguracji samej reguły biznesowej.
Konwersja z JSON – grid na JSON
W przypadku, gdy żądanie zostanie utworzone w formacie „JSON – grid”, istnieje możliwość konwersji danych do formatu „JSON” bez utraty struktury danych.
Zawartość żądania w formacie „JSON – grid”
W tym celu należy zmienić typ danych w polu „Typ zawartości” z „JSON – grid” na „JSON”. W tym momencie wyświetlone zostanie pytanie, czy dokonać mapowania wartości.
Komunikat informujący o wygenerowaniu formatu JSON
Po zaakceptowaniu dane pojawią się w odpowiednim formacie.
Zawartość żądania w formacie JSON
Odbieranie zagnieżdżonej kolekcji
W wersji WEBCON BPS 2021 dostępna jest możliwość zagnieżdżania kolekcji.
W przykładzie wykorzystany zostanie interfejs API udostępniany przez Narodowy Bank Polski (NBP). Tabela A dostępna pod adresem http://api.nbp.pl/api/exchangerates/tables/A zawiera aktualnie obowiązujące średnie kursy walut. Jak widać na załączonym poniżej zrzucie, kolekcja „ExchangeRatesTable”, oprócz pól „Table”, „No” i „EffectiveDate”, zawiera także kolekcję „Rates”, w której znajdują się kursy poszczególnych walut.
Tabela A interfejsu API Narodowego Banku Polskiego
Aby zwrócić na formularzu dane w takim schemacie, należy zacząć od skonfigurowania połączenia z NBP, a następnie określenia właściwej tabeli i metody.
Zakładka „Dane żądania”
W zakładce „Odpowiedź” za pomocą przycisku „Wczytaj” można w prosty sposób wczytać strukturę.
Wczytywanie struktury
Po prawidłowym wczytaniu danych można zauważyć, że są one dwupoziomowe.
Zmapowana struktura danych
Aby poprawnie zmapować dane, należy na poziomie oznaczonym prawym ukośnikiem („/”) wybrać listę pozycji, do której mają zostać wczytane wartości. Lista ta zostanie automatycznie podpięta także na poziomie „rates” bez opcji jej edycji. Warto pamiętać, że nie ma możliwości podpinania różnych list do zagnieżdżonych kolekcji.
Mapowanie list pozycji
Następnie konieczne jest podanie dla mapowanych wartości odpowiednich kolumn z wybranej listy pozycji „Average exchange rate”.
Mapowanie kolumn listy pozycji
Jak widać na załączonym zrzucie, zgodnie z założeniem po wciśnięciu przycisku na listę pozycji „Średni kurs walut” zostają zmapowane średnie kursy walut.
Kursy walut zmapowane na listę pozycji
Jeżeli, oprócz mapowania wartości na listę pozycji, konieczne jest zmapowanie wartości na inne atrybuty, należy dodać dwie kolumny techniczne: „_data obowiązywania” (typu data) i „_numer” (typu tekst). Dodano je także w ustawieniach mapowania wartości w konfiguracji akcji.
Mapowanie wartości do kolumn technicznych listy pozycji
W ten sposób data oraz numer zostaną zapisane w kolumnach technicznych. Aby wartości z tych kolumn przekazać do atrybutów, najlepiej wykorzystać akcję „Zmień wartość pola”. Do przycisku „Pobierz kursy walut” uruchamiającego akcję „Wywołaj Rest service” dodano dwie nowe akcje zmieniające wartość pola o nazwach odpowiednio „Zmień datę” i „Zmień numer”.
Dwie nowe akcje zmieniające wartość pola
Akcja „Zmień datę” pobiera wartość z kolumny „_data obowiązywania” z listy pozycji i za pomocą funkcji „Distinct” wybiera unikalne wartości. Ponieważ wszystkie kolumny zawierają taką samą wartość, funkcja ta zwraca tylko jedną datę. Warto nadmienić przy tym, że zamiast funkcji „Distinct” możliwe jest skorzystanie z funkcji „Min” lub „Max”.
Konfiguracja akcji zmiany wartości pola
W analogiczny sposób skonfigurowano akcję „Zmień numer”.
Po wciśnięciu przycisku na formularzu można zauważyć, że do pól „Data obowiązywania” i „Numer” prawidłowo zmapowano wartości.
Wartości zmapowane na pola „Numer” oraz „Data obowiązywania”
Wysyłanie zagnieżdżonej kolekcji
Aby zaprezentować funkcjonalność wysyłania zagnieżdżonej kolekcji, utworzono prosty obieg faktury kosztowej zawierający listę pozycji z rozbiciem analitycznym.
Formularz faktury kosztowej
Jak widać na załączonym zrzucie, w kolumnie „Kod centrum kosztowego” dostępne są dwie wartości, względem których zawężane są następnie wartości w kolumnie „Typ kosztów".
Schemat danych, które mają zostać wysłane, został zapisany w formacie JSON i zaprezentowany na poniższym zrzucie.
Struktura wysyłanych wartości
Wysyłane dane to:
- atrybut „Numer faktury”
- atrybut „Data”
- atrybut Kwota netto
- kolekcja „Zestawienie kosztów”, a w niej
- kolumna „Kod centrum kosztowego”
- zagnieżdżona kolekcja „Szczegóły”, a w niej
- kolumna „Typ kosztów”
- kolumna „Wartość”
W celu wysłania danych utworzony został przycisk „Prześlij fakturę” z akcją „Wywołaj REST Web service”.
Po dodaniu połączenia do web serwisu, do którego wysyłane będą dane, oraz wybraniu metody „POST” w zakładce „Zawartość żądania” utworzono strukturę mapowanych wartości.
Konfiguracja zakładki „Zawartość żądania”
Pobieranie danych ze Swaggera
Ostatnią z funkcjonalności, które pojawiły się w wersji BPS 2021, jest możliwość połączenia z wykorzystaniem Swaggera. W oknie konfiguracji akcji, w zakładce „Dane żądania” pojawiła się sekcja „Na podstawie Swaggera”.
Opcja pobierania danych ze Swaggera
Po wciśnięciu przycisku „Wczytaj” pojawi się okno „Definicja Swaggera”, w którym należy podać link do Swaggera
Okno wyboru
Po zaakceptowaniu zostaną załadowane wszystkie dostępne metody. Aby wybrać żądaną, należy kliknąć wybraną metodę z rozwijanej listy.
Dostępne metody
