...

Katalog domowy jest jednym wspólnym miejscem do trzymania danych/ustawień aplikacji takich jak:

1. logi (domyślnie)
2. wtyczki
3. konfiguracja
4. XPDL
5. katalog tymczasowy

Elementy katalogu domowego

Podczas pierwszego uruchomienia systemu z ustawionym katalogiem domowym, powstaną poniższe jego elementy z domyślnymi ustawieniami.
Jednak jest możliwość podania także własnych ustawień w podanym miejscu.

Elementy konfiguracyjne

To elementy umieszczone w katalogu domowym, które służą do ustawień działania PlusWorkflow.

...

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/

...

Konfiguracja parametrów systemu

...

Pozostałe elementy

To elementy umieszczone w katalogu domowym, które nie służą do ustawień działania, ale zawierają już konkretne elementy potrzebne do działania albo efekty 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.

Konfiguracja katalogu domowego

Aby ustawić/zmienić katalog domowy trzeba ustawić jego elementy konfiguracyjne we wskazanym w 'Elementy konfiguracyjne' lokalizacji własnych ustawień :

Konfiguracja ścieżki katalogu

 Ustawienie 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:

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 parametrów systemu

...

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'

Konfiguracja logów

Polega na podpięciu własnego pliku ustawień log4j, w miejscu wskazanym w 'Elementy konfiguracyjne' lokalizacja własnych ustawień.

Włączenie katalogu domowego

Aby po raz pierwszy włączyć katalog domowy, nie wszystkie ustawienia są konieczne. Potrzebne są z kolei dodatkowe kroki, jeśli chcemy włączyć katalog domowy na działającym już systemie.
Poniższy opis pokazuje co trzeba zrobić, a co jest opcjonalne w zależności od sytuacji.
Natomiast bardziej szczegółowy sposób ustawiania elementów konfigurowalnych jest opisany w 'Konfiguracja katalogu domowego', a informacje o miejscu ich wykonania znajduje się w opisie elementów tj. w 'Elementy konfiguracyjne'.

Na nowym systemie

Aby nowo przygotowywany system działał z Katalogiem domowym należy wykonać następujące ustawienia w zależności sposobu instalacji i potrzeb.

Instalowanym bez Instalatora

	Wymagane	Uwagi
Ustawienie ścieżki katalogu
Ustawienie własnej bazy danych	*	*Nie wymagane tylko na systemach tymczasowych np. demonstracyjnych. Wtedy ten krok można pominąć, a system domyślnie uruchomi się na wbudowanej bazie danych.
Ustawienie własnych wartości wybranych parametrów systemu
Ustawienie własnych logów

Instalowanym za pomocą Instalatora

Na nowym systemie, który jest instalowany za pomocą instalatora wystarczy podać podczas instalacji w oknie instalator'a, ścieżkę katalogu domowego. A parametry dot bazy danych, tylko jeśli korzystamy z zewnętrznej bazy danych.
Wtedy elementy konfiguracyjne  zostaną odpowiednio wypełnione przez instalator.

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 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 wątków (zmienne środowiskowe)

Mechanizm monitorowania 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 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).

Inne zmienne środowiskowe

Oprócz powyższych zmiennych środowiskowych, dostępne są również następujące z nich do użycia wewnętrznego:

• PWFL_SHARK_UNCOMMITED_TX_DEADLOCK_PROTECTION_STARTUP_DEADLINE
  • opóźnienie w minutach pierwszego sprawdzenia stanu wtyczki
• PWFL_SHARK_UNCOMMITED_TX_DEADLOCK_PROTECTION_ATTEMPTS
  • ilość podejmowanych prób commitowania zawieszonych połączeń sharkowych
• PWFL_SHARK_UNCOMMITED_TX_DEADLOCK_PROTECTION_ATTEMPT_POSTPONE
  • opóźnienie w sekundach podjęcia następnej próby commitowania zawieszonych połączeń sharkowych

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 ustawienia kroki w zależności od potrzeb :

Należy usunąć

Opis kroku	Wymagane	Wymagana dodatkowa czynność	Ustawienie ścieżki katalogu	Dodatkowe informacje
Ustaw ścieżkę katalogu w parametrze plusworkflow.home w web.xml (włączenie katalogu domowego)
Ustawienie własnej Przenieś ustawienia bazy danych z context.xml do pliku <home-dir>/config/db.properties		Należy usunąć Usuń konfigurację bazy z pliku context.xml i web.xml (tag 'resource-ref').
Ustawienie własnych wartości wybranych parametrów systemu		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 zlikwidowanie 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 tego pliku web.xml usunąć parametr 'WorkingDirectory'.
Ustawienie własnych logów		Należy usunąć konfigurację dot. parametru o nazwie 'log4jConfigLocation' z pliku web.xml
Migracja zainstalowanych wtyczek		Przekopiować zawartość obecnego katalogu z wtyczkami do nowej lokalizacji (wg info o lokalizacji własnych ustawień).
Migracja zainstalowanych map procesów		Przekopiować zawartość obecnego katalogu z mapami XPDL do nowej lokalizacji (wg info o lokalizacji własnych ustawień).
Migracja logów		Przekopiować zawartość obecnego 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 (wg info o lokalizacji własnych ustawień). Jeśli tego nie zrobimy to logi będą powstawały od nowa w 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();