Wstęp

Katalog domowy jest jednym wspólnym miejscem do trzymania następujących elementów PlusWorkflow:

• konfiguracji:
  - bazy danych,
  - parametrów systemu,
  - logów,
  - funkcji eksperymentalnych
• danych:
  -pliki logów,
  -zainstalowane wtyczki,
  -katalog tymczasowy,
  -mapy procesów.

Włączenie katalogu domowego na nowym systemie

Na nowych systemach katalog domowy domyślnie jest włączony (parametr plusworkflow.home w pliku web.xml domyślnie ustawiony na '../PlusWorkflow Home'). Wystarczy ustawić konfigurację bazy danych (w <home-dir>/config/db.properties), a pozostałe ustawienia najlepiej pozostawić domyślne. Dla systemów tymczasowych (np.demonstracyjnych) także ustawienie bazy danych nie jest potrzebne, wtedy PlusWorkflow uruchomi się na wbudowanej bazie.

Z kolei w przypadku instalowania nowego systemu instalatorem wystarczy podać ścieżkę katalogu domowego oraz konfigurację bazy danych w oknie instalatora.

Automatyczna instalacja wtyczek

Istnieje możliwość automatycznego instalowania wtyczek umieszczonych w katalogu domowych (od wersji 4.1.2). W katalogu <home-dir>/config/plugins należy umieścić pliki .jar wtyczek które chcemy instalować przy starcie systemu.

Zasady aktualizacji w zależności od wersji wtyczek już zainstalowanych:

Wersja w katalogu domowym	Wersja zainstalowana	Akcja
1.0.0	brak
1.0.0-SNAPSHOT	brak
1.0.1	1.0.0	(wtyczka w katalogu jest nowsza)
1.0.0	1.0.0	(wersje wtyczek są takie same)
1.0.0	1.0.1	(zainstalowana wtyczka jest nowsza)
2.0.0	1.0.0-SNAPSHOT	(wtyczka w wersji SNAPSHOT)
1.0.0-SNAPSHOT	2.0.0	(wtyczka w wersji SNAPSHOT)

Zmiana ustawień katalogu domowego

Ustawienia katalogu domowego można ustawić poprzez konfigurację jego następujących elementów. Aczkolwiek poza konfiguracją bazy danych, zalecane jest pozostawienie domyślnych ustawień.

Konfiguracja ścieżki katalogu

plusworkflow-home.properties

Lokalizacja: parametr plusworkflow.home w plusworkflow-home.properties

Plik plusworkflow-home.properties musi znajdować się w projekcie w folderze src/main/resources. Po wypakowaniu systemu na Tomcata jest to odpowiednio katalog webapp/WEB-INF/classes . Przykładowa zawartość pliku:

plusworkflow.home=/home/nazwa_uzytkownika/Suncode/Home

web.xml

Lokalizacja: parametr plusworkflow.home w web.xml

Plik web.xml musi znajdować się w projekcie w folderze src/main/webapp/WEB-INF. Po wypakowaniu systemu na Tomcata jest to odpowiednio katalog webapp/WEB-INF . "Szablon" pliku web.xml najlepiej pobierać z czystego projektu systemu w określonej wersji.

	<context-param>
		<param-name>plusworkflow.home</param-name>
		<param-value>../PlusWorkflow Home</param-value>
	</context-param>

Konfiguracja bazy danych (plik db.properties)

Lokalizacja: parametry w pliku <home-dir>/config/db.properties

# Database connection configuration
# [Connection]
# Database name
db.name=
# Database server type [postgresql, oracle, mssql, db2, db2as400]
db.type=
# Database server host (without port)
db.host=
# Port on which database server accepts connections
db.port=
# Database user
db.username=
# Database user password
db.password=
# [Optional] JDBC connection URL (if empty, connection URL will be build based on properties above)
db.connectionUrl=

# [Connection pool configuration]
# Maximum pool size (default 30)
db.pool.size=30
# Minimum number of idle connections in pool (default 5)
db.pool.idle=5
# Timeout for acquiring connection from the pool (defaults to 5 minutes)
db.pool.connectionTimeout=300000
# Time after acquired connection will be considered as leak if it wasn't closed (defaults to 5 minutes). To disable set 0.
db.pool.leakDetectionThreshold=300000
# [Optional] SQL that will be invoked on new connection creation
db.pool.connectionInitSql=

Konfiguracja bazy danych (zmienne środowiskowe)

