PASOE – OEMANAGER

Właśnie pojawiła się nowa wersja OpenEdge LTS 12.8 a wraz z nią sporo nowości. Poświęcę im cały artykuł, ale to następnym razem. Teraz chciałbym skupić się na jednym elemencie dotyczącym serwera aplikacji PASOE, a mianowicie na narzędziu OEMANAGER.
Pamiętacie może, że dla klasycznego appservera czy webspeeda można było uruchomić z poziomu wiersza poleceń (proenv) komendę ASBMAN czy WTBMAN aby uzyskać status procesu i podstawowe metryki.
Podobnie jest z OEMANAGER – można uzyskać wszystkie potrzebne metryki w jednym wywołaniu, w przeciwieństwie do innych sposobów jak wywołania API. Ponadto, narzędzie OEMANAGER może być wykorzystywane podczas runtime’u.
Aby można było z niego skorzystać instancja musi zawierać wdrożone aplikacje: OpenEdge Manager (oemanager.war) and Tomcat Manager (manager.war). Możemy wdrożyć je odpowienimi poleceniami do istniejącej instancji lub stworzyć nową z już wdrożonymi tymi aplikacjami używając opcji -f. Poniżej zamieszczam komendę utworzenia takiej instancji mypasoe. Do niedawna zalecani nie instalować tych aplikacji w środowisku produkcyjnym ale obecnie nie ma takich przeciwskazań o ile odpowienio je zabezpieczymy. Jednym takim elementem zabezpieczeń jest oczywista zmiana domyślnych haseł. Po resztę informacji odsyłam do dokumentacji. Ja w tym przykładzie pozostanę przy domyślnych hasłach, a dlaczego, to zaraz pokażę.

pasman create -v -f -p 8813 -P 8814 -s 8815 %WRKDIR%\mypasoe
Teraz uruchamiam instancję poleceniem:
pasman oeserver -start -I mypasoe
Jest to nowsza forma komendy tcman (pasman) pasoestart, wprowadzona od OE 12.5. Po prawidłowym uruchomieniu procesu Tomcata nie oznacza, że wszystkie komponenty OpenEdge zostały uruchomione. Polecenie tcman -oeserver start sprawdza logi pod kątem takich błędów. Polecenie posiada kilka jeszcze innych opcji, a więc ci, którzy mają wersję 12.5+ powinni korzystać właśnie z niej.

Po uruchomieniu oemanager dostajemy poniższą długą listę opcji.

     [echo]  TCMAN Shortcuts:
     [echo]
     [echo]  oemanager query    - Use TCMAN to query the PAS instance
     [echo]
     [echo]  oemanager startup  - Use TCMAN to start the PAS instance
     [echo]                       [OPTIONAL] timeout=300 - Time (seconds) to wait for a proper startup
     [echo]
     [echo]  oemanager shutdown - Use TCMAN to stop the PAS instance
     [echo]                       [OPTIONAL] timeout=300 - Time (seconds) to wait for a proper shutdown
     [echo]
     [echo]
     [echo]  Support Tools:
     [echo]
     [echo]  oemanager inventory - Bundle useful PAS instance files (as .zip) for support tickets
     [echo]
     [echo]
     [echo]  Status/Info:
     [echo]
     [echo]  oemanager status - [RO] Obtain MSAgent/connection status information for an ABL App
     [echo]                     [OPTIONAL] basemem=819200 - Minimum memory threshold (bytes) to consider as 'unused' agent sessions
     [echo]
     [echo]  oemanager stacks - [RO] Obtain stack information for all MSAgents for an ABL App
     [echo]
     [echo]  oemanager flush  - [RO] Flush the available deferred log buffer to agent log file
     [echo]
     [echo]  oemanager locks  - [RO] Display database users and their table locks related to an MSAgent-Session
     [echo]                     This utilizes a single DBConnection; edit the 'locks' task in build.xml to add more as necessary
     [echo]                     Note: Only provides session data if using self-service DB connections for OE versions under 12.5
     [echo]                     [REQUIRED] pf=[PF_NAME] - PF file to use for database connection(s)
     [echo]
     [echo]  oemanager users  - [RO] Alias for 'locks' task
     [echo]
     [echo]
     [echo]  Agent Management:
     [echo]
     [echo]  oemanager add     - Add (read: start) one new MSAgent for an ABL App
     [echo]
     [echo]  oemanager close   - Perform a 'soft restart' of an ABL App (runs: status, flush + trimhttp + stop, status)
     [echo]                                       For this task the 'trimhttp' will be called with the termination option 1 (forced)
     [echo]                      [REQUIRED] webapp=[WEBAPP_NAME] - WebApp for Tomcat Manager to terminate active client sessions
     [echo]                                  The given WebApp is expected to be associated with the provided ablapp name
     [echo]                      [OPTIONAL] sleep=1 - Sleep time in minutes after stop, prior to final 'status' output
     [echo]
     [echo]  oemanager clean   - Alias for 'close' task [Deprecated]
     [echo]
     [echo]  oemanager refresh - Refresh ABL Sessions for each MSAgent for an ABL App (OE 12 Only)
     [echo]                      Note: This will essentially terminate all sessions (gracefully),
     [echo]                            and prepare the Agent to pick up any R-code changes
     [echo]
     [echo]  oemanager reset   - Reset an aspect of each MSAgent for an ABL App
     [echo]                      [REQUIRED] resettype=stats [stats|logs]
     [echo]
     [echo]  oemanager stop    - Gracefully stop one or all MSAgents (+stacks output) for an ABL App
     [echo]                      [OPTIONAL] waitfinish=120000 - How long to wait (milliseconds) if the MSAgent is busy serving a request
     [echo]                      [OPTIONAL]  waitafter=60000  - Additional time to wait (milliseconds) before killing [hard stop] the MSAgent
     [echo]                      [OPTIONAL]        pid=[AGENT_PID] - Numeric process ID for a specific MSAgent to be stopped
     [echo]
     [echo]
     [echo]  Session Management:
     [echo]
     [echo]  Note: All trim actions listed below will write application stack information to a file.
     [echo]
     [echo]  oemanager trimsingle - Trim a single ABL Session (via the Agent Manager) for a specific MSAgent
     [echo]                         [REQUIRED]          pid=[AGENT_PID]  - Numeric process ID of the MSAgent for context
     [echo]                         [REQUIRED]       sessid=[SESSION_ID] - Numeric ID for the ABL Session to be stopped
     [echo]                         [OPTIONAL] terminateopt=0 - Termination Option: 0=graceful, 1=forced, 2=finish+stop
     [echo]
     [echo]  oemanager trimall    - Trim all available ABL Sessions (via the Agent Manager) for each MSAgent for an ABL App
     [echo]                         Note: For any busy sessions considered stuck use 'trimhttp' with a specific Session ID
     [echo]                         [OPTIONAL] terminateopt=0 - Termination Option: 0=graceful, 1=forced, 2=finish/stop
     [echo]
     [echo]  oemanager trimidle   - Trim only the IDLE ABL Sessions (via the Agent Manager) for each MSAgent for an ABL App
     [echo]                         Allows for manually scaling down an MSAgent which may have many unused ABL Sessions
     [echo]                         [OPTIONAL] terminateopt=0 - Termination Option: 0=graceful, 1=forced, 2=finish+stop
     [echo]
     [echo]  oemanager trimhttp   - Trim one or all Client HTTP Sessions (via the Session Manager) for an ABLApp + WebApp
     [echo]                         Terminating a client HTTP session will also terminate its associated ABL Session
     [echo]                         [REQUIRED]       webapp=[WEBAPP_NAME] - WebApp for Tomcat Manager to terminate active sessions
     [echo]                                           The given WebApp is expected to be associated with the provided ablapp name
     [echo]                         [OPTIONAL]       sessid=[SESSION_ID]  - Alphanumeric Client Session ID to be stopped
     [echo]                                           When no session ID provided, all available Client HTTP Sessions will be expired
     [echo]                         [OPTIONAL] terminateopt=0 - Termination Option: 0=graceful, 1=forced, 2=finish+stop
     [echo]
     [echo]
     [echo] Current parameter values, override via command line or 'oemanager.properties':
     [echo]     scheme=http
     [echo]       host=localhost
     [echo]       port=8813
     [echo]     userid=tomcat
     [echo]     passwd=tomcat
     [echo]     ablapp=mypasoe

