Import aplikacji przy użyciu publicznego API

Facebooktwitterpinterestlinkedinmail
Dotyczy wersji: 2024 R1 i powyżej; autor: Krystyna Gawryał

 

Wprowadzenie

Platforma WEBCON BPS jest wyposażona w mechanizmy eksportu oraz importu aplikacji, dzięki którym aplikacje mogą być przygotowywane w jednym środowisku (DEV/TEST/PROD), a następnie wdrażane w kolejnym. Do tej pory operacje eksportu i importu były wywoływane przez administratora w WEBCON BPS Designer Studio i wymagały interakcji z użytkownikiem, wskazania dokładnego zakresu eksportu/importu oraz kontroli ich przebiegu. Takie postępowanie mogło jednak być utrudnione, np. z uwagi na ograniczony dostęp do poszczególnych środowisk lub brak odpowiednich uprawnień.

Wraz z wersją 2024 R1 wprowadzono funkcjonalność, która umożliwia zautomatyzowanie operacji importu aplikacji oraz jej wykonanie w z wykorzystaniem publicznego API w Portalu. W niniejszym artykule opisano tę funkcjonalność oraz wszelkie towarzyszące jej zmiany systemu.

 

Aplikacja do automatycznego importu

Wprowadzenie funkcjonalności wiązało się z przygotowaniem odpowiednich narzędzi. W związku z tym powstała konsolowa aplikacja o nazwie BatchImportApp (plik .exe), którą udostępniono wśród plików instalacyjnych WEBCON BPS w katalogu „Tools” (uprzednio „Migration Tools”). Narzędzie to wykonuje import aplikacji WEBCON BPS z wykorzystaniem zdefiniowanych parametrów. Podanie niektórych z nich jest wymagane, aby operacja automatycznego, domyślnego importu zakończyła się powodzeniem, natomiast udostępniono w niej również parametry opcjonalne, które służą do niestandardowego importu danych lub też bezpośrednio odnoszą się do samego narzędzia.

W Tab. 1 poniżej wyszczególniono wspomniane parametry ze wskazaniem ich funkcji i wymagalności.

Tab. 1. Parametry automatycznego importu aplikacji

Parametry wymagane
Nazwa Opis
-a, –portalAddress Adres Portalu
-d, –dbId ID bazy zawartości
-c, –clientId Client ID
-s, –clientSecret Client secret
-p, –package Ścieżka wyeksportowanej paczki
Parametry opcjonalne
Nazwa Opis
-i, –importConfiguration Ścieżka do pliku .json z niestandardową konfiguracją importu
-l, –splitFileLargerThan Podział pliku paczki większego niż 20 MB (domyślnie)
-f, –fileChunkSize Rozmiar pojedynczej partii w przypadku podziału pliku paczki;
domyślnie 4 MB
–help Wyświetlenie pomocy kontekstowej z opisem parametrów
–version Wyświetlenie informacji o wersji aplikacji

 

Rys. 1. Podgląd ekranu aplikacji z objaśnieniami parametrów importu

 

Procedura automatycznego, domyślnego importu aplikacji

Przygotowanie do importu

Zgodnie z Tab. 1 powyżej, parametrami wymaganymi do domyślnego importu za pomocą dedykowanej aplikacji konsolowej są: adres Portalu i ID bazy danych na środowisku, na którym aplikacja ma być zaimportowana, dane uwierzytelniające aplikacji API, za pośrednictwem której ma odbyć się import, tj. Client ID oraz Client secret, a także ścieżka wyeksportowanej wcześniej z Designer Studio paczki z danymi w postaci pliku .bpe na dysku lokalnym.

Import automatyczny można przeprowadzić za pomocą dowolnej aplikacji API. Parametry Client ID oraz Client secret dostępne są w jej oknie konfiguracyjnym (Profil użytkownika → Administracja → IntegracjaAPI).

Rys. 2. Okno edycji aplikacji API z zaznaczonymi danymi uwierzytelniającymi

 

Aby import był możliwy, na liście uprawnień aplikacji API należy zaznaczyć nową pozycję Admin.Import, która umożliwia odczyt i modyfikację wszystkich danych konfiguracyjnych wykorzystywanych podczas importu aplikacji. (Operacja powiedzie się również przy zaznaczonym uprawnieniu Admin.ReadWrite.All).

