Dotyczy wersji: 2024 R1 i powyżej; autor: Łukasz Chechelski
Wstęp
Mechanizm Public Forms stanowi ciekawe rozwiązanie pozwalające na utworzenie zewnętrznych formularzy, których główną zaletą jest anonimowość. Utworzona w ten sposób witryna komunikuje się przez standard REST z WEBCON BPS, tworząc nowe elementy w określonych procesach. Co ważne, mechanizm jest udostępniany nieodpłatnie na portalu GitHub na zasadzie licencji MIT.
Instalacja może być przeprowadzona na jeden z trzech sposobów:
- IIS
- Azure App Service
- Kontener w Docker
Bieżący artykuł skupia się na pierwszej z opcji – bezpośredniej instalacji w IIS. Opisywany scenariusz zakłada przygotowanie zewnętrznej witryny, która pozwoli potencjalnym klientom na zgłoszenie chęci kontaktu w celu uzyskania dokładniejszych informacji. Tak przygotowana funkcjonalność będzie mogła zostać osadzona na witrynie jako IFrame.
Rys. 1. Schemat komunikacji między Public Forms a WEBCON BPS
Ze względów bezpieczeństwa zalecamy, aby Public Forms instalować na osobnej maszynie, innej niż z zainstalowanym serwerem aplikacyjnym BPS.
Instalacja
W pierwszej kolejności należy pobrać Public Forms z oficjalnego konta GitHub, dostępnego pod adresem: WEBCON BPS GitHub. Na głównym ekranie znajduje się kod źródłowy, który można wykorzystać do własnego rozwoju rozwiązania. Skompilowana paczka znajduje się w prawym panelu. Należy pobrać jej najnowszą wersję.
Rys. 2. W witrynie należy pobrać archiwum z zaznaczonego linku – nie kod źródłowy!
Archiwum należy wypakować do uprzednio utworzonego folderu na serwerze. Jako że jest to aplikacja oparta na .NET, wymagane będzie utworzenie odpowiedniej puli aplikacji. W tym momencie wskazane jest, aby dodać uprawnienia do folderu dla konta, w kontekście którego będzie działała aplikacja. Wymagane są uprawnienia na poziomie Modify, Read, Write.
Rys. 3. Uprawnienia nadane dla konta puli aplikacji
Następny etap to konfiguracja w IIS Manager, gdzie w lewym panelu należy wybrać Application Pools, a następnie utworzyć nową pulę aplikacji. Jej nazwa może być dowolna.
Rys. 4. Okno dialogowe tworzonej puli aplikacji
W konfiguracji zaawansowanej utworzonej puli należy zaktualizować dane konta, w kontekście którego pula działa. W miejscu zaznaczonym na Rys. 5 należy wskazać konto, które otrzymało uprawnienia do folderu z Public Forms.
Rys. 5. Zaktualizowane dane konta puli aplikacji
Mając przygotowaną pulę aplikacji, należy utworzyć witrynę. Po kliknięciu prawym przyciskiem myszy na Sites pojawi się opcja dodania nowej witryny. Nazwa tworzonej witryny może być dowolna. Ważne jest, aby poprawnie wskazać utworzoną pulę aplikacji i fizyczną ścieżkę, gdzie wypakowany został Public Forms. Kluczowa jest także odpowiednia konfiguracja adresacji w zakładce Binding.
Rys. 6. Przykładowa konfiguracja tworzonej witryny
Komunikacja z WEBCON BPS
Utworzona witryna komunikuje się z WEBCON BPS poprzez REST API. Wymaga to odpowiedniego przygotowania aplikacji API od strony BPS. Będąc na witrynie Portalu, należy przejść do zakładki Administracja dostępnej po kliknięciu na awatar użytkownika. Po przejściu do zakładki Integracje należy utworzyć nową aplikację. Połączenie będzie wykonywane w kontekście aplikacji. Należy pamiętać, że login tworzonej aplikacji musi być w postaci BPS ID.
Rys. 7. Dane aplikacji API
Po zapisie konfiguracji możliwe będzie wygenerowanie tajnego klucza klienta (tzw. Secret). Jest on niezbędny do poprawnego uwierzytelnienia i autoryzacji komunikacji przez BPS API.
Uwaga: po wygenerowaniu klucza nie ma możliwości jego ponownego podglądu. Zalecane jest jego zapisanie w bezpiecznym miejscu.
Rys. 8. Okno generowania klucza
W tym samym oknie należy wskazać uprawnienia dla utworzonej aplikacji. Uprawnienia działają na podobnej zasadzie, jak te w rejestrowanych aplikacjach w portalu Azure. Łącząc się do BPS w kontekście danej aplikacji, możliwe będzie wykonanie jedynie tych operacji, na które pozwala zakres uprawnień. Do startowania nowych elementów wymagane są co najmniej następujące uprawnienia:
- App.Metadata.Read – odczyt danych konfiguracyjnych aplikacji i procesów. Niezbędne są dodatkowe uprawnienia na każdej z odczytywanych aplikacji.
- App.Elements.ReadWrite.All – odczyt, startowanie nowych oraz edycja elementów obiegu we wszystkich procesach (dane formularza, załączniki, metadane). Niezbędne są dodatkowe uprawnienia odpowiedniego typu na poziomie elementu.
- Admin.BusinessEntities.Read – odczyt danych o spółkach.
Po zapisie należy dodać uprawnienia dla aplikacji na poziomie procesu, tak aby miała możliwość startowania nowych elementów. Będzie ona dostępna w wyszukiwarce, podobnie jak grupy dostępowe czy użytkownicy. Dostęp do metadanych pozwoli na wylistowanie dostępnych atrybutów podczas konfiguracji Public Forms.
Rys. 9. Podgląd uprawnień na poziomie aplikacji
Natomiast uprawnienia na poziomie procesu pozwolą na startowanie nowych elementów przez BPS REST API.
Rys. 10. Podgląd uprawnień na poziomie procesu
Jako że komunikacja odbywa się w kontekście użytkownika, to należy przydzielić mu licencję pozwalającą na wystartowanie elementu. W BPS Designer Studio należy przejść do Konfiguracji systemu, a następnie do zakładki Przydzielanie licencji. W tym miejscu przydzielana jest licencja dla poszczególnych użytkowników.
Public Forms – konfiguracja połączenia
Do komunikacji z WEBCON BPS Public Forms wykorzystuje dane zawarte w zmiennych osadzonych na IIS. W IIS manager należy z głównego węzła wybrać opcję Configuration Editor i wskazać odpowiednią sekcję. Zmienne należy wprowadzić w polu environmentVariables. Poniższa lista zawiera zmienne, które należy dopisać:
- APP_ADMIN_LOGIN – login, który pozwoli zalogować się do panelu administracyjnego Public Forms,
- APP_ADMIN_PASSWORD – hasło dla wspomnianego wyżej konta,
- APP_BASE_DOMAIN – adres domenowy, np. publicforms.example.com,
- APP_BPS_PORTAL_URL – adres URL Portalu,
- APP_BPS_PORTAL_CLIENT_ID – ID aplikacji utworzonej w panelu administracyjnym na Portalu,
- APP_BPS_PORTAL_CLIENT_SECRET – sekret wygenerowany w panelu administracyjnym dla aplikacji,
- APP_BPS_PORTAL_DB_ID – ID bazy zawartości BPS. Domyślnie przyjmuje wartość 1.
Rys. 11. Ekran wprowadzania zmiennych środowiskowych
Po wprowadzeniu danych i ich zapisie wskazane jest wykonanie recycle puli, na której działa Public Forms.
Uruchomienie i konfiguracja formularza
Następnym etapem jest przygotowanie formularza. Po otwarciu witryny Public Forms wyświetli się okno logowania. Uwierzytelnienie następuje po podaniu ustawionych w zmiennych danych logowania. Wyświetlony zostanie panel administracyjny, gdzie możliwe jest utworzenie nowego formularza publicznego. Po kliknięciu przycisku Dodaj pojawi się kreator tworzenia formularza. Bazując na przyznanych uprawnieniach dla aplikacji API, system zwróci listę procesów i atrybutów.
Rys. 12. Konfiguracja formularza
Dodatkowo możliwe jest wizualne wzbogacenie szaty tworzonego formularza poprzez zastosowanie elementów graficznych oraz CSS.
Rys. 13. Konfiguracja wyświetlanych informacji
Na dole ekranu konfiguracji znajduje się lista atrybutów pobranych z wybranego procesu.
Rys. 14. Lista atrybutów
Witryna konfiguracji oferuje też możliwość podglądu formularza przed jego finalnym zapisaniem. Po zapisie system wygeneruje kod IFrame z odnośnikiem do utworzonej strony. Tak utworzony formularz możemy osadzić na dowolnej witrynie. Należy jednak pamiętać, że do poprawnego działania wymagane jest połączenie do serwera aplikacyjnego BPS.
Rys. 15. Wygenerowany formularz
Uzupełnienie pól i przejście ścieżką zainicjuje start elementu w określonym w konfiguracji obiegu. Jako autor widniało będzie uprzednio skonfigurowane konto aplikacji API.
Rys. 16. Uruchomiony element na podstawie Public Forms
Należy też pamiętać, że rozwiązanie Public Forms umieszczone na GITHub ma kilka ograniczeń:
- brak możliwości przesyłania załącznika,
- brak obsługi pól słownikowych opartych o inne źródło niż stała lista wartości,
- brak wsparcia dla List pozycji.
Podsumowanie
Public Forms jest szybkim w konfiguracji narzędziem, które w prosty sposób pozwala na utworzenie dedykowanych formularzy zintegrowanych z WEBCON BPS. Dzięki anonimowości doskonale nadaje się do zastosowania jako wsparcie obiegów reklamacji, ankietowania, czy kontaktu. Narzędzie udostępniane jest nieodpłatnie na licencji MIT, zatem można je rozwijać także we własnym zakresie. Ponadto jest to również możliwe w ramach usług świadczonych przez WEBCON.