Niektóre są oczywiste jak: start, stop, status itp. ale niektóre wyglądają bardzo ciekawie, np. opcja flush – pomaga znaleźć przyczynę powtarzających się awarii agenta, poprzez opóżnione zrzucenie informacji ze specjalnego bufora do pliku.
Na samym dole widać użytkownika i hasło do procesu Tomcata. Należy dla bezpieczeństwa wejść do pliku oemanager.properties, znajdującego się w podkatalogu bin dla instancji, odkomentować dwie linie i ustawić puste dane logowania, jak na poniższym obrazku.

OK, poniżej zamieściłem wynik działania komendy oemanager status.

 [PCTRun]  PASOE Instance: http://localhost:8813
   [PCTRun]
   [PCTRun] ABL Application Information [mypasoe - v12.8.0 ( 2023-12-21 )]
   [PCTRun]     WebApp: ROOT
   [PCTRun]       APSV: ENABLED
   [PCTRun]       SOAP: ENABLED
   [PCTRun]       REST: ENABLED
   [PCTRun]        WEB: ENABLED
   [PCTRun]
   [PCTRun] Manager Properties
   [PCTRun]             Maximum Agents:           2
   [PCTRun]             Minimum Agents:           1
   [PCTRun]             Initial Agents:           1
   [PCTRun]     Max. Connections/Agent:         200
   [PCTRun]     Max. ABLSessions/Agent:         200
   [PCTRun]         Idle Conn. Timeout:     300.000 ms (00:00:05:00.000)
   [PCTRun]       Idle Session Timeout:   1.800.000 ms (00:00:30:00.000)
   [PCTRun]         Idle Agent Timeout:   1.800.000 ms (00:00:30:00.000)
   [PCTRun]      Idle Resource Timeout:           0 ms (00:00:00:00.000)
   [PCTRun]         Conn. Wait Timeout:       3.000 ms (00:00:00:03.000)
   [PCTRun]       Request Wait Timeout:      15.000 ms (00:00:00:15.000)
   [PCTRun]     Initial Sessions/Agent:           2
   [PCTRun]     Min. Avail. Sess/Agent:           1
   [PCTRun]
   [PCTRun] > Agent PID 13208: AVAILABLE
   [PCTRun]     Est. Agent Lifetime: 00:00:00:00.000
   [PCTRun]     DynMax ABL Sessions:          200
   [PCTRun]      Total ABL Sessions:            2
   [PCTRun]      Avail ABL Sessions:            2
   [PCTRun]        Open Connections:            1
   [PCTRun]         Overhead Memory: 13.897 KB
   [PCTRun]
   [PCTRun]     SESSION ID      STATE           STARTED                         LIFETIME          SESS. MEMORY     ACTIVE MEM.   REQUESTS       BOUND/ACTIVE CLIENT SESSION
   [PCTRun]                4    IDLE            18/02/2024 15:18:40,229-01:00   00:00:01:28.600         742 KB         742 KB           0        -
   [PCTRun]                7    IDLE            18/02/2024 15:18:40,229-01:00   00:00:01:28.600         742 KB         742 KB           0        -
   [PCTRun]       Active Agent-Sessions: 0 of 2 (0% Busy)
   [PCTRun]     Utilized Agent-Sessions: 0 of 2 (>801 KB)
   [PCTRun]        Approx. Agent Memory: 15.380 KB
   [PCTRun]
   [PCTRun] Session Manager Metrics (Count-Based)
   [PCTRun]            # Requests to Session:           0
   [PCTRun]           # Agent Responses Read:           0 (0 Errors)
   [PCTRun]         # Agent Requests Written:           0 (0 Errors)
   [PCTRun]     Concurrent Connected Clients:           0 (Max: 0)
   [PCTRun]       # Reserve ABLSession Waits:           0
   [PCTRun]     # Reserve ABLSession Timeout:           0
   [PCTRun]
   [PCTRun] Client HTTP Sessions: 0