Rys. 3. Okno uprawnień aplikacji API z wybraną rolą Admin.Import

 

Domyślny import aplikacji za pomocą API

Aby zainicjować standardowy import aplikacji, za pomocą wiersza poleceń CMD należy otworzyć konsolową aplikację BatchImportApp, a następnie wprowadzić wszystkie wymagane parametry wraz z ich odpowiednimi wartościami. Kolejność podawania parametrów w poleceniu jest dowolna.

Rys. 4. Przykład polecenia do domyślnego importu aplikacji

 

O pomyślnym imporcie aplikacji będzie świadczył status „Completed” w wierszu poleceń. Dodatkowo logi aplikacji dostępne są w pliku .txt.

Rys. 5. Informacje dotyczące pomyślnie zakończonego importu aplikacji
w konsoli CMD

Historia importu

Oprócz możliwości korzystania z nowej/zaktualizowanej aplikacji na środowisku docelowym, użytkownicy mogą teraz dodatkowo sprawdzić szczegóły przeprowadzonego importu automatycznego. Podobnie jak w przypadku standardowego importu za pomocą kreatora, wszelkie odnośne informacje i logi są dostępne w Historii importu. Dodatkowo zakres logowanych informacji rozszerzono o sekcję „LogSummary” zawierającą podsumowanie importu.

Rys. 6. Historia importu z zaznaczoną opcją pobierania logów
i fragmentem logu zawierającym sekcję „LogSummary”

 

W przypadku ewentualnych nieprawidłowości w logu dostępne będą również informacje na temat błędów importu (co uprzednio zostanie zasygnalizowane przez samą aplikację BatchImportApp).

 

Import automatyczny z użyciem dodatkowego pliku konfiguracyjnego

Pobieranie pliku konfiguracyjnego

Oprócz automatycznego importu aplikacji z wykorzystaniem parametrów domyślnych przewidziano także możliwość przeprowadzenia importu ze wskazaniem konkretnych elementów, które takiemu importowi będą podlegać. Rozwiązanie to jest szczególnie przydatne w przypadku rozbudowanych aplikacji (np. składających się z wielu procesów), gdzie wskazanie tylko istotnych z punktu widzenia importu elementów jest bardziej optymalne i uzasadnione.

W tym celu w oknie kreatora eksportu w Designer Studio dodano opcję Utwórz plik z domyślnymi parametrami importu (API). Po jej zaznaczeniu podczas eksportu aplikacji utworzony zostanie dodatkowy plik konfiguracyjny .json z ustawieniami, które będzie można opcjonalnie wykorzystać do importu aplikacji na środowisko docelowe za pomocą API. Parametry przekazywane w pliku zostaną zastosowane na etapie związanym z analizą paczki oraz środowiska, w którym następuje import.

Rys. 7. Okno kreatora eksportu z zaznaczoną opcją tworzenia pliku
z domyślnymi parametrami importu

 

Po udanej operacji eksportu plik .json zostanie automatycznie zapisany w lokalizacji wskazanej dla standardowego pliku eksportu .bpe. Zawartość pliku .json będzie można również przeglądać, klikając przycisk Parametry importu w kroku Zakończ w kreatorze.

Rys. 8. Okno kreatora eksportu z opcją podglądu pliku .json

 

Parametry pliku konfiguracyjnego

Zapisany na dysku plik .json zawiera domyślną konfigurację importu, a jego zawartość jest zawsze taka sama, niezależnie od eksportowanej aplikacji.

Rys. 9. Zawartość domyślnego pliku .json

 

Główną rolą pliku jest dostarczenie użytkownikowi  gotowej struktury, jakiej powinien użyć do niestandardowego importu aplikacji i danych konfiguracyjnych jej procesu(-ów). W Tab. 2. poniżej objaśniono funkcje wszystkich parametry dostępnych w pliku.

 

Tab. 2. Parametry pliku .json do niestandardowego importu aplikacji

