




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 → Integracja → API).
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:
- 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.
- Ustaw definicję API beta i wybierz przycisk Authorize. W polu Value wpisz wartość „Bearer”, a następnie skopiowany token poprzedzony spacją.
- Rozwiń węzeł PublicApiImport, aby wyświetlić dodane metody HTTP.
- 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.
- 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.
- 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.
- GET (Get logs) pozwala sprawdzać szczegółowe logi z wykonanej operacji importu. Do tego celu konieczne jest podanie dbID oraz sessionID.
- 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.