Bazę danych również można skonfigurować przez zmienne środowiskowe. Jest to mało przydatne przy normalnej instalacji systemu u klienta. Jest to preferowana opcja skonfigurowania połączenia z bazą, jeśli system uruchamiany jest w Dockerze (np. Azure).

Nazwy parametrów do skonfigurowania (funkcje analogicznie, do parametrów w punkcie Konfiguracja bazy danych (plik db.properties):

• PWFL_DB_HOST
• PWFL_DB_TYPE
• PWFL_DB_PORT
• PWFL_DB_USERNAME
• PWFL_DB_PASSWORD
• PWFL_DB_NAME
• PWFL_DB_CONNECTIONURL
• PWFL_DB_POOL_SIZE
• PWFL_DB_POOL_IDLE
• PWFL_DB_POOL_CONNECTIONTIMEOUT
• PWFL_DB_POOL_LEAKDETECTIONTHRESHOLD
• PWFL_DB_POOL_CONNECTIONINITSQL

Jeśli skonfigurowane są wymagane zmienne środowiskowe, system pominie sprawdzanie pliku db.properties. Nie utworzy również katalogu config w katalogu domowym.

Konfiguracja parametrów systemu

Lokalizacja: PlusWorkflow w 'Administracja' -> 'Konfiguracja systemu' -> 'Parametry systemowe'

Od wersji 3.2.22 zalecanym sposobem zmiany parametrów jest ich zmiana bezpośrednio w PlusWorkflow.
Natomiast w starszych wersjach można to zrobić poprzez własne ustawienia wartości parametrów w <home-dir>/config/PlusWorkflow.conf

Konfiguracja logów

Lokalizacja pliku konfiguracyjnego: 

Na początku system sprawdza, czy w katalogu domowym w folderze config znajduje się plik log4j2.xml i z niego bierze konfigurację.

Jeżeli plik nie istnieje, to konfiguracja brana jest z projektu plusworkflow-web/resources z pliku log4j2-prod.xml (katalog WEB-INF/classes).

W celu modyfikacji pliku konfiguracyjnego należy przekopiować plik log4j2-prod.xml do folderu config w katalogu domowym i zmienić nazwę na log4j2.xml. Po modyfikacji należy zrestartować system.

Lokalizacja plików z logami:

Domyślnie pliki z logami zapisywane są do folderu logs w katalogu domowym.

Ścieżkę można zmienić ustawiając parametr plusworkflow.logs w pliku plusworkflow-home.properties lub zmieniając ścieżki w pliku konfiguracyjnym w wybranym appenderze.

Konfiguracja funkcji eksperymentalnych

Lokalizacja: domyślna lokalizacja (opcjonalnie odczytywana przez system) pliku to <home-dir>/config/experimental.properties.

Funkcje eksperymentalne uruchamiane są poprzez dodanie w nowej linii wpisu reprezentującego daną funkcje:

• <id funkcji>=<true/false>

Przykładowa zawartość pliku experimental.properties z uruchomionymi dwoma funkcjami:

jakasFunkcja1=true
jakasFunkcja2=true

Lista funkcji eksperymentalnych jest zmienna i obecnie dostępne funkcje zadeklarowane są klasie enumeracyjnej ExperimentalFeature jako parametr konstruktora

• np. dla JAKAS_FUNKCJA_1( "jakasFunkcja1" ) identyfikatorem parametru jest jakasFunkcja1

Konfiguracja mechanizmu monitorowania połączeń oraz wątków (plik db.properties)

Lokalizacja: parametry w pliku <home-dir>/config/db.properties

# [Threads monitoring configuration]

# Global toggle for threads monitoring mechanisms (default false)
db.threads-monitoring.enabled=false

# Starts tasks periodically dumping threads states to Concurrent logs (default false)
db.threads-monitoring.task.enabled=false

# Delay in seconds to start task after system start (default 240)
db.threads-monitoring.task.delay=240

# Period in seconds between each threads states dumps (default 60)
db.threads-monitoring.task.period=60

# Enable logging of shark process lock attempts that could lead to deadlock exception (default false)
db.threads-monitoring.warnings.dangerousProcessLocks=false

# Enable logging of redundant shark transaction creation
# Such transactions can lead to older data access and faster shark transaction pool drain (default false)
db.threads-monitoring.warnings.redundantSharkTransactions=false

# Enable logging of redundant hikari connection allocations
# Such allocations can lead to faster hikari connection pool drain (default false)
db.threads-monitoring.warnings.redundantHikariConnections=false

Konfiguracja mechanizmu monitorowania połączeń oraz wątków (zmienne środowiskowe)

Mechanizm monitorowania połączeń oraz wątków również można skonfigurować przez zmienne środowiskowe. Jest to mało przydatne przy normalnej instalacji systemu u klienta. Jest to preferowana opcja skonfigurowania tego mechanizmu, jeśli system uruchamiany jest w Dockerze (np. Azure).

Nazwy parametrów do skonfigurowania (funkcje analogicznie, do parametrów w punkcie Konfiguracja mechanizmu monitorowania połączeń oraz wątków (plik db.properties)):

• PWFL_DB_THREADS_MONITORING_ENABLED
• PWFL_DB_THREADS_MONITORING_TASK_ENABLED
• PWFL_DB_THREADS_MONITORING_TASK_DELAY
• PWFL_DB_THREADS_MONITORING_TASK_PERIOD
• PWFL_DB_THREADS_MONITORING_WARNINGS_DANGEROUS_PROCESS_LOCKS
• PWFL_DB_THREADS_MONITORING_WARNINGS_REDUNDANT_SHARK_TRANSACTIONS
• PWFL_DB_THREADS_MONITORING_WARNINGS_REDUNDANT_HIKARI_CONNECTIONS

To, czy użyte zostaną te zmienne środowiskowe, zależy od zdefiniowania wymaganych parametrów z sekcji Konfiguracja bazy danych (zmienne środowiskowe).

Lokalizacja danych

Jeśli katalog domowy jest włączony to w ustawionym folderze znajdują się następujące dane dotyczące działania PlusWorkflow:

Kompatybilność wstecz

Jeżeli w pliku web.xml nie został skonfigurowany katalog domowy, to:

• wczytywana jest konfiguracja z PlusWorkflow.conf po staremu (parametr w web.xml)
• baza danych pobierana jest z context.xml 
• wtyczki przechowywane są w starym katalogu (skonfigurowanym w suncode-plugins.xml)

Katalog domowy jest mimo wszystko ustawiany (domyślnie ../PlusWorkflow Home) – dlatego mogą tam trafić logi (jeżeli plik nie został nadpisany), będzie tam temp, katalog użytkownika (user.dir) etc.

Włączenie katalogu domowego na działającym systemie (bez katalogu domowego)

Aby zmigrować do katalogu domowego system (z tą samą bazą, procesami itp), który wcześniej działał bez katalogu domowego, należy wykonać następujące kroki w zależności od potrzeb :

Opis kroku	Wymagane	Dodatkowe informacje
Ustaw ścieżkę katalogu w parametrze plusworkflow.home w web.xml (włączenie katalogu domowego)
Przenieś ustawienia bazy danych z context.xml do pliku <home-dir>/config/db.properties		Usuń konfigurację bazy z pliku context.xml i web.xml (tag 'resource-ref').
Przenieś ustawienia parametrów z PlusWorkflow.conf, które mają ustawienia różne od domyślnych. Zmień wartości domyślne parametrów w PlusWorkflow w Administracja' -> 'Konfiguracja systemu' -> 'Parametry systemowe'		Usuń konfigurację parametru 'Shark_Conf' z pliku web.xml Jeśli używany był PlusWorkflow.conf z własnymi ustawieniami parametrów to zalecane jest jego usunięcie i ustawienie tych zmienionych parametrów w Konfiguracji systemu->Parametry systemu. Jeśli jednak ustawienia parametrów zostaną nadpisane poprzez umieszczenie PlusWorkflow.conf w miejscu własnych ustawień (nie zalecane), to trzeba z web.xml usunąć parametr 'WorkingDirectory'.
Przenieś zawartość dotychczasowego katalogu z wtyczkami do <home-dir>/data/plugins (lub ew. zainstaluj wtyczki od nowa)
Przenieś zawartość dotychczasowego katalogu z mapami procesów do <home-dir>/XPDL
Własne ustawienia logów		Jeśli to niezbędne, bo nie jest zalecane, ustaw własne ustawienia logów przenosząc plik Log4j2.xml z katalogu resources w projekcie plusworkflow-web do <home-dir>/config.
Jeśli przeniesiono własne ustawienia logów i została w nich zmieniona lokalizacja powstawania plików z logami, a chcesz kontynuować poprzednie pliki logów to przekopiuj zawartość wcześniejszego katalogu z logami do nowej lokalizacji (ustawionej w <home-dir>/config/Log4j.xml)

InitialContext initialContext = new InitialContext();
DataSource dataSource = (DataSource) initialContext.lookup( "java:comp/env/PlusWorkflowResource" );

DataSource dataSource = DataSourceFactory.getDataSource();