Parametry
Nazwa Funkcja
ImportAllNewApplications Import wszystkich nowych aplikacji
ImportAllModifiedApplications Import wszystkich zmienionych aplikacji
ImportAllPresentationObjects Import wszystkich elementów prezentacji
ImportAllNewProcesses Import wszystkich nowych procesów
ImportAllModifiedProcesses Import wszystkich zmienionych procesów
ImportOnlySelected Applications Import tylko wybranych aplikacji
ImportBpsGroups Import grup BPS
ImportOnlySelectedBpsGroups Import tylko wybranych Grup BPS
OverwriteAllBusinessEntitiesPrivilegeSettings Nadpisanie uprawnień we wszystkich spółkach
OverwriteSelectedBusinessEntitiesPrivilegeSettings Nadpisanie uprawnień w wybranych spółkach
OverwriteSecuritySettings Nadpisanie ustawień bezpieczeństwa
OverwriteAllGlobalBusinessRules Nadpisanie wszystkich globalnych reguł biznesowych
OverwriteSelectedGlobalBusinessRules Nadpisanie wybranych globalnych reguł biznesowych
OverwriteAllGlobalFormRules Nadpisanie wszystkich globalnych reguł formularza
OverwriteSelectedGlobalFormRules Nadpisanie wybranych globalnych reguł formularza
OverwriteAllGlobalFields Nadpisanie wszystkich atrybutów globalnych
OverwriteSelectedlGlobalFields Nadpisanie wybranych atrybutów globalnych
OverwriteAllGlobalConstants Nadpisanie wszystkich stałych globalnych
OverwriteSelectedGlobalConstants Nadpisanie wybranych stałych globalnych
OverwriteAllGlobalAutomations Nadpisanie wszystkich automatyzacji globalnych
OverwriteSelectedGlobalAutomations Nadpisanie wybranych automatyzacji globalnych
OverwriteAllDataSources Nadpisanie wszystkich źródeł danych
OverwriteSelectedDataSources Nadpisanie wybranych źródeł danych
OverwriteAllConnections Nadpisanie wszystkich połączeń
OverwriteSelectedConnections Nadpisanie wybranych połączeń
OverwriteAllPluginPackages Nadpisanie wszystkich paczek dodatków
OverwriteSelectedPluginPackages Nadpisanie wybranych paczek dodatków
OverwriteAllProcessesDeploymentMode Ustawienie trybu wdrożeniowego na wszystkich procesach
OverwriteAllProcessesDeployment
ModeMailRecipient
Nadpisanie odbiorców powiadomień w trybie wdrożeniowym na wszystkich procesach
ImportAllDictionaryElements Import wszystkich elementów słownika
OverwriteAllDictionaryItems Nadpisanie wszystkich elementów słownika
ImportOnlySelectedDictionaryElements Import tylko wybranych elementów słownika
ImportAllDocTemplates Import wszystkich szablonów dokumentów
OverwriteAllDocTemplates Nadpisanie wszystkich szablonów dokumentów
ImportOnlySelectedDocTemplates Import tylko wybranych szablonów dokumentów
IgnoreNoExistingGUID Ignorowanie nieistniejących identyfikatorów GUID

 

Plik .json należy uzupełnić zgodnie z przewidywanym zakresem importu. Każdy z parametrów w pliku może zostać zmodyfikowany poprzez podanie w miejsce wartości „null” lub pomiędzy nawiasy kwadratowe identyfikatora GUID określonego elementu BPS (aplikacji, procesu, elementu prezentacji, źródła danych itd.) i odpowiednie ustawienie wartości true/false. Istotnym jest jednak fakt, że wskazanie konkretnych elementów („Selected” / „OnlySelected”) ma znaczenie nadrzędne nad wszystkimi elementami podlegającymi importowi („All”). Przykładowo, parametr „ImportAllPresentationObjects” ustawiony na wartość „true” zostanie zignorowany, jeżeli w tym samym pliku konfiguracyjnym wprowadzony zostanie parametr „ImportOnlySelectedPresentationObjects” z podaniem odpowiedniego identyfikatora GUID elementu prezentacji.

Rys. 10. Fragment uzupełnionego pliku .json, według którego importowi będą
podlegać m.in. tylko wybrany proces i element prezentacji

 

Zgodnie z przedstawionym przykładem GUID aplikacji należy podać, wprowadzając parametr „appGuid”, a GUID elementu prezentacji w ramach parametru „ImportOnlySelectedPresentationObjects”. Jeżeli importowi miałby podlegać tylko wybrany proces, to proces ten należy wskazać, podając jego GUID w ramach parametru „processGuid”. W podobny sposób należy postępować, wprowadzając wartości innych parametrów (patrz Tab. 2.), jeżeli operacja importu ma ograniczać się do wybranych elementów aplikacji/procesu lub polegać na ich nadpisaniu.

 