Administrator otrzymuje natychmiastową całościową informację o warstwach transportowych, właściwościach agentów itd.
Zachęcam do przetestowania i korzystania z opcji komendy OEMANAGER.

Debugging w aplikacjach PASOE

W kilkunastu postach opisywałem tworzenie serwisów i aplikacji z udziałem serwera aplikacji PASOE i coraz więcej naszych klientów korzysta z tej technologii. Coraz częściej powtarza się pytanie: jak można wykorzystać debugger aby wychwytywać błędy i testować aplikacje.
PASOE to połączenie technologii Tomcat (Java) i OpenEdge (ABL), więc kompletny proces debuggowania jest dość złożony.
Tutaj chciałbym pokazać jak zacząć ten proces z punktu widzenia OpenEdge’a.

Jak zwykle przed przystąpieniem do wykorzystania debuggera, trzeba włączyć tę funkcjonalność w środowisku OpenEdge. Należy uruchomić komendę prodebugenable -enable-all jako administrator.

Drugim krokiem jest wdrożenie web aplikacji oedb.war w testowanej instancji. Pamiętajmy, że ze względów bezpieczeństwa, nigdy nie wdrażać jej w środowisku produkcyjnym!
pasman deploy -I oepas1 %DLC%\servers\pasoe\extras\oedbg.war


Cały proces debuggowania będzie odbywał się w Progress Developer’s Studio for OpenEdge.
Wykorzystam do testowania plik klasy wygenerowany przy tworzeniu prostego serwisu REST i dodania zasobu (Business Entity) Customer, co opisywałem na początku 2016 roku.
Dostajemy klasę customer.cls z metodami CRUD: CreateCustomer, ReadCustomer, UpdateCustomer i DeleteCustomer. Ja wykorzystam metodę ReadCustomer i wstawię breakpoint zaraz za instrukcją SUPER:ReadData(filter). klikając po lewej stronie dwukrotnie myszką.

Teraz klikając prawym przyciskiem myszy na instancję PASOE wybieramy Restart in Debug.


Następnie uruchamiamy serwis w przeglądarce poprzez link dla Custnum=1,
http://localhost:8810/CustProj/rest/CustProjService/customer?filter=Custnum=1
a w następnej kolejności dla Custnum < 5.
http://localhost:8810/CustProj/rest/CustProjService/customer?filter=Custnum<5

W PDSOE w widoku dla zmiennych zobaczymy wartość filtra odpowiednio “Custnum=1″oraz “Custnum<5”.
Widać z tego, że zasada testowania aplikacji przy pomocy debuggera jest dość prosta.



Dodam jeszcze jedną informację, ponieważ byłem o to kilka razy pytany: W sytuacji gdy mamy wiele projektów i instancji PASOE, jak sprawdzić która instancja obsługuje dany serwis.
Można sprawdzić np. poleceniem tcman jakie serwisy są wdrożone w danej instancji, a w PDSOE podejrzeć właściwości danego projektu jak na widoku poniżej.

Cały proces debuggowania można prześledzić na kanale Youtube.
Webinar ten jest rozszerzony o testowanie aplikacji nie tylko lokalnych ale także zdalnych.

OpenEdge Command Center 1.3

Witajcie wciąż w wakacyjnym nastroju! Ponieważ pojawiła się ostatnio nowa wersja OpenEdge Command Center – 1.3, właśnie jej poświęcam sierpniowy wpis.
Na początku wspomnę jeszcze o jednym elemencie, o którym nie napisałem uprzednio, a który jest od pierwszej wersji OECC – o etykietach. Na poniższym obrazie widać takie etykiety, które reprezentują nazwę maszyny, tryb instancji oraz jej nazwę. Dodatkowo usunąłem niektóre kolumny, zostawiając te najważniejsze, z punktu widzenia czytelności. Etykiety są ważnym elementem szczególnie w sytuacji gdy instancji jest bardzo wiele i są kłopoty z identyfikacją.

Ale przejdźmy teraz do instalacji nowej wersji OECC 1.3. Tym razem w dokumentacji możemy znaleźć opis całego procesu, choć niektóre istotne informacje są pominięte, dlatego zamiast korzystać z instrukcji pdf, polecam raczej dokumentację online.
Nowa wersja OECC wymaga także nowszej wersji MongoDB: 4.4, 5.0, lub 6.0. Ja zainstalowałem wersji 6.0 na Windows Server 2019. Tym razem nie instaluję MongoDB jako serwis Windows.

Po zainstalowaniu MongoDB gdy baza i OECC są zainstalowane na tej samej maszynie i w takiej sytuacji trzeba związać adres ip 0.0.0.0.

W pliku konfiguracyjnym …\conf\db-config.json
ustawiam wartość:

"dbHostNameAndPort": "0.0.0.0:27017"

Ponadto od wersji MongoDB 6.x w pliku …\bin\mongod.cfg ustawiamy

Dodaję katalog np. c:\mongodata i startuję MongoDB jako administrator poleceniem:
mongod.exe –dbpath c:\mongodata -bind_ip 0.0.0.0
(Tego okna nie zamykam, dopóki proces MongoDB ma działać).

Dodaję użytkownika do bazy admin (tak jak opisałem to wcześniej).

Teraz restartujemy MongoDB z włączoną autoryzacją:
mongod.exe –dbpath c:\mongodata -bind_ip 0.0.0.0 –-auth

I możemy przystąpić do instalacji OECC 1.3, jak było to opisane wcześniej.
Po zainstalowaniu na jednej lub kilku systemach Agenta OECC, możemy w końcu zobaczyć jakie informacje są przekazywane do konsoli na serwerze.
Widzimy, że została dodana nowa ikonka po lewej stronie, reprezentująca bazy danych.