Import z wykorzystaniem pliku .json

Zawartość zaktualizowanego pliku .json jest przekazywana po wprowadzeniu w konsolowej aplikacji BatchImportApp polecenia zawierającego parametr -i ze ścieżką tego pliku na dysku.

Rys. 11. Niestandardowy import aplikacji i jej elementów z użyciem pliku konfiguracyjnego .json

 

Szczegóły przeprowadzonego importu automatycznego również będzie można sprawdzić w odpowiednim logu pobranym z sekcji Historia importu.

 

Swagger

Wprowadzenie omawianej funkcjonalności wiązało się również z dodaniem nowych endpointów i metod HTTP w Swaggerze. Elementy te utworzono w sekcji PublicApiImport w ramach definicji API beta:

Rys. 12. Nowe endpointy typu POST, PATCH i GET w Swaggerze

 

Dzięki temu rozwiązaniu możliwe będzie integracja z aplikacją API wykorzystywaną do automatycznego importu, wyświetlanie interaktywnej dokumentacji, a także wywoływanie zapytań i testowanie funkcjonalności.

 

Kolejność wywoływania metod

Poniżej podano kolejność wywoływania nowych metod w Swaggerze na potrzeby testowania funkcjonalności automatycznego importu:

  1. Przeprowadź operację uwierzytelnienia. Wybierz definicję API w prawym górnym rogu ekranu. W sekcji Account naciśnij przycisk Try iy out, a następnie wypełnij pola grant_type, clinet-id, client_secret, podając dane ze skonfigurowanej wcześniej w Portalu aplikacji API. Skopiuj wygenerowany token.
  2. Ustaw definicję API beta i wybierz przycisk Authorize. W polu Value wpisz wartość „Bearer”, a następnie skopiowany token poprzedzony spacją.
  3. Rozwiń węzeł PublicApiImport, aby wyświetlić dodane metody HTTP.
  4. Dla pierwszej z metod typu POST (Start import), kliknij opcję Try it out. Podaj ID bazy danych, uzupełniając pole dbID. Jeśli import ma odbywać się w częściach, to uzupełnij wartości parametrów „ChunkSize” oraz „TotalSize” (wartości podawane w bajtach (B)). Status „201” operacji będzie świadczył o jej powodzeniu.
  5. Przejdź do metody POST (Upload file). Kliknij Try it out. Ponownie uzupełnij pole dbID. W sekcji sessionId skopiuj identyfikator sesji z aplikacji konsolowej (patrz Rys. 11). W polu chunkNumber podaj numer kolejny partycji. Jeśli import odbywa się w jeden części, to wpisz „1”. Kliknij przycisk Wybierz plik dostępny obok opcji file i wskaż lokalizację wyeksportowanego pliku .bpe na dysku lokalnym. Status „200” operacji świadczy o jej powodzeniu.
  6. W przypadku metody PATCH (Upload configuration) należy również podać dbID i sessionID. W polu Example value wklej zawartość pliku .json z domyślną lub zmodyfikowaną konfiguracją importu. Jeżeli wszystkie wprowadzone parametry są prawidłowe, to rozpocznie się import.
  7. GET (Get logs) pozwala sprawdzać szczegółowe logi z wykonanej operacji importu. Do tego celu konieczne jest podanie dbID oraz sessionID.
  8. GET (Get status) pozwala śledzić status automatycznego importu, tzn. informuje, czy zakończył się powodzeniem, błędem lub czy operacja nadal trwa.

 

Podsumowanie

Import aplikacji z użyciem publicznego API jest rozwiązaniem, które umożliwia przenoszenie danych powiązanych z aplikacją BPS na inne środowiska. Znajduje ono szczególne zastosowanie w przypadku środowisk o wysokim stopniu izolacji, gdzie wprowadzenie jakichkolwiek zmian wiąże się z koniecznością posiadania specjalnych uprawnień oraz wykonania szeregu testów. Opisywana w niniejszym artykule metoda importu aplikacji przebiega w sposób bardziej zautomatyzowany, odbywa się z wykorzystaniem gotowych narzędzi i danych uwierzytelniających dostępnych bezpośrednio w Portalu i nie wymaga dostępu do wielu zasobów, dlatego może stanowić doskonałą alternatywę dla standardowego importu aplikacji przeprowadzanego z użyciem dedykowanego kreatora w Designer Studio.