Klikając ikonkę mamy dostęp do następujących danych:

  • Nazwa bazy danych.
  • Etykiety przypisane do bazy danych.
  • Pełna ścieżka do bazy.
  • Nazwa agenta OECC.
  • Status uruchomienia bazy.
  • Nazwa portu/usługi.
  • Wersja bazy danych.
  • Nazwa hosta na którym pracuje baza danych.
  • Instalacja OpenEdge, w której znajduje się baza.

Podobnie jak dla PASOE wygodnie jest ustawić etykiety identyfikujące instancje bazy.

Jeśli agent nie wychwycił jakiejś instancji, musimy ją dodać ręcznie. W polu OpenEdge Installation wybieramy wersję OE. Dodajemy pełną ścieżkę, numer portu/nazwę usługi oraz dane logowania. Możemy dodać też opcjonalnie dodatkowe parametry startowe.

Jak widać nie ma tutaj szczegółowych danych wydajności bazy znanych z OE Management. Takie dane można uzyskać wykorzystując technologię OpenTelemetry oraz aplikację typu APM (Application Performance Monitor).

OpenEdge Command Center – cz. 2

W niniejszym wpisie powracamy do tematu OECC. Muszę powiedzieć na wstępie, że ten produkt cieszy się coraz większym zainteresowaniem klientów ze względu na nowoczesny interfejs, duże bezpieczeństwo, wydajność czy łatwość w monitorowaniu zdalnymi zasobami. Te zalety są kluczowe w porównaniu z OEM/OEE, który jest bardzo wygodny do stosowania raczej dla lokalnych zasobów. Należy przypomnieć że technologia OECC zaczyna się od OE 12.2 – nie da się monitorować wcześniejszych wersji.

Tym razem zainstalujemy agenta na maszynie z zainstalowanym środowiskiem OpenEdge (PASOE, bazy danych), który będzie zbierał dane i przesyłał je do OECC Servera.
Pierwszym krokiem jest wygenerowanie klucza na serwerze, który posłuży do uwierzytelnienia połączenia z agentem. Wybieramy Generate Agent Keys.


Wygenerowany nowy klucz zapisujemy na dysku. Jest to plik o nazwie serverInfo.json. Będzie potrzebny do zainstalowania agenta (najczęściej na innej maszynie).

Sama instalacja jest bardzo prosta. Jedynym ciekawym krokiem jest moment wczytania danych z podanego pliku, co zaoszczędzi nam ręcznego wpisywania danych.

Jeśli instalujemy nowszą wersję agenta w miejsce starej, pojawi się poniższy komunikat (nie będzie wtedy konieczności podawania danych z pliku json).

OK, zainstalowaliśmy agenta i teraz chcemy zobaczyć czy wysyła on dane do centrum monitorowania na serwerze. Musimy jeszcze upewnić się czy w zaporze otwarty jest port (domyślnie 8000), bo w przeciwnym wypadku dane będą blokowane. W moim przykładzie serwer OECC został zainstalowany na VM z systemem Windows Server 2016, a agent i OpenEdge 12 na Windows 10.

Z poziomu konsoli serwera OECC możemy dla danej instancji PASOE wybrać kilka akcji. Najciekawiej wygląda Clone, która ma utworzyć kopię instancji w nowej lokalizacji. Zróbmy to dla mypasoe. Nowa nazwa (mało wyszukana) mypasoeCLONE.

Na sklonowanie zwykle trzeba chwilę zaczekać, szczególnie jeśli instancji jest online.

I po chwili mamy nowego clona. Instancja jest zatrzymana i zwykle wymaga pewnego dostosowania w konfiguracji aby była w pełni działająca.

Zobaczmy jeszcze dla mypasoe jakie inne ciekawe informacje możemy tu znaleźć. Jest np. info o wdrożonych aplikacjach webowych, usługach, ich parametry i aktualny status.

Tyle o wersji OECC 1.2. W następnym artykule chciałbym pokazać jakie inne elementy monitorowania zostały dodane w OECC 1.3 !

OpenEdge 12.7

5 maja pojawiła się wersja OpenEdge 12.7. Ma być ona ostatnią z wersji Innovation dla dwunastki ponieważ ostatnia, zapowiadana na koniec roku, ma być wersją LTS. Przyjrzyjmy się wybranym nowościom.

PROSTRCT REMOVEONLINE – nowa komanda poprawiająca dostępność bazy danych. Umożliwia usuwanie extentów lub całych obszarów bez konieczności zamykania bazy.

PROUTIL TABLEREORG to narzędzie służące do poprawy stopnia fragmentacji w tabelach (zastępuje operacje dump i load online) dla obszarów typu II. Wprowadzono je w OE 12.3, a teraz dodano nowe parametry np. restrict czy nosmartscan. Pierwsza opcja jest przeznaczona dla dużych tabel i pozwala na reorganizację wybranego fragmentu tabeli wg. wartości pola. Druga opcja wyłącza domyślne inteligentne skanowanie. Przykład poniżej.

Wprowadzono nowy typ pakietu (lub biblioteki) kodu aplikacji ABL, który można podpisać i weryfikować, aby mieć pewność, że skompilowany kod aplikacji ABL nie został uszkodzony ani zmodyfikowany. Ten nowy typ biblioteki jest znany jako plik archiwum i ma rozszerzenie .apl. Do utworzenia archiwum, dodawania r-kodów służy komenda PROPACK, a do podpisywania PROSIGN.

OpenEdge obsługuje teraz OAuth2 i SAML do uwierzytelniania i autoryzacji. Te standardowe protokoły zapewniają bezpieczny i wygodny mechanizm uwierzytelniania użytkowników bez udostępniania poufnych informacji. OpenEdge Authentication Gateway może automatycznie przekonwertować zweryfikowane tokeny na token OpenEdge Client Principal, który możemy obsługiwać w aplikacjach ABL.

Administrowanie PASOE: do tej pory można było skonfigurować instancje tak aby w razie potrzeby agent wielosesyjny uruchamiał dodatkowe sesje, ale nie było możliwości aby te sesje były automatycznie przycinane. W obecnej wersji OpenEdge dodano nowe właściwości do pliku openedge.properties, które umożliwiają administratorowi systemu skonfigurowanie instancji PASOE tak, aby sesje ABL były przycinane gdy nie są już potrzebne czy też gdy osiągnęły limit czasu lub pamięci.

W Developer Studio dodano ABL Type Hierarchy View, który pokazuje relacje rodzic-dziecko między klasami ABL i interfejsami, aby pomóc programiście ABL zobaczyć hierarchię i strukturę dziedziczenia klasy i przechodzenie do dowolnego elementu widocznego w widoku.

Dla wykorzystujących AI Archiver do zapisu After Image pojawiła się ciekawa możliwość wystartowania tego procesu online bez konieczności wykonania backupu. Jest to szczególnie istotne dla dużych baz gdy wykonanie kopii powodowało wstrzymanie wykonywanie transakcji.

W operacja przywracanie bazy PROREST dodano parametry do wykonania jej jako proces wielowątkowy.

Jest jeszcze kilka nowinek po które odsyłam do dokumentacji.

Swagger UI i PASOE

Swagger UI jest narzędziem które umożliwia wizualizację zasobów API bez konieczności implementacji dodatkowych zewnętrznych aplikacji.

Swagger składa się z plików HTML, JavaScript i CSS, które dynamicznie generują dokumentację na podstawie interfejsu API.
Jest dostępny w PASOE począwszy od wersji OE 12.0 (domyślnie wyłączony). Od wersji OE 12.2 jest domyślnie włączony dla instancji deweloperskich – należy pamiętać aby nigdy nie włączać go w środowiskach produkcyjnych.

Dostęp do Swaggera jest z poziomu oemanagera (http://host:port/oemanager/), ale jeśli dostęp jest zabroniony, to wchodzimy z poziomu managera, czyli http://host:port/manager/, np. http://localhost:8813/manager.


Tutaj klikając oemanager dostajemy ekran dokumentacji Swaggera.


Ekran składa się z sekcji np. dla każdej warstwy transportowej,  Agent Manager, Session Manager i OEABL ManagerService.
Przechodzimy do tej drugiej i klikamy na GET /applications, następnie Try it out i Execute.


Dostajemy listę wszystkich aplikacji ABL dla instancji PASOE wraz z parametrami w postaci JSON. Listę tę można pobrać jako plik tekstowy.

Jeśli w OEABL ManagerService kliknę GET /applications/{AppName}/webapps i wpiszę nazwę aplikacji ABL, dostanę w podobnej postaci listę wszystkich aplikacji webowych dla tejże aplikacji.

Aby pobrać listę web servisów dla danej aplikacji webowej wybieram GET/applications/{AppName}/webapps/{WebAppName} i podaję nazwę aplikacji ABL i web serwisu.

Jak widać na obrazkach czasowniki GET nie są jedynymi do użycia. Można np. zaktualizować listę poprzez czasownik POST czy zerować metryki (DELETE).
Opcji jest bardzo wiele.

PASOE HealthScanner

OpenEdge HealthScanner został stworzony po to, aby ostrzegać administratorów o potencjalnych problemach z instancją PASOE, dzięki czemu serwer może zostać wyłączony z eksploatacji zanim wystąpi awaria.Usługa nie jest przeznaczona do badania ani rozwiązywania problemu lecz do oznaczenia serwera, który znajduje się poniżej pewnego, zdefiniowanego progu.

OpenEdge HealthScanner jest przeznaczony do użytku z instancjami PASOE w środowisku produkcyjnym chociaż można go testować również w środowisku deweloperskim. HealthScanner jest serwisem Tomcata z własnym portem HTTP, pulą wątków i konfiguracją.

Tradycyjnie będę tutaj korzystać z polecenia pasman (zamiast tcman) i tak polecenie:
pasman feature -I mypasoe wyświetli funkcje instancji PASOE (tutaj: mypasoe) i ich stan. Widać, że funkcja HealthCheck jest wyłączona.

Włączenie funkcji można wykonać przez komendę tcman feature (pasman feature), a następnie sprawdzić tę samą komendą czy polecenie przyniosło zamierzony efekt. Obie komendy widać poniżej.

Innym sposobem jest skorzystanie z interfejsu OEM/OEE.

Samo włączenie funkcji jednak nie wystarczy. Potrzebne jest także włączenie tzw. data collectora, czyli procesu zbierającego dane. Komendy włączające proces i sprawdzające jego status są widoczne poniżej.

Proces ten pobiera dane z różnych wirtualnych “sond” takich jak: PASOE HealthScanner, JVM Health, Tomcat Health, Transport Health i wielu innych. Każda próbka ma określona wagę, wykorzystywaną do obliczenia ogólnego współczynnika “zdrowia” PASOE.

Wszystkie sondy i ich wagi możemy podejrzeć w pliku: [instancja]/conf/health.config.

Jeśli przyjrzymy się np. sekcji Transport Health, zauważymy, że są tu trzy warstwy transportowe APSV, WEB i REST. Udział każdej wynosi 0.33333. Jeśli w naszym systemie aplikacyjnym nie ma np. warstwy WEB, to możemy ustawić udział w niej na 0, a w pozostałych dwóch na 0.5.

Warto przeczytać także informacje dot. wyliczeń współczynników zawarte w pliku [instancja]/conf/health.config.README.

Usługa działa domyślnie na porcie 8899 i generuje kilka zestawień w formacie JSON np:
http://localhost:8899/health?view=summary

zestawienie szczegółowe:
http://localhost:8899/health?view=details

czy bardzo ciekawe zestawienie przedstawiające konfigurację sond i wyliczeń:
http://localhost:8899/health?view=config

Korzystanie z PASOE HealthScanner wymaga pewnej wprawy i dlatego nie jest to usługa dostępna od razu po instalacji, a dopiero po włączeniu jej przez administratora, ale warto ją przetestować i poznać bliżej.

OpenEdge Command Center

Czytelnicy niniejszego bloga znają podstawowy i sztandarowy produkt służący do monitorowania systemów – OpenEdge Management (OEM) oraz jego uboższą wersję OpenEdge Explorer (OEE).
Produkt ten został wprowadzony po raz pierwszy wiele lat temu pod nazwą Fathom Management w wersji V9. Wciąż jest rozwijany i świetnie spisuje się w małych i średnich sieciach.

Tym razem chciałbym przybliżyć nowy produkt, OpenEdge Command Center (OECC) służący do zarządzanie wieloma zasobami i instalacjami OpenEdge na różnych komputerach i różnych wersjach OpenEdge.

Pierwsza wersja OpenEdge Command Center została stworzona z myślą o efektywnym zarządzaniu PASOE oraz, w przyszłości, bazami danych. Aktualna wersja 1.0 wspiera OE 12.2.5 i wyższe. Nie ma wsparcia wstecz.
OECC jest darmowe dla posiadaczy licencji OE, podobnie jak OEE i ma na celu uproszczenie ogólnego zarządzania platformą OpenEdge.
Serwer OpenEdge Command Center jest obsługiwany na następujących platformach:

  • Ubuntu 18.04 LTS
  • Oracle Linux 8
  • Red Hat Enterprise Linux 8
  • SUSE Linux Enterprise Server 15
  • CentOS Linux 8
  • Windows 64

Można także uruchomić OpenEdge Command Center Server na 64-bitowym serwerze Linux z obsługą chmury, który jest skonfigurowany z MongoDB ATLAS.
Jednym z celów OECC jest zastąpienie produktu OEE, ze względu na niektóre problemy, które były zgłaszane przez użytkowników jak np. przestarzały interfejs, “ciężki” proces zdalnego AdminServera wymagający otwarcia 4 portów czy to, że API muszą być wyeksponowane w standardzie OpenAPI.

Serwer OECC można wdrożyć jako pojedynczy węzeł lub, dla zapewnienia wysokiej dostępności, jako klaster wielowęzłowy. Aby zapewnić wysoką dostępność, serwer współpracuje ze wszystkimi load balancerami obsługującymi transporty HTTP/HTTPS oraz protokoły websocket, takie jak Nginx, Serwer HTTP Apache, AWS, ELB/ALB itp.
OECC do przechowywania danych korzysta z bazy danych MongoDB oraz magazynu plików (patrz rysunek).


MongoDB to nierelacyjna baza, która przechowuje dane w postaci dokumentów w formacie podobnym do JSON. Są w niej zawarte wszystkie szczegóły dotyczące wykrytych komponentów OE takich jak PASOE (w przyszłości także baz danych OE) oraz ustawienia konfiguracyjne OECC. Instalacja bazy MongoDB jest wymagana przed instalacją serwera OECC, który wspiera następujące wersje (www.mongodb.com):

  • MongoDB Community Server
  • MongoDB Atlas running on AWS, Azure, and Google Cloud Platform (GCP)
  • MongoDB Enterprise Edition

Oprócz bazy część danych jest przechowywana w postaci repozytorium plików. Mieszczą się tu informacje o połączeniu z bazą danych, konfiguracji bezpieczeństwa i logowania itp.
O instalację MongoDB (podobnie jak i Java JDK) klient musi zadbać we własnym zakresie.

Ażeby dane były pobierane z różnych środowisk, na każdej maszynie trzeba zainstalować agenta OECC. Jest to lekki proces instalujący się razem z OE. Niezależnie od tego, czy masz jedną czy więcej instalacji OpenEdge na maszynie wystarczy zainstalować jednego agenta (OE 12.2.5 i wyżej).

Proces agenta działa autonomicznie; trzeba tylko upewnić się że jest poprawnie uruchomiony. Dla bezpiecznego połączenia z serwerem OECC trzeba z konsoli wygenerować unikalny klucz dla każdego agenta.

Cały proces konfiguracji i monitorowania przeprowadzamy z konsoli dostępnej z przeglądarek internetowych (HTTP/HTTPS), patrz przykład poniżej.

OpenEdge Command Center to bardzo ciekawy produkt, który obecnie monitoruje tylko procesy PASOE, ale w najbliższym czasie ma być rozszerzony także o procesy baz danych. Warto jest go zainstalować i przetestować.

Migracja do PASOE

O PASOE sporo pisałem. Wiadomo, w OE12 nie ma już klasycznego AppServera i trzeba podjąć decyzję o migracji aplikacji, a przed decyzją dobrze jest poznać za i przeciw nowego produktu.
Teraz jednak powracam do tematu samej migracji w szerszym kontekście (pisałem o podstawach migracji w 2017).

Korzyść z nowego AppServera widać już podczas instalacji: możemy wybrać czy instalowana instancja będzie deweloperska czy produkcyjna. Dla tej ostatniej dodajemy w komendzie parametr -Z prod i mamy instalowanie instancji z implementacją silniejszych zabezpieczeń niż dla wersji deweloperskiej. O samych zabezpieczeniach nie będę pisał ponieważ temu tematowi poświęciłem tutaj kilka wpisów.

Następnym krokiem jest migracja ustawień, czyli pliku z właściwościami. Istniejący plik ubroker.properties musi zostać przekonwertowany na nowy format używany przez PASOE openedge.properties.
Kolejność działania jest następująca: najpierw uruchamiamy polecenie paspropconv, które konwertuje właściwości z pliku ubroker.properties do tymczasowego pliku ubrokername.oemerge. Plik ten można dopasować do naszych potrzeb i włączyć ustawienia naszej nowej instancji do pliku openedge.properties.

Komendę paspropconv uruchamiamy w podkatalogu conf dla instancji PASOE z przykładowymi parametrami, które są wymagane. Podwójne myślniki przed nazwą parametru wynikają stąd, że skrypt jest napisany w języku Perl.

--ubrokerPropsFile C:\classicapp\ubroker.properties 
--ubrokerName UBroker.AS.asbroker1 
--pasoeAppName myprod

Pierwszy parametr określa ścieżkę do pliku z właściwościami dla klasycznego AppServera, drugi jest nazwą instancji tego AppServera, wreszcie trzeci określa nazwę nowej instancji PASOE.
Po uruchomieniu komendy w katalogu conf zostały utworzone poniższe pliki:

Dla nas istotny jest plik .oemerge. Niemal całą jego zawartość stanowi przewodnik po migracji, zawierający sekcje np:
Tryby pracy (operating modes) – zawiera porady dotyczące migracji istniejących trybów pracy (state-reset, state-aware, stateless, statefree) na tryby pracy w PASOE. Omówione są proste instrukcje, realizujące ten etap migracji, które wiążą i zwalniają bieżącą sesję ABL (były omawiane na blogu kilka lat temu).
Procedury zdarzeniowe (event procedures) – omawiane są stare i nowe procedury (agentStartupProc, sessionStartupProcParam) związane z inicjalizacją agenta wielo-sesyjnego oraz każdej sesji ABL.

# paspropconv  v1.15 (MSWin32)
# 
# Input arguments:
# 
#   ubrokerPropsFile    = C:\classicapp\ubroker.properties
#   ubrokerMergeFile    = 
#   ubrokerName         = UBroker.AS.asbroker1
#   pasoeAppName        = myprod
#   pasoeWebAppName     = ROOT
#   pasoeMergeFile      = myprod.asbroker1.oemerge
#   pasoeSetEnvFile     = asbroker1_setenv
#   convNotesDBFile     = C:\OPENED~1\bin\paspropconv_notesdb.en
#   logFile             = paspropconv.log
#   loggingLevel        = 2
# 
# Operating Modes
# ---------------
# 
# The classic AppServer supports 4 operating modes:
#   state-reset
#   state-aware
#   stateless
#   statefree
# 
# In the classic AppServer, the operating mode is specified when the AppServer
# is deployed.  Consequently, all ABL sessions supported by the AppServer
# employ the same operating mode.
# 
# In PASOE, the operating mode of a session is not specified during deployment.
# As such, a single PAS server can support concurrent ABL sessions, each
# emulating the behavior of different classic operating modes.
# 
# To support the different types of operating mode behavior
# provided in the various classic modes, some ABL code modifications
# may be required.  It is recommended that these changes are made in 
# the PASOE sessionConnectProc () and
# sessionDisconnProc () event procedures.
.......
[AppServer.Agent.myprod]
    PROPATH=${CATALINA_BASE}/openedge,${CATALINA_BASE}/webapps/ROOT/WEB-INF/openedge,.....
    agentMaxPort=2202
    agentMinPort=2002
    keyAlias=
    keyAliasPasswd=
    keyStorePasswd=
    keyStorePath=${DLC}/keys/
    noSessionCache=0
    numInitialSessions=5
    sessionActivateProc=
    sessionConnectProc=
    sessionDeactivateProc=
    sessionDisconnProc=
    sessionExecutionTimeLimit=0
    sessionShutdownProc=
    sessionStartupProc=
    sessionStartupProcParam=
    sessionTimeout=180
    sslAlgorithms=
    sslEnable=0
.......

Ostatnia sekcja nie jest komentarzem – zawiera zestaw właściwości, które powinny zostać scalone z plikiem openge.properties dla nowej instancji serwera.

Dalsze porady dotyczą ręcznej konfiguracji wynikającej z różnic w ścieżkach dostępu, architektury systemu operacyjnego, zmiennych środowiskowych, połączeń z bazami danych itd.
Dla pełniejszych informacji warto pobrać i przeczytać dokument: Quick Start: Moving Your Classic AppServer Applications to the Progress® Application Server for OpenEdge®.

Bezpieczeństwo w PASOE cz. V – OE Realm

Po ostatnim artykule dostałem pytanie: czy można wykorzystać obiekt CLIENT-PRINCIPAL w PASOE bez konieczności korzystanie z LDAP. Otóż można i zaraz pokażę jak to zrobić na podstawie informacji zaczerpniętych z bazy wiedzy (000194706). (Uwaga: technika ta dotyczy wersji OE 12.2. W bazie można znaleźć podobne rozwiązanie np. dla OE 11, które nie działa poprawnie).

Na początek trzeba powiedzieć czym jest OERealm. Jest to implementacja SPA (Single Point of Authentication), rozszerzająca proces uwierzytelniania Spring Security. Implementacja ta składa się z komponentu klienta i servera OERealm napisanych w języku obiektowym ABL (OO ABL).


Źródłem danych może być nie tylko baza, ale także omawiane wcześniej LDAP lub inne żródło.
OE Realm Service Interface jest klasą OO ABL, która zawiera metody sprawdzające tożsamość użytkownika i dostarczające informację o atrybutach zweryfikowanego użytkownika.

Po stronie klienta należy zaimplementować własny proces uwierzytelniający. Aktualnie klientem OE Realm może być REST, BPM i Rollbase.

W niniejszym artykule zajmiemy się uwierzytelnianie klientów REST, przy czym dane użytkowników są zdefiniowane w tabeli _User w domenach bazy danych OpenEdge.

Na początek przygotujmy bazę (realmdb, kopia bazy sports2000), dadajmy domenę RealmDom, kod dostępu do domeny realmpa.

Dodajmy użytkownika restuser1 do domeny RealmDom oraz user1 do domeny pustej (hasło np. takie samo jak nazwa użytkownika).

Teraz trzeba stworzyć rolę i nadać ją użytkownikowi restuser1…


CREATE _Sec-role.
ASSIGN _Role-name = “PSCUser”
_Role-description = “User level role”.
_Role-creator = “”. /* Name of the user or Role that created this role */

CREATE _sec-granted-role.
ASSIGN _sec-granted-role._grantee = “restuser1@RealmDom”.
_sec-granted-role._role-name = “PSCUser”.
_sec-granted-role._grantor = “”. /* the user or role that granted use of this role */
_sec-granted-role._grant-rights = YES.
_sec-granted-role._granted-role-guid = substring(base64-encode(generate-uuid), 1, 22).

…oraz sekwencję wymaganą przez klasę OEUserRealm.cls.


USING OpenEdge.DataAdmin.*.

DEFINE VARIABLE sequence AS ISequence NO-UNDO.
DEFINE VARIABLE service AS CLASS DataAdminService.
service = NEW DataAdminService().

sequence = service:NewSequence("Next-User-Num").

sequence:InitialValue = 1.
sequence:IncrementValue = 1.
sequence:IsCyclic = FALSE.
sequence:MaximumValue = ?.

service:CreateSequence(sequence).

Tworzymy nową instancję PASOE (nazwałem ją realmpas) z przyłączoną bazą realmdb.
Aby tylko ta instancja mogła uruchomić plik klasy Oe Realm, wygenerujemy plik CP poleceniem:
genspacp -user oerealm -password RESTSPAPassword -role RESTSpaClient -file realm.cp

W komendzie tej dane użytkownika nie mają nic wspólnego z użytkownikami zdefiniowanymi w bazie.
Dane te będą znajdować się w pliku spaservice.properties, który należy umieścić w podkatalogu …/realmpas/openedge.
Wygenerowany plik realm.cp umieścimy natomiast w podkatalogu …/realmpas/common/lib/.

Teraz, podobnie jak w poprzednim artykule, wygenerujemy zaszyfrowany plik rejestru. Najpierw tworzymy prosty plik tekstowy domreg.csv zawierający tylko jedną linię: nazwa domeny, kod dostępu.
RealmDom, realmpa.
Zaszyfrowany plik generujemy poleceniem gendomreg domreg.csv ABLDomainRegistry.keystore.
Nazwa pliku jest dowolna. W tym przykładzie jest to nazwa domyślna, używana w pliku z ustawieniami PASOE. Umieszczamy go w podkatalogu …/realmpas/conf.
Plik OEUserRealm.properties kopiujemy do podkatalogu …/realmpas/openedge. Zawiera on tylko dwie linie:

validateCP=true
debugMsg=true

Wszystkie pliki potrzebne aby uruchomić ten przykład możemy pobrać STĄD.

Przejdżmy teraz do Developer’s Studio i stwórzmy prosty projekt oparty na naszym PASOE typu REST z wykorzystaniem JSDO (pokazywałem kiedyś jak to zrobić na tym blogu). W projekcie tym (nazwałem go myrealm) tworzymy Busineee Entity dla tabeli Customer. Zresztą, może to być jakikolwiek inny projekt dla serwisu REST. Mamy więc projekt i wygenerowany podkatalog AppServer. Importujemy do tego podkatalogu pobraną strukturę psc/stat/realm z plikami klasy.
Jeśli tworzycie takie projekty to pewnie dobrze wiecie jak to zrobić. Jeśli nie, to wg. mnie, najwygodniej utworzyć plik zip tylko ze strukturą i plikami, które chcemy zaimportować (pobrany plik .zip zawiera także ustawienia, plik .cp itp.), a następnie klikamy prawym klawiszem na podkatalog AppServer i wybieramy import -> Archive File. Radzę skasować pliki .r ponieważ były skompilowane dla bazy sports2000 i mogą generowac błędy.

Przechodzimy teraz do pliku z ustawieniami PASOE oeablSecurity.properties. Możemy to zrobić bezpośrednio w podkatalogu …\realmpas\webapps\myrealm\WEB-INF, bądź z Dev. Studio pod naszym projektem PASOEContent/WEB-INF/oeablSecurity.properties.

Dodajemy w nim ustawienia lub upewniamy się, że są tam takie jak poniżej (niektóre ustawienia powinny mieć domyślne wartości).

http.all.authmanager=oerealm
client.login.model=form

OEClientPrincipalFilter.enabled=true
OEClientPrincipalFilter.registryFile=ABLDomainRegistry.keystore

OERealm.UserDetails.realmClass=psc.stat.realm.OEUserRealm
OERealm.UserDetails.grantedAuthorities=ROLE_PSCUser.ROLE_PSCAdmin,ROLE_PSCDebug
OERealm.UserDetails.appendRealmError=false
OERealm.UserDetails.realmTokenFile=realm.cp

W ustawieniach PASOE dodajemy procedurę activate.p. Można to zrobić w OE Explorer (jak poniżej), w pliku openedge.properties lub w Dev. Studio Open Launch configuration -> Startup. Ta ostatnia metoda ustawia zmienne tylko tymczasowo i jest bardzo wygodna w testowaniu.
Procedura ta jest zapisana w podkatalogu …/realmpas/openedge. Uruchamia ona procedurę dumpCP.p, którą także musimy umieścić w tym katalogu. Zapisuje ona do logu dane o Client-Proncipal.

Po tych wszystkich zabiegach tak wygląda podkatalog …/realmpas/openedge

… a tak pliki w projekcie.

Uruchamiam PASOE i próbuję zalogować się do mojego serwisu: http://localhost:8853/myrealm/static/auth/login.jsp

Próba jest udana i w logu agenta możemy znaleźć nast. informacje:

.....
(Procedure: 'dumpCP.p' Line:16) psc.stat.realm.OEUserRealm&ValidateUser Client-Principal:
(Procedure: 'dumpCP.p' Line:17) ID:         'oerealm@OESPA'
(Procedure: 'dumpCP.p' Line:18) session-id: 1ehUo504Taq+XFpP8CFSMw
(Procedure: 'dumpCP.p' Line:19) state:      SSO
(Procedure: 'dumpCP.p' Line:25) details: The CLIENT-PRINCIPAL object credentials were validated by an external system
(Procedure: 'dumpCP.p' Line:27) roles: RESTSpaClient
.....
(Procedure: 'ValidateUser psc.stat.realm.OEUserRealm' Line:590) Lookup ABL user account for: restuser1@RealmDom
(Procedure: 'ValidateUser psc.stat.realm.OEUserRealm' Line:599) ValidateUser found user: restuser1@RealmDom
(Procedure: 'ValidateUser psc.stat.realm.OEUserRealm' Line:613) Lookup user account for: restuser1@RealmDom returned id: 2
.....

Pliki klas możemy oczywiście napisać sami, ale potrzebna jest do tego odpowiednia wiedza. Na początek warto bazować na tych przykładowych plikach.
I to by było na tyle.

1 2