Upload
lamduong
View
216
Download
0
Embed Size (px)
Citation preview
Release Notes BALVI Schnittstellenserver Seite 1 von 37
Inhaltsverzeichnis
1 Allgemeine Hinweise 3 11 Neuerungen in Version 3132 3 12 Neuerungen in Version 30 5 13 Hinweise zum Update von aumllteren Versionen (vor 30x) 6 14 Nacharbeiten nach dem Update auf Version 28 (ADMIN) 7 15 Neuerungen in Version 28 7
151 Jeder Schnittstellen-Server benoumltigt eine Kennung bdquoserverIDldquo 7 152 Optional ist nun eine Namensvergabe moumlglich 8
2 Einrichtungshinweise 9 21 Allgemeine Hinweise zum Betrieb 9
211 Kompatibilitaumlt zu Apache Tomcat und Java SE 9 212 Oracle Java SE Lizenzierung 9 213 Einsatz von TLSSSL 9 214 Nutzung von Java-Proxyeinstellungen 10 215 Spracheinstellung Deutsch 11 216 Datenbankverbindung 11 217 Probleme beim Anlegen von LOB-Objekten 11 218 Umbenennung der gelieferten WAR-Datei 11 219 Server-Schnittstellen 11
22 Kompatibilitaumltsliste 12 23 Erforderliche Bibliotheken fuumlr Apache Tomcat 13 24 Datenbank-Installation 13
241 Erstinstallation Datenbank-Benutzer anlegen 14 242 Rechte zuweisen 14 243 Wann ist die Ausfuumlhrung des Grant-Skripts erforderlich 15 244 Welche Version des Grant-Skripts soll ich nehmen 16 245 Kombination von mehreren Verfahren 16
25 Konfiguration des Schnittstellen-Servers 17 251 Die bdquocontextxmlldquo-Parameter 17
26 Logging mit logback 27 27 Tocmat Optional Suche im bdquoKlassenpfadldquo um den Ordner bdquoconfldquo erweitern 28
3 Die neue Browser-Oberflaumlche 28 31 Server-Protokoll 28 32 Jobs 30 33 Log-Ausgaben 30 34 LogoutAbmeldung vom System 32 35 Cache loumlschen 32
4 Einrichtung in BALVI iP 34 5 Bekannte Probleme und Loumlsungen 36
51 ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner 36
Release Notes BALVI Schnittstellenserver Seite 2 von 37
52 Server startet nicht 36 53 ORA-00942 table or view does not exist 36 54 ORA-0406x bdquoBestehender Paketstatus wurde aufgehobenldquo 36 55 Jobs sind nicht ausfuumlhrbar 37
Release Notes BALVI Schnittstellenserver Seite 3 von 37
1 Allgemeine Hinweise
Der neue BALVI Schnittstellenserver (BSS) 32 ersetzt alle ausgelieferten Versionen
Der BSS ist ausschlieszliglich ein Zusatz-Server welcher an eine vorhandene BALVI iP Datenbank angebunden werden kann um neue automatisierte webbasierte Schnittstellen zur Verfuumlgung zu stellen
Zu diesen Schnittstellen gehoumlren bislang
BALVI mobil XT ab Version 15
Daten-Export an eFi (BVL nur fuumlr ausgewaumlhlte Test-Bundeslaumlnder)
Bidirektionale Datenaustausch-Schnittstelle zum LIMS
xDomea-konforme DMS-Web-Schnittstelle
Betriebsregister-Schnittstelle zum Abgleich von Betriebsstammdaten
TSK-Meldebogen-Schnittstelle (Sachsen)
Import-Schnittstelle XGewerbeanzeigen des BMWi gem Spez 1112
RioPP LM ndash Uumlbernahme der Probenplaumlne (NRW)
Synchronisation mit IP2-Modulen
o IP2 ndash DM ndash Duumlngemittelmodul NRW und BALVI mobil 2 (DM)
o IP2 ndash LM ndash Lebensmittelmodul (NRW Teststellung)
o IP2 ndash BTS ndash Betriebsstaumlttenmodul (NRW Teststellung)
o IP2 ndash ZDA ndash Zentrale Dokumentablage (ab BALVI iP 1249 nutzbar)
Die meisten Schnittstellen koumlnnen durch BALVI dynamisch aktualisiert und erweitert werden ohne dass dabei der Betrieb von BALVI iP beeinflusst wird In einzelnen Faumlllen ist es jedoch erforderlich den BSS nach der Aktualisierung bzw Bereitstellung einer neuen Schnittstelle neu zu starten
Da der BSS bislang als Erweiterung fuumlr BALVI iP konzipiert ist gibt es zusaumltzlich mehrere BALVI iP Patches welche in die BALVI iP Datenbank eingespielt werden muumlssen um die neuen Schnittstellen zu aktivieren bzw zu aktualisieren
Das Update des WAR auf die neue Version 320 hat folgende Grundvoraussetzungen
- BALVI iP 1240 (oder houmlher)
- Java SE 8
- Tomcat 8 (min 8030 oder neuer)
Sollten Sie noch eine aumlltere Version von BALVI iP einsetzen und aus organisatorischen Gruumlnden nicht auf 1240 oder houmlher aktualisieren koumlnnen kontaktieren Sie bitte den Support
11 Neuerungen in Version 3132 Das Update von Version 3x auf 32 beinhaltet diverse Optimierungen und Erweiterungen der ETL-Engine damit die Ausfuumlhrung von IP1-zu-IP2-Synchronisationsprozessen besser moumlglich ist Dafuumlr wurde in der
Release Notes BALVI Schnittstellenserver Seite 4 von 37
Oberflaumlche ein neuer Menuumlpunkt bdquoETL-Tasksldquo ergaumlnzt der jedoch in der Datei bdquocontextxmlldquo aktiviert werden muss
Um den Menuumlpunkt zu aktivieren ergaumlnzen Sie in der Konfiguration folgenden Parameter
lt--ETL spezifische Erweiterungen ab BSS 31 --gt
ltEnvironment
name=isEtlTaskViewEnabled
value=true
type=javalangBoolean override=true
gt
Zudem wurden die folgenden Parameter ergaumlnzt damit im Datenabgleich Performance-Tuning moumlglich ist
lt-- Timeout-Einstellungen --gt
lt-- Wartezeit in Sekunden bei Requests Standard 60 --gt
ltEnvironment
name=xmlgenrestRequestTimeoutSeconds
value=60
type=javalangInteger override=true
gt
lt-- Anzahl an angefragten Ergebnisdatensaumltzen pro Requests Standard 20 --gt
ltEnvironment
name=xmlgenmaxEntriesPerRestRequest
value=20
type=javalangInteger override=true
gt
Zudem die Ausgabe der Java-Protokolle und deren Anzeige in der Oberflaumlche uumlberarbeitet In diesem Zusammenhang wurde ermoumlglicht dass der Tomcat-Administrator die Liste der Dateitypen angibt die beim Export der LOG-Dateien gesucht und in den Download eingepackt werden sollen
lt-- Neu ab BSS 32 auf Wunsch einiger Kunden (OPTIONAL) --gt
lt-- Welche Dateierweiterungen sollen als Default
fuumlr LOG-Dateien verwendet werden (Standard log txt) --gt
ltEnvironment
name=extensionsOfLogFiles
value=log txt out gz
type=javalangString override=true
gt
Die Ausgabe der Fachprotokolle in der Oberflaumlche wurde ebenfalls uumlberarbeitet so dass nun ein Datumsfilter bdquo(Heute ndash 1 Monat)ldquo vorbelegt wurde Neu ergaumlnzt wurde die Moumlglichkeit in der Suche die Anzeige von allen Protokollsaumltzen (Standard ist bdquoNur Kopfsaumltzeldquo) wieder mit auszugeben
Release Notes BALVI Schnittstellenserver Seite 5 von 37
12 Neuerungen in Version 30 Der BSS 3x beinhaltet alle Funktionalitaumlten des BSS 28x und ist daher abwaumlrtskompatibel
Zusaumltzlich ist es ab Version 3x moumlglich Synchronisations-Jobs zu verarbeiten die mit der OpenSource ETL- Engine bdquoPentaholdquo durch BALVI entwickelt werden Damit wird der BSS auf das zukuumlnftige BALVI iP2 vorbereitet In diesem Zuge wurden diverse Funktionalitaumlten aktualisiert
Beim Update von BSS 2x auf BSS 3x muumlssen an der Datei bdquocontextxmlldquo folgende Anpassungen vorgenommen werden bevor der Server gestartet werden darf
1 Neuer Parameter isJobServiceEnabled
Der Parameter availableServices wurde durch isJobServiceEnabled ersetzt (siehe Kapitel 2516) Damit ist der Jobservice standardmaumlszligig aktiv Empfehlung Suchen Sie availableServices und entfernen Sie diese Einstellung
2 Neue Logging-Konfiguration
Zu BSS 30 wurde auf eine neue Logging-Klasse umgestellt (siehe Kapitel 26) Ersetzen Sie im Ordner conf die vorhandene Datei bdquolog4j-commserverxmlldquo durch die Datei bdquologback-bssxmlldquo um den neuen APPENDER nutzen zu koumlnnen Entfernen Sie log4jConfigLocation und fuumlgen Sie loggingconf hinzu Tragen Sie in der Datei bdquocontextxmlldquo beim neuen Parameter loggingconf den Pfad zur Datei bdquologback-bssxmlldquo ein Die Logging-Funktionalitaumlt des Servers ist davon nicht betroffen
3 Datenbank-Verbindung bdquofactoryldquo umstellen
Bis Version 28 wurde aus Kompatibilitaumltsgruumlnden zu Tomcat 6 als DBCP-Factory noch auf orgapachecommonsdbcpBasicDataSourceFactory verwiesen Ab Tomcat 7 wird jedoch empfohlen die Tomcat-eigene Umsetzung zu verwenden Aumlndern Sie dazu die Angabe factory= in der bdquojdbcDataSourceldquo auf factory=orgapachetomcatjdbcpoolDataSourceFactory Die Verwendung von commonsdhcp wird nicht mehr empfohlen da die Tomcat-spezifische Datasource orgapachetomcatjdbc diverse interne Mechanismen bereitstellt die den Datenbankzugriff aus Apache Tomcat verbessern Dazu gehoumlren die Interceptor-Einstellungen die im Beispiel von BALVI bssxmlexmaple ergaumlnzt wurden (siehe Kapitel 2511)
Release Notes BALVI Schnittstellenserver Seite 6 von 37
4 ETL-Prozesser
Neue Datenquellen ergaumlnzen
Fuumlr die Kommunikation zwischen iP2 Modulen und iP1 wird Kettle benutzt In die contextxml muss dafuumlr eine zusaumltzliche DataSource eingefuumlgt werden wenn Sie die Daten-Uumlbermittlung von IP1 an IP2 verwenden
Die jdbcKettleIP1DataSource ist im Beispiel auskommentiert verwendet derzeit jedoch immer die Zugangsdaten die Sie auch in der jdbcDataSource eingestellt haben da derzeit beide Datenbank-Verbindungen auf das angebundene BALVI iP (124x) zugreifen sollen Beachten Sie jedoch dass die jdbcKettleIP1DataSource die Einstellung type=debalvikettleKettleDataSourceSettings (nicht javaxsqlDataSource) verwendet damit diese nur und ausschlieszliglich dann geladen wird wenn die Kettle-Engine eine separate Datenbankverbindung benoumltigt Um ETL-Engine (Kettle) mitzuteilen welche DataSource das auszufuumlhrende Modul benoumltigt sind folgende Umgebungseinstellungen in die Datei bdquocontextxmlldquo einzufuumlgen
Beispiel
ltResource
name=jdbcKettleIP1DataSource
auth=Container
type=debalvikettleKettleDataSourceSettings
factory=orgapachetomcatjdbcnamingGenericNamingResourcesFactory
maxActive=3 maxIdle=2 minIdle=1 initialSize=1
gt
Kettle Bibliotheken
Da Kettle fuumlr die Ausfuumlhrung verschiedene Dateien benoumltigt muss zudem der Parameter bdquokettlePluginDirectoryldquo eingestellt werden Weisen Sie dem Wert (bdquovalue=ldquo) den Pfad zu dem Verzeichnis zu in dem die Ausfuumlhrungsdateien liegen Die erforderlichen Dateien sind Bestandteil der Auslieferung
ltEnvironment
name=kettlePluginDirectory
value=hometest_ip2_bsskettleplugins
type=javalangString
override=true
gt
13 Hinweise zum Update von aumllteren Versionen (vor 30x) Ab BSS 282 wird eine bdquoserverIDldquo erwartet Daher ist es zwingend erforderlich die vorhandene Datei bdquocontextxmlldquo zu erweitern und den neuen Environment-Parameter bdquoserverIDldquo zu ergaumlnzen
Release Notes BALVI Schnittstellenserver Seite 7 von 37
14 Nacharbeiten nach dem Update auf Version 28
(ADMIN) Sofern Sie schon aktive bdquoJobsldquo im BSS in Verwendung haben werden diese mit dem Update automatisch deaktiviert da die Jobs nun an den ausfuumlhrenden Server gebunden werden muumlssen Oumlffnen Sie dazu den Job in der Detailansicht setzen Sie den Haken hinter bdquoJob an Server bindenldquo setzen und speichern Sie die Einstellung
Der Job wird anschlieszligend in der Uumlbersicht wieder mit dem Status bdquoAktiviertldquo angezeigt Diesen Konfigurationsschritt muumlssen Sie nun jedes Mal durchfuumlhren nachdem die Datenbank von Produktion auf Test geklont wurde
15 Neuerungen in Version 28
151 Jeder Schnittstellen-Server benoumltigt eine Kennung bdquoserverIDldquo Viele Kunden nutzen den Schnittstellenserver mehrfach in Ihrer Umgebung da mehrere BALVI iP Installationen (z B Produktion und Test) in der Infrastruktur existieren
Da die Schnittstellenkonfiguration fuumlr den BSS in der Datenbank abgelegt wird kam es in manchen Faumlllen vor dass nach dem Klonen der Produktionsdatenbank auf ein Testsystem die im BSS angelegten Jobs sofort nach dem Start in der Testumgebung wieder angesprungen sind Um dieses Problem zu beseitigen muss jedem BSS ab Version 28 eine eindeutige bdquoserverIDldquo zugewiesen werden Diese Server-ID wird in der Datei bdquocontextxmlldquo hinterlegt um neutral zur Datenbank zu sein
Ist keine Environment-Variable bdquoserverIDldquo vorhanden wird der Start des BSS 28 (oder houmlher) sofort mit einer Fehlermeldung abgebrochen Im Server-Protokoll wird dabei der Fehler bdquoERROR [IdentityServiceImpl] serverID must not be emptyrdquo ausgegeben Danach kommt sofort die Meldung dass der BSS wieder heruntergefahren wird
INFO [localhost-startStop-1] [ContextCreationListener]
BALVI-Schnittstellen-Server
Version 280
hellip
ERROR [localhost-startStop-1] [IdentityServiceImpl] serverID must not be empty
ERROR [localhost-startStop-1] [ContextLoader] Context initialization failed
Um eine ldquoserverIDrdquo zu vergeben fuumlgen Sie in der Datei bdquocontextxmlldquo folgende Angabe ein
lt--
Release Notes BALVI Schnittstellenserver Seite 8 von 37
ID fuumlr den Server
Diese muss pro Schnittstellenserver eindeutig sein
Eine Aumlnderung dieser ID fuumlhrt sofort dazu dass alle
eingerichteten Server-Jobs inaktiv werden und neu mit
der Instanz gekoppelt werden muumlssen um wieder aktiviert
werden zu koumlnnen
Als value kann ein Text der max Laumlnge von 32 Zeichen
vergeben werden z B ProductionEnvNode1 fuumlr die Produktion
und TestEnvNode1 fuumlr die Testumgebung
--gt
ltEnvironment
name=serverID
value=ProductionEnvNode1
type=javalangString
override=true
gt
152 Optional ist nun eine Namensvergabe moumlglich Auf Wunsch mehrerer Kunden wurde die Option geschaffen jedem Server zusaumltzlich einen kundenspezifischen bdquoTitelldquo zu geben um die Server besser unterscheiden zu koumlnnen
lt--
Visueller Name des Servers in der Oberflaumlche
(Optional)
--gt
ltEnvironment
name=serverName
value=TIERZ Tomcat 8 Java 8 mit BALVI_TIERZXGEWETLBTR_BSS
type=javalangString
override=true
gt
Der hier angegebene Text wird in der Kopfzeile zwischen den eckigen Klammern ausgegeben
Release Notes BALVI Schnittstellenserver Seite 9 von 37
2 Einrichtungshinweise
21 Allgemeine Hinweise zum Betrieb
211 Kompatibilitaumlt zu Apache Tomcat und Java SE Der BALVI Schnittstellenserver wurde getestet und freigegeben fuumlr Apache Tomcat 8 (ab Version 8030 oder neuer) Zudem wurde die aktuellste (letzte offizielle) Version von Java SE 8 getestet und kann verwendet werden (Java SE 8u40 und neuer)
Installieren Sie stets die aktuellsten Sicherheitsupdates fuumlr Java SE 8 Beachten Sie dabei jedoch dass nicht die Aktualisierung auf eine andere Java-Version (z B Java 9) gemeint ist
Freigegebene Major-Versionen werden explizit von BALVI benannt Falls Sie beabsichtigen die Major-Version zu aumlndern pruumlfen Sie bitte die aktuellen Release Notes oder kontaktieren die BALVI Kundenbetreuung
212 Oracle Java SE Lizenzierung Java SE beinhaltet auch kostenpflichtige Funktionen fuumlr deren Nutzung Oracle Lizenzgebuumlhren fordert wenn sie bei der Entwicklung eingesetzt werden Die von BALVI gelieferte Software ist frei von den kommerziellen Teilen der Oracle Java SE nutzbar Fuumlr den Einsatz von Oracle Java SE (einschlieszliglich JDK und JRE) fallen im Rahmen der Nutzung der BALVI Software keine Lizenzkosten an
Trotzdem werden wir parallel pruumlfen ob technische Probleme bei der Umstellung auf das OpenJDK zu erkennen sind Ein einfacher Funktionstest hat im BSS 3x noch keine technischen Probleme gezeigt als wir die Laufzeitumgebung auf das OpenJDK 8U111 AMD64 (Debian) umgestellt haben Bitte haben Sie Verstaumlndnis dafuumlr dass wir keine Funktionstests fuumlr jedes Linux-Derivat durchfuumlhren koumlnnen und dass es offiziell keine Version des OpenJDK fuumlr Windows Betriebssysteme gibt
213 Einsatz von TLSSSL BALVI hat keine spezifischen Anforderungen an die Konfiguration von SSL bzw TLS Der Einsatz von TLS 12 gem der Richtlinie TR-02102-2 vom BSI ist moumlglich wenn Sie sich an die von Apache Tomcat herausgegebene Dokumentation halten Es sind keine Anpassungen des Schnittstellenservers erforderlich Daher gehen wir davon aus dass auch der BSS 28x oder aumllter in einem Apache Tomcat mit TLS 12 betrieben werden kann
Das gilt jedoch nicht fuumlr alle Clients die den Tomcat-Server ansprechen moumlchten So ist z B erst ab BALVI mobil 191958 sichergestellt dass die Protokolle TLS 11 und TLS 12 programmseitig aktiviert sind Fuumlr Details zu diesem Problem wurde ein separates Rundschreiben per E-Mail versendet
Release Notes BALVI Schnittstellenserver Seite 10 von 37
214 Nutzung von Java-Proxyeinstellungen Der BALVI Schnittstellenserver verwendet fuumlr ausgehende Verbindungen die Java-Net Einstellungen welche in der Java-Dokumentation1 beschrieben sind Falls Sie Jobs einsetzen welche ausgehenden Zugriff auf Adressen im Internet benoumltigen kann es passieren dass Sie z B eine bdquojavanetUnknownHostExceptionldquo im Protokoll finden dann muumlssen Sie ihre Proxy-Umgebung in den Java-Umgebungseinstellungen ergaumlnzen
Die folgenden Parameter sollten daher in Ihrer Umgebung gesetzt werden wenn der Zugriff auf das Internet nur uumlber einen Proxy moumlglich ist
-DproxySet=true
-DproxyHost=10111213
-DproxyPort=8888
-DhttpnonProxyHosts=domainorg|localhost|10
Starten Sie nach Aumlnderung der Einstellungen den Server neu damit die Einstellungen wirksam werden
2141 Proxy-Einstellung unter Windows (Tomcat-Dienst)
Verwenden Sie das Dienste-Konfigurationsprogramm (z B tomcat7wexe) und ergaumlnzen Sie die fehlenden Einstellungen
2142 Proxy-Einstellung unter Linux
In Linux wird in der Konfigurationsdatei (z B conftomcat7conf) die Variable bdquo$JAVA_OPTSldquo entsprechend erweitert und die Werte uumlbergeben Beachten Sie dabei dass die Variablen von Linux (bzw der Bash) gelesen werden Daher muss das bdquoPipeldquo-Zeichen bdquo|ldquo mit bdquoldquo maskiert werden ansonsten erhalten Sie bei der Verarbeitung der Umgebungsvariable bdquohttpnonProxyHostsldquo Fehlermeldungen in der Linux -Konsole welche dazu fuumlhren dass Java nicht korrekt konfiguriert werden kann
JAVA_OPTS=$JAVA_OPTS -DproxySet=true -DproxyHost=10111213 -DproxyPort=8888
JAVA_OPTS=$JAVA_OPTS -DhttpnonProxyHosts=domainorg|localhost|10
1 httpdocsoraclecomjavase8docstechnotesguidesnetpropertieshtml
Release Notes BALVI Schnittstellenserver Seite 11 von 37
215 Spracheinstellung Deutsch Es wurde festgestellt dass unter einigen Linux-Versionen die Spracheinstellung beim Starten des Apache Tomcat nicht auf eine deutsche Umgebung verweist Dieses kann technische Probleme verursachen Unter Linux sollte die Einstellung (Umgebungsvariable) entsprechend auf LANG=de_DEUTF-8 eingestellt sein
216 Datenbankverbindung Wenn Sie eine Firewall zwischen dem Oracle-Server und dem Database Connection Pool (DBCP) verwenden sollte unbedingt die bdquovalidationQueryldquo in der DBCP-Konfiguration aktiviert werden damit die Anwendung schneller freie Connections aus dem Pool erhalten kann Die Dokumentation zu den Einstellmoumlglichkeiten ist in der beiliegenden Contextxml ergaumlnzt worden
Bitte beachten Sie dass dringende empfohlen wird die bdquoFactoryldquo auf orgapachetomcatjdbcpoolDataSourceFactory anzupassen falls sie noch auf bdquoorgapachecommonsdbcpBasicDataSourceFactoryldquo eingestellt ist
217 Probleme beim Anlegen von LOB-Objekten Der BALVI Schnittstellen-Server erfordert die JDBC-Spezifikation DBCP V4 welche durch die Factory bdquoorgapachetomcatjdbcldquo ab Tomcat 7 automatisch bereitgestellt wird
Wenn die Pooling-Komponente oder der Oracle-Treiber nicht JDBC4-Kompatibel sind gibt es beim Bearbeiten von LOB-Objekten in Java diverse Exceptions z B
Servletservice() for servlet soapws threw exception
javalangAbstractMethodError
orgapachecommonsdbcpPoolingDataSource$PoolGuardConnectionWrappercreateClob()LjavasqlClob
at debalvicoreauditspyConnectionSpycreateClob(ConnectionSpyjava511)
Ursache dieses Problems ist meistens dass noch nicht auf bdquoorgapachetomcatjdbcldquo umgestellt wurde
218 Umbenennung der gelieferten WAR-Datei Das im Paket von BALVI gelieferte WAR kann jederzeit umbenannt werden (z B als ROOTwar) ohne dass dabei spezielle Einstellungen in der Datei bdquocontextxmlldquo erforderlich sind
Beachten Sie dabei jedoch dass die zum WAR zugehoumlrige Datei bdquocontextxmlldquo im Apache Tomcat immer denselben Namen erhaumllt wie das WAR z B bdquocommserverwarldquo und bdquocommserverxmlldquo Der Name ist dabei ausschlaggebend fuumlr die Zugriffs-Adresse (Context) im Apache Tomcat selbst Die Benennung des WAR in bdquocommserverwarldquo wuumlrde folgendermaszligen aufzurufen sein httpserverportcommserver
219 Server-Schnittstellen Die Uumlberarbeitung bzw Erweiterung der Export- und Importschnittstellen welche uumlber den Schnittstellenserver bereitgestellt werden ist unabhaumlngig vom Schnittstellenserver selbst Die Schnittstellen sind daher nicht Bestandteile des Schnittstellenserver und werden je Verfahren separat
Release Notes BALVI Schnittstellenserver Seite 12 von 37
ausgeliefert Ggf ist es fuumlr unterschiedliche Schnittstellen erforderlich die Grant-Rechte zu aktualisieren (Vgl bdquoWann ist die Ausfuumlhrung des Grant-Skripts erforderlichldquo)
22 Kompatibilitaumltsliste Diverse Verfahren setzen eine Mindestversion des BALVI Schnittstellenservers voraus Die Schnittstellen sind jedoch so konzipiert dass eine Aktualisierung auf eine houmlhere Version des Servers ohne Anpassung an den vorhandenen Schnittstellen jederzeit moumlglich ist
Derzeit sind folgende Mindestanforderungen gegeben
1 BALVI mobil XT 170 oder houmlher setzt BSS 265 und BALVI iP 124x voraus
2 BALVI mobil XT 183 oder houmlher setzt BSS 281 und BALVI iP 124x voraus
3 BALVI mobil 2 (DM) setzt BSS 311 und BALVI iP 124x voraus
4 Die Schnittstelle eFI setzt BSS 251 und BALVI iP 122c voraus
5 Die Schnittstelle LIMS setzt BSS 265 voraus
6 Die Schnittstelle TSK (SN) setzt BSS 265 voraus
7 Die Schnittstelle xDomea (SN) setzt BSS 265 und Java 7 voraus
8 Die Schnittstelle XGewerbeanzeigen 11 setzt BSS 281 BALVI iP 124x Java 8 mit der bdquoJava
Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy2ldquo voraus
9 Die Schnittstelle XGewerbeanzeigen 12 (ab Paket 7 Ausbaustufe 3) setzt BSS 302 BALVI iP
124x Java 8 mit der bdquoJava Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policyldquo
voraus
10 Die Schnittstelle RioPP LM (NRW) setzt BSS 303 und die ETL-Konfiguration voraus
11 Die Schnittstellen zu BALVI iP2 (Fachmodule BTS LM ZDA Stand Juni 2017) setzen BSS 32x
voraus
2 httpwwworaclecomtechnetworkjavajavasedownloadsjce8-download-2133166html
Release Notes BALVI Schnittstellenserver Seite 13 von 37
23 Erforderliche Bibliotheken fuumlr Apache Tomcat Dateiname Funktion Quelle ojdbc6jar Oracle 11gR2 Clientpaket Oracle JDBC Client fuumlr Java
16 ersetzt die bisherige Version bdquoojdbc14jarldquo Die alte Library muss auf jeden Fall entfernt werden
httpwwworaclecomtechnetworkdatabaseenterprise-editionjdbc-112010-090769html
encrypted-datasource-110-alljar
Die Library muss auf jeden Fall entfernt werden Wird derzeit nicht weiter gepflegt da kein Interesse an der Funktionalitaumlt bestand
slf4j-api-1511jar slf4j-log4j12-1511jar log4jdbc4-12beta2jar
Entfaumlllt nicht mehr erforderlich Es wird empfohlen diese zu entfernen falls diese im LIB-Verzeichnis vorhanden sein sollten
commons-dbcp-14jar commons-pool-154jar
Entfaumlllt nicht mehr erforderlich Es wird empfohlen diese zu entfernen falls diese im LIB-Verzeichnis vorhanden sein sollten
Erwartet wird stattdessen ab Tomcat7 die mitgelieferte bdquotomcat-jdbcjarldquo
log4j-1217jar (oder houmlher)
Logging-Funktionalitaumlt Apache Log4j httploggingapacheorglog4j12downloadhtml
bcprov-jdk15on-157jar (oder houmlher)
BouncyCastle Security Provider fuumlr SSLAES hellip wird ab Version 27 im Ordner bdquolibldquo des Tomcat erwartet Sollte es aus Sicherheitsgruumlnden erwuumlnscht sein eine aktuellere Version einzusetzen ist dieses idR moumlglich
httpmvnrepositorycomartifactorgbouncycastlebcprov-jdk15on157
24 Datenbank-Installation Der BALVI Schnittstellenserver benoumltigt auszligerhalb des angebundenen BALVI iP keine eigenen Tabellen Die Web-Anwendung kann im einfachsten Fall direkt auf das Schema von BALVI iP zugreifen indem der Benutzer und das Passwort des BALVI iP-Schemas in der Datei bdquocontextxmlldquo eingetragen werden (nicht empfohlen)
Sollte dies aus Sicherheitsgruumlnden nicht erwuumlnscht sein (empfohlen vom BSI und von BALVI) finden Sie im Paket ein GRANT-Skript um Zugriffsrechte vom BALVI iP Schema fuumlr den Webservice-Schema-Benutzer einzurichten
Zwischen dem Schema von BALVI iP und jeder Web-Anwendung ist dann eine Trennung moumlglich um sicherzustellen dass der Datenbank-Benutzer welcher in der Tomcat-Konfiguration fuumlr die Web-Anwendung eingetragen wird geaumlndert oder geloumlscht werden kann ohne dass die Windows-Anwendung BALVI iP davon betroffen ist Zudem vergibt das von BALVI gelieferte Grant-Skript keine Rechte zum Loumlschen von Tabellenstrukturen oder Tabelleninhalten so dass der Webservice nur festgelegte Daten aumlndern oder lesen darf Es wird empfohlen je Web-Anwendung einen eigenen Datenbank-Benutzer zu vergeben wenn Sie ein BALVI iP mit mehreren Webservices verbinden wollen
Die Moumlglichkeiten im Uumlberblick
1) Sie betreiben den Webservice mit einem eigenstaumlndigen Oracle-Benutzer In diesem Fall muss das
Grant-Skript ausgefuumlhrt werden um den Webservice-Benutzer und den BALVI iP-Benutzer
miteinander zu koppeln
2) In der Tomcat-Konfiguration wird der Oracle-Benutzer eingetragen welcher auch der BALVI iP
Schemabesitzer ist und in der bdquobalviip_conninildquo hinterlegt ist (NICHT Empfohlen) Der Webservice
Release Notes BALVI Schnittstellenserver Seite 14 von 37
hat 100 Zugriffsrechte (auch Loumlsch- oder Aumlnderungsrechte am Schema) es wird kein Grant-
Skript benoumltigt
Wenn Sie die Konfiguration 2) waumlhlen moumlchten koumlnnen Sie die folgenden Unterkapitel uumlberspringen und in Kapitel 0 bzw fortsetzen
241 Erstinstallation Datenbank-Benutzer anlegen Wenn Sie den Webservice-Benutzer vom BALVI iP Schema trennen moumlchten muss durch die DB-Administration in der Oracle-Server-Instanz wo auch BALVI iP sein Schema besitzt ein Benutzer (ggf je Web-Anwendung) angelegt werden welcher folgende Rechte benoumltigt
CONNECT
ALTER SESSION
CREATE JOB
CREATE PROCEDURE
CREATE SESSION
CREATE TABLE
CREATE TRIGGER
CREATE TYPE
CREATE VIEW
CREATE SEQUENCE
CREATE SYNONYM
QUERY REWRITE
Der Default-Tablespace ist frei waumlhlbar Der Benutzer braucht das Recht QUOTA UNLIMITED auf den Tablespace von BALVI iP (Default BALVI_IP) Ein Beispiel-Create-Skript bdquooraCreate_WEB_Usersqlldquo liegt der Auslieferung bei
242 Rechte zuweisen Wenn der BALVI iP Schemabesitzer NICHT in der Tomcat-Umgebung eingetragen werden soll muss ein Oracle DBA das beiliegende GRANT-Skript bdquooraGrantIP_to_Websqlldquo ausfuumlhren um dem jeweiligen Webservice (in Tomcat verwendeten Oracle-Benutzer) die minimalen Rechte auf das Schema von BALVI iP zu gewaumlhren
Dieses Skript setzt voraus dass es von einem Oracle Administrator als bdquoUser SYSTEMldquo ausgefuumlhrt wird Lesen Sie die im Skript enthaltenen README-Kommentare und passen Sie die Benutzer (BALVI iP Schema) und (WEB-Schema) an
====================================================
DEKLARATIVER TEIL MUSS vom KUNDEN geaumlndert
bzw auf die korrekten SCHEMA-Namen angepasst
werden
Die USER-Namen muumlssen in Groszligbuchstaben
geschrieben sein sonst werden sie nicht
gefunden
====================================================
sUserBALVI_IP = BALVI_IP_SCHEMABESITZER
sUserBALVI_WEB = BALVI_WEB_SCHEMABESITZER
Release Notes BALVI Schnittstellenserver Seite 15 von 37
Neu ab Grant-Skript 158 ist die Umbenennung der Verfahrenszuordnung
Pruumlfen Sie dass die Einstellung fuumlr Ihr BundeslandVerfahren korrekt ist dort muss eine 1 fuumlr min ein Verfahren gesetzt sein Diese Einstellung befindet sich direkt unter den Schemabesitzer-Angaben
-- Verfahrensbezogene Konfiguration
-- Setzen Sie fuumlr das jeweilige Verfahren eine 1
-- BALVI Schnittstellenserver (BSS)
-- bis V266 auch BALVI Kommunikationsserver (BKS) genannt
-- generell fuumlr die meisten Verfahren guumlltig
-- Ab Version 57 entfaumlllt mit der Einfuumlhrung der
-- Schnittstelle XGewerbeanzeigen auch der separate Schalter
-- WS_BTR beide Verfahren wurden vereinheitlicht
WS_BSS = 1
Fuumlhren Sie das Skript nach der Anpassung als User SYSTEM aus um die Grants durchzufuumlhren Dieses wurde mit dem von ORACLE gelieferten Programm SQLPLUS (Command-Line) SQLPLUS Worksheet (GUI) und Oracle SQL-Developer getestet
Das Skript generiert fuumlr jedes Objekt ein SYNONYM fuumlr den WEB-USER so dass dieser auf die Objekte ohne Angabe des Owners des IP-Schemas zugreifen kann Pruumlfen Sie nach der Ausfuumlhrung dass die SYNONYMS vorhanden und VALID sind dieses kann ggf nicht der Fall sein Das Skript kann jederzeit erneut ausgefuumlhrt werden um die Grants neu zu erzeugen und bietet ebenfalls die Option alle Grants und Synonyme wieder zu entfernen Detaillierte Informationen zur Nutzung des Skripts sind als Kommentar-Block im Skript enthalten
Hinweis Die Versionsinformation ist unter den Kommentaren direkt im Skript zu finden
Zugriffsberechtigungen fuumlr Webanwendungen auf BALVI iP anlegen
===============================================================
Version 158
Guumlltig fuumlr BALVI iP 123 oder houmlher
Autor Frank Holler
SVN Revisionsinformationen
$Revision 479 $
$Date 2016-02-15 152755 +0100 (Mo 15 Feb 2016) $
================================================================
243 Wann ist die Ausfuumlhrung des Grant-Skripts erforderlich Durch das Strukturupdate von BALVI iP (z B 1240 auf 1241) werden veraltete Strukturen geloumlscht und ggf neue Views oder Tabellen angelegt Die Grant-Rechte geht dabei ggf verloren Daher ist die Ausfuumlhrung des Grant-Skripts immer dann erforderlich wenn sich die Datenbank-Struktur von BALVI iP veraumlndert
Zudem kann es fachliche Neuerungen geben welche im alten Grant-Skript nicht vorhanden sind Daher muss das Skript ggf auch ausgefuumlhrt werden wenn eine neue Schnittstelle im Schnittstellenserver bereitgestellt wurde Dieses betrifft z B auch die Bereitstellung von neuen Versionen von BALVI mobil XT
Release Notes BALVI Schnittstellenserver Seite 16 von 37
da auch dort mit einem fachlich erweiterten Client die Moumlglichkeit besteht dass neue Schnittstellen bereitgestellt und somit mehr Schreibrechte auf Tabellen benoumltigt werden
244 Welche Version des Grant-Skripts soll ich nehmen Wie der Schnittstellenserver sind auch die Grant-Skripte versioniert Neuere Versionen des Grant-Skriptes sind abwaumlrts-kompatibel und koumlnnen immer verwendet werden auch wenn in einer Schnittstellenbeschreibung eine aumlltere Version des Grant-Skriptes explizit benannt wurde
245 Kombination von mehreren Verfahren Wenn Sie zwei oder mehr Schnittstellen im BSS verwenden moumlchten ist es ggf erforderlich auch mehrere Verfahren auf aktiv (bdquo1ldquo) zu setzen
Im Beispiel nehmen wir an Sie moumlchten bdquoeFildquo und bdquoBALVI mobil XTldquo im Schnittstellenserver bereitstellen In der Beschreibung von bdquoeFildquo steht dass das Grant-Skript V36 erforderlich ist BALVI mobil XT 18 erfordert jedoch schon V56
Wenn Sie beide Verfahren betreiben ist im Grant-Skript (V56 oder houmlher) die Einstellung fuumlr beide Verfahren zu aktivieren
====================================================
DEKLARATIVER TEIL MUSS vom KUNDEN geaumlndert
bzw auf die korrekten SCHEMA-Namen angepasst
werden
Die USER-Namen muumlssen in Groszligbuchstaben
geschrieben sein sonst werden sie nicht
gefunden
====================================================
sUserBALVI_IP = BALVI_IP_SCHEMA
sUserBALVI_WEB = WEBAPP_SCHEMA
-- Verfahrensbezogene Konfiguration
-- Setzen Sie fuumlr das jeweilige Verfahren eine 1
-- BALVI Schnittstellenserver (BSS)
-- bis V266 auch BALVI Kommunikationsserver (BKS) genannt
-- generell fuumlr die meisten Verfahren guumlltig
-- Ab Version 57 entfaumlllt mit der Einfuumlhrung der
-- Schnittstelle XGewerbeanzeigen auch der separate Schalter
-- WS_BTR beide Verfahren wurden vereinheitlicht
WS_BSS = 1
-- WebService BTR (Betriebsstaumlttenregister) (NRW TH)
-- entfernt mit Update V57 setzen Sie stattdessen bei WS_BSS = 1
--WS_BTR = 0
-- Probenahme Futtermittel im Browser(BY)
WS_PROBE_FM = 0
-- Risikoorientierte Probenplanung Futtermittel ndash RIOPP FM (BY)
WS_RIOPP_FM = 0
-- Verfahren Export an EFi (Status Pilotbetrieb)
WS_EFI = 1
-- neu ab Version 35 des Grant-Skriptes ist die Moumlglichkeit den Webuser
Release Notes BALVI Schnittstellenserver Seite 17 von 37
-- fuumlr das Loumlschen der Ausgangskoumlrbe explizit zu berechtigen bzw sogar einen
-- expliziten abweichenden User festzulegen Die Konfiguration in der
-- Job-Oberflaumlche sieht vor dass man die Oracle-Datenbank-Zugangsdaten fuumlr
-- das Loumlschen einstellen muss Hier muss im Normalfall derselbe Oracle
-- Datenbankbenutzer eingetragen werden wie in der Tomcat-Verbindungs-
-- konfiguration In diesem Fall sollte wenn WS_EFI = 1 eingestellt wurde
-- ebenfalls WS_EFI_DELETE = 1 eingestellt werden
-- Alternativen
-- 1) Datenbankbenutzer aumlndern
-- Wenn bei sUserEFI_TRUNC anstatt sUserBALVI_WEB (Standard) ein anderer
-- Oracle-Benutzername angegeben wird wird das Loumlschrecht fuumlr die EFi
-- Ausgangskoumlrbe Datenbankseitig exklusiv dem angegeben Datenbankbenutzer
-- zugewiesen
-- 2) Loumlschrecht verweigern
-- Setzen Sie die Variablen WS_EFI_DELETE = 0 damit kein Loumlschrecht
-- zugeweisen wird
WS_EFI_DELETE = 0
-- Beispiel Anderer Benutzer muss in der Datenbank existieren
-- Entfernen Sie die fuumlhrenden -- vor der Variable sUserEFI_TRUNC und
-- setzen den entsprechenden Oracle-Benutzer ein
--sUserEFI_TRUNC = TEST_EFI_TRUNC
hellip
25 Konfiguration des Schnittstellen-Servers
251 Die bdquocontextxmlldquo-Parameter Die von der Servlet-Spezifikation vorgegeben Rump-Struktur sieht folgendermaszligen aus
ltxml version=10 encoding=utf-8gt
ltDOCTYPE Contextgt
ltContextgt
lt-- Kundenspezifische Einstellungen --gt
ltContextgt
Anwendungsspezifische Einstellungen werden zwischen ltContextgt und ltContextgt eingefuumlgt Alle allgemeinguumlltigen Einstellungen in der Datei bdquocontextxmlldquo werden hier erlaumlutert Kommentare finden sich auch in der von BALVI ausgelieferten Beispiel-Konfiguration
Neben den im Folgenden beschriebenen Standard-Einstellungen kann es auch vorkommen dass bundeslandspezifische Erweiterungen vorhanden sind welche nicht in dieser Dokumentation aufgefuumlhrt werden Diese funktionieren trotzdem regulaumlr weiter wenn keine expliziten Informationen zu Kompatibilitaumltsproblemen in den Release-Notes aufgefuumlhrt wurden
2511 Datenbankverbindung jdbcDataSource
Die Datenbankverbindung wird uumlber die von DBCP und dem Oracle-Treiber vorgegebenen Moumlglichkeiten realisiert Der Einsatz der orgapachetomcatjdbcpoolDataSourceFactory (automatisch verfuumlgbar ab Apache Tomcat 7 in der mitgelieferten tomcat-dbcpjar) wird als Beispiel-Konfiguration ausgeliefert
ltResource
name=jdbcDataSource
auth=Container
Release Notes BALVI Schnittstellenserver Seite 18 von 37
type=javaxsqlDataSource
factory=orgapachetomcatjdbcpoolDataSourceFactory
maxActive=10 initialSize=3
maxIdle=5
maxWait=10000
url=jdbcoraclethinBL2-ORA10-KUNDENBALVIINTERN1521ORCL
driverClassName=oraclejdbcdriverOracleDriver
username=balvi_webservice_schema
password=balvi_webservice_password
description=Oracle Datasource
maxOpenPreparedStatements=50
removeAbandoned=false
removeAbandonedTimeout=100
logAbandoned=true
jdbcInterceptors=hellip
gt
Hinweise zur Einstellung der jdbcDataSource
Standard-Einstellungen fuumlr den Datenbank-Verbindungspool
Der Verbindungspool muss entsprechend der Anzahl der zu erwartenden gleichzeitigen Benutzer konfiguriert werden Wenn Sie erwarten dass 50 Anwender gleichzeitig arbeiten stellen Sie bitte folgende Werte ein
maxActive=(50 + 10 (fuumlr System und Jobs)) = 60
maxIdle= (50 10) = 5
1 maxActive - maximale Anzahl der gleichzeitigen aktiven Anfragen an die DB
Wenn der Werte maxActive erreicht ist z B wenn mehrere Benutzer gleichzeitig einen Export starten moumlchten welcher laumlngere Zeit in Anspruch nimmt dann kann der Server die Anfrage nicht mehr bedienen und der Anwender wird abgewiesen maxActive hat zudem Auswirkungen auf die im Hintergrund ausgefuumlhrten Jobs maxActive wird daher kalkuliert mit der Anzahl der Anwender und moumlglicher Datenbank-Connections fuumlr Hintergrund-Jobs Jeder aktiv ausgefuumlhrte Job benoumltigt mindestens eine Connection nur selten wird aus Performance-Gruumlnden mehr als eine Connection waumlhrend der Job-Ausfuumlhrung verwendet Im Normalfall sollten daher 10 Connections fuumlr Hintergrundprozesse ausreichend sein
2 maxIdle - Anzahl der offenen Verbindungen auch wenn der Server im Leerlauf ist
Jede offene Verbindung im Leerlauf haumllt auf dem Datenbankserver eine Session offen Auch diese erfordert Ressourcen Wenn die Verbindungen jedoch geschlossen werden kann die Anfragezeit fuumlr eine neue Verbindung steigen da diese Verbindung erst neu ausgehandelt werden muss Die Empfehlung fuumlr den Wert bdquomaxIdleldquo ist ca 10 der Einstellung von maxActive
KeepAlive-Einstellungen fuumlr den Pool
1 validationQuery
Diese wird ausgefuumlhrt um die Verbindung zu DB zu validieren Es MUSS ein Datensatz zuruumlckgegeben werden ansonsten nimmt der DBCP an dass die Abfrage nicht erfolgreich abgesetzt wurde Achten Sie also bitte darauf dass die Abfrage nicht zu leitungsintensiv ist und genau einen Datensatz liefert
Release Notes BALVI Schnittstellenserver Seite 19 von 37
Oracle bietet dafuumlr die virtuelle Tabelle DUAL an welche sich fuumlr die ValidationQuery sehr gut eignet da die Abfrage kaum Ressourcen verbraucht
validationQuery=select 1 from dual
2 testOnBorrow - Boolscher Wert true oder false
Diese Einstellung sorgt dafuumlr dass der Pool die Verfuumlgbarkeit anhand der validationQuery pruumlft bevor
die DB-Verbindung an die Anwendung ausgeliehen wird Empfehlung
testOnBorrow=true
3 testWhileIdle - Boolscher Wert true oder false
Diese Einstellung ist hilfreich wenn zwischen dem Tomcat und der DB eine Firewall mit Stateful
Packet Inspection verwendet wird Nach laumlngerer Inaktivitaumlt wird normalerweise durch die Firewall die
DB-Verbindung geschlossen Dieses loumlst dann beim Ausleihen der Verbindung eine Fehlermeldung im
Protokoll aus 2012-08-16 165418720 WARN [http-0000-8080-8]
[orgspringframeworkjdbcsupportSQLErrorCodesFactory] Error while extracting
database product name - falling back to empty error codes
orgspringframeworkjdbcsupportMetaDataAccessException Error while extracting
DatabaseMetaData nested exception is javasqlSQLRecoverableException Getrennte
Verbindung Um dieses Problem zu beheben sollte die Option testWhileIdle=true eingestellt werden
testWhileIdle=true
Damit diese weiszlig wie oft eine Pruumlfung durchgefuumlhrt werden muss sind jedoch noch zusaumltzliche Angaben erforderlich welche fuumlr die Einstellung der Zeit zusaumltzlich gesetzt werden muumlssen
a) minEvictableIdleTimeMillis - Long in Millisekunden
Min Zeit wie lange eine DB-Verbindung im Leerlauf ist bevor diese zur Pruumlfung
gekennzeichnet wird Dieses haumlngt stark von der Einstellung der Firewall ab Wenn Sie eine
sehr restriktive Firewall haben kann es sein dass diese die Verbindung nach wenigen
Minuten Leerlauf trennt Stellen Sie den Wert immer so ein dass dieser unter der Leerlaufzeit
der Firewall liegt empfohlen 300000 entspricht 300 Sek = 5 min
minEvictableIdleTimeMillis=300000
b) timeBetweenEvictionRunsMillis - Long in Millisekunden
Der Pruumlflauf startet in der Default-Konfiguration alle 1800000 Millisekunden = 30 Min n als
zu Pruumlfen markierte Verbindungen werden in einem Pruumlflauf getestet n wird bestimmt durch
die Einstellung numTestsPerEvictionRun Empfehlung Stellen Sie den Wert auf alle 15 Min
ein
timeBetweenEvictionRunsMillis=900000
Release Notes BALVI Schnittstellenserver Seite 20 von 37
c) numTestsPerEvictionRun - Integer
Wie viele Verbindungen sollen getestet werden waumlhrend der Pruumlflauf ausgefuumlhrt wird Im
Normalfall sollte die Anzahl der zu testenden Verbindungen nicht zu hoch eingestellt werden
Der Default ist 3 Wenn Sie houmlhere Sicherheit haben wollen dass keine bdquototenldquo
Datenbankverbindungen bestehen bleiben erhoumlhen Sie den Wert auf max bdquo(maxActive ndash
maxIdle) 2ldquo Wenn Ihnen 3 ausreichend erscheint muss der Wert nicht gesetzt sein dann
wird der Default verwendet
Beispiel numTestsPerEvictionRun=10
4 Interceptors konfigurieren Neu ergaumlnzt wurde die Moumlglichkeit spezielle bdquoInterceptorsldquo zu konfigurieren die ermoumlglichen das Verhalten des Pools zu steuern Wichtig hierbei ist dass die Angabe von Werten auf real existierende Java-Klassen erfolgt die im Classpath des Tomcat vorhanden sind Groszlig-und-Kleinschreibung ist zu beachten Folgende Default-Einstellung hat BALVI fuumlr den BSS festgelegt jdbcInterceptors=
orgapachetomcatjdbcpoolinterceptorConnectionState
orgapachetomcatjdbcpoolinterceptorStatementFinalizer
orgapachetomcatjdbcpoolinterceptorResetAbandonedTimer
Details zu den verwendeten Interceptor-Einstellungen finden Sie in der Tomcat-Dokumentation3
3 httptomcatapacheorgtomcat-80-docjdbc-poolhtmlJDBC_interceptors
Release Notes BALVI Schnittstellenserver Seite 21 von 37
2512 Datenbank-Zugangsdaten verschluumlsseln
Die Verschluumlsselung fuumlr die Datenbank-Verbindung (bdquoEncrypted Datasourceldquo) ist eine Ableitung der Bibliothek Apache-Common-DBCP-14 und daher nicht mehr mit Java 8 kompatibel Die Einrichtung der Verschluumlsselung wird daher mit der Auslieferung des BSS 30 nicht mehr angeboten
2513 Active-Directory-Authentifizierung
Uumlber die folgenden Parameter wird der Zugriff des Schnittstellen-Servers auf einen Microsoft Active Directory Domain-Controller konfiguriert
ldquoldapServerAddressrdquo
Syntax PROTOKOLLIP-Adresse oder DNS-NamePORT
ltEnvironment
name=ldapServerAddress
value=ldapbl2-dc02balviintern389
type=javalangString
override=true
gt
Als Protokoll besteht auch die Moumlglichkeit ldaps (LDAP+SSL) wenn der Domain-Controller entsprechend konfiguriert wurde Im Java Truststore muss dann das Zertifikat der CA vorhanden sein welche das Zertifikat des Domain-Controllers signiert hat Zudem darf bei ldaps keine IP-Adresse verwendet werden es muss der DNS-Name des Server-Zertifikats eingetragen sein Ansonsten gibt es beim Verbinden eine Sicherheits-Exception
lt-- SSL-Beispiel
ltEnvironment
name=ldapServerAddress
value=ldapsbl2-dc02balviintern636
type=javalangString
override=true
gt
--gt
bdquoldapBaseDnrdquo
LDAP-Suchpfad fuumlr die Domain-Basis Diese muss der LDAP-Syntax fuumlr den Domain-Suffix entsprechen
Syntax DC=SERVERDC=ROOTDN
ltEnvironment
name=ldapBaseDn
value=DC=BALVIDC=INTERN
type=javalangString
override=true
gt
Release Notes BALVI Schnittstellenserver Seite 22 von 37
bdquowebLoginUseActiveDirectoryAuthenticationrdquo
Die Authentifizierung in der Browser-Oberflaumlche kann uumlber die Active-Directory-Authentifizierung erfolgen In der ersten Version ist nur die Protokoll-Auswertung moumlglich wenn der ADMIN sich anmeldet Dieser hat normalerweise niemals AD-Kennungen zugeordnet BALVI empfiehlt diese Einstellung auf bdquofalseldquo zu belassen Webservices welche uumlber SOAPREST zugreifen koumlnnen die Active-Directory-Authentifizierung trotzdem verwenden
ltEnvironment
name=webLoginUseActiveDirectoryAuthentication
value=false
type=javalangBoolean
override=true
gt
ldquoldapDaysBeforeExpirationNotificationrdquo
Die Passwort-Aumlnderung im Active-Directory uumlber die Browser-Oberflaumlche ist in der ersten Version noch nicht implementiert der Parameter wird bislang nicht ausgewertet
ltEnvironment
name=ldapDaysBeforeExpirationNotification
value=14
type=javalangInteger
override=true
gt
2514 Statement-Protokollierung in BALVI iP
Diese Option aktiviert die Lese- und Aumlnderungsprotokollierung fuumlr BALVI iP Standard ist bdquofalseldquo und wird fuumlr alle Kunden empfohlen solange keine speziellen Datenbank-Jobs eingerichtet wurden welche zeitgesteuert die Protokolleintraumlge wieder loumlschen Fuumlr Bayern wurde ein spezielles Konzept zur Leseprotokollierung entworfen Wenn Sie mehr daruumlber erfahren moumlchten kontaktieren Sie bitte die BALVI GmbH
ltEnvironment
name=enableSqlStatementMonitoring
value=true
type=javalangBoolean
override=true
gt
Beachten Sie dass diese Option massive INSERT-Statements in BALVI iP in die Tabelle VIS_D92 ausfuumlhrt Jedes abgesetzte SQL-Statement wird dabei vollstaumlndig protokolliert Dieses erzeugt eine sehr hohe INSERT-Last und in der Folge auch erhoumlhte Redolog-Switches und COMMIT-Transaktionen
Optional Aktivieren der INSERT + APPEND - Logik
Beachten Sie bitte die Hinweise von Oracle zum Hint + APPEND
Release Notes BALVI Schnittstellenserver Seite 23 von 37
Wenn Sie dieses Verhalten aktivieren moumlchten ergaumlnzen Sie bitte den folgenden Environment-Parameter
ltEnvironment
name=statementMonitoringactivateAppendMode
value=true
type=javalangBoolean
override=true
gt
2515 Einstellungen fuumlr BALVI mobil XT (bzw den bdquopartitionedExportldquo)
Diese Logik des FIFO-Buffers wurde so konzipiert dass dem Rechenzentrum diverse Einstellmoumlglichkeiten uumlber die Datei bdquocontextxmlldquo zur Verfuumlgung stehen um die Steuerung des FIFO-Puffers zu beeinflussen
Schematische Darstellung des FIFO-Puffers
Das ermoumlglicht es z B dem BALVI mobil XT Client (14 oder houmlher) den aktiven Block abzuholen und dies beim Fehler bis zu 10-mal zu wiederholen Sobald der Block [001] erfolgreich beim Client angekommen ist und dieser den naumlchsten Block anfragt wird der Block [001] verworfen wird Der Server fuumlllt dann im Hintergrund den frei gewordenen Block wieder waumlhrend der Client den Block [002] abholt
Die Groumlszlige und Anzahl der vorgecachten Bloumlcke kann uumlber die folgenden Einstellungen in der Datei bdquocontextxmlldquo definiert werden
ltEnvironment
name=partitionedExportmaxBufferedPartitions
value=3 type=javalangInteger override=true
gt
ltEnvironment
name=partitionedExportpartitionSize
value=256000 type=javalangInteger override=true
gt
Die Einstellung partitionedExportmaxBufferedPartitions ist dabei die Anzahl der vorgecachten Bloumlcke mindestens muss 2 angegeben werden Der Puffercache wird ausschlieszliglich im RAM der JVM aufgebaut es wird folglich mehr Arbeitsspeicher verwendet Dieser Arbeitsspeicher muss je gleichzeitiger Session auf dem Server bereitgestellt werden die Default-Einstellung mit 3 Partitionen a 256 KB + dem aktiven Puffer erfordern 1 MB RAM je aktiven Anwender
Aktiv
er
Puffe
r
[001] Vorg
ecac
hter
Bl
ock
[002] Vorg
ecac
hter
Bl
ock
[003]
Aktiv
er P
uffe
r
[002] Vorg
ecac
hter
Bl
ock
[003] Vorg
ecac
hter
Bl
ock
[leer]
Release Notes BALVI Schnittstellenserver Seite 24 von 37
Gleichzeitig wurde die Moumlglichkeit geschaffen dass die maximale Anzahl an gleichzeitigen Exporten durch das Rechenzentrum eingeschraumlnkt werden kann um einem OutOfMemory-Fehler vorzubeugen Die Einstellung
ltEnvironment
name=partitionedExportmaxConcurrentExports
value=10 type=javalangInteger override=true
gt
muss entsprechend der zu erwartenden gleichzeitigen Zugriffe konzipiert werden ansonsten wird der Server einen Verbindungsversuch durch die Clients ablehnen
Beachten Sie dass die folgenden Einstellungen partitionedExportmaxBufferedPartitions partitionedExportmaxConcurrentExports und partitionedExportpartitionSize gemeinsam als Rechenbasis fuumlr den RAM-Bedarf des Webservers herangezogen werden muumlssen
Folgende Faustformel sollte fuumlr die Einrichtung verwendet werden
Min 256 MB (Serverbasis) + (11 partitionedExportmaxConcurrentExports partitionedExportmaxBufferedPartitions partitionedExportpartitionSize)
Beispiel 50 gleichzeitige Anwender Blockgroumlszlige 256 KB 4 Partitionen
256 MB + (11 50 256 4) KB = 312 MB fuumlr die JVM
Empf 512 MB (Serverbasis) + (12 partitionedExportmaxConcurrentExports partitionedExportmaxBufferedPartitions partitionedExportpartitionSize)
Beispiel 50 gleichzeitige Anwender Blockgroumlszlige 256 KB 4 Partitionen
512 MB + (12 50 256 4) KB = 572 MB fuumlr die JVM
partitionedExportmaxConcurrentExports
Bestimmt die Anzahl der maximalen Export Tasks (Threads) die fuumlr partitionierte Exporte bereitgestellt werden Wenn die Anzahl uumlberschritten wird wird die entsprechende Exportanfrage abgewiesen und der Client muss zu einem spaumlteren Zeitpunkt erneut anfragen Stellen Sie diesen Wert entsprechend der zu erwartenden Benutzeranzahl ein bei 50 Anwendern also 50
Exporte oumlffnen auf der Datenbank entsprechend zur Ausfuumlhrungszeit min einen Cursor ggf fuumlr rekursive Unterabfragen kurzfristig sogar mehr Die hier eingestellte Anzahl muss mit der Anzahl von maxActive korrelieren
ltEnvironment
name=partitionedExportmaxConcurrentExports
value=10 type=javalangInteger override=true
gt
partitionedExportmaxBufferedPartitions
Bestimmt die Anzahl der Datenbloumlcke (Partitionen) die vom Server bei Abruf eines Exportes gepuffert werden Die seit Version 24 eingefuumlhrte FIFO-Puffer-Logik ermoumlglicht dass der Server schon die Ergebnisse vorpuffert so dass der Client weniger Wartezeiten bei der Anfrage nach Daten hat Diese
Release Notes BALVI Schnittstellenserver Seite 25 von 37
Puffer-Logik unterteilt den Exportdatenstrom (je Export) in mehre Bloumlcke Der Client kann nun den letzten Block neu anfordern oder den naumlchsten Block wenn der letzte Block erfolgreich verarbeitet wurde Wie viele naumlchste Bloumlcke durch den Server bereit gestellt werden entscheidet diese Einstellung Sobald kein naumlchster Block mehr bereit gestellt werden muss wird der Datenbank-Cursor geschlossen eine Erhoumlhung kann also zu einer Entlastung der aktiven DB-Verbindungen fuumlhren erhoumlht jedoch den Bedarf an RAM des Servers
Der von BALVI voreingestellte Wert ist 3
ltEnvironment
name=partitionedExportmaxBufferedPartitions
value=3 type=javalangInteger override=true
gt
partitionedExportpartitionSizeldquo
Die Groumlszlige der Datenbloumlcke (Partitionen) die an den Client uumlbermittelt werden in Bytes Wenn Sie diesen Wert zu niedrig einstellen reduziert sich die Effizienz des Caches da der Client mehr Datenbloumlcke hintereinander abrufen muss Waumlhlen Sie einen zu groszligen Wert wird die neu zu uumlbertragende Datenmenge im Fall eines Fehlers houmlher
Der von BALVI voreingestellte Wert ist 256000 (256 KB)
ltEnvironment
name=partitionedExportpartitionSize
value=256000 type=javalangInteger override=true
gt
exportTokensmaxTokenCount
Maximale Anzahl der gleichzeitig vergebenen Token die vom Server gecached werden Jede Sitzung welche einen Export durchfuumlhrt erhaumllt einen Session-Token
Wenn eine Sitzung laumlngere Zeit nicht verwendet wurde wird dieser Session-Token wieder entfernt Wenn Sie den Wert zu niedrig einstellen fuumlhrt das zu einer generellen Session-Begrenzung auch fuumlr den nicht partitionierten Export-Modus welcher ab Version 21 verfuumlgbar ist
Ist die Anzahl der Tokens houmlher als die Datenbankeinstellung maxActive kann es vorkommen dass zwar eine Session gestartet werden kann jedoch kein Datenexport zustande kommt
Der von BALVI voreingestellte Wert ist 2000
ltEnvironment
name=exportTokensmaxTokenCount
value=20 type=javalangInteger override=true
gt
exportTokenstokenExpirationInSeconds
Zeit in Sekunden die verstreichen muss bis ein Token unguumlltig wird falls darauf kein Zugriff mehr erfolgt Nach einem erfolgreichen Export wird der Token automatisch geschlossen diese Option ist fuumlr den Abbruchfall vorgesehen Der von BALVI voreingestellte Wert ist 180 (180 s = 3 min)
Release Notes BALVI Schnittstellenserver Seite 26 von 37
ltEnvironment
name=exportTokenstokenExpirationInSeconds
value=180 type=javalangInteger override=true
gt
exportTokenstokenDisposalInSeconds
Zeit in Sekunden die verstreichen muss bis ein Token das erfolgreich abgearbeitet wurde aus dem Cache geloumlscht wird Um sicher zu stellen dass der letzte Exportblock noch erfolgreich abgerufen werden kann bleibt der Token auch nach Fertigmeldung des Clients noch N Sek guumlltig
Der von BALVI voreingestellte Wert ist 60 (60 s = 1 min)
ltEnvironment
name=exportTokenstokenDisposalInSeconds
value=60 type=javalangInteger override=true
gt
2516 Job-Verwaltung fuumlr den BSS konfigurieren Aktivierung der Jobverwaltung
Bis zur Version 28 des BSS gab es den Parameter bdquoavailableServicesldquo Dieser konnte bei Bedarf aktiviert werden wenn die Jobs benoumltigt wurden
Mit Version 30 ist die Einstellung bdquoavailableServicesldquo zu entfernen und kann durch den neuen optionalen Parameter bdquoisJobServiceEnabledldquo in der Datei bdquocontextxmlldquo ersetzt werden
lt-- Neue Parameter zur Aktivierung des Job Service Ersatz fuumlr availableServices --gt
ltEnvironment
name=isJobServiceEnabled
value=true
type=javalangBoolean
override=true
gt
Ab BSS 30 wird die Jobs-Engine standardmaumlszligig aktiviert Sollte die Jobs-Engine nicht benoumltigt werden muss bdquovalueldquo der Wert bdquofalseldquo zugewiesen werden Wird bdquoisJobServiceEnabledldquo nicht eingefuumlgt sind die Jobs trotzdem standardmaumlszligig aktiv
Nach dem Neustart des Servers und erneutem Einloggen erscheint nun zusaumltzlich der Menuumlpunkt bdquoJobsldquo
bdquopasswordKeyldquo fuumlr Jobs
In der Job-Logik wird ein von BALVI definierter Standard-Schluumlssel fuumlr die Ablagen von schuumltzenswerten Daten z B Passwoumlrtern verwendet Diese Einstellung ermoumlglicht den BALVI-Standard zu uumlberschreiben Wenn Sie diese Einstellung aumlndern muumlssen jedoch alle bislang verschluumlsselten Job-Parameter neu verschluumlsselt werden
ltEnvironment
name=javacompenvjobspasswordKey
value=MeinHochsicheresNeuesPasswort
type=javalangString
Release Notes BALVI Schnittstellenserver Seite 27 von 37
override=true
gt
bdquoJob ID enableddisabledldquo (Deprecated ersetzt ab 28 durch das bdquoBindenldquo von Jobs)
Sondereinstellungen fuumlr die Job-Verwaltung Da alle Jobs in einer Datenbank administriert werden jedoch ggf verteilt auf mehreren Tomcat-Servern ausgefuumlhrt werden sollen besteht hier die Option Jobs fuumlr die aktuelle Tomcat-Instanz separat zu deaktivieren
Die Einstellung ID koumlnnte z B folgendermaszligen aussehen javacompenvjobsC0DB58D8D52C4BBC966D1DC788A4EF8Benabled
Fuumlr weitere Fragen zu dieser Einstellung kontaktieren Sie bitte die BALVI GmbH
ltEnvironment
name=javacompenvjobsIDenabled
value=false
type=javalangBoolean
override=true
gt
2517 Weitere optionale Parameter
Es ist fuumlr diverse einzelne Schnittstellen ggf erforderlich Einstellungen in der Datei bdquocontextxmlldquo zu ergaumlnzen Hinweise zu diesen Parametern sind dann in dem der Schnittstelle beiliegenden Dokument enthalten Das gilt z B fuumlr die Schnittstelle bdquoXGewerbeanzeigenldquo
26 Logging mit logback Das Logging wurde komplett uumlberarbeitet Statt bdquoLog4Jldquo wird jetzt bdquologbackldquo4 benutzt Ab BSS 30 ist es zwingend notwendig die Einstellung vorzunehmen um das Logging der Anwendung zu steuern
Migration Ergaumlnzen Sie die neue Einstellung bdquologgingconfigldquo
lt-- Neue Paramter zur Angabe der Logback Config Ersatz fuumlr log4jConfigLocation --gt
ltEnvironment
name=loggingconfig
value=$catalinabaseconflogback-bssxml
type=javalangString
override=true
gt
Nach wie vor steht es Ihnen frei die Logging-Konfiguration eigenstaumlndig anzupassen
Wenn Sie jedoch dieselbe WAR in einer Tomcat-Instanz unter mehreren Context-Namen betreiben wuumlrden beide dieselbe Logging-Konfiguration verwenden so dass alle Protokolleintraumlge in einer Log-Datei aus
4 httplogbackqoschmanualappendershtml
Release Notes BALVI Schnittstellenserver Seite 28 von 37
mehreren Webanwendungen generiert werden Aumlndern Sie den Namen der Logging-Konfiguration entsprechend ab um fuumlr jede Anwendung eine spezifische Logging-Einstellung vornehmen zu koumlnnen
27 Tocmat Optional Suche im bdquoKlassenpfadldquo um den
Ordner bdquoconfldquo erweitern Die Suche nach Dateien uumlber bdquoclasspathldquo setzt voraus dass die Ordner- und Dateinamen im Apache Tomcat bekannt gegeben werden Der Klassenpfad kann in der Datei bdquocatalinapropertiesldquo angepasst werden Wenn Sie dort unter commonloader die folgenden Werte ergaumlnzen kann eine Datei auch im Ordner conf abgelegt werden damit Apache Tomcat diese findet Ansonsten muss die Datei im Ordner lib abgelegt werden
commonloader=$catalinabaseconf$catalinahomeconf
3 Die neue Browser-Oberflaumlche Der BALVI Schnittstellenserver hat seit Version 25 neben der Protokollierung auch die Moumlglichkeit Job-Konfigurationen zu pflegen Der Login ist nur fuumlr einen in BALVI iP eingetragenen ADMIN (z B Benutzer bdquoSYSTEMADMINldquo) mit dem in BALVI iP hinterlegten Passwort moumlglich Zur Anmeldung muss immer [SYSTEMBenutzername] im Feld Benutzer angegeben werden ansonsten schlaumlgt die Anmeldung fehl Bitte achten Sie darauf dass der bdquoldquo (Slash) und nicht der bdquoldquo (Backslash) verwendet werden muss
31 Server-Protokoll Um das Server-Protokoll anzuzeigen waumlhlen Sie den entsprechenden Menuumlpunkt Dort haben Sie seit BSS 26 die Moumlglichkeit uumlber alle Spalten der Protokolle nach Informationen zu suchen
Seit BSS 31 gibt es die Moumlglichkeit Verfahren in bdquoKopfsaumltzeldquo und bdquoDetailsaumltzeldquo zu unterteilen Wurde das Verfahren entsprechend konfiguriert (wie z B bei der Schnittstelle bdquoXGewerbeanzeigenldquo) dann wird im Protokoll-Kopfsatz nur der Start und das Ende der Ausfuumlhrung in der Liste angezeigt Erst bei einem Klick auf bdquoInformationenldquo wird die Liste aller Detailsaumltze angezeigt die im Durchlauf erzeugt wurden
Release Notes BALVI Schnittstellenserver Seite 29 von 37
Verfahren
Die Liste der verfuumlgbaren Verfahren die bei Ihnen im System installiert sind ZB
BEFUNDEhellip Schnittstelle Befunde LM FM oder TS
PROBEhellip Schnittstelle zum Export von Proben an Labore ebenfalls Spezifisch fuumlr einzelne Fachbereiche
MOBILXT Protokolle der BALVI Mobil XT Synchronisation
WEB Allgemeine nicht spezifizierte Protokolle hierunter ist bislang auch die eFi-Protokollierung zu finden
WEB_I0802 Protokolle zur Schnittstelle BALVI iP LIMS (Lebensmittelproben)
XGEWERBE Schnittstelle XGewerbeanzeigen
Klicken Sie auf die Schaltflaumlche so besteht bei den neuen Protokolldatensaumltzen die Moumlglichkeit Detail-Informationen zum Protokollsatz zu erhalten
Release Notes BALVI Schnittstellenserver Seite 30 von 37
Seit BSS 30x ist die Anzeige der Protokolle ebenfalls farblich abgesetzt so dass Protokolleintraumlge mit Fehlern hellrot und Warnungen hellgelb hinterlegt werden
32 Jobs Mit einem Klick auf den Menuumlpunkt Jobs rufen Sie die Oberflaumlche fuumlr die Job-Konfiguration auf Daraufhin werden alle Jobs aufgelistet die fuumlr den BSS freigegeben sind Hier koumlnnen Sie Einstellungen an den Jobs vornehmen und die Jobs aktivieren bzw deaktivieren Die Beschreibungen bzw Einstellungsmoumlglichkeiten fuumlr den jeweiligen SST-Job sind nicht Bestandteil dieser Dokumentation
33 Log-Ausgaben Uumlber den Menuumlpunkt Log-Ausgaben koumlnnen Sie die Ausgabe der Protokolleintraumlge in Echtzeit beobachten
Release Notes BALVI Schnittstellenserver Seite 31 von 37
Starten Sie die Echtzeit-Protokollierung indem Sie auf die Schaltflaumlche mit dem Symbol bdquoPlayldquo (Dreieck) klicken unterbrechen Sie die Ausgabe indem Sie die auf Schaltflaumlche mit dem Symbol bdquoPauseldquo (zwei Balken) klicken
Klicken Sie auf die Schaltflaumlche bdquoAktualisierenldquo (zwei Pfeile) um die neuesten Protokolleintraumlge angezeigt zu bekommen
Klicken Sie auf das Symbol mit dem Papierkorb um die letzten Protokollmeldungen in der Anzeige zu loumlschen
Die Daten in den Protokolldateien auf der Festplatte des Servers sind davon nicht betroffen
Uumlber das Symbol bdquoLogging anpassenldquo (Schraubenschluumlssel) koumlnnen Sie die Ausgabe der Daten im Echtzeitfenster und in den Protokolldateien aumlndern jedoch ist diese Einstellung nur temporaumlr Die Standardeinstellungen koumlnnen ausschlieszliglich uumlber die Anpassung der Datei bdquologback-bssxmlldquo im Konfigurationsverzeichnis des Servers selbst geaumlndert werden
Release Notes BALVI Schnittstellenserver Seite 32 von 37
In der Logging-Parameter Konfiguration koumlnnen Sie verschiedene Parameter einstellen und uumlber die Schaltflaumlche bdquoAnwendenldquo dann sofort im Echtzeitprotokoll sehen Welche Einstellungen moumlglich sind erfahren Sie wenn es eine akute Fehlersituation gibt die detailliertere Ausgaben im Protokoll erfordert
Warnung Wenn Sie den Log-Level fuumlr ROOT oder eine andere Klasse auf TRACE einstellen werden sehr viele Protokollausgaben generiert die auch dazu fuumlhren koumlnnen dass der Server sehr langsam wird oder die Festplatte des Servers zulaumluft wenn fuumlr das Logging kein Dateilimit konfiguriert wurde
34 LogoutAbmeldung vom System Zum Abmelden waumlhlen Sie oben rechts das Kontextmenuuml
35 Cache loumlschen Der Cache wird in der Regel automatisch geloumlscht Wenn Sie jedoch gerade in BALVI iP eine Aumlnderung an den Schnittstellen eingespielt haben und moumlchten dass diese sofort wirksam wird kann die Funktion bdquoCache loumlschenldquo dazu verwendet werden dass der BALVI Schnittstellenserver die Einstellungen bei der naumlchsten Anfrage neu einliest
Release Notes BALVI Schnittstellenserver Seite 33 von 37
Release Notes BALVI Schnittstellenserver Seite 34 von 37
4 Einrichtung in BALVI iP Um die Verfahren fuumlr den BALVI Schnittstellenserver fuumlr Anwender freizuschalten wird das Objekt bdquoSystemeinstellungenldquo oder bdquoMandanten- und Benutzereinstellungenldquo verwendet Die Anpassung ist je Verfahren moumlglich so kann in BALVI iP fuumlr den Zugriff durch den BALVI Schnittstellenserver ein Benutzer bdquoAldquo am Verfahren bdquoMobilldquo berechtigt werden ein Benutzer bdquoBldquo nur am Verfahren bdquoSLA_FLESHldquo usw Die Logik ist jedoch einheitlich Je Verfahren wird durch BALVI eine Verfahrensgruppe mit dem Verfahrensnamen angelegt und mit den entsprechenden Einstellungen vorkonfiguriert welche durch das Verfahren erforderlich sind Dabei kann die Komplexitaumlt der Einstellungen variieren wie z B an den zu Version 23 verfuumlgbaren Verfahren bdquoMobilldquo und bdquoSLA_Fleshldquo ersichtlich wird
Im Verfahren BALVI Mobil sind diverse Anpassungen moumlglich welche je Bundesland oder eingesetzter Import- und Export-Variante durch den BALVI Schnittstellenserver bei der Bearbeitung von Anfragen gepruumlft werden siehe Punkt 3 Abb Mobil-Einstellung in BALVI iP
Abb Mobil-Einstellung in BALVI iP
Alle Verfahren verwenden jedoch die regulaumlre Benutzerverwaltung von BALVI iP Ein Benutzer ohne Passwort gilt fuumlr BALVI iP als gesperrt was fuumlr das Login bedeutet dass der Anwender sich nur uumlber die Active-Directory-Authentifizierung anmelden kann Ist das nicht moumlglich (bzw nicht konfiguriert) kann der Anwender sich weder in BALVI iP noch uumlber die Webservice-Schnittstelle authentifizieren
Fuumlr Dienste-Schnittstellen welche keine persoumlnliche Authentifizierung durch einen Anwender erfordern wird empfohlen einen separaten Benutzer in der Benutzerverwaltung anzulegen und ein sicheres Kennwort zu vergeben Das Anlegen von zusaumltzlichen Benutzern gilt nicht fuumlr BALVI mobil XT da beim Holen und Uumlbermitteln von Daten jeder Benutzer auch ein fachlich konfigurierter Anwender innerhalb von BALVI iP ist und die Anwendungsoberflaumlche ebenfalls zur Erfassung von Daten verwendet
Unter Punkt 2 der Abb Mobil-Einstellung in BALVI iP wird ein modales Fenster geoumlffnet (Abb BALVI mobil Benutzerverwaltung) Innerhalb dieses modalen Fensters werden mandantenweise die Benutzer fuumlr BALVI
Release Notes BALVI Schnittstellenserver Seite 35 von 37
mobil und den jeweiligen Fachbereich festgelegt Dabei ist es wichtig dass man die Haken bdquoAktiv fuumlr hellipldquo bei bdquohellip mobilldquo und bei einem Fachbereich (bdquohellip LMldquo bdquohellip FMldquo usw) setzt weil sonst uumlber den BALVI Schnittstellenserver keine Kommunikation mit BALVI iP moumlglich ist
Abb BALVI mobil Benutzerverwaltung
Alternativ zur Passwort-Authentifizierung wird wie beschrieben auch die Active-Directory-Authentifizierung angeboten Dazu muss der BALVI iP-Anwender uumlber die Schaltflaumlche bdquoDomaumlnen-Benutzer zuordnenldquo mit dem Active Directory verknuumlpft werden
Nur wenn die Active-Directory-Konfigurationen in BALVI iP und im BALVI Schnittstellenserver auf dieselbe Domaumlne verweisen sind die Domaumlnen-Zuordnung und die Active-Directory-Authentifizierung (z B uumlber BALVI mobil XT) moumlglich
Release Notes BALVI Schnittstellenserver Seite 36 von 37
5 Bekannte Probleme und Loumlsungen
51 ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner Bei der Job-Bearbeitung tritt folgender Fehler auf ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner
Behebung
Fuumlhren Sie das beiliegende IP-Patch (UPDATEexe) aus bevor Sie das WAR austauschen
52 Server startet nicht Sie finden folgende Zeilen im Protokoll (catalinaout oder bsslog)
ERROR [localhost-startStop-1] [IdentityServiceImpl] serverID must not be empty
ERROR [localhost-startStop-1] [ContextLoader] Context initialization failed
Behebung
Setzen Sie die Umgebungsvariable ldquoserverIDrdquo in der Datei bdquocontextxmlldquo
53 ORA-00942 table or view does not exist In vielen Faumlllen wird der Fehler ldquoTabelle oder View nicht vorhandenrdquo ausgeworfen (Java-Protokoll im Ordner logs von Apache Tomcat) wenn eine neue Schnittstelle eingerichtet oder ein neues BALVI iP Release bzw Update eingespielt wurde ohne anschlieszligend das aktuelle GRANT-Skript auszufuumlhren
Behebung
Fuumlhren Sie das GRANT-Skript erneut aus
54 ORA-0406x bdquoBestehender Paketstatus wurde aufgehobenldquo
ORA-04061 Bestehender Status von package body ABCXYZ wurde annulliert
ORA-04065 Ausfuumlhrung nicht erfolgreich package body ABCXYZ wurde geaumlndert oder geloumlscht
Release Notes BALVI Schnittstellenserver Seite 37 von 37
Der Fehler tritt haumlufig ein nachdem die UPDATEexe ausgefuumlhrt und in der Ausfuumlhrungsliste ein Package aktualisiert wurde Oracle merkt sich je User-Session bestimmte Werte im Package wenn der Anwender es verwendet hat Durch einen bdquoCREATE OR REPLACE PACKAGEldquo-Befehl kann dieser Status temporaumlr aufgehoben werden Normalerweise tritt dieser Fehler nach dem Update genau einmal in jeder aktiven Session auf wenn der BSS nicht neu gestartet wird
Behebung
Starten Sie nach jedem Update den BSS neu um alle laufenden Sessions zu beenden
55 Jobs sind nicht ausfuumlhrbar
1 Ein Job wird mit dem Status bdquoNicht unterstuumltztldquo angezeigt wenn fuumlr seine Ausfuumlhrung eine houmlhere Version des BSS erforderlich ist
2 Nach dem Klonen der Datenbank von der Produktions- auf die Testumgebung erhalten alle Jobs automatisch den Status bdquoDeaktiviertldquo wenn die bdquoserverIDldquo nicht identisch ist
Beide Statusaumlnderungen sind gewollt Damit soll verhindert werden dass Jobs nach einem Serverneustart oder nach einem Update automatisch starten und dabei Fehler verursachen
Um Jobs mit dem Status bdquoNicht unterstuumltztldquo nutzen und konfigurieren zu koumlnnen ist es erforderlich den BALVI Schnittstellenserver zu aktualisieren
Deaktivierte Jobs koumlnnen Sie aktivieren indem Sie den jeweiligen Job an den aktuellen Server binden und den Haken bei bdquoAktivldquo setzen
Release Notes BALVI Schnittstellenserver Seite 2 von 37
52 Server startet nicht 36 53 ORA-00942 table or view does not exist 36 54 ORA-0406x bdquoBestehender Paketstatus wurde aufgehobenldquo 36 55 Jobs sind nicht ausfuumlhrbar 37
Release Notes BALVI Schnittstellenserver Seite 3 von 37
1 Allgemeine Hinweise
Der neue BALVI Schnittstellenserver (BSS) 32 ersetzt alle ausgelieferten Versionen
Der BSS ist ausschlieszliglich ein Zusatz-Server welcher an eine vorhandene BALVI iP Datenbank angebunden werden kann um neue automatisierte webbasierte Schnittstellen zur Verfuumlgung zu stellen
Zu diesen Schnittstellen gehoumlren bislang
BALVI mobil XT ab Version 15
Daten-Export an eFi (BVL nur fuumlr ausgewaumlhlte Test-Bundeslaumlnder)
Bidirektionale Datenaustausch-Schnittstelle zum LIMS
xDomea-konforme DMS-Web-Schnittstelle
Betriebsregister-Schnittstelle zum Abgleich von Betriebsstammdaten
TSK-Meldebogen-Schnittstelle (Sachsen)
Import-Schnittstelle XGewerbeanzeigen des BMWi gem Spez 1112
RioPP LM ndash Uumlbernahme der Probenplaumlne (NRW)
Synchronisation mit IP2-Modulen
o IP2 ndash DM ndash Duumlngemittelmodul NRW und BALVI mobil 2 (DM)
o IP2 ndash LM ndash Lebensmittelmodul (NRW Teststellung)
o IP2 ndash BTS ndash Betriebsstaumlttenmodul (NRW Teststellung)
o IP2 ndash ZDA ndash Zentrale Dokumentablage (ab BALVI iP 1249 nutzbar)
Die meisten Schnittstellen koumlnnen durch BALVI dynamisch aktualisiert und erweitert werden ohne dass dabei der Betrieb von BALVI iP beeinflusst wird In einzelnen Faumlllen ist es jedoch erforderlich den BSS nach der Aktualisierung bzw Bereitstellung einer neuen Schnittstelle neu zu starten
Da der BSS bislang als Erweiterung fuumlr BALVI iP konzipiert ist gibt es zusaumltzlich mehrere BALVI iP Patches welche in die BALVI iP Datenbank eingespielt werden muumlssen um die neuen Schnittstellen zu aktivieren bzw zu aktualisieren
Das Update des WAR auf die neue Version 320 hat folgende Grundvoraussetzungen
- BALVI iP 1240 (oder houmlher)
- Java SE 8
- Tomcat 8 (min 8030 oder neuer)
Sollten Sie noch eine aumlltere Version von BALVI iP einsetzen und aus organisatorischen Gruumlnden nicht auf 1240 oder houmlher aktualisieren koumlnnen kontaktieren Sie bitte den Support
11 Neuerungen in Version 3132 Das Update von Version 3x auf 32 beinhaltet diverse Optimierungen und Erweiterungen der ETL-Engine damit die Ausfuumlhrung von IP1-zu-IP2-Synchronisationsprozessen besser moumlglich ist Dafuumlr wurde in der
Release Notes BALVI Schnittstellenserver Seite 4 von 37
Oberflaumlche ein neuer Menuumlpunkt bdquoETL-Tasksldquo ergaumlnzt der jedoch in der Datei bdquocontextxmlldquo aktiviert werden muss
Um den Menuumlpunkt zu aktivieren ergaumlnzen Sie in der Konfiguration folgenden Parameter
lt--ETL spezifische Erweiterungen ab BSS 31 --gt
ltEnvironment
name=isEtlTaskViewEnabled
value=true
type=javalangBoolean override=true
gt
Zudem wurden die folgenden Parameter ergaumlnzt damit im Datenabgleich Performance-Tuning moumlglich ist
lt-- Timeout-Einstellungen --gt
lt-- Wartezeit in Sekunden bei Requests Standard 60 --gt
ltEnvironment
name=xmlgenrestRequestTimeoutSeconds
value=60
type=javalangInteger override=true
gt
lt-- Anzahl an angefragten Ergebnisdatensaumltzen pro Requests Standard 20 --gt
ltEnvironment
name=xmlgenmaxEntriesPerRestRequest
value=20
type=javalangInteger override=true
gt
Zudem die Ausgabe der Java-Protokolle und deren Anzeige in der Oberflaumlche uumlberarbeitet In diesem Zusammenhang wurde ermoumlglicht dass der Tomcat-Administrator die Liste der Dateitypen angibt die beim Export der LOG-Dateien gesucht und in den Download eingepackt werden sollen
lt-- Neu ab BSS 32 auf Wunsch einiger Kunden (OPTIONAL) --gt
lt-- Welche Dateierweiterungen sollen als Default
fuumlr LOG-Dateien verwendet werden (Standard log txt) --gt
ltEnvironment
name=extensionsOfLogFiles
value=log txt out gz
type=javalangString override=true
gt
Die Ausgabe der Fachprotokolle in der Oberflaumlche wurde ebenfalls uumlberarbeitet so dass nun ein Datumsfilter bdquo(Heute ndash 1 Monat)ldquo vorbelegt wurde Neu ergaumlnzt wurde die Moumlglichkeit in der Suche die Anzeige von allen Protokollsaumltzen (Standard ist bdquoNur Kopfsaumltzeldquo) wieder mit auszugeben
Release Notes BALVI Schnittstellenserver Seite 5 von 37
12 Neuerungen in Version 30 Der BSS 3x beinhaltet alle Funktionalitaumlten des BSS 28x und ist daher abwaumlrtskompatibel
Zusaumltzlich ist es ab Version 3x moumlglich Synchronisations-Jobs zu verarbeiten die mit der OpenSource ETL- Engine bdquoPentaholdquo durch BALVI entwickelt werden Damit wird der BSS auf das zukuumlnftige BALVI iP2 vorbereitet In diesem Zuge wurden diverse Funktionalitaumlten aktualisiert
Beim Update von BSS 2x auf BSS 3x muumlssen an der Datei bdquocontextxmlldquo folgende Anpassungen vorgenommen werden bevor der Server gestartet werden darf
1 Neuer Parameter isJobServiceEnabled
Der Parameter availableServices wurde durch isJobServiceEnabled ersetzt (siehe Kapitel 2516) Damit ist der Jobservice standardmaumlszligig aktiv Empfehlung Suchen Sie availableServices und entfernen Sie diese Einstellung
2 Neue Logging-Konfiguration
Zu BSS 30 wurde auf eine neue Logging-Klasse umgestellt (siehe Kapitel 26) Ersetzen Sie im Ordner conf die vorhandene Datei bdquolog4j-commserverxmlldquo durch die Datei bdquologback-bssxmlldquo um den neuen APPENDER nutzen zu koumlnnen Entfernen Sie log4jConfigLocation und fuumlgen Sie loggingconf hinzu Tragen Sie in der Datei bdquocontextxmlldquo beim neuen Parameter loggingconf den Pfad zur Datei bdquologback-bssxmlldquo ein Die Logging-Funktionalitaumlt des Servers ist davon nicht betroffen
3 Datenbank-Verbindung bdquofactoryldquo umstellen
Bis Version 28 wurde aus Kompatibilitaumltsgruumlnden zu Tomcat 6 als DBCP-Factory noch auf orgapachecommonsdbcpBasicDataSourceFactory verwiesen Ab Tomcat 7 wird jedoch empfohlen die Tomcat-eigene Umsetzung zu verwenden Aumlndern Sie dazu die Angabe factory= in der bdquojdbcDataSourceldquo auf factory=orgapachetomcatjdbcpoolDataSourceFactory Die Verwendung von commonsdhcp wird nicht mehr empfohlen da die Tomcat-spezifische Datasource orgapachetomcatjdbc diverse interne Mechanismen bereitstellt die den Datenbankzugriff aus Apache Tomcat verbessern Dazu gehoumlren die Interceptor-Einstellungen die im Beispiel von BALVI bssxmlexmaple ergaumlnzt wurden (siehe Kapitel 2511)
Release Notes BALVI Schnittstellenserver Seite 6 von 37
4 ETL-Prozesser
Neue Datenquellen ergaumlnzen
Fuumlr die Kommunikation zwischen iP2 Modulen und iP1 wird Kettle benutzt In die contextxml muss dafuumlr eine zusaumltzliche DataSource eingefuumlgt werden wenn Sie die Daten-Uumlbermittlung von IP1 an IP2 verwenden
Die jdbcKettleIP1DataSource ist im Beispiel auskommentiert verwendet derzeit jedoch immer die Zugangsdaten die Sie auch in der jdbcDataSource eingestellt haben da derzeit beide Datenbank-Verbindungen auf das angebundene BALVI iP (124x) zugreifen sollen Beachten Sie jedoch dass die jdbcKettleIP1DataSource die Einstellung type=debalvikettleKettleDataSourceSettings (nicht javaxsqlDataSource) verwendet damit diese nur und ausschlieszliglich dann geladen wird wenn die Kettle-Engine eine separate Datenbankverbindung benoumltigt Um ETL-Engine (Kettle) mitzuteilen welche DataSource das auszufuumlhrende Modul benoumltigt sind folgende Umgebungseinstellungen in die Datei bdquocontextxmlldquo einzufuumlgen
Beispiel
ltResource
name=jdbcKettleIP1DataSource
auth=Container
type=debalvikettleKettleDataSourceSettings
factory=orgapachetomcatjdbcnamingGenericNamingResourcesFactory
maxActive=3 maxIdle=2 minIdle=1 initialSize=1
gt
Kettle Bibliotheken
Da Kettle fuumlr die Ausfuumlhrung verschiedene Dateien benoumltigt muss zudem der Parameter bdquokettlePluginDirectoryldquo eingestellt werden Weisen Sie dem Wert (bdquovalue=ldquo) den Pfad zu dem Verzeichnis zu in dem die Ausfuumlhrungsdateien liegen Die erforderlichen Dateien sind Bestandteil der Auslieferung
ltEnvironment
name=kettlePluginDirectory
value=hometest_ip2_bsskettleplugins
type=javalangString
override=true
gt
13 Hinweise zum Update von aumllteren Versionen (vor 30x) Ab BSS 282 wird eine bdquoserverIDldquo erwartet Daher ist es zwingend erforderlich die vorhandene Datei bdquocontextxmlldquo zu erweitern und den neuen Environment-Parameter bdquoserverIDldquo zu ergaumlnzen
Release Notes BALVI Schnittstellenserver Seite 7 von 37
14 Nacharbeiten nach dem Update auf Version 28
(ADMIN) Sofern Sie schon aktive bdquoJobsldquo im BSS in Verwendung haben werden diese mit dem Update automatisch deaktiviert da die Jobs nun an den ausfuumlhrenden Server gebunden werden muumlssen Oumlffnen Sie dazu den Job in der Detailansicht setzen Sie den Haken hinter bdquoJob an Server bindenldquo setzen und speichern Sie die Einstellung
Der Job wird anschlieszligend in der Uumlbersicht wieder mit dem Status bdquoAktiviertldquo angezeigt Diesen Konfigurationsschritt muumlssen Sie nun jedes Mal durchfuumlhren nachdem die Datenbank von Produktion auf Test geklont wurde
15 Neuerungen in Version 28
151 Jeder Schnittstellen-Server benoumltigt eine Kennung bdquoserverIDldquo Viele Kunden nutzen den Schnittstellenserver mehrfach in Ihrer Umgebung da mehrere BALVI iP Installationen (z B Produktion und Test) in der Infrastruktur existieren
Da die Schnittstellenkonfiguration fuumlr den BSS in der Datenbank abgelegt wird kam es in manchen Faumlllen vor dass nach dem Klonen der Produktionsdatenbank auf ein Testsystem die im BSS angelegten Jobs sofort nach dem Start in der Testumgebung wieder angesprungen sind Um dieses Problem zu beseitigen muss jedem BSS ab Version 28 eine eindeutige bdquoserverIDldquo zugewiesen werden Diese Server-ID wird in der Datei bdquocontextxmlldquo hinterlegt um neutral zur Datenbank zu sein
Ist keine Environment-Variable bdquoserverIDldquo vorhanden wird der Start des BSS 28 (oder houmlher) sofort mit einer Fehlermeldung abgebrochen Im Server-Protokoll wird dabei der Fehler bdquoERROR [IdentityServiceImpl] serverID must not be emptyrdquo ausgegeben Danach kommt sofort die Meldung dass der BSS wieder heruntergefahren wird
INFO [localhost-startStop-1] [ContextCreationListener]
BALVI-Schnittstellen-Server
Version 280
hellip
ERROR [localhost-startStop-1] [IdentityServiceImpl] serverID must not be empty
ERROR [localhost-startStop-1] [ContextLoader] Context initialization failed
Um eine ldquoserverIDrdquo zu vergeben fuumlgen Sie in der Datei bdquocontextxmlldquo folgende Angabe ein
lt--
Release Notes BALVI Schnittstellenserver Seite 8 von 37
ID fuumlr den Server
Diese muss pro Schnittstellenserver eindeutig sein
Eine Aumlnderung dieser ID fuumlhrt sofort dazu dass alle
eingerichteten Server-Jobs inaktiv werden und neu mit
der Instanz gekoppelt werden muumlssen um wieder aktiviert
werden zu koumlnnen
Als value kann ein Text der max Laumlnge von 32 Zeichen
vergeben werden z B ProductionEnvNode1 fuumlr die Produktion
und TestEnvNode1 fuumlr die Testumgebung
--gt
ltEnvironment
name=serverID
value=ProductionEnvNode1
type=javalangString
override=true
gt
152 Optional ist nun eine Namensvergabe moumlglich Auf Wunsch mehrerer Kunden wurde die Option geschaffen jedem Server zusaumltzlich einen kundenspezifischen bdquoTitelldquo zu geben um die Server besser unterscheiden zu koumlnnen
lt--
Visueller Name des Servers in der Oberflaumlche
(Optional)
--gt
ltEnvironment
name=serverName
value=TIERZ Tomcat 8 Java 8 mit BALVI_TIERZXGEWETLBTR_BSS
type=javalangString
override=true
gt
Der hier angegebene Text wird in der Kopfzeile zwischen den eckigen Klammern ausgegeben
Release Notes BALVI Schnittstellenserver Seite 9 von 37
2 Einrichtungshinweise
21 Allgemeine Hinweise zum Betrieb
211 Kompatibilitaumlt zu Apache Tomcat und Java SE Der BALVI Schnittstellenserver wurde getestet und freigegeben fuumlr Apache Tomcat 8 (ab Version 8030 oder neuer) Zudem wurde die aktuellste (letzte offizielle) Version von Java SE 8 getestet und kann verwendet werden (Java SE 8u40 und neuer)
Installieren Sie stets die aktuellsten Sicherheitsupdates fuumlr Java SE 8 Beachten Sie dabei jedoch dass nicht die Aktualisierung auf eine andere Java-Version (z B Java 9) gemeint ist
Freigegebene Major-Versionen werden explizit von BALVI benannt Falls Sie beabsichtigen die Major-Version zu aumlndern pruumlfen Sie bitte die aktuellen Release Notes oder kontaktieren die BALVI Kundenbetreuung
212 Oracle Java SE Lizenzierung Java SE beinhaltet auch kostenpflichtige Funktionen fuumlr deren Nutzung Oracle Lizenzgebuumlhren fordert wenn sie bei der Entwicklung eingesetzt werden Die von BALVI gelieferte Software ist frei von den kommerziellen Teilen der Oracle Java SE nutzbar Fuumlr den Einsatz von Oracle Java SE (einschlieszliglich JDK und JRE) fallen im Rahmen der Nutzung der BALVI Software keine Lizenzkosten an
Trotzdem werden wir parallel pruumlfen ob technische Probleme bei der Umstellung auf das OpenJDK zu erkennen sind Ein einfacher Funktionstest hat im BSS 3x noch keine technischen Probleme gezeigt als wir die Laufzeitumgebung auf das OpenJDK 8U111 AMD64 (Debian) umgestellt haben Bitte haben Sie Verstaumlndnis dafuumlr dass wir keine Funktionstests fuumlr jedes Linux-Derivat durchfuumlhren koumlnnen und dass es offiziell keine Version des OpenJDK fuumlr Windows Betriebssysteme gibt
213 Einsatz von TLSSSL BALVI hat keine spezifischen Anforderungen an die Konfiguration von SSL bzw TLS Der Einsatz von TLS 12 gem der Richtlinie TR-02102-2 vom BSI ist moumlglich wenn Sie sich an die von Apache Tomcat herausgegebene Dokumentation halten Es sind keine Anpassungen des Schnittstellenservers erforderlich Daher gehen wir davon aus dass auch der BSS 28x oder aumllter in einem Apache Tomcat mit TLS 12 betrieben werden kann
Das gilt jedoch nicht fuumlr alle Clients die den Tomcat-Server ansprechen moumlchten So ist z B erst ab BALVI mobil 191958 sichergestellt dass die Protokolle TLS 11 und TLS 12 programmseitig aktiviert sind Fuumlr Details zu diesem Problem wurde ein separates Rundschreiben per E-Mail versendet
Release Notes BALVI Schnittstellenserver Seite 10 von 37
214 Nutzung von Java-Proxyeinstellungen Der BALVI Schnittstellenserver verwendet fuumlr ausgehende Verbindungen die Java-Net Einstellungen welche in der Java-Dokumentation1 beschrieben sind Falls Sie Jobs einsetzen welche ausgehenden Zugriff auf Adressen im Internet benoumltigen kann es passieren dass Sie z B eine bdquojavanetUnknownHostExceptionldquo im Protokoll finden dann muumlssen Sie ihre Proxy-Umgebung in den Java-Umgebungseinstellungen ergaumlnzen
Die folgenden Parameter sollten daher in Ihrer Umgebung gesetzt werden wenn der Zugriff auf das Internet nur uumlber einen Proxy moumlglich ist
-DproxySet=true
-DproxyHost=10111213
-DproxyPort=8888
-DhttpnonProxyHosts=domainorg|localhost|10
Starten Sie nach Aumlnderung der Einstellungen den Server neu damit die Einstellungen wirksam werden
2141 Proxy-Einstellung unter Windows (Tomcat-Dienst)
Verwenden Sie das Dienste-Konfigurationsprogramm (z B tomcat7wexe) und ergaumlnzen Sie die fehlenden Einstellungen
2142 Proxy-Einstellung unter Linux
In Linux wird in der Konfigurationsdatei (z B conftomcat7conf) die Variable bdquo$JAVA_OPTSldquo entsprechend erweitert und die Werte uumlbergeben Beachten Sie dabei dass die Variablen von Linux (bzw der Bash) gelesen werden Daher muss das bdquoPipeldquo-Zeichen bdquo|ldquo mit bdquoldquo maskiert werden ansonsten erhalten Sie bei der Verarbeitung der Umgebungsvariable bdquohttpnonProxyHostsldquo Fehlermeldungen in der Linux -Konsole welche dazu fuumlhren dass Java nicht korrekt konfiguriert werden kann
JAVA_OPTS=$JAVA_OPTS -DproxySet=true -DproxyHost=10111213 -DproxyPort=8888
JAVA_OPTS=$JAVA_OPTS -DhttpnonProxyHosts=domainorg|localhost|10
1 httpdocsoraclecomjavase8docstechnotesguidesnetpropertieshtml
Release Notes BALVI Schnittstellenserver Seite 11 von 37
215 Spracheinstellung Deutsch Es wurde festgestellt dass unter einigen Linux-Versionen die Spracheinstellung beim Starten des Apache Tomcat nicht auf eine deutsche Umgebung verweist Dieses kann technische Probleme verursachen Unter Linux sollte die Einstellung (Umgebungsvariable) entsprechend auf LANG=de_DEUTF-8 eingestellt sein
216 Datenbankverbindung Wenn Sie eine Firewall zwischen dem Oracle-Server und dem Database Connection Pool (DBCP) verwenden sollte unbedingt die bdquovalidationQueryldquo in der DBCP-Konfiguration aktiviert werden damit die Anwendung schneller freie Connections aus dem Pool erhalten kann Die Dokumentation zu den Einstellmoumlglichkeiten ist in der beiliegenden Contextxml ergaumlnzt worden
Bitte beachten Sie dass dringende empfohlen wird die bdquoFactoryldquo auf orgapachetomcatjdbcpoolDataSourceFactory anzupassen falls sie noch auf bdquoorgapachecommonsdbcpBasicDataSourceFactoryldquo eingestellt ist
217 Probleme beim Anlegen von LOB-Objekten Der BALVI Schnittstellen-Server erfordert die JDBC-Spezifikation DBCP V4 welche durch die Factory bdquoorgapachetomcatjdbcldquo ab Tomcat 7 automatisch bereitgestellt wird
Wenn die Pooling-Komponente oder der Oracle-Treiber nicht JDBC4-Kompatibel sind gibt es beim Bearbeiten von LOB-Objekten in Java diverse Exceptions z B
Servletservice() for servlet soapws threw exception
javalangAbstractMethodError
orgapachecommonsdbcpPoolingDataSource$PoolGuardConnectionWrappercreateClob()LjavasqlClob
at debalvicoreauditspyConnectionSpycreateClob(ConnectionSpyjava511)
Ursache dieses Problems ist meistens dass noch nicht auf bdquoorgapachetomcatjdbcldquo umgestellt wurde
218 Umbenennung der gelieferten WAR-Datei Das im Paket von BALVI gelieferte WAR kann jederzeit umbenannt werden (z B als ROOTwar) ohne dass dabei spezielle Einstellungen in der Datei bdquocontextxmlldquo erforderlich sind
Beachten Sie dabei jedoch dass die zum WAR zugehoumlrige Datei bdquocontextxmlldquo im Apache Tomcat immer denselben Namen erhaumllt wie das WAR z B bdquocommserverwarldquo und bdquocommserverxmlldquo Der Name ist dabei ausschlaggebend fuumlr die Zugriffs-Adresse (Context) im Apache Tomcat selbst Die Benennung des WAR in bdquocommserverwarldquo wuumlrde folgendermaszligen aufzurufen sein httpserverportcommserver
219 Server-Schnittstellen Die Uumlberarbeitung bzw Erweiterung der Export- und Importschnittstellen welche uumlber den Schnittstellenserver bereitgestellt werden ist unabhaumlngig vom Schnittstellenserver selbst Die Schnittstellen sind daher nicht Bestandteile des Schnittstellenserver und werden je Verfahren separat
Release Notes BALVI Schnittstellenserver Seite 12 von 37
ausgeliefert Ggf ist es fuumlr unterschiedliche Schnittstellen erforderlich die Grant-Rechte zu aktualisieren (Vgl bdquoWann ist die Ausfuumlhrung des Grant-Skripts erforderlichldquo)
22 Kompatibilitaumltsliste Diverse Verfahren setzen eine Mindestversion des BALVI Schnittstellenservers voraus Die Schnittstellen sind jedoch so konzipiert dass eine Aktualisierung auf eine houmlhere Version des Servers ohne Anpassung an den vorhandenen Schnittstellen jederzeit moumlglich ist
Derzeit sind folgende Mindestanforderungen gegeben
1 BALVI mobil XT 170 oder houmlher setzt BSS 265 und BALVI iP 124x voraus
2 BALVI mobil XT 183 oder houmlher setzt BSS 281 und BALVI iP 124x voraus
3 BALVI mobil 2 (DM) setzt BSS 311 und BALVI iP 124x voraus
4 Die Schnittstelle eFI setzt BSS 251 und BALVI iP 122c voraus
5 Die Schnittstelle LIMS setzt BSS 265 voraus
6 Die Schnittstelle TSK (SN) setzt BSS 265 voraus
7 Die Schnittstelle xDomea (SN) setzt BSS 265 und Java 7 voraus
8 Die Schnittstelle XGewerbeanzeigen 11 setzt BSS 281 BALVI iP 124x Java 8 mit der bdquoJava
Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy2ldquo voraus
9 Die Schnittstelle XGewerbeanzeigen 12 (ab Paket 7 Ausbaustufe 3) setzt BSS 302 BALVI iP
124x Java 8 mit der bdquoJava Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policyldquo
voraus
10 Die Schnittstelle RioPP LM (NRW) setzt BSS 303 und die ETL-Konfiguration voraus
11 Die Schnittstellen zu BALVI iP2 (Fachmodule BTS LM ZDA Stand Juni 2017) setzen BSS 32x
voraus
2 httpwwworaclecomtechnetworkjavajavasedownloadsjce8-download-2133166html
Release Notes BALVI Schnittstellenserver Seite 13 von 37
23 Erforderliche Bibliotheken fuumlr Apache Tomcat Dateiname Funktion Quelle ojdbc6jar Oracle 11gR2 Clientpaket Oracle JDBC Client fuumlr Java
16 ersetzt die bisherige Version bdquoojdbc14jarldquo Die alte Library muss auf jeden Fall entfernt werden
httpwwworaclecomtechnetworkdatabaseenterprise-editionjdbc-112010-090769html
encrypted-datasource-110-alljar
Die Library muss auf jeden Fall entfernt werden Wird derzeit nicht weiter gepflegt da kein Interesse an der Funktionalitaumlt bestand
slf4j-api-1511jar slf4j-log4j12-1511jar log4jdbc4-12beta2jar
Entfaumlllt nicht mehr erforderlich Es wird empfohlen diese zu entfernen falls diese im LIB-Verzeichnis vorhanden sein sollten
commons-dbcp-14jar commons-pool-154jar
Entfaumlllt nicht mehr erforderlich Es wird empfohlen diese zu entfernen falls diese im LIB-Verzeichnis vorhanden sein sollten
Erwartet wird stattdessen ab Tomcat7 die mitgelieferte bdquotomcat-jdbcjarldquo
log4j-1217jar (oder houmlher)
Logging-Funktionalitaumlt Apache Log4j httploggingapacheorglog4j12downloadhtml
bcprov-jdk15on-157jar (oder houmlher)
BouncyCastle Security Provider fuumlr SSLAES hellip wird ab Version 27 im Ordner bdquolibldquo des Tomcat erwartet Sollte es aus Sicherheitsgruumlnden erwuumlnscht sein eine aktuellere Version einzusetzen ist dieses idR moumlglich
httpmvnrepositorycomartifactorgbouncycastlebcprov-jdk15on157
24 Datenbank-Installation Der BALVI Schnittstellenserver benoumltigt auszligerhalb des angebundenen BALVI iP keine eigenen Tabellen Die Web-Anwendung kann im einfachsten Fall direkt auf das Schema von BALVI iP zugreifen indem der Benutzer und das Passwort des BALVI iP-Schemas in der Datei bdquocontextxmlldquo eingetragen werden (nicht empfohlen)
Sollte dies aus Sicherheitsgruumlnden nicht erwuumlnscht sein (empfohlen vom BSI und von BALVI) finden Sie im Paket ein GRANT-Skript um Zugriffsrechte vom BALVI iP Schema fuumlr den Webservice-Schema-Benutzer einzurichten
Zwischen dem Schema von BALVI iP und jeder Web-Anwendung ist dann eine Trennung moumlglich um sicherzustellen dass der Datenbank-Benutzer welcher in der Tomcat-Konfiguration fuumlr die Web-Anwendung eingetragen wird geaumlndert oder geloumlscht werden kann ohne dass die Windows-Anwendung BALVI iP davon betroffen ist Zudem vergibt das von BALVI gelieferte Grant-Skript keine Rechte zum Loumlschen von Tabellenstrukturen oder Tabelleninhalten so dass der Webservice nur festgelegte Daten aumlndern oder lesen darf Es wird empfohlen je Web-Anwendung einen eigenen Datenbank-Benutzer zu vergeben wenn Sie ein BALVI iP mit mehreren Webservices verbinden wollen
Die Moumlglichkeiten im Uumlberblick
1) Sie betreiben den Webservice mit einem eigenstaumlndigen Oracle-Benutzer In diesem Fall muss das
Grant-Skript ausgefuumlhrt werden um den Webservice-Benutzer und den BALVI iP-Benutzer
miteinander zu koppeln
2) In der Tomcat-Konfiguration wird der Oracle-Benutzer eingetragen welcher auch der BALVI iP
Schemabesitzer ist und in der bdquobalviip_conninildquo hinterlegt ist (NICHT Empfohlen) Der Webservice
Release Notes BALVI Schnittstellenserver Seite 14 von 37
hat 100 Zugriffsrechte (auch Loumlsch- oder Aumlnderungsrechte am Schema) es wird kein Grant-
Skript benoumltigt
Wenn Sie die Konfiguration 2) waumlhlen moumlchten koumlnnen Sie die folgenden Unterkapitel uumlberspringen und in Kapitel 0 bzw fortsetzen
241 Erstinstallation Datenbank-Benutzer anlegen Wenn Sie den Webservice-Benutzer vom BALVI iP Schema trennen moumlchten muss durch die DB-Administration in der Oracle-Server-Instanz wo auch BALVI iP sein Schema besitzt ein Benutzer (ggf je Web-Anwendung) angelegt werden welcher folgende Rechte benoumltigt
CONNECT
ALTER SESSION
CREATE JOB
CREATE PROCEDURE
CREATE SESSION
CREATE TABLE
CREATE TRIGGER
CREATE TYPE
CREATE VIEW
CREATE SEQUENCE
CREATE SYNONYM
QUERY REWRITE
Der Default-Tablespace ist frei waumlhlbar Der Benutzer braucht das Recht QUOTA UNLIMITED auf den Tablespace von BALVI iP (Default BALVI_IP) Ein Beispiel-Create-Skript bdquooraCreate_WEB_Usersqlldquo liegt der Auslieferung bei
242 Rechte zuweisen Wenn der BALVI iP Schemabesitzer NICHT in der Tomcat-Umgebung eingetragen werden soll muss ein Oracle DBA das beiliegende GRANT-Skript bdquooraGrantIP_to_Websqlldquo ausfuumlhren um dem jeweiligen Webservice (in Tomcat verwendeten Oracle-Benutzer) die minimalen Rechte auf das Schema von BALVI iP zu gewaumlhren
Dieses Skript setzt voraus dass es von einem Oracle Administrator als bdquoUser SYSTEMldquo ausgefuumlhrt wird Lesen Sie die im Skript enthaltenen README-Kommentare und passen Sie die Benutzer (BALVI iP Schema) und (WEB-Schema) an
====================================================
DEKLARATIVER TEIL MUSS vom KUNDEN geaumlndert
bzw auf die korrekten SCHEMA-Namen angepasst
werden
Die USER-Namen muumlssen in Groszligbuchstaben
geschrieben sein sonst werden sie nicht
gefunden
====================================================
sUserBALVI_IP = BALVI_IP_SCHEMABESITZER
sUserBALVI_WEB = BALVI_WEB_SCHEMABESITZER
Release Notes BALVI Schnittstellenserver Seite 15 von 37
Neu ab Grant-Skript 158 ist die Umbenennung der Verfahrenszuordnung
Pruumlfen Sie dass die Einstellung fuumlr Ihr BundeslandVerfahren korrekt ist dort muss eine 1 fuumlr min ein Verfahren gesetzt sein Diese Einstellung befindet sich direkt unter den Schemabesitzer-Angaben
-- Verfahrensbezogene Konfiguration
-- Setzen Sie fuumlr das jeweilige Verfahren eine 1
-- BALVI Schnittstellenserver (BSS)
-- bis V266 auch BALVI Kommunikationsserver (BKS) genannt
-- generell fuumlr die meisten Verfahren guumlltig
-- Ab Version 57 entfaumlllt mit der Einfuumlhrung der
-- Schnittstelle XGewerbeanzeigen auch der separate Schalter
-- WS_BTR beide Verfahren wurden vereinheitlicht
WS_BSS = 1
Fuumlhren Sie das Skript nach der Anpassung als User SYSTEM aus um die Grants durchzufuumlhren Dieses wurde mit dem von ORACLE gelieferten Programm SQLPLUS (Command-Line) SQLPLUS Worksheet (GUI) und Oracle SQL-Developer getestet
Das Skript generiert fuumlr jedes Objekt ein SYNONYM fuumlr den WEB-USER so dass dieser auf die Objekte ohne Angabe des Owners des IP-Schemas zugreifen kann Pruumlfen Sie nach der Ausfuumlhrung dass die SYNONYMS vorhanden und VALID sind dieses kann ggf nicht der Fall sein Das Skript kann jederzeit erneut ausgefuumlhrt werden um die Grants neu zu erzeugen und bietet ebenfalls die Option alle Grants und Synonyme wieder zu entfernen Detaillierte Informationen zur Nutzung des Skripts sind als Kommentar-Block im Skript enthalten
Hinweis Die Versionsinformation ist unter den Kommentaren direkt im Skript zu finden
Zugriffsberechtigungen fuumlr Webanwendungen auf BALVI iP anlegen
===============================================================
Version 158
Guumlltig fuumlr BALVI iP 123 oder houmlher
Autor Frank Holler
SVN Revisionsinformationen
$Revision 479 $
$Date 2016-02-15 152755 +0100 (Mo 15 Feb 2016) $
================================================================
243 Wann ist die Ausfuumlhrung des Grant-Skripts erforderlich Durch das Strukturupdate von BALVI iP (z B 1240 auf 1241) werden veraltete Strukturen geloumlscht und ggf neue Views oder Tabellen angelegt Die Grant-Rechte geht dabei ggf verloren Daher ist die Ausfuumlhrung des Grant-Skripts immer dann erforderlich wenn sich die Datenbank-Struktur von BALVI iP veraumlndert
Zudem kann es fachliche Neuerungen geben welche im alten Grant-Skript nicht vorhanden sind Daher muss das Skript ggf auch ausgefuumlhrt werden wenn eine neue Schnittstelle im Schnittstellenserver bereitgestellt wurde Dieses betrifft z B auch die Bereitstellung von neuen Versionen von BALVI mobil XT
Release Notes BALVI Schnittstellenserver Seite 16 von 37
da auch dort mit einem fachlich erweiterten Client die Moumlglichkeit besteht dass neue Schnittstellen bereitgestellt und somit mehr Schreibrechte auf Tabellen benoumltigt werden
244 Welche Version des Grant-Skripts soll ich nehmen Wie der Schnittstellenserver sind auch die Grant-Skripte versioniert Neuere Versionen des Grant-Skriptes sind abwaumlrts-kompatibel und koumlnnen immer verwendet werden auch wenn in einer Schnittstellenbeschreibung eine aumlltere Version des Grant-Skriptes explizit benannt wurde
245 Kombination von mehreren Verfahren Wenn Sie zwei oder mehr Schnittstellen im BSS verwenden moumlchten ist es ggf erforderlich auch mehrere Verfahren auf aktiv (bdquo1ldquo) zu setzen
Im Beispiel nehmen wir an Sie moumlchten bdquoeFildquo und bdquoBALVI mobil XTldquo im Schnittstellenserver bereitstellen In der Beschreibung von bdquoeFildquo steht dass das Grant-Skript V36 erforderlich ist BALVI mobil XT 18 erfordert jedoch schon V56
Wenn Sie beide Verfahren betreiben ist im Grant-Skript (V56 oder houmlher) die Einstellung fuumlr beide Verfahren zu aktivieren
====================================================
DEKLARATIVER TEIL MUSS vom KUNDEN geaumlndert
bzw auf die korrekten SCHEMA-Namen angepasst
werden
Die USER-Namen muumlssen in Groszligbuchstaben
geschrieben sein sonst werden sie nicht
gefunden
====================================================
sUserBALVI_IP = BALVI_IP_SCHEMA
sUserBALVI_WEB = WEBAPP_SCHEMA
-- Verfahrensbezogene Konfiguration
-- Setzen Sie fuumlr das jeweilige Verfahren eine 1
-- BALVI Schnittstellenserver (BSS)
-- bis V266 auch BALVI Kommunikationsserver (BKS) genannt
-- generell fuumlr die meisten Verfahren guumlltig
-- Ab Version 57 entfaumlllt mit der Einfuumlhrung der
-- Schnittstelle XGewerbeanzeigen auch der separate Schalter
-- WS_BTR beide Verfahren wurden vereinheitlicht
WS_BSS = 1
-- WebService BTR (Betriebsstaumlttenregister) (NRW TH)
-- entfernt mit Update V57 setzen Sie stattdessen bei WS_BSS = 1
--WS_BTR = 0
-- Probenahme Futtermittel im Browser(BY)
WS_PROBE_FM = 0
-- Risikoorientierte Probenplanung Futtermittel ndash RIOPP FM (BY)
WS_RIOPP_FM = 0
-- Verfahren Export an EFi (Status Pilotbetrieb)
WS_EFI = 1
-- neu ab Version 35 des Grant-Skriptes ist die Moumlglichkeit den Webuser
Release Notes BALVI Schnittstellenserver Seite 17 von 37
-- fuumlr das Loumlschen der Ausgangskoumlrbe explizit zu berechtigen bzw sogar einen
-- expliziten abweichenden User festzulegen Die Konfiguration in der
-- Job-Oberflaumlche sieht vor dass man die Oracle-Datenbank-Zugangsdaten fuumlr
-- das Loumlschen einstellen muss Hier muss im Normalfall derselbe Oracle
-- Datenbankbenutzer eingetragen werden wie in der Tomcat-Verbindungs-
-- konfiguration In diesem Fall sollte wenn WS_EFI = 1 eingestellt wurde
-- ebenfalls WS_EFI_DELETE = 1 eingestellt werden
-- Alternativen
-- 1) Datenbankbenutzer aumlndern
-- Wenn bei sUserEFI_TRUNC anstatt sUserBALVI_WEB (Standard) ein anderer
-- Oracle-Benutzername angegeben wird wird das Loumlschrecht fuumlr die EFi
-- Ausgangskoumlrbe Datenbankseitig exklusiv dem angegeben Datenbankbenutzer
-- zugewiesen
-- 2) Loumlschrecht verweigern
-- Setzen Sie die Variablen WS_EFI_DELETE = 0 damit kein Loumlschrecht
-- zugeweisen wird
WS_EFI_DELETE = 0
-- Beispiel Anderer Benutzer muss in der Datenbank existieren
-- Entfernen Sie die fuumlhrenden -- vor der Variable sUserEFI_TRUNC und
-- setzen den entsprechenden Oracle-Benutzer ein
--sUserEFI_TRUNC = TEST_EFI_TRUNC
hellip
25 Konfiguration des Schnittstellen-Servers
251 Die bdquocontextxmlldquo-Parameter Die von der Servlet-Spezifikation vorgegeben Rump-Struktur sieht folgendermaszligen aus
ltxml version=10 encoding=utf-8gt
ltDOCTYPE Contextgt
ltContextgt
lt-- Kundenspezifische Einstellungen --gt
ltContextgt
Anwendungsspezifische Einstellungen werden zwischen ltContextgt und ltContextgt eingefuumlgt Alle allgemeinguumlltigen Einstellungen in der Datei bdquocontextxmlldquo werden hier erlaumlutert Kommentare finden sich auch in der von BALVI ausgelieferten Beispiel-Konfiguration
Neben den im Folgenden beschriebenen Standard-Einstellungen kann es auch vorkommen dass bundeslandspezifische Erweiterungen vorhanden sind welche nicht in dieser Dokumentation aufgefuumlhrt werden Diese funktionieren trotzdem regulaumlr weiter wenn keine expliziten Informationen zu Kompatibilitaumltsproblemen in den Release-Notes aufgefuumlhrt wurden
2511 Datenbankverbindung jdbcDataSource
Die Datenbankverbindung wird uumlber die von DBCP und dem Oracle-Treiber vorgegebenen Moumlglichkeiten realisiert Der Einsatz der orgapachetomcatjdbcpoolDataSourceFactory (automatisch verfuumlgbar ab Apache Tomcat 7 in der mitgelieferten tomcat-dbcpjar) wird als Beispiel-Konfiguration ausgeliefert
ltResource
name=jdbcDataSource
auth=Container
Release Notes BALVI Schnittstellenserver Seite 18 von 37
type=javaxsqlDataSource
factory=orgapachetomcatjdbcpoolDataSourceFactory
maxActive=10 initialSize=3
maxIdle=5
maxWait=10000
url=jdbcoraclethinBL2-ORA10-KUNDENBALVIINTERN1521ORCL
driverClassName=oraclejdbcdriverOracleDriver
username=balvi_webservice_schema
password=balvi_webservice_password
description=Oracle Datasource
maxOpenPreparedStatements=50
removeAbandoned=false
removeAbandonedTimeout=100
logAbandoned=true
jdbcInterceptors=hellip
gt
Hinweise zur Einstellung der jdbcDataSource
Standard-Einstellungen fuumlr den Datenbank-Verbindungspool
Der Verbindungspool muss entsprechend der Anzahl der zu erwartenden gleichzeitigen Benutzer konfiguriert werden Wenn Sie erwarten dass 50 Anwender gleichzeitig arbeiten stellen Sie bitte folgende Werte ein
maxActive=(50 + 10 (fuumlr System und Jobs)) = 60
maxIdle= (50 10) = 5
1 maxActive - maximale Anzahl der gleichzeitigen aktiven Anfragen an die DB
Wenn der Werte maxActive erreicht ist z B wenn mehrere Benutzer gleichzeitig einen Export starten moumlchten welcher laumlngere Zeit in Anspruch nimmt dann kann der Server die Anfrage nicht mehr bedienen und der Anwender wird abgewiesen maxActive hat zudem Auswirkungen auf die im Hintergrund ausgefuumlhrten Jobs maxActive wird daher kalkuliert mit der Anzahl der Anwender und moumlglicher Datenbank-Connections fuumlr Hintergrund-Jobs Jeder aktiv ausgefuumlhrte Job benoumltigt mindestens eine Connection nur selten wird aus Performance-Gruumlnden mehr als eine Connection waumlhrend der Job-Ausfuumlhrung verwendet Im Normalfall sollten daher 10 Connections fuumlr Hintergrundprozesse ausreichend sein
2 maxIdle - Anzahl der offenen Verbindungen auch wenn der Server im Leerlauf ist
Jede offene Verbindung im Leerlauf haumllt auf dem Datenbankserver eine Session offen Auch diese erfordert Ressourcen Wenn die Verbindungen jedoch geschlossen werden kann die Anfragezeit fuumlr eine neue Verbindung steigen da diese Verbindung erst neu ausgehandelt werden muss Die Empfehlung fuumlr den Wert bdquomaxIdleldquo ist ca 10 der Einstellung von maxActive
KeepAlive-Einstellungen fuumlr den Pool
1 validationQuery
Diese wird ausgefuumlhrt um die Verbindung zu DB zu validieren Es MUSS ein Datensatz zuruumlckgegeben werden ansonsten nimmt der DBCP an dass die Abfrage nicht erfolgreich abgesetzt wurde Achten Sie also bitte darauf dass die Abfrage nicht zu leitungsintensiv ist und genau einen Datensatz liefert
Release Notes BALVI Schnittstellenserver Seite 19 von 37
Oracle bietet dafuumlr die virtuelle Tabelle DUAL an welche sich fuumlr die ValidationQuery sehr gut eignet da die Abfrage kaum Ressourcen verbraucht
validationQuery=select 1 from dual
2 testOnBorrow - Boolscher Wert true oder false
Diese Einstellung sorgt dafuumlr dass der Pool die Verfuumlgbarkeit anhand der validationQuery pruumlft bevor
die DB-Verbindung an die Anwendung ausgeliehen wird Empfehlung
testOnBorrow=true
3 testWhileIdle - Boolscher Wert true oder false
Diese Einstellung ist hilfreich wenn zwischen dem Tomcat und der DB eine Firewall mit Stateful
Packet Inspection verwendet wird Nach laumlngerer Inaktivitaumlt wird normalerweise durch die Firewall die
DB-Verbindung geschlossen Dieses loumlst dann beim Ausleihen der Verbindung eine Fehlermeldung im
Protokoll aus 2012-08-16 165418720 WARN [http-0000-8080-8]
[orgspringframeworkjdbcsupportSQLErrorCodesFactory] Error while extracting
database product name - falling back to empty error codes
orgspringframeworkjdbcsupportMetaDataAccessException Error while extracting
DatabaseMetaData nested exception is javasqlSQLRecoverableException Getrennte
Verbindung Um dieses Problem zu beheben sollte die Option testWhileIdle=true eingestellt werden
testWhileIdle=true
Damit diese weiszlig wie oft eine Pruumlfung durchgefuumlhrt werden muss sind jedoch noch zusaumltzliche Angaben erforderlich welche fuumlr die Einstellung der Zeit zusaumltzlich gesetzt werden muumlssen
a) minEvictableIdleTimeMillis - Long in Millisekunden
Min Zeit wie lange eine DB-Verbindung im Leerlauf ist bevor diese zur Pruumlfung
gekennzeichnet wird Dieses haumlngt stark von der Einstellung der Firewall ab Wenn Sie eine
sehr restriktive Firewall haben kann es sein dass diese die Verbindung nach wenigen
Minuten Leerlauf trennt Stellen Sie den Wert immer so ein dass dieser unter der Leerlaufzeit
der Firewall liegt empfohlen 300000 entspricht 300 Sek = 5 min
minEvictableIdleTimeMillis=300000
b) timeBetweenEvictionRunsMillis - Long in Millisekunden
Der Pruumlflauf startet in der Default-Konfiguration alle 1800000 Millisekunden = 30 Min n als
zu Pruumlfen markierte Verbindungen werden in einem Pruumlflauf getestet n wird bestimmt durch
die Einstellung numTestsPerEvictionRun Empfehlung Stellen Sie den Wert auf alle 15 Min
ein
timeBetweenEvictionRunsMillis=900000
Release Notes BALVI Schnittstellenserver Seite 20 von 37
c) numTestsPerEvictionRun - Integer
Wie viele Verbindungen sollen getestet werden waumlhrend der Pruumlflauf ausgefuumlhrt wird Im
Normalfall sollte die Anzahl der zu testenden Verbindungen nicht zu hoch eingestellt werden
Der Default ist 3 Wenn Sie houmlhere Sicherheit haben wollen dass keine bdquototenldquo
Datenbankverbindungen bestehen bleiben erhoumlhen Sie den Wert auf max bdquo(maxActive ndash
maxIdle) 2ldquo Wenn Ihnen 3 ausreichend erscheint muss der Wert nicht gesetzt sein dann
wird der Default verwendet
Beispiel numTestsPerEvictionRun=10
4 Interceptors konfigurieren Neu ergaumlnzt wurde die Moumlglichkeit spezielle bdquoInterceptorsldquo zu konfigurieren die ermoumlglichen das Verhalten des Pools zu steuern Wichtig hierbei ist dass die Angabe von Werten auf real existierende Java-Klassen erfolgt die im Classpath des Tomcat vorhanden sind Groszlig-und-Kleinschreibung ist zu beachten Folgende Default-Einstellung hat BALVI fuumlr den BSS festgelegt jdbcInterceptors=
orgapachetomcatjdbcpoolinterceptorConnectionState
orgapachetomcatjdbcpoolinterceptorStatementFinalizer
orgapachetomcatjdbcpoolinterceptorResetAbandonedTimer
Details zu den verwendeten Interceptor-Einstellungen finden Sie in der Tomcat-Dokumentation3
3 httptomcatapacheorgtomcat-80-docjdbc-poolhtmlJDBC_interceptors
Release Notes BALVI Schnittstellenserver Seite 21 von 37
2512 Datenbank-Zugangsdaten verschluumlsseln
Die Verschluumlsselung fuumlr die Datenbank-Verbindung (bdquoEncrypted Datasourceldquo) ist eine Ableitung der Bibliothek Apache-Common-DBCP-14 und daher nicht mehr mit Java 8 kompatibel Die Einrichtung der Verschluumlsselung wird daher mit der Auslieferung des BSS 30 nicht mehr angeboten
2513 Active-Directory-Authentifizierung
Uumlber die folgenden Parameter wird der Zugriff des Schnittstellen-Servers auf einen Microsoft Active Directory Domain-Controller konfiguriert
ldquoldapServerAddressrdquo
Syntax PROTOKOLLIP-Adresse oder DNS-NamePORT
ltEnvironment
name=ldapServerAddress
value=ldapbl2-dc02balviintern389
type=javalangString
override=true
gt
Als Protokoll besteht auch die Moumlglichkeit ldaps (LDAP+SSL) wenn der Domain-Controller entsprechend konfiguriert wurde Im Java Truststore muss dann das Zertifikat der CA vorhanden sein welche das Zertifikat des Domain-Controllers signiert hat Zudem darf bei ldaps keine IP-Adresse verwendet werden es muss der DNS-Name des Server-Zertifikats eingetragen sein Ansonsten gibt es beim Verbinden eine Sicherheits-Exception
lt-- SSL-Beispiel
ltEnvironment
name=ldapServerAddress
value=ldapsbl2-dc02balviintern636
type=javalangString
override=true
gt
--gt
bdquoldapBaseDnrdquo
LDAP-Suchpfad fuumlr die Domain-Basis Diese muss der LDAP-Syntax fuumlr den Domain-Suffix entsprechen
Syntax DC=SERVERDC=ROOTDN
ltEnvironment
name=ldapBaseDn
value=DC=BALVIDC=INTERN
type=javalangString
override=true
gt
Release Notes BALVI Schnittstellenserver Seite 22 von 37
bdquowebLoginUseActiveDirectoryAuthenticationrdquo
Die Authentifizierung in der Browser-Oberflaumlche kann uumlber die Active-Directory-Authentifizierung erfolgen In der ersten Version ist nur die Protokoll-Auswertung moumlglich wenn der ADMIN sich anmeldet Dieser hat normalerweise niemals AD-Kennungen zugeordnet BALVI empfiehlt diese Einstellung auf bdquofalseldquo zu belassen Webservices welche uumlber SOAPREST zugreifen koumlnnen die Active-Directory-Authentifizierung trotzdem verwenden
ltEnvironment
name=webLoginUseActiveDirectoryAuthentication
value=false
type=javalangBoolean
override=true
gt
ldquoldapDaysBeforeExpirationNotificationrdquo
Die Passwort-Aumlnderung im Active-Directory uumlber die Browser-Oberflaumlche ist in der ersten Version noch nicht implementiert der Parameter wird bislang nicht ausgewertet
ltEnvironment
name=ldapDaysBeforeExpirationNotification
value=14
type=javalangInteger
override=true
gt
2514 Statement-Protokollierung in BALVI iP
Diese Option aktiviert die Lese- und Aumlnderungsprotokollierung fuumlr BALVI iP Standard ist bdquofalseldquo und wird fuumlr alle Kunden empfohlen solange keine speziellen Datenbank-Jobs eingerichtet wurden welche zeitgesteuert die Protokolleintraumlge wieder loumlschen Fuumlr Bayern wurde ein spezielles Konzept zur Leseprotokollierung entworfen Wenn Sie mehr daruumlber erfahren moumlchten kontaktieren Sie bitte die BALVI GmbH
ltEnvironment
name=enableSqlStatementMonitoring
value=true
type=javalangBoolean
override=true
gt
Beachten Sie dass diese Option massive INSERT-Statements in BALVI iP in die Tabelle VIS_D92 ausfuumlhrt Jedes abgesetzte SQL-Statement wird dabei vollstaumlndig protokolliert Dieses erzeugt eine sehr hohe INSERT-Last und in der Folge auch erhoumlhte Redolog-Switches und COMMIT-Transaktionen
Optional Aktivieren der INSERT + APPEND - Logik
Beachten Sie bitte die Hinweise von Oracle zum Hint + APPEND
Release Notes BALVI Schnittstellenserver Seite 23 von 37
Wenn Sie dieses Verhalten aktivieren moumlchten ergaumlnzen Sie bitte den folgenden Environment-Parameter
ltEnvironment
name=statementMonitoringactivateAppendMode
value=true
type=javalangBoolean
override=true
gt
2515 Einstellungen fuumlr BALVI mobil XT (bzw den bdquopartitionedExportldquo)
Diese Logik des FIFO-Buffers wurde so konzipiert dass dem Rechenzentrum diverse Einstellmoumlglichkeiten uumlber die Datei bdquocontextxmlldquo zur Verfuumlgung stehen um die Steuerung des FIFO-Puffers zu beeinflussen
Schematische Darstellung des FIFO-Puffers
Das ermoumlglicht es z B dem BALVI mobil XT Client (14 oder houmlher) den aktiven Block abzuholen und dies beim Fehler bis zu 10-mal zu wiederholen Sobald der Block [001] erfolgreich beim Client angekommen ist und dieser den naumlchsten Block anfragt wird der Block [001] verworfen wird Der Server fuumlllt dann im Hintergrund den frei gewordenen Block wieder waumlhrend der Client den Block [002] abholt
Die Groumlszlige und Anzahl der vorgecachten Bloumlcke kann uumlber die folgenden Einstellungen in der Datei bdquocontextxmlldquo definiert werden
ltEnvironment
name=partitionedExportmaxBufferedPartitions
value=3 type=javalangInteger override=true
gt
ltEnvironment
name=partitionedExportpartitionSize
value=256000 type=javalangInteger override=true
gt
Die Einstellung partitionedExportmaxBufferedPartitions ist dabei die Anzahl der vorgecachten Bloumlcke mindestens muss 2 angegeben werden Der Puffercache wird ausschlieszliglich im RAM der JVM aufgebaut es wird folglich mehr Arbeitsspeicher verwendet Dieser Arbeitsspeicher muss je gleichzeitiger Session auf dem Server bereitgestellt werden die Default-Einstellung mit 3 Partitionen a 256 KB + dem aktiven Puffer erfordern 1 MB RAM je aktiven Anwender
Aktiv
er
Puffe
r
[001] Vorg
ecac
hter
Bl
ock
[002] Vorg
ecac
hter
Bl
ock
[003]
Aktiv
er P
uffe
r
[002] Vorg
ecac
hter
Bl
ock
[003] Vorg
ecac
hter
Bl
ock
[leer]
Release Notes BALVI Schnittstellenserver Seite 24 von 37
Gleichzeitig wurde die Moumlglichkeit geschaffen dass die maximale Anzahl an gleichzeitigen Exporten durch das Rechenzentrum eingeschraumlnkt werden kann um einem OutOfMemory-Fehler vorzubeugen Die Einstellung
ltEnvironment
name=partitionedExportmaxConcurrentExports
value=10 type=javalangInteger override=true
gt
muss entsprechend der zu erwartenden gleichzeitigen Zugriffe konzipiert werden ansonsten wird der Server einen Verbindungsversuch durch die Clients ablehnen
Beachten Sie dass die folgenden Einstellungen partitionedExportmaxBufferedPartitions partitionedExportmaxConcurrentExports und partitionedExportpartitionSize gemeinsam als Rechenbasis fuumlr den RAM-Bedarf des Webservers herangezogen werden muumlssen
Folgende Faustformel sollte fuumlr die Einrichtung verwendet werden
Min 256 MB (Serverbasis) + (11 partitionedExportmaxConcurrentExports partitionedExportmaxBufferedPartitions partitionedExportpartitionSize)
Beispiel 50 gleichzeitige Anwender Blockgroumlszlige 256 KB 4 Partitionen
256 MB + (11 50 256 4) KB = 312 MB fuumlr die JVM
Empf 512 MB (Serverbasis) + (12 partitionedExportmaxConcurrentExports partitionedExportmaxBufferedPartitions partitionedExportpartitionSize)
Beispiel 50 gleichzeitige Anwender Blockgroumlszlige 256 KB 4 Partitionen
512 MB + (12 50 256 4) KB = 572 MB fuumlr die JVM
partitionedExportmaxConcurrentExports
Bestimmt die Anzahl der maximalen Export Tasks (Threads) die fuumlr partitionierte Exporte bereitgestellt werden Wenn die Anzahl uumlberschritten wird wird die entsprechende Exportanfrage abgewiesen und der Client muss zu einem spaumlteren Zeitpunkt erneut anfragen Stellen Sie diesen Wert entsprechend der zu erwartenden Benutzeranzahl ein bei 50 Anwendern also 50
Exporte oumlffnen auf der Datenbank entsprechend zur Ausfuumlhrungszeit min einen Cursor ggf fuumlr rekursive Unterabfragen kurzfristig sogar mehr Die hier eingestellte Anzahl muss mit der Anzahl von maxActive korrelieren
ltEnvironment
name=partitionedExportmaxConcurrentExports
value=10 type=javalangInteger override=true
gt
partitionedExportmaxBufferedPartitions
Bestimmt die Anzahl der Datenbloumlcke (Partitionen) die vom Server bei Abruf eines Exportes gepuffert werden Die seit Version 24 eingefuumlhrte FIFO-Puffer-Logik ermoumlglicht dass der Server schon die Ergebnisse vorpuffert so dass der Client weniger Wartezeiten bei der Anfrage nach Daten hat Diese
Release Notes BALVI Schnittstellenserver Seite 25 von 37
Puffer-Logik unterteilt den Exportdatenstrom (je Export) in mehre Bloumlcke Der Client kann nun den letzten Block neu anfordern oder den naumlchsten Block wenn der letzte Block erfolgreich verarbeitet wurde Wie viele naumlchste Bloumlcke durch den Server bereit gestellt werden entscheidet diese Einstellung Sobald kein naumlchster Block mehr bereit gestellt werden muss wird der Datenbank-Cursor geschlossen eine Erhoumlhung kann also zu einer Entlastung der aktiven DB-Verbindungen fuumlhren erhoumlht jedoch den Bedarf an RAM des Servers
Der von BALVI voreingestellte Wert ist 3
ltEnvironment
name=partitionedExportmaxBufferedPartitions
value=3 type=javalangInteger override=true
gt
partitionedExportpartitionSizeldquo
Die Groumlszlige der Datenbloumlcke (Partitionen) die an den Client uumlbermittelt werden in Bytes Wenn Sie diesen Wert zu niedrig einstellen reduziert sich die Effizienz des Caches da der Client mehr Datenbloumlcke hintereinander abrufen muss Waumlhlen Sie einen zu groszligen Wert wird die neu zu uumlbertragende Datenmenge im Fall eines Fehlers houmlher
Der von BALVI voreingestellte Wert ist 256000 (256 KB)
ltEnvironment
name=partitionedExportpartitionSize
value=256000 type=javalangInteger override=true
gt
exportTokensmaxTokenCount
Maximale Anzahl der gleichzeitig vergebenen Token die vom Server gecached werden Jede Sitzung welche einen Export durchfuumlhrt erhaumllt einen Session-Token
Wenn eine Sitzung laumlngere Zeit nicht verwendet wurde wird dieser Session-Token wieder entfernt Wenn Sie den Wert zu niedrig einstellen fuumlhrt das zu einer generellen Session-Begrenzung auch fuumlr den nicht partitionierten Export-Modus welcher ab Version 21 verfuumlgbar ist
Ist die Anzahl der Tokens houmlher als die Datenbankeinstellung maxActive kann es vorkommen dass zwar eine Session gestartet werden kann jedoch kein Datenexport zustande kommt
Der von BALVI voreingestellte Wert ist 2000
ltEnvironment
name=exportTokensmaxTokenCount
value=20 type=javalangInteger override=true
gt
exportTokenstokenExpirationInSeconds
Zeit in Sekunden die verstreichen muss bis ein Token unguumlltig wird falls darauf kein Zugriff mehr erfolgt Nach einem erfolgreichen Export wird der Token automatisch geschlossen diese Option ist fuumlr den Abbruchfall vorgesehen Der von BALVI voreingestellte Wert ist 180 (180 s = 3 min)
Release Notes BALVI Schnittstellenserver Seite 26 von 37
ltEnvironment
name=exportTokenstokenExpirationInSeconds
value=180 type=javalangInteger override=true
gt
exportTokenstokenDisposalInSeconds
Zeit in Sekunden die verstreichen muss bis ein Token das erfolgreich abgearbeitet wurde aus dem Cache geloumlscht wird Um sicher zu stellen dass der letzte Exportblock noch erfolgreich abgerufen werden kann bleibt der Token auch nach Fertigmeldung des Clients noch N Sek guumlltig
Der von BALVI voreingestellte Wert ist 60 (60 s = 1 min)
ltEnvironment
name=exportTokenstokenDisposalInSeconds
value=60 type=javalangInteger override=true
gt
2516 Job-Verwaltung fuumlr den BSS konfigurieren Aktivierung der Jobverwaltung
Bis zur Version 28 des BSS gab es den Parameter bdquoavailableServicesldquo Dieser konnte bei Bedarf aktiviert werden wenn die Jobs benoumltigt wurden
Mit Version 30 ist die Einstellung bdquoavailableServicesldquo zu entfernen und kann durch den neuen optionalen Parameter bdquoisJobServiceEnabledldquo in der Datei bdquocontextxmlldquo ersetzt werden
lt-- Neue Parameter zur Aktivierung des Job Service Ersatz fuumlr availableServices --gt
ltEnvironment
name=isJobServiceEnabled
value=true
type=javalangBoolean
override=true
gt
Ab BSS 30 wird die Jobs-Engine standardmaumlszligig aktiviert Sollte die Jobs-Engine nicht benoumltigt werden muss bdquovalueldquo der Wert bdquofalseldquo zugewiesen werden Wird bdquoisJobServiceEnabledldquo nicht eingefuumlgt sind die Jobs trotzdem standardmaumlszligig aktiv
Nach dem Neustart des Servers und erneutem Einloggen erscheint nun zusaumltzlich der Menuumlpunkt bdquoJobsldquo
bdquopasswordKeyldquo fuumlr Jobs
In der Job-Logik wird ein von BALVI definierter Standard-Schluumlssel fuumlr die Ablagen von schuumltzenswerten Daten z B Passwoumlrtern verwendet Diese Einstellung ermoumlglicht den BALVI-Standard zu uumlberschreiben Wenn Sie diese Einstellung aumlndern muumlssen jedoch alle bislang verschluumlsselten Job-Parameter neu verschluumlsselt werden
ltEnvironment
name=javacompenvjobspasswordKey
value=MeinHochsicheresNeuesPasswort
type=javalangString
Release Notes BALVI Schnittstellenserver Seite 27 von 37
override=true
gt
bdquoJob ID enableddisabledldquo (Deprecated ersetzt ab 28 durch das bdquoBindenldquo von Jobs)
Sondereinstellungen fuumlr die Job-Verwaltung Da alle Jobs in einer Datenbank administriert werden jedoch ggf verteilt auf mehreren Tomcat-Servern ausgefuumlhrt werden sollen besteht hier die Option Jobs fuumlr die aktuelle Tomcat-Instanz separat zu deaktivieren
Die Einstellung ID koumlnnte z B folgendermaszligen aussehen javacompenvjobsC0DB58D8D52C4BBC966D1DC788A4EF8Benabled
Fuumlr weitere Fragen zu dieser Einstellung kontaktieren Sie bitte die BALVI GmbH
ltEnvironment
name=javacompenvjobsIDenabled
value=false
type=javalangBoolean
override=true
gt
2517 Weitere optionale Parameter
Es ist fuumlr diverse einzelne Schnittstellen ggf erforderlich Einstellungen in der Datei bdquocontextxmlldquo zu ergaumlnzen Hinweise zu diesen Parametern sind dann in dem der Schnittstelle beiliegenden Dokument enthalten Das gilt z B fuumlr die Schnittstelle bdquoXGewerbeanzeigenldquo
26 Logging mit logback Das Logging wurde komplett uumlberarbeitet Statt bdquoLog4Jldquo wird jetzt bdquologbackldquo4 benutzt Ab BSS 30 ist es zwingend notwendig die Einstellung vorzunehmen um das Logging der Anwendung zu steuern
Migration Ergaumlnzen Sie die neue Einstellung bdquologgingconfigldquo
lt-- Neue Paramter zur Angabe der Logback Config Ersatz fuumlr log4jConfigLocation --gt
ltEnvironment
name=loggingconfig
value=$catalinabaseconflogback-bssxml
type=javalangString
override=true
gt
Nach wie vor steht es Ihnen frei die Logging-Konfiguration eigenstaumlndig anzupassen
Wenn Sie jedoch dieselbe WAR in einer Tomcat-Instanz unter mehreren Context-Namen betreiben wuumlrden beide dieselbe Logging-Konfiguration verwenden so dass alle Protokolleintraumlge in einer Log-Datei aus
4 httplogbackqoschmanualappendershtml
Release Notes BALVI Schnittstellenserver Seite 28 von 37
mehreren Webanwendungen generiert werden Aumlndern Sie den Namen der Logging-Konfiguration entsprechend ab um fuumlr jede Anwendung eine spezifische Logging-Einstellung vornehmen zu koumlnnen
27 Tocmat Optional Suche im bdquoKlassenpfadldquo um den
Ordner bdquoconfldquo erweitern Die Suche nach Dateien uumlber bdquoclasspathldquo setzt voraus dass die Ordner- und Dateinamen im Apache Tomcat bekannt gegeben werden Der Klassenpfad kann in der Datei bdquocatalinapropertiesldquo angepasst werden Wenn Sie dort unter commonloader die folgenden Werte ergaumlnzen kann eine Datei auch im Ordner conf abgelegt werden damit Apache Tomcat diese findet Ansonsten muss die Datei im Ordner lib abgelegt werden
commonloader=$catalinabaseconf$catalinahomeconf
3 Die neue Browser-Oberflaumlche Der BALVI Schnittstellenserver hat seit Version 25 neben der Protokollierung auch die Moumlglichkeit Job-Konfigurationen zu pflegen Der Login ist nur fuumlr einen in BALVI iP eingetragenen ADMIN (z B Benutzer bdquoSYSTEMADMINldquo) mit dem in BALVI iP hinterlegten Passwort moumlglich Zur Anmeldung muss immer [SYSTEMBenutzername] im Feld Benutzer angegeben werden ansonsten schlaumlgt die Anmeldung fehl Bitte achten Sie darauf dass der bdquoldquo (Slash) und nicht der bdquoldquo (Backslash) verwendet werden muss
31 Server-Protokoll Um das Server-Protokoll anzuzeigen waumlhlen Sie den entsprechenden Menuumlpunkt Dort haben Sie seit BSS 26 die Moumlglichkeit uumlber alle Spalten der Protokolle nach Informationen zu suchen
Seit BSS 31 gibt es die Moumlglichkeit Verfahren in bdquoKopfsaumltzeldquo und bdquoDetailsaumltzeldquo zu unterteilen Wurde das Verfahren entsprechend konfiguriert (wie z B bei der Schnittstelle bdquoXGewerbeanzeigenldquo) dann wird im Protokoll-Kopfsatz nur der Start und das Ende der Ausfuumlhrung in der Liste angezeigt Erst bei einem Klick auf bdquoInformationenldquo wird die Liste aller Detailsaumltze angezeigt die im Durchlauf erzeugt wurden
Release Notes BALVI Schnittstellenserver Seite 29 von 37
Verfahren
Die Liste der verfuumlgbaren Verfahren die bei Ihnen im System installiert sind ZB
BEFUNDEhellip Schnittstelle Befunde LM FM oder TS
PROBEhellip Schnittstelle zum Export von Proben an Labore ebenfalls Spezifisch fuumlr einzelne Fachbereiche
MOBILXT Protokolle der BALVI Mobil XT Synchronisation
WEB Allgemeine nicht spezifizierte Protokolle hierunter ist bislang auch die eFi-Protokollierung zu finden
WEB_I0802 Protokolle zur Schnittstelle BALVI iP LIMS (Lebensmittelproben)
XGEWERBE Schnittstelle XGewerbeanzeigen
Klicken Sie auf die Schaltflaumlche so besteht bei den neuen Protokolldatensaumltzen die Moumlglichkeit Detail-Informationen zum Protokollsatz zu erhalten
Release Notes BALVI Schnittstellenserver Seite 30 von 37
Seit BSS 30x ist die Anzeige der Protokolle ebenfalls farblich abgesetzt so dass Protokolleintraumlge mit Fehlern hellrot und Warnungen hellgelb hinterlegt werden
32 Jobs Mit einem Klick auf den Menuumlpunkt Jobs rufen Sie die Oberflaumlche fuumlr die Job-Konfiguration auf Daraufhin werden alle Jobs aufgelistet die fuumlr den BSS freigegeben sind Hier koumlnnen Sie Einstellungen an den Jobs vornehmen und die Jobs aktivieren bzw deaktivieren Die Beschreibungen bzw Einstellungsmoumlglichkeiten fuumlr den jeweiligen SST-Job sind nicht Bestandteil dieser Dokumentation
33 Log-Ausgaben Uumlber den Menuumlpunkt Log-Ausgaben koumlnnen Sie die Ausgabe der Protokolleintraumlge in Echtzeit beobachten
Release Notes BALVI Schnittstellenserver Seite 31 von 37
Starten Sie die Echtzeit-Protokollierung indem Sie auf die Schaltflaumlche mit dem Symbol bdquoPlayldquo (Dreieck) klicken unterbrechen Sie die Ausgabe indem Sie die auf Schaltflaumlche mit dem Symbol bdquoPauseldquo (zwei Balken) klicken
Klicken Sie auf die Schaltflaumlche bdquoAktualisierenldquo (zwei Pfeile) um die neuesten Protokolleintraumlge angezeigt zu bekommen
Klicken Sie auf das Symbol mit dem Papierkorb um die letzten Protokollmeldungen in der Anzeige zu loumlschen
Die Daten in den Protokolldateien auf der Festplatte des Servers sind davon nicht betroffen
Uumlber das Symbol bdquoLogging anpassenldquo (Schraubenschluumlssel) koumlnnen Sie die Ausgabe der Daten im Echtzeitfenster und in den Protokolldateien aumlndern jedoch ist diese Einstellung nur temporaumlr Die Standardeinstellungen koumlnnen ausschlieszliglich uumlber die Anpassung der Datei bdquologback-bssxmlldquo im Konfigurationsverzeichnis des Servers selbst geaumlndert werden
Release Notes BALVI Schnittstellenserver Seite 32 von 37
In der Logging-Parameter Konfiguration koumlnnen Sie verschiedene Parameter einstellen und uumlber die Schaltflaumlche bdquoAnwendenldquo dann sofort im Echtzeitprotokoll sehen Welche Einstellungen moumlglich sind erfahren Sie wenn es eine akute Fehlersituation gibt die detailliertere Ausgaben im Protokoll erfordert
Warnung Wenn Sie den Log-Level fuumlr ROOT oder eine andere Klasse auf TRACE einstellen werden sehr viele Protokollausgaben generiert die auch dazu fuumlhren koumlnnen dass der Server sehr langsam wird oder die Festplatte des Servers zulaumluft wenn fuumlr das Logging kein Dateilimit konfiguriert wurde
34 LogoutAbmeldung vom System Zum Abmelden waumlhlen Sie oben rechts das Kontextmenuuml
35 Cache loumlschen Der Cache wird in der Regel automatisch geloumlscht Wenn Sie jedoch gerade in BALVI iP eine Aumlnderung an den Schnittstellen eingespielt haben und moumlchten dass diese sofort wirksam wird kann die Funktion bdquoCache loumlschenldquo dazu verwendet werden dass der BALVI Schnittstellenserver die Einstellungen bei der naumlchsten Anfrage neu einliest
Release Notes BALVI Schnittstellenserver Seite 33 von 37
Release Notes BALVI Schnittstellenserver Seite 34 von 37
4 Einrichtung in BALVI iP Um die Verfahren fuumlr den BALVI Schnittstellenserver fuumlr Anwender freizuschalten wird das Objekt bdquoSystemeinstellungenldquo oder bdquoMandanten- und Benutzereinstellungenldquo verwendet Die Anpassung ist je Verfahren moumlglich so kann in BALVI iP fuumlr den Zugriff durch den BALVI Schnittstellenserver ein Benutzer bdquoAldquo am Verfahren bdquoMobilldquo berechtigt werden ein Benutzer bdquoBldquo nur am Verfahren bdquoSLA_FLESHldquo usw Die Logik ist jedoch einheitlich Je Verfahren wird durch BALVI eine Verfahrensgruppe mit dem Verfahrensnamen angelegt und mit den entsprechenden Einstellungen vorkonfiguriert welche durch das Verfahren erforderlich sind Dabei kann die Komplexitaumlt der Einstellungen variieren wie z B an den zu Version 23 verfuumlgbaren Verfahren bdquoMobilldquo und bdquoSLA_Fleshldquo ersichtlich wird
Im Verfahren BALVI Mobil sind diverse Anpassungen moumlglich welche je Bundesland oder eingesetzter Import- und Export-Variante durch den BALVI Schnittstellenserver bei der Bearbeitung von Anfragen gepruumlft werden siehe Punkt 3 Abb Mobil-Einstellung in BALVI iP
Abb Mobil-Einstellung in BALVI iP
Alle Verfahren verwenden jedoch die regulaumlre Benutzerverwaltung von BALVI iP Ein Benutzer ohne Passwort gilt fuumlr BALVI iP als gesperrt was fuumlr das Login bedeutet dass der Anwender sich nur uumlber die Active-Directory-Authentifizierung anmelden kann Ist das nicht moumlglich (bzw nicht konfiguriert) kann der Anwender sich weder in BALVI iP noch uumlber die Webservice-Schnittstelle authentifizieren
Fuumlr Dienste-Schnittstellen welche keine persoumlnliche Authentifizierung durch einen Anwender erfordern wird empfohlen einen separaten Benutzer in der Benutzerverwaltung anzulegen und ein sicheres Kennwort zu vergeben Das Anlegen von zusaumltzlichen Benutzern gilt nicht fuumlr BALVI mobil XT da beim Holen und Uumlbermitteln von Daten jeder Benutzer auch ein fachlich konfigurierter Anwender innerhalb von BALVI iP ist und die Anwendungsoberflaumlche ebenfalls zur Erfassung von Daten verwendet
Unter Punkt 2 der Abb Mobil-Einstellung in BALVI iP wird ein modales Fenster geoumlffnet (Abb BALVI mobil Benutzerverwaltung) Innerhalb dieses modalen Fensters werden mandantenweise die Benutzer fuumlr BALVI
Release Notes BALVI Schnittstellenserver Seite 35 von 37
mobil und den jeweiligen Fachbereich festgelegt Dabei ist es wichtig dass man die Haken bdquoAktiv fuumlr hellipldquo bei bdquohellip mobilldquo und bei einem Fachbereich (bdquohellip LMldquo bdquohellip FMldquo usw) setzt weil sonst uumlber den BALVI Schnittstellenserver keine Kommunikation mit BALVI iP moumlglich ist
Abb BALVI mobil Benutzerverwaltung
Alternativ zur Passwort-Authentifizierung wird wie beschrieben auch die Active-Directory-Authentifizierung angeboten Dazu muss der BALVI iP-Anwender uumlber die Schaltflaumlche bdquoDomaumlnen-Benutzer zuordnenldquo mit dem Active Directory verknuumlpft werden
Nur wenn die Active-Directory-Konfigurationen in BALVI iP und im BALVI Schnittstellenserver auf dieselbe Domaumlne verweisen sind die Domaumlnen-Zuordnung und die Active-Directory-Authentifizierung (z B uumlber BALVI mobil XT) moumlglich
Release Notes BALVI Schnittstellenserver Seite 36 von 37
5 Bekannte Probleme und Loumlsungen
51 ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner Bei der Job-Bearbeitung tritt folgender Fehler auf ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner
Behebung
Fuumlhren Sie das beiliegende IP-Patch (UPDATEexe) aus bevor Sie das WAR austauschen
52 Server startet nicht Sie finden folgende Zeilen im Protokoll (catalinaout oder bsslog)
ERROR [localhost-startStop-1] [IdentityServiceImpl] serverID must not be empty
ERROR [localhost-startStop-1] [ContextLoader] Context initialization failed
Behebung
Setzen Sie die Umgebungsvariable ldquoserverIDrdquo in der Datei bdquocontextxmlldquo
53 ORA-00942 table or view does not exist In vielen Faumlllen wird der Fehler ldquoTabelle oder View nicht vorhandenrdquo ausgeworfen (Java-Protokoll im Ordner logs von Apache Tomcat) wenn eine neue Schnittstelle eingerichtet oder ein neues BALVI iP Release bzw Update eingespielt wurde ohne anschlieszligend das aktuelle GRANT-Skript auszufuumlhren
Behebung
Fuumlhren Sie das GRANT-Skript erneut aus
54 ORA-0406x bdquoBestehender Paketstatus wurde aufgehobenldquo
ORA-04061 Bestehender Status von package body ABCXYZ wurde annulliert
ORA-04065 Ausfuumlhrung nicht erfolgreich package body ABCXYZ wurde geaumlndert oder geloumlscht
Release Notes BALVI Schnittstellenserver Seite 37 von 37
Der Fehler tritt haumlufig ein nachdem die UPDATEexe ausgefuumlhrt und in der Ausfuumlhrungsliste ein Package aktualisiert wurde Oracle merkt sich je User-Session bestimmte Werte im Package wenn der Anwender es verwendet hat Durch einen bdquoCREATE OR REPLACE PACKAGEldquo-Befehl kann dieser Status temporaumlr aufgehoben werden Normalerweise tritt dieser Fehler nach dem Update genau einmal in jeder aktiven Session auf wenn der BSS nicht neu gestartet wird
Behebung
Starten Sie nach jedem Update den BSS neu um alle laufenden Sessions zu beenden
55 Jobs sind nicht ausfuumlhrbar
1 Ein Job wird mit dem Status bdquoNicht unterstuumltztldquo angezeigt wenn fuumlr seine Ausfuumlhrung eine houmlhere Version des BSS erforderlich ist
2 Nach dem Klonen der Datenbank von der Produktions- auf die Testumgebung erhalten alle Jobs automatisch den Status bdquoDeaktiviertldquo wenn die bdquoserverIDldquo nicht identisch ist
Beide Statusaumlnderungen sind gewollt Damit soll verhindert werden dass Jobs nach einem Serverneustart oder nach einem Update automatisch starten und dabei Fehler verursachen
Um Jobs mit dem Status bdquoNicht unterstuumltztldquo nutzen und konfigurieren zu koumlnnen ist es erforderlich den BALVI Schnittstellenserver zu aktualisieren
Deaktivierte Jobs koumlnnen Sie aktivieren indem Sie den jeweiligen Job an den aktuellen Server binden und den Haken bei bdquoAktivldquo setzen
Release Notes BALVI Schnittstellenserver Seite 3 von 37
1 Allgemeine Hinweise
Der neue BALVI Schnittstellenserver (BSS) 32 ersetzt alle ausgelieferten Versionen
Der BSS ist ausschlieszliglich ein Zusatz-Server welcher an eine vorhandene BALVI iP Datenbank angebunden werden kann um neue automatisierte webbasierte Schnittstellen zur Verfuumlgung zu stellen
Zu diesen Schnittstellen gehoumlren bislang
BALVI mobil XT ab Version 15
Daten-Export an eFi (BVL nur fuumlr ausgewaumlhlte Test-Bundeslaumlnder)
Bidirektionale Datenaustausch-Schnittstelle zum LIMS
xDomea-konforme DMS-Web-Schnittstelle
Betriebsregister-Schnittstelle zum Abgleich von Betriebsstammdaten
TSK-Meldebogen-Schnittstelle (Sachsen)
Import-Schnittstelle XGewerbeanzeigen des BMWi gem Spez 1112
RioPP LM ndash Uumlbernahme der Probenplaumlne (NRW)
Synchronisation mit IP2-Modulen
o IP2 ndash DM ndash Duumlngemittelmodul NRW und BALVI mobil 2 (DM)
o IP2 ndash LM ndash Lebensmittelmodul (NRW Teststellung)
o IP2 ndash BTS ndash Betriebsstaumlttenmodul (NRW Teststellung)
o IP2 ndash ZDA ndash Zentrale Dokumentablage (ab BALVI iP 1249 nutzbar)
Die meisten Schnittstellen koumlnnen durch BALVI dynamisch aktualisiert und erweitert werden ohne dass dabei der Betrieb von BALVI iP beeinflusst wird In einzelnen Faumlllen ist es jedoch erforderlich den BSS nach der Aktualisierung bzw Bereitstellung einer neuen Schnittstelle neu zu starten
Da der BSS bislang als Erweiterung fuumlr BALVI iP konzipiert ist gibt es zusaumltzlich mehrere BALVI iP Patches welche in die BALVI iP Datenbank eingespielt werden muumlssen um die neuen Schnittstellen zu aktivieren bzw zu aktualisieren
Das Update des WAR auf die neue Version 320 hat folgende Grundvoraussetzungen
- BALVI iP 1240 (oder houmlher)
- Java SE 8
- Tomcat 8 (min 8030 oder neuer)
Sollten Sie noch eine aumlltere Version von BALVI iP einsetzen und aus organisatorischen Gruumlnden nicht auf 1240 oder houmlher aktualisieren koumlnnen kontaktieren Sie bitte den Support
11 Neuerungen in Version 3132 Das Update von Version 3x auf 32 beinhaltet diverse Optimierungen und Erweiterungen der ETL-Engine damit die Ausfuumlhrung von IP1-zu-IP2-Synchronisationsprozessen besser moumlglich ist Dafuumlr wurde in der
Release Notes BALVI Schnittstellenserver Seite 4 von 37
Oberflaumlche ein neuer Menuumlpunkt bdquoETL-Tasksldquo ergaumlnzt der jedoch in der Datei bdquocontextxmlldquo aktiviert werden muss
Um den Menuumlpunkt zu aktivieren ergaumlnzen Sie in der Konfiguration folgenden Parameter
lt--ETL spezifische Erweiterungen ab BSS 31 --gt
ltEnvironment
name=isEtlTaskViewEnabled
value=true
type=javalangBoolean override=true
gt
Zudem wurden die folgenden Parameter ergaumlnzt damit im Datenabgleich Performance-Tuning moumlglich ist
lt-- Timeout-Einstellungen --gt
lt-- Wartezeit in Sekunden bei Requests Standard 60 --gt
ltEnvironment
name=xmlgenrestRequestTimeoutSeconds
value=60
type=javalangInteger override=true
gt
lt-- Anzahl an angefragten Ergebnisdatensaumltzen pro Requests Standard 20 --gt
ltEnvironment
name=xmlgenmaxEntriesPerRestRequest
value=20
type=javalangInteger override=true
gt
Zudem die Ausgabe der Java-Protokolle und deren Anzeige in der Oberflaumlche uumlberarbeitet In diesem Zusammenhang wurde ermoumlglicht dass der Tomcat-Administrator die Liste der Dateitypen angibt die beim Export der LOG-Dateien gesucht und in den Download eingepackt werden sollen
lt-- Neu ab BSS 32 auf Wunsch einiger Kunden (OPTIONAL) --gt
lt-- Welche Dateierweiterungen sollen als Default
fuumlr LOG-Dateien verwendet werden (Standard log txt) --gt
ltEnvironment
name=extensionsOfLogFiles
value=log txt out gz
type=javalangString override=true
gt
Die Ausgabe der Fachprotokolle in der Oberflaumlche wurde ebenfalls uumlberarbeitet so dass nun ein Datumsfilter bdquo(Heute ndash 1 Monat)ldquo vorbelegt wurde Neu ergaumlnzt wurde die Moumlglichkeit in der Suche die Anzeige von allen Protokollsaumltzen (Standard ist bdquoNur Kopfsaumltzeldquo) wieder mit auszugeben
Release Notes BALVI Schnittstellenserver Seite 5 von 37
12 Neuerungen in Version 30 Der BSS 3x beinhaltet alle Funktionalitaumlten des BSS 28x und ist daher abwaumlrtskompatibel
Zusaumltzlich ist es ab Version 3x moumlglich Synchronisations-Jobs zu verarbeiten die mit der OpenSource ETL- Engine bdquoPentaholdquo durch BALVI entwickelt werden Damit wird der BSS auf das zukuumlnftige BALVI iP2 vorbereitet In diesem Zuge wurden diverse Funktionalitaumlten aktualisiert
Beim Update von BSS 2x auf BSS 3x muumlssen an der Datei bdquocontextxmlldquo folgende Anpassungen vorgenommen werden bevor der Server gestartet werden darf
1 Neuer Parameter isJobServiceEnabled
Der Parameter availableServices wurde durch isJobServiceEnabled ersetzt (siehe Kapitel 2516) Damit ist der Jobservice standardmaumlszligig aktiv Empfehlung Suchen Sie availableServices und entfernen Sie diese Einstellung
2 Neue Logging-Konfiguration
Zu BSS 30 wurde auf eine neue Logging-Klasse umgestellt (siehe Kapitel 26) Ersetzen Sie im Ordner conf die vorhandene Datei bdquolog4j-commserverxmlldquo durch die Datei bdquologback-bssxmlldquo um den neuen APPENDER nutzen zu koumlnnen Entfernen Sie log4jConfigLocation und fuumlgen Sie loggingconf hinzu Tragen Sie in der Datei bdquocontextxmlldquo beim neuen Parameter loggingconf den Pfad zur Datei bdquologback-bssxmlldquo ein Die Logging-Funktionalitaumlt des Servers ist davon nicht betroffen
3 Datenbank-Verbindung bdquofactoryldquo umstellen
Bis Version 28 wurde aus Kompatibilitaumltsgruumlnden zu Tomcat 6 als DBCP-Factory noch auf orgapachecommonsdbcpBasicDataSourceFactory verwiesen Ab Tomcat 7 wird jedoch empfohlen die Tomcat-eigene Umsetzung zu verwenden Aumlndern Sie dazu die Angabe factory= in der bdquojdbcDataSourceldquo auf factory=orgapachetomcatjdbcpoolDataSourceFactory Die Verwendung von commonsdhcp wird nicht mehr empfohlen da die Tomcat-spezifische Datasource orgapachetomcatjdbc diverse interne Mechanismen bereitstellt die den Datenbankzugriff aus Apache Tomcat verbessern Dazu gehoumlren die Interceptor-Einstellungen die im Beispiel von BALVI bssxmlexmaple ergaumlnzt wurden (siehe Kapitel 2511)
Release Notes BALVI Schnittstellenserver Seite 6 von 37
4 ETL-Prozesser
Neue Datenquellen ergaumlnzen
Fuumlr die Kommunikation zwischen iP2 Modulen und iP1 wird Kettle benutzt In die contextxml muss dafuumlr eine zusaumltzliche DataSource eingefuumlgt werden wenn Sie die Daten-Uumlbermittlung von IP1 an IP2 verwenden
Die jdbcKettleIP1DataSource ist im Beispiel auskommentiert verwendet derzeit jedoch immer die Zugangsdaten die Sie auch in der jdbcDataSource eingestellt haben da derzeit beide Datenbank-Verbindungen auf das angebundene BALVI iP (124x) zugreifen sollen Beachten Sie jedoch dass die jdbcKettleIP1DataSource die Einstellung type=debalvikettleKettleDataSourceSettings (nicht javaxsqlDataSource) verwendet damit diese nur und ausschlieszliglich dann geladen wird wenn die Kettle-Engine eine separate Datenbankverbindung benoumltigt Um ETL-Engine (Kettle) mitzuteilen welche DataSource das auszufuumlhrende Modul benoumltigt sind folgende Umgebungseinstellungen in die Datei bdquocontextxmlldquo einzufuumlgen
Beispiel
ltResource
name=jdbcKettleIP1DataSource
auth=Container
type=debalvikettleKettleDataSourceSettings
factory=orgapachetomcatjdbcnamingGenericNamingResourcesFactory
maxActive=3 maxIdle=2 minIdle=1 initialSize=1
gt
Kettle Bibliotheken
Da Kettle fuumlr die Ausfuumlhrung verschiedene Dateien benoumltigt muss zudem der Parameter bdquokettlePluginDirectoryldquo eingestellt werden Weisen Sie dem Wert (bdquovalue=ldquo) den Pfad zu dem Verzeichnis zu in dem die Ausfuumlhrungsdateien liegen Die erforderlichen Dateien sind Bestandteil der Auslieferung
ltEnvironment
name=kettlePluginDirectory
value=hometest_ip2_bsskettleplugins
type=javalangString
override=true
gt
13 Hinweise zum Update von aumllteren Versionen (vor 30x) Ab BSS 282 wird eine bdquoserverIDldquo erwartet Daher ist es zwingend erforderlich die vorhandene Datei bdquocontextxmlldquo zu erweitern und den neuen Environment-Parameter bdquoserverIDldquo zu ergaumlnzen
Release Notes BALVI Schnittstellenserver Seite 7 von 37
14 Nacharbeiten nach dem Update auf Version 28
(ADMIN) Sofern Sie schon aktive bdquoJobsldquo im BSS in Verwendung haben werden diese mit dem Update automatisch deaktiviert da die Jobs nun an den ausfuumlhrenden Server gebunden werden muumlssen Oumlffnen Sie dazu den Job in der Detailansicht setzen Sie den Haken hinter bdquoJob an Server bindenldquo setzen und speichern Sie die Einstellung
Der Job wird anschlieszligend in der Uumlbersicht wieder mit dem Status bdquoAktiviertldquo angezeigt Diesen Konfigurationsschritt muumlssen Sie nun jedes Mal durchfuumlhren nachdem die Datenbank von Produktion auf Test geklont wurde
15 Neuerungen in Version 28
151 Jeder Schnittstellen-Server benoumltigt eine Kennung bdquoserverIDldquo Viele Kunden nutzen den Schnittstellenserver mehrfach in Ihrer Umgebung da mehrere BALVI iP Installationen (z B Produktion und Test) in der Infrastruktur existieren
Da die Schnittstellenkonfiguration fuumlr den BSS in der Datenbank abgelegt wird kam es in manchen Faumlllen vor dass nach dem Klonen der Produktionsdatenbank auf ein Testsystem die im BSS angelegten Jobs sofort nach dem Start in der Testumgebung wieder angesprungen sind Um dieses Problem zu beseitigen muss jedem BSS ab Version 28 eine eindeutige bdquoserverIDldquo zugewiesen werden Diese Server-ID wird in der Datei bdquocontextxmlldquo hinterlegt um neutral zur Datenbank zu sein
Ist keine Environment-Variable bdquoserverIDldquo vorhanden wird der Start des BSS 28 (oder houmlher) sofort mit einer Fehlermeldung abgebrochen Im Server-Protokoll wird dabei der Fehler bdquoERROR [IdentityServiceImpl] serverID must not be emptyrdquo ausgegeben Danach kommt sofort die Meldung dass der BSS wieder heruntergefahren wird
INFO [localhost-startStop-1] [ContextCreationListener]
BALVI-Schnittstellen-Server
Version 280
hellip
ERROR [localhost-startStop-1] [IdentityServiceImpl] serverID must not be empty
ERROR [localhost-startStop-1] [ContextLoader] Context initialization failed
Um eine ldquoserverIDrdquo zu vergeben fuumlgen Sie in der Datei bdquocontextxmlldquo folgende Angabe ein
lt--
Release Notes BALVI Schnittstellenserver Seite 8 von 37
ID fuumlr den Server
Diese muss pro Schnittstellenserver eindeutig sein
Eine Aumlnderung dieser ID fuumlhrt sofort dazu dass alle
eingerichteten Server-Jobs inaktiv werden und neu mit
der Instanz gekoppelt werden muumlssen um wieder aktiviert
werden zu koumlnnen
Als value kann ein Text der max Laumlnge von 32 Zeichen
vergeben werden z B ProductionEnvNode1 fuumlr die Produktion
und TestEnvNode1 fuumlr die Testumgebung
--gt
ltEnvironment
name=serverID
value=ProductionEnvNode1
type=javalangString
override=true
gt
152 Optional ist nun eine Namensvergabe moumlglich Auf Wunsch mehrerer Kunden wurde die Option geschaffen jedem Server zusaumltzlich einen kundenspezifischen bdquoTitelldquo zu geben um die Server besser unterscheiden zu koumlnnen
lt--
Visueller Name des Servers in der Oberflaumlche
(Optional)
--gt
ltEnvironment
name=serverName
value=TIERZ Tomcat 8 Java 8 mit BALVI_TIERZXGEWETLBTR_BSS
type=javalangString
override=true
gt
Der hier angegebene Text wird in der Kopfzeile zwischen den eckigen Klammern ausgegeben
Release Notes BALVI Schnittstellenserver Seite 9 von 37
2 Einrichtungshinweise
21 Allgemeine Hinweise zum Betrieb
211 Kompatibilitaumlt zu Apache Tomcat und Java SE Der BALVI Schnittstellenserver wurde getestet und freigegeben fuumlr Apache Tomcat 8 (ab Version 8030 oder neuer) Zudem wurde die aktuellste (letzte offizielle) Version von Java SE 8 getestet und kann verwendet werden (Java SE 8u40 und neuer)
Installieren Sie stets die aktuellsten Sicherheitsupdates fuumlr Java SE 8 Beachten Sie dabei jedoch dass nicht die Aktualisierung auf eine andere Java-Version (z B Java 9) gemeint ist
Freigegebene Major-Versionen werden explizit von BALVI benannt Falls Sie beabsichtigen die Major-Version zu aumlndern pruumlfen Sie bitte die aktuellen Release Notes oder kontaktieren die BALVI Kundenbetreuung
212 Oracle Java SE Lizenzierung Java SE beinhaltet auch kostenpflichtige Funktionen fuumlr deren Nutzung Oracle Lizenzgebuumlhren fordert wenn sie bei der Entwicklung eingesetzt werden Die von BALVI gelieferte Software ist frei von den kommerziellen Teilen der Oracle Java SE nutzbar Fuumlr den Einsatz von Oracle Java SE (einschlieszliglich JDK und JRE) fallen im Rahmen der Nutzung der BALVI Software keine Lizenzkosten an
Trotzdem werden wir parallel pruumlfen ob technische Probleme bei der Umstellung auf das OpenJDK zu erkennen sind Ein einfacher Funktionstest hat im BSS 3x noch keine technischen Probleme gezeigt als wir die Laufzeitumgebung auf das OpenJDK 8U111 AMD64 (Debian) umgestellt haben Bitte haben Sie Verstaumlndnis dafuumlr dass wir keine Funktionstests fuumlr jedes Linux-Derivat durchfuumlhren koumlnnen und dass es offiziell keine Version des OpenJDK fuumlr Windows Betriebssysteme gibt
213 Einsatz von TLSSSL BALVI hat keine spezifischen Anforderungen an die Konfiguration von SSL bzw TLS Der Einsatz von TLS 12 gem der Richtlinie TR-02102-2 vom BSI ist moumlglich wenn Sie sich an die von Apache Tomcat herausgegebene Dokumentation halten Es sind keine Anpassungen des Schnittstellenservers erforderlich Daher gehen wir davon aus dass auch der BSS 28x oder aumllter in einem Apache Tomcat mit TLS 12 betrieben werden kann
Das gilt jedoch nicht fuumlr alle Clients die den Tomcat-Server ansprechen moumlchten So ist z B erst ab BALVI mobil 191958 sichergestellt dass die Protokolle TLS 11 und TLS 12 programmseitig aktiviert sind Fuumlr Details zu diesem Problem wurde ein separates Rundschreiben per E-Mail versendet
Release Notes BALVI Schnittstellenserver Seite 10 von 37
214 Nutzung von Java-Proxyeinstellungen Der BALVI Schnittstellenserver verwendet fuumlr ausgehende Verbindungen die Java-Net Einstellungen welche in der Java-Dokumentation1 beschrieben sind Falls Sie Jobs einsetzen welche ausgehenden Zugriff auf Adressen im Internet benoumltigen kann es passieren dass Sie z B eine bdquojavanetUnknownHostExceptionldquo im Protokoll finden dann muumlssen Sie ihre Proxy-Umgebung in den Java-Umgebungseinstellungen ergaumlnzen
Die folgenden Parameter sollten daher in Ihrer Umgebung gesetzt werden wenn der Zugriff auf das Internet nur uumlber einen Proxy moumlglich ist
-DproxySet=true
-DproxyHost=10111213
-DproxyPort=8888
-DhttpnonProxyHosts=domainorg|localhost|10
Starten Sie nach Aumlnderung der Einstellungen den Server neu damit die Einstellungen wirksam werden
2141 Proxy-Einstellung unter Windows (Tomcat-Dienst)
Verwenden Sie das Dienste-Konfigurationsprogramm (z B tomcat7wexe) und ergaumlnzen Sie die fehlenden Einstellungen
2142 Proxy-Einstellung unter Linux
In Linux wird in der Konfigurationsdatei (z B conftomcat7conf) die Variable bdquo$JAVA_OPTSldquo entsprechend erweitert und die Werte uumlbergeben Beachten Sie dabei dass die Variablen von Linux (bzw der Bash) gelesen werden Daher muss das bdquoPipeldquo-Zeichen bdquo|ldquo mit bdquoldquo maskiert werden ansonsten erhalten Sie bei der Verarbeitung der Umgebungsvariable bdquohttpnonProxyHostsldquo Fehlermeldungen in der Linux -Konsole welche dazu fuumlhren dass Java nicht korrekt konfiguriert werden kann
JAVA_OPTS=$JAVA_OPTS -DproxySet=true -DproxyHost=10111213 -DproxyPort=8888
JAVA_OPTS=$JAVA_OPTS -DhttpnonProxyHosts=domainorg|localhost|10
1 httpdocsoraclecomjavase8docstechnotesguidesnetpropertieshtml
Release Notes BALVI Schnittstellenserver Seite 11 von 37
215 Spracheinstellung Deutsch Es wurde festgestellt dass unter einigen Linux-Versionen die Spracheinstellung beim Starten des Apache Tomcat nicht auf eine deutsche Umgebung verweist Dieses kann technische Probleme verursachen Unter Linux sollte die Einstellung (Umgebungsvariable) entsprechend auf LANG=de_DEUTF-8 eingestellt sein
216 Datenbankverbindung Wenn Sie eine Firewall zwischen dem Oracle-Server und dem Database Connection Pool (DBCP) verwenden sollte unbedingt die bdquovalidationQueryldquo in der DBCP-Konfiguration aktiviert werden damit die Anwendung schneller freie Connections aus dem Pool erhalten kann Die Dokumentation zu den Einstellmoumlglichkeiten ist in der beiliegenden Contextxml ergaumlnzt worden
Bitte beachten Sie dass dringende empfohlen wird die bdquoFactoryldquo auf orgapachetomcatjdbcpoolDataSourceFactory anzupassen falls sie noch auf bdquoorgapachecommonsdbcpBasicDataSourceFactoryldquo eingestellt ist
217 Probleme beim Anlegen von LOB-Objekten Der BALVI Schnittstellen-Server erfordert die JDBC-Spezifikation DBCP V4 welche durch die Factory bdquoorgapachetomcatjdbcldquo ab Tomcat 7 automatisch bereitgestellt wird
Wenn die Pooling-Komponente oder der Oracle-Treiber nicht JDBC4-Kompatibel sind gibt es beim Bearbeiten von LOB-Objekten in Java diverse Exceptions z B
Servletservice() for servlet soapws threw exception
javalangAbstractMethodError
orgapachecommonsdbcpPoolingDataSource$PoolGuardConnectionWrappercreateClob()LjavasqlClob
at debalvicoreauditspyConnectionSpycreateClob(ConnectionSpyjava511)
Ursache dieses Problems ist meistens dass noch nicht auf bdquoorgapachetomcatjdbcldquo umgestellt wurde
218 Umbenennung der gelieferten WAR-Datei Das im Paket von BALVI gelieferte WAR kann jederzeit umbenannt werden (z B als ROOTwar) ohne dass dabei spezielle Einstellungen in der Datei bdquocontextxmlldquo erforderlich sind
Beachten Sie dabei jedoch dass die zum WAR zugehoumlrige Datei bdquocontextxmlldquo im Apache Tomcat immer denselben Namen erhaumllt wie das WAR z B bdquocommserverwarldquo und bdquocommserverxmlldquo Der Name ist dabei ausschlaggebend fuumlr die Zugriffs-Adresse (Context) im Apache Tomcat selbst Die Benennung des WAR in bdquocommserverwarldquo wuumlrde folgendermaszligen aufzurufen sein httpserverportcommserver
219 Server-Schnittstellen Die Uumlberarbeitung bzw Erweiterung der Export- und Importschnittstellen welche uumlber den Schnittstellenserver bereitgestellt werden ist unabhaumlngig vom Schnittstellenserver selbst Die Schnittstellen sind daher nicht Bestandteile des Schnittstellenserver und werden je Verfahren separat
Release Notes BALVI Schnittstellenserver Seite 12 von 37
ausgeliefert Ggf ist es fuumlr unterschiedliche Schnittstellen erforderlich die Grant-Rechte zu aktualisieren (Vgl bdquoWann ist die Ausfuumlhrung des Grant-Skripts erforderlichldquo)
22 Kompatibilitaumltsliste Diverse Verfahren setzen eine Mindestversion des BALVI Schnittstellenservers voraus Die Schnittstellen sind jedoch so konzipiert dass eine Aktualisierung auf eine houmlhere Version des Servers ohne Anpassung an den vorhandenen Schnittstellen jederzeit moumlglich ist
Derzeit sind folgende Mindestanforderungen gegeben
1 BALVI mobil XT 170 oder houmlher setzt BSS 265 und BALVI iP 124x voraus
2 BALVI mobil XT 183 oder houmlher setzt BSS 281 und BALVI iP 124x voraus
3 BALVI mobil 2 (DM) setzt BSS 311 und BALVI iP 124x voraus
4 Die Schnittstelle eFI setzt BSS 251 und BALVI iP 122c voraus
5 Die Schnittstelle LIMS setzt BSS 265 voraus
6 Die Schnittstelle TSK (SN) setzt BSS 265 voraus
7 Die Schnittstelle xDomea (SN) setzt BSS 265 und Java 7 voraus
8 Die Schnittstelle XGewerbeanzeigen 11 setzt BSS 281 BALVI iP 124x Java 8 mit der bdquoJava
Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy2ldquo voraus
9 Die Schnittstelle XGewerbeanzeigen 12 (ab Paket 7 Ausbaustufe 3) setzt BSS 302 BALVI iP
124x Java 8 mit der bdquoJava Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policyldquo
voraus
10 Die Schnittstelle RioPP LM (NRW) setzt BSS 303 und die ETL-Konfiguration voraus
11 Die Schnittstellen zu BALVI iP2 (Fachmodule BTS LM ZDA Stand Juni 2017) setzen BSS 32x
voraus
2 httpwwworaclecomtechnetworkjavajavasedownloadsjce8-download-2133166html
Release Notes BALVI Schnittstellenserver Seite 13 von 37
23 Erforderliche Bibliotheken fuumlr Apache Tomcat Dateiname Funktion Quelle ojdbc6jar Oracle 11gR2 Clientpaket Oracle JDBC Client fuumlr Java
16 ersetzt die bisherige Version bdquoojdbc14jarldquo Die alte Library muss auf jeden Fall entfernt werden
httpwwworaclecomtechnetworkdatabaseenterprise-editionjdbc-112010-090769html
encrypted-datasource-110-alljar
Die Library muss auf jeden Fall entfernt werden Wird derzeit nicht weiter gepflegt da kein Interesse an der Funktionalitaumlt bestand
slf4j-api-1511jar slf4j-log4j12-1511jar log4jdbc4-12beta2jar
Entfaumlllt nicht mehr erforderlich Es wird empfohlen diese zu entfernen falls diese im LIB-Verzeichnis vorhanden sein sollten
commons-dbcp-14jar commons-pool-154jar
Entfaumlllt nicht mehr erforderlich Es wird empfohlen diese zu entfernen falls diese im LIB-Verzeichnis vorhanden sein sollten
Erwartet wird stattdessen ab Tomcat7 die mitgelieferte bdquotomcat-jdbcjarldquo
log4j-1217jar (oder houmlher)
Logging-Funktionalitaumlt Apache Log4j httploggingapacheorglog4j12downloadhtml
bcprov-jdk15on-157jar (oder houmlher)
BouncyCastle Security Provider fuumlr SSLAES hellip wird ab Version 27 im Ordner bdquolibldquo des Tomcat erwartet Sollte es aus Sicherheitsgruumlnden erwuumlnscht sein eine aktuellere Version einzusetzen ist dieses idR moumlglich
httpmvnrepositorycomartifactorgbouncycastlebcprov-jdk15on157
24 Datenbank-Installation Der BALVI Schnittstellenserver benoumltigt auszligerhalb des angebundenen BALVI iP keine eigenen Tabellen Die Web-Anwendung kann im einfachsten Fall direkt auf das Schema von BALVI iP zugreifen indem der Benutzer und das Passwort des BALVI iP-Schemas in der Datei bdquocontextxmlldquo eingetragen werden (nicht empfohlen)
Sollte dies aus Sicherheitsgruumlnden nicht erwuumlnscht sein (empfohlen vom BSI und von BALVI) finden Sie im Paket ein GRANT-Skript um Zugriffsrechte vom BALVI iP Schema fuumlr den Webservice-Schema-Benutzer einzurichten
Zwischen dem Schema von BALVI iP und jeder Web-Anwendung ist dann eine Trennung moumlglich um sicherzustellen dass der Datenbank-Benutzer welcher in der Tomcat-Konfiguration fuumlr die Web-Anwendung eingetragen wird geaumlndert oder geloumlscht werden kann ohne dass die Windows-Anwendung BALVI iP davon betroffen ist Zudem vergibt das von BALVI gelieferte Grant-Skript keine Rechte zum Loumlschen von Tabellenstrukturen oder Tabelleninhalten so dass der Webservice nur festgelegte Daten aumlndern oder lesen darf Es wird empfohlen je Web-Anwendung einen eigenen Datenbank-Benutzer zu vergeben wenn Sie ein BALVI iP mit mehreren Webservices verbinden wollen
Die Moumlglichkeiten im Uumlberblick
1) Sie betreiben den Webservice mit einem eigenstaumlndigen Oracle-Benutzer In diesem Fall muss das
Grant-Skript ausgefuumlhrt werden um den Webservice-Benutzer und den BALVI iP-Benutzer
miteinander zu koppeln
2) In der Tomcat-Konfiguration wird der Oracle-Benutzer eingetragen welcher auch der BALVI iP
Schemabesitzer ist und in der bdquobalviip_conninildquo hinterlegt ist (NICHT Empfohlen) Der Webservice
Release Notes BALVI Schnittstellenserver Seite 14 von 37
hat 100 Zugriffsrechte (auch Loumlsch- oder Aumlnderungsrechte am Schema) es wird kein Grant-
Skript benoumltigt
Wenn Sie die Konfiguration 2) waumlhlen moumlchten koumlnnen Sie die folgenden Unterkapitel uumlberspringen und in Kapitel 0 bzw fortsetzen
241 Erstinstallation Datenbank-Benutzer anlegen Wenn Sie den Webservice-Benutzer vom BALVI iP Schema trennen moumlchten muss durch die DB-Administration in der Oracle-Server-Instanz wo auch BALVI iP sein Schema besitzt ein Benutzer (ggf je Web-Anwendung) angelegt werden welcher folgende Rechte benoumltigt
CONNECT
ALTER SESSION
CREATE JOB
CREATE PROCEDURE
CREATE SESSION
CREATE TABLE
CREATE TRIGGER
CREATE TYPE
CREATE VIEW
CREATE SEQUENCE
CREATE SYNONYM
QUERY REWRITE
Der Default-Tablespace ist frei waumlhlbar Der Benutzer braucht das Recht QUOTA UNLIMITED auf den Tablespace von BALVI iP (Default BALVI_IP) Ein Beispiel-Create-Skript bdquooraCreate_WEB_Usersqlldquo liegt der Auslieferung bei
242 Rechte zuweisen Wenn der BALVI iP Schemabesitzer NICHT in der Tomcat-Umgebung eingetragen werden soll muss ein Oracle DBA das beiliegende GRANT-Skript bdquooraGrantIP_to_Websqlldquo ausfuumlhren um dem jeweiligen Webservice (in Tomcat verwendeten Oracle-Benutzer) die minimalen Rechte auf das Schema von BALVI iP zu gewaumlhren
Dieses Skript setzt voraus dass es von einem Oracle Administrator als bdquoUser SYSTEMldquo ausgefuumlhrt wird Lesen Sie die im Skript enthaltenen README-Kommentare und passen Sie die Benutzer (BALVI iP Schema) und (WEB-Schema) an
====================================================
DEKLARATIVER TEIL MUSS vom KUNDEN geaumlndert
bzw auf die korrekten SCHEMA-Namen angepasst
werden
Die USER-Namen muumlssen in Groszligbuchstaben
geschrieben sein sonst werden sie nicht
gefunden
====================================================
sUserBALVI_IP = BALVI_IP_SCHEMABESITZER
sUserBALVI_WEB = BALVI_WEB_SCHEMABESITZER
Release Notes BALVI Schnittstellenserver Seite 15 von 37
Neu ab Grant-Skript 158 ist die Umbenennung der Verfahrenszuordnung
Pruumlfen Sie dass die Einstellung fuumlr Ihr BundeslandVerfahren korrekt ist dort muss eine 1 fuumlr min ein Verfahren gesetzt sein Diese Einstellung befindet sich direkt unter den Schemabesitzer-Angaben
-- Verfahrensbezogene Konfiguration
-- Setzen Sie fuumlr das jeweilige Verfahren eine 1
-- BALVI Schnittstellenserver (BSS)
-- bis V266 auch BALVI Kommunikationsserver (BKS) genannt
-- generell fuumlr die meisten Verfahren guumlltig
-- Ab Version 57 entfaumlllt mit der Einfuumlhrung der
-- Schnittstelle XGewerbeanzeigen auch der separate Schalter
-- WS_BTR beide Verfahren wurden vereinheitlicht
WS_BSS = 1
Fuumlhren Sie das Skript nach der Anpassung als User SYSTEM aus um die Grants durchzufuumlhren Dieses wurde mit dem von ORACLE gelieferten Programm SQLPLUS (Command-Line) SQLPLUS Worksheet (GUI) und Oracle SQL-Developer getestet
Das Skript generiert fuumlr jedes Objekt ein SYNONYM fuumlr den WEB-USER so dass dieser auf die Objekte ohne Angabe des Owners des IP-Schemas zugreifen kann Pruumlfen Sie nach der Ausfuumlhrung dass die SYNONYMS vorhanden und VALID sind dieses kann ggf nicht der Fall sein Das Skript kann jederzeit erneut ausgefuumlhrt werden um die Grants neu zu erzeugen und bietet ebenfalls die Option alle Grants und Synonyme wieder zu entfernen Detaillierte Informationen zur Nutzung des Skripts sind als Kommentar-Block im Skript enthalten
Hinweis Die Versionsinformation ist unter den Kommentaren direkt im Skript zu finden
Zugriffsberechtigungen fuumlr Webanwendungen auf BALVI iP anlegen
===============================================================
Version 158
Guumlltig fuumlr BALVI iP 123 oder houmlher
Autor Frank Holler
SVN Revisionsinformationen
$Revision 479 $
$Date 2016-02-15 152755 +0100 (Mo 15 Feb 2016) $
================================================================
243 Wann ist die Ausfuumlhrung des Grant-Skripts erforderlich Durch das Strukturupdate von BALVI iP (z B 1240 auf 1241) werden veraltete Strukturen geloumlscht und ggf neue Views oder Tabellen angelegt Die Grant-Rechte geht dabei ggf verloren Daher ist die Ausfuumlhrung des Grant-Skripts immer dann erforderlich wenn sich die Datenbank-Struktur von BALVI iP veraumlndert
Zudem kann es fachliche Neuerungen geben welche im alten Grant-Skript nicht vorhanden sind Daher muss das Skript ggf auch ausgefuumlhrt werden wenn eine neue Schnittstelle im Schnittstellenserver bereitgestellt wurde Dieses betrifft z B auch die Bereitstellung von neuen Versionen von BALVI mobil XT
Release Notes BALVI Schnittstellenserver Seite 16 von 37
da auch dort mit einem fachlich erweiterten Client die Moumlglichkeit besteht dass neue Schnittstellen bereitgestellt und somit mehr Schreibrechte auf Tabellen benoumltigt werden
244 Welche Version des Grant-Skripts soll ich nehmen Wie der Schnittstellenserver sind auch die Grant-Skripte versioniert Neuere Versionen des Grant-Skriptes sind abwaumlrts-kompatibel und koumlnnen immer verwendet werden auch wenn in einer Schnittstellenbeschreibung eine aumlltere Version des Grant-Skriptes explizit benannt wurde
245 Kombination von mehreren Verfahren Wenn Sie zwei oder mehr Schnittstellen im BSS verwenden moumlchten ist es ggf erforderlich auch mehrere Verfahren auf aktiv (bdquo1ldquo) zu setzen
Im Beispiel nehmen wir an Sie moumlchten bdquoeFildquo und bdquoBALVI mobil XTldquo im Schnittstellenserver bereitstellen In der Beschreibung von bdquoeFildquo steht dass das Grant-Skript V36 erforderlich ist BALVI mobil XT 18 erfordert jedoch schon V56
Wenn Sie beide Verfahren betreiben ist im Grant-Skript (V56 oder houmlher) die Einstellung fuumlr beide Verfahren zu aktivieren
====================================================
DEKLARATIVER TEIL MUSS vom KUNDEN geaumlndert
bzw auf die korrekten SCHEMA-Namen angepasst
werden
Die USER-Namen muumlssen in Groszligbuchstaben
geschrieben sein sonst werden sie nicht
gefunden
====================================================
sUserBALVI_IP = BALVI_IP_SCHEMA
sUserBALVI_WEB = WEBAPP_SCHEMA
-- Verfahrensbezogene Konfiguration
-- Setzen Sie fuumlr das jeweilige Verfahren eine 1
-- BALVI Schnittstellenserver (BSS)
-- bis V266 auch BALVI Kommunikationsserver (BKS) genannt
-- generell fuumlr die meisten Verfahren guumlltig
-- Ab Version 57 entfaumlllt mit der Einfuumlhrung der
-- Schnittstelle XGewerbeanzeigen auch der separate Schalter
-- WS_BTR beide Verfahren wurden vereinheitlicht
WS_BSS = 1
-- WebService BTR (Betriebsstaumlttenregister) (NRW TH)
-- entfernt mit Update V57 setzen Sie stattdessen bei WS_BSS = 1
--WS_BTR = 0
-- Probenahme Futtermittel im Browser(BY)
WS_PROBE_FM = 0
-- Risikoorientierte Probenplanung Futtermittel ndash RIOPP FM (BY)
WS_RIOPP_FM = 0
-- Verfahren Export an EFi (Status Pilotbetrieb)
WS_EFI = 1
-- neu ab Version 35 des Grant-Skriptes ist die Moumlglichkeit den Webuser
Release Notes BALVI Schnittstellenserver Seite 17 von 37
-- fuumlr das Loumlschen der Ausgangskoumlrbe explizit zu berechtigen bzw sogar einen
-- expliziten abweichenden User festzulegen Die Konfiguration in der
-- Job-Oberflaumlche sieht vor dass man die Oracle-Datenbank-Zugangsdaten fuumlr
-- das Loumlschen einstellen muss Hier muss im Normalfall derselbe Oracle
-- Datenbankbenutzer eingetragen werden wie in der Tomcat-Verbindungs-
-- konfiguration In diesem Fall sollte wenn WS_EFI = 1 eingestellt wurde
-- ebenfalls WS_EFI_DELETE = 1 eingestellt werden
-- Alternativen
-- 1) Datenbankbenutzer aumlndern
-- Wenn bei sUserEFI_TRUNC anstatt sUserBALVI_WEB (Standard) ein anderer
-- Oracle-Benutzername angegeben wird wird das Loumlschrecht fuumlr die EFi
-- Ausgangskoumlrbe Datenbankseitig exklusiv dem angegeben Datenbankbenutzer
-- zugewiesen
-- 2) Loumlschrecht verweigern
-- Setzen Sie die Variablen WS_EFI_DELETE = 0 damit kein Loumlschrecht
-- zugeweisen wird
WS_EFI_DELETE = 0
-- Beispiel Anderer Benutzer muss in der Datenbank existieren
-- Entfernen Sie die fuumlhrenden -- vor der Variable sUserEFI_TRUNC und
-- setzen den entsprechenden Oracle-Benutzer ein
--sUserEFI_TRUNC = TEST_EFI_TRUNC
hellip
25 Konfiguration des Schnittstellen-Servers
251 Die bdquocontextxmlldquo-Parameter Die von der Servlet-Spezifikation vorgegeben Rump-Struktur sieht folgendermaszligen aus
ltxml version=10 encoding=utf-8gt
ltDOCTYPE Contextgt
ltContextgt
lt-- Kundenspezifische Einstellungen --gt
ltContextgt
Anwendungsspezifische Einstellungen werden zwischen ltContextgt und ltContextgt eingefuumlgt Alle allgemeinguumlltigen Einstellungen in der Datei bdquocontextxmlldquo werden hier erlaumlutert Kommentare finden sich auch in der von BALVI ausgelieferten Beispiel-Konfiguration
Neben den im Folgenden beschriebenen Standard-Einstellungen kann es auch vorkommen dass bundeslandspezifische Erweiterungen vorhanden sind welche nicht in dieser Dokumentation aufgefuumlhrt werden Diese funktionieren trotzdem regulaumlr weiter wenn keine expliziten Informationen zu Kompatibilitaumltsproblemen in den Release-Notes aufgefuumlhrt wurden
2511 Datenbankverbindung jdbcDataSource
Die Datenbankverbindung wird uumlber die von DBCP und dem Oracle-Treiber vorgegebenen Moumlglichkeiten realisiert Der Einsatz der orgapachetomcatjdbcpoolDataSourceFactory (automatisch verfuumlgbar ab Apache Tomcat 7 in der mitgelieferten tomcat-dbcpjar) wird als Beispiel-Konfiguration ausgeliefert
ltResource
name=jdbcDataSource
auth=Container
Release Notes BALVI Schnittstellenserver Seite 18 von 37
type=javaxsqlDataSource
factory=orgapachetomcatjdbcpoolDataSourceFactory
maxActive=10 initialSize=3
maxIdle=5
maxWait=10000
url=jdbcoraclethinBL2-ORA10-KUNDENBALVIINTERN1521ORCL
driverClassName=oraclejdbcdriverOracleDriver
username=balvi_webservice_schema
password=balvi_webservice_password
description=Oracle Datasource
maxOpenPreparedStatements=50
removeAbandoned=false
removeAbandonedTimeout=100
logAbandoned=true
jdbcInterceptors=hellip
gt
Hinweise zur Einstellung der jdbcDataSource
Standard-Einstellungen fuumlr den Datenbank-Verbindungspool
Der Verbindungspool muss entsprechend der Anzahl der zu erwartenden gleichzeitigen Benutzer konfiguriert werden Wenn Sie erwarten dass 50 Anwender gleichzeitig arbeiten stellen Sie bitte folgende Werte ein
maxActive=(50 + 10 (fuumlr System und Jobs)) = 60
maxIdle= (50 10) = 5
1 maxActive - maximale Anzahl der gleichzeitigen aktiven Anfragen an die DB
Wenn der Werte maxActive erreicht ist z B wenn mehrere Benutzer gleichzeitig einen Export starten moumlchten welcher laumlngere Zeit in Anspruch nimmt dann kann der Server die Anfrage nicht mehr bedienen und der Anwender wird abgewiesen maxActive hat zudem Auswirkungen auf die im Hintergrund ausgefuumlhrten Jobs maxActive wird daher kalkuliert mit der Anzahl der Anwender und moumlglicher Datenbank-Connections fuumlr Hintergrund-Jobs Jeder aktiv ausgefuumlhrte Job benoumltigt mindestens eine Connection nur selten wird aus Performance-Gruumlnden mehr als eine Connection waumlhrend der Job-Ausfuumlhrung verwendet Im Normalfall sollten daher 10 Connections fuumlr Hintergrundprozesse ausreichend sein
2 maxIdle - Anzahl der offenen Verbindungen auch wenn der Server im Leerlauf ist
Jede offene Verbindung im Leerlauf haumllt auf dem Datenbankserver eine Session offen Auch diese erfordert Ressourcen Wenn die Verbindungen jedoch geschlossen werden kann die Anfragezeit fuumlr eine neue Verbindung steigen da diese Verbindung erst neu ausgehandelt werden muss Die Empfehlung fuumlr den Wert bdquomaxIdleldquo ist ca 10 der Einstellung von maxActive
KeepAlive-Einstellungen fuumlr den Pool
1 validationQuery
Diese wird ausgefuumlhrt um die Verbindung zu DB zu validieren Es MUSS ein Datensatz zuruumlckgegeben werden ansonsten nimmt der DBCP an dass die Abfrage nicht erfolgreich abgesetzt wurde Achten Sie also bitte darauf dass die Abfrage nicht zu leitungsintensiv ist und genau einen Datensatz liefert
Release Notes BALVI Schnittstellenserver Seite 19 von 37
Oracle bietet dafuumlr die virtuelle Tabelle DUAL an welche sich fuumlr die ValidationQuery sehr gut eignet da die Abfrage kaum Ressourcen verbraucht
validationQuery=select 1 from dual
2 testOnBorrow - Boolscher Wert true oder false
Diese Einstellung sorgt dafuumlr dass der Pool die Verfuumlgbarkeit anhand der validationQuery pruumlft bevor
die DB-Verbindung an die Anwendung ausgeliehen wird Empfehlung
testOnBorrow=true
3 testWhileIdle - Boolscher Wert true oder false
Diese Einstellung ist hilfreich wenn zwischen dem Tomcat und der DB eine Firewall mit Stateful
Packet Inspection verwendet wird Nach laumlngerer Inaktivitaumlt wird normalerweise durch die Firewall die
DB-Verbindung geschlossen Dieses loumlst dann beim Ausleihen der Verbindung eine Fehlermeldung im
Protokoll aus 2012-08-16 165418720 WARN [http-0000-8080-8]
[orgspringframeworkjdbcsupportSQLErrorCodesFactory] Error while extracting
database product name - falling back to empty error codes
orgspringframeworkjdbcsupportMetaDataAccessException Error while extracting
DatabaseMetaData nested exception is javasqlSQLRecoverableException Getrennte
Verbindung Um dieses Problem zu beheben sollte die Option testWhileIdle=true eingestellt werden
testWhileIdle=true
Damit diese weiszlig wie oft eine Pruumlfung durchgefuumlhrt werden muss sind jedoch noch zusaumltzliche Angaben erforderlich welche fuumlr die Einstellung der Zeit zusaumltzlich gesetzt werden muumlssen
a) minEvictableIdleTimeMillis - Long in Millisekunden
Min Zeit wie lange eine DB-Verbindung im Leerlauf ist bevor diese zur Pruumlfung
gekennzeichnet wird Dieses haumlngt stark von der Einstellung der Firewall ab Wenn Sie eine
sehr restriktive Firewall haben kann es sein dass diese die Verbindung nach wenigen
Minuten Leerlauf trennt Stellen Sie den Wert immer so ein dass dieser unter der Leerlaufzeit
der Firewall liegt empfohlen 300000 entspricht 300 Sek = 5 min
minEvictableIdleTimeMillis=300000
b) timeBetweenEvictionRunsMillis - Long in Millisekunden
Der Pruumlflauf startet in der Default-Konfiguration alle 1800000 Millisekunden = 30 Min n als
zu Pruumlfen markierte Verbindungen werden in einem Pruumlflauf getestet n wird bestimmt durch
die Einstellung numTestsPerEvictionRun Empfehlung Stellen Sie den Wert auf alle 15 Min
ein
timeBetweenEvictionRunsMillis=900000
Release Notes BALVI Schnittstellenserver Seite 20 von 37
c) numTestsPerEvictionRun - Integer
Wie viele Verbindungen sollen getestet werden waumlhrend der Pruumlflauf ausgefuumlhrt wird Im
Normalfall sollte die Anzahl der zu testenden Verbindungen nicht zu hoch eingestellt werden
Der Default ist 3 Wenn Sie houmlhere Sicherheit haben wollen dass keine bdquototenldquo
Datenbankverbindungen bestehen bleiben erhoumlhen Sie den Wert auf max bdquo(maxActive ndash
maxIdle) 2ldquo Wenn Ihnen 3 ausreichend erscheint muss der Wert nicht gesetzt sein dann
wird der Default verwendet
Beispiel numTestsPerEvictionRun=10
4 Interceptors konfigurieren Neu ergaumlnzt wurde die Moumlglichkeit spezielle bdquoInterceptorsldquo zu konfigurieren die ermoumlglichen das Verhalten des Pools zu steuern Wichtig hierbei ist dass die Angabe von Werten auf real existierende Java-Klassen erfolgt die im Classpath des Tomcat vorhanden sind Groszlig-und-Kleinschreibung ist zu beachten Folgende Default-Einstellung hat BALVI fuumlr den BSS festgelegt jdbcInterceptors=
orgapachetomcatjdbcpoolinterceptorConnectionState
orgapachetomcatjdbcpoolinterceptorStatementFinalizer
orgapachetomcatjdbcpoolinterceptorResetAbandonedTimer
Details zu den verwendeten Interceptor-Einstellungen finden Sie in der Tomcat-Dokumentation3
3 httptomcatapacheorgtomcat-80-docjdbc-poolhtmlJDBC_interceptors
Release Notes BALVI Schnittstellenserver Seite 21 von 37
2512 Datenbank-Zugangsdaten verschluumlsseln
Die Verschluumlsselung fuumlr die Datenbank-Verbindung (bdquoEncrypted Datasourceldquo) ist eine Ableitung der Bibliothek Apache-Common-DBCP-14 und daher nicht mehr mit Java 8 kompatibel Die Einrichtung der Verschluumlsselung wird daher mit der Auslieferung des BSS 30 nicht mehr angeboten
2513 Active-Directory-Authentifizierung
Uumlber die folgenden Parameter wird der Zugriff des Schnittstellen-Servers auf einen Microsoft Active Directory Domain-Controller konfiguriert
ldquoldapServerAddressrdquo
Syntax PROTOKOLLIP-Adresse oder DNS-NamePORT
ltEnvironment
name=ldapServerAddress
value=ldapbl2-dc02balviintern389
type=javalangString
override=true
gt
Als Protokoll besteht auch die Moumlglichkeit ldaps (LDAP+SSL) wenn der Domain-Controller entsprechend konfiguriert wurde Im Java Truststore muss dann das Zertifikat der CA vorhanden sein welche das Zertifikat des Domain-Controllers signiert hat Zudem darf bei ldaps keine IP-Adresse verwendet werden es muss der DNS-Name des Server-Zertifikats eingetragen sein Ansonsten gibt es beim Verbinden eine Sicherheits-Exception
lt-- SSL-Beispiel
ltEnvironment
name=ldapServerAddress
value=ldapsbl2-dc02balviintern636
type=javalangString
override=true
gt
--gt
bdquoldapBaseDnrdquo
LDAP-Suchpfad fuumlr die Domain-Basis Diese muss der LDAP-Syntax fuumlr den Domain-Suffix entsprechen
Syntax DC=SERVERDC=ROOTDN
ltEnvironment
name=ldapBaseDn
value=DC=BALVIDC=INTERN
type=javalangString
override=true
gt
Release Notes BALVI Schnittstellenserver Seite 22 von 37
bdquowebLoginUseActiveDirectoryAuthenticationrdquo
Die Authentifizierung in der Browser-Oberflaumlche kann uumlber die Active-Directory-Authentifizierung erfolgen In der ersten Version ist nur die Protokoll-Auswertung moumlglich wenn der ADMIN sich anmeldet Dieser hat normalerweise niemals AD-Kennungen zugeordnet BALVI empfiehlt diese Einstellung auf bdquofalseldquo zu belassen Webservices welche uumlber SOAPREST zugreifen koumlnnen die Active-Directory-Authentifizierung trotzdem verwenden
ltEnvironment
name=webLoginUseActiveDirectoryAuthentication
value=false
type=javalangBoolean
override=true
gt
ldquoldapDaysBeforeExpirationNotificationrdquo
Die Passwort-Aumlnderung im Active-Directory uumlber die Browser-Oberflaumlche ist in der ersten Version noch nicht implementiert der Parameter wird bislang nicht ausgewertet
ltEnvironment
name=ldapDaysBeforeExpirationNotification
value=14
type=javalangInteger
override=true
gt
2514 Statement-Protokollierung in BALVI iP
Diese Option aktiviert die Lese- und Aumlnderungsprotokollierung fuumlr BALVI iP Standard ist bdquofalseldquo und wird fuumlr alle Kunden empfohlen solange keine speziellen Datenbank-Jobs eingerichtet wurden welche zeitgesteuert die Protokolleintraumlge wieder loumlschen Fuumlr Bayern wurde ein spezielles Konzept zur Leseprotokollierung entworfen Wenn Sie mehr daruumlber erfahren moumlchten kontaktieren Sie bitte die BALVI GmbH
ltEnvironment
name=enableSqlStatementMonitoring
value=true
type=javalangBoolean
override=true
gt
Beachten Sie dass diese Option massive INSERT-Statements in BALVI iP in die Tabelle VIS_D92 ausfuumlhrt Jedes abgesetzte SQL-Statement wird dabei vollstaumlndig protokolliert Dieses erzeugt eine sehr hohe INSERT-Last und in der Folge auch erhoumlhte Redolog-Switches und COMMIT-Transaktionen
Optional Aktivieren der INSERT + APPEND - Logik
Beachten Sie bitte die Hinweise von Oracle zum Hint + APPEND
Release Notes BALVI Schnittstellenserver Seite 23 von 37
Wenn Sie dieses Verhalten aktivieren moumlchten ergaumlnzen Sie bitte den folgenden Environment-Parameter
ltEnvironment
name=statementMonitoringactivateAppendMode
value=true
type=javalangBoolean
override=true
gt
2515 Einstellungen fuumlr BALVI mobil XT (bzw den bdquopartitionedExportldquo)
Diese Logik des FIFO-Buffers wurde so konzipiert dass dem Rechenzentrum diverse Einstellmoumlglichkeiten uumlber die Datei bdquocontextxmlldquo zur Verfuumlgung stehen um die Steuerung des FIFO-Puffers zu beeinflussen
Schematische Darstellung des FIFO-Puffers
Das ermoumlglicht es z B dem BALVI mobil XT Client (14 oder houmlher) den aktiven Block abzuholen und dies beim Fehler bis zu 10-mal zu wiederholen Sobald der Block [001] erfolgreich beim Client angekommen ist und dieser den naumlchsten Block anfragt wird der Block [001] verworfen wird Der Server fuumlllt dann im Hintergrund den frei gewordenen Block wieder waumlhrend der Client den Block [002] abholt
Die Groumlszlige und Anzahl der vorgecachten Bloumlcke kann uumlber die folgenden Einstellungen in der Datei bdquocontextxmlldquo definiert werden
ltEnvironment
name=partitionedExportmaxBufferedPartitions
value=3 type=javalangInteger override=true
gt
ltEnvironment
name=partitionedExportpartitionSize
value=256000 type=javalangInteger override=true
gt
Die Einstellung partitionedExportmaxBufferedPartitions ist dabei die Anzahl der vorgecachten Bloumlcke mindestens muss 2 angegeben werden Der Puffercache wird ausschlieszliglich im RAM der JVM aufgebaut es wird folglich mehr Arbeitsspeicher verwendet Dieser Arbeitsspeicher muss je gleichzeitiger Session auf dem Server bereitgestellt werden die Default-Einstellung mit 3 Partitionen a 256 KB + dem aktiven Puffer erfordern 1 MB RAM je aktiven Anwender
Aktiv
er
Puffe
r
[001] Vorg
ecac
hter
Bl
ock
[002] Vorg
ecac
hter
Bl
ock
[003]
Aktiv
er P
uffe
r
[002] Vorg
ecac
hter
Bl
ock
[003] Vorg
ecac
hter
Bl
ock
[leer]
Release Notes BALVI Schnittstellenserver Seite 24 von 37
Gleichzeitig wurde die Moumlglichkeit geschaffen dass die maximale Anzahl an gleichzeitigen Exporten durch das Rechenzentrum eingeschraumlnkt werden kann um einem OutOfMemory-Fehler vorzubeugen Die Einstellung
ltEnvironment
name=partitionedExportmaxConcurrentExports
value=10 type=javalangInteger override=true
gt
muss entsprechend der zu erwartenden gleichzeitigen Zugriffe konzipiert werden ansonsten wird der Server einen Verbindungsversuch durch die Clients ablehnen
Beachten Sie dass die folgenden Einstellungen partitionedExportmaxBufferedPartitions partitionedExportmaxConcurrentExports und partitionedExportpartitionSize gemeinsam als Rechenbasis fuumlr den RAM-Bedarf des Webservers herangezogen werden muumlssen
Folgende Faustformel sollte fuumlr die Einrichtung verwendet werden
Min 256 MB (Serverbasis) + (11 partitionedExportmaxConcurrentExports partitionedExportmaxBufferedPartitions partitionedExportpartitionSize)
Beispiel 50 gleichzeitige Anwender Blockgroumlszlige 256 KB 4 Partitionen
256 MB + (11 50 256 4) KB = 312 MB fuumlr die JVM
Empf 512 MB (Serverbasis) + (12 partitionedExportmaxConcurrentExports partitionedExportmaxBufferedPartitions partitionedExportpartitionSize)
Beispiel 50 gleichzeitige Anwender Blockgroumlszlige 256 KB 4 Partitionen
512 MB + (12 50 256 4) KB = 572 MB fuumlr die JVM
partitionedExportmaxConcurrentExports
Bestimmt die Anzahl der maximalen Export Tasks (Threads) die fuumlr partitionierte Exporte bereitgestellt werden Wenn die Anzahl uumlberschritten wird wird die entsprechende Exportanfrage abgewiesen und der Client muss zu einem spaumlteren Zeitpunkt erneut anfragen Stellen Sie diesen Wert entsprechend der zu erwartenden Benutzeranzahl ein bei 50 Anwendern also 50
Exporte oumlffnen auf der Datenbank entsprechend zur Ausfuumlhrungszeit min einen Cursor ggf fuumlr rekursive Unterabfragen kurzfristig sogar mehr Die hier eingestellte Anzahl muss mit der Anzahl von maxActive korrelieren
ltEnvironment
name=partitionedExportmaxConcurrentExports
value=10 type=javalangInteger override=true
gt
partitionedExportmaxBufferedPartitions
Bestimmt die Anzahl der Datenbloumlcke (Partitionen) die vom Server bei Abruf eines Exportes gepuffert werden Die seit Version 24 eingefuumlhrte FIFO-Puffer-Logik ermoumlglicht dass der Server schon die Ergebnisse vorpuffert so dass der Client weniger Wartezeiten bei der Anfrage nach Daten hat Diese
Release Notes BALVI Schnittstellenserver Seite 25 von 37
Puffer-Logik unterteilt den Exportdatenstrom (je Export) in mehre Bloumlcke Der Client kann nun den letzten Block neu anfordern oder den naumlchsten Block wenn der letzte Block erfolgreich verarbeitet wurde Wie viele naumlchste Bloumlcke durch den Server bereit gestellt werden entscheidet diese Einstellung Sobald kein naumlchster Block mehr bereit gestellt werden muss wird der Datenbank-Cursor geschlossen eine Erhoumlhung kann also zu einer Entlastung der aktiven DB-Verbindungen fuumlhren erhoumlht jedoch den Bedarf an RAM des Servers
Der von BALVI voreingestellte Wert ist 3
ltEnvironment
name=partitionedExportmaxBufferedPartitions
value=3 type=javalangInteger override=true
gt
partitionedExportpartitionSizeldquo
Die Groumlszlige der Datenbloumlcke (Partitionen) die an den Client uumlbermittelt werden in Bytes Wenn Sie diesen Wert zu niedrig einstellen reduziert sich die Effizienz des Caches da der Client mehr Datenbloumlcke hintereinander abrufen muss Waumlhlen Sie einen zu groszligen Wert wird die neu zu uumlbertragende Datenmenge im Fall eines Fehlers houmlher
Der von BALVI voreingestellte Wert ist 256000 (256 KB)
ltEnvironment
name=partitionedExportpartitionSize
value=256000 type=javalangInteger override=true
gt
exportTokensmaxTokenCount
Maximale Anzahl der gleichzeitig vergebenen Token die vom Server gecached werden Jede Sitzung welche einen Export durchfuumlhrt erhaumllt einen Session-Token
Wenn eine Sitzung laumlngere Zeit nicht verwendet wurde wird dieser Session-Token wieder entfernt Wenn Sie den Wert zu niedrig einstellen fuumlhrt das zu einer generellen Session-Begrenzung auch fuumlr den nicht partitionierten Export-Modus welcher ab Version 21 verfuumlgbar ist
Ist die Anzahl der Tokens houmlher als die Datenbankeinstellung maxActive kann es vorkommen dass zwar eine Session gestartet werden kann jedoch kein Datenexport zustande kommt
Der von BALVI voreingestellte Wert ist 2000
ltEnvironment
name=exportTokensmaxTokenCount
value=20 type=javalangInteger override=true
gt
exportTokenstokenExpirationInSeconds
Zeit in Sekunden die verstreichen muss bis ein Token unguumlltig wird falls darauf kein Zugriff mehr erfolgt Nach einem erfolgreichen Export wird der Token automatisch geschlossen diese Option ist fuumlr den Abbruchfall vorgesehen Der von BALVI voreingestellte Wert ist 180 (180 s = 3 min)
Release Notes BALVI Schnittstellenserver Seite 26 von 37
ltEnvironment
name=exportTokenstokenExpirationInSeconds
value=180 type=javalangInteger override=true
gt
exportTokenstokenDisposalInSeconds
Zeit in Sekunden die verstreichen muss bis ein Token das erfolgreich abgearbeitet wurde aus dem Cache geloumlscht wird Um sicher zu stellen dass der letzte Exportblock noch erfolgreich abgerufen werden kann bleibt der Token auch nach Fertigmeldung des Clients noch N Sek guumlltig
Der von BALVI voreingestellte Wert ist 60 (60 s = 1 min)
ltEnvironment
name=exportTokenstokenDisposalInSeconds
value=60 type=javalangInteger override=true
gt
2516 Job-Verwaltung fuumlr den BSS konfigurieren Aktivierung der Jobverwaltung
Bis zur Version 28 des BSS gab es den Parameter bdquoavailableServicesldquo Dieser konnte bei Bedarf aktiviert werden wenn die Jobs benoumltigt wurden
Mit Version 30 ist die Einstellung bdquoavailableServicesldquo zu entfernen und kann durch den neuen optionalen Parameter bdquoisJobServiceEnabledldquo in der Datei bdquocontextxmlldquo ersetzt werden
lt-- Neue Parameter zur Aktivierung des Job Service Ersatz fuumlr availableServices --gt
ltEnvironment
name=isJobServiceEnabled
value=true
type=javalangBoolean
override=true
gt
Ab BSS 30 wird die Jobs-Engine standardmaumlszligig aktiviert Sollte die Jobs-Engine nicht benoumltigt werden muss bdquovalueldquo der Wert bdquofalseldquo zugewiesen werden Wird bdquoisJobServiceEnabledldquo nicht eingefuumlgt sind die Jobs trotzdem standardmaumlszligig aktiv
Nach dem Neustart des Servers und erneutem Einloggen erscheint nun zusaumltzlich der Menuumlpunkt bdquoJobsldquo
bdquopasswordKeyldquo fuumlr Jobs
In der Job-Logik wird ein von BALVI definierter Standard-Schluumlssel fuumlr die Ablagen von schuumltzenswerten Daten z B Passwoumlrtern verwendet Diese Einstellung ermoumlglicht den BALVI-Standard zu uumlberschreiben Wenn Sie diese Einstellung aumlndern muumlssen jedoch alle bislang verschluumlsselten Job-Parameter neu verschluumlsselt werden
ltEnvironment
name=javacompenvjobspasswordKey
value=MeinHochsicheresNeuesPasswort
type=javalangString
Release Notes BALVI Schnittstellenserver Seite 27 von 37
override=true
gt
bdquoJob ID enableddisabledldquo (Deprecated ersetzt ab 28 durch das bdquoBindenldquo von Jobs)
Sondereinstellungen fuumlr die Job-Verwaltung Da alle Jobs in einer Datenbank administriert werden jedoch ggf verteilt auf mehreren Tomcat-Servern ausgefuumlhrt werden sollen besteht hier die Option Jobs fuumlr die aktuelle Tomcat-Instanz separat zu deaktivieren
Die Einstellung ID koumlnnte z B folgendermaszligen aussehen javacompenvjobsC0DB58D8D52C4BBC966D1DC788A4EF8Benabled
Fuumlr weitere Fragen zu dieser Einstellung kontaktieren Sie bitte die BALVI GmbH
ltEnvironment
name=javacompenvjobsIDenabled
value=false
type=javalangBoolean
override=true
gt
2517 Weitere optionale Parameter
Es ist fuumlr diverse einzelne Schnittstellen ggf erforderlich Einstellungen in der Datei bdquocontextxmlldquo zu ergaumlnzen Hinweise zu diesen Parametern sind dann in dem der Schnittstelle beiliegenden Dokument enthalten Das gilt z B fuumlr die Schnittstelle bdquoXGewerbeanzeigenldquo
26 Logging mit logback Das Logging wurde komplett uumlberarbeitet Statt bdquoLog4Jldquo wird jetzt bdquologbackldquo4 benutzt Ab BSS 30 ist es zwingend notwendig die Einstellung vorzunehmen um das Logging der Anwendung zu steuern
Migration Ergaumlnzen Sie die neue Einstellung bdquologgingconfigldquo
lt-- Neue Paramter zur Angabe der Logback Config Ersatz fuumlr log4jConfigLocation --gt
ltEnvironment
name=loggingconfig
value=$catalinabaseconflogback-bssxml
type=javalangString
override=true
gt
Nach wie vor steht es Ihnen frei die Logging-Konfiguration eigenstaumlndig anzupassen
Wenn Sie jedoch dieselbe WAR in einer Tomcat-Instanz unter mehreren Context-Namen betreiben wuumlrden beide dieselbe Logging-Konfiguration verwenden so dass alle Protokolleintraumlge in einer Log-Datei aus
4 httplogbackqoschmanualappendershtml
Release Notes BALVI Schnittstellenserver Seite 28 von 37
mehreren Webanwendungen generiert werden Aumlndern Sie den Namen der Logging-Konfiguration entsprechend ab um fuumlr jede Anwendung eine spezifische Logging-Einstellung vornehmen zu koumlnnen
27 Tocmat Optional Suche im bdquoKlassenpfadldquo um den
Ordner bdquoconfldquo erweitern Die Suche nach Dateien uumlber bdquoclasspathldquo setzt voraus dass die Ordner- und Dateinamen im Apache Tomcat bekannt gegeben werden Der Klassenpfad kann in der Datei bdquocatalinapropertiesldquo angepasst werden Wenn Sie dort unter commonloader die folgenden Werte ergaumlnzen kann eine Datei auch im Ordner conf abgelegt werden damit Apache Tomcat diese findet Ansonsten muss die Datei im Ordner lib abgelegt werden
commonloader=$catalinabaseconf$catalinahomeconf
3 Die neue Browser-Oberflaumlche Der BALVI Schnittstellenserver hat seit Version 25 neben der Protokollierung auch die Moumlglichkeit Job-Konfigurationen zu pflegen Der Login ist nur fuumlr einen in BALVI iP eingetragenen ADMIN (z B Benutzer bdquoSYSTEMADMINldquo) mit dem in BALVI iP hinterlegten Passwort moumlglich Zur Anmeldung muss immer [SYSTEMBenutzername] im Feld Benutzer angegeben werden ansonsten schlaumlgt die Anmeldung fehl Bitte achten Sie darauf dass der bdquoldquo (Slash) und nicht der bdquoldquo (Backslash) verwendet werden muss
31 Server-Protokoll Um das Server-Protokoll anzuzeigen waumlhlen Sie den entsprechenden Menuumlpunkt Dort haben Sie seit BSS 26 die Moumlglichkeit uumlber alle Spalten der Protokolle nach Informationen zu suchen
Seit BSS 31 gibt es die Moumlglichkeit Verfahren in bdquoKopfsaumltzeldquo und bdquoDetailsaumltzeldquo zu unterteilen Wurde das Verfahren entsprechend konfiguriert (wie z B bei der Schnittstelle bdquoXGewerbeanzeigenldquo) dann wird im Protokoll-Kopfsatz nur der Start und das Ende der Ausfuumlhrung in der Liste angezeigt Erst bei einem Klick auf bdquoInformationenldquo wird die Liste aller Detailsaumltze angezeigt die im Durchlauf erzeugt wurden
Release Notes BALVI Schnittstellenserver Seite 29 von 37
Verfahren
Die Liste der verfuumlgbaren Verfahren die bei Ihnen im System installiert sind ZB
BEFUNDEhellip Schnittstelle Befunde LM FM oder TS
PROBEhellip Schnittstelle zum Export von Proben an Labore ebenfalls Spezifisch fuumlr einzelne Fachbereiche
MOBILXT Protokolle der BALVI Mobil XT Synchronisation
WEB Allgemeine nicht spezifizierte Protokolle hierunter ist bislang auch die eFi-Protokollierung zu finden
WEB_I0802 Protokolle zur Schnittstelle BALVI iP LIMS (Lebensmittelproben)
XGEWERBE Schnittstelle XGewerbeanzeigen
Klicken Sie auf die Schaltflaumlche so besteht bei den neuen Protokolldatensaumltzen die Moumlglichkeit Detail-Informationen zum Protokollsatz zu erhalten
Release Notes BALVI Schnittstellenserver Seite 30 von 37
Seit BSS 30x ist die Anzeige der Protokolle ebenfalls farblich abgesetzt so dass Protokolleintraumlge mit Fehlern hellrot und Warnungen hellgelb hinterlegt werden
32 Jobs Mit einem Klick auf den Menuumlpunkt Jobs rufen Sie die Oberflaumlche fuumlr die Job-Konfiguration auf Daraufhin werden alle Jobs aufgelistet die fuumlr den BSS freigegeben sind Hier koumlnnen Sie Einstellungen an den Jobs vornehmen und die Jobs aktivieren bzw deaktivieren Die Beschreibungen bzw Einstellungsmoumlglichkeiten fuumlr den jeweiligen SST-Job sind nicht Bestandteil dieser Dokumentation
33 Log-Ausgaben Uumlber den Menuumlpunkt Log-Ausgaben koumlnnen Sie die Ausgabe der Protokolleintraumlge in Echtzeit beobachten
Release Notes BALVI Schnittstellenserver Seite 31 von 37
Starten Sie die Echtzeit-Protokollierung indem Sie auf die Schaltflaumlche mit dem Symbol bdquoPlayldquo (Dreieck) klicken unterbrechen Sie die Ausgabe indem Sie die auf Schaltflaumlche mit dem Symbol bdquoPauseldquo (zwei Balken) klicken
Klicken Sie auf die Schaltflaumlche bdquoAktualisierenldquo (zwei Pfeile) um die neuesten Protokolleintraumlge angezeigt zu bekommen
Klicken Sie auf das Symbol mit dem Papierkorb um die letzten Protokollmeldungen in der Anzeige zu loumlschen
Die Daten in den Protokolldateien auf der Festplatte des Servers sind davon nicht betroffen
Uumlber das Symbol bdquoLogging anpassenldquo (Schraubenschluumlssel) koumlnnen Sie die Ausgabe der Daten im Echtzeitfenster und in den Protokolldateien aumlndern jedoch ist diese Einstellung nur temporaumlr Die Standardeinstellungen koumlnnen ausschlieszliglich uumlber die Anpassung der Datei bdquologback-bssxmlldquo im Konfigurationsverzeichnis des Servers selbst geaumlndert werden
Release Notes BALVI Schnittstellenserver Seite 32 von 37
In der Logging-Parameter Konfiguration koumlnnen Sie verschiedene Parameter einstellen und uumlber die Schaltflaumlche bdquoAnwendenldquo dann sofort im Echtzeitprotokoll sehen Welche Einstellungen moumlglich sind erfahren Sie wenn es eine akute Fehlersituation gibt die detailliertere Ausgaben im Protokoll erfordert
Warnung Wenn Sie den Log-Level fuumlr ROOT oder eine andere Klasse auf TRACE einstellen werden sehr viele Protokollausgaben generiert die auch dazu fuumlhren koumlnnen dass der Server sehr langsam wird oder die Festplatte des Servers zulaumluft wenn fuumlr das Logging kein Dateilimit konfiguriert wurde
34 LogoutAbmeldung vom System Zum Abmelden waumlhlen Sie oben rechts das Kontextmenuuml
35 Cache loumlschen Der Cache wird in der Regel automatisch geloumlscht Wenn Sie jedoch gerade in BALVI iP eine Aumlnderung an den Schnittstellen eingespielt haben und moumlchten dass diese sofort wirksam wird kann die Funktion bdquoCache loumlschenldquo dazu verwendet werden dass der BALVI Schnittstellenserver die Einstellungen bei der naumlchsten Anfrage neu einliest
Release Notes BALVI Schnittstellenserver Seite 33 von 37
Release Notes BALVI Schnittstellenserver Seite 34 von 37
4 Einrichtung in BALVI iP Um die Verfahren fuumlr den BALVI Schnittstellenserver fuumlr Anwender freizuschalten wird das Objekt bdquoSystemeinstellungenldquo oder bdquoMandanten- und Benutzereinstellungenldquo verwendet Die Anpassung ist je Verfahren moumlglich so kann in BALVI iP fuumlr den Zugriff durch den BALVI Schnittstellenserver ein Benutzer bdquoAldquo am Verfahren bdquoMobilldquo berechtigt werden ein Benutzer bdquoBldquo nur am Verfahren bdquoSLA_FLESHldquo usw Die Logik ist jedoch einheitlich Je Verfahren wird durch BALVI eine Verfahrensgruppe mit dem Verfahrensnamen angelegt und mit den entsprechenden Einstellungen vorkonfiguriert welche durch das Verfahren erforderlich sind Dabei kann die Komplexitaumlt der Einstellungen variieren wie z B an den zu Version 23 verfuumlgbaren Verfahren bdquoMobilldquo und bdquoSLA_Fleshldquo ersichtlich wird
Im Verfahren BALVI Mobil sind diverse Anpassungen moumlglich welche je Bundesland oder eingesetzter Import- und Export-Variante durch den BALVI Schnittstellenserver bei der Bearbeitung von Anfragen gepruumlft werden siehe Punkt 3 Abb Mobil-Einstellung in BALVI iP
Abb Mobil-Einstellung in BALVI iP
Alle Verfahren verwenden jedoch die regulaumlre Benutzerverwaltung von BALVI iP Ein Benutzer ohne Passwort gilt fuumlr BALVI iP als gesperrt was fuumlr das Login bedeutet dass der Anwender sich nur uumlber die Active-Directory-Authentifizierung anmelden kann Ist das nicht moumlglich (bzw nicht konfiguriert) kann der Anwender sich weder in BALVI iP noch uumlber die Webservice-Schnittstelle authentifizieren
Fuumlr Dienste-Schnittstellen welche keine persoumlnliche Authentifizierung durch einen Anwender erfordern wird empfohlen einen separaten Benutzer in der Benutzerverwaltung anzulegen und ein sicheres Kennwort zu vergeben Das Anlegen von zusaumltzlichen Benutzern gilt nicht fuumlr BALVI mobil XT da beim Holen und Uumlbermitteln von Daten jeder Benutzer auch ein fachlich konfigurierter Anwender innerhalb von BALVI iP ist und die Anwendungsoberflaumlche ebenfalls zur Erfassung von Daten verwendet
Unter Punkt 2 der Abb Mobil-Einstellung in BALVI iP wird ein modales Fenster geoumlffnet (Abb BALVI mobil Benutzerverwaltung) Innerhalb dieses modalen Fensters werden mandantenweise die Benutzer fuumlr BALVI
Release Notes BALVI Schnittstellenserver Seite 35 von 37
mobil und den jeweiligen Fachbereich festgelegt Dabei ist es wichtig dass man die Haken bdquoAktiv fuumlr hellipldquo bei bdquohellip mobilldquo und bei einem Fachbereich (bdquohellip LMldquo bdquohellip FMldquo usw) setzt weil sonst uumlber den BALVI Schnittstellenserver keine Kommunikation mit BALVI iP moumlglich ist
Abb BALVI mobil Benutzerverwaltung
Alternativ zur Passwort-Authentifizierung wird wie beschrieben auch die Active-Directory-Authentifizierung angeboten Dazu muss der BALVI iP-Anwender uumlber die Schaltflaumlche bdquoDomaumlnen-Benutzer zuordnenldquo mit dem Active Directory verknuumlpft werden
Nur wenn die Active-Directory-Konfigurationen in BALVI iP und im BALVI Schnittstellenserver auf dieselbe Domaumlne verweisen sind die Domaumlnen-Zuordnung und die Active-Directory-Authentifizierung (z B uumlber BALVI mobil XT) moumlglich
Release Notes BALVI Schnittstellenserver Seite 36 von 37
5 Bekannte Probleme und Loumlsungen
51 ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner Bei der Job-Bearbeitung tritt folgender Fehler auf ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner
Behebung
Fuumlhren Sie das beiliegende IP-Patch (UPDATEexe) aus bevor Sie das WAR austauschen
52 Server startet nicht Sie finden folgende Zeilen im Protokoll (catalinaout oder bsslog)
ERROR [localhost-startStop-1] [IdentityServiceImpl] serverID must not be empty
ERROR [localhost-startStop-1] [ContextLoader] Context initialization failed
Behebung
Setzen Sie die Umgebungsvariable ldquoserverIDrdquo in der Datei bdquocontextxmlldquo
53 ORA-00942 table or view does not exist In vielen Faumlllen wird der Fehler ldquoTabelle oder View nicht vorhandenrdquo ausgeworfen (Java-Protokoll im Ordner logs von Apache Tomcat) wenn eine neue Schnittstelle eingerichtet oder ein neues BALVI iP Release bzw Update eingespielt wurde ohne anschlieszligend das aktuelle GRANT-Skript auszufuumlhren
Behebung
Fuumlhren Sie das GRANT-Skript erneut aus
54 ORA-0406x bdquoBestehender Paketstatus wurde aufgehobenldquo
ORA-04061 Bestehender Status von package body ABCXYZ wurde annulliert
ORA-04065 Ausfuumlhrung nicht erfolgreich package body ABCXYZ wurde geaumlndert oder geloumlscht
Release Notes BALVI Schnittstellenserver Seite 37 von 37
Der Fehler tritt haumlufig ein nachdem die UPDATEexe ausgefuumlhrt und in der Ausfuumlhrungsliste ein Package aktualisiert wurde Oracle merkt sich je User-Session bestimmte Werte im Package wenn der Anwender es verwendet hat Durch einen bdquoCREATE OR REPLACE PACKAGEldquo-Befehl kann dieser Status temporaumlr aufgehoben werden Normalerweise tritt dieser Fehler nach dem Update genau einmal in jeder aktiven Session auf wenn der BSS nicht neu gestartet wird
Behebung
Starten Sie nach jedem Update den BSS neu um alle laufenden Sessions zu beenden
55 Jobs sind nicht ausfuumlhrbar
1 Ein Job wird mit dem Status bdquoNicht unterstuumltztldquo angezeigt wenn fuumlr seine Ausfuumlhrung eine houmlhere Version des BSS erforderlich ist
2 Nach dem Klonen der Datenbank von der Produktions- auf die Testumgebung erhalten alle Jobs automatisch den Status bdquoDeaktiviertldquo wenn die bdquoserverIDldquo nicht identisch ist
Beide Statusaumlnderungen sind gewollt Damit soll verhindert werden dass Jobs nach einem Serverneustart oder nach einem Update automatisch starten und dabei Fehler verursachen
Um Jobs mit dem Status bdquoNicht unterstuumltztldquo nutzen und konfigurieren zu koumlnnen ist es erforderlich den BALVI Schnittstellenserver zu aktualisieren
Deaktivierte Jobs koumlnnen Sie aktivieren indem Sie den jeweiligen Job an den aktuellen Server binden und den Haken bei bdquoAktivldquo setzen
Release Notes BALVI Schnittstellenserver Seite 4 von 37
Oberflaumlche ein neuer Menuumlpunkt bdquoETL-Tasksldquo ergaumlnzt der jedoch in der Datei bdquocontextxmlldquo aktiviert werden muss
Um den Menuumlpunkt zu aktivieren ergaumlnzen Sie in der Konfiguration folgenden Parameter
lt--ETL spezifische Erweiterungen ab BSS 31 --gt
ltEnvironment
name=isEtlTaskViewEnabled
value=true
type=javalangBoolean override=true
gt
Zudem wurden die folgenden Parameter ergaumlnzt damit im Datenabgleich Performance-Tuning moumlglich ist
lt-- Timeout-Einstellungen --gt
lt-- Wartezeit in Sekunden bei Requests Standard 60 --gt
ltEnvironment
name=xmlgenrestRequestTimeoutSeconds
value=60
type=javalangInteger override=true
gt
lt-- Anzahl an angefragten Ergebnisdatensaumltzen pro Requests Standard 20 --gt
ltEnvironment
name=xmlgenmaxEntriesPerRestRequest
value=20
type=javalangInteger override=true
gt
Zudem die Ausgabe der Java-Protokolle und deren Anzeige in der Oberflaumlche uumlberarbeitet In diesem Zusammenhang wurde ermoumlglicht dass der Tomcat-Administrator die Liste der Dateitypen angibt die beim Export der LOG-Dateien gesucht und in den Download eingepackt werden sollen
lt-- Neu ab BSS 32 auf Wunsch einiger Kunden (OPTIONAL) --gt
lt-- Welche Dateierweiterungen sollen als Default
fuumlr LOG-Dateien verwendet werden (Standard log txt) --gt
ltEnvironment
name=extensionsOfLogFiles
value=log txt out gz
type=javalangString override=true
gt
Die Ausgabe der Fachprotokolle in der Oberflaumlche wurde ebenfalls uumlberarbeitet so dass nun ein Datumsfilter bdquo(Heute ndash 1 Monat)ldquo vorbelegt wurde Neu ergaumlnzt wurde die Moumlglichkeit in der Suche die Anzeige von allen Protokollsaumltzen (Standard ist bdquoNur Kopfsaumltzeldquo) wieder mit auszugeben
Release Notes BALVI Schnittstellenserver Seite 5 von 37
12 Neuerungen in Version 30 Der BSS 3x beinhaltet alle Funktionalitaumlten des BSS 28x und ist daher abwaumlrtskompatibel
Zusaumltzlich ist es ab Version 3x moumlglich Synchronisations-Jobs zu verarbeiten die mit der OpenSource ETL- Engine bdquoPentaholdquo durch BALVI entwickelt werden Damit wird der BSS auf das zukuumlnftige BALVI iP2 vorbereitet In diesem Zuge wurden diverse Funktionalitaumlten aktualisiert
Beim Update von BSS 2x auf BSS 3x muumlssen an der Datei bdquocontextxmlldquo folgende Anpassungen vorgenommen werden bevor der Server gestartet werden darf
1 Neuer Parameter isJobServiceEnabled
Der Parameter availableServices wurde durch isJobServiceEnabled ersetzt (siehe Kapitel 2516) Damit ist der Jobservice standardmaumlszligig aktiv Empfehlung Suchen Sie availableServices und entfernen Sie diese Einstellung
2 Neue Logging-Konfiguration
Zu BSS 30 wurde auf eine neue Logging-Klasse umgestellt (siehe Kapitel 26) Ersetzen Sie im Ordner conf die vorhandene Datei bdquolog4j-commserverxmlldquo durch die Datei bdquologback-bssxmlldquo um den neuen APPENDER nutzen zu koumlnnen Entfernen Sie log4jConfigLocation und fuumlgen Sie loggingconf hinzu Tragen Sie in der Datei bdquocontextxmlldquo beim neuen Parameter loggingconf den Pfad zur Datei bdquologback-bssxmlldquo ein Die Logging-Funktionalitaumlt des Servers ist davon nicht betroffen
3 Datenbank-Verbindung bdquofactoryldquo umstellen
Bis Version 28 wurde aus Kompatibilitaumltsgruumlnden zu Tomcat 6 als DBCP-Factory noch auf orgapachecommonsdbcpBasicDataSourceFactory verwiesen Ab Tomcat 7 wird jedoch empfohlen die Tomcat-eigene Umsetzung zu verwenden Aumlndern Sie dazu die Angabe factory= in der bdquojdbcDataSourceldquo auf factory=orgapachetomcatjdbcpoolDataSourceFactory Die Verwendung von commonsdhcp wird nicht mehr empfohlen da die Tomcat-spezifische Datasource orgapachetomcatjdbc diverse interne Mechanismen bereitstellt die den Datenbankzugriff aus Apache Tomcat verbessern Dazu gehoumlren die Interceptor-Einstellungen die im Beispiel von BALVI bssxmlexmaple ergaumlnzt wurden (siehe Kapitel 2511)
Release Notes BALVI Schnittstellenserver Seite 6 von 37
4 ETL-Prozesser
Neue Datenquellen ergaumlnzen
Fuumlr die Kommunikation zwischen iP2 Modulen und iP1 wird Kettle benutzt In die contextxml muss dafuumlr eine zusaumltzliche DataSource eingefuumlgt werden wenn Sie die Daten-Uumlbermittlung von IP1 an IP2 verwenden
Die jdbcKettleIP1DataSource ist im Beispiel auskommentiert verwendet derzeit jedoch immer die Zugangsdaten die Sie auch in der jdbcDataSource eingestellt haben da derzeit beide Datenbank-Verbindungen auf das angebundene BALVI iP (124x) zugreifen sollen Beachten Sie jedoch dass die jdbcKettleIP1DataSource die Einstellung type=debalvikettleKettleDataSourceSettings (nicht javaxsqlDataSource) verwendet damit diese nur und ausschlieszliglich dann geladen wird wenn die Kettle-Engine eine separate Datenbankverbindung benoumltigt Um ETL-Engine (Kettle) mitzuteilen welche DataSource das auszufuumlhrende Modul benoumltigt sind folgende Umgebungseinstellungen in die Datei bdquocontextxmlldquo einzufuumlgen
Beispiel
ltResource
name=jdbcKettleIP1DataSource
auth=Container
type=debalvikettleKettleDataSourceSettings
factory=orgapachetomcatjdbcnamingGenericNamingResourcesFactory
maxActive=3 maxIdle=2 minIdle=1 initialSize=1
gt
Kettle Bibliotheken
Da Kettle fuumlr die Ausfuumlhrung verschiedene Dateien benoumltigt muss zudem der Parameter bdquokettlePluginDirectoryldquo eingestellt werden Weisen Sie dem Wert (bdquovalue=ldquo) den Pfad zu dem Verzeichnis zu in dem die Ausfuumlhrungsdateien liegen Die erforderlichen Dateien sind Bestandteil der Auslieferung
ltEnvironment
name=kettlePluginDirectory
value=hometest_ip2_bsskettleplugins
type=javalangString
override=true
gt
13 Hinweise zum Update von aumllteren Versionen (vor 30x) Ab BSS 282 wird eine bdquoserverIDldquo erwartet Daher ist es zwingend erforderlich die vorhandene Datei bdquocontextxmlldquo zu erweitern und den neuen Environment-Parameter bdquoserverIDldquo zu ergaumlnzen
Release Notes BALVI Schnittstellenserver Seite 7 von 37
14 Nacharbeiten nach dem Update auf Version 28
(ADMIN) Sofern Sie schon aktive bdquoJobsldquo im BSS in Verwendung haben werden diese mit dem Update automatisch deaktiviert da die Jobs nun an den ausfuumlhrenden Server gebunden werden muumlssen Oumlffnen Sie dazu den Job in der Detailansicht setzen Sie den Haken hinter bdquoJob an Server bindenldquo setzen und speichern Sie die Einstellung
Der Job wird anschlieszligend in der Uumlbersicht wieder mit dem Status bdquoAktiviertldquo angezeigt Diesen Konfigurationsschritt muumlssen Sie nun jedes Mal durchfuumlhren nachdem die Datenbank von Produktion auf Test geklont wurde
15 Neuerungen in Version 28
151 Jeder Schnittstellen-Server benoumltigt eine Kennung bdquoserverIDldquo Viele Kunden nutzen den Schnittstellenserver mehrfach in Ihrer Umgebung da mehrere BALVI iP Installationen (z B Produktion und Test) in der Infrastruktur existieren
Da die Schnittstellenkonfiguration fuumlr den BSS in der Datenbank abgelegt wird kam es in manchen Faumlllen vor dass nach dem Klonen der Produktionsdatenbank auf ein Testsystem die im BSS angelegten Jobs sofort nach dem Start in der Testumgebung wieder angesprungen sind Um dieses Problem zu beseitigen muss jedem BSS ab Version 28 eine eindeutige bdquoserverIDldquo zugewiesen werden Diese Server-ID wird in der Datei bdquocontextxmlldquo hinterlegt um neutral zur Datenbank zu sein
Ist keine Environment-Variable bdquoserverIDldquo vorhanden wird der Start des BSS 28 (oder houmlher) sofort mit einer Fehlermeldung abgebrochen Im Server-Protokoll wird dabei der Fehler bdquoERROR [IdentityServiceImpl] serverID must not be emptyrdquo ausgegeben Danach kommt sofort die Meldung dass der BSS wieder heruntergefahren wird
INFO [localhost-startStop-1] [ContextCreationListener]
BALVI-Schnittstellen-Server
Version 280
hellip
ERROR [localhost-startStop-1] [IdentityServiceImpl] serverID must not be empty
ERROR [localhost-startStop-1] [ContextLoader] Context initialization failed
Um eine ldquoserverIDrdquo zu vergeben fuumlgen Sie in der Datei bdquocontextxmlldquo folgende Angabe ein
lt--
Release Notes BALVI Schnittstellenserver Seite 8 von 37
ID fuumlr den Server
Diese muss pro Schnittstellenserver eindeutig sein
Eine Aumlnderung dieser ID fuumlhrt sofort dazu dass alle
eingerichteten Server-Jobs inaktiv werden und neu mit
der Instanz gekoppelt werden muumlssen um wieder aktiviert
werden zu koumlnnen
Als value kann ein Text der max Laumlnge von 32 Zeichen
vergeben werden z B ProductionEnvNode1 fuumlr die Produktion
und TestEnvNode1 fuumlr die Testumgebung
--gt
ltEnvironment
name=serverID
value=ProductionEnvNode1
type=javalangString
override=true
gt
152 Optional ist nun eine Namensvergabe moumlglich Auf Wunsch mehrerer Kunden wurde die Option geschaffen jedem Server zusaumltzlich einen kundenspezifischen bdquoTitelldquo zu geben um die Server besser unterscheiden zu koumlnnen
lt--
Visueller Name des Servers in der Oberflaumlche
(Optional)
--gt
ltEnvironment
name=serverName
value=TIERZ Tomcat 8 Java 8 mit BALVI_TIERZXGEWETLBTR_BSS
type=javalangString
override=true
gt
Der hier angegebene Text wird in der Kopfzeile zwischen den eckigen Klammern ausgegeben
Release Notes BALVI Schnittstellenserver Seite 9 von 37
2 Einrichtungshinweise
21 Allgemeine Hinweise zum Betrieb
211 Kompatibilitaumlt zu Apache Tomcat und Java SE Der BALVI Schnittstellenserver wurde getestet und freigegeben fuumlr Apache Tomcat 8 (ab Version 8030 oder neuer) Zudem wurde die aktuellste (letzte offizielle) Version von Java SE 8 getestet und kann verwendet werden (Java SE 8u40 und neuer)
Installieren Sie stets die aktuellsten Sicherheitsupdates fuumlr Java SE 8 Beachten Sie dabei jedoch dass nicht die Aktualisierung auf eine andere Java-Version (z B Java 9) gemeint ist
Freigegebene Major-Versionen werden explizit von BALVI benannt Falls Sie beabsichtigen die Major-Version zu aumlndern pruumlfen Sie bitte die aktuellen Release Notes oder kontaktieren die BALVI Kundenbetreuung
212 Oracle Java SE Lizenzierung Java SE beinhaltet auch kostenpflichtige Funktionen fuumlr deren Nutzung Oracle Lizenzgebuumlhren fordert wenn sie bei der Entwicklung eingesetzt werden Die von BALVI gelieferte Software ist frei von den kommerziellen Teilen der Oracle Java SE nutzbar Fuumlr den Einsatz von Oracle Java SE (einschlieszliglich JDK und JRE) fallen im Rahmen der Nutzung der BALVI Software keine Lizenzkosten an
Trotzdem werden wir parallel pruumlfen ob technische Probleme bei der Umstellung auf das OpenJDK zu erkennen sind Ein einfacher Funktionstest hat im BSS 3x noch keine technischen Probleme gezeigt als wir die Laufzeitumgebung auf das OpenJDK 8U111 AMD64 (Debian) umgestellt haben Bitte haben Sie Verstaumlndnis dafuumlr dass wir keine Funktionstests fuumlr jedes Linux-Derivat durchfuumlhren koumlnnen und dass es offiziell keine Version des OpenJDK fuumlr Windows Betriebssysteme gibt
213 Einsatz von TLSSSL BALVI hat keine spezifischen Anforderungen an die Konfiguration von SSL bzw TLS Der Einsatz von TLS 12 gem der Richtlinie TR-02102-2 vom BSI ist moumlglich wenn Sie sich an die von Apache Tomcat herausgegebene Dokumentation halten Es sind keine Anpassungen des Schnittstellenservers erforderlich Daher gehen wir davon aus dass auch der BSS 28x oder aumllter in einem Apache Tomcat mit TLS 12 betrieben werden kann
Das gilt jedoch nicht fuumlr alle Clients die den Tomcat-Server ansprechen moumlchten So ist z B erst ab BALVI mobil 191958 sichergestellt dass die Protokolle TLS 11 und TLS 12 programmseitig aktiviert sind Fuumlr Details zu diesem Problem wurde ein separates Rundschreiben per E-Mail versendet
Release Notes BALVI Schnittstellenserver Seite 10 von 37
214 Nutzung von Java-Proxyeinstellungen Der BALVI Schnittstellenserver verwendet fuumlr ausgehende Verbindungen die Java-Net Einstellungen welche in der Java-Dokumentation1 beschrieben sind Falls Sie Jobs einsetzen welche ausgehenden Zugriff auf Adressen im Internet benoumltigen kann es passieren dass Sie z B eine bdquojavanetUnknownHostExceptionldquo im Protokoll finden dann muumlssen Sie ihre Proxy-Umgebung in den Java-Umgebungseinstellungen ergaumlnzen
Die folgenden Parameter sollten daher in Ihrer Umgebung gesetzt werden wenn der Zugriff auf das Internet nur uumlber einen Proxy moumlglich ist
-DproxySet=true
-DproxyHost=10111213
-DproxyPort=8888
-DhttpnonProxyHosts=domainorg|localhost|10
Starten Sie nach Aumlnderung der Einstellungen den Server neu damit die Einstellungen wirksam werden
2141 Proxy-Einstellung unter Windows (Tomcat-Dienst)
Verwenden Sie das Dienste-Konfigurationsprogramm (z B tomcat7wexe) und ergaumlnzen Sie die fehlenden Einstellungen
2142 Proxy-Einstellung unter Linux
In Linux wird in der Konfigurationsdatei (z B conftomcat7conf) die Variable bdquo$JAVA_OPTSldquo entsprechend erweitert und die Werte uumlbergeben Beachten Sie dabei dass die Variablen von Linux (bzw der Bash) gelesen werden Daher muss das bdquoPipeldquo-Zeichen bdquo|ldquo mit bdquoldquo maskiert werden ansonsten erhalten Sie bei der Verarbeitung der Umgebungsvariable bdquohttpnonProxyHostsldquo Fehlermeldungen in der Linux -Konsole welche dazu fuumlhren dass Java nicht korrekt konfiguriert werden kann
JAVA_OPTS=$JAVA_OPTS -DproxySet=true -DproxyHost=10111213 -DproxyPort=8888
JAVA_OPTS=$JAVA_OPTS -DhttpnonProxyHosts=domainorg|localhost|10
1 httpdocsoraclecomjavase8docstechnotesguidesnetpropertieshtml
Release Notes BALVI Schnittstellenserver Seite 11 von 37
215 Spracheinstellung Deutsch Es wurde festgestellt dass unter einigen Linux-Versionen die Spracheinstellung beim Starten des Apache Tomcat nicht auf eine deutsche Umgebung verweist Dieses kann technische Probleme verursachen Unter Linux sollte die Einstellung (Umgebungsvariable) entsprechend auf LANG=de_DEUTF-8 eingestellt sein
216 Datenbankverbindung Wenn Sie eine Firewall zwischen dem Oracle-Server und dem Database Connection Pool (DBCP) verwenden sollte unbedingt die bdquovalidationQueryldquo in der DBCP-Konfiguration aktiviert werden damit die Anwendung schneller freie Connections aus dem Pool erhalten kann Die Dokumentation zu den Einstellmoumlglichkeiten ist in der beiliegenden Contextxml ergaumlnzt worden
Bitte beachten Sie dass dringende empfohlen wird die bdquoFactoryldquo auf orgapachetomcatjdbcpoolDataSourceFactory anzupassen falls sie noch auf bdquoorgapachecommonsdbcpBasicDataSourceFactoryldquo eingestellt ist
217 Probleme beim Anlegen von LOB-Objekten Der BALVI Schnittstellen-Server erfordert die JDBC-Spezifikation DBCP V4 welche durch die Factory bdquoorgapachetomcatjdbcldquo ab Tomcat 7 automatisch bereitgestellt wird
Wenn die Pooling-Komponente oder der Oracle-Treiber nicht JDBC4-Kompatibel sind gibt es beim Bearbeiten von LOB-Objekten in Java diverse Exceptions z B
Servletservice() for servlet soapws threw exception
javalangAbstractMethodError
orgapachecommonsdbcpPoolingDataSource$PoolGuardConnectionWrappercreateClob()LjavasqlClob
at debalvicoreauditspyConnectionSpycreateClob(ConnectionSpyjava511)
Ursache dieses Problems ist meistens dass noch nicht auf bdquoorgapachetomcatjdbcldquo umgestellt wurde
218 Umbenennung der gelieferten WAR-Datei Das im Paket von BALVI gelieferte WAR kann jederzeit umbenannt werden (z B als ROOTwar) ohne dass dabei spezielle Einstellungen in der Datei bdquocontextxmlldquo erforderlich sind
Beachten Sie dabei jedoch dass die zum WAR zugehoumlrige Datei bdquocontextxmlldquo im Apache Tomcat immer denselben Namen erhaumllt wie das WAR z B bdquocommserverwarldquo und bdquocommserverxmlldquo Der Name ist dabei ausschlaggebend fuumlr die Zugriffs-Adresse (Context) im Apache Tomcat selbst Die Benennung des WAR in bdquocommserverwarldquo wuumlrde folgendermaszligen aufzurufen sein httpserverportcommserver
219 Server-Schnittstellen Die Uumlberarbeitung bzw Erweiterung der Export- und Importschnittstellen welche uumlber den Schnittstellenserver bereitgestellt werden ist unabhaumlngig vom Schnittstellenserver selbst Die Schnittstellen sind daher nicht Bestandteile des Schnittstellenserver und werden je Verfahren separat
Release Notes BALVI Schnittstellenserver Seite 12 von 37
ausgeliefert Ggf ist es fuumlr unterschiedliche Schnittstellen erforderlich die Grant-Rechte zu aktualisieren (Vgl bdquoWann ist die Ausfuumlhrung des Grant-Skripts erforderlichldquo)
22 Kompatibilitaumltsliste Diverse Verfahren setzen eine Mindestversion des BALVI Schnittstellenservers voraus Die Schnittstellen sind jedoch so konzipiert dass eine Aktualisierung auf eine houmlhere Version des Servers ohne Anpassung an den vorhandenen Schnittstellen jederzeit moumlglich ist
Derzeit sind folgende Mindestanforderungen gegeben
1 BALVI mobil XT 170 oder houmlher setzt BSS 265 und BALVI iP 124x voraus
2 BALVI mobil XT 183 oder houmlher setzt BSS 281 und BALVI iP 124x voraus
3 BALVI mobil 2 (DM) setzt BSS 311 und BALVI iP 124x voraus
4 Die Schnittstelle eFI setzt BSS 251 und BALVI iP 122c voraus
5 Die Schnittstelle LIMS setzt BSS 265 voraus
6 Die Schnittstelle TSK (SN) setzt BSS 265 voraus
7 Die Schnittstelle xDomea (SN) setzt BSS 265 und Java 7 voraus
8 Die Schnittstelle XGewerbeanzeigen 11 setzt BSS 281 BALVI iP 124x Java 8 mit der bdquoJava
Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy2ldquo voraus
9 Die Schnittstelle XGewerbeanzeigen 12 (ab Paket 7 Ausbaustufe 3) setzt BSS 302 BALVI iP
124x Java 8 mit der bdquoJava Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policyldquo
voraus
10 Die Schnittstelle RioPP LM (NRW) setzt BSS 303 und die ETL-Konfiguration voraus
11 Die Schnittstellen zu BALVI iP2 (Fachmodule BTS LM ZDA Stand Juni 2017) setzen BSS 32x
voraus
2 httpwwworaclecomtechnetworkjavajavasedownloadsjce8-download-2133166html
Release Notes BALVI Schnittstellenserver Seite 13 von 37
23 Erforderliche Bibliotheken fuumlr Apache Tomcat Dateiname Funktion Quelle ojdbc6jar Oracle 11gR2 Clientpaket Oracle JDBC Client fuumlr Java
16 ersetzt die bisherige Version bdquoojdbc14jarldquo Die alte Library muss auf jeden Fall entfernt werden
httpwwworaclecomtechnetworkdatabaseenterprise-editionjdbc-112010-090769html
encrypted-datasource-110-alljar
Die Library muss auf jeden Fall entfernt werden Wird derzeit nicht weiter gepflegt da kein Interesse an der Funktionalitaumlt bestand
slf4j-api-1511jar slf4j-log4j12-1511jar log4jdbc4-12beta2jar
Entfaumlllt nicht mehr erforderlich Es wird empfohlen diese zu entfernen falls diese im LIB-Verzeichnis vorhanden sein sollten
commons-dbcp-14jar commons-pool-154jar
Entfaumlllt nicht mehr erforderlich Es wird empfohlen diese zu entfernen falls diese im LIB-Verzeichnis vorhanden sein sollten
Erwartet wird stattdessen ab Tomcat7 die mitgelieferte bdquotomcat-jdbcjarldquo
log4j-1217jar (oder houmlher)
Logging-Funktionalitaumlt Apache Log4j httploggingapacheorglog4j12downloadhtml
bcprov-jdk15on-157jar (oder houmlher)
BouncyCastle Security Provider fuumlr SSLAES hellip wird ab Version 27 im Ordner bdquolibldquo des Tomcat erwartet Sollte es aus Sicherheitsgruumlnden erwuumlnscht sein eine aktuellere Version einzusetzen ist dieses idR moumlglich
httpmvnrepositorycomartifactorgbouncycastlebcprov-jdk15on157
24 Datenbank-Installation Der BALVI Schnittstellenserver benoumltigt auszligerhalb des angebundenen BALVI iP keine eigenen Tabellen Die Web-Anwendung kann im einfachsten Fall direkt auf das Schema von BALVI iP zugreifen indem der Benutzer und das Passwort des BALVI iP-Schemas in der Datei bdquocontextxmlldquo eingetragen werden (nicht empfohlen)
Sollte dies aus Sicherheitsgruumlnden nicht erwuumlnscht sein (empfohlen vom BSI und von BALVI) finden Sie im Paket ein GRANT-Skript um Zugriffsrechte vom BALVI iP Schema fuumlr den Webservice-Schema-Benutzer einzurichten
Zwischen dem Schema von BALVI iP und jeder Web-Anwendung ist dann eine Trennung moumlglich um sicherzustellen dass der Datenbank-Benutzer welcher in der Tomcat-Konfiguration fuumlr die Web-Anwendung eingetragen wird geaumlndert oder geloumlscht werden kann ohne dass die Windows-Anwendung BALVI iP davon betroffen ist Zudem vergibt das von BALVI gelieferte Grant-Skript keine Rechte zum Loumlschen von Tabellenstrukturen oder Tabelleninhalten so dass der Webservice nur festgelegte Daten aumlndern oder lesen darf Es wird empfohlen je Web-Anwendung einen eigenen Datenbank-Benutzer zu vergeben wenn Sie ein BALVI iP mit mehreren Webservices verbinden wollen
Die Moumlglichkeiten im Uumlberblick
1) Sie betreiben den Webservice mit einem eigenstaumlndigen Oracle-Benutzer In diesem Fall muss das
Grant-Skript ausgefuumlhrt werden um den Webservice-Benutzer und den BALVI iP-Benutzer
miteinander zu koppeln
2) In der Tomcat-Konfiguration wird der Oracle-Benutzer eingetragen welcher auch der BALVI iP
Schemabesitzer ist und in der bdquobalviip_conninildquo hinterlegt ist (NICHT Empfohlen) Der Webservice
Release Notes BALVI Schnittstellenserver Seite 14 von 37
hat 100 Zugriffsrechte (auch Loumlsch- oder Aumlnderungsrechte am Schema) es wird kein Grant-
Skript benoumltigt
Wenn Sie die Konfiguration 2) waumlhlen moumlchten koumlnnen Sie die folgenden Unterkapitel uumlberspringen und in Kapitel 0 bzw fortsetzen
241 Erstinstallation Datenbank-Benutzer anlegen Wenn Sie den Webservice-Benutzer vom BALVI iP Schema trennen moumlchten muss durch die DB-Administration in der Oracle-Server-Instanz wo auch BALVI iP sein Schema besitzt ein Benutzer (ggf je Web-Anwendung) angelegt werden welcher folgende Rechte benoumltigt
CONNECT
ALTER SESSION
CREATE JOB
CREATE PROCEDURE
CREATE SESSION
CREATE TABLE
CREATE TRIGGER
CREATE TYPE
CREATE VIEW
CREATE SEQUENCE
CREATE SYNONYM
QUERY REWRITE
Der Default-Tablespace ist frei waumlhlbar Der Benutzer braucht das Recht QUOTA UNLIMITED auf den Tablespace von BALVI iP (Default BALVI_IP) Ein Beispiel-Create-Skript bdquooraCreate_WEB_Usersqlldquo liegt der Auslieferung bei
242 Rechte zuweisen Wenn der BALVI iP Schemabesitzer NICHT in der Tomcat-Umgebung eingetragen werden soll muss ein Oracle DBA das beiliegende GRANT-Skript bdquooraGrantIP_to_Websqlldquo ausfuumlhren um dem jeweiligen Webservice (in Tomcat verwendeten Oracle-Benutzer) die minimalen Rechte auf das Schema von BALVI iP zu gewaumlhren
Dieses Skript setzt voraus dass es von einem Oracle Administrator als bdquoUser SYSTEMldquo ausgefuumlhrt wird Lesen Sie die im Skript enthaltenen README-Kommentare und passen Sie die Benutzer (BALVI iP Schema) und (WEB-Schema) an
====================================================
DEKLARATIVER TEIL MUSS vom KUNDEN geaumlndert
bzw auf die korrekten SCHEMA-Namen angepasst
werden
Die USER-Namen muumlssen in Groszligbuchstaben
geschrieben sein sonst werden sie nicht
gefunden
====================================================
sUserBALVI_IP = BALVI_IP_SCHEMABESITZER
sUserBALVI_WEB = BALVI_WEB_SCHEMABESITZER
Release Notes BALVI Schnittstellenserver Seite 15 von 37
Neu ab Grant-Skript 158 ist die Umbenennung der Verfahrenszuordnung
Pruumlfen Sie dass die Einstellung fuumlr Ihr BundeslandVerfahren korrekt ist dort muss eine 1 fuumlr min ein Verfahren gesetzt sein Diese Einstellung befindet sich direkt unter den Schemabesitzer-Angaben
-- Verfahrensbezogene Konfiguration
-- Setzen Sie fuumlr das jeweilige Verfahren eine 1
-- BALVI Schnittstellenserver (BSS)
-- bis V266 auch BALVI Kommunikationsserver (BKS) genannt
-- generell fuumlr die meisten Verfahren guumlltig
-- Ab Version 57 entfaumlllt mit der Einfuumlhrung der
-- Schnittstelle XGewerbeanzeigen auch der separate Schalter
-- WS_BTR beide Verfahren wurden vereinheitlicht
WS_BSS = 1
Fuumlhren Sie das Skript nach der Anpassung als User SYSTEM aus um die Grants durchzufuumlhren Dieses wurde mit dem von ORACLE gelieferten Programm SQLPLUS (Command-Line) SQLPLUS Worksheet (GUI) und Oracle SQL-Developer getestet
Das Skript generiert fuumlr jedes Objekt ein SYNONYM fuumlr den WEB-USER so dass dieser auf die Objekte ohne Angabe des Owners des IP-Schemas zugreifen kann Pruumlfen Sie nach der Ausfuumlhrung dass die SYNONYMS vorhanden und VALID sind dieses kann ggf nicht der Fall sein Das Skript kann jederzeit erneut ausgefuumlhrt werden um die Grants neu zu erzeugen und bietet ebenfalls die Option alle Grants und Synonyme wieder zu entfernen Detaillierte Informationen zur Nutzung des Skripts sind als Kommentar-Block im Skript enthalten
Hinweis Die Versionsinformation ist unter den Kommentaren direkt im Skript zu finden
Zugriffsberechtigungen fuumlr Webanwendungen auf BALVI iP anlegen
===============================================================
Version 158
Guumlltig fuumlr BALVI iP 123 oder houmlher
Autor Frank Holler
SVN Revisionsinformationen
$Revision 479 $
$Date 2016-02-15 152755 +0100 (Mo 15 Feb 2016) $
================================================================
243 Wann ist die Ausfuumlhrung des Grant-Skripts erforderlich Durch das Strukturupdate von BALVI iP (z B 1240 auf 1241) werden veraltete Strukturen geloumlscht und ggf neue Views oder Tabellen angelegt Die Grant-Rechte geht dabei ggf verloren Daher ist die Ausfuumlhrung des Grant-Skripts immer dann erforderlich wenn sich die Datenbank-Struktur von BALVI iP veraumlndert
Zudem kann es fachliche Neuerungen geben welche im alten Grant-Skript nicht vorhanden sind Daher muss das Skript ggf auch ausgefuumlhrt werden wenn eine neue Schnittstelle im Schnittstellenserver bereitgestellt wurde Dieses betrifft z B auch die Bereitstellung von neuen Versionen von BALVI mobil XT
Release Notes BALVI Schnittstellenserver Seite 16 von 37
da auch dort mit einem fachlich erweiterten Client die Moumlglichkeit besteht dass neue Schnittstellen bereitgestellt und somit mehr Schreibrechte auf Tabellen benoumltigt werden
244 Welche Version des Grant-Skripts soll ich nehmen Wie der Schnittstellenserver sind auch die Grant-Skripte versioniert Neuere Versionen des Grant-Skriptes sind abwaumlrts-kompatibel und koumlnnen immer verwendet werden auch wenn in einer Schnittstellenbeschreibung eine aumlltere Version des Grant-Skriptes explizit benannt wurde
245 Kombination von mehreren Verfahren Wenn Sie zwei oder mehr Schnittstellen im BSS verwenden moumlchten ist es ggf erforderlich auch mehrere Verfahren auf aktiv (bdquo1ldquo) zu setzen
Im Beispiel nehmen wir an Sie moumlchten bdquoeFildquo und bdquoBALVI mobil XTldquo im Schnittstellenserver bereitstellen In der Beschreibung von bdquoeFildquo steht dass das Grant-Skript V36 erforderlich ist BALVI mobil XT 18 erfordert jedoch schon V56
Wenn Sie beide Verfahren betreiben ist im Grant-Skript (V56 oder houmlher) die Einstellung fuumlr beide Verfahren zu aktivieren
====================================================
DEKLARATIVER TEIL MUSS vom KUNDEN geaumlndert
bzw auf die korrekten SCHEMA-Namen angepasst
werden
Die USER-Namen muumlssen in Groszligbuchstaben
geschrieben sein sonst werden sie nicht
gefunden
====================================================
sUserBALVI_IP = BALVI_IP_SCHEMA
sUserBALVI_WEB = WEBAPP_SCHEMA
-- Verfahrensbezogene Konfiguration
-- Setzen Sie fuumlr das jeweilige Verfahren eine 1
-- BALVI Schnittstellenserver (BSS)
-- bis V266 auch BALVI Kommunikationsserver (BKS) genannt
-- generell fuumlr die meisten Verfahren guumlltig
-- Ab Version 57 entfaumlllt mit der Einfuumlhrung der
-- Schnittstelle XGewerbeanzeigen auch der separate Schalter
-- WS_BTR beide Verfahren wurden vereinheitlicht
WS_BSS = 1
-- WebService BTR (Betriebsstaumlttenregister) (NRW TH)
-- entfernt mit Update V57 setzen Sie stattdessen bei WS_BSS = 1
--WS_BTR = 0
-- Probenahme Futtermittel im Browser(BY)
WS_PROBE_FM = 0
-- Risikoorientierte Probenplanung Futtermittel ndash RIOPP FM (BY)
WS_RIOPP_FM = 0
-- Verfahren Export an EFi (Status Pilotbetrieb)
WS_EFI = 1
-- neu ab Version 35 des Grant-Skriptes ist die Moumlglichkeit den Webuser
Release Notes BALVI Schnittstellenserver Seite 17 von 37
-- fuumlr das Loumlschen der Ausgangskoumlrbe explizit zu berechtigen bzw sogar einen
-- expliziten abweichenden User festzulegen Die Konfiguration in der
-- Job-Oberflaumlche sieht vor dass man die Oracle-Datenbank-Zugangsdaten fuumlr
-- das Loumlschen einstellen muss Hier muss im Normalfall derselbe Oracle
-- Datenbankbenutzer eingetragen werden wie in der Tomcat-Verbindungs-
-- konfiguration In diesem Fall sollte wenn WS_EFI = 1 eingestellt wurde
-- ebenfalls WS_EFI_DELETE = 1 eingestellt werden
-- Alternativen
-- 1) Datenbankbenutzer aumlndern
-- Wenn bei sUserEFI_TRUNC anstatt sUserBALVI_WEB (Standard) ein anderer
-- Oracle-Benutzername angegeben wird wird das Loumlschrecht fuumlr die EFi
-- Ausgangskoumlrbe Datenbankseitig exklusiv dem angegeben Datenbankbenutzer
-- zugewiesen
-- 2) Loumlschrecht verweigern
-- Setzen Sie die Variablen WS_EFI_DELETE = 0 damit kein Loumlschrecht
-- zugeweisen wird
WS_EFI_DELETE = 0
-- Beispiel Anderer Benutzer muss in der Datenbank existieren
-- Entfernen Sie die fuumlhrenden -- vor der Variable sUserEFI_TRUNC und
-- setzen den entsprechenden Oracle-Benutzer ein
--sUserEFI_TRUNC = TEST_EFI_TRUNC
hellip
25 Konfiguration des Schnittstellen-Servers
251 Die bdquocontextxmlldquo-Parameter Die von der Servlet-Spezifikation vorgegeben Rump-Struktur sieht folgendermaszligen aus
ltxml version=10 encoding=utf-8gt
ltDOCTYPE Contextgt
ltContextgt
lt-- Kundenspezifische Einstellungen --gt
ltContextgt
Anwendungsspezifische Einstellungen werden zwischen ltContextgt und ltContextgt eingefuumlgt Alle allgemeinguumlltigen Einstellungen in der Datei bdquocontextxmlldquo werden hier erlaumlutert Kommentare finden sich auch in der von BALVI ausgelieferten Beispiel-Konfiguration
Neben den im Folgenden beschriebenen Standard-Einstellungen kann es auch vorkommen dass bundeslandspezifische Erweiterungen vorhanden sind welche nicht in dieser Dokumentation aufgefuumlhrt werden Diese funktionieren trotzdem regulaumlr weiter wenn keine expliziten Informationen zu Kompatibilitaumltsproblemen in den Release-Notes aufgefuumlhrt wurden
2511 Datenbankverbindung jdbcDataSource
Die Datenbankverbindung wird uumlber die von DBCP und dem Oracle-Treiber vorgegebenen Moumlglichkeiten realisiert Der Einsatz der orgapachetomcatjdbcpoolDataSourceFactory (automatisch verfuumlgbar ab Apache Tomcat 7 in der mitgelieferten tomcat-dbcpjar) wird als Beispiel-Konfiguration ausgeliefert
ltResource
name=jdbcDataSource
auth=Container
Release Notes BALVI Schnittstellenserver Seite 18 von 37
type=javaxsqlDataSource
factory=orgapachetomcatjdbcpoolDataSourceFactory
maxActive=10 initialSize=3
maxIdle=5
maxWait=10000
url=jdbcoraclethinBL2-ORA10-KUNDENBALVIINTERN1521ORCL
driverClassName=oraclejdbcdriverOracleDriver
username=balvi_webservice_schema
password=balvi_webservice_password
description=Oracle Datasource
maxOpenPreparedStatements=50
removeAbandoned=false
removeAbandonedTimeout=100
logAbandoned=true
jdbcInterceptors=hellip
gt
Hinweise zur Einstellung der jdbcDataSource
Standard-Einstellungen fuumlr den Datenbank-Verbindungspool
Der Verbindungspool muss entsprechend der Anzahl der zu erwartenden gleichzeitigen Benutzer konfiguriert werden Wenn Sie erwarten dass 50 Anwender gleichzeitig arbeiten stellen Sie bitte folgende Werte ein
maxActive=(50 + 10 (fuumlr System und Jobs)) = 60
maxIdle= (50 10) = 5
1 maxActive - maximale Anzahl der gleichzeitigen aktiven Anfragen an die DB
Wenn der Werte maxActive erreicht ist z B wenn mehrere Benutzer gleichzeitig einen Export starten moumlchten welcher laumlngere Zeit in Anspruch nimmt dann kann der Server die Anfrage nicht mehr bedienen und der Anwender wird abgewiesen maxActive hat zudem Auswirkungen auf die im Hintergrund ausgefuumlhrten Jobs maxActive wird daher kalkuliert mit der Anzahl der Anwender und moumlglicher Datenbank-Connections fuumlr Hintergrund-Jobs Jeder aktiv ausgefuumlhrte Job benoumltigt mindestens eine Connection nur selten wird aus Performance-Gruumlnden mehr als eine Connection waumlhrend der Job-Ausfuumlhrung verwendet Im Normalfall sollten daher 10 Connections fuumlr Hintergrundprozesse ausreichend sein
2 maxIdle - Anzahl der offenen Verbindungen auch wenn der Server im Leerlauf ist
Jede offene Verbindung im Leerlauf haumllt auf dem Datenbankserver eine Session offen Auch diese erfordert Ressourcen Wenn die Verbindungen jedoch geschlossen werden kann die Anfragezeit fuumlr eine neue Verbindung steigen da diese Verbindung erst neu ausgehandelt werden muss Die Empfehlung fuumlr den Wert bdquomaxIdleldquo ist ca 10 der Einstellung von maxActive
KeepAlive-Einstellungen fuumlr den Pool
1 validationQuery
Diese wird ausgefuumlhrt um die Verbindung zu DB zu validieren Es MUSS ein Datensatz zuruumlckgegeben werden ansonsten nimmt der DBCP an dass die Abfrage nicht erfolgreich abgesetzt wurde Achten Sie also bitte darauf dass die Abfrage nicht zu leitungsintensiv ist und genau einen Datensatz liefert
Release Notes BALVI Schnittstellenserver Seite 19 von 37
Oracle bietet dafuumlr die virtuelle Tabelle DUAL an welche sich fuumlr die ValidationQuery sehr gut eignet da die Abfrage kaum Ressourcen verbraucht
validationQuery=select 1 from dual
2 testOnBorrow - Boolscher Wert true oder false
Diese Einstellung sorgt dafuumlr dass der Pool die Verfuumlgbarkeit anhand der validationQuery pruumlft bevor
die DB-Verbindung an die Anwendung ausgeliehen wird Empfehlung
testOnBorrow=true
3 testWhileIdle - Boolscher Wert true oder false
Diese Einstellung ist hilfreich wenn zwischen dem Tomcat und der DB eine Firewall mit Stateful
Packet Inspection verwendet wird Nach laumlngerer Inaktivitaumlt wird normalerweise durch die Firewall die
DB-Verbindung geschlossen Dieses loumlst dann beim Ausleihen der Verbindung eine Fehlermeldung im
Protokoll aus 2012-08-16 165418720 WARN [http-0000-8080-8]
[orgspringframeworkjdbcsupportSQLErrorCodesFactory] Error while extracting
database product name - falling back to empty error codes
orgspringframeworkjdbcsupportMetaDataAccessException Error while extracting
DatabaseMetaData nested exception is javasqlSQLRecoverableException Getrennte
Verbindung Um dieses Problem zu beheben sollte die Option testWhileIdle=true eingestellt werden
testWhileIdle=true
Damit diese weiszlig wie oft eine Pruumlfung durchgefuumlhrt werden muss sind jedoch noch zusaumltzliche Angaben erforderlich welche fuumlr die Einstellung der Zeit zusaumltzlich gesetzt werden muumlssen
a) minEvictableIdleTimeMillis - Long in Millisekunden
Min Zeit wie lange eine DB-Verbindung im Leerlauf ist bevor diese zur Pruumlfung
gekennzeichnet wird Dieses haumlngt stark von der Einstellung der Firewall ab Wenn Sie eine
sehr restriktive Firewall haben kann es sein dass diese die Verbindung nach wenigen
Minuten Leerlauf trennt Stellen Sie den Wert immer so ein dass dieser unter der Leerlaufzeit
der Firewall liegt empfohlen 300000 entspricht 300 Sek = 5 min
minEvictableIdleTimeMillis=300000
b) timeBetweenEvictionRunsMillis - Long in Millisekunden
Der Pruumlflauf startet in der Default-Konfiguration alle 1800000 Millisekunden = 30 Min n als
zu Pruumlfen markierte Verbindungen werden in einem Pruumlflauf getestet n wird bestimmt durch
die Einstellung numTestsPerEvictionRun Empfehlung Stellen Sie den Wert auf alle 15 Min
ein
timeBetweenEvictionRunsMillis=900000
Release Notes BALVI Schnittstellenserver Seite 20 von 37
c) numTestsPerEvictionRun - Integer
Wie viele Verbindungen sollen getestet werden waumlhrend der Pruumlflauf ausgefuumlhrt wird Im
Normalfall sollte die Anzahl der zu testenden Verbindungen nicht zu hoch eingestellt werden
Der Default ist 3 Wenn Sie houmlhere Sicherheit haben wollen dass keine bdquototenldquo
Datenbankverbindungen bestehen bleiben erhoumlhen Sie den Wert auf max bdquo(maxActive ndash
maxIdle) 2ldquo Wenn Ihnen 3 ausreichend erscheint muss der Wert nicht gesetzt sein dann
wird der Default verwendet
Beispiel numTestsPerEvictionRun=10
4 Interceptors konfigurieren Neu ergaumlnzt wurde die Moumlglichkeit spezielle bdquoInterceptorsldquo zu konfigurieren die ermoumlglichen das Verhalten des Pools zu steuern Wichtig hierbei ist dass die Angabe von Werten auf real existierende Java-Klassen erfolgt die im Classpath des Tomcat vorhanden sind Groszlig-und-Kleinschreibung ist zu beachten Folgende Default-Einstellung hat BALVI fuumlr den BSS festgelegt jdbcInterceptors=
orgapachetomcatjdbcpoolinterceptorConnectionState
orgapachetomcatjdbcpoolinterceptorStatementFinalizer
orgapachetomcatjdbcpoolinterceptorResetAbandonedTimer
Details zu den verwendeten Interceptor-Einstellungen finden Sie in der Tomcat-Dokumentation3
3 httptomcatapacheorgtomcat-80-docjdbc-poolhtmlJDBC_interceptors
Release Notes BALVI Schnittstellenserver Seite 21 von 37
2512 Datenbank-Zugangsdaten verschluumlsseln
Die Verschluumlsselung fuumlr die Datenbank-Verbindung (bdquoEncrypted Datasourceldquo) ist eine Ableitung der Bibliothek Apache-Common-DBCP-14 und daher nicht mehr mit Java 8 kompatibel Die Einrichtung der Verschluumlsselung wird daher mit der Auslieferung des BSS 30 nicht mehr angeboten
2513 Active-Directory-Authentifizierung
Uumlber die folgenden Parameter wird der Zugriff des Schnittstellen-Servers auf einen Microsoft Active Directory Domain-Controller konfiguriert
ldquoldapServerAddressrdquo
Syntax PROTOKOLLIP-Adresse oder DNS-NamePORT
ltEnvironment
name=ldapServerAddress
value=ldapbl2-dc02balviintern389
type=javalangString
override=true
gt
Als Protokoll besteht auch die Moumlglichkeit ldaps (LDAP+SSL) wenn der Domain-Controller entsprechend konfiguriert wurde Im Java Truststore muss dann das Zertifikat der CA vorhanden sein welche das Zertifikat des Domain-Controllers signiert hat Zudem darf bei ldaps keine IP-Adresse verwendet werden es muss der DNS-Name des Server-Zertifikats eingetragen sein Ansonsten gibt es beim Verbinden eine Sicherheits-Exception
lt-- SSL-Beispiel
ltEnvironment
name=ldapServerAddress
value=ldapsbl2-dc02balviintern636
type=javalangString
override=true
gt
--gt
bdquoldapBaseDnrdquo
LDAP-Suchpfad fuumlr die Domain-Basis Diese muss der LDAP-Syntax fuumlr den Domain-Suffix entsprechen
Syntax DC=SERVERDC=ROOTDN
ltEnvironment
name=ldapBaseDn
value=DC=BALVIDC=INTERN
type=javalangString
override=true
gt
Release Notes BALVI Schnittstellenserver Seite 22 von 37
bdquowebLoginUseActiveDirectoryAuthenticationrdquo
Die Authentifizierung in der Browser-Oberflaumlche kann uumlber die Active-Directory-Authentifizierung erfolgen In der ersten Version ist nur die Protokoll-Auswertung moumlglich wenn der ADMIN sich anmeldet Dieser hat normalerweise niemals AD-Kennungen zugeordnet BALVI empfiehlt diese Einstellung auf bdquofalseldquo zu belassen Webservices welche uumlber SOAPREST zugreifen koumlnnen die Active-Directory-Authentifizierung trotzdem verwenden
ltEnvironment
name=webLoginUseActiveDirectoryAuthentication
value=false
type=javalangBoolean
override=true
gt
ldquoldapDaysBeforeExpirationNotificationrdquo
Die Passwort-Aumlnderung im Active-Directory uumlber die Browser-Oberflaumlche ist in der ersten Version noch nicht implementiert der Parameter wird bislang nicht ausgewertet
ltEnvironment
name=ldapDaysBeforeExpirationNotification
value=14
type=javalangInteger
override=true
gt
2514 Statement-Protokollierung in BALVI iP
Diese Option aktiviert die Lese- und Aumlnderungsprotokollierung fuumlr BALVI iP Standard ist bdquofalseldquo und wird fuumlr alle Kunden empfohlen solange keine speziellen Datenbank-Jobs eingerichtet wurden welche zeitgesteuert die Protokolleintraumlge wieder loumlschen Fuumlr Bayern wurde ein spezielles Konzept zur Leseprotokollierung entworfen Wenn Sie mehr daruumlber erfahren moumlchten kontaktieren Sie bitte die BALVI GmbH
ltEnvironment
name=enableSqlStatementMonitoring
value=true
type=javalangBoolean
override=true
gt
Beachten Sie dass diese Option massive INSERT-Statements in BALVI iP in die Tabelle VIS_D92 ausfuumlhrt Jedes abgesetzte SQL-Statement wird dabei vollstaumlndig protokolliert Dieses erzeugt eine sehr hohe INSERT-Last und in der Folge auch erhoumlhte Redolog-Switches und COMMIT-Transaktionen
Optional Aktivieren der INSERT + APPEND - Logik
Beachten Sie bitte die Hinweise von Oracle zum Hint + APPEND
Release Notes BALVI Schnittstellenserver Seite 23 von 37
Wenn Sie dieses Verhalten aktivieren moumlchten ergaumlnzen Sie bitte den folgenden Environment-Parameter
ltEnvironment
name=statementMonitoringactivateAppendMode
value=true
type=javalangBoolean
override=true
gt
2515 Einstellungen fuumlr BALVI mobil XT (bzw den bdquopartitionedExportldquo)
Diese Logik des FIFO-Buffers wurde so konzipiert dass dem Rechenzentrum diverse Einstellmoumlglichkeiten uumlber die Datei bdquocontextxmlldquo zur Verfuumlgung stehen um die Steuerung des FIFO-Puffers zu beeinflussen
Schematische Darstellung des FIFO-Puffers
Das ermoumlglicht es z B dem BALVI mobil XT Client (14 oder houmlher) den aktiven Block abzuholen und dies beim Fehler bis zu 10-mal zu wiederholen Sobald der Block [001] erfolgreich beim Client angekommen ist und dieser den naumlchsten Block anfragt wird der Block [001] verworfen wird Der Server fuumlllt dann im Hintergrund den frei gewordenen Block wieder waumlhrend der Client den Block [002] abholt
Die Groumlszlige und Anzahl der vorgecachten Bloumlcke kann uumlber die folgenden Einstellungen in der Datei bdquocontextxmlldquo definiert werden
ltEnvironment
name=partitionedExportmaxBufferedPartitions
value=3 type=javalangInteger override=true
gt
ltEnvironment
name=partitionedExportpartitionSize
value=256000 type=javalangInteger override=true
gt
Die Einstellung partitionedExportmaxBufferedPartitions ist dabei die Anzahl der vorgecachten Bloumlcke mindestens muss 2 angegeben werden Der Puffercache wird ausschlieszliglich im RAM der JVM aufgebaut es wird folglich mehr Arbeitsspeicher verwendet Dieser Arbeitsspeicher muss je gleichzeitiger Session auf dem Server bereitgestellt werden die Default-Einstellung mit 3 Partitionen a 256 KB + dem aktiven Puffer erfordern 1 MB RAM je aktiven Anwender
Aktiv
er
Puffe
r
[001] Vorg
ecac
hter
Bl
ock
[002] Vorg
ecac
hter
Bl
ock
[003]
Aktiv
er P
uffe
r
[002] Vorg
ecac
hter
Bl
ock
[003] Vorg
ecac
hter
Bl
ock
[leer]
Release Notes BALVI Schnittstellenserver Seite 24 von 37
Gleichzeitig wurde die Moumlglichkeit geschaffen dass die maximale Anzahl an gleichzeitigen Exporten durch das Rechenzentrum eingeschraumlnkt werden kann um einem OutOfMemory-Fehler vorzubeugen Die Einstellung
ltEnvironment
name=partitionedExportmaxConcurrentExports
value=10 type=javalangInteger override=true
gt
muss entsprechend der zu erwartenden gleichzeitigen Zugriffe konzipiert werden ansonsten wird der Server einen Verbindungsversuch durch die Clients ablehnen
Beachten Sie dass die folgenden Einstellungen partitionedExportmaxBufferedPartitions partitionedExportmaxConcurrentExports und partitionedExportpartitionSize gemeinsam als Rechenbasis fuumlr den RAM-Bedarf des Webservers herangezogen werden muumlssen
Folgende Faustformel sollte fuumlr die Einrichtung verwendet werden
Min 256 MB (Serverbasis) + (11 partitionedExportmaxConcurrentExports partitionedExportmaxBufferedPartitions partitionedExportpartitionSize)
Beispiel 50 gleichzeitige Anwender Blockgroumlszlige 256 KB 4 Partitionen
256 MB + (11 50 256 4) KB = 312 MB fuumlr die JVM
Empf 512 MB (Serverbasis) + (12 partitionedExportmaxConcurrentExports partitionedExportmaxBufferedPartitions partitionedExportpartitionSize)
Beispiel 50 gleichzeitige Anwender Blockgroumlszlige 256 KB 4 Partitionen
512 MB + (12 50 256 4) KB = 572 MB fuumlr die JVM
partitionedExportmaxConcurrentExports
Bestimmt die Anzahl der maximalen Export Tasks (Threads) die fuumlr partitionierte Exporte bereitgestellt werden Wenn die Anzahl uumlberschritten wird wird die entsprechende Exportanfrage abgewiesen und der Client muss zu einem spaumlteren Zeitpunkt erneut anfragen Stellen Sie diesen Wert entsprechend der zu erwartenden Benutzeranzahl ein bei 50 Anwendern also 50
Exporte oumlffnen auf der Datenbank entsprechend zur Ausfuumlhrungszeit min einen Cursor ggf fuumlr rekursive Unterabfragen kurzfristig sogar mehr Die hier eingestellte Anzahl muss mit der Anzahl von maxActive korrelieren
ltEnvironment
name=partitionedExportmaxConcurrentExports
value=10 type=javalangInteger override=true
gt
partitionedExportmaxBufferedPartitions
Bestimmt die Anzahl der Datenbloumlcke (Partitionen) die vom Server bei Abruf eines Exportes gepuffert werden Die seit Version 24 eingefuumlhrte FIFO-Puffer-Logik ermoumlglicht dass der Server schon die Ergebnisse vorpuffert so dass der Client weniger Wartezeiten bei der Anfrage nach Daten hat Diese
Release Notes BALVI Schnittstellenserver Seite 25 von 37
Puffer-Logik unterteilt den Exportdatenstrom (je Export) in mehre Bloumlcke Der Client kann nun den letzten Block neu anfordern oder den naumlchsten Block wenn der letzte Block erfolgreich verarbeitet wurde Wie viele naumlchste Bloumlcke durch den Server bereit gestellt werden entscheidet diese Einstellung Sobald kein naumlchster Block mehr bereit gestellt werden muss wird der Datenbank-Cursor geschlossen eine Erhoumlhung kann also zu einer Entlastung der aktiven DB-Verbindungen fuumlhren erhoumlht jedoch den Bedarf an RAM des Servers
Der von BALVI voreingestellte Wert ist 3
ltEnvironment
name=partitionedExportmaxBufferedPartitions
value=3 type=javalangInteger override=true
gt
partitionedExportpartitionSizeldquo
Die Groumlszlige der Datenbloumlcke (Partitionen) die an den Client uumlbermittelt werden in Bytes Wenn Sie diesen Wert zu niedrig einstellen reduziert sich die Effizienz des Caches da der Client mehr Datenbloumlcke hintereinander abrufen muss Waumlhlen Sie einen zu groszligen Wert wird die neu zu uumlbertragende Datenmenge im Fall eines Fehlers houmlher
Der von BALVI voreingestellte Wert ist 256000 (256 KB)
ltEnvironment
name=partitionedExportpartitionSize
value=256000 type=javalangInteger override=true
gt
exportTokensmaxTokenCount
Maximale Anzahl der gleichzeitig vergebenen Token die vom Server gecached werden Jede Sitzung welche einen Export durchfuumlhrt erhaumllt einen Session-Token
Wenn eine Sitzung laumlngere Zeit nicht verwendet wurde wird dieser Session-Token wieder entfernt Wenn Sie den Wert zu niedrig einstellen fuumlhrt das zu einer generellen Session-Begrenzung auch fuumlr den nicht partitionierten Export-Modus welcher ab Version 21 verfuumlgbar ist
Ist die Anzahl der Tokens houmlher als die Datenbankeinstellung maxActive kann es vorkommen dass zwar eine Session gestartet werden kann jedoch kein Datenexport zustande kommt
Der von BALVI voreingestellte Wert ist 2000
ltEnvironment
name=exportTokensmaxTokenCount
value=20 type=javalangInteger override=true
gt
exportTokenstokenExpirationInSeconds
Zeit in Sekunden die verstreichen muss bis ein Token unguumlltig wird falls darauf kein Zugriff mehr erfolgt Nach einem erfolgreichen Export wird der Token automatisch geschlossen diese Option ist fuumlr den Abbruchfall vorgesehen Der von BALVI voreingestellte Wert ist 180 (180 s = 3 min)
Release Notes BALVI Schnittstellenserver Seite 26 von 37
ltEnvironment
name=exportTokenstokenExpirationInSeconds
value=180 type=javalangInteger override=true
gt
exportTokenstokenDisposalInSeconds
Zeit in Sekunden die verstreichen muss bis ein Token das erfolgreich abgearbeitet wurde aus dem Cache geloumlscht wird Um sicher zu stellen dass der letzte Exportblock noch erfolgreich abgerufen werden kann bleibt der Token auch nach Fertigmeldung des Clients noch N Sek guumlltig
Der von BALVI voreingestellte Wert ist 60 (60 s = 1 min)
ltEnvironment
name=exportTokenstokenDisposalInSeconds
value=60 type=javalangInteger override=true
gt
2516 Job-Verwaltung fuumlr den BSS konfigurieren Aktivierung der Jobverwaltung
Bis zur Version 28 des BSS gab es den Parameter bdquoavailableServicesldquo Dieser konnte bei Bedarf aktiviert werden wenn die Jobs benoumltigt wurden
Mit Version 30 ist die Einstellung bdquoavailableServicesldquo zu entfernen und kann durch den neuen optionalen Parameter bdquoisJobServiceEnabledldquo in der Datei bdquocontextxmlldquo ersetzt werden
lt-- Neue Parameter zur Aktivierung des Job Service Ersatz fuumlr availableServices --gt
ltEnvironment
name=isJobServiceEnabled
value=true
type=javalangBoolean
override=true
gt
Ab BSS 30 wird die Jobs-Engine standardmaumlszligig aktiviert Sollte die Jobs-Engine nicht benoumltigt werden muss bdquovalueldquo der Wert bdquofalseldquo zugewiesen werden Wird bdquoisJobServiceEnabledldquo nicht eingefuumlgt sind die Jobs trotzdem standardmaumlszligig aktiv
Nach dem Neustart des Servers und erneutem Einloggen erscheint nun zusaumltzlich der Menuumlpunkt bdquoJobsldquo
bdquopasswordKeyldquo fuumlr Jobs
In der Job-Logik wird ein von BALVI definierter Standard-Schluumlssel fuumlr die Ablagen von schuumltzenswerten Daten z B Passwoumlrtern verwendet Diese Einstellung ermoumlglicht den BALVI-Standard zu uumlberschreiben Wenn Sie diese Einstellung aumlndern muumlssen jedoch alle bislang verschluumlsselten Job-Parameter neu verschluumlsselt werden
ltEnvironment
name=javacompenvjobspasswordKey
value=MeinHochsicheresNeuesPasswort
type=javalangString
Release Notes BALVI Schnittstellenserver Seite 27 von 37
override=true
gt
bdquoJob ID enableddisabledldquo (Deprecated ersetzt ab 28 durch das bdquoBindenldquo von Jobs)
Sondereinstellungen fuumlr die Job-Verwaltung Da alle Jobs in einer Datenbank administriert werden jedoch ggf verteilt auf mehreren Tomcat-Servern ausgefuumlhrt werden sollen besteht hier die Option Jobs fuumlr die aktuelle Tomcat-Instanz separat zu deaktivieren
Die Einstellung ID koumlnnte z B folgendermaszligen aussehen javacompenvjobsC0DB58D8D52C4BBC966D1DC788A4EF8Benabled
Fuumlr weitere Fragen zu dieser Einstellung kontaktieren Sie bitte die BALVI GmbH
ltEnvironment
name=javacompenvjobsIDenabled
value=false
type=javalangBoolean
override=true
gt
2517 Weitere optionale Parameter
Es ist fuumlr diverse einzelne Schnittstellen ggf erforderlich Einstellungen in der Datei bdquocontextxmlldquo zu ergaumlnzen Hinweise zu diesen Parametern sind dann in dem der Schnittstelle beiliegenden Dokument enthalten Das gilt z B fuumlr die Schnittstelle bdquoXGewerbeanzeigenldquo
26 Logging mit logback Das Logging wurde komplett uumlberarbeitet Statt bdquoLog4Jldquo wird jetzt bdquologbackldquo4 benutzt Ab BSS 30 ist es zwingend notwendig die Einstellung vorzunehmen um das Logging der Anwendung zu steuern
Migration Ergaumlnzen Sie die neue Einstellung bdquologgingconfigldquo
lt-- Neue Paramter zur Angabe der Logback Config Ersatz fuumlr log4jConfigLocation --gt
ltEnvironment
name=loggingconfig
value=$catalinabaseconflogback-bssxml
type=javalangString
override=true
gt
Nach wie vor steht es Ihnen frei die Logging-Konfiguration eigenstaumlndig anzupassen
Wenn Sie jedoch dieselbe WAR in einer Tomcat-Instanz unter mehreren Context-Namen betreiben wuumlrden beide dieselbe Logging-Konfiguration verwenden so dass alle Protokolleintraumlge in einer Log-Datei aus
4 httplogbackqoschmanualappendershtml
Release Notes BALVI Schnittstellenserver Seite 28 von 37
mehreren Webanwendungen generiert werden Aumlndern Sie den Namen der Logging-Konfiguration entsprechend ab um fuumlr jede Anwendung eine spezifische Logging-Einstellung vornehmen zu koumlnnen
27 Tocmat Optional Suche im bdquoKlassenpfadldquo um den
Ordner bdquoconfldquo erweitern Die Suche nach Dateien uumlber bdquoclasspathldquo setzt voraus dass die Ordner- und Dateinamen im Apache Tomcat bekannt gegeben werden Der Klassenpfad kann in der Datei bdquocatalinapropertiesldquo angepasst werden Wenn Sie dort unter commonloader die folgenden Werte ergaumlnzen kann eine Datei auch im Ordner conf abgelegt werden damit Apache Tomcat diese findet Ansonsten muss die Datei im Ordner lib abgelegt werden
commonloader=$catalinabaseconf$catalinahomeconf
3 Die neue Browser-Oberflaumlche Der BALVI Schnittstellenserver hat seit Version 25 neben der Protokollierung auch die Moumlglichkeit Job-Konfigurationen zu pflegen Der Login ist nur fuumlr einen in BALVI iP eingetragenen ADMIN (z B Benutzer bdquoSYSTEMADMINldquo) mit dem in BALVI iP hinterlegten Passwort moumlglich Zur Anmeldung muss immer [SYSTEMBenutzername] im Feld Benutzer angegeben werden ansonsten schlaumlgt die Anmeldung fehl Bitte achten Sie darauf dass der bdquoldquo (Slash) und nicht der bdquoldquo (Backslash) verwendet werden muss
31 Server-Protokoll Um das Server-Protokoll anzuzeigen waumlhlen Sie den entsprechenden Menuumlpunkt Dort haben Sie seit BSS 26 die Moumlglichkeit uumlber alle Spalten der Protokolle nach Informationen zu suchen
Seit BSS 31 gibt es die Moumlglichkeit Verfahren in bdquoKopfsaumltzeldquo und bdquoDetailsaumltzeldquo zu unterteilen Wurde das Verfahren entsprechend konfiguriert (wie z B bei der Schnittstelle bdquoXGewerbeanzeigenldquo) dann wird im Protokoll-Kopfsatz nur der Start und das Ende der Ausfuumlhrung in der Liste angezeigt Erst bei einem Klick auf bdquoInformationenldquo wird die Liste aller Detailsaumltze angezeigt die im Durchlauf erzeugt wurden
Release Notes BALVI Schnittstellenserver Seite 29 von 37
Verfahren
Die Liste der verfuumlgbaren Verfahren die bei Ihnen im System installiert sind ZB
BEFUNDEhellip Schnittstelle Befunde LM FM oder TS
PROBEhellip Schnittstelle zum Export von Proben an Labore ebenfalls Spezifisch fuumlr einzelne Fachbereiche
MOBILXT Protokolle der BALVI Mobil XT Synchronisation
WEB Allgemeine nicht spezifizierte Protokolle hierunter ist bislang auch die eFi-Protokollierung zu finden
WEB_I0802 Protokolle zur Schnittstelle BALVI iP LIMS (Lebensmittelproben)
XGEWERBE Schnittstelle XGewerbeanzeigen
Klicken Sie auf die Schaltflaumlche so besteht bei den neuen Protokolldatensaumltzen die Moumlglichkeit Detail-Informationen zum Protokollsatz zu erhalten
Release Notes BALVI Schnittstellenserver Seite 30 von 37
Seit BSS 30x ist die Anzeige der Protokolle ebenfalls farblich abgesetzt so dass Protokolleintraumlge mit Fehlern hellrot und Warnungen hellgelb hinterlegt werden
32 Jobs Mit einem Klick auf den Menuumlpunkt Jobs rufen Sie die Oberflaumlche fuumlr die Job-Konfiguration auf Daraufhin werden alle Jobs aufgelistet die fuumlr den BSS freigegeben sind Hier koumlnnen Sie Einstellungen an den Jobs vornehmen und die Jobs aktivieren bzw deaktivieren Die Beschreibungen bzw Einstellungsmoumlglichkeiten fuumlr den jeweiligen SST-Job sind nicht Bestandteil dieser Dokumentation
33 Log-Ausgaben Uumlber den Menuumlpunkt Log-Ausgaben koumlnnen Sie die Ausgabe der Protokolleintraumlge in Echtzeit beobachten
Release Notes BALVI Schnittstellenserver Seite 31 von 37
Starten Sie die Echtzeit-Protokollierung indem Sie auf die Schaltflaumlche mit dem Symbol bdquoPlayldquo (Dreieck) klicken unterbrechen Sie die Ausgabe indem Sie die auf Schaltflaumlche mit dem Symbol bdquoPauseldquo (zwei Balken) klicken
Klicken Sie auf die Schaltflaumlche bdquoAktualisierenldquo (zwei Pfeile) um die neuesten Protokolleintraumlge angezeigt zu bekommen
Klicken Sie auf das Symbol mit dem Papierkorb um die letzten Protokollmeldungen in der Anzeige zu loumlschen
Die Daten in den Protokolldateien auf der Festplatte des Servers sind davon nicht betroffen
Uumlber das Symbol bdquoLogging anpassenldquo (Schraubenschluumlssel) koumlnnen Sie die Ausgabe der Daten im Echtzeitfenster und in den Protokolldateien aumlndern jedoch ist diese Einstellung nur temporaumlr Die Standardeinstellungen koumlnnen ausschlieszliglich uumlber die Anpassung der Datei bdquologback-bssxmlldquo im Konfigurationsverzeichnis des Servers selbst geaumlndert werden
Release Notes BALVI Schnittstellenserver Seite 32 von 37
In der Logging-Parameter Konfiguration koumlnnen Sie verschiedene Parameter einstellen und uumlber die Schaltflaumlche bdquoAnwendenldquo dann sofort im Echtzeitprotokoll sehen Welche Einstellungen moumlglich sind erfahren Sie wenn es eine akute Fehlersituation gibt die detailliertere Ausgaben im Protokoll erfordert
Warnung Wenn Sie den Log-Level fuumlr ROOT oder eine andere Klasse auf TRACE einstellen werden sehr viele Protokollausgaben generiert die auch dazu fuumlhren koumlnnen dass der Server sehr langsam wird oder die Festplatte des Servers zulaumluft wenn fuumlr das Logging kein Dateilimit konfiguriert wurde
34 LogoutAbmeldung vom System Zum Abmelden waumlhlen Sie oben rechts das Kontextmenuuml
35 Cache loumlschen Der Cache wird in der Regel automatisch geloumlscht Wenn Sie jedoch gerade in BALVI iP eine Aumlnderung an den Schnittstellen eingespielt haben und moumlchten dass diese sofort wirksam wird kann die Funktion bdquoCache loumlschenldquo dazu verwendet werden dass der BALVI Schnittstellenserver die Einstellungen bei der naumlchsten Anfrage neu einliest
Release Notes BALVI Schnittstellenserver Seite 33 von 37
Release Notes BALVI Schnittstellenserver Seite 34 von 37
4 Einrichtung in BALVI iP Um die Verfahren fuumlr den BALVI Schnittstellenserver fuumlr Anwender freizuschalten wird das Objekt bdquoSystemeinstellungenldquo oder bdquoMandanten- und Benutzereinstellungenldquo verwendet Die Anpassung ist je Verfahren moumlglich so kann in BALVI iP fuumlr den Zugriff durch den BALVI Schnittstellenserver ein Benutzer bdquoAldquo am Verfahren bdquoMobilldquo berechtigt werden ein Benutzer bdquoBldquo nur am Verfahren bdquoSLA_FLESHldquo usw Die Logik ist jedoch einheitlich Je Verfahren wird durch BALVI eine Verfahrensgruppe mit dem Verfahrensnamen angelegt und mit den entsprechenden Einstellungen vorkonfiguriert welche durch das Verfahren erforderlich sind Dabei kann die Komplexitaumlt der Einstellungen variieren wie z B an den zu Version 23 verfuumlgbaren Verfahren bdquoMobilldquo und bdquoSLA_Fleshldquo ersichtlich wird
Im Verfahren BALVI Mobil sind diverse Anpassungen moumlglich welche je Bundesland oder eingesetzter Import- und Export-Variante durch den BALVI Schnittstellenserver bei der Bearbeitung von Anfragen gepruumlft werden siehe Punkt 3 Abb Mobil-Einstellung in BALVI iP
Abb Mobil-Einstellung in BALVI iP
Alle Verfahren verwenden jedoch die regulaumlre Benutzerverwaltung von BALVI iP Ein Benutzer ohne Passwort gilt fuumlr BALVI iP als gesperrt was fuumlr das Login bedeutet dass der Anwender sich nur uumlber die Active-Directory-Authentifizierung anmelden kann Ist das nicht moumlglich (bzw nicht konfiguriert) kann der Anwender sich weder in BALVI iP noch uumlber die Webservice-Schnittstelle authentifizieren
Fuumlr Dienste-Schnittstellen welche keine persoumlnliche Authentifizierung durch einen Anwender erfordern wird empfohlen einen separaten Benutzer in der Benutzerverwaltung anzulegen und ein sicheres Kennwort zu vergeben Das Anlegen von zusaumltzlichen Benutzern gilt nicht fuumlr BALVI mobil XT da beim Holen und Uumlbermitteln von Daten jeder Benutzer auch ein fachlich konfigurierter Anwender innerhalb von BALVI iP ist und die Anwendungsoberflaumlche ebenfalls zur Erfassung von Daten verwendet
Unter Punkt 2 der Abb Mobil-Einstellung in BALVI iP wird ein modales Fenster geoumlffnet (Abb BALVI mobil Benutzerverwaltung) Innerhalb dieses modalen Fensters werden mandantenweise die Benutzer fuumlr BALVI
Release Notes BALVI Schnittstellenserver Seite 35 von 37
mobil und den jeweiligen Fachbereich festgelegt Dabei ist es wichtig dass man die Haken bdquoAktiv fuumlr hellipldquo bei bdquohellip mobilldquo und bei einem Fachbereich (bdquohellip LMldquo bdquohellip FMldquo usw) setzt weil sonst uumlber den BALVI Schnittstellenserver keine Kommunikation mit BALVI iP moumlglich ist
Abb BALVI mobil Benutzerverwaltung
Alternativ zur Passwort-Authentifizierung wird wie beschrieben auch die Active-Directory-Authentifizierung angeboten Dazu muss der BALVI iP-Anwender uumlber die Schaltflaumlche bdquoDomaumlnen-Benutzer zuordnenldquo mit dem Active Directory verknuumlpft werden
Nur wenn die Active-Directory-Konfigurationen in BALVI iP und im BALVI Schnittstellenserver auf dieselbe Domaumlne verweisen sind die Domaumlnen-Zuordnung und die Active-Directory-Authentifizierung (z B uumlber BALVI mobil XT) moumlglich
Release Notes BALVI Schnittstellenserver Seite 36 von 37
5 Bekannte Probleme und Loumlsungen
51 ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner Bei der Job-Bearbeitung tritt folgender Fehler auf ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner
Behebung
Fuumlhren Sie das beiliegende IP-Patch (UPDATEexe) aus bevor Sie das WAR austauschen
52 Server startet nicht Sie finden folgende Zeilen im Protokoll (catalinaout oder bsslog)
ERROR [localhost-startStop-1] [IdentityServiceImpl] serverID must not be empty
ERROR [localhost-startStop-1] [ContextLoader] Context initialization failed
Behebung
Setzen Sie die Umgebungsvariable ldquoserverIDrdquo in der Datei bdquocontextxmlldquo
53 ORA-00942 table or view does not exist In vielen Faumlllen wird der Fehler ldquoTabelle oder View nicht vorhandenrdquo ausgeworfen (Java-Protokoll im Ordner logs von Apache Tomcat) wenn eine neue Schnittstelle eingerichtet oder ein neues BALVI iP Release bzw Update eingespielt wurde ohne anschlieszligend das aktuelle GRANT-Skript auszufuumlhren
Behebung
Fuumlhren Sie das GRANT-Skript erneut aus
54 ORA-0406x bdquoBestehender Paketstatus wurde aufgehobenldquo
ORA-04061 Bestehender Status von package body ABCXYZ wurde annulliert
ORA-04065 Ausfuumlhrung nicht erfolgreich package body ABCXYZ wurde geaumlndert oder geloumlscht
Release Notes BALVI Schnittstellenserver Seite 37 von 37
Der Fehler tritt haumlufig ein nachdem die UPDATEexe ausgefuumlhrt und in der Ausfuumlhrungsliste ein Package aktualisiert wurde Oracle merkt sich je User-Session bestimmte Werte im Package wenn der Anwender es verwendet hat Durch einen bdquoCREATE OR REPLACE PACKAGEldquo-Befehl kann dieser Status temporaumlr aufgehoben werden Normalerweise tritt dieser Fehler nach dem Update genau einmal in jeder aktiven Session auf wenn der BSS nicht neu gestartet wird
Behebung
Starten Sie nach jedem Update den BSS neu um alle laufenden Sessions zu beenden
55 Jobs sind nicht ausfuumlhrbar
1 Ein Job wird mit dem Status bdquoNicht unterstuumltztldquo angezeigt wenn fuumlr seine Ausfuumlhrung eine houmlhere Version des BSS erforderlich ist
2 Nach dem Klonen der Datenbank von der Produktions- auf die Testumgebung erhalten alle Jobs automatisch den Status bdquoDeaktiviertldquo wenn die bdquoserverIDldquo nicht identisch ist
Beide Statusaumlnderungen sind gewollt Damit soll verhindert werden dass Jobs nach einem Serverneustart oder nach einem Update automatisch starten und dabei Fehler verursachen
Um Jobs mit dem Status bdquoNicht unterstuumltztldquo nutzen und konfigurieren zu koumlnnen ist es erforderlich den BALVI Schnittstellenserver zu aktualisieren
Deaktivierte Jobs koumlnnen Sie aktivieren indem Sie den jeweiligen Job an den aktuellen Server binden und den Haken bei bdquoAktivldquo setzen
Release Notes BALVI Schnittstellenserver Seite 5 von 37
12 Neuerungen in Version 30 Der BSS 3x beinhaltet alle Funktionalitaumlten des BSS 28x und ist daher abwaumlrtskompatibel
Zusaumltzlich ist es ab Version 3x moumlglich Synchronisations-Jobs zu verarbeiten die mit der OpenSource ETL- Engine bdquoPentaholdquo durch BALVI entwickelt werden Damit wird der BSS auf das zukuumlnftige BALVI iP2 vorbereitet In diesem Zuge wurden diverse Funktionalitaumlten aktualisiert
Beim Update von BSS 2x auf BSS 3x muumlssen an der Datei bdquocontextxmlldquo folgende Anpassungen vorgenommen werden bevor der Server gestartet werden darf
1 Neuer Parameter isJobServiceEnabled
Der Parameter availableServices wurde durch isJobServiceEnabled ersetzt (siehe Kapitel 2516) Damit ist der Jobservice standardmaumlszligig aktiv Empfehlung Suchen Sie availableServices und entfernen Sie diese Einstellung
2 Neue Logging-Konfiguration
Zu BSS 30 wurde auf eine neue Logging-Klasse umgestellt (siehe Kapitel 26) Ersetzen Sie im Ordner conf die vorhandene Datei bdquolog4j-commserverxmlldquo durch die Datei bdquologback-bssxmlldquo um den neuen APPENDER nutzen zu koumlnnen Entfernen Sie log4jConfigLocation und fuumlgen Sie loggingconf hinzu Tragen Sie in der Datei bdquocontextxmlldquo beim neuen Parameter loggingconf den Pfad zur Datei bdquologback-bssxmlldquo ein Die Logging-Funktionalitaumlt des Servers ist davon nicht betroffen
3 Datenbank-Verbindung bdquofactoryldquo umstellen
Bis Version 28 wurde aus Kompatibilitaumltsgruumlnden zu Tomcat 6 als DBCP-Factory noch auf orgapachecommonsdbcpBasicDataSourceFactory verwiesen Ab Tomcat 7 wird jedoch empfohlen die Tomcat-eigene Umsetzung zu verwenden Aumlndern Sie dazu die Angabe factory= in der bdquojdbcDataSourceldquo auf factory=orgapachetomcatjdbcpoolDataSourceFactory Die Verwendung von commonsdhcp wird nicht mehr empfohlen da die Tomcat-spezifische Datasource orgapachetomcatjdbc diverse interne Mechanismen bereitstellt die den Datenbankzugriff aus Apache Tomcat verbessern Dazu gehoumlren die Interceptor-Einstellungen die im Beispiel von BALVI bssxmlexmaple ergaumlnzt wurden (siehe Kapitel 2511)
Release Notes BALVI Schnittstellenserver Seite 6 von 37
4 ETL-Prozesser
Neue Datenquellen ergaumlnzen
Fuumlr die Kommunikation zwischen iP2 Modulen und iP1 wird Kettle benutzt In die contextxml muss dafuumlr eine zusaumltzliche DataSource eingefuumlgt werden wenn Sie die Daten-Uumlbermittlung von IP1 an IP2 verwenden
Die jdbcKettleIP1DataSource ist im Beispiel auskommentiert verwendet derzeit jedoch immer die Zugangsdaten die Sie auch in der jdbcDataSource eingestellt haben da derzeit beide Datenbank-Verbindungen auf das angebundene BALVI iP (124x) zugreifen sollen Beachten Sie jedoch dass die jdbcKettleIP1DataSource die Einstellung type=debalvikettleKettleDataSourceSettings (nicht javaxsqlDataSource) verwendet damit diese nur und ausschlieszliglich dann geladen wird wenn die Kettle-Engine eine separate Datenbankverbindung benoumltigt Um ETL-Engine (Kettle) mitzuteilen welche DataSource das auszufuumlhrende Modul benoumltigt sind folgende Umgebungseinstellungen in die Datei bdquocontextxmlldquo einzufuumlgen
Beispiel
ltResource
name=jdbcKettleIP1DataSource
auth=Container
type=debalvikettleKettleDataSourceSettings
factory=orgapachetomcatjdbcnamingGenericNamingResourcesFactory
maxActive=3 maxIdle=2 minIdle=1 initialSize=1
gt
Kettle Bibliotheken
Da Kettle fuumlr die Ausfuumlhrung verschiedene Dateien benoumltigt muss zudem der Parameter bdquokettlePluginDirectoryldquo eingestellt werden Weisen Sie dem Wert (bdquovalue=ldquo) den Pfad zu dem Verzeichnis zu in dem die Ausfuumlhrungsdateien liegen Die erforderlichen Dateien sind Bestandteil der Auslieferung
ltEnvironment
name=kettlePluginDirectory
value=hometest_ip2_bsskettleplugins
type=javalangString
override=true
gt
13 Hinweise zum Update von aumllteren Versionen (vor 30x) Ab BSS 282 wird eine bdquoserverIDldquo erwartet Daher ist es zwingend erforderlich die vorhandene Datei bdquocontextxmlldquo zu erweitern und den neuen Environment-Parameter bdquoserverIDldquo zu ergaumlnzen
Release Notes BALVI Schnittstellenserver Seite 7 von 37
14 Nacharbeiten nach dem Update auf Version 28
(ADMIN) Sofern Sie schon aktive bdquoJobsldquo im BSS in Verwendung haben werden diese mit dem Update automatisch deaktiviert da die Jobs nun an den ausfuumlhrenden Server gebunden werden muumlssen Oumlffnen Sie dazu den Job in der Detailansicht setzen Sie den Haken hinter bdquoJob an Server bindenldquo setzen und speichern Sie die Einstellung
Der Job wird anschlieszligend in der Uumlbersicht wieder mit dem Status bdquoAktiviertldquo angezeigt Diesen Konfigurationsschritt muumlssen Sie nun jedes Mal durchfuumlhren nachdem die Datenbank von Produktion auf Test geklont wurde
15 Neuerungen in Version 28
151 Jeder Schnittstellen-Server benoumltigt eine Kennung bdquoserverIDldquo Viele Kunden nutzen den Schnittstellenserver mehrfach in Ihrer Umgebung da mehrere BALVI iP Installationen (z B Produktion und Test) in der Infrastruktur existieren
Da die Schnittstellenkonfiguration fuumlr den BSS in der Datenbank abgelegt wird kam es in manchen Faumlllen vor dass nach dem Klonen der Produktionsdatenbank auf ein Testsystem die im BSS angelegten Jobs sofort nach dem Start in der Testumgebung wieder angesprungen sind Um dieses Problem zu beseitigen muss jedem BSS ab Version 28 eine eindeutige bdquoserverIDldquo zugewiesen werden Diese Server-ID wird in der Datei bdquocontextxmlldquo hinterlegt um neutral zur Datenbank zu sein
Ist keine Environment-Variable bdquoserverIDldquo vorhanden wird der Start des BSS 28 (oder houmlher) sofort mit einer Fehlermeldung abgebrochen Im Server-Protokoll wird dabei der Fehler bdquoERROR [IdentityServiceImpl] serverID must not be emptyrdquo ausgegeben Danach kommt sofort die Meldung dass der BSS wieder heruntergefahren wird
INFO [localhost-startStop-1] [ContextCreationListener]
BALVI-Schnittstellen-Server
Version 280
hellip
ERROR [localhost-startStop-1] [IdentityServiceImpl] serverID must not be empty
ERROR [localhost-startStop-1] [ContextLoader] Context initialization failed
Um eine ldquoserverIDrdquo zu vergeben fuumlgen Sie in der Datei bdquocontextxmlldquo folgende Angabe ein
lt--
Release Notes BALVI Schnittstellenserver Seite 8 von 37
ID fuumlr den Server
Diese muss pro Schnittstellenserver eindeutig sein
Eine Aumlnderung dieser ID fuumlhrt sofort dazu dass alle
eingerichteten Server-Jobs inaktiv werden und neu mit
der Instanz gekoppelt werden muumlssen um wieder aktiviert
werden zu koumlnnen
Als value kann ein Text der max Laumlnge von 32 Zeichen
vergeben werden z B ProductionEnvNode1 fuumlr die Produktion
und TestEnvNode1 fuumlr die Testumgebung
--gt
ltEnvironment
name=serverID
value=ProductionEnvNode1
type=javalangString
override=true
gt
152 Optional ist nun eine Namensvergabe moumlglich Auf Wunsch mehrerer Kunden wurde die Option geschaffen jedem Server zusaumltzlich einen kundenspezifischen bdquoTitelldquo zu geben um die Server besser unterscheiden zu koumlnnen
lt--
Visueller Name des Servers in der Oberflaumlche
(Optional)
--gt
ltEnvironment
name=serverName
value=TIERZ Tomcat 8 Java 8 mit BALVI_TIERZXGEWETLBTR_BSS
type=javalangString
override=true
gt
Der hier angegebene Text wird in der Kopfzeile zwischen den eckigen Klammern ausgegeben
Release Notes BALVI Schnittstellenserver Seite 9 von 37
2 Einrichtungshinweise
21 Allgemeine Hinweise zum Betrieb
211 Kompatibilitaumlt zu Apache Tomcat und Java SE Der BALVI Schnittstellenserver wurde getestet und freigegeben fuumlr Apache Tomcat 8 (ab Version 8030 oder neuer) Zudem wurde die aktuellste (letzte offizielle) Version von Java SE 8 getestet und kann verwendet werden (Java SE 8u40 und neuer)
Installieren Sie stets die aktuellsten Sicherheitsupdates fuumlr Java SE 8 Beachten Sie dabei jedoch dass nicht die Aktualisierung auf eine andere Java-Version (z B Java 9) gemeint ist
Freigegebene Major-Versionen werden explizit von BALVI benannt Falls Sie beabsichtigen die Major-Version zu aumlndern pruumlfen Sie bitte die aktuellen Release Notes oder kontaktieren die BALVI Kundenbetreuung
212 Oracle Java SE Lizenzierung Java SE beinhaltet auch kostenpflichtige Funktionen fuumlr deren Nutzung Oracle Lizenzgebuumlhren fordert wenn sie bei der Entwicklung eingesetzt werden Die von BALVI gelieferte Software ist frei von den kommerziellen Teilen der Oracle Java SE nutzbar Fuumlr den Einsatz von Oracle Java SE (einschlieszliglich JDK und JRE) fallen im Rahmen der Nutzung der BALVI Software keine Lizenzkosten an
Trotzdem werden wir parallel pruumlfen ob technische Probleme bei der Umstellung auf das OpenJDK zu erkennen sind Ein einfacher Funktionstest hat im BSS 3x noch keine technischen Probleme gezeigt als wir die Laufzeitumgebung auf das OpenJDK 8U111 AMD64 (Debian) umgestellt haben Bitte haben Sie Verstaumlndnis dafuumlr dass wir keine Funktionstests fuumlr jedes Linux-Derivat durchfuumlhren koumlnnen und dass es offiziell keine Version des OpenJDK fuumlr Windows Betriebssysteme gibt
213 Einsatz von TLSSSL BALVI hat keine spezifischen Anforderungen an die Konfiguration von SSL bzw TLS Der Einsatz von TLS 12 gem der Richtlinie TR-02102-2 vom BSI ist moumlglich wenn Sie sich an die von Apache Tomcat herausgegebene Dokumentation halten Es sind keine Anpassungen des Schnittstellenservers erforderlich Daher gehen wir davon aus dass auch der BSS 28x oder aumllter in einem Apache Tomcat mit TLS 12 betrieben werden kann
Das gilt jedoch nicht fuumlr alle Clients die den Tomcat-Server ansprechen moumlchten So ist z B erst ab BALVI mobil 191958 sichergestellt dass die Protokolle TLS 11 und TLS 12 programmseitig aktiviert sind Fuumlr Details zu diesem Problem wurde ein separates Rundschreiben per E-Mail versendet
Release Notes BALVI Schnittstellenserver Seite 10 von 37
214 Nutzung von Java-Proxyeinstellungen Der BALVI Schnittstellenserver verwendet fuumlr ausgehende Verbindungen die Java-Net Einstellungen welche in der Java-Dokumentation1 beschrieben sind Falls Sie Jobs einsetzen welche ausgehenden Zugriff auf Adressen im Internet benoumltigen kann es passieren dass Sie z B eine bdquojavanetUnknownHostExceptionldquo im Protokoll finden dann muumlssen Sie ihre Proxy-Umgebung in den Java-Umgebungseinstellungen ergaumlnzen
Die folgenden Parameter sollten daher in Ihrer Umgebung gesetzt werden wenn der Zugriff auf das Internet nur uumlber einen Proxy moumlglich ist
-DproxySet=true
-DproxyHost=10111213
-DproxyPort=8888
-DhttpnonProxyHosts=domainorg|localhost|10
Starten Sie nach Aumlnderung der Einstellungen den Server neu damit die Einstellungen wirksam werden
2141 Proxy-Einstellung unter Windows (Tomcat-Dienst)
Verwenden Sie das Dienste-Konfigurationsprogramm (z B tomcat7wexe) und ergaumlnzen Sie die fehlenden Einstellungen
2142 Proxy-Einstellung unter Linux
In Linux wird in der Konfigurationsdatei (z B conftomcat7conf) die Variable bdquo$JAVA_OPTSldquo entsprechend erweitert und die Werte uumlbergeben Beachten Sie dabei dass die Variablen von Linux (bzw der Bash) gelesen werden Daher muss das bdquoPipeldquo-Zeichen bdquo|ldquo mit bdquoldquo maskiert werden ansonsten erhalten Sie bei der Verarbeitung der Umgebungsvariable bdquohttpnonProxyHostsldquo Fehlermeldungen in der Linux -Konsole welche dazu fuumlhren dass Java nicht korrekt konfiguriert werden kann
JAVA_OPTS=$JAVA_OPTS -DproxySet=true -DproxyHost=10111213 -DproxyPort=8888
JAVA_OPTS=$JAVA_OPTS -DhttpnonProxyHosts=domainorg|localhost|10
1 httpdocsoraclecomjavase8docstechnotesguidesnetpropertieshtml
Release Notes BALVI Schnittstellenserver Seite 11 von 37
215 Spracheinstellung Deutsch Es wurde festgestellt dass unter einigen Linux-Versionen die Spracheinstellung beim Starten des Apache Tomcat nicht auf eine deutsche Umgebung verweist Dieses kann technische Probleme verursachen Unter Linux sollte die Einstellung (Umgebungsvariable) entsprechend auf LANG=de_DEUTF-8 eingestellt sein
216 Datenbankverbindung Wenn Sie eine Firewall zwischen dem Oracle-Server und dem Database Connection Pool (DBCP) verwenden sollte unbedingt die bdquovalidationQueryldquo in der DBCP-Konfiguration aktiviert werden damit die Anwendung schneller freie Connections aus dem Pool erhalten kann Die Dokumentation zu den Einstellmoumlglichkeiten ist in der beiliegenden Contextxml ergaumlnzt worden
Bitte beachten Sie dass dringende empfohlen wird die bdquoFactoryldquo auf orgapachetomcatjdbcpoolDataSourceFactory anzupassen falls sie noch auf bdquoorgapachecommonsdbcpBasicDataSourceFactoryldquo eingestellt ist
217 Probleme beim Anlegen von LOB-Objekten Der BALVI Schnittstellen-Server erfordert die JDBC-Spezifikation DBCP V4 welche durch die Factory bdquoorgapachetomcatjdbcldquo ab Tomcat 7 automatisch bereitgestellt wird
Wenn die Pooling-Komponente oder der Oracle-Treiber nicht JDBC4-Kompatibel sind gibt es beim Bearbeiten von LOB-Objekten in Java diverse Exceptions z B
Servletservice() for servlet soapws threw exception
javalangAbstractMethodError
orgapachecommonsdbcpPoolingDataSource$PoolGuardConnectionWrappercreateClob()LjavasqlClob
at debalvicoreauditspyConnectionSpycreateClob(ConnectionSpyjava511)
Ursache dieses Problems ist meistens dass noch nicht auf bdquoorgapachetomcatjdbcldquo umgestellt wurde
218 Umbenennung der gelieferten WAR-Datei Das im Paket von BALVI gelieferte WAR kann jederzeit umbenannt werden (z B als ROOTwar) ohne dass dabei spezielle Einstellungen in der Datei bdquocontextxmlldquo erforderlich sind
Beachten Sie dabei jedoch dass die zum WAR zugehoumlrige Datei bdquocontextxmlldquo im Apache Tomcat immer denselben Namen erhaumllt wie das WAR z B bdquocommserverwarldquo und bdquocommserverxmlldquo Der Name ist dabei ausschlaggebend fuumlr die Zugriffs-Adresse (Context) im Apache Tomcat selbst Die Benennung des WAR in bdquocommserverwarldquo wuumlrde folgendermaszligen aufzurufen sein httpserverportcommserver
219 Server-Schnittstellen Die Uumlberarbeitung bzw Erweiterung der Export- und Importschnittstellen welche uumlber den Schnittstellenserver bereitgestellt werden ist unabhaumlngig vom Schnittstellenserver selbst Die Schnittstellen sind daher nicht Bestandteile des Schnittstellenserver und werden je Verfahren separat
Release Notes BALVI Schnittstellenserver Seite 12 von 37
ausgeliefert Ggf ist es fuumlr unterschiedliche Schnittstellen erforderlich die Grant-Rechte zu aktualisieren (Vgl bdquoWann ist die Ausfuumlhrung des Grant-Skripts erforderlichldquo)
22 Kompatibilitaumltsliste Diverse Verfahren setzen eine Mindestversion des BALVI Schnittstellenservers voraus Die Schnittstellen sind jedoch so konzipiert dass eine Aktualisierung auf eine houmlhere Version des Servers ohne Anpassung an den vorhandenen Schnittstellen jederzeit moumlglich ist
Derzeit sind folgende Mindestanforderungen gegeben
1 BALVI mobil XT 170 oder houmlher setzt BSS 265 und BALVI iP 124x voraus
2 BALVI mobil XT 183 oder houmlher setzt BSS 281 und BALVI iP 124x voraus
3 BALVI mobil 2 (DM) setzt BSS 311 und BALVI iP 124x voraus
4 Die Schnittstelle eFI setzt BSS 251 und BALVI iP 122c voraus
5 Die Schnittstelle LIMS setzt BSS 265 voraus
6 Die Schnittstelle TSK (SN) setzt BSS 265 voraus
7 Die Schnittstelle xDomea (SN) setzt BSS 265 und Java 7 voraus
8 Die Schnittstelle XGewerbeanzeigen 11 setzt BSS 281 BALVI iP 124x Java 8 mit der bdquoJava
Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy2ldquo voraus
9 Die Schnittstelle XGewerbeanzeigen 12 (ab Paket 7 Ausbaustufe 3) setzt BSS 302 BALVI iP
124x Java 8 mit der bdquoJava Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policyldquo
voraus
10 Die Schnittstelle RioPP LM (NRW) setzt BSS 303 und die ETL-Konfiguration voraus
11 Die Schnittstellen zu BALVI iP2 (Fachmodule BTS LM ZDA Stand Juni 2017) setzen BSS 32x
voraus
2 httpwwworaclecomtechnetworkjavajavasedownloadsjce8-download-2133166html
Release Notes BALVI Schnittstellenserver Seite 13 von 37
23 Erforderliche Bibliotheken fuumlr Apache Tomcat Dateiname Funktion Quelle ojdbc6jar Oracle 11gR2 Clientpaket Oracle JDBC Client fuumlr Java
16 ersetzt die bisherige Version bdquoojdbc14jarldquo Die alte Library muss auf jeden Fall entfernt werden
httpwwworaclecomtechnetworkdatabaseenterprise-editionjdbc-112010-090769html
encrypted-datasource-110-alljar
Die Library muss auf jeden Fall entfernt werden Wird derzeit nicht weiter gepflegt da kein Interesse an der Funktionalitaumlt bestand
slf4j-api-1511jar slf4j-log4j12-1511jar log4jdbc4-12beta2jar
Entfaumlllt nicht mehr erforderlich Es wird empfohlen diese zu entfernen falls diese im LIB-Verzeichnis vorhanden sein sollten
commons-dbcp-14jar commons-pool-154jar
Entfaumlllt nicht mehr erforderlich Es wird empfohlen diese zu entfernen falls diese im LIB-Verzeichnis vorhanden sein sollten
Erwartet wird stattdessen ab Tomcat7 die mitgelieferte bdquotomcat-jdbcjarldquo
log4j-1217jar (oder houmlher)
Logging-Funktionalitaumlt Apache Log4j httploggingapacheorglog4j12downloadhtml
bcprov-jdk15on-157jar (oder houmlher)
BouncyCastle Security Provider fuumlr SSLAES hellip wird ab Version 27 im Ordner bdquolibldquo des Tomcat erwartet Sollte es aus Sicherheitsgruumlnden erwuumlnscht sein eine aktuellere Version einzusetzen ist dieses idR moumlglich
httpmvnrepositorycomartifactorgbouncycastlebcprov-jdk15on157
24 Datenbank-Installation Der BALVI Schnittstellenserver benoumltigt auszligerhalb des angebundenen BALVI iP keine eigenen Tabellen Die Web-Anwendung kann im einfachsten Fall direkt auf das Schema von BALVI iP zugreifen indem der Benutzer und das Passwort des BALVI iP-Schemas in der Datei bdquocontextxmlldquo eingetragen werden (nicht empfohlen)
Sollte dies aus Sicherheitsgruumlnden nicht erwuumlnscht sein (empfohlen vom BSI und von BALVI) finden Sie im Paket ein GRANT-Skript um Zugriffsrechte vom BALVI iP Schema fuumlr den Webservice-Schema-Benutzer einzurichten
Zwischen dem Schema von BALVI iP und jeder Web-Anwendung ist dann eine Trennung moumlglich um sicherzustellen dass der Datenbank-Benutzer welcher in der Tomcat-Konfiguration fuumlr die Web-Anwendung eingetragen wird geaumlndert oder geloumlscht werden kann ohne dass die Windows-Anwendung BALVI iP davon betroffen ist Zudem vergibt das von BALVI gelieferte Grant-Skript keine Rechte zum Loumlschen von Tabellenstrukturen oder Tabelleninhalten so dass der Webservice nur festgelegte Daten aumlndern oder lesen darf Es wird empfohlen je Web-Anwendung einen eigenen Datenbank-Benutzer zu vergeben wenn Sie ein BALVI iP mit mehreren Webservices verbinden wollen
Die Moumlglichkeiten im Uumlberblick
1) Sie betreiben den Webservice mit einem eigenstaumlndigen Oracle-Benutzer In diesem Fall muss das
Grant-Skript ausgefuumlhrt werden um den Webservice-Benutzer und den BALVI iP-Benutzer
miteinander zu koppeln
2) In der Tomcat-Konfiguration wird der Oracle-Benutzer eingetragen welcher auch der BALVI iP
Schemabesitzer ist und in der bdquobalviip_conninildquo hinterlegt ist (NICHT Empfohlen) Der Webservice
Release Notes BALVI Schnittstellenserver Seite 14 von 37
hat 100 Zugriffsrechte (auch Loumlsch- oder Aumlnderungsrechte am Schema) es wird kein Grant-
Skript benoumltigt
Wenn Sie die Konfiguration 2) waumlhlen moumlchten koumlnnen Sie die folgenden Unterkapitel uumlberspringen und in Kapitel 0 bzw fortsetzen
241 Erstinstallation Datenbank-Benutzer anlegen Wenn Sie den Webservice-Benutzer vom BALVI iP Schema trennen moumlchten muss durch die DB-Administration in der Oracle-Server-Instanz wo auch BALVI iP sein Schema besitzt ein Benutzer (ggf je Web-Anwendung) angelegt werden welcher folgende Rechte benoumltigt
CONNECT
ALTER SESSION
CREATE JOB
CREATE PROCEDURE
CREATE SESSION
CREATE TABLE
CREATE TRIGGER
CREATE TYPE
CREATE VIEW
CREATE SEQUENCE
CREATE SYNONYM
QUERY REWRITE
Der Default-Tablespace ist frei waumlhlbar Der Benutzer braucht das Recht QUOTA UNLIMITED auf den Tablespace von BALVI iP (Default BALVI_IP) Ein Beispiel-Create-Skript bdquooraCreate_WEB_Usersqlldquo liegt der Auslieferung bei
242 Rechte zuweisen Wenn der BALVI iP Schemabesitzer NICHT in der Tomcat-Umgebung eingetragen werden soll muss ein Oracle DBA das beiliegende GRANT-Skript bdquooraGrantIP_to_Websqlldquo ausfuumlhren um dem jeweiligen Webservice (in Tomcat verwendeten Oracle-Benutzer) die minimalen Rechte auf das Schema von BALVI iP zu gewaumlhren
Dieses Skript setzt voraus dass es von einem Oracle Administrator als bdquoUser SYSTEMldquo ausgefuumlhrt wird Lesen Sie die im Skript enthaltenen README-Kommentare und passen Sie die Benutzer (BALVI iP Schema) und (WEB-Schema) an
====================================================
DEKLARATIVER TEIL MUSS vom KUNDEN geaumlndert
bzw auf die korrekten SCHEMA-Namen angepasst
werden
Die USER-Namen muumlssen in Groszligbuchstaben
geschrieben sein sonst werden sie nicht
gefunden
====================================================
sUserBALVI_IP = BALVI_IP_SCHEMABESITZER
sUserBALVI_WEB = BALVI_WEB_SCHEMABESITZER
Release Notes BALVI Schnittstellenserver Seite 15 von 37
Neu ab Grant-Skript 158 ist die Umbenennung der Verfahrenszuordnung
Pruumlfen Sie dass die Einstellung fuumlr Ihr BundeslandVerfahren korrekt ist dort muss eine 1 fuumlr min ein Verfahren gesetzt sein Diese Einstellung befindet sich direkt unter den Schemabesitzer-Angaben
-- Verfahrensbezogene Konfiguration
-- Setzen Sie fuumlr das jeweilige Verfahren eine 1
-- BALVI Schnittstellenserver (BSS)
-- bis V266 auch BALVI Kommunikationsserver (BKS) genannt
-- generell fuumlr die meisten Verfahren guumlltig
-- Ab Version 57 entfaumlllt mit der Einfuumlhrung der
-- Schnittstelle XGewerbeanzeigen auch der separate Schalter
-- WS_BTR beide Verfahren wurden vereinheitlicht
WS_BSS = 1
Fuumlhren Sie das Skript nach der Anpassung als User SYSTEM aus um die Grants durchzufuumlhren Dieses wurde mit dem von ORACLE gelieferten Programm SQLPLUS (Command-Line) SQLPLUS Worksheet (GUI) und Oracle SQL-Developer getestet
Das Skript generiert fuumlr jedes Objekt ein SYNONYM fuumlr den WEB-USER so dass dieser auf die Objekte ohne Angabe des Owners des IP-Schemas zugreifen kann Pruumlfen Sie nach der Ausfuumlhrung dass die SYNONYMS vorhanden und VALID sind dieses kann ggf nicht der Fall sein Das Skript kann jederzeit erneut ausgefuumlhrt werden um die Grants neu zu erzeugen und bietet ebenfalls die Option alle Grants und Synonyme wieder zu entfernen Detaillierte Informationen zur Nutzung des Skripts sind als Kommentar-Block im Skript enthalten
Hinweis Die Versionsinformation ist unter den Kommentaren direkt im Skript zu finden
Zugriffsberechtigungen fuumlr Webanwendungen auf BALVI iP anlegen
===============================================================
Version 158
Guumlltig fuumlr BALVI iP 123 oder houmlher
Autor Frank Holler
SVN Revisionsinformationen
$Revision 479 $
$Date 2016-02-15 152755 +0100 (Mo 15 Feb 2016) $
================================================================
243 Wann ist die Ausfuumlhrung des Grant-Skripts erforderlich Durch das Strukturupdate von BALVI iP (z B 1240 auf 1241) werden veraltete Strukturen geloumlscht und ggf neue Views oder Tabellen angelegt Die Grant-Rechte geht dabei ggf verloren Daher ist die Ausfuumlhrung des Grant-Skripts immer dann erforderlich wenn sich die Datenbank-Struktur von BALVI iP veraumlndert
Zudem kann es fachliche Neuerungen geben welche im alten Grant-Skript nicht vorhanden sind Daher muss das Skript ggf auch ausgefuumlhrt werden wenn eine neue Schnittstelle im Schnittstellenserver bereitgestellt wurde Dieses betrifft z B auch die Bereitstellung von neuen Versionen von BALVI mobil XT
Release Notes BALVI Schnittstellenserver Seite 16 von 37
da auch dort mit einem fachlich erweiterten Client die Moumlglichkeit besteht dass neue Schnittstellen bereitgestellt und somit mehr Schreibrechte auf Tabellen benoumltigt werden
244 Welche Version des Grant-Skripts soll ich nehmen Wie der Schnittstellenserver sind auch die Grant-Skripte versioniert Neuere Versionen des Grant-Skriptes sind abwaumlrts-kompatibel und koumlnnen immer verwendet werden auch wenn in einer Schnittstellenbeschreibung eine aumlltere Version des Grant-Skriptes explizit benannt wurde
245 Kombination von mehreren Verfahren Wenn Sie zwei oder mehr Schnittstellen im BSS verwenden moumlchten ist es ggf erforderlich auch mehrere Verfahren auf aktiv (bdquo1ldquo) zu setzen
Im Beispiel nehmen wir an Sie moumlchten bdquoeFildquo und bdquoBALVI mobil XTldquo im Schnittstellenserver bereitstellen In der Beschreibung von bdquoeFildquo steht dass das Grant-Skript V36 erforderlich ist BALVI mobil XT 18 erfordert jedoch schon V56
Wenn Sie beide Verfahren betreiben ist im Grant-Skript (V56 oder houmlher) die Einstellung fuumlr beide Verfahren zu aktivieren
====================================================
DEKLARATIVER TEIL MUSS vom KUNDEN geaumlndert
bzw auf die korrekten SCHEMA-Namen angepasst
werden
Die USER-Namen muumlssen in Groszligbuchstaben
geschrieben sein sonst werden sie nicht
gefunden
====================================================
sUserBALVI_IP = BALVI_IP_SCHEMA
sUserBALVI_WEB = WEBAPP_SCHEMA
-- Verfahrensbezogene Konfiguration
-- Setzen Sie fuumlr das jeweilige Verfahren eine 1
-- BALVI Schnittstellenserver (BSS)
-- bis V266 auch BALVI Kommunikationsserver (BKS) genannt
-- generell fuumlr die meisten Verfahren guumlltig
-- Ab Version 57 entfaumlllt mit der Einfuumlhrung der
-- Schnittstelle XGewerbeanzeigen auch der separate Schalter
-- WS_BTR beide Verfahren wurden vereinheitlicht
WS_BSS = 1
-- WebService BTR (Betriebsstaumlttenregister) (NRW TH)
-- entfernt mit Update V57 setzen Sie stattdessen bei WS_BSS = 1
--WS_BTR = 0
-- Probenahme Futtermittel im Browser(BY)
WS_PROBE_FM = 0
-- Risikoorientierte Probenplanung Futtermittel ndash RIOPP FM (BY)
WS_RIOPP_FM = 0
-- Verfahren Export an EFi (Status Pilotbetrieb)
WS_EFI = 1
-- neu ab Version 35 des Grant-Skriptes ist die Moumlglichkeit den Webuser
Release Notes BALVI Schnittstellenserver Seite 17 von 37
-- fuumlr das Loumlschen der Ausgangskoumlrbe explizit zu berechtigen bzw sogar einen
-- expliziten abweichenden User festzulegen Die Konfiguration in der
-- Job-Oberflaumlche sieht vor dass man die Oracle-Datenbank-Zugangsdaten fuumlr
-- das Loumlschen einstellen muss Hier muss im Normalfall derselbe Oracle
-- Datenbankbenutzer eingetragen werden wie in der Tomcat-Verbindungs-
-- konfiguration In diesem Fall sollte wenn WS_EFI = 1 eingestellt wurde
-- ebenfalls WS_EFI_DELETE = 1 eingestellt werden
-- Alternativen
-- 1) Datenbankbenutzer aumlndern
-- Wenn bei sUserEFI_TRUNC anstatt sUserBALVI_WEB (Standard) ein anderer
-- Oracle-Benutzername angegeben wird wird das Loumlschrecht fuumlr die EFi
-- Ausgangskoumlrbe Datenbankseitig exklusiv dem angegeben Datenbankbenutzer
-- zugewiesen
-- 2) Loumlschrecht verweigern
-- Setzen Sie die Variablen WS_EFI_DELETE = 0 damit kein Loumlschrecht
-- zugeweisen wird
WS_EFI_DELETE = 0
-- Beispiel Anderer Benutzer muss in der Datenbank existieren
-- Entfernen Sie die fuumlhrenden -- vor der Variable sUserEFI_TRUNC und
-- setzen den entsprechenden Oracle-Benutzer ein
--sUserEFI_TRUNC = TEST_EFI_TRUNC
hellip
25 Konfiguration des Schnittstellen-Servers
251 Die bdquocontextxmlldquo-Parameter Die von der Servlet-Spezifikation vorgegeben Rump-Struktur sieht folgendermaszligen aus
ltxml version=10 encoding=utf-8gt
ltDOCTYPE Contextgt
ltContextgt
lt-- Kundenspezifische Einstellungen --gt
ltContextgt
Anwendungsspezifische Einstellungen werden zwischen ltContextgt und ltContextgt eingefuumlgt Alle allgemeinguumlltigen Einstellungen in der Datei bdquocontextxmlldquo werden hier erlaumlutert Kommentare finden sich auch in der von BALVI ausgelieferten Beispiel-Konfiguration
Neben den im Folgenden beschriebenen Standard-Einstellungen kann es auch vorkommen dass bundeslandspezifische Erweiterungen vorhanden sind welche nicht in dieser Dokumentation aufgefuumlhrt werden Diese funktionieren trotzdem regulaumlr weiter wenn keine expliziten Informationen zu Kompatibilitaumltsproblemen in den Release-Notes aufgefuumlhrt wurden
2511 Datenbankverbindung jdbcDataSource
Die Datenbankverbindung wird uumlber die von DBCP und dem Oracle-Treiber vorgegebenen Moumlglichkeiten realisiert Der Einsatz der orgapachetomcatjdbcpoolDataSourceFactory (automatisch verfuumlgbar ab Apache Tomcat 7 in der mitgelieferten tomcat-dbcpjar) wird als Beispiel-Konfiguration ausgeliefert
ltResource
name=jdbcDataSource
auth=Container
Release Notes BALVI Schnittstellenserver Seite 18 von 37
type=javaxsqlDataSource
factory=orgapachetomcatjdbcpoolDataSourceFactory
maxActive=10 initialSize=3
maxIdle=5
maxWait=10000
url=jdbcoraclethinBL2-ORA10-KUNDENBALVIINTERN1521ORCL
driverClassName=oraclejdbcdriverOracleDriver
username=balvi_webservice_schema
password=balvi_webservice_password
description=Oracle Datasource
maxOpenPreparedStatements=50
removeAbandoned=false
removeAbandonedTimeout=100
logAbandoned=true
jdbcInterceptors=hellip
gt
Hinweise zur Einstellung der jdbcDataSource
Standard-Einstellungen fuumlr den Datenbank-Verbindungspool
Der Verbindungspool muss entsprechend der Anzahl der zu erwartenden gleichzeitigen Benutzer konfiguriert werden Wenn Sie erwarten dass 50 Anwender gleichzeitig arbeiten stellen Sie bitte folgende Werte ein
maxActive=(50 + 10 (fuumlr System und Jobs)) = 60
maxIdle= (50 10) = 5
1 maxActive - maximale Anzahl der gleichzeitigen aktiven Anfragen an die DB
Wenn der Werte maxActive erreicht ist z B wenn mehrere Benutzer gleichzeitig einen Export starten moumlchten welcher laumlngere Zeit in Anspruch nimmt dann kann der Server die Anfrage nicht mehr bedienen und der Anwender wird abgewiesen maxActive hat zudem Auswirkungen auf die im Hintergrund ausgefuumlhrten Jobs maxActive wird daher kalkuliert mit der Anzahl der Anwender und moumlglicher Datenbank-Connections fuumlr Hintergrund-Jobs Jeder aktiv ausgefuumlhrte Job benoumltigt mindestens eine Connection nur selten wird aus Performance-Gruumlnden mehr als eine Connection waumlhrend der Job-Ausfuumlhrung verwendet Im Normalfall sollten daher 10 Connections fuumlr Hintergrundprozesse ausreichend sein
2 maxIdle - Anzahl der offenen Verbindungen auch wenn der Server im Leerlauf ist
Jede offene Verbindung im Leerlauf haumllt auf dem Datenbankserver eine Session offen Auch diese erfordert Ressourcen Wenn die Verbindungen jedoch geschlossen werden kann die Anfragezeit fuumlr eine neue Verbindung steigen da diese Verbindung erst neu ausgehandelt werden muss Die Empfehlung fuumlr den Wert bdquomaxIdleldquo ist ca 10 der Einstellung von maxActive
KeepAlive-Einstellungen fuumlr den Pool
1 validationQuery
Diese wird ausgefuumlhrt um die Verbindung zu DB zu validieren Es MUSS ein Datensatz zuruumlckgegeben werden ansonsten nimmt der DBCP an dass die Abfrage nicht erfolgreich abgesetzt wurde Achten Sie also bitte darauf dass die Abfrage nicht zu leitungsintensiv ist und genau einen Datensatz liefert
Release Notes BALVI Schnittstellenserver Seite 19 von 37
Oracle bietet dafuumlr die virtuelle Tabelle DUAL an welche sich fuumlr die ValidationQuery sehr gut eignet da die Abfrage kaum Ressourcen verbraucht
validationQuery=select 1 from dual
2 testOnBorrow - Boolscher Wert true oder false
Diese Einstellung sorgt dafuumlr dass der Pool die Verfuumlgbarkeit anhand der validationQuery pruumlft bevor
die DB-Verbindung an die Anwendung ausgeliehen wird Empfehlung
testOnBorrow=true
3 testWhileIdle - Boolscher Wert true oder false
Diese Einstellung ist hilfreich wenn zwischen dem Tomcat und der DB eine Firewall mit Stateful
Packet Inspection verwendet wird Nach laumlngerer Inaktivitaumlt wird normalerweise durch die Firewall die
DB-Verbindung geschlossen Dieses loumlst dann beim Ausleihen der Verbindung eine Fehlermeldung im
Protokoll aus 2012-08-16 165418720 WARN [http-0000-8080-8]
[orgspringframeworkjdbcsupportSQLErrorCodesFactory] Error while extracting
database product name - falling back to empty error codes
orgspringframeworkjdbcsupportMetaDataAccessException Error while extracting
DatabaseMetaData nested exception is javasqlSQLRecoverableException Getrennte
Verbindung Um dieses Problem zu beheben sollte die Option testWhileIdle=true eingestellt werden
testWhileIdle=true
Damit diese weiszlig wie oft eine Pruumlfung durchgefuumlhrt werden muss sind jedoch noch zusaumltzliche Angaben erforderlich welche fuumlr die Einstellung der Zeit zusaumltzlich gesetzt werden muumlssen
a) minEvictableIdleTimeMillis - Long in Millisekunden
Min Zeit wie lange eine DB-Verbindung im Leerlauf ist bevor diese zur Pruumlfung
gekennzeichnet wird Dieses haumlngt stark von der Einstellung der Firewall ab Wenn Sie eine
sehr restriktive Firewall haben kann es sein dass diese die Verbindung nach wenigen
Minuten Leerlauf trennt Stellen Sie den Wert immer so ein dass dieser unter der Leerlaufzeit
der Firewall liegt empfohlen 300000 entspricht 300 Sek = 5 min
minEvictableIdleTimeMillis=300000
b) timeBetweenEvictionRunsMillis - Long in Millisekunden
Der Pruumlflauf startet in der Default-Konfiguration alle 1800000 Millisekunden = 30 Min n als
zu Pruumlfen markierte Verbindungen werden in einem Pruumlflauf getestet n wird bestimmt durch
die Einstellung numTestsPerEvictionRun Empfehlung Stellen Sie den Wert auf alle 15 Min
ein
timeBetweenEvictionRunsMillis=900000
Release Notes BALVI Schnittstellenserver Seite 20 von 37
c) numTestsPerEvictionRun - Integer
Wie viele Verbindungen sollen getestet werden waumlhrend der Pruumlflauf ausgefuumlhrt wird Im
Normalfall sollte die Anzahl der zu testenden Verbindungen nicht zu hoch eingestellt werden
Der Default ist 3 Wenn Sie houmlhere Sicherheit haben wollen dass keine bdquototenldquo
Datenbankverbindungen bestehen bleiben erhoumlhen Sie den Wert auf max bdquo(maxActive ndash
maxIdle) 2ldquo Wenn Ihnen 3 ausreichend erscheint muss der Wert nicht gesetzt sein dann
wird der Default verwendet
Beispiel numTestsPerEvictionRun=10
4 Interceptors konfigurieren Neu ergaumlnzt wurde die Moumlglichkeit spezielle bdquoInterceptorsldquo zu konfigurieren die ermoumlglichen das Verhalten des Pools zu steuern Wichtig hierbei ist dass die Angabe von Werten auf real existierende Java-Klassen erfolgt die im Classpath des Tomcat vorhanden sind Groszlig-und-Kleinschreibung ist zu beachten Folgende Default-Einstellung hat BALVI fuumlr den BSS festgelegt jdbcInterceptors=
orgapachetomcatjdbcpoolinterceptorConnectionState
orgapachetomcatjdbcpoolinterceptorStatementFinalizer
orgapachetomcatjdbcpoolinterceptorResetAbandonedTimer
Details zu den verwendeten Interceptor-Einstellungen finden Sie in der Tomcat-Dokumentation3
3 httptomcatapacheorgtomcat-80-docjdbc-poolhtmlJDBC_interceptors
Release Notes BALVI Schnittstellenserver Seite 21 von 37
2512 Datenbank-Zugangsdaten verschluumlsseln
Die Verschluumlsselung fuumlr die Datenbank-Verbindung (bdquoEncrypted Datasourceldquo) ist eine Ableitung der Bibliothek Apache-Common-DBCP-14 und daher nicht mehr mit Java 8 kompatibel Die Einrichtung der Verschluumlsselung wird daher mit der Auslieferung des BSS 30 nicht mehr angeboten
2513 Active-Directory-Authentifizierung
Uumlber die folgenden Parameter wird der Zugriff des Schnittstellen-Servers auf einen Microsoft Active Directory Domain-Controller konfiguriert
ldquoldapServerAddressrdquo
Syntax PROTOKOLLIP-Adresse oder DNS-NamePORT
ltEnvironment
name=ldapServerAddress
value=ldapbl2-dc02balviintern389
type=javalangString
override=true
gt
Als Protokoll besteht auch die Moumlglichkeit ldaps (LDAP+SSL) wenn der Domain-Controller entsprechend konfiguriert wurde Im Java Truststore muss dann das Zertifikat der CA vorhanden sein welche das Zertifikat des Domain-Controllers signiert hat Zudem darf bei ldaps keine IP-Adresse verwendet werden es muss der DNS-Name des Server-Zertifikats eingetragen sein Ansonsten gibt es beim Verbinden eine Sicherheits-Exception
lt-- SSL-Beispiel
ltEnvironment
name=ldapServerAddress
value=ldapsbl2-dc02balviintern636
type=javalangString
override=true
gt
--gt
bdquoldapBaseDnrdquo
LDAP-Suchpfad fuumlr die Domain-Basis Diese muss der LDAP-Syntax fuumlr den Domain-Suffix entsprechen
Syntax DC=SERVERDC=ROOTDN
ltEnvironment
name=ldapBaseDn
value=DC=BALVIDC=INTERN
type=javalangString
override=true
gt
Release Notes BALVI Schnittstellenserver Seite 22 von 37
bdquowebLoginUseActiveDirectoryAuthenticationrdquo
Die Authentifizierung in der Browser-Oberflaumlche kann uumlber die Active-Directory-Authentifizierung erfolgen In der ersten Version ist nur die Protokoll-Auswertung moumlglich wenn der ADMIN sich anmeldet Dieser hat normalerweise niemals AD-Kennungen zugeordnet BALVI empfiehlt diese Einstellung auf bdquofalseldquo zu belassen Webservices welche uumlber SOAPREST zugreifen koumlnnen die Active-Directory-Authentifizierung trotzdem verwenden
ltEnvironment
name=webLoginUseActiveDirectoryAuthentication
value=false
type=javalangBoolean
override=true
gt
ldquoldapDaysBeforeExpirationNotificationrdquo
Die Passwort-Aumlnderung im Active-Directory uumlber die Browser-Oberflaumlche ist in der ersten Version noch nicht implementiert der Parameter wird bislang nicht ausgewertet
ltEnvironment
name=ldapDaysBeforeExpirationNotification
value=14
type=javalangInteger
override=true
gt
2514 Statement-Protokollierung in BALVI iP
Diese Option aktiviert die Lese- und Aumlnderungsprotokollierung fuumlr BALVI iP Standard ist bdquofalseldquo und wird fuumlr alle Kunden empfohlen solange keine speziellen Datenbank-Jobs eingerichtet wurden welche zeitgesteuert die Protokolleintraumlge wieder loumlschen Fuumlr Bayern wurde ein spezielles Konzept zur Leseprotokollierung entworfen Wenn Sie mehr daruumlber erfahren moumlchten kontaktieren Sie bitte die BALVI GmbH
ltEnvironment
name=enableSqlStatementMonitoring
value=true
type=javalangBoolean
override=true
gt
Beachten Sie dass diese Option massive INSERT-Statements in BALVI iP in die Tabelle VIS_D92 ausfuumlhrt Jedes abgesetzte SQL-Statement wird dabei vollstaumlndig protokolliert Dieses erzeugt eine sehr hohe INSERT-Last und in der Folge auch erhoumlhte Redolog-Switches und COMMIT-Transaktionen
Optional Aktivieren der INSERT + APPEND - Logik
Beachten Sie bitte die Hinweise von Oracle zum Hint + APPEND
Release Notes BALVI Schnittstellenserver Seite 23 von 37
Wenn Sie dieses Verhalten aktivieren moumlchten ergaumlnzen Sie bitte den folgenden Environment-Parameter
ltEnvironment
name=statementMonitoringactivateAppendMode
value=true
type=javalangBoolean
override=true
gt
2515 Einstellungen fuumlr BALVI mobil XT (bzw den bdquopartitionedExportldquo)
Diese Logik des FIFO-Buffers wurde so konzipiert dass dem Rechenzentrum diverse Einstellmoumlglichkeiten uumlber die Datei bdquocontextxmlldquo zur Verfuumlgung stehen um die Steuerung des FIFO-Puffers zu beeinflussen
Schematische Darstellung des FIFO-Puffers
Das ermoumlglicht es z B dem BALVI mobil XT Client (14 oder houmlher) den aktiven Block abzuholen und dies beim Fehler bis zu 10-mal zu wiederholen Sobald der Block [001] erfolgreich beim Client angekommen ist und dieser den naumlchsten Block anfragt wird der Block [001] verworfen wird Der Server fuumlllt dann im Hintergrund den frei gewordenen Block wieder waumlhrend der Client den Block [002] abholt
Die Groumlszlige und Anzahl der vorgecachten Bloumlcke kann uumlber die folgenden Einstellungen in der Datei bdquocontextxmlldquo definiert werden
ltEnvironment
name=partitionedExportmaxBufferedPartitions
value=3 type=javalangInteger override=true
gt
ltEnvironment
name=partitionedExportpartitionSize
value=256000 type=javalangInteger override=true
gt
Die Einstellung partitionedExportmaxBufferedPartitions ist dabei die Anzahl der vorgecachten Bloumlcke mindestens muss 2 angegeben werden Der Puffercache wird ausschlieszliglich im RAM der JVM aufgebaut es wird folglich mehr Arbeitsspeicher verwendet Dieser Arbeitsspeicher muss je gleichzeitiger Session auf dem Server bereitgestellt werden die Default-Einstellung mit 3 Partitionen a 256 KB + dem aktiven Puffer erfordern 1 MB RAM je aktiven Anwender
Aktiv
er
Puffe
r
[001] Vorg
ecac
hter
Bl
ock
[002] Vorg
ecac
hter
Bl
ock
[003]
Aktiv
er P
uffe
r
[002] Vorg
ecac
hter
Bl
ock
[003] Vorg
ecac
hter
Bl
ock
[leer]
Release Notes BALVI Schnittstellenserver Seite 24 von 37
Gleichzeitig wurde die Moumlglichkeit geschaffen dass die maximale Anzahl an gleichzeitigen Exporten durch das Rechenzentrum eingeschraumlnkt werden kann um einem OutOfMemory-Fehler vorzubeugen Die Einstellung
ltEnvironment
name=partitionedExportmaxConcurrentExports
value=10 type=javalangInteger override=true
gt
muss entsprechend der zu erwartenden gleichzeitigen Zugriffe konzipiert werden ansonsten wird der Server einen Verbindungsversuch durch die Clients ablehnen
Beachten Sie dass die folgenden Einstellungen partitionedExportmaxBufferedPartitions partitionedExportmaxConcurrentExports und partitionedExportpartitionSize gemeinsam als Rechenbasis fuumlr den RAM-Bedarf des Webservers herangezogen werden muumlssen
Folgende Faustformel sollte fuumlr die Einrichtung verwendet werden
Min 256 MB (Serverbasis) + (11 partitionedExportmaxConcurrentExports partitionedExportmaxBufferedPartitions partitionedExportpartitionSize)
Beispiel 50 gleichzeitige Anwender Blockgroumlszlige 256 KB 4 Partitionen
256 MB + (11 50 256 4) KB = 312 MB fuumlr die JVM
Empf 512 MB (Serverbasis) + (12 partitionedExportmaxConcurrentExports partitionedExportmaxBufferedPartitions partitionedExportpartitionSize)
Beispiel 50 gleichzeitige Anwender Blockgroumlszlige 256 KB 4 Partitionen
512 MB + (12 50 256 4) KB = 572 MB fuumlr die JVM
partitionedExportmaxConcurrentExports
Bestimmt die Anzahl der maximalen Export Tasks (Threads) die fuumlr partitionierte Exporte bereitgestellt werden Wenn die Anzahl uumlberschritten wird wird die entsprechende Exportanfrage abgewiesen und der Client muss zu einem spaumlteren Zeitpunkt erneut anfragen Stellen Sie diesen Wert entsprechend der zu erwartenden Benutzeranzahl ein bei 50 Anwendern also 50
Exporte oumlffnen auf der Datenbank entsprechend zur Ausfuumlhrungszeit min einen Cursor ggf fuumlr rekursive Unterabfragen kurzfristig sogar mehr Die hier eingestellte Anzahl muss mit der Anzahl von maxActive korrelieren
ltEnvironment
name=partitionedExportmaxConcurrentExports
value=10 type=javalangInteger override=true
gt
partitionedExportmaxBufferedPartitions
Bestimmt die Anzahl der Datenbloumlcke (Partitionen) die vom Server bei Abruf eines Exportes gepuffert werden Die seit Version 24 eingefuumlhrte FIFO-Puffer-Logik ermoumlglicht dass der Server schon die Ergebnisse vorpuffert so dass der Client weniger Wartezeiten bei der Anfrage nach Daten hat Diese
Release Notes BALVI Schnittstellenserver Seite 25 von 37
Puffer-Logik unterteilt den Exportdatenstrom (je Export) in mehre Bloumlcke Der Client kann nun den letzten Block neu anfordern oder den naumlchsten Block wenn der letzte Block erfolgreich verarbeitet wurde Wie viele naumlchste Bloumlcke durch den Server bereit gestellt werden entscheidet diese Einstellung Sobald kein naumlchster Block mehr bereit gestellt werden muss wird der Datenbank-Cursor geschlossen eine Erhoumlhung kann also zu einer Entlastung der aktiven DB-Verbindungen fuumlhren erhoumlht jedoch den Bedarf an RAM des Servers
Der von BALVI voreingestellte Wert ist 3
ltEnvironment
name=partitionedExportmaxBufferedPartitions
value=3 type=javalangInteger override=true
gt
partitionedExportpartitionSizeldquo
Die Groumlszlige der Datenbloumlcke (Partitionen) die an den Client uumlbermittelt werden in Bytes Wenn Sie diesen Wert zu niedrig einstellen reduziert sich die Effizienz des Caches da der Client mehr Datenbloumlcke hintereinander abrufen muss Waumlhlen Sie einen zu groszligen Wert wird die neu zu uumlbertragende Datenmenge im Fall eines Fehlers houmlher
Der von BALVI voreingestellte Wert ist 256000 (256 KB)
ltEnvironment
name=partitionedExportpartitionSize
value=256000 type=javalangInteger override=true
gt
exportTokensmaxTokenCount
Maximale Anzahl der gleichzeitig vergebenen Token die vom Server gecached werden Jede Sitzung welche einen Export durchfuumlhrt erhaumllt einen Session-Token
Wenn eine Sitzung laumlngere Zeit nicht verwendet wurde wird dieser Session-Token wieder entfernt Wenn Sie den Wert zu niedrig einstellen fuumlhrt das zu einer generellen Session-Begrenzung auch fuumlr den nicht partitionierten Export-Modus welcher ab Version 21 verfuumlgbar ist
Ist die Anzahl der Tokens houmlher als die Datenbankeinstellung maxActive kann es vorkommen dass zwar eine Session gestartet werden kann jedoch kein Datenexport zustande kommt
Der von BALVI voreingestellte Wert ist 2000
ltEnvironment
name=exportTokensmaxTokenCount
value=20 type=javalangInteger override=true
gt
exportTokenstokenExpirationInSeconds
Zeit in Sekunden die verstreichen muss bis ein Token unguumlltig wird falls darauf kein Zugriff mehr erfolgt Nach einem erfolgreichen Export wird der Token automatisch geschlossen diese Option ist fuumlr den Abbruchfall vorgesehen Der von BALVI voreingestellte Wert ist 180 (180 s = 3 min)
Release Notes BALVI Schnittstellenserver Seite 26 von 37
ltEnvironment
name=exportTokenstokenExpirationInSeconds
value=180 type=javalangInteger override=true
gt
exportTokenstokenDisposalInSeconds
Zeit in Sekunden die verstreichen muss bis ein Token das erfolgreich abgearbeitet wurde aus dem Cache geloumlscht wird Um sicher zu stellen dass der letzte Exportblock noch erfolgreich abgerufen werden kann bleibt der Token auch nach Fertigmeldung des Clients noch N Sek guumlltig
Der von BALVI voreingestellte Wert ist 60 (60 s = 1 min)
ltEnvironment
name=exportTokenstokenDisposalInSeconds
value=60 type=javalangInteger override=true
gt
2516 Job-Verwaltung fuumlr den BSS konfigurieren Aktivierung der Jobverwaltung
Bis zur Version 28 des BSS gab es den Parameter bdquoavailableServicesldquo Dieser konnte bei Bedarf aktiviert werden wenn die Jobs benoumltigt wurden
Mit Version 30 ist die Einstellung bdquoavailableServicesldquo zu entfernen und kann durch den neuen optionalen Parameter bdquoisJobServiceEnabledldquo in der Datei bdquocontextxmlldquo ersetzt werden
lt-- Neue Parameter zur Aktivierung des Job Service Ersatz fuumlr availableServices --gt
ltEnvironment
name=isJobServiceEnabled
value=true
type=javalangBoolean
override=true
gt
Ab BSS 30 wird die Jobs-Engine standardmaumlszligig aktiviert Sollte die Jobs-Engine nicht benoumltigt werden muss bdquovalueldquo der Wert bdquofalseldquo zugewiesen werden Wird bdquoisJobServiceEnabledldquo nicht eingefuumlgt sind die Jobs trotzdem standardmaumlszligig aktiv
Nach dem Neustart des Servers und erneutem Einloggen erscheint nun zusaumltzlich der Menuumlpunkt bdquoJobsldquo
bdquopasswordKeyldquo fuumlr Jobs
In der Job-Logik wird ein von BALVI definierter Standard-Schluumlssel fuumlr die Ablagen von schuumltzenswerten Daten z B Passwoumlrtern verwendet Diese Einstellung ermoumlglicht den BALVI-Standard zu uumlberschreiben Wenn Sie diese Einstellung aumlndern muumlssen jedoch alle bislang verschluumlsselten Job-Parameter neu verschluumlsselt werden
ltEnvironment
name=javacompenvjobspasswordKey
value=MeinHochsicheresNeuesPasswort
type=javalangString
Release Notes BALVI Schnittstellenserver Seite 27 von 37
override=true
gt
bdquoJob ID enableddisabledldquo (Deprecated ersetzt ab 28 durch das bdquoBindenldquo von Jobs)
Sondereinstellungen fuumlr die Job-Verwaltung Da alle Jobs in einer Datenbank administriert werden jedoch ggf verteilt auf mehreren Tomcat-Servern ausgefuumlhrt werden sollen besteht hier die Option Jobs fuumlr die aktuelle Tomcat-Instanz separat zu deaktivieren
Die Einstellung ID koumlnnte z B folgendermaszligen aussehen javacompenvjobsC0DB58D8D52C4BBC966D1DC788A4EF8Benabled
Fuumlr weitere Fragen zu dieser Einstellung kontaktieren Sie bitte die BALVI GmbH
ltEnvironment
name=javacompenvjobsIDenabled
value=false
type=javalangBoolean
override=true
gt
2517 Weitere optionale Parameter
Es ist fuumlr diverse einzelne Schnittstellen ggf erforderlich Einstellungen in der Datei bdquocontextxmlldquo zu ergaumlnzen Hinweise zu diesen Parametern sind dann in dem der Schnittstelle beiliegenden Dokument enthalten Das gilt z B fuumlr die Schnittstelle bdquoXGewerbeanzeigenldquo
26 Logging mit logback Das Logging wurde komplett uumlberarbeitet Statt bdquoLog4Jldquo wird jetzt bdquologbackldquo4 benutzt Ab BSS 30 ist es zwingend notwendig die Einstellung vorzunehmen um das Logging der Anwendung zu steuern
Migration Ergaumlnzen Sie die neue Einstellung bdquologgingconfigldquo
lt-- Neue Paramter zur Angabe der Logback Config Ersatz fuumlr log4jConfigLocation --gt
ltEnvironment
name=loggingconfig
value=$catalinabaseconflogback-bssxml
type=javalangString
override=true
gt
Nach wie vor steht es Ihnen frei die Logging-Konfiguration eigenstaumlndig anzupassen
Wenn Sie jedoch dieselbe WAR in einer Tomcat-Instanz unter mehreren Context-Namen betreiben wuumlrden beide dieselbe Logging-Konfiguration verwenden so dass alle Protokolleintraumlge in einer Log-Datei aus
4 httplogbackqoschmanualappendershtml
Release Notes BALVI Schnittstellenserver Seite 28 von 37
mehreren Webanwendungen generiert werden Aumlndern Sie den Namen der Logging-Konfiguration entsprechend ab um fuumlr jede Anwendung eine spezifische Logging-Einstellung vornehmen zu koumlnnen
27 Tocmat Optional Suche im bdquoKlassenpfadldquo um den
Ordner bdquoconfldquo erweitern Die Suche nach Dateien uumlber bdquoclasspathldquo setzt voraus dass die Ordner- und Dateinamen im Apache Tomcat bekannt gegeben werden Der Klassenpfad kann in der Datei bdquocatalinapropertiesldquo angepasst werden Wenn Sie dort unter commonloader die folgenden Werte ergaumlnzen kann eine Datei auch im Ordner conf abgelegt werden damit Apache Tomcat diese findet Ansonsten muss die Datei im Ordner lib abgelegt werden
commonloader=$catalinabaseconf$catalinahomeconf
3 Die neue Browser-Oberflaumlche Der BALVI Schnittstellenserver hat seit Version 25 neben der Protokollierung auch die Moumlglichkeit Job-Konfigurationen zu pflegen Der Login ist nur fuumlr einen in BALVI iP eingetragenen ADMIN (z B Benutzer bdquoSYSTEMADMINldquo) mit dem in BALVI iP hinterlegten Passwort moumlglich Zur Anmeldung muss immer [SYSTEMBenutzername] im Feld Benutzer angegeben werden ansonsten schlaumlgt die Anmeldung fehl Bitte achten Sie darauf dass der bdquoldquo (Slash) und nicht der bdquoldquo (Backslash) verwendet werden muss
31 Server-Protokoll Um das Server-Protokoll anzuzeigen waumlhlen Sie den entsprechenden Menuumlpunkt Dort haben Sie seit BSS 26 die Moumlglichkeit uumlber alle Spalten der Protokolle nach Informationen zu suchen
Seit BSS 31 gibt es die Moumlglichkeit Verfahren in bdquoKopfsaumltzeldquo und bdquoDetailsaumltzeldquo zu unterteilen Wurde das Verfahren entsprechend konfiguriert (wie z B bei der Schnittstelle bdquoXGewerbeanzeigenldquo) dann wird im Protokoll-Kopfsatz nur der Start und das Ende der Ausfuumlhrung in der Liste angezeigt Erst bei einem Klick auf bdquoInformationenldquo wird die Liste aller Detailsaumltze angezeigt die im Durchlauf erzeugt wurden
Release Notes BALVI Schnittstellenserver Seite 29 von 37
Verfahren
Die Liste der verfuumlgbaren Verfahren die bei Ihnen im System installiert sind ZB
BEFUNDEhellip Schnittstelle Befunde LM FM oder TS
PROBEhellip Schnittstelle zum Export von Proben an Labore ebenfalls Spezifisch fuumlr einzelne Fachbereiche
MOBILXT Protokolle der BALVI Mobil XT Synchronisation
WEB Allgemeine nicht spezifizierte Protokolle hierunter ist bislang auch die eFi-Protokollierung zu finden
WEB_I0802 Protokolle zur Schnittstelle BALVI iP LIMS (Lebensmittelproben)
XGEWERBE Schnittstelle XGewerbeanzeigen
Klicken Sie auf die Schaltflaumlche so besteht bei den neuen Protokolldatensaumltzen die Moumlglichkeit Detail-Informationen zum Protokollsatz zu erhalten
Release Notes BALVI Schnittstellenserver Seite 30 von 37
Seit BSS 30x ist die Anzeige der Protokolle ebenfalls farblich abgesetzt so dass Protokolleintraumlge mit Fehlern hellrot und Warnungen hellgelb hinterlegt werden
32 Jobs Mit einem Klick auf den Menuumlpunkt Jobs rufen Sie die Oberflaumlche fuumlr die Job-Konfiguration auf Daraufhin werden alle Jobs aufgelistet die fuumlr den BSS freigegeben sind Hier koumlnnen Sie Einstellungen an den Jobs vornehmen und die Jobs aktivieren bzw deaktivieren Die Beschreibungen bzw Einstellungsmoumlglichkeiten fuumlr den jeweiligen SST-Job sind nicht Bestandteil dieser Dokumentation
33 Log-Ausgaben Uumlber den Menuumlpunkt Log-Ausgaben koumlnnen Sie die Ausgabe der Protokolleintraumlge in Echtzeit beobachten
Release Notes BALVI Schnittstellenserver Seite 31 von 37
Starten Sie die Echtzeit-Protokollierung indem Sie auf die Schaltflaumlche mit dem Symbol bdquoPlayldquo (Dreieck) klicken unterbrechen Sie die Ausgabe indem Sie die auf Schaltflaumlche mit dem Symbol bdquoPauseldquo (zwei Balken) klicken
Klicken Sie auf die Schaltflaumlche bdquoAktualisierenldquo (zwei Pfeile) um die neuesten Protokolleintraumlge angezeigt zu bekommen
Klicken Sie auf das Symbol mit dem Papierkorb um die letzten Protokollmeldungen in der Anzeige zu loumlschen
Die Daten in den Protokolldateien auf der Festplatte des Servers sind davon nicht betroffen
Uumlber das Symbol bdquoLogging anpassenldquo (Schraubenschluumlssel) koumlnnen Sie die Ausgabe der Daten im Echtzeitfenster und in den Protokolldateien aumlndern jedoch ist diese Einstellung nur temporaumlr Die Standardeinstellungen koumlnnen ausschlieszliglich uumlber die Anpassung der Datei bdquologback-bssxmlldquo im Konfigurationsverzeichnis des Servers selbst geaumlndert werden
Release Notes BALVI Schnittstellenserver Seite 32 von 37
In der Logging-Parameter Konfiguration koumlnnen Sie verschiedene Parameter einstellen und uumlber die Schaltflaumlche bdquoAnwendenldquo dann sofort im Echtzeitprotokoll sehen Welche Einstellungen moumlglich sind erfahren Sie wenn es eine akute Fehlersituation gibt die detailliertere Ausgaben im Protokoll erfordert
Warnung Wenn Sie den Log-Level fuumlr ROOT oder eine andere Klasse auf TRACE einstellen werden sehr viele Protokollausgaben generiert die auch dazu fuumlhren koumlnnen dass der Server sehr langsam wird oder die Festplatte des Servers zulaumluft wenn fuumlr das Logging kein Dateilimit konfiguriert wurde
34 LogoutAbmeldung vom System Zum Abmelden waumlhlen Sie oben rechts das Kontextmenuuml
35 Cache loumlschen Der Cache wird in der Regel automatisch geloumlscht Wenn Sie jedoch gerade in BALVI iP eine Aumlnderung an den Schnittstellen eingespielt haben und moumlchten dass diese sofort wirksam wird kann die Funktion bdquoCache loumlschenldquo dazu verwendet werden dass der BALVI Schnittstellenserver die Einstellungen bei der naumlchsten Anfrage neu einliest
Release Notes BALVI Schnittstellenserver Seite 33 von 37
Release Notes BALVI Schnittstellenserver Seite 34 von 37
4 Einrichtung in BALVI iP Um die Verfahren fuumlr den BALVI Schnittstellenserver fuumlr Anwender freizuschalten wird das Objekt bdquoSystemeinstellungenldquo oder bdquoMandanten- und Benutzereinstellungenldquo verwendet Die Anpassung ist je Verfahren moumlglich so kann in BALVI iP fuumlr den Zugriff durch den BALVI Schnittstellenserver ein Benutzer bdquoAldquo am Verfahren bdquoMobilldquo berechtigt werden ein Benutzer bdquoBldquo nur am Verfahren bdquoSLA_FLESHldquo usw Die Logik ist jedoch einheitlich Je Verfahren wird durch BALVI eine Verfahrensgruppe mit dem Verfahrensnamen angelegt und mit den entsprechenden Einstellungen vorkonfiguriert welche durch das Verfahren erforderlich sind Dabei kann die Komplexitaumlt der Einstellungen variieren wie z B an den zu Version 23 verfuumlgbaren Verfahren bdquoMobilldquo und bdquoSLA_Fleshldquo ersichtlich wird
Im Verfahren BALVI Mobil sind diverse Anpassungen moumlglich welche je Bundesland oder eingesetzter Import- und Export-Variante durch den BALVI Schnittstellenserver bei der Bearbeitung von Anfragen gepruumlft werden siehe Punkt 3 Abb Mobil-Einstellung in BALVI iP
Abb Mobil-Einstellung in BALVI iP
Alle Verfahren verwenden jedoch die regulaumlre Benutzerverwaltung von BALVI iP Ein Benutzer ohne Passwort gilt fuumlr BALVI iP als gesperrt was fuumlr das Login bedeutet dass der Anwender sich nur uumlber die Active-Directory-Authentifizierung anmelden kann Ist das nicht moumlglich (bzw nicht konfiguriert) kann der Anwender sich weder in BALVI iP noch uumlber die Webservice-Schnittstelle authentifizieren
Fuumlr Dienste-Schnittstellen welche keine persoumlnliche Authentifizierung durch einen Anwender erfordern wird empfohlen einen separaten Benutzer in der Benutzerverwaltung anzulegen und ein sicheres Kennwort zu vergeben Das Anlegen von zusaumltzlichen Benutzern gilt nicht fuumlr BALVI mobil XT da beim Holen und Uumlbermitteln von Daten jeder Benutzer auch ein fachlich konfigurierter Anwender innerhalb von BALVI iP ist und die Anwendungsoberflaumlche ebenfalls zur Erfassung von Daten verwendet
Unter Punkt 2 der Abb Mobil-Einstellung in BALVI iP wird ein modales Fenster geoumlffnet (Abb BALVI mobil Benutzerverwaltung) Innerhalb dieses modalen Fensters werden mandantenweise die Benutzer fuumlr BALVI
Release Notes BALVI Schnittstellenserver Seite 35 von 37
mobil und den jeweiligen Fachbereich festgelegt Dabei ist es wichtig dass man die Haken bdquoAktiv fuumlr hellipldquo bei bdquohellip mobilldquo und bei einem Fachbereich (bdquohellip LMldquo bdquohellip FMldquo usw) setzt weil sonst uumlber den BALVI Schnittstellenserver keine Kommunikation mit BALVI iP moumlglich ist
Abb BALVI mobil Benutzerverwaltung
Alternativ zur Passwort-Authentifizierung wird wie beschrieben auch die Active-Directory-Authentifizierung angeboten Dazu muss der BALVI iP-Anwender uumlber die Schaltflaumlche bdquoDomaumlnen-Benutzer zuordnenldquo mit dem Active Directory verknuumlpft werden
Nur wenn die Active-Directory-Konfigurationen in BALVI iP und im BALVI Schnittstellenserver auf dieselbe Domaumlne verweisen sind die Domaumlnen-Zuordnung und die Active-Directory-Authentifizierung (z B uumlber BALVI mobil XT) moumlglich
Release Notes BALVI Schnittstellenserver Seite 36 von 37
5 Bekannte Probleme und Loumlsungen
51 ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner Bei der Job-Bearbeitung tritt folgender Fehler auf ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner
Behebung
Fuumlhren Sie das beiliegende IP-Patch (UPDATEexe) aus bevor Sie das WAR austauschen
52 Server startet nicht Sie finden folgende Zeilen im Protokoll (catalinaout oder bsslog)
ERROR [localhost-startStop-1] [IdentityServiceImpl] serverID must not be empty
ERROR [localhost-startStop-1] [ContextLoader] Context initialization failed
Behebung
Setzen Sie die Umgebungsvariable ldquoserverIDrdquo in der Datei bdquocontextxmlldquo
53 ORA-00942 table or view does not exist In vielen Faumlllen wird der Fehler ldquoTabelle oder View nicht vorhandenrdquo ausgeworfen (Java-Protokoll im Ordner logs von Apache Tomcat) wenn eine neue Schnittstelle eingerichtet oder ein neues BALVI iP Release bzw Update eingespielt wurde ohne anschlieszligend das aktuelle GRANT-Skript auszufuumlhren
Behebung
Fuumlhren Sie das GRANT-Skript erneut aus
54 ORA-0406x bdquoBestehender Paketstatus wurde aufgehobenldquo
ORA-04061 Bestehender Status von package body ABCXYZ wurde annulliert
ORA-04065 Ausfuumlhrung nicht erfolgreich package body ABCXYZ wurde geaumlndert oder geloumlscht
Release Notes BALVI Schnittstellenserver Seite 37 von 37
Der Fehler tritt haumlufig ein nachdem die UPDATEexe ausgefuumlhrt und in der Ausfuumlhrungsliste ein Package aktualisiert wurde Oracle merkt sich je User-Session bestimmte Werte im Package wenn der Anwender es verwendet hat Durch einen bdquoCREATE OR REPLACE PACKAGEldquo-Befehl kann dieser Status temporaumlr aufgehoben werden Normalerweise tritt dieser Fehler nach dem Update genau einmal in jeder aktiven Session auf wenn der BSS nicht neu gestartet wird
Behebung
Starten Sie nach jedem Update den BSS neu um alle laufenden Sessions zu beenden
55 Jobs sind nicht ausfuumlhrbar
1 Ein Job wird mit dem Status bdquoNicht unterstuumltztldquo angezeigt wenn fuumlr seine Ausfuumlhrung eine houmlhere Version des BSS erforderlich ist
2 Nach dem Klonen der Datenbank von der Produktions- auf die Testumgebung erhalten alle Jobs automatisch den Status bdquoDeaktiviertldquo wenn die bdquoserverIDldquo nicht identisch ist
Beide Statusaumlnderungen sind gewollt Damit soll verhindert werden dass Jobs nach einem Serverneustart oder nach einem Update automatisch starten und dabei Fehler verursachen
Um Jobs mit dem Status bdquoNicht unterstuumltztldquo nutzen und konfigurieren zu koumlnnen ist es erforderlich den BALVI Schnittstellenserver zu aktualisieren
Deaktivierte Jobs koumlnnen Sie aktivieren indem Sie den jeweiligen Job an den aktuellen Server binden und den Haken bei bdquoAktivldquo setzen
Release Notes BALVI Schnittstellenserver Seite 6 von 37
4 ETL-Prozesser
Neue Datenquellen ergaumlnzen
Fuumlr die Kommunikation zwischen iP2 Modulen und iP1 wird Kettle benutzt In die contextxml muss dafuumlr eine zusaumltzliche DataSource eingefuumlgt werden wenn Sie die Daten-Uumlbermittlung von IP1 an IP2 verwenden
Die jdbcKettleIP1DataSource ist im Beispiel auskommentiert verwendet derzeit jedoch immer die Zugangsdaten die Sie auch in der jdbcDataSource eingestellt haben da derzeit beide Datenbank-Verbindungen auf das angebundene BALVI iP (124x) zugreifen sollen Beachten Sie jedoch dass die jdbcKettleIP1DataSource die Einstellung type=debalvikettleKettleDataSourceSettings (nicht javaxsqlDataSource) verwendet damit diese nur und ausschlieszliglich dann geladen wird wenn die Kettle-Engine eine separate Datenbankverbindung benoumltigt Um ETL-Engine (Kettle) mitzuteilen welche DataSource das auszufuumlhrende Modul benoumltigt sind folgende Umgebungseinstellungen in die Datei bdquocontextxmlldquo einzufuumlgen
Beispiel
ltResource
name=jdbcKettleIP1DataSource
auth=Container
type=debalvikettleKettleDataSourceSettings
factory=orgapachetomcatjdbcnamingGenericNamingResourcesFactory
maxActive=3 maxIdle=2 minIdle=1 initialSize=1
gt
Kettle Bibliotheken
Da Kettle fuumlr die Ausfuumlhrung verschiedene Dateien benoumltigt muss zudem der Parameter bdquokettlePluginDirectoryldquo eingestellt werden Weisen Sie dem Wert (bdquovalue=ldquo) den Pfad zu dem Verzeichnis zu in dem die Ausfuumlhrungsdateien liegen Die erforderlichen Dateien sind Bestandteil der Auslieferung
ltEnvironment
name=kettlePluginDirectory
value=hometest_ip2_bsskettleplugins
type=javalangString
override=true
gt
13 Hinweise zum Update von aumllteren Versionen (vor 30x) Ab BSS 282 wird eine bdquoserverIDldquo erwartet Daher ist es zwingend erforderlich die vorhandene Datei bdquocontextxmlldquo zu erweitern und den neuen Environment-Parameter bdquoserverIDldquo zu ergaumlnzen
Release Notes BALVI Schnittstellenserver Seite 7 von 37
14 Nacharbeiten nach dem Update auf Version 28
(ADMIN) Sofern Sie schon aktive bdquoJobsldquo im BSS in Verwendung haben werden diese mit dem Update automatisch deaktiviert da die Jobs nun an den ausfuumlhrenden Server gebunden werden muumlssen Oumlffnen Sie dazu den Job in der Detailansicht setzen Sie den Haken hinter bdquoJob an Server bindenldquo setzen und speichern Sie die Einstellung
Der Job wird anschlieszligend in der Uumlbersicht wieder mit dem Status bdquoAktiviertldquo angezeigt Diesen Konfigurationsschritt muumlssen Sie nun jedes Mal durchfuumlhren nachdem die Datenbank von Produktion auf Test geklont wurde
15 Neuerungen in Version 28
151 Jeder Schnittstellen-Server benoumltigt eine Kennung bdquoserverIDldquo Viele Kunden nutzen den Schnittstellenserver mehrfach in Ihrer Umgebung da mehrere BALVI iP Installationen (z B Produktion und Test) in der Infrastruktur existieren
Da die Schnittstellenkonfiguration fuumlr den BSS in der Datenbank abgelegt wird kam es in manchen Faumlllen vor dass nach dem Klonen der Produktionsdatenbank auf ein Testsystem die im BSS angelegten Jobs sofort nach dem Start in der Testumgebung wieder angesprungen sind Um dieses Problem zu beseitigen muss jedem BSS ab Version 28 eine eindeutige bdquoserverIDldquo zugewiesen werden Diese Server-ID wird in der Datei bdquocontextxmlldquo hinterlegt um neutral zur Datenbank zu sein
Ist keine Environment-Variable bdquoserverIDldquo vorhanden wird der Start des BSS 28 (oder houmlher) sofort mit einer Fehlermeldung abgebrochen Im Server-Protokoll wird dabei der Fehler bdquoERROR [IdentityServiceImpl] serverID must not be emptyrdquo ausgegeben Danach kommt sofort die Meldung dass der BSS wieder heruntergefahren wird
INFO [localhost-startStop-1] [ContextCreationListener]
BALVI-Schnittstellen-Server
Version 280
hellip
ERROR [localhost-startStop-1] [IdentityServiceImpl] serverID must not be empty
ERROR [localhost-startStop-1] [ContextLoader] Context initialization failed
Um eine ldquoserverIDrdquo zu vergeben fuumlgen Sie in der Datei bdquocontextxmlldquo folgende Angabe ein
lt--
Release Notes BALVI Schnittstellenserver Seite 8 von 37
ID fuumlr den Server
Diese muss pro Schnittstellenserver eindeutig sein
Eine Aumlnderung dieser ID fuumlhrt sofort dazu dass alle
eingerichteten Server-Jobs inaktiv werden und neu mit
der Instanz gekoppelt werden muumlssen um wieder aktiviert
werden zu koumlnnen
Als value kann ein Text der max Laumlnge von 32 Zeichen
vergeben werden z B ProductionEnvNode1 fuumlr die Produktion
und TestEnvNode1 fuumlr die Testumgebung
--gt
ltEnvironment
name=serverID
value=ProductionEnvNode1
type=javalangString
override=true
gt
152 Optional ist nun eine Namensvergabe moumlglich Auf Wunsch mehrerer Kunden wurde die Option geschaffen jedem Server zusaumltzlich einen kundenspezifischen bdquoTitelldquo zu geben um die Server besser unterscheiden zu koumlnnen
lt--
Visueller Name des Servers in der Oberflaumlche
(Optional)
--gt
ltEnvironment
name=serverName
value=TIERZ Tomcat 8 Java 8 mit BALVI_TIERZXGEWETLBTR_BSS
type=javalangString
override=true
gt
Der hier angegebene Text wird in der Kopfzeile zwischen den eckigen Klammern ausgegeben
Release Notes BALVI Schnittstellenserver Seite 9 von 37
2 Einrichtungshinweise
21 Allgemeine Hinweise zum Betrieb
211 Kompatibilitaumlt zu Apache Tomcat und Java SE Der BALVI Schnittstellenserver wurde getestet und freigegeben fuumlr Apache Tomcat 8 (ab Version 8030 oder neuer) Zudem wurde die aktuellste (letzte offizielle) Version von Java SE 8 getestet und kann verwendet werden (Java SE 8u40 und neuer)
Installieren Sie stets die aktuellsten Sicherheitsupdates fuumlr Java SE 8 Beachten Sie dabei jedoch dass nicht die Aktualisierung auf eine andere Java-Version (z B Java 9) gemeint ist
Freigegebene Major-Versionen werden explizit von BALVI benannt Falls Sie beabsichtigen die Major-Version zu aumlndern pruumlfen Sie bitte die aktuellen Release Notes oder kontaktieren die BALVI Kundenbetreuung
212 Oracle Java SE Lizenzierung Java SE beinhaltet auch kostenpflichtige Funktionen fuumlr deren Nutzung Oracle Lizenzgebuumlhren fordert wenn sie bei der Entwicklung eingesetzt werden Die von BALVI gelieferte Software ist frei von den kommerziellen Teilen der Oracle Java SE nutzbar Fuumlr den Einsatz von Oracle Java SE (einschlieszliglich JDK und JRE) fallen im Rahmen der Nutzung der BALVI Software keine Lizenzkosten an
Trotzdem werden wir parallel pruumlfen ob technische Probleme bei der Umstellung auf das OpenJDK zu erkennen sind Ein einfacher Funktionstest hat im BSS 3x noch keine technischen Probleme gezeigt als wir die Laufzeitumgebung auf das OpenJDK 8U111 AMD64 (Debian) umgestellt haben Bitte haben Sie Verstaumlndnis dafuumlr dass wir keine Funktionstests fuumlr jedes Linux-Derivat durchfuumlhren koumlnnen und dass es offiziell keine Version des OpenJDK fuumlr Windows Betriebssysteme gibt
213 Einsatz von TLSSSL BALVI hat keine spezifischen Anforderungen an die Konfiguration von SSL bzw TLS Der Einsatz von TLS 12 gem der Richtlinie TR-02102-2 vom BSI ist moumlglich wenn Sie sich an die von Apache Tomcat herausgegebene Dokumentation halten Es sind keine Anpassungen des Schnittstellenservers erforderlich Daher gehen wir davon aus dass auch der BSS 28x oder aumllter in einem Apache Tomcat mit TLS 12 betrieben werden kann
Das gilt jedoch nicht fuumlr alle Clients die den Tomcat-Server ansprechen moumlchten So ist z B erst ab BALVI mobil 191958 sichergestellt dass die Protokolle TLS 11 und TLS 12 programmseitig aktiviert sind Fuumlr Details zu diesem Problem wurde ein separates Rundschreiben per E-Mail versendet
Release Notes BALVI Schnittstellenserver Seite 10 von 37
214 Nutzung von Java-Proxyeinstellungen Der BALVI Schnittstellenserver verwendet fuumlr ausgehende Verbindungen die Java-Net Einstellungen welche in der Java-Dokumentation1 beschrieben sind Falls Sie Jobs einsetzen welche ausgehenden Zugriff auf Adressen im Internet benoumltigen kann es passieren dass Sie z B eine bdquojavanetUnknownHostExceptionldquo im Protokoll finden dann muumlssen Sie ihre Proxy-Umgebung in den Java-Umgebungseinstellungen ergaumlnzen
Die folgenden Parameter sollten daher in Ihrer Umgebung gesetzt werden wenn der Zugriff auf das Internet nur uumlber einen Proxy moumlglich ist
-DproxySet=true
-DproxyHost=10111213
-DproxyPort=8888
-DhttpnonProxyHosts=domainorg|localhost|10
Starten Sie nach Aumlnderung der Einstellungen den Server neu damit die Einstellungen wirksam werden
2141 Proxy-Einstellung unter Windows (Tomcat-Dienst)
Verwenden Sie das Dienste-Konfigurationsprogramm (z B tomcat7wexe) und ergaumlnzen Sie die fehlenden Einstellungen
2142 Proxy-Einstellung unter Linux
In Linux wird in der Konfigurationsdatei (z B conftomcat7conf) die Variable bdquo$JAVA_OPTSldquo entsprechend erweitert und die Werte uumlbergeben Beachten Sie dabei dass die Variablen von Linux (bzw der Bash) gelesen werden Daher muss das bdquoPipeldquo-Zeichen bdquo|ldquo mit bdquoldquo maskiert werden ansonsten erhalten Sie bei der Verarbeitung der Umgebungsvariable bdquohttpnonProxyHostsldquo Fehlermeldungen in der Linux -Konsole welche dazu fuumlhren dass Java nicht korrekt konfiguriert werden kann
JAVA_OPTS=$JAVA_OPTS -DproxySet=true -DproxyHost=10111213 -DproxyPort=8888
JAVA_OPTS=$JAVA_OPTS -DhttpnonProxyHosts=domainorg|localhost|10
1 httpdocsoraclecomjavase8docstechnotesguidesnetpropertieshtml
Release Notes BALVI Schnittstellenserver Seite 11 von 37
215 Spracheinstellung Deutsch Es wurde festgestellt dass unter einigen Linux-Versionen die Spracheinstellung beim Starten des Apache Tomcat nicht auf eine deutsche Umgebung verweist Dieses kann technische Probleme verursachen Unter Linux sollte die Einstellung (Umgebungsvariable) entsprechend auf LANG=de_DEUTF-8 eingestellt sein
216 Datenbankverbindung Wenn Sie eine Firewall zwischen dem Oracle-Server und dem Database Connection Pool (DBCP) verwenden sollte unbedingt die bdquovalidationQueryldquo in der DBCP-Konfiguration aktiviert werden damit die Anwendung schneller freie Connections aus dem Pool erhalten kann Die Dokumentation zu den Einstellmoumlglichkeiten ist in der beiliegenden Contextxml ergaumlnzt worden
Bitte beachten Sie dass dringende empfohlen wird die bdquoFactoryldquo auf orgapachetomcatjdbcpoolDataSourceFactory anzupassen falls sie noch auf bdquoorgapachecommonsdbcpBasicDataSourceFactoryldquo eingestellt ist
217 Probleme beim Anlegen von LOB-Objekten Der BALVI Schnittstellen-Server erfordert die JDBC-Spezifikation DBCP V4 welche durch die Factory bdquoorgapachetomcatjdbcldquo ab Tomcat 7 automatisch bereitgestellt wird
Wenn die Pooling-Komponente oder der Oracle-Treiber nicht JDBC4-Kompatibel sind gibt es beim Bearbeiten von LOB-Objekten in Java diverse Exceptions z B
Servletservice() for servlet soapws threw exception
javalangAbstractMethodError
orgapachecommonsdbcpPoolingDataSource$PoolGuardConnectionWrappercreateClob()LjavasqlClob
at debalvicoreauditspyConnectionSpycreateClob(ConnectionSpyjava511)
Ursache dieses Problems ist meistens dass noch nicht auf bdquoorgapachetomcatjdbcldquo umgestellt wurde
218 Umbenennung der gelieferten WAR-Datei Das im Paket von BALVI gelieferte WAR kann jederzeit umbenannt werden (z B als ROOTwar) ohne dass dabei spezielle Einstellungen in der Datei bdquocontextxmlldquo erforderlich sind
Beachten Sie dabei jedoch dass die zum WAR zugehoumlrige Datei bdquocontextxmlldquo im Apache Tomcat immer denselben Namen erhaumllt wie das WAR z B bdquocommserverwarldquo und bdquocommserverxmlldquo Der Name ist dabei ausschlaggebend fuumlr die Zugriffs-Adresse (Context) im Apache Tomcat selbst Die Benennung des WAR in bdquocommserverwarldquo wuumlrde folgendermaszligen aufzurufen sein httpserverportcommserver
219 Server-Schnittstellen Die Uumlberarbeitung bzw Erweiterung der Export- und Importschnittstellen welche uumlber den Schnittstellenserver bereitgestellt werden ist unabhaumlngig vom Schnittstellenserver selbst Die Schnittstellen sind daher nicht Bestandteile des Schnittstellenserver und werden je Verfahren separat
Release Notes BALVI Schnittstellenserver Seite 12 von 37
ausgeliefert Ggf ist es fuumlr unterschiedliche Schnittstellen erforderlich die Grant-Rechte zu aktualisieren (Vgl bdquoWann ist die Ausfuumlhrung des Grant-Skripts erforderlichldquo)
22 Kompatibilitaumltsliste Diverse Verfahren setzen eine Mindestversion des BALVI Schnittstellenservers voraus Die Schnittstellen sind jedoch so konzipiert dass eine Aktualisierung auf eine houmlhere Version des Servers ohne Anpassung an den vorhandenen Schnittstellen jederzeit moumlglich ist
Derzeit sind folgende Mindestanforderungen gegeben
1 BALVI mobil XT 170 oder houmlher setzt BSS 265 und BALVI iP 124x voraus
2 BALVI mobil XT 183 oder houmlher setzt BSS 281 und BALVI iP 124x voraus
3 BALVI mobil 2 (DM) setzt BSS 311 und BALVI iP 124x voraus
4 Die Schnittstelle eFI setzt BSS 251 und BALVI iP 122c voraus
5 Die Schnittstelle LIMS setzt BSS 265 voraus
6 Die Schnittstelle TSK (SN) setzt BSS 265 voraus
7 Die Schnittstelle xDomea (SN) setzt BSS 265 und Java 7 voraus
8 Die Schnittstelle XGewerbeanzeigen 11 setzt BSS 281 BALVI iP 124x Java 8 mit der bdquoJava
Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy2ldquo voraus
9 Die Schnittstelle XGewerbeanzeigen 12 (ab Paket 7 Ausbaustufe 3) setzt BSS 302 BALVI iP
124x Java 8 mit der bdquoJava Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policyldquo
voraus
10 Die Schnittstelle RioPP LM (NRW) setzt BSS 303 und die ETL-Konfiguration voraus
11 Die Schnittstellen zu BALVI iP2 (Fachmodule BTS LM ZDA Stand Juni 2017) setzen BSS 32x
voraus
2 httpwwworaclecomtechnetworkjavajavasedownloadsjce8-download-2133166html
Release Notes BALVI Schnittstellenserver Seite 13 von 37
23 Erforderliche Bibliotheken fuumlr Apache Tomcat Dateiname Funktion Quelle ojdbc6jar Oracle 11gR2 Clientpaket Oracle JDBC Client fuumlr Java
16 ersetzt die bisherige Version bdquoojdbc14jarldquo Die alte Library muss auf jeden Fall entfernt werden
httpwwworaclecomtechnetworkdatabaseenterprise-editionjdbc-112010-090769html
encrypted-datasource-110-alljar
Die Library muss auf jeden Fall entfernt werden Wird derzeit nicht weiter gepflegt da kein Interesse an der Funktionalitaumlt bestand
slf4j-api-1511jar slf4j-log4j12-1511jar log4jdbc4-12beta2jar
Entfaumlllt nicht mehr erforderlich Es wird empfohlen diese zu entfernen falls diese im LIB-Verzeichnis vorhanden sein sollten
commons-dbcp-14jar commons-pool-154jar
Entfaumlllt nicht mehr erforderlich Es wird empfohlen diese zu entfernen falls diese im LIB-Verzeichnis vorhanden sein sollten
Erwartet wird stattdessen ab Tomcat7 die mitgelieferte bdquotomcat-jdbcjarldquo
log4j-1217jar (oder houmlher)
Logging-Funktionalitaumlt Apache Log4j httploggingapacheorglog4j12downloadhtml
bcprov-jdk15on-157jar (oder houmlher)
BouncyCastle Security Provider fuumlr SSLAES hellip wird ab Version 27 im Ordner bdquolibldquo des Tomcat erwartet Sollte es aus Sicherheitsgruumlnden erwuumlnscht sein eine aktuellere Version einzusetzen ist dieses idR moumlglich
httpmvnrepositorycomartifactorgbouncycastlebcprov-jdk15on157
24 Datenbank-Installation Der BALVI Schnittstellenserver benoumltigt auszligerhalb des angebundenen BALVI iP keine eigenen Tabellen Die Web-Anwendung kann im einfachsten Fall direkt auf das Schema von BALVI iP zugreifen indem der Benutzer und das Passwort des BALVI iP-Schemas in der Datei bdquocontextxmlldquo eingetragen werden (nicht empfohlen)
Sollte dies aus Sicherheitsgruumlnden nicht erwuumlnscht sein (empfohlen vom BSI und von BALVI) finden Sie im Paket ein GRANT-Skript um Zugriffsrechte vom BALVI iP Schema fuumlr den Webservice-Schema-Benutzer einzurichten
Zwischen dem Schema von BALVI iP und jeder Web-Anwendung ist dann eine Trennung moumlglich um sicherzustellen dass der Datenbank-Benutzer welcher in der Tomcat-Konfiguration fuumlr die Web-Anwendung eingetragen wird geaumlndert oder geloumlscht werden kann ohne dass die Windows-Anwendung BALVI iP davon betroffen ist Zudem vergibt das von BALVI gelieferte Grant-Skript keine Rechte zum Loumlschen von Tabellenstrukturen oder Tabelleninhalten so dass der Webservice nur festgelegte Daten aumlndern oder lesen darf Es wird empfohlen je Web-Anwendung einen eigenen Datenbank-Benutzer zu vergeben wenn Sie ein BALVI iP mit mehreren Webservices verbinden wollen
Die Moumlglichkeiten im Uumlberblick
1) Sie betreiben den Webservice mit einem eigenstaumlndigen Oracle-Benutzer In diesem Fall muss das
Grant-Skript ausgefuumlhrt werden um den Webservice-Benutzer und den BALVI iP-Benutzer
miteinander zu koppeln
2) In der Tomcat-Konfiguration wird der Oracle-Benutzer eingetragen welcher auch der BALVI iP
Schemabesitzer ist und in der bdquobalviip_conninildquo hinterlegt ist (NICHT Empfohlen) Der Webservice
Release Notes BALVI Schnittstellenserver Seite 14 von 37
hat 100 Zugriffsrechte (auch Loumlsch- oder Aumlnderungsrechte am Schema) es wird kein Grant-
Skript benoumltigt
Wenn Sie die Konfiguration 2) waumlhlen moumlchten koumlnnen Sie die folgenden Unterkapitel uumlberspringen und in Kapitel 0 bzw fortsetzen
241 Erstinstallation Datenbank-Benutzer anlegen Wenn Sie den Webservice-Benutzer vom BALVI iP Schema trennen moumlchten muss durch die DB-Administration in der Oracle-Server-Instanz wo auch BALVI iP sein Schema besitzt ein Benutzer (ggf je Web-Anwendung) angelegt werden welcher folgende Rechte benoumltigt
CONNECT
ALTER SESSION
CREATE JOB
CREATE PROCEDURE
CREATE SESSION
CREATE TABLE
CREATE TRIGGER
CREATE TYPE
CREATE VIEW
CREATE SEQUENCE
CREATE SYNONYM
QUERY REWRITE
Der Default-Tablespace ist frei waumlhlbar Der Benutzer braucht das Recht QUOTA UNLIMITED auf den Tablespace von BALVI iP (Default BALVI_IP) Ein Beispiel-Create-Skript bdquooraCreate_WEB_Usersqlldquo liegt der Auslieferung bei
242 Rechte zuweisen Wenn der BALVI iP Schemabesitzer NICHT in der Tomcat-Umgebung eingetragen werden soll muss ein Oracle DBA das beiliegende GRANT-Skript bdquooraGrantIP_to_Websqlldquo ausfuumlhren um dem jeweiligen Webservice (in Tomcat verwendeten Oracle-Benutzer) die minimalen Rechte auf das Schema von BALVI iP zu gewaumlhren
Dieses Skript setzt voraus dass es von einem Oracle Administrator als bdquoUser SYSTEMldquo ausgefuumlhrt wird Lesen Sie die im Skript enthaltenen README-Kommentare und passen Sie die Benutzer (BALVI iP Schema) und (WEB-Schema) an
====================================================
DEKLARATIVER TEIL MUSS vom KUNDEN geaumlndert
bzw auf die korrekten SCHEMA-Namen angepasst
werden
Die USER-Namen muumlssen in Groszligbuchstaben
geschrieben sein sonst werden sie nicht
gefunden
====================================================
sUserBALVI_IP = BALVI_IP_SCHEMABESITZER
sUserBALVI_WEB = BALVI_WEB_SCHEMABESITZER
Release Notes BALVI Schnittstellenserver Seite 15 von 37
Neu ab Grant-Skript 158 ist die Umbenennung der Verfahrenszuordnung
Pruumlfen Sie dass die Einstellung fuumlr Ihr BundeslandVerfahren korrekt ist dort muss eine 1 fuumlr min ein Verfahren gesetzt sein Diese Einstellung befindet sich direkt unter den Schemabesitzer-Angaben
-- Verfahrensbezogene Konfiguration
-- Setzen Sie fuumlr das jeweilige Verfahren eine 1
-- BALVI Schnittstellenserver (BSS)
-- bis V266 auch BALVI Kommunikationsserver (BKS) genannt
-- generell fuumlr die meisten Verfahren guumlltig
-- Ab Version 57 entfaumlllt mit der Einfuumlhrung der
-- Schnittstelle XGewerbeanzeigen auch der separate Schalter
-- WS_BTR beide Verfahren wurden vereinheitlicht
WS_BSS = 1
Fuumlhren Sie das Skript nach der Anpassung als User SYSTEM aus um die Grants durchzufuumlhren Dieses wurde mit dem von ORACLE gelieferten Programm SQLPLUS (Command-Line) SQLPLUS Worksheet (GUI) und Oracle SQL-Developer getestet
Das Skript generiert fuumlr jedes Objekt ein SYNONYM fuumlr den WEB-USER so dass dieser auf die Objekte ohne Angabe des Owners des IP-Schemas zugreifen kann Pruumlfen Sie nach der Ausfuumlhrung dass die SYNONYMS vorhanden und VALID sind dieses kann ggf nicht der Fall sein Das Skript kann jederzeit erneut ausgefuumlhrt werden um die Grants neu zu erzeugen und bietet ebenfalls die Option alle Grants und Synonyme wieder zu entfernen Detaillierte Informationen zur Nutzung des Skripts sind als Kommentar-Block im Skript enthalten
Hinweis Die Versionsinformation ist unter den Kommentaren direkt im Skript zu finden
Zugriffsberechtigungen fuumlr Webanwendungen auf BALVI iP anlegen
===============================================================
Version 158
Guumlltig fuumlr BALVI iP 123 oder houmlher
Autor Frank Holler
SVN Revisionsinformationen
$Revision 479 $
$Date 2016-02-15 152755 +0100 (Mo 15 Feb 2016) $
================================================================
243 Wann ist die Ausfuumlhrung des Grant-Skripts erforderlich Durch das Strukturupdate von BALVI iP (z B 1240 auf 1241) werden veraltete Strukturen geloumlscht und ggf neue Views oder Tabellen angelegt Die Grant-Rechte geht dabei ggf verloren Daher ist die Ausfuumlhrung des Grant-Skripts immer dann erforderlich wenn sich die Datenbank-Struktur von BALVI iP veraumlndert
Zudem kann es fachliche Neuerungen geben welche im alten Grant-Skript nicht vorhanden sind Daher muss das Skript ggf auch ausgefuumlhrt werden wenn eine neue Schnittstelle im Schnittstellenserver bereitgestellt wurde Dieses betrifft z B auch die Bereitstellung von neuen Versionen von BALVI mobil XT
Release Notes BALVI Schnittstellenserver Seite 16 von 37
da auch dort mit einem fachlich erweiterten Client die Moumlglichkeit besteht dass neue Schnittstellen bereitgestellt und somit mehr Schreibrechte auf Tabellen benoumltigt werden
244 Welche Version des Grant-Skripts soll ich nehmen Wie der Schnittstellenserver sind auch die Grant-Skripte versioniert Neuere Versionen des Grant-Skriptes sind abwaumlrts-kompatibel und koumlnnen immer verwendet werden auch wenn in einer Schnittstellenbeschreibung eine aumlltere Version des Grant-Skriptes explizit benannt wurde
245 Kombination von mehreren Verfahren Wenn Sie zwei oder mehr Schnittstellen im BSS verwenden moumlchten ist es ggf erforderlich auch mehrere Verfahren auf aktiv (bdquo1ldquo) zu setzen
Im Beispiel nehmen wir an Sie moumlchten bdquoeFildquo und bdquoBALVI mobil XTldquo im Schnittstellenserver bereitstellen In der Beschreibung von bdquoeFildquo steht dass das Grant-Skript V36 erforderlich ist BALVI mobil XT 18 erfordert jedoch schon V56
Wenn Sie beide Verfahren betreiben ist im Grant-Skript (V56 oder houmlher) die Einstellung fuumlr beide Verfahren zu aktivieren
====================================================
DEKLARATIVER TEIL MUSS vom KUNDEN geaumlndert
bzw auf die korrekten SCHEMA-Namen angepasst
werden
Die USER-Namen muumlssen in Groszligbuchstaben
geschrieben sein sonst werden sie nicht
gefunden
====================================================
sUserBALVI_IP = BALVI_IP_SCHEMA
sUserBALVI_WEB = WEBAPP_SCHEMA
-- Verfahrensbezogene Konfiguration
-- Setzen Sie fuumlr das jeweilige Verfahren eine 1
-- BALVI Schnittstellenserver (BSS)
-- bis V266 auch BALVI Kommunikationsserver (BKS) genannt
-- generell fuumlr die meisten Verfahren guumlltig
-- Ab Version 57 entfaumlllt mit der Einfuumlhrung der
-- Schnittstelle XGewerbeanzeigen auch der separate Schalter
-- WS_BTR beide Verfahren wurden vereinheitlicht
WS_BSS = 1
-- WebService BTR (Betriebsstaumlttenregister) (NRW TH)
-- entfernt mit Update V57 setzen Sie stattdessen bei WS_BSS = 1
--WS_BTR = 0
-- Probenahme Futtermittel im Browser(BY)
WS_PROBE_FM = 0
-- Risikoorientierte Probenplanung Futtermittel ndash RIOPP FM (BY)
WS_RIOPP_FM = 0
-- Verfahren Export an EFi (Status Pilotbetrieb)
WS_EFI = 1
-- neu ab Version 35 des Grant-Skriptes ist die Moumlglichkeit den Webuser
Release Notes BALVI Schnittstellenserver Seite 17 von 37
-- fuumlr das Loumlschen der Ausgangskoumlrbe explizit zu berechtigen bzw sogar einen
-- expliziten abweichenden User festzulegen Die Konfiguration in der
-- Job-Oberflaumlche sieht vor dass man die Oracle-Datenbank-Zugangsdaten fuumlr
-- das Loumlschen einstellen muss Hier muss im Normalfall derselbe Oracle
-- Datenbankbenutzer eingetragen werden wie in der Tomcat-Verbindungs-
-- konfiguration In diesem Fall sollte wenn WS_EFI = 1 eingestellt wurde
-- ebenfalls WS_EFI_DELETE = 1 eingestellt werden
-- Alternativen
-- 1) Datenbankbenutzer aumlndern
-- Wenn bei sUserEFI_TRUNC anstatt sUserBALVI_WEB (Standard) ein anderer
-- Oracle-Benutzername angegeben wird wird das Loumlschrecht fuumlr die EFi
-- Ausgangskoumlrbe Datenbankseitig exklusiv dem angegeben Datenbankbenutzer
-- zugewiesen
-- 2) Loumlschrecht verweigern
-- Setzen Sie die Variablen WS_EFI_DELETE = 0 damit kein Loumlschrecht
-- zugeweisen wird
WS_EFI_DELETE = 0
-- Beispiel Anderer Benutzer muss in der Datenbank existieren
-- Entfernen Sie die fuumlhrenden -- vor der Variable sUserEFI_TRUNC und
-- setzen den entsprechenden Oracle-Benutzer ein
--sUserEFI_TRUNC = TEST_EFI_TRUNC
hellip
25 Konfiguration des Schnittstellen-Servers
251 Die bdquocontextxmlldquo-Parameter Die von der Servlet-Spezifikation vorgegeben Rump-Struktur sieht folgendermaszligen aus
ltxml version=10 encoding=utf-8gt
ltDOCTYPE Contextgt
ltContextgt
lt-- Kundenspezifische Einstellungen --gt
ltContextgt
Anwendungsspezifische Einstellungen werden zwischen ltContextgt und ltContextgt eingefuumlgt Alle allgemeinguumlltigen Einstellungen in der Datei bdquocontextxmlldquo werden hier erlaumlutert Kommentare finden sich auch in der von BALVI ausgelieferten Beispiel-Konfiguration
Neben den im Folgenden beschriebenen Standard-Einstellungen kann es auch vorkommen dass bundeslandspezifische Erweiterungen vorhanden sind welche nicht in dieser Dokumentation aufgefuumlhrt werden Diese funktionieren trotzdem regulaumlr weiter wenn keine expliziten Informationen zu Kompatibilitaumltsproblemen in den Release-Notes aufgefuumlhrt wurden
2511 Datenbankverbindung jdbcDataSource
Die Datenbankverbindung wird uumlber die von DBCP und dem Oracle-Treiber vorgegebenen Moumlglichkeiten realisiert Der Einsatz der orgapachetomcatjdbcpoolDataSourceFactory (automatisch verfuumlgbar ab Apache Tomcat 7 in der mitgelieferten tomcat-dbcpjar) wird als Beispiel-Konfiguration ausgeliefert
ltResource
name=jdbcDataSource
auth=Container
Release Notes BALVI Schnittstellenserver Seite 18 von 37
type=javaxsqlDataSource
factory=orgapachetomcatjdbcpoolDataSourceFactory
maxActive=10 initialSize=3
maxIdle=5
maxWait=10000
url=jdbcoraclethinBL2-ORA10-KUNDENBALVIINTERN1521ORCL
driverClassName=oraclejdbcdriverOracleDriver
username=balvi_webservice_schema
password=balvi_webservice_password
description=Oracle Datasource
maxOpenPreparedStatements=50
removeAbandoned=false
removeAbandonedTimeout=100
logAbandoned=true
jdbcInterceptors=hellip
gt
Hinweise zur Einstellung der jdbcDataSource
Standard-Einstellungen fuumlr den Datenbank-Verbindungspool
Der Verbindungspool muss entsprechend der Anzahl der zu erwartenden gleichzeitigen Benutzer konfiguriert werden Wenn Sie erwarten dass 50 Anwender gleichzeitig arbeiten stellen Sie bitte folgende Werte ein
maxActive=(50 + 10 (fuumlr System und Jobs)) = 60
maxIdle= (50 10) = 5
1 maxActive - maximale Anzahl der gleichzeitigen aktiven Anfragen an die DB
Wenn der Werte maxActive erreicht ist z B wenn mehrere Benutzer gleichzeitig einen Export starten moumlchten welcher laumlngere Zeit in Anspruch nimmt dann kann der Server die Anfrage nicht mehr bedienen und der Anwender wird abgewiesen maxActive hat zudem Auswirkungen auf die im Hintergrund ausgefuumlhrten Jobs maxActive wird daher kalkuliert mit der Anzahl der Anwender und moumlglicher Datenbank-Connections fuumlr Hintergrund-Jobs Jeder aktiv ausgefuumlhrte Job benoumltigt mindestens eine Connection nur selten wird aus Performance-Gruumlnden mehr als eine Connection waumlhrend der Job-Ausfuumlhrung verwendet Im Normalfall sollten daher 10 Connections fuumlr Hintergrundprozesse ausreichend sein
2 maxIdle - Anzahl der offenen Verbindungen auch wenn der Server im Leerlauf ist
Jede offene Verbindung im Leerlauf haumllt auf dem Datenbankserver eine Session offen Auch diese erfordert Ressourcen Wenn die Verbindungen jedoch geschlossen werden kann die Anfragezeit fuumlr eine neue Verbindung steigen da diese Verbindung erst neu ausgehandelt werden muss Die Empfehlung fuumlr den Wert bdquomaxIdleldquo ist ca 10 der Einstellung von maxActive
KeepAlive-Einstellungen fuumlr den Pool
1 validationQuery
Diese wird ausgefuumlhrt um die Verbindung zu DB zu validieren Es MUSS ein Datensatz zuruumlckgegeben werden ansonsten nimmt der DBCP an dass die Abfrage nicht erfolgreich abgesetzt wurde Achten Sie also bitte darauf dass die Abfrage nicht zu leitungsintensiv ist und genau einen Datensatz liefert
Release Notes BALVI Schnittstellenserver Seite 19 von 37
Oracle bietet dafuumlr die virtuelle Tabelle DUAL an welche sich fuumlr die ValidationQuery sehr gut eignet da die Abfrage kaum Ressourcen verbraucht
validationQuery=select 1 from dual
2 testOnBorrow - Boolscher Wert true oder false
Diese Einstellung sorgt dafuumlr dass der Pool die Verfuumlgbarkeit anhand der validationQuery pruumlft bevor
die DB-Verbindung an die Anwendung ausgeliehen wird Empfehlung
testOnBorrow=true
3 testWhileIdle - Boolscher Wert true oder false
Diese Einstellung ist hilfreich wenn zwischen dem Tomcat und der DB eine Firewall mit Stateful
Packet Inspection verwendet wird Nach laumlngerer Inaktivitaumlt wird normalerweise durch die Firewall die
DB-Verbindung geschlossen Dieses loumlst dann beim Ausleihen der Verbindung eine Fehlermeldung im
Protokoll aus 2012-08-16 165418720 WARN [http-0000-8080-8]
[orgspringframeworkjdbcsupportSQLErrorCodesFactory] Error while extracting
database product name - falling back to empty error codes
orgspringframeworkjdbcsupportMetaDataAccessException Error while extracting
DatabaseMetaData nested exception is javasqlSQLRecoverableException Getrennte
Verbindung Um dieses Problem zu beheben sollte die Option testWhileIdle=true eingestellt werden
testWhileIdle=true
Damit diese weiszlig wie oft eine Pruumlfung durchgefuumlhrt werden muss sind jedoch noch zusaumltzliche Angaben erforderlich welche fuumlr die Einstellung der Zeit zusaumltzlich gesetzt werden muumlssen
a) minEvictableIdleTimeMillis - Long in Millisekunden
Min Zeit wie lange eine DB-Verbindung im Leerlauf ist bevor diese zur Pruumlfung
gekennzeichnet wird Dieses haumlngt stark von der Einstellung der Firewall ab Wenn Sie eine
sehr restriktive Firewall haben kann es sein dass diese die Verbindung nach wenigen
Minuten Leerlauf trennt Stellen Sie den Wert immer so ein dass dieser unter der Leerlaufzeit
der Firewall liegt empfohlen 300000 entspricht 300 Sek = 5 min
minEvictableIdleTimeMillis=300000
b) timeBetweenEvictionRunsMillis - Long in Millisekunden
Der Pruumlflauf startet in der Default-Konfiguration alle 1800000 Millisekunden = 30 Min n als
zu Pruumlfen markierte Verbindungen werden in einem Pruumlflauf getestet n wird bestimmt durch
die Einstellung numTestsPerEvictionRun Empfehlung Stellen Sie den Wert auf alle 15 Min
ein
timeBetweenEvictionRunsMillis=900000
Release Notes BALVI Schnittstellenserver Seite 20 von 37
c) numTestsPerEvictionRun - Integer
Wie viele Verbindungen sollen getestet werden waumlhrend der Pruumlflauf ausgefuumlhrt wird Im
Normalfall sollte die Anzahl der zu testenden Verbindungen nicht zu hoch eingestellt werden
Der Default ist 3 Wenn Sie houmlhere Sicherheit haben wollen dass keine bdquototenldquo
Datenbankverbindungen bestehen bleiben erhoumlhen Sie den Wert auf max bdquo(maxActive ndash
maxIdle) 2ldquo Wenn Ihnen 3 ausreichend erscheint muss der Wert nicht gesetzt sein dann
wird der Default verwendet
Beispiel numTestsPerEvictionRun=10
4 Interceptors konfigurieren Neu ergaumlnzt wurde die Moumlglichkeit spezielle bdquoInterceptorsldquo zu konfigurieren die ermoumlglichen das Verhalten des Pools zu steuern Wichtig hierbei ist dass die Angabe von Werten auf real existierende Java-Klassen erfolgt die im Classpath des Tomcat vorhanden sind Groszlig-und-Kleinschreibung ist zu beachten Folgende Default-Einstellung hat BALVI fuumlr den BSS festgelegt jdbcInterceptors=
orgapachetomcatjdbcpoolinterceptorConnectionState
orgapachetomcatjdbcpoolinterceptorStatementFinalizer
orgapachetomcatjdbcpoolinterceptorResetAbandonedTimer
Details zu den verwendeten Interceptor-Einstellungen finden Sie in der Tomcat-Dokumentation3
3 httptomcatapacheorgtomcat-80-docjdbc-poolhtmlJDBC_interceptors
Release Notes BALVI Schnittstellenserver Seite 21 von 37
2512 Datenbank-Zugangsdaten verschluumlsseln
Die Verschluumlsselung fuumlr die Datenbank-Verbindung (bdquoEncrypted Datasourceldquo) ist eine Ableitung der Bibliothek Apache-Common-DBCP-14 und daher nicht mehr mit Java 8 kompatibel Die Einrichtung der Verschluumlsselung wird daher mit der Auslieferung des BSS 30 nicht mehr angeboten
2513 Active-Directory-Authentifizierung
Uumlber die folgenden Parameter wird der Zugriff des Schnittstellen-Servers auf einen Microsoft Active Directory Domain-Controller konfiguriert
ldquoldapServerAddressrdquo
Syntax PROTOKOLLIP-Adresse oder DNS-NamePORT
ltEnvironment
name=ldapServerAddress
value=ldapbl2-dc02balviintern389
type=javalangString
override=true
gt
Als Protokoll besteht auch die Moumlglichkeit ldaps (LDAP+SSL) wenn der Domain-Controller entsprechend konfiguriert wurde Im Java Truststore muss dann das Zertifikat der CA vorhanden sein welche das Zertifikat des Domain-Controllers signiert hat Zudem darf bei ldaps keine IP-Adresse verwendet werden es muss der DNS-Name des Server-Zertifikats eingetragen sein Ansonsten gibt es beim Verbinden eine Sicherheits-Exception
lt-- SSL-Beispiel
ltEnvironment
name=ldapServerAddress
value=ldapsbl2-dc02balviintern636
type=javalangString
override=true
gt
--gt
bdquoldapBaseDnrdquo
LDAP-Suchpfad fuumlr die Domain-Basis Diese muss der LDAP-Syntax fuumlr den Domain-Suffix entsprechen
Syntax DC=SERVERDC=ROOTDN
ltEnvironment
name=ldapBaseDn
value=DC=BALVIDC=INTERN
type=javalangString
override=true
gt
Release Notes BALVI Schnittstellenserver Seite 22 von 37
bdquowebLoginUseActiveDirectoryAuthenticationrdquo
Die Authentifizierung in der Browser-Oberflaumlche kann uumlber die Active-Directory-Authentifizierung erfolgen In der ersten Version ist nur die Protokoll-Auswertung moumlglich wenn der ADMIN sich anmeldet Dieser hat normalerweise niemals AD-Kennungen zugeordnet BALVI empfiehlt diese Einstellung auf bdquofalseldquo zu belassen Webservices welche uumlber SOAPREST zugreifen koumlnnen die Active-Directory-Authentifizierung trotzdem verwenden
ltEnvironment
name=webLoginUseActiveDirectoryAuthentication
value=false
type=javalangBoolean
override=true
gt
ldquoldapDaysBeforeExpirationNotificationrdquo
Die Passwort-Aumlnderung im Active-Directory uumlber die Browser-Oberflaumlche ist in der ersten Version noch nicht implementiert der Parameter wird bislang nicht ausgewertet
ltEnvironment
name=ldapDaysBeforeExpirationNotification
value=14
type=javalangInteger
override=true
gt
2514 Statement-Protokollierung in BALVI iP
Diese Option aktiviert die Lese- und Aumlnderungsprotokollierung fuumlr BALVI iP Standard ist bdquofalseldquo und wird fuumlr alle Kunden empfohlen solange keine speziellen Datenbank-Jobs eingerichtet wurden welche zeitgesteuert die Protokolleintraumlge wieder loumlschen Fuumlr Bayern wurde ein spezielles Konzept zur Leseprotokollierung entworfen Wenn Sie mehr daruumlber erfahren moumlchten kontaktieren Sie bitte die BALVI GmbH
ltEnvironment
name=enableSqlStatementMonitoring
value=true
type=javalangBoolean
override=true
gt
Beachten Sie dass diese Option massive INSERT-Statements in BALVI iP in die Tabelle VIS_D92 ausfuumlhrt Jedes abgesetzte SQL-Statement wird dabei vollstaumlndig protokolliert Dieses erzeugt eine sehr hohe INSERT-Last und in der Folge auch erhoumlhte Redolog-Switches und COMMIT-Transaktionen
Optional Aktivieren der INSERT + APPEND - Logik
Beachten Sie bitte die Hinweise von Oracle zum Hint + APPEND
Release Notes BALVI Schnittstellenserver Seite 23 von 37
Wenn Sie dieses Verhalten aktivieren moumlchten ergaumlnzen Sie bitte den folgenden Environment-Parameter
ltEnvironment
name=statementMonitoringactivateAppendMode
value=true
type=javalangBoolean
override=true
gt
2515 Einstellungen fuumlr BALVI mobil XT (bzw den bdquopartitionedExportldquo)
Diese Logik des FIFO-Buffers wurde so konzipiert dass dem Rechenzentrum diverse Einstellmoumlglichkeiten uumlber die Datei bdquocontextxmlldquo zur Verfuumlgung stehen um die Steuerung des FIFO-Puffers zu beeinflussen
Schematische Darstellung des FIFO-Puffers
Das ermoumlglicht es z B dem BALVI mobil XT Client (14 oder houmlher) den aktiven Block abzuholen und dies beim Fehler bis zu 10-mal zu wiederholen Sobald der Block [001] erfolgreich beim Client angekommen ist und dieser den naumlchsten Block anfragt wird der Block [001] verworfen wird Der Server fuumlllt dann im Hintergrund den frei gewordenen Block wieder waumlhrend der Client den Block [002] abholt
Die Groumlszlige und Anzahl der vorgecachten Bloumlcke kann uumlber die folgenden Einstellungen in der Datei bdquocontextxmlldquo definiert werden
ltEnvironment
name=partitionedExportmaxBufferedPartitions
value=3 type=javalangInteger override=true
gt
ltEnvironment
name=partitionedExportpartitionSize
value=256000 type=javalangInteger override=true
gt
Die Einstellung partitionedExportmaxBufferedPartitions ist dabei die Anzahl der vorgecachten Bloumlcke mindestens muss 2 angegeben werden Der Puffercache wird ausschlieszliglich im RAM der JVM aufgebaut es wird folglich mehr Arbeitsspeicher verwendet Dieser Arbeitsspeicher muss je gleichzeitiger Session auf dem Server bereitgestellt werden die Default-Einstellung mit 3 Partitionen a 256 KB + dem aktiven Puffer erfordern 1 MB RAM je aktiven Anwender
Aktiv
er
Puffe
r
[001] Vorg
ecac
hter
Bl
ock
[002] Vorg
ecac
hter
Bl
ock
[003]
Aktiv
er P
uffe
r
[002] Vorg
ecac
hter
Bl
ock
[003] Vorg
ecac
hter
Bl
ock
[leer]
Release Notes BALVI Schnittstellenserver Seite 24 von 37
Gleichzeitig wurde die Moumlglichkeit geschaffen dass die maximale Anzahl an gleichzeitigen Exporten durch das Rechenzentrum eingeschraumlnkt werden kann um einem OutOfMemory-Fehler vorzubeugen Die Einstellung
ltEnvironment
name=partitionedExportmaxConcurrentExports
value=10 type=javalangInteger override=true
gt
muss entsprechend der zu erwartenden gleichzeitigen Zugriffe konzipiert werden ansonsten wird der Server einen Verbindungsversuch durch die Clients ablehnen
Beachten Sie dass die folgenden Einstellungen partitionedExportmaxBufferedPartitions partitionedExportmaxConcurrentExports und partitionedExportpartitionSize gemeinsam als Rechenbasis fuumlr den RAM-Bedarf des Webservers herangezogen werden muumlssen
Folgende Faustformel sollte fuumlr die Einrichtung verwendet werden
Min 256 MB (Serverbasis) + (11 partitionedExportmaxConcurrentExports partitionedExportmaxBufferedPartitions partitionedExportpartitionSize)
Beispiel 50 gleichzeitige Anwender Blockgroumlszlige 256 KB 4 Partitionen
256 MB + (11 50 256 4) KB = 312 MB fuumlr die JVM
Empf 512 MB (Serverbasis) + (12 partitionedExportmaxConcurrentExports partitionedExportmaxBufferedPartitions partitionedExportpartitionSize)
Beispiel 50 gleichzeitige Anwender Blockgroumlszlige 256 KB 4 Partitionen
512 MB + (12 50 256 4) KB = 572 MB fuumlr die JVM
partitionedExportmaxConcurrentExports
Bestimmt die Anzahl der maximalen Export Tasks (Threads) die fuumlr partitionierte Exporte bereitgestellt werden Wenn die Anzahl uumlberschritten wird wird die entsprechende Exportanfrage abgewiesen und der Client muss zu einem spaumlteren Zeitpunkt erneut anfragen Stellen Sie diesen Wert entsprechend der zu erwartenden Benutzeranzahl ein bei 50 Anwendern also 50
Exporte oumlffnen auf der Datenbank entsprechend zur Ausfuumlhrungszeit min einen Cursor ggf fuumlr rekursive Unterabfragen kurzfristig sogar mehr Die hier eingestellte Anzahl muss mit der Anzahl von maxActive korrelieren
ltEnvironment
name=partitionedExportmaxConcurrentExports
value=10 type=javalangInteger override=true
gt
partitionedExportmaxBufferedPartitions
Bestimmt die Anzahl der Datenbloumlcke (Partitionen) die vom Server bei Abruf eines Exportes gepuffert werden Die seit Version 24 eingefuumlhrte FIFO-Puffer-Logik ermoumlglicht dass der Server schon die Ergebnisse vorpuffert so dass der Client weniger Wartezeiten bei der Anfrage nach Daten hat Diese
Release Notes BALVI Schnittstellenserver Seite 25 von 37
Puffer-Logik unterteilt den Exportdatenstrom (je Export) in mehre Bloumlcke Der Client kann nun den letzten Block neu anfordern oder den naumlchsten Block wenn der letzte Block erfolgreich verarbeitet wurde Wie viele naumlchste Bloumlcke durch den Server bereit gestellt werden entscheidet diese Einstellung Sobald kein naumlchster Block mehr bereit gestellt werden muss wird der Datenbank-Cursor geschlossen eine Erhoumlhung kann also zu einer Entlastung der aktiven DB-Verbindungen fuumlhren erhoumlht jedoch den Bedarf an RAM des Servers
Der von BALVI voreingestellte Wert ist 3
ltEnvironment
name=partitionedExportmaxBufferedPartitions
value=3 type=javalangInteger override=true
gt
partitionedExportpartitionSizeldquo
Die Groumlszlige der Datenbloumlcke (Partitionen) die an den Client uumlbermittelt werden in Bytes Wenn Sie diesen Wert zu niedrig einstellen reduziert sich die Effizienz des Caches da der Client mehr Datenbloumlcke hintereinander abrufen muss Waumlhlen Sie einen zu groszligen Wert wird die neu zu uumlbertragende Datenmenge im Fall eines Fehlers houmlher
Der von BALVI voreingestellte Wert ist 256000 (256 KB)
ltEnvironment
name=partitionedExportpartitionSize
value=256000 type=javalangInteger override=true
gt
exportTokensmaxTokenCount
Maximale Anzahl der gleichzeitig vergebenen Token die vom Server gecached werden Jede Sitzung welche einen Export durchfuumlhrt erhaumllt einen Session-Token
Wenn eine Sitzung laumlngere Zeit nicht verwendet wurde wird dieser Session-Token wieder entfernt Wenn Sie den Wert zu niedrig einstellen fuumlhrt das zu einer generellen Session-Begrenzung auch fuumlr den nicht partitionierten Export-Modus welcher ab Version 21 verfuumlgbar ist
Ist die Anzahl der Tokens houmlher als die Datenbankeinstellung maxActive kann es vorkommen dass zwar eine Session gestartet werden kann jedoch kein Datenexport zustande kommt
Der von BALVI voreingestellte Wert ist 2000
ltEnvironment
name=exportTokensmaxTokenCount
value=20 type=javalangInteger override=true
gt
exportTokenstokenExpirationInSeconds
Zeit in Sekunden die verstreichen muss bis ein Token unguumlltig wird falls darauf kein Zugriff mehr erfolgt Nach einem erfolgreichen Export wird der Token automatisch geschlossen diese Option ist fuumlr den Abbruchfall vorgesehen Der von BALVI voreingestellte Wert ist 180 (180 s = 3 min)
Release Notes BALVI Schnittstellenserver Seite 26 von 37
ltEnvironment
name=exportTokenstokenExpirationInSeconds
value=180 type=javalangInteger override=true
gt
exportTokenstokenDisposalInSeconds
Zeit in Sekunden die verstreichen muss bis ein Token das erfolgreich abgearbeitet wurde aus dem Cache geloumlscht wird Um sicher zu stellen dass der letzte Exportblock noch erfolgreich abgerufen werden kann bleibt der Token auch nach Fertigmeldung des Clients noch N Sek guumlltig
Der von BALVI voreingestellte Wert ist 60 (60 s = 1 min)
ltEnvironment
name=exportTokenstokenDisposalInSeconds
value=60 type=javalangInteger override=true
gt
2516 Job-Verwaltung fuumlr den BSS konfigurieren Aktivierung der Jobverwaltung
Bis zur Version 28 des BSS gab es den Parameter bdquoavailableServicesldquo Dieser konnte bei Bedarf aktiviert werden wenn die Jobs benoumltigt wurden
Mit Version 30 ist die Einstellung bdquoavailableServicesldquo zu entfernen und kann durch den neuen optionalen Parameter bdquoisJobServiceEnabledldquo in der Datei bdquocontextxmlldquo ersetzt werden
lt-- Neue Parameter zur Aktivierung des Job Service Ersatz fuumlr availableServices --gt
ltEnvironment
name=isJobServiceEnabled
value=true
type=javalangBoolean
override=true
gt
Ab BSS 30 wird die Jobs-Engine standardmaumlszligig aktiviert Sollte die Jobs-Engine nicht benoumltigt werden muss bdquovalueldquo der Wert bdquofalseldquo zugewiesen werden Wird bdquoisJobServiceEnabledldquo nicht eingefuumlgt sind die Jobs trotzdem standardmaumlszligig aktiv
Nach dem Neustart des Servers und erneutem Einloggen erscheint nun zusaumltzlich der Menuumlpunkt bdquoJobsldquo
bdquopasswordKeyldquo fuumlr Jobs
In der Job-Logik wird ein von BALVI definierter Standard-Schluumlssel fuumlr die Ablagen von schuumltzenswerten Daten z B Passwoumlrtern verwendet Diese Einstellung ermoumlglicht den BALVI-Standard zu uumlberschreiben Wenn Sie diese Einstellung aumlndern muumlssen jedoch alle bislang verschluumlsselten Job-Parameter neu verschluumlsselt werden
ltEnvironment
name=javacompenvjobspasswordKey
value=MeinHochsicheresNeuesPasswort
type=javalangString
Release Notes BALVI Schnittstellenserver Seite 27 von 37
override=true
gt
bdquoJob ID enableddisabledldquo (Deprecated ersetzt ab 28 durch das bdquoBindenldquo von Jobs)
Sondereinstellungen fuumlr die Job-Verwaltung Da alle Jobs in einer Datenbank administriert werden jedoch ggf verteilt auf mehreren Tomcat-Servern ausgefuumlhrt werden sollen besteht hier die Option Jobs fuumlr die aktuelle Tomcat-Instanz separat zu deaktivieren
Die Einstellung ID koumlnnte z B folgendermaszligen aussehen javacompenvjobsC0DB58D8D52C4BBC966D1DC788A4EF8Benabled
Fuumlr weitere Fragen zu dieser Einstellung kontaktieren Sie bitte die BALVI GmbH
ltEnvironment
name=javacompenvjobsIDenabled
value=false
type=javalangBoolean
override=true
gt
2517 Weitere optionale Parameter
Es ist fuumlr diverse einzelne Schnittstellen ggf erforderlich Einstellungen in der Datei bdquocontextxmlldquo zu ergaumlnzen Hinweise zu diesen Parametern sind dann in dem der Schnittstelle beiliegenden Dokument enthalten Das gilt z B fuumlr die Schnittstelle bdquoXGewerbeanzeigenldquo
26 Logging mit logback Das Logging wurde komplett uumlberarbeitet Statt bdquoLog4Jldquo wird jetzt bdquologbackldquo4 benutzt Ab BSS 30 ist es zwingend notwendig die Einstellung vorzunehmen um das Logging der Anwendung zu steuern
Migration Ergaumlnzen Sie die neue Einstellung bdquologgingconfigldquo
lt-- Neue Paramter zur Angabe der Logback Config Ersatz fuumlr log4jConfigLocation --gt
ltEnvironment
name=loggingconfig
value=$catalinabaseconflogback-bssxml
type=javalangString
override=true
gt
Nach wie vor steht es Ihnen frei die Logging-Konfiguration eigenstaumlndig anzupassen
Wenn Sie jedoch dieselbe WAR in einer Tomcat-Instanz unter mehreren Context-Namen betreiben wuumlrden beide dieselbe Logging-Konfiguration verwenden so dass alle Protokolleintraumlge in einer Log-Datei aus
4 httplogbackqoschmanualappendershtml
Release Notes BALVI Schnittstellenserver Seite 28 von 37
mehreren Webanwendungen generiert werden Aumlndern Sie den Namen der Logging-Konfiguration entsprechend ab um fuumlr jede Anwendung eine spezifische Logging-Einstellung vornehmen zu koumlnnen
27 Tocmat Optional Suche im bdquoKlassenpfadldquo um den
Ordner bdquoconfldquo erweitern Die Suche nach Dateien uumlber bdquoclasspathldquo setzt voraus dass die Ordner- und Dateinamen im Apache Tomcat bekannt gegeben werden Der Klassenpfad kann in der Datei bdquocatalinapropertiesldquo angepasst werden Wenn Sie dort unter commonloader die folgenden Werte ergaumlnzen kann eine Datei auch im Ordner conf abgelegt werden damit Apache Tomcat diese findet Ansonsten muss die Datei im Ordner lib abgelegt werden
commonloader=$catalinabaseconf$catalinahomeconf
3 Die neue Browser-Oberflaumlche Der BALVI Schnittstellenserver hat seit Version 25 neben der Protokollierung auch die Moumlglichkeit Job-Konfigurationen zu pflegen Der Login ist nur fuumlr einen in BALVI iP eingetragenen ADMIN (z B Benutzer bdquoSYSTEMADMINldquo) mit dem in BALVI iP hinterlegten Passwort moumlglich Zur Anmeldung muss immer [SYSTEMBenutzername] im Feld Benutzer angegeben werden ansonsten schlaumlgt die Anmeldung fehl Bitte achten Sie darauf dass der bdquoldquo (Slash) und nicht der bdquoldquo (Backslash) verwendet werden muss
31 Server-Protokoll Um das Server-Protokoll anzuzeigen waumlhlen Sie den entsprechenden Menuumlpunkt Dort haben Sie seit BSS 26 die Moumlglichkeit uumlber alle Spalten der Protokolle nach Informationen zu suchen
Seit BSS 31 gibt es die Moumlglichkeit Verfahren in bdquoKopfsaumltzeldquo und bdquoDetailsaumltzeldquo zu unterteilen Wurde das Verfahren entsprechend konfiguriert (wie z B bei der Schnittstelle bdquoXGewerbeanzeigenldquo) dann wird im Protokoll-Kopfsatz nur der Start und das Ende der Ausfuumlhrung in der Liste angezeigt Erst bei einem Klick auf bdquoInformationenldquo wird die Liste aller Detailsaumltze angezeigt die im Durchlauf erzeugt wurden
Release Notes BALVI Schnittstellenserver Seite 29 von 37
Verfahren
Die Liste der verfuumlgbaren Verfahren die bei Ihnen im System installiert sind ZB
BEFUNDEhellip Schnittstelle Befunde LM FM oder TS
PROBEhellip Schnittstelle zum Export von Proben an Labore ebenfalls Spezifisch fuumlr einzelne Fachbereiche
MOBILXT Protokolle der BALVI Mobil XT Synchronisation
WEB Allgemeine nicht spezifizierte Protokolle hierunter ist bislang auch die eFi-Protokollierung zu finden
WEB_I0802 Protokolle zur Schnittstelle BALVI iP LIMS (Lebensmittelproben)
XGEWERBE Schnittstelle XGewerbeanzeigen
Klicken Sie auf die Schaltflaumlche so besteht bei den neuen Protokolldatensaumltzen die Moumlglichkeit Detail-Informationen zum Protokollsatz zu erhalten
Release Notes BALVI Schnittstellenserver Seite 30 von 37
Seit BSS 30x ist die Anzeige der Protokolle ebenfalls farblich abgesetzt so dass Protokolleintraumlge mit Fehlern hellrot und Warnungen hellgelb hinterlegt werden
32 Jobs Mit einem Klick auf den Menuumlpunkt Jobs rufen Sie die Oberflaumlche fuumlr die Job-Konfiguration auf Daraufhin werden alle Jobs aufgelistet die fuumlr den BSS freigegeben sind Hier koumlnnen Sie Einstellungen an den Jobs vornehmen und die Jobs aktivieren bzw deaktivieren Die Beschreibungen bzw Einstellungsmoumlglichkeiten fuumlr den jeweiligen SST-Job sind nicht Bestandteil dieser Dokumentation
33 Log-Ausgaben Uumlber den Menuumlpunkt Log-Ausgaben koumlnnen Sie die Ausgabe der Protokolleintraumlge in Echtzeit beobachten
Release Notes BALVI Schnittstellenserver Seite 31 von 37
Starten Sie die Echtzeit-Protokollierung indem Sie auf die Schaltflaumlche mit dem Symbol bdquoPlayldquo (Dreieck) klicken unterbrechen Sie die Ausgabe indem Sie die auf Schaltflaumlche mit dem Symbol bdquoPauseldquo (zwei Balken) klicken
Klicken Sie auf die Schaltflaumlche bdquoAktualisierenldquo (zwei Pfeile) um die neuesten Protokolleintraumlge angezeigt zu bekommen
Klicken Sie auf das Symbol mit dem Papierkorb um die letzten Protokollmeldungen in der Anzeige zu loumlschen
Die Daten in den Protokolldateien auf der Festplatte des Servers sind davon nicht betroffen
Uumlber das Symbol bdquoLogging anpassenldquo (Schraubenschluumlssel) koumlnnen Sie die Ausgabe der Daten im Echtzeitfenster und in den Protokolldateien aumlndern jedoch ist diese Einstellung nur temporaumlr Die Standardeinstellungen koumlnnen ausschlieszliglich uumlber die Anpassung der Datei bdquologback-bssxmlldquo im Konfigurationsverzeichnis des Servers selbst geaumlndert werden
Release Notes BALVI Schnittstellenserver Seite 32 von 37
In der Logging-Parameter Konfiguration koumlnnen Sie verschiedene Parameter einstellen und uumlber die Schaltflaumlche bdquoAnwendenldquo dann sofort im Echtzeitprotokoll sehen Welche Einstellungen moumlglich sind erfahren Sie wenn es eine akute Fehlersituation gibt die detailliertere Ausgaben im Protokoll erfordert
Warnung Wenn Sie den Log-Level fuumlr ROOT oder eine andere Klasse auf TRACE einstellen werden sehr viele Protokollausgaben generiert die auch dazu fuumlhren koumlnnen dass der Server sehr langsam wird oder die Festplatte des Servers zulaumluft wenn fuumlr das Logging kein Dateilimit konfiguriert wurde
34 LogoutAbmeldung vom System Zum Abmelden waumlhlen Sie oben rechts das Kontextmenuuml
35 Cache loumlschen Der Cache wird in der Regel automatisch geloumlscht Wenn Sie jedoch gerade in BALVI iP eine Aumlnderung an den Schnittstellen eingespielt haben und moumlchten dass diese sofort wirksam wird kann die Funktion bdquoCache loumlschenldquo dazu verwendet werden dass der BALVI Schnittstellenserver die Einstellungen bei der naumlchsten Anfrage neu einliest
Release Notes BALVI Schnittstellenserver Seite 33 von 37
Release Notes BALVI Schnittstellenserver Seite 34 von 37
4 Einrichtung in BALVI iP Um die Verfahren fuumlr den BALVI Schnittstellenserver fuumlr Anwender freizuschalten wird das Objekt bdquoSystemeinstellungenldquo oder bdquoMandanten- und Benutzereinstellungenldquo verwendet Die Anpassung ist je Verfahren moumlglich so kann in BALVI iP fuumlr den Zugriff durch den BALVI Schnittstellenserver ein Benutzer bdquoAldquo am Verfahren bdquoMobilldquo berechtigt werden ein Benutzer bdquoBldquo nur am Verfahren bdquoSLA_FLESHldquo usw Die Logik ist jedoch einheitlich Je Verfahren wird durch BALVI eine Verfahrensgruppe mit dem Verfahrensnamen angelegt und mit den entsprechenden Einstellungen vorkonfiguriert welche durch das Verfahren erforderlich sind Dabei kann die Komplexitaumlt der Einstellungen variieren wie z B an den zu Version 23 verfuumlgbaren Verfahren bdquoMobilldquo und bdquoSLA_Fleshldquo ersichtlich wird
Im Verfahren BALVI Mobil sind diverse Anpassungen moumlglich welche je Bundesland oder eingesetzter Import- und Export-Variante durch den BALVI Schnittstellenserver bei der Bearbeitung von Anfragen gepruumlft werden siehe Punkt 3 Abb Mobil-Einstellung in BALVI iP
Abb Mobil-Einstellung in BALVI iP
Alle Verfahren verwenden jedoch die regulaumlre Benutzerverwaltung von BALVI iP Ein Benutzer ohne Passwort gilt fuumlr BALVI iP als gesperrt was fuumlr das Login bedeutet dass der Anwender sich nur uumlber die Active-Directory-Authentifizierung anmelden kann Ist das nicht moumlglich (bzw nicht konfiguriert) kann der Anwender sich weder in BALVI iP noch uumlber die Webservice-Schnittstelle authentifizieren
Fuumlr Dienste-Schnittstellen welche keine persoumlnliche Authentifizierung durch einen Anwender erfordern wird empfohlen einen separaten Benutzer in der Benutzerverwaltung anzulegen und ein sicheres Kennwort zu vergeben Das Anlegen von zusaumltzlichen Benutzern gilt nicht fuumlr BALVI mobil XT da beim Holen und Uumlbermitteln von Daten jeder Benutzer auch ein fachlich konfigurierter Anwender innerhalb von BALVI iP ist und die Anwendungsoberflaumlche ebenfalls zur Erfassung von Daten verwendet
Unter Punkt 2 der Abb Mobil-Einstellung in BALVI iP wird ein modales Fenster geoumlffnet (Abb BALVI mobil Benutzerverwaltung) Innerhalb dieses modalen Fensters werden mandantenweise die Benutzer fuumlr BALVI
Release Notes BALVI Schnittstellenserver Seite 35 von 37
mobil und den jeweiligen Fachbereich festgelegt Dabei ist es wichtig dass man die Haken bdquoAktiv fuumlr hellipldquo bei bdquohellip mobilldquo und bei einem Fachbereich (bdquohellip LMldquo bdquohellip FMldquo usw) setzt weil sonst uumlber den BALVI Schnittstellenserver keine Kommunikation mit BALVI iP moumlglich ist
Abb BALVI mobil Benutzerverwaltung
Alternativ zur Passwort-Authentifizierung wird wie beschrieben auch die Active-Directory-Authentifizierung angeboten Dazu muss der BALVI iP-Anwender uumlber die Schaltflaumlche bdquoDomaumlnen-Benutzer zuordnenldquo mit dem Active Directory verknuumlpft werden
Nur wenn die Active-Directory-Konfigurationen in BALVI iP und im BALVI Schnittstellenserver auf dieselbe Domaumlne verweisen sind die Domaumlnen-Zuordnung und die Active-Directory-Authentifizierung (z B uumlber BALVI mobil XT) moumlglich
Release Notes BALVI Schnittstellenserver Seite 36 von 37
5 Bekannte Probleme und Loumlsungen
51 ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner Bei der Job-Bearbeitung tritt folgender Fehler auf ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner
Behebung
Fuumlhren Sie das beiliegende IP-Patch (UPDATEexe) aus bevor Sie das WAR austauschen
52 Server startet nicht Sie finden folgende Zeilen im Protokoll (catalinaout oder bsslog)
ERROR [localhost-startStop-1] [IdentityServiceImpl] serverID must not be empty
ERROR [localhost-startStop-1] [ContextLoader] Context initialization failed
Behebung
Setzen Sie die Umgebungsvariable ldquoserverIDrdquo in der Datei bdquocontextxmlldquo
53 ORA-00942 table or view does not exist In vielen Faumlllen wird der Fehler ldquoTabelle oder View nicht vorhandenrdquo ausgeworfen (Java-Protokoll im Ordner logs von Apache Tomcat) wenn eine neue Schnittstelle eingerichtet oder ein neues BALVI iP Release bzw Update eingespielt wurde ohne anschlieszligend das aktuelle GRANT-Skript auszufuumlhren
Behebung
Fuumlhren Sie das GRANT-Skript erneut aus
54 ORA-0406x bdquoBestehender Paketstatus wurde aufgehobenldquo
ORA-04061 Bestehender Status von package body ABCXYZ wurde annulliert
ORA-04065 Ausfuumlhrung nicht erfolgreich package body ABCXYZ wurde geaumlndert oder geloumlscht
Release Notes BALVI Schnittstellenserver Seite 37 von 37
Der Fehler tritt haumlufig ein nachdem die UPDATEexe ausgefuumlhrt und in der Ausfuumlhrungsliste ein Package aktualisiert wurde Oracle merkt sich je User-Session bestimmte Werte im Package wenn der Anwender es verwendet hat Durch einen bdquoCREATE OR REPLACE PACKAGEldquo-Befehl kann dieser Status temporaumlr aufgehoben werden Normalerweise tritt dieser Fehler nach dem Update genau einmal in jeder aktiven Session auf wenn der BSS nicht neu gestartet wird
Behebung
Starten Sie nach jedem Update den BSS neu um alle laufenden Sessions zu beenden
55 Jobs sind nicht ausfuumlhrbar
1 Ein Job wird mit dem Status bdquoNicht unterstuumltztldquo angezeigt wenn fuumlr seine Ausfuumlhrung eine houmlhere Version des BSS erforderlich ist
2 Nach dem Klonen der Datenbank von der Produktions- auf die Testumgebung erhalten alle Jobs automatisch den Status bdquoDeaktiviertldquo wenn die bdquoserverIDldquo nicht identisch ist
Beide Statusaumlnderungen sind gewollt Damit soll verhindert werden dass Jobs nach einem Serverneustart oder nach einem Update automatisch starten und dabei Fehler verursachen
Um Jobs mit dem Status bdquoNicht unterstuumltztldquo nutzen und konfigurieren zu koumlnnen ist es erforderlich den BALVI Schnittstellenserver zu aktualisieren
Deaktivierte Jobs koumlnnen Sie aktivieren indem Sie den jeweiligen Job an den aktuellen Server binden und den Haken bei bdquoAktivldquo setzen
Release Notes BALVI Schnittstellenserver Seite 7 von 37
14 Nacharbeiten nach dem Update auf Version 28
(ADMIN) Sofern Sie schon aktive bdquoJobsldquo im BSS in Verwendung haben werden diese mit dem Update automatisch deaktiviert da die Jobs nun an den ausfuumlhrenden Server gebunden werden muumlssen Oumlffnen Sie dazu den Job in der Detailansicht setzen Sie den Haken hinter bdquoJob an Server bindenldquo setzen und speichern Sie die Einstellung
Der Job wird anschlieszligend in der Uumlbersicht wieder mit dem Status bdquoAktiviertldquo angezeigt Diesen Konfigurationsschritt muumlssen Sie nun jedes Mal durchfuumlhren nachdem die Datenbank von Produktion auf Test geklont wurde
15 Neuerungen in Version 28
151 Jeder Schnittstellen-Server benoumltigt eine Kennung bdquoserverIDldquo Viele Kunden nutzen den Schnittstellenserver mehrfach in Ihrer Umgebung da mehrere BALVI iP Installationen (z B Produktion und Test) in der Infrastruktur existieren
Da die Schnittstellenkonfiguration fuumlr den BSS in der Datenbank abgelegt wird kam es in manchen Faumlllen vor dass nach dem Klonen der Produktionsdatenbank auf ein Testsystem die im BSS angelegten Jobs sofort nach dem Start in der Testumgebung wieder angesprungen sind Um dieses Problem zu beseitigen muss jedem BSS ab Version 28 eine eindeutige bdquoserverIDldquo zugewiesen werden Diese Server-ID wird in der Datei bdquocontextxmlldquo hinterlegt um neutral zur Datenbank zu sein
Ist keine Environment-Variable bdquoserverIDldquo vorhanden wird der Start des BSS 28 (oder houmlher) sofort mit einer Fehlermeldung abgebrochen Im Server-Protokoll wird dabei der Fehler bdquoERROR [IdentityServiceImpl] serverID must not be emptyrdquo ausgegeben Danach kommt sofort die Meldung dass der BSS wieder heruntergefahren wird
INFO [localhost-startStop-1] [ContextCreationListener]
BALVI-Schnittstellen-Server
Version 280
hellip
ERROR [localhost-startStop-1] [IdentityServiceImpl] serverID must not be empty
ERROR [localhost-startStop-1] [ContextLoader] Context initialization failed
Um eine ldquoserverIDrdquo zu vergeben fuumlgen Sie in der Datei bdquocontextxmlldquo folgende Angabe ein
lt--
Release Notes BALVI Schnittstellenserver Seite 8 von 37
ID fuumlr den Server
Diese muss pro Schnittstellenserver eindeutig sein
Eine Aumlnderung dieser ID fuumlhrt sofort dazu dass alle
eingerichteten Server-Jobs inaktiv werden und neu mit
der Instanz gekoppelt werden muumlssen um wieder aktiviert
werden zu koumlnnen
Als value kann ein Text der max Laumlnge von 32 Zeichen
vergeben werden z B ProductionEnvNode1 fuumlr die Produktion
und TestEnvNode1 fuumlr die Testumgebung
--gt
ltEnvironment
name=serverID
value=ProductionEnvNode1
type=javalangString
override=true
gt
152 Optional ist nun eine Namensvergabe moumlglich Auf Wunsch mehrerer Kunden wurde die Option geschaffen jedem Server zusaumltzlich einen kundenspezifischen bdquoTitelldquo zu geben um die Server besser unterscheiden zu koumlnnen
lt--
Visueller Name des Servers in der Oberflaumlche
(Optional)
--gt
ltEnvironment
name=serverName
value=TIERZ Tomcat 8 Java 8 mit BALVI_TIERZXGEWETLBTR_BSS
type=javalangString
override=true
gt
Der hier angegebene Text wird in der Kopfzeile zwischen den eckigen Klammern ausgegeben
Release Notes BALVI Schnittstellenserver Seite 9 von 37
2 Einrichtungshinweise
21 Allgemeine Hinweise zum Betrieb
211 Kompatibilitaumlt zu Apache Tomcat und Java SE Der BALVI Schnittstellenserver wurde getestet und freigegeben fuumlr Apache Tomcat 8 (ab Version 8030 oder neuer) Zudem wurde die aktuellste (letzte offizielle) Version von Java SE 8 getestet und kann verwendet werden (Java SE 8u40 und neuer)
Installieren Sie stets die aktuellsten Sicherheitsupdates fuumlr Java SE 8 Beachten Sie dabei jedoch dass nicht die Aktualisierung auf eine andere Java-Version (z B Java 9) gemeint ist
Freigegebene Major-Versionen werden explizit von BALVI benannt Falls Sie beabsichtigen die Major-Version zu aumlndern pruumlfen Sie bitte die aktuellen Release Notes oder kontaktieren die BALVI Kundenbetreuung
212 Oracle Java SE Lizenzierung Java SE beinhaltet auch kostenpflichtige Funktionen fuumlr deren Nutzung Oracle Lizenzgebuumlhren fordert wenn sie bei der Entwicklung eingesetzt werden Die von BALVI gelieferte Software ist frei von den kommerziellen Teilen der Oracle Java SE nutzbar Fuumlr den Einsatz von Oracle Java SE (einschlieszliglich JDK und JRE) fallen im Rahmen der Nutzung der BALVI Software keine Lizenzkosten an
Trotzdem werden wir parallel pruumlfen ob technische Probleme bei der Umstellung auf das OpenJDK zu erkennen sind Ein einfacher Funktionstest hat im BSS 3x noch keine technischen Probleme gezeigt als wir die Laufzeitumgebung auf das OpenJDK 8U111 AMD64 (Debian) umgestellt haben Bitte haben Sie Verstaumlndnis dafuumlr dass wir keine Funktionstests fuumlr jedes Linux-Derivat durchfuumlhren koumlnnen und dass es offiziell keine Version des OpenJDK fuumlr Windows Betriebssysteme gibt
213 Einsatz von TLSSSL BALVI hat keine spezifischen Anforderungen an die Konfiguration von SSL bzw TLS Der Einsatz von TLS 12 gem der Richtlinie TR-02102-2 vom BSI ist moumlglich wenn Sie sich an die von Apache Tomcat herausgegebene Dokumentation halten Es sind keine Anpassungen des Schnittstellenservers erforderlich Daher gehen wir davon aus dass auch der BSS 28x oder aumllter in einem Apache Tomcat mit TLS 12 betrieben werden kann
Das gilt jedoch nicht fuumlr alle Clients die den Tomcat-Server ansprechen moumlchten So ist z B erst ab BALVI mobil 191958 sichergestellt dass die Protokolle TLS 11 und TLS 12 programmseitig aktiviert sind Fuumlr Details zu diesem Problem wurde ein separates Rundschreiben per E-Mail versendet
Release Notes BALVI Schnittstellenserver Seite 10 von 37
214 Nutzung von Java-Proxyeinstellungen Der BALVI Schnittstellenserver verwendet fuumlr ausgehende Verbindungen die Java-Net Einstellungen welche in der Java-Dokumentation1 beschrieben sind Falls Sie Jobs einsetzen welche ausgehenden Zugriff auf Adressen im Internet benoumltigen kann es passieren dass Sie z B eine bdquojavanetUnknownHostExceptionldquo im Protokoll finden dann muumlssen Sie ihre Proxy-Umgebung in den Java-Umgebungseinstellungen ergaumlnzen
Die folgenden Parameter sollten daher in Ihrer Umgebung gesetzt werden wenn der Zugriff auf das Internet nur uumlber einen Proxy moumlglich ist
-DproxySet=true
-DproxyHost=10111213
-DproxyPort=8888
-DhttpnonProxyHosts=domainorg|localhost|10
Starten Sie nach Aumlnderung der Einstellungen den Server neu damit die Einstellungen wirksam werden
2141 Proxy-Einstellung unter Windows (Tomcat-Dienst)
Verwenden Sie das Dienste-Konfigurationsprogramm (z B tomcat7wexe) und ergaumlnzen Sie die fehlenden Einstellungen
2142 Proxy-Einstellung unter Linux
In Linux wird in der Konfigurationsdatei (z B conftomcat7conf) die Variable bdquo$JAVA_OPTSldquo entsprechend erweitert und die Werte uumlbergeben Beachten Sie dabei dass die Variablen von Linux (bzw der Bash) gelesen werden Daher muss das bdquoPipeldquo-Zeichen bdquo|ldquo mit bdquoldquo maskiert werden ansonsten erhalten Sie bei der Verarbeitung der Umgebungsvariable bdquohttpnonProxyHostsldquo Fehlermeldungen in der Linux -Konsole welche dazu fuumlhren dass Java nicht korrekt konfiguriert werden kann
JAVA_OPTS=$JAVA_OPTS -DproxySet=true -DproxyHost=10111213 -DproxyPort=8888
JAVA_OPTS=$JAVA_OPTS -DhttpnonProxyHosts=domainorg|localhost|10
1 httpdocsoraclecomjavase8docstechnotesguidesnetpropertieshtml
Release Notes BALVI Schnittstellenserver Seite 11 von 37
215 Spracheinstellung Deutsch Es wurde festgestellt dass unter einigen Linux-Versionen die Spracheinstellung beim Starten des Apache Tomcat nicht auf eine deutsche Umgebung verweist Dieses kann technische Probleme verursachen Unter Linux sollte die Einstellung (Umgebungsvariable) entsprechend auf LANG=de_DEUTF-8 eingestellt sein
216 Datenbankverbindung Wenn Sie eine Firewall zwischen dem Oracle-Server und dem Database Connection Pool (DBCP) verwenden sollte unbedingt die bdquovalidationQueryldquo in der DBCP-Konfiguration aktiviert werden damit die Anwendung schneller freie Connections aus dem Pool erhalten kann Die Dokumentation zu den Einstellmoumlglichkeiten ist in der beiliegenden Contextxml ergaumlnzt worden
Bitte beachten Sie dass dringende empfohlen wird die bdquoFactoryldquo auf orgapachetomcatjdbcpoolDataSourceFactory anzupassen falls sie noch auf bdquoorgapachecommonsdbcpBasicDataSourceFactoryldquo eingestellt ist
217 Probleme beim Anlegen von LOB-Objekten Der BALVI Schnittstellen-Server erfordert die JDBC-Spezifikation DBCP V4 welche durch die Factory bdquoorgapachetomcatjdbcldquo ab Tomcat 7 automatisch bereitgestellt wird
Wenn die Pooling-Komponente oder der Oracle-Treiber nicht JDBC4-Kompatibel sind gibt es beim Bearbeiten von LOB-Objekten in Java diverse Exceptions z B
Servletservice() for servlet soapws threw exception
javalangAbstractMethodError
orgapachecommonsdbcpPoolingDataSource$PoolGuardConnectionWrappercreateClob()LjavasqlClob
at debalvicoreauditspyConnectionSpycreateClob(ConnectionSpyjava511)
Ursache dieses Problems ist meistens dass noch nicht auf bdquoorgapachetomcatjdbcldquo umgestellt wurde
218 Umbenennung der gelieferten WAR-Datei Das im Paket von BALVI gelieferte WAR kann jederzeit umbenannt werden (z B als ROOTwar) ohne dass dabei spezielle Einstellungen in der Datei bdquocontextxmlldquo erforderlich sind
Beachten Sie dabei jedoch dass die zum WAR zugehoumlrige Datei bdquocontextxmlldquo im Apache Tomcat immer denselben Namen erhaumllt wie das WAR z B bdquocommserverwarldquo und bdquocommserverxmlldquo Der Name ist dabei ausschlaggebend fuumlr die Zugriffs-Adresse (Context) im Apache Tomcat selbst Die Benennung des WAR in bdquocommserverwarldquo wuumlrde folgendermaszligen aufzurufen sein httpserverportcommserver
219 Server-Schnittstellen Die Uumlberarbeitung bzw Erweiterung der Export- und Importschnittstellen welche uumlber den Schnittstellenserver bereitgestellt werden ist unabhaumlngig vom Schnittstellenserver selbst Die Schnittstellen sind daher nicht Bestandteile des Schnittstellenserver und werden je Verfahren separat
Release Notes BALVI Schnittstellenserver Seite 12 von 37
ausgeliefert Ggf ist es fuumlr unterschiedliche Schnittstellen erforderlich die Grant-Rechte zu aktualisieren (Vgl bdquoWann ist die Ausfuumlhrung des Grant-Skripts erforderlichldquo)
22 Kompatibilitaumltsliste Diverse Verfahren setzen eine Mindestversion des BALVI Schnittstellenservers voraus Die Schnittstellen sind jedoch so konzipiert dass eine Aktualisierung auf eine houmlhere Version des Servers ohne Anpassung an den vorhandenen Schnittstellen jederzeit moumlglich ist
Derzeit sind folgende Mindestanforderungen gegeben
1 BALVI mobil XT 170 oder houmlher setzt BSS 265 und BALVI iP 124x voraus
2 BALVI mobil XT 183 oder houmlher setzt BSS 281 und BALVI iP 124x voraus
3 BALVI mobil 2 (DM) setzt BSS 311 und BALVI iP 124x voraus
4 Die Schnittstelle eFI setzt BSS 251 und BALVI iP 122c voraus
5 Die Schnittstelle LIMS setzt BSS 265 voraus
6 Die Schnittstelle TSK (SN) setzt BSS 265 voraus
7 Die Schnittstelle xDomea (SN) setzt BSS 265 und Java 7 voraus
8 Die Schnittstelle XGewerbeanzeigen 11 setzt BSS 281 BALVI iP 124x Java 8 mit der bdquoJava
Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy2ldquo voraus
9 Die Schnittstelle XGewerbeanzeigen 12 (ab Paket 7 Ausbaustufe 3) setzt BSS 302 BALVI iP
124x Java 8 mit der bdquoJava Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policyldquo
voraus
10 Die Schnittstelle RioPP LM (NRW) setzt BSS 303 und die ETL-Konfiguration voraus
11 Die Schnittstellen zu BALVI iP2 (Fachmodule BTS LM ZDA Stand Juni 2017) setzen BSS 32x
voraus
2 httpwwworaclecomtechnetworkjavajavasedownloadsjce8-download-2133166html
Release Notes BALVI Schnittstellenserver Seite 13 von 37
23 Erforderliche Bibliotheken fuumlr Apache Tomcat Dateiname Funktion Quelle ojdbc6jar Oracle 11gR2 Clientpaket Oracle JDBC Client fuumlr Java
16 ersetzt die bisherige Version bdquoojdbc14jarldquo Die alte Library muss auf jeden Fall entfernt werden
httpwwworaclecomtechnetworkdatabaseenterprise-editionjdbc-112010-090769html
encrypted-datasource-110-alljar
Die Library muss auf jeden Fall entfernt werden Wird derzeit nicht weiter gepflegt da kein Interesse an der Funktionalitaumlt bestand
slf4j-api-1511jar slf4j-log4j12-1511jar log4jdbc4-12beta2jar
Entfaumlllt nicht mehr erforderlich Es wird empfohlen diese zu entfernen falls diese im LIB-Verzeichnis vorhanden sein sollten
commons-dbcp-14jar commons-pool-154jar
Entfaumlllt nicht mehr erforderlich Es wird empfohlen diese zu entfernen falls diese im LIB-Verzeichnis vorhanden sein sollten
Erwartet wird stattdessen ab Tomcat7 die mitgelieferte bdquotomcat-jdbcjarldquo
log4j-1217jar (oder houmlher)
Logging-Funktionalitaumlt Apache Log4j httploggingapacheorglog4j12downloadhtml
bcprov-jdk15on-157jar (oder houmlher)
BouncyCastle Security Provider fuumlr SSLAES hellip wird ab Version 27 im Ordner bdquolibldquo des Tomcat erwartet Sollte es aus Sicherheitsgruumlnden erwuumlnscht sein eine aktuellere Version einzusetzen ist dieses idR moumlglich
httpmvnrepositorycomartifactorgbouncycastlebcprov-jdk15on157
24 Datenbank-Installation Der BALVI Schnittstellenserver benoumltigt auszligerhalb des angebundenen BALVI iP keine eigenen Tabellen Die Web-Anwendung kann im einfachsten Fall direkt auf das Schema von BALVI iP zugreifen indem der Benutzer und das Passwort des BALVI iP-Schemas in der Datei bdquocontextxmlldquo eingetragen werden (nicht empfohlen)
Sollte dies aus Sicherheitsgruumlnden nicht erwuumlnscht sein (empfohlen vom BSI und von BALVI) finden Sie im Paket ein GRANT-Skript um Zugriffsrechte vom BALVI iP Schema fuumlr den Webservice-Schema-Benutzer einzurichten
Zwischen dem Schema von BALVI iP und jeder Web-Anwendung ist dann eine Trennung moumlglich um sicherzustellen dass der Datenbank-Benutzer welcher in der Tomcat-Konfiguration fuumlr die Web-Anwendung eingetragen wird geaumlndert oder geloumlscht werden kann ohne dass die Windows-Anwendung BALVI iP davon betroffen ist Zudem vergibt das von BALVI gelieferte Grant-Skript keine Rechte zum Loumlschen von Tabellenstrukturen oder Tabelleninhalten so dass der Webservice nur festgelegte Daten aumlndern oder lesen darf Es wird empfohlen je Web-Anwendung einen eigenen Datenbank-Benutzer zu vergeben wenn Sie ein BALVI iP mit mehreren Webservices verbinden wollen
Die Moumlglichkeiten im Uumlberblick
1) Sie betreiben den Webservice mit einem eigenstaumlndigen Oracle-Benutzer In diesem Fall muss das
Grant-Skript ausgefuumlhrt werden um den Webservice-Benutzer und den BALVI iP-Benutzer
miteinander zu koppeln
2) In der Tomcat-Konfiguration wird der Oracle-Benutzer eingetragen welcher auch der BALVI iP
Schemabesitzer ist und in der bdquobalviip_conninildquo hinterlegt ist (NICHT Empfohlen) Der Webservice
Release Notes BALVI Schnittstellenserver Seite 14 von 37
hat 100 Zugriffsrechte (auch Loumlsch- oder Aumlnderungsrechte am Schema) es wird kein Grant-
Skript benoumltigt
Wenn Sie die Konfiguration 2) waumlhlen moumlchten koumlnnen Sie die folgenden Unterkapitel uumlberspringen und in Kapitel 0 bzw fortsetzen
241 Erstinstallation Datenbank-Benutzer anlegen Wenn Sie den Webservice-Benutzer vom BALVI iP Schema trennen moumlchten muss durch die DB-Administration in der Oracle-Server-Instanz wo auch BALVI iP sein Schema besitzt ein Benutzer (ggf je Web-Anwendung) angelegt werden welcher folgende Rechte benoumltigt
CONNECT
ALTER SESSION
CREATE JOB
CREATE PROCEDURE
CREATE SESSION
CREATE TABLE
CREATE TRIGGER
CREATE TYPE
CREATE VIEW
CREATE SEQUENCE
CREATE SYNONYM
QUERY REWRITE
Der Default-Tablespace ist frei waumlhlbar Der Benutzer braucht das Recht QUOTA UNLIMITED auf den Tablespace von BALVI iP (Default BALVI_IP) Ein Beispiel-Create-Skript bdquooraCreate_WEB_Usersqlldquo liegt der Auslieferung bei
242 Rechte zuweisen Wenn der BALVI iP Schemabesitzer NICHT in der Tomcat-Umgebung eingetragen werden soll muss ein Oracle DBA das beiliegende GRANT-Skript bdquooraGrantIP_to_Websqlldquo ausfuumlhren um dem jeweiligen Webservice (in Tomcat verwendeten Oracle-Benutzer) die minimalen Rechte auf das Schema von BALVI iP zu gewaumlhren
Dieses Skript setzt voraus dass es von einem Oracle Administrator als bdquoUser SYSTEMldquo ausgefuumlhrt wird Lesen Sie die im Skript enthaltenen README-Kommentare und passen Sie die Benutzer (BALVI iP Schema) und (WEB-Schema) an
====================================================
DEKLARATIVER TEIL MUSS vom KUNDEN geaumlndert
bzw auf die korrekten SCHEMA-Namen angepasst
werden
Die USER-Namen muumlssen in Groszligbuchstaben
geschrieben sein sonst werden sie nicht
gefunden
====================================================
sUserBALVI_IP = BALVI_IP_SCHEMABESITZER
sUserBALVI_WEB = BALVI_WEB_SCHEMABESITZER
Release Notes BALVI Schnittstellenserver Seite 15 von 37
Neu ab Grant-Skript 158 ist die Umbenennung der Verfahrenszuordnung
Pruumlfen Sie dass die Einstellung fuumlr Ihr BundeslandVerfahren korrekt ist dort muss eine 1 fuumlr min ein Verfahren gesetzt sein Diese Einstellung befindet sich direkt unter den Schemabesitzer-Angaben
-- Verfahrensbezogene Konfiguration
-- Setzen Sie fuumlr das jeweilige Verfahren eine 1
-- BALVI Schnittstellenserver (BSS)
-- bis V266 auch BALVI Kommunikationsserver (BKS) genannt
-- generell fuumlr die meisten Verfahren guumlltig
-- Ab Version 57 entfaumlllt mit der Einfuumlhrung der
-- Schnittstelle XGewerbeanzeigen auch der separate Schalter
-- WS_BTR beide Verfahren wurden vereinheitlicht
WS_BSS = 1
Fuumlhren Sie das Skript nach der Anpassung als User SYSTEM aus um die Grants durchzufuumlhren Dieses wurde mit dem von ORACLE gelieferten Programm SQLPLUS (Command-Line) SQLPLUS Worksheet (GUI) und Oracle SQL-Developer getestet
Das Skript generiert fuumlr jedes Objekt ein SYNONYM fuumlr den WEB-USER so dass dieser auf die Objekte ohne Angabe des Owners des IP-Schemas zugreifen kann Pruumlfen Sie nach der Ausfuumlhrung dass die SYNONYMS vorhanden und VALID sind dieses kann ggf nicht der Fall sein Das Skript kann jederzeit erneut ausgefuumlhrt werden um die Grants neu zu erzeugen und bietet ebenfalls die Option alle Grants und Synonyme wieder zu entfernen Detaillierte Informationen zur Nutzung des Skripts sind als Kommentar-Block im Skript enthalten
Hinweis Die Versionsinformation ist unter den Kommentaren direkt im Skript zu finden
Zugriffsberechtigungen fuumlr Webanwendungen auf BALVI iP anlegen
===============================================================
Version 158
Guumlltig fuumlr BALVI iP 123 oder houmlher
Autor Frank Holler
SVN Revisionsinformationen
$Revision 479 $
$Date 2016-02-15 152755 +0100 (Mo 15 Feb 2016) $
================================================================
243 Wann ist die Ausfuumlhrung des Grant-Skripts erforderlich Durch das Strukturupdate von BALVI iP (z B 1240 auf 1241) werden veraltete Strukturen geloumlscht und ggf neue Views oder Tabellen angelegt Die Grant-Rechte geht dabei ggf verloren Daher ist die Ausfuumlhrung des Grant-Skripts immer dann erforderlich wenn sich die Datenbank-Struktur von BALVI iP veraumlndert
Zudem kann es fachliche Neuerungen geben welche im alten Grant-Skript nicht vorhanden sind Daher muss das Skript ggf auch ausgefuumlhrt werden wenn eine neue Schnittstelle im Schnittstellenserver bereitgestellt wurde Dieses betrifft z B auch die Bereitstellung von neuen Versionen von BALVI mobil XT
Release Notes BALVI Schnittstellenserver Seite 16 von 37
da auch dort mit einem fachlich erweiterten Client die Moumlglichkeit besteht dass neue Schnittstellen bereitgestellt und somit mehr Schreibrechte auf Tabellen benoumltigt werden
244 Welche Version des Grant-Skripts soll ich nehmen Wie der Schnittstellenserver sind auch die Grant-Skripte versioniert Neuere Versionen des Grant-Skriptes sind abwaumlrts-kompatibel und koumlnnen immer verwendet werden auch wenn in einer Schnittstellenbeschreibung eine aumlltere Version des Grant-Skriptes explizit benannt wurde
245 Kombination von mehreren Verfahren Wenn Sie zwei oder mehr Schnittstellen im BSS verwenden moumlchten ist es ggf erforderlich auch mehrere Verfahren auf aktiv (bdquo1ldquo) zu setzen
Im Beispiel nehmen wir an Sie moumlchten bdquoeFildquo und bdquoBALVI mobil XTldquo im Schnittstellenserver bereitstellen In der Beschreibung von bdquoeFildquo steht dass das Grant-Skript V36 erforderlich ist BALVI mobil XT 18 erfordert jedoch schon V56
Wenn Sie beide Verfahren betreiben ist im Grant-Skript (V56 oder houmlher) die Einstellung fuumlr beide Verfahren zu aktivieren
====================================================
DEKLARATIVER TEIL MUSS vom KUNDEN geaumlndert
bzw auf die korrekten SCHEMA-Namen angepasst
werden
Die USER-Namen muumlssen in Groszligbuchstaben
geschrieben sein sonst werden sie nicht
gefunden
====================================================
sUserBALVI_IP = BALVI_IP_SCHEMA
sUserBALVI_WEB = WEBAPP_SCHEMA
-- Verfahrensbezogene Konfiguration
-- Setzen Sie fuumlr das jeweilige Verfahren eine 1
-- BALVI Schnittstellenserver (BSS)
-- bis V266 auch BALVI Kommunikationsserver (BKS) genannt
-- generell fuumlr die meisten Verfahren guumlltig
-- Ab Version 57 entfaumlllt mit der Einfuumlhrung der
-- Schnittstelle XGewerbeanzeigen auch der separate Schalter
-- WS_BTR beide Verfahren wurden vereinheitlicht
WS_BSS = 1
-- WebService BTR (Betriebsstaumlttenregister) (NRW TH)
-- entfernt mit Update V57 setzen Sie stattdessen bei WS_BSS = 1
--WS_BTR = 0
-- Probenahme Futtermittel im Browser(BY)
WS_PROBE_FM = 0
-- Risikoorientierte Probenplanung Futtermittel ndash RIOPP FM (BY)
WS_RIOPP_FM = 0
-- Verfahren Export an EFi (Status Pilotbetrieb)
WS_EFI = 1
-- neu ab Version 35 des Grant-Skriptes ist die Moumlglichkeit den Webuser
Release Notes BALVI Schnittstellenserver Seite 17 von 37
-- fuumlr das Loumlschen der Ausgangskoumlrbe explizit zu berechtigen bzw sogar einen
-- expliziten abweichenden User festzulegen Die Konfiguration in der
-- Job-Oberflaumlche sieht vor dass man die Oracle-Datenbank-Zugangsdaten fuumlr
-- das Loumlschen einstellen muss Hier muss im Normalfall derselbe Oracle
-- Datenbankbenutzer eingetragen werden wie in der Tomcat-Verbindungs-
-- konfiguration In diesem Fall sollte wenn WS_EFI = 1 eingestellt wurde
-- ebenfalls WS_EFI_DELETE = 1 eingestellt werden
-- Alternativen
-- 1) Datenbankbenutzer aumlndern
-- Wenn bei sUserEFI_TRUNC anstatt sUserBALVI_WEB (Standard) ein anderer
-- Oracle-Benutzername angegeben wird wird das Loumlschrecht fuumlr die EFi
-- Ausgangskoumlrbe Datenbankseitig exklusiv dem angegeben Datenbankbenutzer
-- zugewiesen
-- 2) Loumlschrecht verweigern
-- Setzen Sie die Variablen WS_EFI_DELETE = 0 damit kein Loumlschrecht
-- zugeweisen wird
WS_EFI_DELETE = 0
-- Beispiel Anderer Benutzer muss in der Datenbank existieren
-- Entfernen Sie die fuumlhrenden -- vor der Variable sUserEFI_TRUNC und
-- setzen den entsprechenden Oracle-Benutzer ein
--sUserEFI_TRUNC = TEST_EFI_TRUNC
hellip
25 Konfiguration des Schnittstellen-Servers
251 Die bdquocontextxmlldquo-Parameter Die von der Servlet-Spezifikation vorgegeben Rump-Struktur sieht folgendermaszligen aus
ltxml version=10 encoding=utf-8gt
ltDOCTYPE Contextgt
ltContextgt
lt-- Kundenspezifische Einstellungen --gt
ltContextgt
Anwendungsspezifische Einstellungen werden zwischen ltContextgt und ltContextgt eingefuumlgt Alle allgemeinguumlltigen Einstellungen in der Datei bdquocontextxmlldquo werden hier erlaumlutert Kommentare finden sich auch in der von BALVI ausgelieferten Beispiel-Konfiguration
Neben den im Folgenden beschriebenen Standard-Einstellungen kann es auch vorkommen dass bundeslandspezifische Erweiterungen vorhanden sind welche nicht in dieser Dokumentation aufgefuumlhrt werden Diese funktionieren trotzdem regulaumlr weiter wenn keine expliziten Informationen zu Kompatibilitaumltsproblemen in den Release-Notes aufgefuumlhrt wurden
2511 Datenbankverbindung jdbcDataSource
Die Datenbankverbindung wird uumlber die von DBCP und dem Oracle-Treiber vorgegebenen Moumlglichkeiten realisiert Der Einsatz der orgapachetomcatjdbcpoolDataSourceFactory (automatisch verfuumlgbar ab Apache Tomcat 7 in der mitgelieferten tomcat-dbcpjar) wird als Beispiel-Konfiguration ausgeliefert
ltResource
name=jdbcDataSource
auth=Container
Release Notes BALVI Schnittstellenserver Seite 18 von 37
type=javaxsqlDataSource
factory=orgapachetomcatjdbcpoolDataSourceFactory
maxActive=10 initialSize=3
maxIdle=5
maxWait=10000
url=jdbcoraclethinBL2-ORA10-KUNDENBALVIINTERN1521ORCL
driverClassName=oraclejdbcdriverOracleDriver
username=balvi_webservice_schema
password=balvi_webservice_password
description=Oracle Datasource
maxOpenPreparedStatements=50
removeAbandoned=false
removeAbandonedTimeout=100
logAbandoned=true
jdbcInterceptors=hellip
gt
Hinweise zur Einstellung der jdbcDataSource
Standard-Einstellungen fuumlr den Datenbank-Verbindungspool
Der Verbindungspool muss entsprechend der Anzahl der zu erwartenden gleichzeitigen Benutzer konfiguriert werden Wenn Sie erwarten dass 50 Anwender gleichzeitig arbeiten stellen Sie bitte folgende Werte ein
maxActive=(50 + 10 (fuumlr System und Jobs)) = 60
maxIdle= (50 10) = 5
1 maxActive - maximale Anzahl der gleichzeitigen aktiven Anfragen an die DB
Wenn der Werte maxActive erreicht ist z B wenn mehrere Benutzer gleichzeitig einen Export starten moumlchten welcher laumlngere Zeit in Anspruch nimmt dann kann der Server die Anfrage nicht mehr bedienen und der Anwender wird abgewiesen maxActive hat zudem Auswirkungen auf die im Hintergrund ausgefuumlhrten Jobs maxActive wird daher kalkuliert mit der Anzahl der Anwender und moumlglicher Datenbank-Connections fuumlr Hintergrund-Jobs Jeder aktiv ausgefuumlhrte Job benoumltigt mindestens eine Connection nur selten wird aus Performance-Gruumlnden mehr als eine Connection waumlhrend der Job-Ausfuumlhrung verwendet Im Normalfall sollten daher 10 Connections fuumlr Hintergrundprozesse ausreichend sein
2 maxIdle - Anzahl der offenen Verbindungen auch wenn der Server im Leerlauf ist
Jede offene Verbindung im Leerlauf haumllt auf dem Datenbankserver eine Session offen Auch diese erfordert Ressourcen Wenn die Verbindungen jedoch geschlossen werden kann die Anfragezeit fuumlr eine neue Verbindung steigen da diese Verbindung erst neu ausgehandelt werden muss Die Empfehlung fuumlr den Wert bdquomaxIdleldquo ist ca 10 der Einstellung von maxActive
KeepAlive-Einstellungen fuumlr den Pool
1 validationQuery
Diese wird ausgefuumlhrt um die Verbindung zu DB zu validieren Es MUSS ein Datensatz zuruumlckgegeben werden ansonsten nimmt der DBCP an dass die Abfrage nicht erfolgreich abgesetzt wurde Achten Sie also bitte darauf dass die Abfrage nicht zu leitungsintensiv ist und genau einen Datensatz liefert
Release Notes BALVI Schnittstellenserver Seite 19 von 37
Oracle bietet dafuumlr die virtuelle Tabelle DUAL an welche sich fuumlr die ValidationQuery sehr gut eignet da die Abfrage kaum Ressourcen verbraucht
validationQuery=select 1 from dual
2 testOnBorrow - Boolscher Wert true oder false
Diese Einstellung sorgt dafuumlr dass der Pool die Verfuumlgbarkeit anhand der validationQuery pruumlft bevor
die DB-Verbindung an die Anwendung ausgeliehen wird Empfehlung
testOnBorrow=true
3 testWhileIdle - Boolscher Wert true oder false
Diese Einstellung ist hilfreich wenn zwischen dem Tomcat und der DB eine Firewall mit Stateful
Packet Inspection verwendet wird Nach laumlngerer Inaktivitaumlt wird normalerweise durch die Firewall die
DB-Verbindung geschlossen Dieses loumlst dann beim Ausleihen der Verbindung eine Fehlermeldung im
Protokoll aus 2012-08-16 165418720 WARN [http-0000-8080-8]
[orgspringframeworkjdbcsupportSQLErrorCodesFactory] Error while extracting
database product name - falling back to empty error codes
orgspringframeworkjdbcsupportMetaDataAccessException Error while extracting
DatabaseMetaData nested exception is javasqlSQLRecoverableException Getrennte
Verbindung Um dieses Problem zu beheben sollte die Option testWhileIdle=true eingestellt werden
testWhileIdle=true
Damit diese weiszlig wie oft eine Pruumlfung durchgefuumlhrt werden muss sind jedoch noch zusaumltzliche Angaben erforderlich welche fuumlr die Einstellung der Zeit zusaumltzlich gesetzt werden muumlssen
a) minEvictableIdleTimeMillis - Long in Millisekunden
Min Zeit wie lange eine DB-Verbindung im Leerlauf ist bevor diese zur Pruumlfung
gekennzeichnet wird Dieses haumlngt stark von der Einstellung der Firewall ab Wenn Sie eine
sehr restriktive Firewall haben kann es sein dass diese die Verbindung nach wenigen
Minuten Leerlauf trennt Stellen Sie den Wert immer so ein dass dieser unter der Leerlaufzeit
der Firewall liegt empfohlen 300000 entspricht 300 Sek = 5 min
minEvictableIdleTimeMillis=300000
b) timeBetweenEvictionRunsMillis - Long in Millisekunden
Der Pruumlflauf startet in der Default-Konfiguration alle 1800000 Millisekunden = 30 Min n als
zu Pruumlfen markierte Verbindungen werden in einem Pruumlflauf getestet n wird bestimmt durch
die Einstellung numTestsPerEvictionRun Empfehlung Stellen Sie den Wert auf alle 15 Min
ein
timeBetweenEvictionRunsMillis=900000
Release Notes BALVI Schnittstellenserver Seite 20 von 37
c) numTestsPerEvictionRun - Integer
Wie viele Verbindungen sollen getestet werden waumlhrend der Pruumlflauf ausgefuumlhrt wird Im
Normalfall sollte die Anzahl der zu testenden Verbindungen nicht zu hoch eingestellt werden
Der Default ist 3 Wenn Sie houmlhere Sicherheit haben wollen dass keine bdquototenldquo
Datenbankverbindungen bestehen bleiben erhoumlhen Sie den Wert auf max bdquo(maxActive ndash
maxIdle) 2ldquo Wenn Ihnen 3 ausreichend erscheint muss der Wert nicht gesetzt sein dann
wird der Default verwendet
Beispiel numTestsPerEvictionRun=10
4 Interceptors konfigurieren Neu ergaumlnzt wurde die Moumlglichkeit spezielle bdquoInterceptorsldquo zu konfigurieren die ermoumlglichen das Verhalten des Pools zu steuern Wichtig hierbei ist dass die Angabe von Werten auf real existierende Java-Klassen erfolgt die im Classpath des Tomcat vorhanden sind Groszlig-und-Kleinschreibung ist zu beachten Folgende Default-Einstellung hat BALVI fuumlr den BSS festgelegt jdbcInterceptors=
orgapachetomcatjdbcpoolinterceptorConnectionState
orgapachetomcatjdbcpoolinterceptorStatementFinalizer
orgapachetomcatjdbcpoolinterceptorResetAbandonedTimer
Details zu den verwendeten Interceptor-Einstellungen finden Sie in der Tomcat-Dokumentation3
3 httptomcatapacheorgtomcat-80-docjdbc-poolhtmlJDBC_interceptors
Release Notes BALVI Schnittstellenserver Seite 21 von 37
2512 Datenbank-Zugangsdaten verschluumlsseln
Die Verschluumlsselung fuumlr die Datenbank-Verbindung (bdquoEncrypted Datasourceldquo) ist eine Ableitung der Bibliothek Apache-Common-DBCP-14 und daher nicht mehr mit Java 8 kompatibel Die Einrichtung der Verschluumlsselung wird daher mit der Auslieferung des BSS 30 nicht mehr angeboten
2513 Active-Directory-Authentifizierung
Uumlber die folgenden Parameter wird der Zugriff des Schnittstellen-Servers auf einen Microsoft Active Directory Domain-Controller konfiguriert
ldquoldapServerAddressrdquo
Syntax PROTOKOLLIP-Adresse oder DNS-NamePORT
ltEnvironment
name=ldapServerAddress
value=ldapbl2-dc02balviintern389
type=javalangString
override=true
gt
Als Protokoll besteht auch die Moumlglichkeit ldaps (LDAP+SSL) wenn der Domain-Controller entsprechend konfiguriert wurde Im Java Truststore muss dann das Zertifikat der CA vorhanden sein welche das Zertifikat des Domain-Controllers signiert hat Zudem darf bei ldaps keine IP-Adresse verwendet werden es muss der DNS-Name des Server-Zertifikats eingetragen sein Ansonsten gibt es beim Verbinden eine Sicherheits-Exception
lt-- SSL-Beispiel
ltEnvironment
name=ldapServerAddress
value=ldapsbl2-dc02balviintern636
type=javalangString
override=true
gt
--gt
bdquoldapBaseDnrdquo
LDAP-Suchpfad fuumlr die Domain-Basis Diese muss der LDAP-Syntax fuumlr den Domain-Suffix entsprechen
Syntax DC=SERVERDC=ROOTDN
ltEnvironment
name=ldapBaseDn
value=DC=BALVIDC=INTERN
type=javalangString
override=true
gt
Release Notes BALVI Schnittstellenserver Seite 22 von 37
bdquowebLoginUseActiveDirectoryAuthenticationrdquo
Die Authentifizierung in der Browser-Oberflaumlche kann uumlber die Active-Directory-Authentifizierung erfolgen In der ersten Version ist nur die Protokoll-Auswertung moumlglich wenn der ADMIN sich anmeldet Dieser hat normalerweise niemals AD-Kennungen zugeordnet BALVI empfiehlt diese Einstellung auf bdquofalseldquo zu belassen Webservices welche uumlber SOAPREST zugreifen koumlnnen die Active-Directory-Authentifizierung trotzdem verwenden
ltEnvironment
name=webLoginUseActiveDirectoryAuthentication
value=false
type=javalangBoolean
override=true
gt
ldquoldapDaysBeforeExpirationNotificationrdquo
Die Passwort-Aumlnderung im Active-Directory uumlber die Browser-Oberflaumlche ist in der ersten Version noch nicht implementiert der Parameter wird bislang nicht ausgewertet
ltEnvironment
name=ldapDaysBeforeExpirationNotification
value=14
type=javalangInteger
override=true
gt
2514 Statement-Protokollierung in BALVI iP
Diese Option aktiviert die Lese- und Aumlnderungsprotokollierung fuumlr BALVI iP Standard ist bdquofalseldquo und wird fuumlr alle Kunden empfohlen solange keine speziellen Datenbank-Jobs eingerichtet wurden welche zeitgesteuert die Protokolleintraumlge wieder loumlschen Fuumlr Bayern wurde ein spezielles Konzept zur Leseprotokollierung entworfen Wenn Sie mehr daruumlber erfahren moumlchten kontaktieren Sie bitte die BALVI GmbH
ltEnvironment
name=enableSqlStatementMonitoring
value=true
type=javalangBoolean
override=true
gt
Beachten Sie dass diese Option massive INSERT-Statements in BALVI iP in die Tabelle VIS_D92 ausfuumlhrt Jedes abgesetzte SQL-Statement wird dabei vollstaumlndig protokolliert Dieses erzeugt eine sehr hohe INSERT-Last und in der Folge auch erhoumlhte Redolog-Switches und COMMIT-Transaktionen
Optional Aktivieren der INSERT + APPEND - Logik
Beachten Sie bitte die Hinweise von Oracle zum Hint + APPEND
Release Notes BALVI Schnittstellenserver Seite 23 von 37
Wenn Sie dieses Verhalten aktivieren moumlchten ergaumlnzen Sie bitte den folgenden Environment-Parameter
ltEnvironment
name=statementMonitoringactivateAppendMode
value=true
type=javalangBoolean
override=true
gt
2515 Einstellungen fuumlr BALVI mobil XT (bzw den bdquopartitionedExportldquo)
Diese Logik des FIFO-Buffers wurde so konzipiert dass dem Rechenzentrum diverse Einstellmoumlglichkeiten uumlber die Datei bdquocontextxmlldquo zur Verfuumlgung stehen um die Steuerung des FIFO-Puffers zu beeinflussen
Schematische Darstellung des FIFO-Puffers
Das ermoumlglicht es z B dem BALVI mobil XT Client (14 oder houmlher) den aktiven Block abzuholen und dies beim Fehler bis zu 10-mal zu wiederholen Sobald der Block [001] erfolgreich beim Client angekommen ist und dieser den naumlchsten Block anfragt wird der Block [001] verworfen wird Der Server fuumlllt dann im Hintergrund den frei gewordenen Block wieder waumlhrend der Client den Block [002] abholt
Die Groumlszlige und Anzahl der vorgecachten Bloumlcke kann uumlber die folgenden Einstellungen in der Datei bdquocontextxmlldquo definiert werden
ltEnvironment
name=partitionedExportmaxBufferedPartitions
value=3 type=javalangInteger override=true
gt
ltEnvironment
name=partitionedExportpartitionSize
value=256000 type=javalangInteger override=true
gt
Die Einstellung partitionedExportmaxBufferedPartitions ist dabei die Anzahl der vorgecachten Bloumlcke mindestens muss 2 angegeben werden Der Puffercache wird ausschlieszliglich im RAM der JVM aufgebaut es wird folglich mehr Arbeitsspeicher verwendet Dieser Arbeitsspeicher muss je gleichzeitiger Session auf dem Server bereitgestellt werden die Default-Einstellung mit 3 Partitionen a 256 KB + dem aktiven Puffer erfordern 1 MB RAM je aktiven Anwender
Aktiv
er
Puffe
r
[001] Vorg
ecac
hter
Bl
ock
[002] Vorg
ecac
hter
Bl
ock
[003]
Aktiv
er P
uffe
r
[002] Vorg
ecac
hter
Bl
ock
[003] Vorg
ecac
hter
Bl
ock
[leer]
Release Notes BALVI Schnittstellenserver Seite 24 von 37
Gleichzeitig wurde die Moumlglichkeit geschaffen dass die maximale Anzahl an gleichzeitigen Exporten durch das Rechenzentrum eingeschraumlnkt werden kann um einem OutOfMemory-Fehler vorzubeugen Die Einstellung
ltEnvironment
name=partitionedExportmaxConcurrentExports
value=10 type=javalangInteger override=true
gt
muss entsprechend der zu erwartenden gleichzeitigen Zugriffe konzipiert werden ansonsten wird der Server einen Verbindungsversuch durch die Clients ablehnen
Beachten Sie dass die folgenden Einstellungen partitionedExportmaxBufferedPartitions partitionedExportmaxConcurrentExports und partitionedExportpartitionSize gemeinsam als Rechenbasis fuumlr den RAM-Bedarf des Webservers herangezogen werden muumlssen
Folgende Faustformel sollte fuumlr die Einrichtung verwendet werden
Min 256 MB (Serverbasis) + (11 partitionedExportmaxConcurrentExports partitionedExportmaxBufferedPartitions partitionedExportpartitionSize)
Beispiel 50 gleichzeitige Anwender Blockgroumlszlige 256 KB 4 Partitionen
256 MB + (11 50 256 4) KB = 312 MB fuumlr die JVM
Empf 512 MB (Serverbasis) + (12 partitionedExportmaxConcurrentExports partitionedExportmaxBufferedPartitions partitionedExportpartitionSize)
Beispiel 50 gleichzeitige Anwender Blockgroumlszlige 256 KB 4 Partitionen
512 MB + (12 50 256 4) KB = 572 MB fuumlr die JVM
partitionedExportmaxConcurrentExports
Bestimmt die Anzahl der maximalen Export Tasks (Threads) die fuumlr partitionierte Exporte bereitgestellt werden Wenn die Anzahl uumlberschritten wird wird die entsprechende Exportanfrage abgewiesen und der Client muss zu einem spaumlteren Zeitpunkt erneut anfragen Stellen Sie diesen Wert entsprechend der zu erwartenden Benutzeranzahl ein bei 50 Anwendern also 50
Exporte oumlffnen auf der Datenbank entsprechend zur Ausfuumlhrungszeit min einen Cursor ggf fuumlr rekursive Unterabfragen kurzfristig sogar mehr Die hier eingestellte Anzahl muss mit der Anzahl von maxActive korrelieren
ltEnvironment
name=partitionedExportmaxConcurrentExports
value=10 type=javalangInteger override=true
gt
partitionedExportmaxBufferedPartitions
Bestimmt die Anzahl der Datenbloumlcke (Partitionen) die vom Server bei Abruf eines Exportes gepuffert werden Die seit Version 24 eingefuumlhrte FIFO-Puffer-Logik ermoumlglicht dass der Server schon die Ergebnisse vorpuffert so dass der Client weniger Wartezeiten bei der Anfrage nach Daten hat Diese
Release Notes BALVI Schnittstellenserver Seite 25 von 37
Puffer-Logik unterteilt den Exportdatenstrom (je Export) in mehre Bloumlcke Der Client kann nun den letzten Block neu anfordern oder den naumlchsten Block wenn der letzte Block erfolgreich verarbeitet wurde Wie viele naumlchste Bloumlcke durch den Server bereit gestellt werden entscheidet diese Einstellung Sobald kein naumlchster Block mehr bereit gestellt werden muss wird der Datenbank-Cursor geschlossen eine Erhoumlhung kann also zu einer Entlastung der aktiven DB-Verbindungen fuumlhren erhoumlht jedoch den Bedarf an RAM des Servers
Der von BALVI voreingestellte Wert ist 3
ltEnvironment
name=partitionedExportmaxBufferedPartitions
value=3 type=javalangInteger override=true
gt
partitionedExportpartitionSizeldquo
Die Groumlszlige der Datenbloumlcke (Partitionen) die an den Client uumlbermittelt werden in Bytes Wenn Sie diesen Wert zu niedrig einstellen reduziert sich die Effizienz des Caches da der Client mehr Datenbloumlcke hintereinander abrufen muss Waumlhlen Sie einen zu groszligen Wert wird die neu zu uumlbertragende Datenmenge im Fall eines Fehlers houmlher
Der von BALVI voreingestellte Wert ist 256000 (256 KB)
ltEnvironment
name=partitionedExportpartitionSize
value=256000 type=javalangInteger override=true
gt
exportTokensmaxTokenCount
Maximale Anzahl der gleichzeitig vergebenen Token die vom Server gecached werden Jede Sitzung welche einen Export durchfuumlhrt erhaumllt einen Session-Token
Wenn eine Sitzung laumlngere Zeit nicht verwendet wurde wird dieser Session-Token wieder entfernt Wenn Sie den Wert zu niedrig einstellen fuumlhrt das zu einer generellen Session-Begrenzung auch fuumlr den nicht partitionierten Export-Modus welcher ab Version 21 verfuumlgbar ist
Ist die Anzahl der Tokens houmlher als die Datenbankeinstellung maxActive kann es vorkommen dass zwar eine Session gestartet werden kann jedoch kein Datenexport zustande kommt
Der von BALVI voreingestellte Wert ist 2000
ltEnvironment
name=exportTokensmaxTokenCount
value=20 type=javalangInteger override=true
gt
exportTokenstokenExpirationInSeconds
Zeit in Sekunden die verstreichen muss bis ein Token unguumlltig wird falls darauf kein Zugriff mehr erfolgt Nach einem erfolgreichen Export wird der Token automatisch geschlossen diese Option ist fuumlr den Abbruchfall vorgesehen Der von BALVI voreingestellte Wert ist 180 (180 s = 3 min)
Release Notes BALVI Schnittstellenserver Seite 26 von 37
ltEnvironment
name=exportTokenstokenExpirationInSeconds
value=180 type=javalangInteger override=true
gt
exportTokenstokenDisposalInSeconds
Zeit in Sekunden die verstreichen muss bis ein Token das erfolgreich abgearbeitet wurde aus dem Cache geloumlscht wird Um sicher zu stellen dass der letzte Exportblock noch erfolgreich abgerufen werden kann bleibt der Token auch nach Fertigmeldung des Clients noch N Sek guumlltig
Der von BALVI voreingestellte Wert ist 60 (60 s = 1 min)
ltEnvironment
name=exportTokenstokenDisposalInSeconds
value=60 type=javalangInteger override=true
gt
2516 Job-Verwaltung fuumlr den BSS konfigurieren Aktivierung der Jobverwaltung
Bis zur Version 28 des BSS gab es den Parameter bdquoavailableServicesldquo Dieser konnte bei Bedarf aktiviert werden wenn die Jobs benoumltigt wurden
Mit Version 30 ist die Einstellung bdquoavailableServicesldquo zu entfernen und kann durch den neuen optionalen Parameter bdquoisJobServiceEnabledldquo in der Datei bdquocontextxmlldquo ersetzt werden
lt-- Neue Parameter zur Aktivierung des Job Service Ersatz fuumlr availableServices --gt
ltEnvironment
name=isJobServiceEnabled
value=true
type=javalangBoolean
override=true
gt
Ab BSS 30 wird die Jobs-Engine standardmaumlszligig aktiviert Sollte die Jobs-Engine nicht benoumltigt werden muss bdquovalueldquo der Wert bdquofalseldquo zugewiesen werden Wird bdquoisJobServiceEnabledldquo nicht eingefuumlgt sind die Jobs trotzdem standardmaumlszligig aktiv
Nach dem Neustart des Servers und erneutem Einloggen erscheint nun zusaumltzlich der Menuumlpunkt bdquoJobsldquo
bdquopasswordKeyldquo fuumlr Jobs
In der Job-Logik wird ein von BALVI definierter Standard-Schluumlssel fuumlr die Ablagen von schuumltzenswerten Daten z B Passwoumlrtern verwendet Diese Einstellung ermoumlglicht den BALVI-Standard zu uumlberschreiben Wenn Sie diese Einstellung aumlndern muumlssen jedoch alle bislang verschluumlsselten Job-Parameter neu verschluumlsselt werden
ltEnvironment
name=javacompenvjobspasswordKey
value=MeinHochsicheresNeuesPasswort
type=javalangString
Release Notes BALVI Schnittstellenserver Seite 27 von 37
override=true
gt
bdquoJob ID enableddisabledldquo (Deprecated ersetzt ab 28 durch das bdquoBindenldquo von Jobs)
Sondereinstellungen fuumlr die Job-Verwaltung Da alle Jobs in einer Datenbank administriert werden jedoch ggf verteilt auf mehreren Tomcat-Servern ausgefuumlhrt werden sollen besteht hier die Option Jobs fuumlr die aktuelle Tomcat-Instanz separat zu deaktivieren
Die Einstellung ID koumlnnte z B folgendermaszligen aussehen javacompenvjobsC0DB58D8D52C4BBC966D1DC788A4EF8Benabled
Fuumlr weitere Fragen zu dieser Einstellung kontaktieren Sie bitte die BALVI GmbH
ltEnvironment
name=javacompenvjobsIDenabled
value=false
type=javalangBoolean
override=true
gt
2517 Weitere optionale Parameter
Es ist fuumlr diverse einzelne Schnittstellen ggf erforderlich Einstellungen in der Datei bdquocontextxmlldquo zu ergaumlnzen Hinweise zu diesen Parametern sind dann in dem der Schnittstelle beiliegenden Dokument enthalten Das gilt z B fuumlr die Schnittstelle bdquoXGewerbeanzeigenldquo
26 Logging mit logback Das Logging wurde komplett uumlberarbeitet Statt bdquoLog4Jldquo wird jetzt bdquologbackldquo4 benutzt Ab BSS 30 ist es zwingend notwendig die Einstellung vorzunehmen um das Logging der Anwendung zu steuern
Migration Ergaumlnzen Sie die neue Einstellung bdquologgingconfigldquo
lt-- Neue Paramter zur Angabe der Logback Config Ersatz fuumlr log4jConfigLocation --gt
ltEnvironment
name=loggingconfig
value=$catalinabaseconflogback-bssxml
type=javalangString
override=true
gt
Nach wie vor steht es Ihnen frei die Logging-Konfiguration eigenstaumlndig anzupassen
Wenn Sie jedoch dieselbe WAR in einer Tomcat-Instanz unter mehreren Context-Namen betreiben wuumlrden beide dieselbe Logging-Konfiguration verwenden so dass alle Protokolleintraumlge in einer Log-Datei aus
4 httplogbackqoschmanualappendershtml
Release Notes BALVI Schnittstellenserver Seite 28 von 37
mehreren Webanwendungen generiert werden Aumlndern Sie den Namen der Logging-Konfiguration entsprechend ab um fuumlr jede Anwendung eine spezifische Logging-Einstellung vornehmen zu koumlnnen
27 Tocmat Optional Suche im bdquoKlassenpfadldquo um den
Ordner bdquoconfldquo erweitern Die Suche nach Dateien uumlber bdquoclasspathldquo setzt voraus dass die Ordner- und Dateinamen im Apache Tomcat bekannt gegeben werden Der Klassenpfad kann in der Datei bdquocatalinapropertiesldquo angepasst werden Wenn Sie dort unter commonloader die folgenden Werte ergaumlnzen kann eine Datei auch im Ordner conf abgelegt werden damit Apache Tomcat diese findet Ansonsten muss die Datei im Ordner lib abgelegt werden
commonloader=$catalinabaseconf$catalinahomeconf
3 Die neue Browser-Oberflaumlche Der BALVI Schnittstellenserver hat seit Version 25 neben der Protokollierung auch die Moumlglichkeit Job-Konfigurationen zu pflegen Der Login ist nur fuumlr einen in BALVI iP eingetragenen ADMIN (z B Benutzer bdquoSYSTEMADMINldquo) mit dem in BALVI iP hinterlegten Passwort moumlglich Zur Anmeldung muss immer [SYSTEMBenutzername] im Feld Benutzer angegeben werden ansonsten schlaumlgt die Anmeldung fehl Bitte achten Sie darauf dass der bdquoldquo (Slash) und nicht der bdquoldquo (Backslash) verwendet werden muss
31 Server-Protokoll Um das Server-Protokoll anzuzeigen waumlhlen Sie den entsprechenden Menuumlpunkt Dort haben Sie seit BSS 26 die Moumlglichkeit uumlber alle Spalten der Protokolle nach Informationen zu suchen
Seit BSS 31 gibt es die Moumlglichkeit Verfahren in bdquoKopfsaumltzeldquo und bdquoDetailsaumltzeldquo zu unterteilen Wurde das Verfahren entsprechend konfiguriert (wie z B bei der Schnittstelle bdquoXGewerbeanzeigenldquo) dann wird im Protokoll-Kopfsatz nur der Start und das Ende der Ausfuumlhrung in der Liste angezeigt Erst bei einem Klick auf bdquoInformationenldquo wird die Liste aller Detailsaumltze angezeigt die im Durchlauf erzeugt wurden
Release Notes BALVI Schnittstellenserver Seite 29 von 37
Verfahren
Die Liste der verfuumlgbaren Verfahren die bei Ihnen im System installiert sind ZB
BEFUNDEhellip Schnittstelle Befunde LM FM oder TS
PROBEhellip Schnittstelle zum Export von Proben an Labore ebenfalls Spezifisch fuumlr einzelne Fachbereiche
MOBILXT Protokolle der BALVI Mobil XT Synchronisation
WEB Allgemeine nicht spezifizierte Protokolle hierunter ist bislang auch die eFi-Protokollierung zu finden
WEB_I0802 Protokolle zur Schnittstelle BALVI iP LIMS (Lebensmittelproben)
XGEWERBE Schnittstelle XGewerbeanzeigen
Klicken Sie auf die Schaltflaumlche so besteht bei den neuen Protokolldatensaumltzen die Moumlglichkeit Detail-Informationen zum Protokollsatz zu erhalten
Release Notes BALVI Schnittstellenserver Seite 30 von 37
Seit BSS 30x ist die Anzeige der Protokolle ebenfalls farblich abgesetzt so dass Protokolleintraumlge mit Fehlern hellrot und Warnungen hellgelb hinterlegt werden
32 Jobs Mit einem Klick auf den Menuumlpunkt Jobs rufen Sie die Oberflaumlche fuumlr die Job-Konfiguration auf Daraufhin werden alle Jobs aufgelistet die fuumlr den BSS freigegeben sind Hier koumlnnen Sie Einstellungen an den Jobs vornehmen und die Jobs aktivieren bzw deaktivieren Die Beschreibungen bzw Einstellungsmoumlglichkeiten fuumlr den jeweiligen SST-Job sind nicht Bestandteil dieser Dokumentation
33 Log-Ausgaben Uumlber den Menuumlpunkt Log-Ausgaben koumlnnen Sie die Ausgabe der Protokolleintraumlge in Echtzeit beobachten
Release Notes BALVI Schnittstellenserver Seite 31 von 37
Starten Sie die Echtzeit-Protokollierung indem Sie auf die Schaltflaumlche mit dem Symbol bdquoPlayldquo (Dreieck) klicken unterbrechen Sie die Ausgabe indem Sie die auf Schaltflaumlche mit dem Symbol bdquoPauseldquo (zwei Balken) klicken
Klicken Sie auf die Schaltflaumlche bdquoAktualisierenldquo (zwei Pfeile) um die neuesten Protokolleintraumlge angezeigt zu bekommen
Klicken Sie auf das Symbol mit dem Papierkorb um die letzten Protokollmeldungen in der Anzeige zu loumlschen
Die Daten in den Protokolldateien auf der Festplatte des Servers sind davon nicht betroffen
Uumlber das Symbol bdquoLogging anpassenldquo (Schraubenschluumlssel) koumlnnen Sie die Ausgabe der Daten im Echtzeitfenster und in den Protokolldateien aumlndern jedoch ist diese Einstellung nur temporaumlr Die Standardeinstellungen koumlnnen ausschlieszliglich uumlber die Anpassung der Datei bdquologback-bssxmlldquo im Konfigurationsverzeichnis des Servers selbst geaumlndert werden
Release Notes BALVI Schnittstellenserver Seite 32 von 37
In der Logging-Parameter Konfiguration koumlnnen Sie verschiedene Parameter einstellen und uumlber die Schaltflaumlche bdquoAnwendenldquo dann sofort im Echtzeitprotokoll sehen Welche Einstellungen moumlglich sind erfahren Sie wenn es eine akute Fehlersituation gibt die detailliertere Ausgaben im Protokoll erfordert
Warnung Wenn Sie den Log-Level fuumlr ROOT oder eine andere Klasse auf TRACE einstellen werden sehr viele Protokollausgaben generiert die auch dazu fuumlhren koumlnnen dass der Server sehr langsam wird oder die Festplatte des Servers zulaumluft wenn fuumlr das Logging kein Dateilimit konfiguriert wurde
34 LogoutAbmeldung vom System Zum Abmelden waumlhlen Sie oben rechts das Kontextmenuuml
35 Cache loumlschen Der Cache wird in der Regel automatisch geloumlscht Wenn Sie jedoch gerade in BALVI iP eine Aumlnderung an den Schnittstellen eingespielt haben und moumlchten dass diese sofort wirksam wird kann die Funktion bdquoCache loumlschenldquo dazu verwendet werden dass der BALVI Schnittstellenserver die Einstellungen bei der naumlchsten Anfrage neu einliest
Release Notes BALVI Schnittstellenserver Seite 33 von 37
Release Notes BALVI Schnittstellenserver Seite 34 von 37
4 Einrichtung in BALVI iP Um die Verfahren fuumlr den BALVI Schnittstellenserver fuumlr Anwender freizuschalten wird das Objekt bdquoSystemeinstellungenldquo oder bdquoMandanten- und Benutzereinstellungenldquo verwendet Die Anpassung ist je Verfahren moumlglich so kann in BALVI iP fuumlr den Zugriff durch den BALVI Schnittstellenserver ein Benutzer bdquoAldquo am Verfahren bdquoMobilldquo berechtigt werden ein Benutzer bdquoBldquo nur am Verfahren bdquoSLA_FLESHldquo usw Die Logik ist jedoch einheitlich Je Verfahren wird durch BALVI eine Verfahrensgruppe mit dem Verfahrensnamen angelegt und mit den entsprechenden Einstellungen vorkonfiguriert welche durch das Verfahren erforderlich sind Dabei kann die Komplexitaumlt der Einstellungen variieren wie z B an den zu Version 23 verfuumlgbaren Verfahren bdquoMobilldquo und bdquoSLA_Fleshldquo ersichtlich wird
Im Verfahren BALVI Mobil sind diverse Anpassungen moumlglich welche je Bundesland oder eingesetzter Import- und Export-Variante durch den BALVI Schnittstellenserver bei der Bearbeitung von Anfragen gepruumlft werden siehe Punkt 3 Abb Mobil-Einstellung in BALVI iP
Abb Mobil-Einstellung in BALVI iP
Alle Verfahren verwenden jedoch die regulaumlre Benutzerverwaltung von BALVI iP Ein Benutzer ohne Passwort gilt fuumlr BALVI iP als gesperrt was fuumlr das Login bedeutet dass der Anwender sich nur uumlber die Active-Directory-Authentifizierung anmelden kann Ist das nicht moumlglich (bzw nicht konfiguriert) kann der Anwender sich weder in BALVI iP noch uumlber die Webservice-Schnittstelle authentifizieren
Fuumlr Dienste-Schnittstellen welche keine persoumlnliche Authentifizierung durch einen Anwender erfordern wird empfohlen einen separaten Benutzer in der Benutzerverwaltung anzulegen und ein sicheres Kennwort zu vergeben Das Anlegen von zusaumltzlichen Benutzern gilt nicht fuumlr BALVI mobil XT da beim Holen und Uumlbermitteln von Daten jeder Benutzer auch ein fachlich konfigurierter Anwender innerhalb von BALVI iP ist und die Anwendungsoberflaumlche ebenfalls zur Erfassung von Daten verwendet
Unter Punkt 2 der Abb Mobil-Einstellung in BALVI iP wird ein modales Fenster geoumlffnet (Abb BALVI mobil Benutzerverwaltung) Innerhalb dieses modalen Fensters werden mandantenweise die Benutzer fuumlr BALVI
Release Notes BALVI Schnittstellenserver Seite 35 von 37
mobil und den jeweiligen Fachbereich festgelegt Dabei ist es wichtig dass man die Haken bdquoAktiv fuumlr hellipldquo bei bdquohellip mobilldquo und bei einem Fachbereich (bdquohellip LMldquo bdquohellip FMldquo usw) setzt weil sonst uumlber den BALVI Schnittstellenserver keine Kommunikation mit BALVI iP moumlglich ist
Abb BALVI mobil Benutzerverwaltung
Alternativ zur Passwort-Authentifizierung wird wie beschrieben auch die Active-Directory-Authentifizierung angeboten Dazu muss der BALVI iP-Anwender uumlber die Schaltflaumlche bdquoDomaumlnen-Benutzer zuordnenldquo mit dem Active Directory verknuumlpft werden
Nur wenn die Active-Directory-Konfigurationen in BALVI iP und im BALVI Schnittstellenserver auf dieselbe Domaumlne verweisen sind die Domaumlnen-Zuordnung und die Active-Directory-Authentifizierung (z B uumlber BALVI mobil XT) moumlglich
Release Notes BALVI Schnittstellenserver Seite 36 von 37
5 Bekannte Probleme und Loumlsungen
51 ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner Bei der Job-Bearbeitung tritt folgender Fehler auf ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner
Behebung
Fuumlhren Sie das beiliegende IP-Patch (UPDATEexe) aus bevor Sie das WAR austauschen
52 Server startet nicht Sie finden folgende Zeilen im Protokoll (catalinaout oder bsslog)
ERROR [localhost-startStop-1] [IdentityServiceImpl] serverID must not be empty
ERROR [localhost-startStop-1] [ContextLoader] Context initialization failed
Behebung
Setzen Sie die Umgebungsvariable ldquoserverIDrdquo in der Datei bdquocontextxmlldquo
53 ORA-00942 table or view does not exist In vielen Faumlllen wird der Fehler ldquoTabelle oder View nicht vorhandenrdquo ausgeworfen (Java-Protokoll im Ordner logs von Apache Tomcat) wenn eine neue Schnittstelle eingerichtet oder ein neues BALVI iP Release bzw Update eingespielt wurde ohne anschlieszligend das aktuelle GRANT-Skript auszufuumlhren
Behebung
Fuumlhren Sie das GRANT-Skript erneut aus
54 ORA-0406x bdquoBestehender Paketstatus wurde aufgehobenldquo
ORA-04061 Bestehender Status von package body ABCXYZ wurde annulliert
ORA-04065 Ausfuumlhrung nicht erfolgreich package body ABCXYZ wurde geaumlndert oder geloumlscht
Release Notes BALVI Schnittstellenserver Seite 37 von 37
Der Fehler tritt haumlufig ein nachdem die UPDATEexe ausgefuumlhrt und in der Ausfuumlhrungsliste ein Package aktualisiert wurde Oracle merkt sich je User-Session bestimmte Werte im Package wenn der Anwender es verwendet hat Durch einen bdquoCREATE OR REPLACE PACKAGEldquo-Befehl kann dieser Status temporaumlr aufgehoben werden Normalerweise tritt dieser Fehler nach dem Update genau einmal in jeder aktiven Session auf wenn der BSS nicht neu gestartet wird
Behebung
Starten Sie nach jedem Update den BSS neu um alle laufenden Sessions zu beenden
55 Jobs sind nicht ausfuumlhrbar
1 Ein Job wird mit dem Status bdquoNicht unterstuumltztldquo angezeigt wenn fuumlr seine Ausfuumlhrung eine houmlhere Version des BSS erforderlich ist
2 Nach dem Klonen der Datenbank von der Produktions- auf die Testumgebung erhalten alle Jobs automatisch den Status bdquoDeaktiviertldquo wenn die bdquoserverIDldquo nicht identisch ist
Beide Statusaumlnderungen sind gewollt Damit soll verhindert werden dass Jobs nach einem Serverneustart oder nach einem Update automatisch starten und dabei Fehler verursachen
Um Jobs mit dem Status bdquoNicht unterstuumltztldquo nutzen und konfigurieren zu koumlnnen ist es erforderlich den BALVI Schnittstellenserver zu aktualisieren
Deaktivierte Jobs koumlnnen Sie aktivieren indem Sie den jeweiligen Job an den aktuellen Server binden und den Haken bei bdquoAktivldquo setzen
Release Notes BALVI Schnittstellenserver Seite 8 von 37
ID fuumlr den Server
Diese muss pro Schnittstellenserver eindeutig sein
Eine Aumlnderung dieser ID fuumlhrt sofort dazu dass alle
eingerichteten Server-Jobs inaktiv werden und neu mit
der Instanz gekoppelt werden muumlssen um wieder aktiviert
werden zu koumlnnen
Als value kann ein Text der max Laumlnge von 32 Zeichen
vergeben werden z B ProductionEnvNode1 fuumlr die Produktion
und TestEnvNode1 fuumlr die Testumgebung
--gt
ltEnvironment
name=serverID
value=ProductionEnvNode1
type=javalangString
override=true
gt
152 Optional ist nun eine Namensvergabe moumlglich Auf Wunsch mehrerer Kunden wurde die Option geschaffen jedem Server zusaumltzlich einen kundenspezifischen bdquoTitelldquo zu geben um die Server besser unterscheiden zu koumlnnen
lt--
Visueller Name des Servers in der Oberflaumlche
(Optional)
--gt
ltEnvironment
name=serverName
value=TIERZ Tomcat 8 Java 8 mit BALVI_TIERZXGEWETLBTR_BSS
type=javalangString
override=true
gt
Der hier angegebene Text wird in der Kopfzeile zwischen den eckigen Klammern ausgegeben
Release Notes BALVI Schnittstellenserver Seite 9 von 37
2 Einrichtungshinweise
21 Allgemeine Hinweise zum Betrieb
211 Kompatibilitaumlt zu Apache Tomcat und Java SE Der BALVI Schnittstellenserver wurde getestet und freigegeben fuumlr Apache Tomcat 8 (ab Version 8030 oder neuer) Zudem wurde die aktuellste (letzte offizielle) Version von Java SE 8 getestet und kann verwendet werden (Java SE 8u40 und neuer)
Installieren Sie stets die aktuellsten Sicherheitsupdates fuumlr Java SE 8 Beachten Sie dabei jedoch dass nicht die Aktualisierung auf eine andere Java-Version (z B Java 9) gemeint ist
Freigegebene Major-Versionen werden explizit von BALVI benannt Falls Sie beabsichtigen die Major-Version zu aumlndern pruumlfen Sie bitte die aktuellen Release Notes oder kontaktieren die BALVI Kundenbetreuung
212 Oracle Java SE Lizenzierung Java SE beinhaltet auch kostenpflichtige Funktionen fuumlr deren Nutzung Oracle Lizenzgebuumlhren fordert wenn sie bei der Entwicklung eingesetzt werden Die von BALVI gelieferte Software ist frei von den kommerziellen Teilen der Oracle Java SE nutzbar Fuumlr den Einsatz von Oracle Java SE (einschlieszliglich JDK und JRE) fallen im Rahmen der Nutzung der BALVI Software keine Lizenzkosten an
Trotzdem werden wir parallel pruumlfen ob technische Probleme bei der Umstellung auf das OpenJDK zu erkennen sind Ein einfacher Funktionstest hat im BSS 3x noch keine technischen Probleme gezeigt als wir die Laufzeitumgebung auf das OpenJDK 8U111 AMD64 (Debian) umgestellt haben Bitte haben Sie Verstaumlndnis dafuumlr dass wir keine Funktionstests fuumlr jedes Linux-Derivat durchfuumlhren koumlnnen und dass es offiziell keine Version des OpenJDK fuumlr Windows Betriebssysteme gibt
213 Einsatz von TLSSSL BALVI hat keine spezifischen Anforderungen an die Konfiguration von SSL bzw TLS Der Einsatz von TLS 12 gem der Richtlinie TR-02102-2 vom BSI ist moumlglich wenn Sie sich an die von Apache Tomcat herausgegebene Dokumentation halten Es sind keine Anpassungen des Schnittstellenservers erforderlich Daher gehen wir davon aus dass auch der BSS 28x oder aumllter in einem Apache Tomcat mit TLS 12 betrieben werden kann
Das gilt jedoch nicht fuumlr alle Clients die den Tomcat-Server ansprechen moumlchten So ist z B erst ab BALVI mobil 191958 sichergestellt dass die Protokolle TLS 11 und TLS 12 programmseitig aktiviert sind Fuumlr Details zu diesem Problem wurde ein separates Rundschreiben per E-Mail versendet
Release Notes BALVI Schnittstellenserver Seite 10 von 37
214 Nutzung von Java-Proxyeinstellungen Der BALVI Schnittstellenserver verwendet fuumlr ausgehende Verbindungen die Java-Net Einstellungen welche in der Java-Dokumentation1 beschrieben sind Falls Sie Jobs einsetzen welche ausgehenden Zugriff auf Adressen im Internet benoumltigen kann es passieren dass Sie z B eine bdquojavanetUnknownHostExceptionldquo im Protokoll finden dann muumlssen Sie ihre Proxy-Umgebung in den Java-Umgebungseinstellungen ergaumlnzen
Die folgenden Parameter sollten daher in Ihrer Umgebung gesetzt werden wenn der Zugriff auf das Internet nur uumlber einen Proxy moumlglich ist
-DproxySet=true
-DproxyHost=10111213
-DproxyPort=8888
-DhttpnonProxyHosts=domainorg|localhost|10
Starten Sie nach Aumlnderung der Einstellungen den Server neu damit die Einstellungen wirksam werden
2141 Proxy-Einstellung unter Windows (Tomcat-Dienst)
Verwenden Sie das Dienste-Konfigurationsprogramm (z B tomcat7wexe) und ergaumlnzen Sie die fehlenden Einstellungen
2142 Proxy-Einstellung unter Linux
In Linux wird in der Konfigurationsdatei (z B conftomcat7conf) die Variable bdquo$JAVA_OPTSldquo entsprechend erweitert und die Werte uumlbergeben Beachten Sie dabei dass die Variablen von Linux (bzw der Bash) gelesen werden Daher muss das bdquoPipeldquo-Zeichen bdquo|ldquo mit bdquoldquo maskiert werden ansonsten erhalten Sie bei der Verarbeitung der Umgebungsvariable bdquohttpnonProxyHostsldquo Fehlermeldungen in der Linux -Konsole welche dazu fuumlhren dass Java nicht korrekt konfiguriert werden kann
JAVA_OPTS=$JAVA_OPTS -DproxySet=true -DproxyHost=10111213 -DproxyPort=8888
JAVA_OPTS=$JAVA_OPTS -DhttpnonProxyHosts=domainorg|localhost|10
1 httpdocsoraclecomjavase8docstechnotesguidesnetpropertieshtml
Release Notes BALVI Schnittstellenserver Seite 11 von 37
215 Spracheinstellung Deutsch Es wurde festgestellt dass unter einigen Linux-Versionen die Spracheinstellung beim Starten des Apache Tomcat nicht auf eine deutsche Umgebung verweist Dieses kann technische Probleme verursachen Unter Linux sollte die Einstellung (Umgebungsvariable) entsprechend auf LANG=de_DEUTF-8 eingestellt sein
216 Datenbankverbindung Wenn Sie eine Firewall zwischen dem Oracle-Server und dem Database Connection Pool (DBCP) verwenden sollte unbedingt die bdquovalidationQueryldquo in der DBCP-Konfiguration aktiviert werden damit die Anwendung schneller freie Connections aus dem Pool erhalten kann Die Dokumentation zu den Einstellmoumlglichkeiten ist in der beiliegenden Contextxml ergaumlnzt worden
Bitte beachten Sie dass dringende empfohlen wird die bdquoFactoryldquo auf orgapachetomcatjdbcpoolDataSourceFactory anzupassen falls sie noch auf bdquoorgapachecommonsdbcpBasicDataSourceFactoryldquo eingestellt ist
217 Probleme beim Anlegen von LOB-Objekten Der BALVI Schnittstellen-Server erfordert die JDBC-Spezifikation DBCP V4 welche durch die Factory bdquoorgapachetomcatjdbcldquo ab Tomcat 7 automatisch bereitgestellt wird
Wenn die Pooling-Komponente oder der Oracle-Treiber nicht JDBC4-Kompatibel sind gibt es beim Bearbeiten von LOB-Objekten in Java diverse Exceptions z B
Servletservice() for servlet soapws threw exception
javalangAbstractMethodError
orgapachecommonsdbcpPoolingDataSource$PoolGuardConnectionWrappercreateClob()LjavasqlClob
at debalvicoreauditspyConnectionSpycreateClob(ConnectionSpyjava511)
Ursache dieses Problems ist meistens dass noch nicht auf bdquoorgapachetomcatjdbcldquo umgestellt wurde
218 Umbenennung der gelieferten WAR-Datei Das im Paket von BALVI gelieferte WAR kann jederzeit umbenannt werden (z B als ROOTwar) ohne dass dabei spezielle Einstellungen in der Datei bdquocontextxmlldquo erforderlich sind
Beachten Sie dabei jedoch dass die zum WAR zugehoumlrige Datei bdquocontextxmlldquo im Apache Tomcat immer denselben Namen erhaumllt wie das WAR z B bdquocommserverwarldquo und bdquocommserverxmlldquo Der Name ist dabei ausschlaggebend fuumlr die Zugriffs-Adresse (Context) im Apache Tomcat selbst Die Benennung des WAR in bdquocommserverwarldquo wuumlrde folgendermaszligen aufzurufen sein httpserverportcommserver
219 Server-Schnittstellen Die Uumlberarbeitung bzw Erweiterung der Export- und Importschnittstellen welche uumlber den Schnittstellenserver bereitgestellt werden ist unabhaumlngig vom Schnittstellenserver selbst Die Schnittstellen sind daher nicht Bestandteile des Schnittstellenserver und werden je Verfahren separat
Release Notes BALVI Schnittstellenserver Seite 12 von 37
ausgeliefert Ggf ist es fuumlr unterschiedliche Schnittstellen erforderlich die Grant-Rechte zu aktualisieren (Vgl bdquoWann ist die Ausfuumlhrung des Grant-Skripts erforderlichldquo)
22 Kompatibilitaumltsliste Diverse Verfahren setzen eine Mindestversion des BALVI Schnittstellenservers voraus Die Schnittstellen sind jedoch so konzipiert dass eine Aktualisierung auf eine houmlhere Version des Servers ohne Anpassung an den vorhandenen Schnittstellen jederzeit moumlglich ist
Derzeit sind folgende Mindestanforderungen gegeben
1 BALVI mobil XT 170 oder houmlher setzt BSS 265 und BALVI iP 124x voraus
2 BALVI mobil XT 183 oder houmlher setzt BSS 281 und BALVI iP 124x voraus
3 BALVI mobil 2 (DM) setzt BSS 311 und BALVI iP 124x voraus
4 Die Schnittstelle eFI setzt BSS 251 und BALVI iP 122c voraus
5 Die Schnittstelle LIMS setzt BSS 265 voraus
6 Die Schnittstelle TSK (SN) setzt BSS 265 voraus
7 Die Schnittstelle xDomea (SN) setzt BSS 265 und Java 7 voraus
8 Die Schnittstelle XGewerbeanzeigen 11 setzt BSS 281 BALVI iP 124x Java 8 mit der bdquoJava
Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy2ldquo voraus
9 Die Schnittstelle XGewerbeanzeigen 12 (ab Paket 7 Ausbaustufe 3) setzt BSS 302 BALVI iP
124x Java 8 mit der bdquoJava Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policyldquo
voraus
10 Die Schnittstelle RioPP LM (NRW) setzt BSS 303 und die ETL-Konfiguration voraus
11 Die Schnittstellen zu BALVI iP2 (Fachmodule BTS LM ZDA Stand Juni 2017) setzen BSS 32x
voraus
2 httpwwworaclecomtechnetworkjavajavasedownloadsjce8-download-2133166html
Release Notes BALVI Schnittstellenserver Seite 13 von 37
23 Erforderliche Bibliotheken fuumlr Apache Tomcat Dateiname Funktion Quelle ojdbc6jar Oracle 11gR2 Clientpaket Oracle JDBC Client fuumlr Java
16 ersetzt die bisherige Version bdquoojdbc14jarldquo Die alte Library muss auf jeden Fall entfernt werden
httpwwworaclecomtechnetworkdatabaseenterprise-editionjdbc-112010-090769html
encrypted-datasource-110-alljar
Die Library muss auf jeden Fall entfernt werden Wird derzeit nicht weiter gepflegt da kein Interesse an der Funktionalitaumlt bestand
slf4j-api-1511jar slf4j-log4j12-1511jar log4jdbc4-12beta2jar
Entfaumlllt nicht mehr erforderlich Es wird empfohlen diese zu entfernen falls diese im LIB-Verzeichnis vorhanden sein sollten
commons-dbcp-14jar commons-pool-154jar
Entfaumlllt nicht mehr erforderlich Es wird empfohlen diese zu entfernen falls diese im LIB-Verzeichnis vorhanden sein sollten
Erwartet wird stattdessen ab Tomcat7 die mitgelieferte bdquotomcat-jdbcjarldquo
log4j-1217jar (oder houmlher)
Logging-Funktionalitaumlt Apache Log4j httploggingapacheorglog4j12downloadhtml
bcprov-jdk15on-157jar (oder houmlher)
BouncyCastle Security Provider fuumlr SSLAES hellip wird ab Version 27 im Ordner bdquolibldquo des Tomcat erwartet Sollte es aus Sicherheitsgruumlnden erwuumlnscht sein eine aktuellere Version einzusetzen ist dieses idR moumlglich
httpmvnrepositorycomartifactorgbouncycastlebcprov-jdk15on157
24 Datenbank-Installation Der BALVI Schnittstellenserver benoumltigt auszligerhalb des angebundenen BALVI iP keine eigenen Tabellen Die Web-Anwendung kann im einfachsten Fall direkt auf das Schema von BALVI iP zugreifen indem der Benutzer und das Passwort des BALVI iP-Schemas in der Datei bdquocontextxmlldquo eingetragen werden (nicht empfohlen)
Sollte dies aus Sicherheitsgruumlnden nicht erwuumlnscht sein (empfohlen vom BSI und von BALVI) finden Sie im Paket ein GRANT-Skript um Zugriffsrechte vom BALVI iP Schema fuumlr den Webservice-Schema-Benutzer einzurichten
Zwischen dem Schema von BALVI iP und jeder Web-Anwendung ist dann eine Trennung moumlglich um sicherzustellen dass der Datenbank-Benutzer welcher in der Tomcat-Konfiguration fuumlr die Web-Anwendung eingetragen wird geaumlndert oder geloumlscht werden kann ohne dass die Windows-Anwendung BALVI iP davon betroffen ist Zudem vergibt das von BALVI gelieferte Grant-Skript keine Rechte zum Loumlschen von Tabellenstrukturen oder Tabelleninhalten so dass der Webservice nur festgelegte Daten aumlndern oder lesen darf Es wird empfohlen je Web-Anwendung einen eigenen Datenbank-Benutzer zu vergeben wenn Sie ein BALVI iP mit mehreren Webservices verbinden wollen
Die Moumlglichkeiten im Uumlberblick
1) Sie betreiben den Webservice mit einem eigenstaumlndigen Oracle-Benutzer In diesem Fall muss das
Grant-Skript ausgefuumlhrt werden um den Webservice-Benutzer und den BALVI iP-Benutzer
miteinander zu koppeln
2) In der Tomcat-Konfiguration wird der Oracle-Benutzer eingetragen welcher auch der BALVI iP
Schemabesitzer ist und in der bdquobalviip_conninildquo hinterlegt ist (NICHT Empfohlen) Der Webservice
Release Notes BALVI Schnittstellenserver Seite 14 von 37
hat 100 Zugriffsrechte (auch Loumlsch- oder Aumlnderungsrechte am Schema) es wird kein Grant-
Skript benoumltigt
Wenn Sie die Konfiguration 2) waumlhlen moumlchten koumlnnen Sie die folgenden Unterkapitel uumlberspringen und in Kapitel 0 bzw fortsetzen
241 Erstinstallation Datenbank-Benutzer anlegen Wenn Sie den Webservice-Benutzer vom BALVI iP Schema trennen moumlchten muss durch die DB-Administration in der Oracle-Server-Instanz wo auch BALVI iP sein Schema besitzt ein Benutzer (ggf je Web-Anwendung) angelegt werden welcher folgende Rechte benoumltigt
CONNECT
ALTER SESSION
CREATE JOB
CREATE PROCEDURE
CREATE SESSION
CREATE TABLE
CREATE TRIGGER
CREATE TYPE
CREATE VIEW
CREATE SEQUENCE
CREATE SYNONYM
QUERY REWRITE
Der Default-Tablespace ist frei waumlhlbar Der Benutzer braucht das Recht QUOTA UNLIMITED auf den Tablespace von BALVI iP (Default BALVI_IP) Ein Beispiel-Create-Skript bdquooraCreate_WEB_Usersqlldquo liegt der Auslieferung bei
242 Rechte zuweisen Wenn der BALVI iP Schemabesitzer NICHT in der Tomcat-Umgebung eingetragen werden soll muss ein Oracle DBA das beiliegende GRANT-Skript bdquooraGrantIP_to_Websqlldquo ausfuumlhren um dem jeweiligen Webservice (in Tomcat verwendeten Oracle-Benutzer) die minimalen Rechte auf das Schema von BALVI iP zu gewaumlhren
Dieses Skript setzt voraus dass es von einem Oracle Administrator als bdquoUser SYSTEMldquo ausgefuumlhrt wird Lesen Sie die im Skript enthaltenen README-Kommentare und passen Sie die Benutzer (BALVI iP Schema) und (WEB-Schema) an
====================================================
DEKLARATIVER TEIL MUSS vom KUNDEN geaumlndert
bzw auf die korrekten SCHEMA-Namen angepasst
werden
Die USER-Namen muumlssen in Groszligbuchstaben
geschrieben sein sonst werden sie nicht
gefunden
====================================================
sUserBALVI_IP = BALVI_IP_SCHEMABESITZER
sUserBALVI_WEB = BALVI_WEB_SCHEMABESITZER
Release Notes BALVI Schnittstellenserver Seite 15 von 37
Neu ab Grant-Skript 158 ist die Umbenennung der Verfahrenszuordnung
Pruumlfen Sie dass die Einstellung fuumlr Ihr BundeslandVerfahren korrekt ist dort muss eine 1 fuumlr min ein Verfahren gesetzt sein Diese Einstellung befindet sich direkt unter den Schemabesitzer-Angaben
-- Verfahrensbezogene Konfiguration
-- Setzen Sie fuumlr das jeweilige Verfahren eine 1
-- BALVI Schnittstellenserver (BSS)
-- bis V266 auch BALVI Kommunikationsserver (BKS) genannt
-- generell fuumlr die meisten Verfahren guumlltig
-- Ab Version 57 entfaumlllt mit der Einfuumlhrung der
-- Schnittstelle XGewerbeanzeigen auch der separate Schalter
-- WS_BTR beide Verfahren wurden vereinheitlicht
WS_BSS = 1
Fuumlhren Sie das Skript nach der Anpassung als User SYSTEM aus um die Grants durchzufuumlhren Dieses wurde mit dem von ORACLE gelieferten Programm SQLPLUS (Command-Line) SQLPLUS Worksheet (GUI) und Oracle SQL-Developer getestet
Das Skript generiert fuumlr jedes Objekt ein SYNONYM fuumlr den WEB-USER so dass dieser auf die Objekte ohne Angabe des Owners des IP-Schemas zugreifen kann Pruumlfen Sie nach der Ausfuumlhrung dass die SYNONYMS vorhanden und VALID sind dieses kann ggf nicht der Fall sein Das Skript kann jederzeit erneut ausgefuumlhrt werden um die Grants neu zu erzeugen und bietet ebenfalls die Option alle Grants und Synonyme wieder zu entfernen Detaillierte Informationen zur Nutzung des Skripts sind als Kommentar-Block im Skript enthalten
Hinweis Die Versionsinformation ist unter den Kommentaren direkt im Skript zu finden
Zugriffsberechtigungen fuumlr Webanwendungen auf BALVI iP anlegen
===============================================================
Version 158
Guumlltig fuumlr BALVI iP 123 oder houmlher
Autor Frank Holler
SVN Revisionsinformationen
$Revision 479 $
$Date 2016-02-15 152755 +0100 (Mo 15 Feb 2016) $
================================================================
243 Wann ist die Ausfuumlhrung des Grant-Skripts erforderlich Durch das Strukturupdate von BALVI iP (z B 1240 auf 1241) werden veraltete Strukturen geloumlscht und ggf neue Views oder Tabellen angelegt Die Grant-Rechte geht dabei ggf verloren Daher ist die Ausfuumlhrung des Grant-Skripts immer dann erforderlich wenn sich die Datenbank-Struktur von BALVI iP veraumlndert
Zudem kann es fachliche Neuerungen geben welche im alten Grant-Skript nicht vorhanden sind Daher muss das Skript ggf auch ausgefuumlhrt werden wenn eine neue Schnittstelle im Schnittstellenserver bereitgestellt wurde Dieses betrifft z B auch die Bereitstellung von neuen Versionen von BALVI mobil XT
Release Notes BALVI Schnittstellenserver Seite 16 von 37
da auch dort mit einem fachlich erweiterten Client die Moumlglichkeit besteht dass neue Schnittstellen bereitgestellt und somit mehr Schreibrechte auf Tabellen benoumltigt werden
244 Welche Version des Grant-Skripts soll ich nehmen Wie der Schnittstellenserver sind auch die Grant-Skripte versioniert Neuere Versionen des Grant-Skriptes sind abwaumlrts-kompatibel und koumlnnen immer verwendet werden auch wenn in einer Schnittstellenbeschreibung eine aumlltere Version des Grant-Skriptes explizit benannt wurde
245 Kombination von mehreren Verfahren Wenn Sie zwei oder mehr Schnittstellen im BSS verwenden moumlchten ist es ggf erforderlich auch mehrere Verfahren auf aktiv (bdquo1ldquo) zu setzen
Im Beispiel nehmen wir an Sie moumlchten bdquoeFildquo und bdquoBALVI mobil XTldquo im Schnittstellenserver bereitstellen In der Beschreibung von bdquoeFildquo steht dass das Grant-Skript V36 erforderlich ist BALVI mobil XT 18 erfordert jedoch schon V56
Wenn Sie beide Verfahren betreiben ist im Grant-Skript (V56 oder houmlher) die Einstellung fuumlr beide Verfahren zu aktivieren
====================================================
DEKLARATIVER TEIL MUSS vom KUNDEN geaumlndert
bzw auf die korrekten SCHEMA-Namen angepasst
werden
Die USER-Namen muumlssen in Groszligbuchstaben
geschrieben sein sonst werden sie nicht
gefunden
====================================================
sUserBALVI_IP = BALVI_IP_SCHEMA
sUserBALVI_WEB = WEBAPP_SCHEMA
-- Verfahrensbezogene Konfiguration
-- Setzen Sie fuumlr das jeweilige Verfahren eine 1
-- BALVI Schnittstellenserver (BSS)
-- bis V266 auch BALVI Kommunikationsserver (BKS) genannt
-- generell fuumlr die meisten Verfahren guumlltig
-- Ab Version 57 entfaumlllt mit der Einfuumlhrung der
-- Schnittstelle XGewerbeanzeigen auch der separate Schalter
-- WS_BTR beide Verfahren wurden vereinheitlicht
WS_BSS = 1
-- WebService BTR (Betriebsstaumlttenregister) (NRW TH)
-- entfernt mit Update V57 setzen Sie stattdessen bei WS_BSS = 1
--WS_BTR = 0
-- Probenahme Futtermittel im Browser(BY)
WS_PROBE_FM = 0
-- Risikoorientierte Probenplanung Futtermittel ndash RIOPP FM (BY)
WS_RIOPP_FM = 0
-- Verfahren Export an EFi (Status Pilotbetrieb)
WS_EFI = 1
-- neu ab Version 35 des Grant-Skriptes ist die Moumlglichkeit den Webuser
Release Notes BALVI Schnittstellenserver Seite 17 von 37
-- fuumlr das Loumlschen der Ausgangskoumlrbe explizit zu berechtigen bzw sogar einen
-- expliziten abweichenden User festzulegen Die Konfiguration in der
-- Job-Oberflaumlche sieht vor dass man die Oracle-Datenbank-Zugangsdaten fuumlr
-- das Loumlschen einstellen muss Hier muss im Normalfall derselbe Oracle
-- Datenbankbenutzer eingetragen werden wie in der Tomcat-Verbindungs-
-- konfiguration In diesem Fall sollte wenn WS_EFI = 1 eingestellt wurde
-- ebenfalls WS_EFI_DELETE = 1 eingestellt werden
-- Alternativen
-- 1) Datenbankbenutzer aumlndern
-- Wenn bei sUserEFI_TRUNC anstatt sUserBALVI_WEB (Standard) ein anderer
-- Oracle-Benutzername angegeben wird wird das Loumlschrecht fuumlr die EFi
-- Ausgangskoumlrbe Datenbankseitig exklusiv dem angegeben Datenbankbenutzer
-- zugewiesen
-- 2) Loumlschrecht verweigern
-- Setzen Sie die Variablen WS_EFI_DELETE = 0 damit kein Loumlschrecht
-- zugeweisen wird
WS_EFI_DELETE = 0
-- Beispiel Anderer Benutzer muss in der Datenbank existieren
-- Entfernen Sie die fuumlhrenden -- vor der Variable sUserEFI_TRUNC und
-- setzen den entsprechenden Oracle-Benutzer ein
--sUserEFI_TRUNC = TEST_EFI_TRUNC
hellip
25 Konfiguration des Schnittstellen-Servers
251 Die bdquocontextxmlldquo-Parameter Die von der Servlet-Spezifikation vorgegeben Rump-Struktur sieht folgendermaszligen aus
ltxml version=10 encoding=utf-8gt
ltDOCTYPE Contextgt
ltContextgt
lt-- Kundenspezifische Einstellungen --gt
ltContextgt
Anwendungsspezifische Einstellungen werden zwischen ltContextgt und ltContextgt eingefuumlgt Alle allgemeinguumlltigen Einstellungen in der Datei bdquocontextxmlldquo werden hier erlaumlutert Kommentare finden sich auch in der von BALVI ausgelieferten Beispiel-Konfiguration
Neben den im Folgenden beschriebenen Standard-Einstellungen kann es auch vorkommen dass bundeslandspezifische Erweiterungen vorhanden sind welche nicht in dieser Dokumentation aufgefuumlhrt werden Diese funktionieren trotzdem regulaumlr weiter wenn keine expliziten Informationen zu Kompatibilitaumltsproblemen in den Release-Notes aufgefuumlhrt wurden
2511 Datenbankverbindung jdbcDataSource
Die Datenbankverbindung wird uumlber die von DBCP und dem Oracle-Treiber vorgegebenen Moumlglichkeiten realisiert Der Einsatz der orgapachetomcatjdbcpoolDataSourceFactory (automatisch verfuumlgbar ab Apache Tomcat 7 in der mitgelieferten tomcat-dbcpjar) wird als Beispiel-Konfiguration ausgeliefert
ltResource
name=jdbcDataSource
auth=Container
Release Notes BALVI Schnittstellenserver Seite 18 von 37
type=javaxsqlDataSource
factory=orgapachetomcatjdbcpoolDataSourceFactory
maxActive=10 initialSize=3
maxIdle=5
maxWait=10000
url=jdbcoraclethinBL2-ORA10-KUNDENBALVIINTERN1521ORCL
driverClassName=oraclejdbcdriverOracleDriver
username=balvi_webservice_schema
password=balvi_webservice_password
description=Oracle Datasource
maxOpenPreparedStatements=50
removeAbandoned=false
removeAbandonedTimeout=100
logAbandoned=true
jdbcInterceptors=hellip
gt
Hinweise zur Einstellung der jdbcDataSource
Standard-Einstellungen fuumlr den Datenbank-Verbindungspool
Der Verbindungspool muss entsprechend der Anzahl der zu erwartenden gleichzeitigen Benutzer konfiguriert werden Wenn Sie erwarten dass 50 Anwender gleichzeitig arbeiten stellen Sie bitte folgende Werte ein
maxActive=(50 + 10 (fuumlr System und Jobs)) = 60
maxIdle= (50 10) = 5
1 maxActive - maximale Anzahl der gleichzeitigen aktiven Anfragen an die DB
Wenn der Werte maxActive erreicht ist z B wenn mehrere Benutzer gleichzeitig einen Export starten moumlchten welcher laumlngere Zeit in Anspruch nimmt dann kann der Server die Anfrage nicht mehr bedienen und der Anwender wird abgewiesen maxActive hat zudem Auswirkungen auf die im Hintergrund ausgefuumlhrten Jobs maxActive wird daher kalkuliert mit der Anzahl der Anwender und moumlglicher Datenbank-Connections fuumlr Hintergrund-Jobs Jeder aktiv ausgefuumlhrte Job benoumltigt mindestens eine Connection nur selten wird aus Performance-Gruumlnden mehr als eine Connection waumlhrend der Job-Ausfuumlhrung verwendet Im Normalfall sollten daher 10 Connections fuumlr Hintergrundprozesse ausreichend sein
2 maxIdle - Anzahl der offenen Verbindungen auch wenn der Server im Leerlauf ist
Jede offene Verbindung im Leerlauf haumllt auf dem Datenbankserver eine Session offen Auch diese erfordert Ressourcen Wenn die Verbindungen jedoch geschlossen werden kann die Anfragezeit fuumlr eine neue Verbindung steigen da diese Verbindung erst neu ausgehandelt werden muss Die Empfehlung fuumlr den Wert bdquomaxIdleldquo ist ca 10 der Einstellung von maxActive
KeepAlive-Einstellungen fuumlr den Pool
1 validationQuery
Diese wird ausgefuumlhrt um die Verbindung zu DB zu validieren Es MUSS ein Datensatz zuruumlckgegeben werden ansonsten nimmt der DBCP an dass die Abfrage nicht erfolgreich abgesetzt wurde Achten Sie also bitte darauf dass die Abfrage nicht zu leitungsintensiv ist und genau einen Datensatz liefert
Release Notes BALVI Schnittstellenserver Seite 19 von 37
Oracle bietet dafuumlr die virtuelle Tabelle DUAL an welche sich fuumlr die ValidationQuery sehr gut eignet da die Abfrage kaum Ressourcen verbraucht
validationQuery=select 1 from dual
2 testOnBorrow - Boolscher Wert true oder false
Diese Einstellung sorgt dafuumlr dass der Pool die Verfuumlgbarkeit anhand der validationQuery pruumlft bevor
die DB-Verbindung an die Anwendung ausgeliehen wird Empfehlung
testOnBorrow=true
3 testWhileIdle - Boolscher Wert true oder false
Diese Einstellung ist hilfreich wenn zwischen dem Tomcat und der DB eine Firewall mit Stateful
Packet Inspection verwendet wird Nach laumlngerer Inaktivitaumlt wird normalerweise durch die Firewall die
DB-Verbindung geschlossen Dieses loumlst dann beim Ausleihen der Verbindung eine Fehlermeldung im
Protokoll aus 2012-08-16 165418720 WARN [http-0000-8080-8]
[orgspringframeworkjdbcsupportSQLErrorCodesFactory] Error while extracting
database product name - falling back to empty error codes
orgspringframeworkjdbcsupportMetaDataAccessException Error while extracting
DatabaseMetaData nested exception is javasqlSQLRecoverableException Getrennte
Verbindung Um dieses Problem zu beheben sollte die Option testWhileIdle=true eingestellt werden
testWhileIdle=true
Damit diese weiszlig wie oft eine Pruumlfung durchgefuumlhrt werden muss sind jedoch noch zusaumltzliche Angaben erforderlich welche fuumlr die Einstellung der Zeit zusaumltzlich gesetzt werden muumlssen
a) minEvictableIdleTimeMillis - Long in Millisekunden
Min Zeit wie lange eine DB-Verbindung im Leerlauf ist bevor diese zur Pruumlfung
gekennzeichnet wird Dieses haumlngt stark von der Einstellung der Firewall ab Wenn Sie eine
sehr restriktive Firewall haben kann es sein dass diese die Verbindung nach wenigen
Minuten Leerlauf trennt Stellen Sie den Wert immer so ein dass dieser unter der Leerlaufzeit
der Firewall liegt empfohlen 300000 entspricht 300 Sek = 5 min
minEvictableIdleTimeMillis=300000
b) timeBetweenEvictionRunsMillis - Long in Millisekunden
Der Pruumlflauf startet in der Default-Konfiguration alle 1800000 Millisekunden = 30 Min n als
zu Pruumlfen markierte Verbindungen werden in einem Pruumlflauf getestet n wird bestimmt durch
die Einstellung numTestsPerEvictionRun Empfehlung Stellen Sie den Wert auf alle 15 Min
ein
timeBetweenEvictionRunsMillis=900000
Release Notes BALVI Schnittstellenserver Seite 20 von 37
c) numTestsPerEvictionRun - Integer
Wie viele Verbindungen sollen getestet werden waumlhrend der Pruumlflauf ausgefuumlhrt wird Im
Normalfall sollte die Anzahl der zu testenden Verbindungen nicht zu hoch eingestellt werden
Der Default ist 3 Wenn Sie houmlhere Sicherheit haben wollen dass keine bdquototenldquo
Datenbankverbindungen bestehen bleiben erhoumlhen Sie den Wert auf max bdquo(maxActive ndash
maxIdle) 2ldquo Wenn Ihnen 3 ausreichend erscheint muss der Wert nicht gesetzt sein dann
wird der Default verwendet
Beispiel numTestsPerEvictionRun=10
4 Interceptors konfigurieren Neu ergaumlnzt wurde die Moumlglichkeit spezielle bdquoInterceptorsldquo zu konfigurieren die ermoumlglichen das Verhalten des Pools zu steuern Wichtig hierbei ist dass die Angabe von Werten auf real existierende Java-Klassen erfolgt die im Classpath des Tomcat vorhanden sind Groszlig-und-Kleinschreibung ist zu beachten Folgende Default-Einstellung hat BALVI fuumlr den BSS festgelegt jdbcInterceptors=
orgapachetomcatjdbcpoolinterceptorConnectionState
orgapachetomcatjdbcpoolinterceptorStatementFinalizer
orgapachetomcatjdbcpoolinterceptorResetAbandonedTimer
Details zu den verwendeten Interceptor-Einstellungen finden Sie in der Tomcat-Dokumentation3
3 httptomcatapacheorgtomcat-80-docjdbc-poolhtmlJDBC_interceptors
Release Notes BALVI Schnittstellenserver Seite 21 von 37
2512 Datenbank-Zugangsdaten verschluumlsseln
Die Verschluumlsselung fuumlr die Datenbank-Verbindung (bdquoEncrypted Datasourceldquo) ist eine Ableitung der Bibliothek Apache-Common-DBCP-14 und daher nicht mehr mit Java 8 kompatibel Die Einrichtung der Verschluumlsselung wird daher mit der Auslieferung des BSS 30 nicht mehr angeboten
2513 Active-Directory-Authentifizierung
Uumlber die folgenden Parameter wird der Zugriff des Schnittstellen-Servers auf einen Microsoft Active Directory Domain-Controller konfiguriert
ldquoldapServerAddressrdquo
Syntax PROTOKOLLIP-Adresse oder DNS-NamePORT
ltEnvironment
name=ldapServerAddress
value=ldapbl2-dc02balviintern389
type=javalangString
override=true
gt
Als Protokoll besteht auch die Moumlglichkeit ldaps (LDAP+SSL) wenn der Domain-Controller entsprechend konfiguriert wurde Im Java Truststore muss dann das Zertifikat der CA vorhanden sein welche das Zertifikat des Domain-Controllers signiert hat Zudem darf bei ldaps keine IP-Adresse verwendet werden es muss der DNS-Name des Server-Zertifikats eingetragen sein Ansonsten gibt es beim Verbinden eine Sicherheits-Exception
lt-- SSL-Beispiel
ltEnvironment
name=ldapServerAddress
value=ldapsbl2-dc02balviintern636
type=javalangString
override=true
gt
--gt
bdquoldapBaseDnrdquo
LDAP-Suchpfad fuumlr die Domain-Basis Diese muss der LDAP-Syntax fuumlr den Domain-Suffix entsprechen
Syntax DC=SERVERDC=ROOTDN
ltEnvironment
name=ldapBaseDn
value=DC=BALVIDC=INTERN
type=javalangString
override=true
gt
Release Notes BALVI Schnittstellenserver Seite 22 von 37
bdquowebLoginUseActiveDirectoryAuthenticationrdquo
Die Authentifizierung in der Browser-Oberflaumlche kann uumlber die Active-Directory-Authentifizierung erfolgen In der ersten Version ist nur die Protokoll-Auswertung moumlglich wenn der ADMIN sich anmeldet Dieser hat normalerweise niemals AD-Kennungen zugeordnet BALVI empfiehlt diese Einstellung auf bdquofalseldquo zu belassen Webservices welche uumlber SOAPREST zugreifen koumlnnen die Active-Directory-Authentifizierung trotzdem verwenden
ltEnvironment
name=webLoginUseActiveDirectoryAuthentication
value=false
type=javalangBoolean
override=true
gt
ldquoldapDaysBeforeExpirationNotificationrdquo
Die Passwort-Aumlnderung im Active-Directory uumlber die Browser-Oberflaumlche ist in der ersten Version noch nicht implementiert der Parameter wird bislang nicht ausgewertet
ltEnvironment
name=ldapDaysBeforeExpirationNotification
value=14
type=javalangInteger
override=true
gt
2514 Statement-Protokollierung in BALVI iP
Diese Option aktiviert die Lese- und Aumlnderungsprotokollierung fuumlr BALVI iP Standard ist bdquofalseldquo und wird fuumlr alle Kunden empfohlen solange keine speziellen Datenbank-Jobs eingerichtet wurden welche zeitgesteuert die Protokolleintraumlge wieder loumlschen Fuumlr Bayern wurde ein spezielles Konzept zur Leseprotokollierung entworfen Wenn Sie mehr daruumlber erfahren moumlchten kontaktieren Sie bitte die BALVI GmbH
ltEnvironment
name=enableSqlStatementMonitoring
value=true
type=javalangBoolean
override=true
gt
Beachten Sie dass diese Option massive INSERT-Statements in BALVI iP in die Tabelle VIS_D92 ausfuumlhrt Jedes abgesetzte SQL-Statement wird dabei vollstaumlndig protokolliert Dieses erzeugt eine sehr hohe INSERT-Last und in der Folge auch erhoumlhte Redolog-Switches und COMMIT-Transaktionen
Optional Aktivieren der INSERT + APPEND - Logik
Beachten Sie bitte die Hinweise von Oracle zum Hint + APPEND
Release Notes BALVI Schnittstellenserver Seite 23 von 37
Wenn Sie dieses Verhalten aktivieren moumlchten ergaumlnzen Sie bitte den folgenden Environment-Parameter
ltEnvironment
name=statementMonitoringactivateAppendMode
value=true
type=javalangBoolean
override=true
gt
2515 Einstellungen fuumlr BALVI mobil XT (bzw den bdquopartitionedExportldquo)
Diese Logik des FIFO-Buffers wurde so konzipiert dass dem Rechenzentrum diverse Einstellmoumlglichkeiten uumlber die Datei bdquocontextxmlldquo zur Verfuumlgung stehen um die Steuerung des FIFO-Puffers zu beeinflussen
Schematische Darstellung des FIFO-Puffers
Das ermoumlglicht es z B dem BALVI mobil XT Client (14 oder houmlher) den aktiven Block abzuholen und dies beim Fehler bis zu 10-mal zu wiederholen Sobald der Block [001] erfolgreich beim Client angekommen ist und dieser den naumlchsten Block anfragt wird der Block [001] verworfen wird Der Server fuumlllt dann im Hintergrund den frei gewordenen Block wieder waumlhrend der Client den Block [002] abholt
Die Groumlszlige und Anzahl der vorgecachten Bloumlcke kann uumlber die folgenden Einstellungen in der Datei bdquocontextxmlldquo definiert werden
ltEnvironment
name=partitionedExportmaxBufferedPartitions
value=3 type=javalangInteger override=true
gt
ltEnvironment
name=partitionedExportpartitionSize
value=256000 type=javalangInteger override=true
gt
Die Einstellung partitionedExportmaxBufferedPartitions ist dabei die Anzahl der vorgecachten Bloumlcke mindestens muss 2 angegeben werden Der Puffercache wird ausschlieszliglich im RAM der JVM aufgebaut es wird folglich mehr Arbeitsspeicher verwendet Dieser Arbeitsspeicher muss je gleichzeitiger Session auf dem Server bereitgestellt werden die Default-Einstellung mit 3 Partitionen a 256 KB + dem aktiven Puffer erfordern 1 MB RAM je aktiven Anwender
Aktiv
er
Puffe
r
[001] Vorg
ecac
hter
Bl
ock
[002] Vorg
ecac
hter
Bl
ock
[003]
Aktiv
er P
uffe
r
[002] Vorg
ecac
hter
Bl
ock
[003] Vorg
ecac
hter
Bl
ock
[leer]
Release Notes BALVI Schnittstellenserver Seite 24 von 37
Gleichzeitig wurde die Moumlglichkeit geschaffen dass die maximale Anzahl an gleichzeitigen Exporten durch das Rechenzentrum eingeschraumlnkt werden kann um einem OutOfMemory-Fehler vorzubeugen Die Einstellung
ltEnvironment
name=partitionedExportmaxConcurrentExports
value=10 type=javalangInteger override=true
gt
muss entsprechend der zu erwartenden gleichzeitigen Zugriffe konzipiert werden ansonsten wird der Server einen Verbindungsversuch durch die Clients ablehnen
Beachten Sie dass die folgenden Einstellungen partitionedExportmaxBufferedPartitions partitionedExportmaxConcurrentExports und partitionedExportpartitionSize gemeinsam als Rechenbasis fuumlr den RAM-Bedarf des Webservers herangezogen werden muumlssen
Folgende Faustformel sollte fuumlr die Einrichtung verwendet werden
Min 256 MB (Serverbasis) + (11 partitionedExportmaxConcurrentExports partitionedExportmaxBufferedPartitions partitionedExportpartitionSize)
Beispiel 50 gleichzeitige Anwender Blockgroumlszlige 256 KB 4 Partitionen
256 MB + (11 50 256 4) KB = 312 MB fuumlr die JVM
Empf 512 MB (Serverbasis) + (12 partitionedExportmaxConcurrentExports partitionedExportmaxBufferedPartitions partitionedExportpartitionSize)
Beispiel 50 gleichzeitige Anwender Blockgroumlszlige 256 KB 4 Partitionen
512 MB + (12 50 256 4) KB = 572 MB fuumlr die JVM
partitionedExportmaxConcurrentExports
Bestimmt die Anzahl der maximalen Export Tasks (Threads) die fuumlr partitionierte Exporte bereitgestellt werden Wenn die Anzahl uumlberschritten wird wird die entsprechende Exportanfrage abgewiesen und der Client muss zu einem spaumlteren Zeitpunkt erneut anfragen Stellen Sie diesen Wert entsprechend der zu erwartenden Benutzeranzahl ein bei 50 Anwendern also 50
Exporte oumlffnen auf der Datenbank entsprechend zur Ausfuumlhrungszeit min einen Cursor ggf fuumlr rekursive Unterabfragen kurzfristig sogar mehr Die hier eingestellte Anzahl muss mit der Anzahl von maxActive korrelieren
ltEnvironment
name=partitionedExportmaxConcurrentExports
value=10 type=javalangInteger override=true
gt
partitionedExportmaxBufferedPartitions
Bestimmt die Anzahl der Datenbloumlcke (Partitionen) die vom Server bei Abruf eines Exportes gepuffert werden Die seit Version 24 eingefuumlhrte FIFO-Puffer-Logik ermoumlglicht dass der Server schon die Ergebnisse vorpuffert so dass der Client weniger Wartezeiten bei der Anfrage nach Daten hat Diese
Release Notes BALVI Schnittstellenserver Seite 25 von 37
Puffer-Logik unterteilt den Exportdatenstrom (je Export) in mehre Bloumlcke Der Client kann nun den letzten Block neu anfordern oder den naumlchsten Block wenn der letzte Block erfolgreich verarbeitet wurde Wie viele naumlchste Bloumlcke durch den Server bereit gestellt werden entscheidet diese Einstellung Sobald kein naumlchster Block mehr bereit gestellt werden muss wird der Datenbank-Cursor geschlossen eine Erhoumlhung kann also zu einer Entlastung der aktiven DB-Verbindungen fuumlhren erhoumlht jedoch den Bedarf an RAM des Servers
Der von BALVI voreingestellte Wert ist 3
ltEnvironment
name=partitionedExportmaxBufferedPartitions
value=3 type=javalangInteger override=true
gt
partitionedExportpartitionSizeldquo
Die Groumlszlige der Datenbloumlcke (Partitionen) die an den Client uumlbermittelt werden in Bytes Wenn Sie diesen Wert zu niedrig einstellen reduziert sich die Effizienz des Caches da der Client mehr Datenbloumlcke hintereinander abrufen muss Waumlhlen Sie einen zu groszligen Wert wird die neu zu uumlbertragende Datenmenge im Fall eines Fehlers houmlher
Der von BALVI voreingestellte Wert ist 256000 (256 KB)
ltEnvironment
name=partitionedExportpartitionSize
value=256000 type=javalangInteger override=true
gt
exportTokensmaxTokenCount
Maximale Anzahl der gleichzeitig vergebenen Token die vom Server gecached werden Jede Sitzung welche einen Export durchfuumlhrt erhaumllt einen Session-Token
Wenn eine Sitzung laumlngere Zeit nicht verwendet wurde wird dieser Session-Token wieder entfernt Wenn Sie den Wert zu niedrig einstellen fuumlhrt das zu einer generellen Session-Begrenzung auch fuumlr den nicht partitionierten Export-Modus welcher ab Version 21 verfuumlgbar ist
Ist die Anzahl der Tokens houmlher als die Datenbankeinstellung maxActive kann es vorkommen dass zwar eine Session gestartet werden kann jedoch kein Datenexport zustande kommt
Der von BALVI voreingestellte Wert ist 2000
ltEnvironment
name=exportTokensmaxTokenCount
value=20 type=javalangInteger override=true
gt
exportTokenstokenExpirationInSeconds
Zeit in Sekunden die verstreichen muss bis ein Token unguumlltig wird falls darauf kein Zugriff mehr erfolgt Nach einem erfolgreichen Export wird der Token automatisch geschlossen diese Option ist fuumlr den Abbruchfall vorgesehen Der von BALVI voreingestellte Wert ist 180 (180 s = 3 min)
Release Notes BALVI Schnittstellenserver Seite 26 von 37
ltEnvironment
name=exportTokenstokenExpirationInSeconds
value=180 type=javalangInteger override=true
gt
exportTokenstokenDisposalInSeconds
Zeit in Sekunden die verstreichen muss bis ein Token das erfolgreich abgearbeitet wurde aus dem Cache geloumlscht wird Um sicher zu stellen dass der letzte Exportblock noch erfolgreich abgerufen werden kann bleibt der Token auch nach Fertigmeldung des Clients noch N Sek guumlltig
Der von BALVI voreingestellte Wert ist 60 (60 s = 1 min)
ltEnvironment
name=exportTokenstokenDisposalInSeconds
value=60 type=javalangInteger override=true
gt
2516 Job-Verwaltung fuumlr den BSS konfigurieren Aktivierung der Jobverwaltung
Bis zur Version 28 des BSS gab es den Parameter bdquoavailableServicesldquo Dieser konnte bei Bedarf aktiviert werden wenn die Jobs benoumltigt wurden
Mit Version 30 ist die Einstellung bdquoavailableServicesldquo zu entfernen und kann durch den neuen optionalen Parameter bdquoisJobServiceEnabledldquo in der Datei bdquocontextxmlldquo ersetzt werden
lt-- Neue Parameter zur Aktivierung des Job Service Ersatz fuumlr availableServices --gt
ltEnvironment
name=isJobServiceEnabled
value=true
type=javalangBoolean
override=true
gt
Ab BSS 30 wird die Jobs-Engine standardmaumlszligig aktiviert Sollte die Jobs-Engine nicht benoumltigt werden muss bdquovalueldquo der Wert bdquofalseldquo zugewiesen werden Wird bdquoisJobServiceEnabledldquo nicht eingefuumlgt sind die Jobs trotzdem standardmaumlszligig aktiv
Nach dem Neustart des Servers und erneutem Einloggen erscheint nun zusaumltzlich der Menuumlpunkt bdquoJobsldquo
bdquopasswordKeyldquo fuumlr Jobs
In der Job-Logik wird ein von BALVI definierter Standard-Schluumlssel fuumlr die Ablagen von schuumltzenswerten Daten z B Passwoumlrtern verwendet Diese Einstellung ermoumlglicht den BALVI-Standard zu uumlberschreiben Wenn Sie diese Einstellung aumlndern muumlssen jedoch alle bislang verschluumlsselten Job-Parameter neu verschluumlsselt werden
ltEnvironment
name=javacompenvjobspasswordKey
value=MeinHochsicheresNeuesPasswort
type=javalangString
Release Notes BALVI Schnittstellenserver Seite 27 von 37
override=true
gt
bdquoJob ID enableddisabledldquo (Deprecated ersetzt ab 28 durch das bdquoBindenldquo von Jobs)
Sondereinstellungen fuumlr die Job-Verwaltung Da alle Jobs in einer Datenbank administriert werden jedoch ggf verteilt auf mehreren Tomcat-Servern ausgefuumlhrt werden sollen besteht hier die Option Jobs fuumlr die aktuelle Tomcat-Instanz separat zu deaktivieren
Die Einstellung ID koumlnnte z B folgendermaszligen aussehen javacompenvjobsC0DB58D8D52C4BBC966D1DC788A4EF8Benabled
Fuumlr weitere Fragen zu dieser Einstellung kontaktieren Sie bitte die BALVI GmbH
ltEnvironment
name=javacompenvjobsIDenabled
value=false
type=javalangBoolean
override=true
gt
2517 Weitere optionale Parameter
Es ist fuumlr diverse einzelne Schnittstellen ggf erforderlich Einstellungen in der Datei bdquocontextxmlldquo zu ergaumlnzen Hinweise zu diesen Parametern sind dann in dem der Schnittstelle beiliegenden Dokument enthalten Das gilt z B fuumlr die Schnittstelle bdquoXGewerbeanzeigenldquo
26 Logging mit logback Das Logging wurde komplett uumlberarbeitet Statt bdquoLog4Jldquo wird jetzt bdquologbackldquo4 benutzt Ab BSS 30 ist es zwingend notwendig die Einstellung vorzunehmen um das Logging der Anwendung zu steuern
Migration Ergaumlnzen Sie die neue Einstellung bdquologgingconfigldquo
lt-- Neue Paramter zur Angabe der Logback Config Ersatz fuumlr log4jConfigLocation --gt
ltEnvironment
name=loggingconfig
value=$catalinabaseconflogback-bssxml
type=javalangString
override=true
gt
Nach wie vor steht es Ihnen frei die Logging-Konfiguration eigenstaumlndig anzupassen
Wenn Sie jedoch dieselbe WAR in einer Tomcat-Instanz unter mehreren Context-Namen betreiben wuumlrden beide dieselbe Logging-Konfiguration verwenden so dass alle Protokolleintraumlge in einer Log-Datei aus
4 httplogbackqoschmanualappendershtml
Release Notes BALVI Schnittstellenserver Seite 28 von 37
mehreren Webanwendungen generiert werden Aumlndern Sie den Namen der Logging-Konfiguration entsprechend ab um fuumlr jede Anwendung eine spezifische Logging-Einstellung vornehmen zu koumlnnen
27 Tocmat Optional Suche im bdquoKlassenpfadldquo um den
Ordner bdquoconfldquo erweitern Die Suche nach Dateien uumlber bdquoclasspathldquo setzt voraus dass die Ordner- und Dateinamen im Apache Tomcat bekannt gegeben werden Der Klassenpfad kann in der Datei bdquocatalinapropertiesldquo angepasst werden Wenn Sie dort unter commonloader die folgenden Werte ergaumlnzen kann eine Datei auch im Ordner conf abgelegt werden damit Apache Tomcat diese findet Ansonsten muss die Datei im Ordner lib abgelegt werden
commonloader=$catalinabaseconf$catalinahomeconf
3 Die neue Browser-Oberflaumlche Der BALVI Schnittstellenserver hat seit Version 25 neben der Protokollierung auch die Moumlglichkeit Job-Konfigurationen zu pflegen Der Login ist nur fuumlr einen in BALVI iP eingetragenen ADMIN (z B Benutzer bdquoSYSTEMADMINldquo) mit dem in BALVI iP hinterlegten Passwort moumlglich Zur Anmeldung muss immer [SYSTEMBenutzername] im Feld Benutzer angegeben werden ansonsten schlaumlgt die Anmeldung fehl Bitte achten Sie darauf dass der bdquoldquo (Slash) und nicht der bdquoldquo (Backslash) verwendet werden muss
31 Server-Protokoll Um das Server-Protokoll anzuzeigen waumlhlen Sie den entsprechenden Menuumlpunkt Dort haben Sie seit BSS 26 die Moumlglichkeit uumlber alle Spalten der Protokolle nach Informationen zu suchen
Seit BSS 31 gibt es die Moumlglichkeit Verfahren in bdquoKopfsaumltzeldquo und bdquoDetailsaumltzeldquo zu unterteilen Wurde das Verfahren entsprechend konfiguriert (wie z B bei der Schnittstelle bdquoXGewerbeanzeigenldquo) dann wird im Protokoll-Kopfsatz nur der Start und das Ende der Ausfuumlhrung in der Liste angezeigt Erst bei einem Klick auf bdquoInformationenldquo wird die Liste aller Detailsaumltze angezeigt die im Durchlauf erzeugt wurden
Release Notes BALVI Schnittstellenserver Seite 29 von 37
Verfahren
Die Liste der verfuumlgbaren Verfahren die bei Ihnen im System installiert sind ZB
BEFUNDEhellip Schnittstelle Befunde LM FM oder TS
PROBEhellip Schnittstelle zum Export von Proben an Labore ebenfalls Spezifisch fuumlr einzelne Fachbereiche
MOBILXT Protokolle der BALVI Mobil XT Synchronisation
WEB Allgemeine nicht spezifizierte Protokolle hierunter ist bislang auch die eFi-Protokollierung zu finden
WEB_I0802 Protokolle zur Schnittstelle BALVI iP LIMS (Lebensmittelproben)
XGEWERBE Schnittstelle XGewerbeanzeigen
Klicken Sie auf die Schaltflaumlche so besteht bei den neuen Protokolldatensaumltzen die Moumlglichkeit Detail-Informationen zum Protokollsatz zu erhalten
Release Notes BALVI Schnittstellenserver Seite 30 von 37
Seit BSS 30x ist die Anzeige der Protokolle ebenfalls farblich abgesetzt so dass Protokolleintraumlge mit Fehlern hellrot und Warnungen hellgelb hinterlegt werden
32 Jobs Mit einem Klick auf den Menuumlpunkt Jobs rufen Sie die Oberflaumlche fuumlr die Job-Konfiguration auf Daraufhin werden alle Jobs aufgelistet die fuumlr den BSS freigegeben sind Hier koumlnnen Sie Einstellungen an den Jobs vornehmen und die Jobs aktivieren bzw deaktivieren Die Beschreibungen bzw Einstellungsmoumlglichkeiten fuumlr den jeweiligen SST-Job sind nicht Bestandteil dieser Dokumentation
33 Log-Ausgaben Uumlber den Menuumlpunkt Log-Ausgaben koumlnnen Sie die Ausgabe der Protokolleintraumlge in Echtzeit beobachten
Release Notes BALVI Schnittstellenserver Seite 31 von 37
Starten Sie die Echtzeit-Protokollierung indem Sie auf die Schaltflaumlche mit dem Symbol bdquoPlayldquo (Dreieck) klicken unterbrechen Sie die Ausgabe indem Sie die auf Schaltflaumlche mit dem Symbol bdquoPauseldquo (zwei Balken) klicken
Klicken Sie auf die Schaltflaumlche bdquoAktualisierenldquo (zwei Pfeile) um die neuesten Protokolleintraumlge angezeigt zu bekommen
Klicken Sie auf das Symbol mit dem Papierkorb um die letzten Protokollmeldungen in der Anzeige zu loumlschen
Die Daten in den Protokolldateien auf der Festplatte des Servers sind davon nicht betroffen
Uumlber das Symbol bdquoLogging anpassenldquo (Schraubenschluumlssel) koumlnnen Sie die Ausgabe der Daten im Echtzeitfenster und in den Protokolldateien aumlndern jedoch ist diese Einstellung nur temporaumlr Die Standardeinstellungen koumlnnen ausschlieszliglich uumlber die Anpassung der Datei bdquologback-bssxmlldquo im Konfigurationsverzeichnis des Servers selbst geaumlndert werden
Release Notes BALVI Schnittstellenserver Seite 32 von 37
In der Logging-Parameter Konfiguration koumlnnen Sie verschiedene Parameter einstellen und uumlber die Schaltflaumlche bdquoAnwendenldquo dann sofort im Echtzeitprotokoll sehen Welche Einstellungen moumlglich sind erfahren Sie wenn es eine akute Fehlersituation gibt die detailliertere Ausgaben im Protokoll erfordert
Warnung Wenn Sie den Log-Level fuumlr ROOT oder eine andere Klasse auf TRACE einstellen werden sehr viele Protokollausgaben generiert die auch dazu fuumlhren koumlnnen dass der Server sehr langsam wird oder die Festplatte des Servers zulaumluft wenn fuumlr das Logging kein Dateilimit konfiguriert wurde
34 LogoutAbmeldung vom System Zum Abmelden waumlhlen Sie oben rechts das Kontextmenuuml
35 Cache loumlschen Der Cache wird in der Regel automatisch geloumlscht Wenn Sie jedoch gerade in BALVI iP eine Aumlnderung an den Schnittstellen eingespielt haben und moumlchten dass diese sofort wirksam wird kann die Funktion bdquoCache loumlschenldquo dazu verwendet werden dass der BALVI Schnittstellenserver die Einstellungen bei der naumlchsten Anfrage neu einliest
Release Notes BALVI Schnittstellenserver Seite 33 von 37
Release Notes BALVI Schnittstellenserver Seite 34 von 37
4 Einrichtung in BALVI iP Um die Verfahren fuumlr den BALVI Schnittstellenserver fuumlr Anwender freizuschalten wird das Objekt bdquoSystemeinstellungenldquo oder bdquoMandanten- und Benutzereinstellungenldquo verwendet Die Anpassung ist je Verfahren moumlglich so kann in BALVI iP fuumlr den Zugriff durch den BALVI Schnittstellenserver ein Benutzer bdquoAldquo am Verfahren bdquoMobilldquo berechtigt werden ein Benutzer bdquoBldquo nur am Verfahren bdquoSLA_FLESHldquo usw Die Logik ist jedoch einheitlich Je Verfahren wird durch BALVI eine Verfahrensgruppe mit dem Verfahrensnamen angelegt und mit den entsprechenden Einstellungen vorkonfiguriert welche durch das Verfahren erforderlich sind Dabei kann die Komplexitaumlt der Einstellungen variieren wie z B an den zu Version 23 verfuumlgbaren Verfahren bdquoMobilldquo und bdquoSLA_Fleshldquo ersichtlich wird
Im Verfahren BALVI Mobil sind diverse Anpassungen moumlglich welche je Bundesland oder eingesetzter Import- und Export-Variante durch den BALVI Schnittstellenserver bei der Bearbeitung von Anfragen gepruumlft werden siehe Punkt 3 Abb Mobil-Einstellung in BALVI iP
Abb Mobil-Einstellung in BALVI iP
Alle Verfahren verwenden jedoch die regulaumlre Benutzerverwaltung von BALVI iP Ein Benutzer ohne Passwort gilt fuumlr BALVI iP als gesperrt was fuumlr das Login bedeutet dass der Anwender sich nur uumlber die Active-Directory-Authentifizierung anmelden kann Ist das nicht moumlglich (bzw nicht konfiguriert) kann der Anwender sich weder in BALVI iP noch uumlber die Webservice-Schnittstelle authentifizieren
Fuumlr Dienste-Schnittstellen welche keine persoumlnliche Authentifizierung durch einen Anwender erfordern wird empfohlen einen separaten Benutzer in der Benutzerverwaltung anzulegen und ein sicheres Kennwort zu vergeben Das Anlegen von zusaumltzlichen Benutzern gilt nicht fuumlr BALVI mobil XT da beim Holen und Uumlbermitteln von Daten jeder Benutzer auch ein fachlich konfigurierter Anwender innerhalb von BALVI iP ist und die Anwendungsoberflaumlche ebenfalls zur Erfassung von Daten verwendet
Unter Punkt 2 der Abb Mobil-Einstellung in BALVI iP wird ein modales Fenster geoumlffnet (Abb BALVI mobil Benutzerverwaltung) Innerhalb dieses modalen Fensters werden mandantenweise die Benutzer fuumlr BALVI
Release Notes BALVI Schnittstellenserver Seite 35 von 37
mobil und den jeweiligen Fachbereich festgelegt Dabei ist es wichtig dass man die Haken bdquoAktiv fuumlr hellipldquo bei bdquohellip mobilldquo und bei einem Fachbereich (bdquohellip LMldquo bdquohellip FMldquo usw) setzt weil sonst uumlber den BALVI Schnittstellenserver keine Kommunikation mit BALVI iP moumlglich ist
Abb BALVI mobil Benutzerverwaltung
Alternativ zur Passwort-Authentifizierung wird wie beschrieben auch die Active-Directory-Authentifizierung angeboten Dazu muss der BALVI iP-Anwender uumlber die Schaltflaumlche bdquoDomaumlnen-Benutzer zuordnenldquo mit dem Active Directory verknuumlpft werden
Nur wenn die Active-Directory-Konfigurationen in BALVI iP und im BALVI Schnittstellenserver auf dieselbe Domaumlne verweisen sind die Domaumlnen-Zuordnung und die Active-Directory-Authentifizierung (z B uumlber BALVI mobil XT) moumlglich
Release Notes BALVI Schnittstellenserver Seite 36 von 37
5 Bekannte Probleme und Loumlsungen
51 ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner Bei der Job-Bearbeitung tritt folgender Fehler auf ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner
Behebung
Fuumlhren Sie das beiliegende IP-Patch (UPDATEexe) aus bevor Sie das WAR austauschen
52 Server startet nicht Sie finden folgende Zeilen im Protokoll (catalinaout oder bsslog)
ERROR [localhost-startStop-1] [IdentityServiceImpl] serverID must not be empty
ERROR [localhost-startStop-1] [ContextLoader] Context initialization failed
Behebung
Setzen Sie die Umgebungsvariable ldquoserverIDrdquo in der Datei bdquocontextxmlldquo
53 ORA-00942 table or view does not exist In vielen Faumlllen wird der Fehler ldquoTabelle oder View nicht vorhandenrdquo ausgeworfen (Java-Protokoll im Ordner logs von Apache Tomcat) wenn eine neue Schnittstelle eingerichtet oder ein neues BALVI iP Release bzw Update eingespielt wurde ohne anschlieszligend das aktuelle GRANT-Skript auszufuumlhren
Behebung
Fuumlhren Sie das GRANT-Skript erneut aus
54 ORA-0406x bdquoBestehender Paketstatus wurde aufgehobenldquo
ORA-04061 Bestehender Status von package body ABCXYZ wurde annulliert
ORA-04065 Ausfuumlhrung nicht erfolgreich package body ABCXYZ wurde geaumlndert oder geloumlscht
Release Notes BALVI Schnittstellenserver Seite 37 von 37
Der Fehler tritt haumlufig ein nachdem die UPDATEexe ausgefuumlhrt und in der Ausfuumlhrungsliste ein Package aktualisiert wurde Oracle merkt sich je User-Session bestimmte Werte im Package wenn der Anwender es verwendet hat Durch einen bdquoCREATE OR REPLACE PACKAGEldquo-Befehl kann dieser Status temporaumlr aufgehoben werden Normalerweise tritt dieser Fehler nach dem Update genau einmal in jeder aktiven Session auf wenn der BSS nicht neu gestartet wird
Behebung
Starten Sie nach jedem Update den BSS neu um alle laufenden Sessions zu beenden
55 Jobs sind nicht ausfuumlhrbar
1 Ein Job wird mit dem Status bdquoNicht unterstuumltztldquo angezeigt wenn fuumlr seine Ausfuumlhrung eine houmlhere Version des BSS erforderlich ist
2 Nach dem Klonen der Datenbank von der Produktions- auf die Testumgebung erhalten alle Jobs automatisch den Status bdquoDeaktiviertldquo wenn die bdquoserverIDldquo nicht identisch ist
Beide Statusaumlnderungen sind gewollt Damit soll verhindert werden dass Jobs nach einem Serverneustart oder nach einem Update automatisch starten und dabei Fehler verursachen
Um Jobs mit dem Status bdquoNicht unterstuumltztldquo nutzen und konfigurieren zu koumlnnen ist es erforderlich den BALVI Schnittstellenserver zu aktualisieren
Deaktivierte Jobs koumlnnen Sie aktivieren indem Sie den jeweiligen Job an den aktuellen Server binden und den Haken bei bdquoAktivldquo setzen
Release Notes BALVI Schnittstellenserver Seite 9 von 37
2 Einrichtungshinweise
21 Allgemeine Hinweise zum Betrieb
211 Kompatibilitaumlt zu Apache Tomcat und Java SE Der BALVI Schnittstellenserver wurde getestet und freigegeben fuumlr Apache Tomcat 8 (ab Version 8030 oder neuer) Zudem wurde die aktuellste (letzte offizielle) Version von Java SE 8 getestet und kann verwendet werden (Java SE 8u40 und neuer)
Installieren Sie stets die aktuellsten Sicherheitsupdates fuumlr Java SE 8 Beachten Sie dabei jedoch dass nicht die Aktualisierung auf eine andere Java-Version (z B Java 9) gemeint ist
Freigegebene Major-Versionen werden explizit von BALVI benannt Falls Sie beabsichtigen die Major-Version zu aumlndern pruumlfen Sie bitte die aktuellen Release Notes oder kontaktieren die BALVI Kundenbetreuung
212 Oracle Java SE Lizenzierung Java SE beinhaltet auch kostenpflichtige Funktionen fuumlr deren Nutzung Oracle Lizenzgebuumlhren fordert wenn sie bei der Entwicklung eingesetzt werden Die von BALVI gelieferte Software ist frei von den kommerziellen Teilen der Oracle Java SE nutzbar Fuumlr den Einsatz von Oracle Java SE (einschlieszliglich JDK und JRE) fallen im Rahmen der Nutzung der BALVI Software keine Lizenzkosten an
Trotzdem werden wir parallel pruumlfen ob technische Probleme bei der Umstellung auf das OpenJDK zu erkennen sind Ein einfacher Funktionstest hat im BSS 3x noch keine technischen Probleme gezeigt als wir die Laufzeitumgebung auf das OpenJDK 8U111 AMD64 (Debian) umgestellt haben Bitte haben Sie Verstaumlndnis dafuumlr dass wir keine Funktionstests fuumlr jedes Linux-Derivat durchfuumlhren koumlnnen und dass es offiziell keine Version des OpenJDK fuumlr Windows Betriebssysteme gibt
213 Einsatz von TLSSSL BALVI hat keine spezifischen Anforderungen an die Konfiguration von SSL bzw TLS Der Einsatz von TLS 12 gem der Richtlinie TR-02102-2 vom BSI ist moumlglich wenn Sie sich an die von Apache Tomcat herausgegebene Dokumentation halten Es sind keine Anpassungen des Schnittstellenservers erforderlich Daher gehen wir davon aus dass auch der BSS 28x oder aumllter in einem Apache Tomcat mit TLS 12 betrieben werden kann
Das gilt jedoch nicht fuumlr alle Clients die den Tomcat-Server ansprechen moumlchten So ist z B erst ab BALVI mobil 191958 sichergestellt dass die Protokolle TLS 11 und TLS 12 programmseitig aktiviert sind Fuumlr Details zu diesem Problem wurde ein separates Rundschreiben per E-Mail versendet
Release Notes BALVI Schnittstellenserver Seite 10 von 37
214 Nutzung von Java-Proxyeinstellungen Der BALVI Schnittstellenserver verwendet fuumlr ausgehende Verbindungen die Java-Net Einstellungen welche in der Java-Dokumentation1 beschrieben sind Falls Sie Jobs einsetzen welche ausgehenden Zugriff auf Adressen im Internet benoumltigen kann es passieren dass Sie z B eine bdquojavanetUnknownHostExceptionldquo im Protokoll finden dann muumlssen Sie ihre Proxy-Umgebung in den Java-Umgebungseinstellungen ergaumlnzen
Die folgenden Parameter sollten daher in Ihrer Umgebung gesetzt werden wenn der Zugriff auf das Internet nur uumlber einen Proxy moumlglich ist
-DproxySet=true
-DproxyHost=10111213
-DproxyPort=8888
-DhttpnonProxyHosts=domainorg|localhost|10
Starten Sie nach Aumlnderung der Einstellungen den Server neu damit die Einstellungen wirksam werden
2141 Proxy-Einstellung unter Windows (Tomcat-Dienst)
Verwenden Sie das Dienste-Konfigurationsprogramm (z B tomcat7wexe) und ergaumlnzen Sie die fehlenden Einstellungen
2142 Proxy-Einstellung unter Linux
In Linux wird in der Konfigurationsdatei (z B conftomcat7conf) die Variable bdquo$JAVA_OPTSldquo entsprechend erweitert und die Werte uumlbergeben Beachten Sie dabei dass die Variablen von Linux (bzw der Bash) gelesen werden Daher muss das bdquoPipeldquo-Zeichen bdquo|ldquo mit bdquoldquo maskiert werden ansonsten erhalten Sie bei der Verarbeitung der Umgebungsvariable bdquohttpnonProxyHostsldquo Fehlermeldungen in der Linux -Konsole welche dazu fuumlhren dass Java nicht korrekt konfiguriert werden kann
JAVA_OPTS=$JAVA_OPTS -DproxySet=true -DproxyHost=10111213 -DproxyPort=8888
JAVA_OPTS=$JAVA_OPTS -DhttpnonProxyHosts=domainorg|localhost|10
1 httpdocsoraclecomjavase8docstechnotesguidesnetpropertieshtml
Release Notes BALVI Schnittstellenserver Seite 11 von 37
215 Spracheinstellung Deutsch Es wurde festgestellt dass unter einigen Linux-Versionen die Spracheinstellung beim Starten des Apache Tomcat nicht auf eine deutsche Umgebung verweist Dieses kann technische Probleme verursachen Unter Linux sollte die Einstellung (Umgebungsvariable) entsprechend auf LANG=de_DEUTF-8 eingestellt sein
216 Datenbankverbindung Wenn Sie eine Firewall zwischen dem Oracle-Server und dem Database Connection Pool (DBCP) verwenden sollte unbedingt die bdquovalidationQueryldquo in der DBCP-Konfiguration aktiviert werden damit die Anwendung schneller freie Connections aus dem Pool erhalten kann Die Dokumentation zu den Einstellmoumlglichkeiten ist in der beiliegenden Contextxml ergaumlnzt worden
Bitte beachten Sie dass dringende empfohlen wird die bdquoFactoryldquo auf orgapachetomcatjdbcpoolDataSourceFactory anzupassen falls sie noch auf bdquoorgapachecommonsdbcpBasicDataSourceFactoryldquo eingestellt ist
217 Probleme beim Anlegen von LOB-Objekten Der BALVI Schnittstellen-Server erfordert die JDBC-Spezifikation DBCP V4 welche durch die Factory bdquoorgapachetomcatjdbcldquo ab Tomcat 7 automatisch bereitgestellt wird
Wenn die Pooling-Komponente oder der Oracle-Treiber nicht JDBC4-Kompatibel sind gibt es beim Bearbeiten von LOB-Objekten in Java diverse Exceptions z B
Servletservice() for servlet soapws threw exception
javalangAbstractMethodError
orgapachecommonsdbcpPoolingDataSource$PoolGuardConnectionWrappercreateClob()LjavasqlClob
at debalvicoreauditspyConnectionSpycreateClob(ConnectionSpyjava511)
Ursache dieses Problems ist meistens dass noch nicht auf bdquoorgapachetomcatjdbcldquo umgestellt wurde
218 Umbenennung der gelieferten WAR-Datei Das im Paket von BALVI gelieferte WAR kann jederzeit umbenannt werden (z B als ROOTwar) ohne dass dabei spezielle Einstellungen in der Datei bdquocontextxmlldquo erforderlich sind
Beachten Sie dabei jedoch dass die zum WAR zugehoumlrige Datei bdquocontextxmlldquo im Apache Tomcat immer denselben Namen erhaumllt wie das WAR z B bdquocommserverwarldquo und bdquocommserverxmlldquo Der Name ist dabei ausschlaggebend fuumlr die Zugriffs-Adresse (Context) im Apache Tomcat selbst Die Benennung des WAR in bdquocommserverwarldquo wuumlrde folgendermaszligen aufzurufen sein httpserverportcommserver
219 Server-Schnittstellen Die Uumlberarbeitung bzw Erweiterung der Export- und Importschnittstellen welche uumlber den Schnittstellenserver bereitgestellt werden ist unabhaumlngig vom Schnittstellenserver selbst Die Schnittstellen sind daher nicht Bestandteile des Schnittstellenserver und werden je Verfahren separat
Release Notes BALVI Schnittstellenserver Seite 12 von 37
ausgeliefert Ggf ist es fuumlr unterschiedliche Schnittstellen erforderlich die Grant-Rechte zu aktualisieren (Vgl bdquoWann ist die Ausfuumlhrung des Grant-Skripts erforderlichldquo)
22 Kompatibilitaumltsliste Diverse Verfahren setzen eine Mindestversion des BALVI Schnittstellenservers voraus Die Schnittstellen sind jedoch so konzipiert dass eine Aktualisierung auf eine houmlhere Version des Servers ohne Anpassung an den vorhandenen Schnittstellen jederzeit moumlglich ist
Derzeit sind folgende Mindestanforderungen gegeben
1 BALVI mobil XT 170 oder houmlher setzt BSS 265 und BALVI iP 124x voraus
2 BALVI mobil XT 183 oder houmlher setzt BSS 281 und BALVI iP 124x voraus
3 BALVI mobil 2 (DM) setzt BSS 311 und BALVI iP 124x voraus
4 Die Schnittstelle eFI setzt BSS 251 und BALVI iP 122c voraus
5 Die Schnittstelle LIMS setzt BSS 265 voraus
6 Die Schnittstelle TSK (SN) setzt BSS 265 voraus
7 Die Schnittstelle xDomea (SN) setzt BSS 265 und Java 7 voraus
8 Die Schnittstelle XGewerbeanzeigen 11 setzt BSS 281 BALVI iP 124x Java 8 mit der bdquoJava
Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy2ldquo voraus
9 Die Schnittstelle XGewerbeanzeigen 12 (ab Paket 7 Ausbaustufe 3) setzt BSS 302 BALVI iP
124x Java 8 mit der bdquoJava Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policyldquo
voraus
10 Die Schnittstelle RioPP LM (NRW) setzt BSS 303 und die ETL-Konfiguration voraus
11 Die Schnittstellen zu BALVI iP2 (Fachmodule BTS LM ZDA Stand Juni 2017) setzen BSS 32x
voraus
2 httpwwworaclecomtechnetworkjavajavasedownloadsjce8-download-2133166html
Release Notes BALVI Schnittstellenserver Seite 13 von 37
23 Erforderliche Bibliotheken fuumlr Apache Tomcat Dateiname Funktion Quelle ojdbc6jar Oracle 11gR2 Clientpaket Oracle JDBC Client fuumlr Java
16 ersetzt die bisherige Version bdquoojdbc14jarldquo Die alte Library muss auf jeden Fall entfernt werden
httpwwworaclecomtechnetworkdatabaseenterprise-editionjdbc-112010-090769html
encrypted-datasource-110-alljar
Die Library muss auf jeden Fall entfernt werden Wird derzeit nicht weiter gepflegt da kein Interesse an der Funktionalitaumlt bestand
slf4j-api-1511jar slf4j-log4j12-1511jar log4jdbc4-12beta2jar
Entfaumlllt nicht mehr erforderlich Es wird empfohlen diese zu entfernen falls diese im LIB-Verzeichnis vorhanden sein sollten
commons-dbcp-14jar commons-pool-154jar
Entfaumlllt nicht mehr erforderlich Es wird empfohlen diese zu entfernen falls diese im LIB-Verzeichnis vorhanden sein sollten
Erwartet wird stattdessen ab Tomcat7 die mitgelieferte bdquotomcat-jdbcjarldquo
log4j-1217jar (oder houmlher)
Logging-Funktionalitaumlt Apache Log4j httploggingapacheorglog4j12downloadhtml
bcprov-jdk15on-157jar (oder houmlher)
BouncyCastle Security Provider fuumlr SSLAES hellip wird ab Version 27 im Ordner bdquolibldquo des Tomcat erwartet Sollte es aus Sicherheitsgruumlnden erwuumlnscht sein eine aktuellere Version einzusetzen ist dieses idR moumlglich
httpmvnrepositorycomartifactorgbouncycastlebcprov-jdk15on157
24 Datenbank-Installation Der BALVI Schnittstellenserver benoumltigt auszligerhalb des angebundenen BALVI iP keine eigenen Tabellen Die Web-Anwendung kann im einfachsten Fall direkt auf das Schema von BALVI iP zugreifen indem der Benutzer und das Passwort des BALVI iP-Schemas in der Datei bdquocontextxmlldquo eingetragen werden (nicht empfohlen)
Sollte dies aus Sicherheitsgruumlnden nicht erwuumlnscht sein (empfohlen vom BSI und von BALVI) finden Sie im Paket ein GRANT-Skript um Zugriffsrechte vom BALVI iP Schema fuumlr den Webservice-Schema-Benutzer einzurichten
Zwischen dem Schema von BALVI iP und jeder Web-Anwendung ist dann eine Trennung moumlglich um sicherzustellen dass der Datenbank-Benutzer welcher in der Tomcat-Konfiguration fuumlr die Web-Anwendung eingetragen wird geaumlndert oder geloumlscht werden kann ohne dass die Windows-Anwendung BALVI iP davon betroffen ist Zudem vergibt das von BALVI gelieferte Grant-Skript keine Rechte zum Loumlschen von Tabellenstrukturen oder Tabelleninhalten so dass der Webservice nur festgelegte Daten aumlndern oder lesen darf Es wird empfohlen je Web-Anwendung einen eigenen Datenbank-Benutzer zu vergeben wenn Sie ein BALVI iP mit mehreren Webservices verbinden wollen
Die Moumlglichkeiten im Uumlberblick
1) Sie betreiben den Webservice mit einem eigenstaumlndigen Oracle-Benutzer In diesem Fall muss das
Grant-Skript ausgefuumlhrt werden um den Webservice-Benutzer und den BALVI iP-Benutzer
miteinander zu koppeln
2) In der Tomcat-Konfiguration wird der Oracle-Benutzer eingetragen welcher auch der BALVI iP
Schemabesitzer ist und in der bdquobalviip_conninildquo hinterlegt ist (NICHT Empfohlen) Der Webservice
Release Notes BALVI Schnittstellenserver Seite 14 von 37
hat 100 Zugriffsrechte (auch Loumlsch- oder Aumlnderungsrechte am Schema) es wird kein Grant-
Skript benoumltigt
Wenn Sie die Konfiguration 2) waumlhlen moumlchten koumlnnen Sie die folgenden Unterkapitel uumlberspringen und in Kapitel 0 bzw fortsetzen
241 Erstinstallation Datenbank-Benutzer anlegen Wenn Sie den Webservice-Benutzer vom BALVI iP Schema trennen moumlchten muss durch die DB-Administration in der Oracle-Server-Instanz wo auch BALVI iP sein Schema besitzt ein Benutzer (ggf je Web-Anwendung) angelegt werden welcher folgende Rechte benoumltigt
CONNECT
ALTER SESSION
CREATE JOB
CREATE PROCEDURE
CREATE SESSION
CREATE TABLE
CREATE TRIGGER
CREATE TYPE
CREATE VIEW
CREATE SEQUENCE
CREATE SYNONYM
QUERY REWRITE
Der Default-Tablespace ist frei waumlhlbar Der Benutzer braucht das Recht QUOTA UNLIMITED auf den Tablespace von BALVI iP (Default BALVI_IP) Ein Beispiel-Create-Skript bdquooraCreate_WEB_Usersqlldquo liegt der Auslieferung bei
242 Rechte zuweisen Wenn der BALVI iP Schemabesitzer NICHT in der Tomcat-Umgebung eingetragen werden soll muss ein Oracle DBA das beiliegende GRANT-Skript bdquooraGrantIP_to_Websqlldquo ausfuumlhren um dem jeweiligen Webservice (in Tomcat verwendeten Oracle-Benutzer) die minimalen Rechte auf das Schema von BALVI iP zu gewaumlhren
Dieses Skript setzt voraus dass es von einem Oracle Administrator als bdquoUser SYSTEMldquo ausgefuumlhrt wird Lesen Sie die im Skript enthaltenen README-Kommentare und passen Sie die Benutzer (BALVI iP Schema) und (WEB-Schema) an
====================================================
DEKLARATIVER TEIL MUSS vom KUNDEN geaumlndert
bzw auf die korrekten SCHEMA-Namen angepasst
werden
Die USER-Namen muumlssen in Groszligbuchstaben
geschrieben sein sonst werden sie nicht
gefunden
====================================================
sUserBALVI_IP = BALVI_IP_SCHEMABESITZER
sUserBALVI_WEB = BALVI_WEB_SCHEMABESITZER
Release Notes BALVI Schnittstellenserver Seite 15 von 37
Neu ab Grant-Skript 158 ist die Umbenennung der Verfahrenszuordnung
Pruumlfen Sie dass die Einstellung fuumlr Ihr BundeslandVerfahren korrekt ist dort muss eine 1 fuumlr min ein Verfahren gesetzt sein Diese Einstellung befindet sich direkt unter den Schemabesitzer-Angaben
-- Verfahrensbezogene Konfiguration
-- Setzen Sie fuumlr das jeweilige Verfahren eine 1
-- BALVI Schnittstellenserver (BSS)
-- bis V266 auch BALVI Kommunikationsserver (BKS) genannt
-- generell fuumlr die meisten Verfahren guumlltig
-- Ab Version 57 entfaumlllt mit der Einfuumlhrung der
-- Schnittstelle XGewerbeanzeigen auch der separate Schalter
-- WS_BTR beide Verfahren wurden vereinheitlicht
WS_BSS = 1
Fuumlhren Sie das Skript nach der Anpassung als User SYSTEM aus um die Grants durchzufuumlhren Dieses wurde mit dem von ORACLE gelieferten Programm SQLPLUS (Command-Line) SQLPLUS Worksheet (GUI) und Oracle SQL-Developer getestet
Das Skript generiert fuumlr jedes Objekt ein SYNONYM fuumlr den WEB-USER so dass dieser auf die Objekte ohne Angabe des Owners des IP-Schemas zugreifen kann Pruumlfen Sie nach der Ausfuumlhrung dass die SYNONYMS vorhanden und VALID sind dieses kann ggf nicht der Fall sein Das Skript kann jederzeit erneut ausgefuumlhrt werden um die Grants neu zu erzeugen und bietet ebenfalls die Option alle Grants und Synonyme wieder zu entfernen Detaillierte Informationen zur Nutzung des Skripts sind als Kommentar-Block im Skript enthalten
Hinweis Die Versionsinformation ist unter den Kommentaren direkt im Skript zu finden
Zugriffsberechtigungen fuumlr Webanwendungen auf BALVI iP anlegen
===============================================================
Version 158
Guumlltig fuumlr BALVI iP 123 oder houmlher
Autor Frank Holler
SVN Revisionsinformationen
$Revision 479 $
$Date 2016-02-15 152755 +0100 (Mo 15 Feb 2016) $
================================================================
243 Wann ist die Ausfuumlhrung des Grant-Skripts erforderlich Durch das Strukturupdate von BALVI iP (z B 1240 auf 1241) werden veraltete Strukturen geloumlscht und ggf neue Views oder Tabellen angelegt Die Grant-Rechte geht dabei ggf verloren Daher ist die Ausfuumlhrung des Grant-Skripts immer dann erforderlich wenn sich die Datenbank-Struktur von BALVI iP veraumlndert
Zudem kann es fachliche Neuerungen geben welche im alten Grant-Skript nicht vorhanden sind Daher muss das Skript ggf auch ausgefuumlhrt werden wenn eine neue Schnittstelle im Schnittstellenserver bereitgestellt wurde Dieses betrifft z B auch die Bereitstellung von neuen Versionen von BALVI mobil XT
Release Notes BALVI Schnittstellenserver Seite 16 von 37
da auch dort mit einem fachlich erweiterten Client die Moumlglichkeit besteht dass neue Schnittstellen bereitgestellt und somit mehr Schreibrechte auf Tabellen benoumltigt werden
244 Welche Version des Grant-Skripts soll ich nehmen Wie der Schnittstellenserver sind auch die Grant-Skripte versioniert Neuere Versionen des Grant-Skriptes sind abwaumlrts-kompatibel und koumlnnen immer verwendet werden auch wenn in einer Schnittstellenbeschreibung eine aumlltere Version des Grant-Skriptes explizit benannt wurde
245 Kombination von mehreren Verfahren Wenn Sie zwei oder mehr Schnittstellen im BSS verwenden moumlchten ist es ggf erforderlich auch mehrere Verfahren auf aktiv (bdquo1ldquo) zu setzen
Im Beispiel nehmen wir an Sie moumlchten bdquoeFildquo und bdquoBALVI mobil XTldquo im Schnittstellenserver bereitstellen In der Beschreibung von bdquoeFildquo steht dass das Grant-Skript V36 erforderlich ist BALVI mobil XT 18 erfordert jedoch schon V56
Wenn Sie beide Verfahren betreiben ist im Grant-Skript (V56 oder houmlher) die Einstellung fuumlr beide Verfahren zu aktivieren
====================================================
DEKLARATIVER TEIL MUSS vom KUNDEN geaumlndert
bzw auf die korrekten SCHEMA-Namen angepasst
werden
Die USER-Namen muumlssen in Groszligbuchstaben
geschrieben sein sonst werden sie nicht
gefunden
====================================================
sUserBALVI_IP = BALVI_IP_SCHEMA
sUserBALVI_WEB = WEBAPP_SCHEMA
-- Verfahrensbezogene Konfiguration
-- Setzen Sie fuumlr das jeweilige Verfahren eine 1
-- BALVI Schnittstellenserver (BSS)
-- bis V266 auch BALVI Kommunikationsserver (BKS) genannt
-- generell fuumlr die meisten Verfahren guumlltig
-- Ab Version 57 entfaumlllt mit der Einfuumlhrung der
-- Schnittstelle XGewerbeanzeigen auch der separate Schalter
-- WS_BTR beide Verfahren wurden vereinheitlicht
WS_BSS = 1
-- WebService BTR (Betriebsstaumlttenregister) (NRW TH)
-- entfernt mit Update V57 setzen Sie stattdessen bei WS_BSS = 1
--WS_BTR = 0
-- Probenahme Futtermittel im Browser(BY)
WS_PROBE_FM = 0
-- Risikoorientierte Probenplanung Futtermittel ndash RIOPP FM (BY)
WS_RIOPP_FM = 0
-- Verfahren Export an EFi (Status Pilotbetrieb)
WS_EFI = 1
-- neu ab Version 35 des Grant-Skriptes ist die Moumlglichkeit den Webuser
Release Notes BALVI Schnittstellenserver Seite 17 von 37
-- fuumlr das Loumlschen der Ausgangskoumlrbe explizit zu berechtigen bzw sogar einen
-- expliziten abweichenden User festzulegen Die Konfiguration in der
-- Job-Oberflaumlche sieht vor dass man die Oracle-Datenbank-Zugangsdaten fuumlr
-- das Loumlschen einstellen muss Hier muss im Normalfall derselbe Oracle
-- Datenbankbenutzer eingetragen werden wie in der Tomcat-Verbindungs-
-- konfiguration In diesem Fall sollte wenn WS_EFI = 1 eingestellt wurde
-- ebenfalls WS_EFI_DELETE = 1 eingestellt werden
-- Alternativen
-- 1) Datenbankbenutzer aumlndern
-- Wenn bei sUserEFI_TRUNC anstatt sUserBALVI_WEB (Standard) ein anderer
-- Oracle-Benutzername angegeben wird wird das Loumlschrecht fuumlr die EFi
-- Ausgangskoumlrbe Datenbankseitig exklusiv dem angegeben Datenbankbenutzer
-- zugewiesen
-- 2) Loumlschrecht verweigern
-- Setzen Sie die Variablen WS_EFI_DELETE = 0 damit kein Loumlschrecht
-- zugeweisen wird
WS_EFI_DELETE = 0
-- Beispiel Anderer Benutzer muss in der Datenbank existieren
-- Entfernen Sie die fuumlhrenden -- vor der Variable sUserEFI_TRUNC und
-- setzen den entsprechenden Oracle-Benutzer ein
--sUserEFI_TRUNC = TEST_EFI_TRUNC
hellip
25 Konfiguration des Schnittstellen-Servers
251 Die bdquocontextxmlldquo-Parameter Die von der Servlet-Spezifikation vorgegeben Rump-Struktur sieht folgendermaszligen aus
ltxml version=10 encoding=utf-8gt
ltDOCTYPE Contextgt
ltContextgt
lt-- Kundenspezifische Einstellungen --gt
ltContextgt
Anwendungsspezifische Einstellungen werden zwischen ltContextgt und ltContextgt eingefuumlgt Alle allgemeinguumlltigen Einstellungen in der Datei bdquocontextxmlldquo werden hier erlaumlutert Kommentare finden sich auch in der von BALVI ausgelieferten Beispiel-Konfiguration
Neben den im Folgenden beschriebenen Standard-Einstellungen kann es auch vorkommen dass bundeslandspezifische Erweiterungen vorhanden sind welche nicht in dieser Dokumentation aufgefuumlhrt werden Diese funktionieren trotzdem regulaumlr weiter wenn keine expliziten Informationen zu Kompatibilitaumltsproblemen in den Release-Notes aufgefuumlhrt wurden
2511 Datenbankverbindung jdbcDataSource
Die Datenbankverbindung wird uumlber die von DBCP und dem Oracle-Treiber vorgegebenen Moumlglichkeiten realisiert Der Einsatz der orgapachetomcatjdbcpoolDataSourceFactory (automatisch verfuumlgbar ab Apache Tomcat 7 in der mitgelieferten tomcat-dbcpjar) wird als Beispiel-Konfiguration ausgeliefert
ltResource
name=jdbcDataSource
auth=Container
Release Notes BALVI Schnittstellenserver Seite 18 von 37
type=javaxsqlDataSource
factory=orgapachetomcatjdbcpoolDataSourceFactory
maxActive=10 initialSize=3
maxIdle=5
maxWait=10000
url=jdbcoraclethinBL2-ORA10-KUNDENBALVIINTERN1521ORCL
driverClassName=oraclejdbcdriverOracleDriver
username=balvi_webservice_schema
password=balvi_webservice_password
description=Oracle Datasource
maxOpenPreparedStatements=50
removeAbandoned=false
removeAbandonedTimeout=100
logAbandoned=true
jdbcInterceptors=hellip
gt
Hinweise zur Einstellung der jdbcDataSource
Standard-Einstellungen fuumlr den Datenbank-Verbindungspool
Der Verbindungspool muss entsprechend der Anzahl der zu erwartenden gleichzeitigen Benutzer konfiguriert werden Wenn Sie erwarten dass 50 Anwender gleichzeitig arbeiten stellen Sie bitte folgende Werte ein
maxActive=(50 + 10 (fuumlr System und Jobs)) = 60
maxIdle= (50 10) = 5
1 maxActive - maximale Anzahl der gleichzeitigen aktiven Anfragen an die DB
Wenn der Werte maxActive erreicht ist z B wenn mehrere Benutzer gleichzeitig einen Export starten moumlchten welcher laumlngere Zeit in Anspruch nimmt dann kann der Server die Anfrage nicht mehr bedienen und der Anwender wird abgewiesen maxActive hat zudem Auswirkungen auf die im Hintergrund ausgefuumlhrten Jobs maxActive wird daher kalkuliert mit der Anzahl der Anwender und moumlglicher Datenbank-Connections fuumlr Hintergrund-Jobs Jeder aktiv ausgefuumlhrte Job benoumltigt mindestens eine Connection nur selten wird aus Performance-Gruumlnden mehr als eine Connection waumlhrend der Job-Ausfuumlhrung verwendet Im Normalfall sollten daher 10 Connections fuumlr Hintergrundprozesse ausreichend sein
2 maxIdle - Anzahl der offenen Verbindungen auch wenn der Server im Leerlauf ist
Jede offene Verbindung im Leerlauf haumllt auf dem Datenbankserver eine Session offen Auch diese erfordert Ressourcen Wenn die Verbindungen jedoch geschlossen werden kann die Anfragezeit fuumlr eine neue Verbindung steigen da diese Verbindung erst neu ausgehandelt werden muss Die Empfehlung fuumlr den Wert bdquomaxIdleldquo ist ca 10 der Einstellung von maxActive
KeepAlive-Einstellungen fuumlr den Pool
1 validationQuery
Diese wird ausgefuumlhrt um die Verbindung zu DB zu validieren Es MUSS ein Datensatz zuruumlckgegeben werden ansonsten nimmt der DBCP an dass die Abfrage nicht erfolgreich abgesetzt wurde Achten Sie also bitte darauf dass die Abfrage nicht zu leitungsintensiv ist und genau einen Datensatz liefert
Release Notes BALVI Schnittstellenserver Seite 19 von 37
Oracle bietet dafuumlr die virtuelle Tabelle DUAL an welche sich fuumlr die ValidationQuery sehr gut eignet da die Abfrage kaum Ressourcen verbraucht
validationQuery=select 1 from dual
2 testOnBorrow - Boolscher Wert true oder false
Diese Einstellung sorgt dafuumlr dass der Pool die Verfuumlgbarkeit anhand der validationQuery pruumlft bevor
die DB-Verbindung an die Anwendung ausgeliehen wird Empfehlung
testOnBorrow=true
3 testWhileIdle - Boolscher Wert true oder false
Diese Einstellung ist hilfreich wenn zwischen dem Tomcat und der DB eine Firewall mit Stateful
Packet Inspection verwendet wird Nach laumlngerer Inaktivitaumlt wird normalerweise durch die Firewall die
DB-Verbindung geschlossen Dieses loumlst dann beim Ausleihen der Verbindung eine Fehlermeldung im
Protokoll aus 2012-08-16 165418720 WARN [http-0000-8080-8]
[orgspringframeworkjdbcsupportSQLErrorCodesFactory] Error while extracting
database product name - falling back to empty error codes
orgspringframeworkjdbcsupportMetaDataAccessException Error while extracting
DatabaseMetaData nested exception is javasqlSQLRecoverableException Getrennte
Verbindung Um dieses Problem zu beheben sollte die Option testWhileIdle=true eingestellt werden
testWhileIdle=true
Damit diese weiszlig wie oft eine Pruumlfung durchgefuumlhrt werden muss sind jedoch noch zusaumltzliche Angaben erforderlich welche fuumlr die Einstellung der Zeit zusaumltzlich gesetzt werden muumlssen
a) minEvictableIdleTimeMillis - Long in Millisekunden
Min Zeit wie lange eine DB-Verbindung im Leerlauf ist bevor diese zur Pruumlfung
gekennzeichnet wird Dieses haumlngt stark von der Einstellung der Firewall ab Wenn Sie eine
sehr restriktive Firewall haben kann es sein dass diese die Verbindung nach wenigen
Minuten Leerlauf trennt Stellen Sie den Wert immer so ein dass dieser unter der Leerlaufzeit
der Firewall liegt empfohlen 300000 entspricht 300 Sek = 5 min
minEvictableIdleTimeMillis=300000
b) timeBetweenEvictionRunsMillis - Long in Millisekunden
Der Pruumlflauf startet in der Default-Konfiguration alle 1800000 Millisekunden = 30 Min n als
zu Pruumlfen markierte Verbindungen werden in einem Pruumlflauf getestet n wird bestimmt durch
die Einstellung numTestsPerEvictionRun Empfehlung Stellen Sie den Wert auf alle 15 Min
ein
timeBetweenEvictionRunsMillis=900000
Release Notes BALVI Schnittstellenserver Seite 20 von 37
c) numTestsPerEvictionRun - Integer
Wie viele Verbindungen sollen getestet werden waumlhrend der Pruumlflauf ausgefuumlhrt wird Im
Normalfall sollte die Anzahl der zu testenden Verbindungen nicht zu hoch eingestellt werden
Der Default ist 3 Wenn Sie houmlhere Sicherheit haben wollen dass keine bdquototenldquo
Datenbankverbindungen bestehen bleiben erhoumlhen Sie den Wert auf max bdquo(maxActive ndash
maxIdle) 2ldquo Wenn Ihnen 3 ausreichend erscheint muss der Wert nicht gesetzt sein dann
wird der Default verwendet
Beispiel numTestsPerEvictionRun=10
4 Interceptors konfigurieren Neu ergaumlnzt wurde die Moumlglichkeit spezielle bdquoInterceptorsldquo zu konfigurieren die ermoumlglichen das Verhalten des Pools zu steuern Wichtig hierbei ist dass die Angabe von Werten auf real existierende Java-Klassen erfolgt die im Classpath des Tomcat vorhanden sind Groszlig-und-Kleinschreibung ist zu beachten Folgende Default-Einstellung hat BALVI fuumlr den BSS festgelegt jdbcInterceptors=
orgapachetomcatjdbcpoolinterceptorConnectionState
orgapachetomcatjdbcpoolinterceptorStatementFinalizer
orgapachetomcatjdbcpoolinterceptorResetAbandonedTimer
Details zu den verwendeten Interceptor-Einstellungen finden Sie in der Tomcat-Dokumentation3
3 httptomcatapacheorgtomcat-80-docjdbc-poolhtmlJDBC_interceptors
Release Notes BALVI Schnittstellenserver Seite 21 von 37
2512 Datenbank-Zugangsdaten verschluumlsseln
Die Verschluumlsselung fuumlr die Datenbank-Verbindung (bdquoEncrypted Datasourceldquo) ist eine Ableitung der Bibliothek Apache-Common-DBCP-14 und daher nicht mehr mit Java 8 kompatibel Die Einrichtung der Verschluumlsselung wird daher mit der Auslieferung des BSS 30 nicht mehr angeboten
2513 Active-Directory-Authentifizierung
Uumlber die folgenden Parameter wird der Zugriff des Schnittstellen-Servers auf einen Microsoft Active Directory Domain-Controller konfiguriert
ldquoldapServerAddressrdquo
Syntax PROTOKOLLIP-Adresse oder DNS-NamePORT
ltEnvironment
name=ldapServerAddress
value=ldapbl2-dc02balviintern389
type=javalangString
override=true
gt
Als Protokoll besteht auch die Moumlglichkeit ldaps (LDAP+SSL) wenn der Domain-Controller entsprechend konfiguriert wurde Im Java Truststore muss dann das Zertifikat der CA vorhanden sein welche das Zertifikat des Domain-Controllers signiert hat Zudem darf bei ldaps keine IP-Adresse verwendet werden es muss der DNS-Name des Server-Zertifikats eingetragen sein Ansonsten gibt es beim Verbinden eine Sicherheits-Exception
lt-- SSL-Beispiel
ltEnvironment
name=ldapServerAddress
value=ldapsbl2-dc02balviintern636
type=javalangString
override=true
gt
--gt
bdquoldapBaseDnrdquo
LDAP-Suchpfad fuumlr die Domain-Basis Diese muss der LDAP-Syntax fuumlr den Domain-Suffix entsprechen
Syntax DC=SERVERDC=ROOTDN
ltEnvironment
name=ldapBaseDn
value=DC=BALVIDC=INTERN
type=javalangString
override=true
gt
Release Notes BALVI Schnittstellenserver Seite 22 von 37
bdquowebLoginUseActiveDirectoryAuthenticationrdquo
Die Authentifizierung in der Browser-Oberflaumlche kann uumlber die Active-Directory-Authentifizierung erfolgen In der ersten Version ist nur die Protokoll-Auswertung moumlglich wenn der ADMIN sich anmeldet Dieser hat normalerweise niemals AD-Kennungen zugeordnet BALVI empfiehlt diese Einstellung auf bdquofalseldquo zu belassen Webservices welche uumlber SOAPREST zugreifen koumlnnen die Active-Directory-Authentifizierung trotzdem verwenden
ltEnvironment
name=webLoginUseActiveDirectoryAuthentication
value=false
type=javalangBoolean
override=true
gt
ldquoldapDaysBeforeExpirationNotificationrdquo
Die Passwort-Aumlnderung im Active-Directory uumlber die Browser-Oberflaumlche ist in der ersten Version noch nicht implementiert der Parameter wird bislang nicht ausgewertet
ltEnvironment
name=ldapDaysBeforeExpirationNotification
value=14
type=javalangInteger
override=true
gt
2514 Statement-Protokollierung in BALVI iP
Diese Option aktiviert die Lese- und Aumlnderungsprotokollierung fuumlr BALVI iP Standard ist bdquofalseldquo und wird fuumlr alle Kunden empfohlen solange keine speziellen Datenbank-Jobs eingerichtet wurden welche zeitgesteuert die Protokolleintraumlge wieder loumlschen Fuumlr Bayern wurde ein spezielles Konzept zur Leseprotokollierung entworfen Wenn Sie mehr daruumlber erfahren moumlchten kontaktieren Sie bitte die BALVI GmbH
ltEnvironment
name=enableSqlStatementMonitoring
value=true
type=javalangBoolean
override=true
gt
Beachten Sie dass diese Option massive INSERT-Statements in BALVI iP in die Tabelle VIS_D92 ausfuumlhrt Jedes abgesetzte SQL-Statement wird dabei vollstaumlndig protokolliert Dieses erzeugt eine sehr hohe INSERT-Last und in der Folge auch erhoumlhte Redolog-Switches und COMMIT-Transaktionen
Optional Aktivieren der INSERT + APPEND - Logik
Beachten Sie bitte die Hinweise von Oracle zum Hint + APPEND
Release Notes BALVI Schnittstellenserver Seite 23 von 37
Wenn Sie dieses Verhalten aktivieren moumlchten ergaumlnzen Sie bitte den folgenden Environment-Parameter
ltEnvironment
name=statementMonitoringactivateAppendMode
value=true
type=javalangBoolean
override=true
gt
2515 Einstellungen fuumlr BALVI mobil XT (bzw den bdquopartitionedExportldquo)
Diese Logik des FIFO-Buffers wurde so konzipiert dass dem Rechenzentrum diverse Einstellmoumlglichkeiten uumlber die Datei bdquocontextxmlldquo zur Verfuumlgung stehen um die Steuerung des FIFO-Puffers zu beeinflussen
Schematische Darstellung des FIFO-Puffers
Das ermoumlglicht es z B dem BALVI mobil XT Client (14 oder houmlher) den aktiven Block abzuholen und dies beim Fehler bis zu 10-mal zu wiederholen Sobald der Block [001] erfolgreich beim Client angekommen ist und dieser den naumlchsten Block anfragt wird der Block [001] verworfen wird Der Server fuumlllt dann im Hintergrund den frei gewordenen Block wieder waumlhrend der Client den Block [002] abholt
Die Groumlszlige und Anzahl der vorgecachten Bloumlcke kann uumlber die folgenden Einstellungen in der Datei bdquocontextxmlldquo definiert werden
ltEnvironment
name=partitionedExportmaxBufferedPartitions
value=3 type=javalangInteger override=true
gt
ltEnvironment
name=partitionedExportpartitionSize
value=256000 type=javalangInteger override=true
gt
Die Einstellung partitionedExportmaxBufferedPartitions ist dabei die Anzahl der vorgecachten Bloumlcke mindestens muss 2 angegeben werden Der Puffercache wird ausschlieszliglich im RAM der JVM aufgebaut es wird folglich mehr Arbeitsspeicher verwendet Dieser Arbeitsspeicher muss je gleichzeitiger Session auf dem Server bereitgestellt werden die Default-Einstellung mit 3 Partitionen a 256 KB + dem aktiven Puffer erfordern 1 MB RAM je aktiven Anwender
Aktiv
er
Puffe
r
[001] Vorg
ecac
hter
Bl
ock
[002] Vorg
ecac
hter
Bl
ock
[003]
Aktiv
er P
uffe
r
[002] Vorg
ecac
hter
Bl
ock
[003] Vorg
ecac
hter
Bl
ock
[leer]
Release Notes BALVI Schnittstellenserver Seite 24 von 37
Gleichzeitig wurde die Moumlglichkeit geschaffen dass die maximale Anzahl an gleichzeitigen Exporten durch das Rechenzentrum eingeschraumlnkt werden kann um einem OutOfMemory-Fehler vorzubeugen Die Einstellung
ltEnvironment
name=partitionedExportmaxConcurrentExports
value=10 type=javalangInteger override=true
gt
muss entsprechend der zu erwartenden gleichzeitigen Zugriffe konzipiert werden ansonsten wird der Server einen Verbindungsversuch durch die Clients ablehnen
Beachten Sie dass die folgenden Einstellungen partitionedExportmaxBufferedPartitions partitionedExportmaxConcurrentExports und partitionedExportpartitionSize gemeinsam als Rechenbasis fuumlr den RAM-Bedarf des Webservers herangezogen werden muumlssen
Folgende Faustformel sollte fuumlr die Einrichtung verwendet werden
Min 256 MB (Serverbasis) + (11 partitionedExportmaxConcurrentExports partitionedExportmaxBufferedPartitions partitionedExportpartitionSize)
Beispiel 50 gleichzeitige Anwender Blockgroumlszlige 256 KB 4 Partitionen
256 MB + (11 50 256 4) KB = 312 MB fuumlr die JVM
Empf 512 MB (Serverbasis) + (12 partitionedExportmaxConcurrentExports partitionedExportmaxBufferedPartitions partitionedExportpartitionSize)
Beispiel 50 gleichzeitige Anwender Blockgroumlszlige 256 KB 4 Partitionen
512 MB + (12 50 256 4) KB = 572 MB fuumlr die JVM
partitionedExportmaxConcurrentExports
Bestimmt die Anzahl der maximalen Export Tasks (Threads) die fuumlr partitionierte Exporte bereitgestellt werden Wenn die Anzahl uumlberschritten wird wird die entsprechende Exportanfrage abgewiesen und der Client muss zu einem spaumlteren Zeitpunkt erneut anfragen Stellen Sie diesen Wert entsprechend der zu erwartenden Benutzeranzahl ein bei 50 Anwendern also 50
Exporte oumlffnen auf der Datenbank entsprechend zur Ausfuumlhrungszeit min einen Cursor ggf fuumlr rekursive Unterabfragen kurzfristig sogar mehr Die hier eingestellte Anzahl muss mit der Anzahl von maxActive korrelieren
ltEnvironment
name=partitionedExportmaxConcurrentExports
value=10 type=javalangInteger override=true
gt
partitionedExportmaxBufferedPartitions
Bestimmt die Anzahl der Datenbloumlcke (Partitionen) die vom Server bei Abruf eines Exportes gepuffert werden Die seit Version 24 eingefuumlhrte FIFO-Puffer-Logik ermoumlglicht dass der Server schon die Ergebnisse vorpuffert so dass der Client weniger Wartezeiten bei der Anfrage nach Daten hat Diese
Release Notes BALVI Schnittstellenserver Seite 25 von 37
Puffer-Logik unterteilt den Exportdatenstrom (je Export) in mehre Bloumlcke Der Client kann nun den letzten Block neu anfordern oder den naumlchsten Block wenn der letzte Block erfolgreich verarbeitet wurde Wie viele naumlchste Bloumlcke durch den Server bereit gestellt werden entscheidet diese Einstellung Sobald kein naumlchster Block mehr bereit gestellt werden muss wird der Datenbank-Cursor geschlossen eine Erhoumlhung kann also zu einer Entlastung der aktiven DB-Verbindungen fuumlhren erhoumlht jedoch den Bedarf an RAM des Servers
Der von BALVI voreingestellte Wert ist 3
ltEnvironment
name=partitionedExportmaxBufferedPartitions
value=3 type=javalangInteger override=true
gt
partitionedExportpartitionSizeldquo
Die Groumlszlige der Datenbloumlcke (Partitionen) die an den Client uumlbermittelt werden in Bytes Wenn Sie diesen Wert zu niedrig einstellen reduziert sich die Effizienz des Caches da der Client mehr Datenbloumlcke hintereinander abrufen muss Waumlhlen Sie einen zu groszligen Wert wird die neu zu uumlbertragende Datenmenge im Fall eines Fehlers houmlher
Der von BALVI voreingestellte Wert ist 256000 (256 KB)
ltEnvironment
name=partitionedExportpartitionSize
value=256000 type=javalangInteger override=true
gt
exportTokensmaxTokenCount
Maximale Anzahl der gleichzeitig vergebenen Token die vom Server gecached werden Jede Sitzung welche einen Export durchfuumlhrt erhaumllt einen Session-Token
Wenn eine Sitzung laumlngere Zeit nicht verwendet wurde wird dieser Session-Token wieder entfernt Wenn Sie den Wert zu niedrig einstellen fuumlhrt das zu einer generellen Session-Begrenzung auch fuumlr den nicht partitionierten Export-Modus welcher ab Version 21 verfuumlgbar ist
Ist die Anzahl der Tokens houmlher als die Datenbankeinstellung maxActive kann es vorkommen dass zwar eine Session gestartet werden kann jedoch kein Datenexport zustande kommt
Der von BALVI voreingestellte Wert ist 2000
ltEnvironment
name=exportTokensmaxTokenCount
value=20 type=javalangInteger override=true
gt
exportTokenstokenExpirationInSeconds
Zeit in Sekunden die verstreichen muss bis ein Token unguumlltig wird falls darauf kein Zugriff mehr erfolgt Nach einem erfolgreichen Export wird der Token automatisch geschlossen diese Option ist fuumlr den Abbruchfall vorgesehen Der von BALVI voreingestellte Wert ist 180 (180 s = 3 min)
Release Notes BALVI Schnittstellenserver Seite 26 von 37
ltEnvironment
name=exportTokenstokenExpirationInSeconds
value=180 type=javalangInteger override=true
gt
exportTokenstokenDisposalInSeconds
Zeit in Sekunden die verstreichen muss bis ein Token das erfolgreich abgearbeitet wurde aus dem Cache geloumlscht wird Um sicher zu stellen dass der letzte Exportblock noch erfolgreich abgerufen werden kann bleibt der Token auch nach Fertigmeldung des Clients noch N Sek guumlltig
Der von BALVI voreingestellte Wert ist 60 (60 s = 1 min)
ltEnvironment
name=exportTokenstokenDisposalInSeconds
value=60 type=javalangInteger override=true
gt
2516 Job-Verwaltung fuumlr den BSS konfigurieren Aktivierung der Jobverwaltung
Bis zur Version 28 des BSS gab es den Parameter bdquoavailableServicesldquo Dieser konnte bei Bedarf aktiviert werden wenn die Jobs benoumltigt wurden
Mit Version 30 ist die Einstellung bdquoavailableServicesldquo zu entfernen und kann durch den neuen optionalen Parameter bdquoisJobServiceEnabledldquo in der Datei bdquocontextxmlldquo ersetzt werden
lt-- Neue Parameter zur Aktivierung des Job Service Ersatz fuumlr availableServices --gt
ltEnvironment
name=isJobServiceEnabled
value=true
type=javalangBoolean
override=true
gt
Ab BSS 30 wird die Jobs-Engine standardmaumlszligig aktiviert Sollte die Jobs-Engine nicht benoumltigt werden muss bdquovalueldquo der Wert bdquofalseldquo zugewiesen werden Wird bdquoisJobServiceEnabledldquo nicht eingefuumlgt sind die Jobs trotzdem standardmaumlszligig aktiv
Nach dem Neustart des Servers und erneutem Einloggen erscheint nun zusaumltzlich der Menuumlpunkt bdquoJobsldquo
bdquopasswordKeyldquo fuumlr Jobs
In der Job-Logik wird ein von BALVI definierter Standard-Schluumlssel fuumlr die Ablagen von schuumltzenswerten Daten z B Passwoumlrtern verwendet Diese Einstellung ermoumlglicht den BALVI-Standard zu uumlberschreiben Wenn Sie diese Einstellung aumlndern muumlssen jedoch alle bislang verschluumlsselten Job-Parameter neu verschluumlsselt werden
ltEnvironment
name=javacompenvjobspasswordKey
value=MeinHochsicheresNeuesPasswort
type=javalangString
Release Notes BALVI Schnittstellenserver Seite 27 von 37
override=true
gt
bdquoJob ID enableddisabledldquo (Deprecated ersetzt ab 28 durch das bdquoBindenldquo von Jobs)
Sondereinstellungen fuumlr die Job-Verwaltung Da alle Jobs in einer Datenbank administriert werden jedoch ggf verteilt auf mehreren Tomcat-Servern ausgefuumlhrt werden sollen besteht hier die Option Jobs fuumlr die aktuelle Tomcat-Instanz separat zu deaktivieren
Die Einstellung ID koumlnnte z B folgendermaszligen aussehen javacompenvjobsC0DB58D8D52C4BBC966D1DC788A4EF8Benabled
Fuumlr weitere Fragen zu dieser Einstellung kontaktieren Sie bitte die BALVI GmbH
ltEnvironment
name=javacompenvjobsIDenabled
value=false
type=javalangBoolean
override=true
gt
2517 Weitere optionale Parameter
Es ist fuumlr diverse einzelne Schnittstellen ggf erforderlich Einstellungen in der Datei bdquocontextxmlldquo zu ergaumlnzen Hinweise zu diesen Parametern sind dann in dem der Schnittstelle beiliegenden Dokument enthalten Das gilt z B fuumlr die Schnittstelle bdquoXGewerbeanzeigenldquo
26 Logging mit logback Das Logging wurde komplett uumlberarbeitet Statt bdquoLog4Jldquo wird jetzt bdquologbackldquo4 benutzt Ab BSS 30 ist es zwingend notwendig die Einstellung vorzunehmen um das Logging der Anwendung zu steuern
Migration Ergaumlnzen Sie die neue Einstellung bdquologgingconfigldquo
lt-- Neue Paramter zur Angabe der Logback Config Ersatz fuumlr log4jConfigLocation --gt
ltEnvironment
name=loggingconfig
value=$catalinabaseconflogback-bssxml
type=javalangString
override=true
gt
Nach wie vor steht es Ihnen frei die Logging-Konfiguration eigenstaumlndig anzupassen
Wenn Sie jedoch dieselbe WAR in einer Tomcat-Instanz unter mehreren Context-Namen betreiben wuumlrden beide dieselbe Logging-Konfiguration verwenden so dass alle Protokolleintraumlge in einer Log-Datei aus
4 httplogbackqoschmanualappendershtml
Release Notes BALVI Schnittstellenserver Seite 28 von 37
mehreren Webanwendungen generiert werden Aumlndern Sie den Namen der Logging-Konfiguration entsprechend ab um fuumlr jede Anwendung eine spezifische Logging-Einstellung vornehmen zu koumlnnen
27 Tocmat Optional Suche im bdquoKlassenpfadldquo um den
Ordner bdquoconfldquo erweitern Die Suche nach Dateien uumlber bdquoclasspathldquo setzt voraus dass die Ordner- und Dateinamen im Apache Tomcat bekannt gegeben werden Der Klassenpfad kann in der Datei bdquocatalinapropertiesldquo angepasst werden Wenn Sie dort unter commonloader die folgenden Werte ergaumlnzen kann eine Datei auch im Ordner conf abgelegt werden damit Apache Tomcat diese findet Ansonsten muss die Datei im Ordner lib abgelegt werden
commonloader=$catalinabaseconf$catalinahomeconf
3 Die neue Browser-Oberflaumlche Der BALVI Schnittstellenserver hat seit Version 25 neben der Protokollierung auch die Moumlglichkeit Job-Konfigurationen zu pflegen Der Login ist nur fuumlr einen in BALVI iP eingetragenen ADMIN (z B Benutzer bdquoSYSTEMADMINldquo) mit dem in BALVI iP hinterlegten Passwort moumlglich Zur Anmeldung muss immer [SYSTEMBenutzername] im Feld Benutzer angegeben werden ansonsten schlaumlgt die Anmeldung fehl Bitte achten Sie darauf dass der bdquoldquo (Slash) und nicht der bdquoldquo (Backslash) verwendet werden muss
31 Server-Protokoll Um das Server-Protokoll anzuzeigen waumlhlen Sie den entsprechenden Menuumlpunkt Dort haben Sie seit BSS 26 die Moumlglichkeit uumlber alle Spalten der Protokolle nach Informationen zu suchen
Seit BSS 31 gibt es die Moumlglichkeit Verfahren in bdquoKopfsaumltzeldquo und bdquoDetailsaumltzeldquo zu unterteilen Wurde das Verfahren entsprechend konfiguriert (wie z B bei der Schnittstelle bdquoXGewerbeanzeigenldquo) dann wird im Protokoll-Kopfsatz nur der Start und das Ende der Ausfuumlhrung in der Liste angezeigt Erst bei einem Klick auf bdquoInformationenldquo wird die Liste aller Detailsaumltze angezeigt die im Durchlauf erzeugt wurden
Release Notes BALVI Schnittstellenserver Seite 29 von 37
Verfahren
Die Liste der verfuumlgbaren Verfahren die bei Ihnen im System installiert sind ZB
BEFUNDEhellip Schnittstelle Befunde LM FM oder TS
PROBEhellip Schnittstelle zum Export von Proben an Labore ebenfalls Spezifisch fuumlr einzelne Fachbereiche
MOBILXT Protokolle der BALVI Mobil XT Synchronisation
WEB Allgemeine nicht spezifizierte Protokolle hierunter ist bislang auch die eFi-Protokollierung zu finden
WEB_I0802 Protokolle zur Schnittstelle BALVI iP LIMS (Lebensmittelproben)
XGEWERBE Schnittstelle XGewerbeanzeigen
Klicken Sie auf die Schaltflaumlche so besteht bei den neuen Protokolldatensaumltzen die Moumlglichkeit Detail-Informationen zum Protokollsatz zu erhalten
Release Notes BALVI Schnittstellenserver Seite 30 von 37
Seit BSS 30x ist die Anzeige der Protokolle ebenfalls farblich abgesetzt so dass Protokolleintraumlge mit Fehlern hellrot und Warnungen hellgelb hinterlegt werden
32 Jobs Mit einem Klick auf den Menuumlpunkt Jobs rufen Sie die Oberflaumlche fuumlr die Job-Konfiguration auf Daraufhin werden alle Jobs aufgelistet die fuumlr den BSS freigegeben sind Hier koumlnnen Sie Einstellungen an den Jobs vornehmen und die Jobs aktivieren bzw deaktivieren Die Beschreibungen bzw Einstellungsmoumlglichkeiten fuumlr den jeweiligen SST-Job sind nicht Bestandteil dieser Dokumentation
33 Log-Ausgaben Uumlber den Menuumlpunkt Log-Ausgaben koumlnnen Sie die Ausgabe der Protokolleintraumlge in Echtzeit beobachten
Release Notes BALVI Schnittstellenserver Seite 31 von 37
Starten Sie die Echtzeit-Protokollierung indem Sie auf die Schaltflaumlche mit dem Symbol bdquoPlayldquo (Dreieck) klicken unterbrechen Sie die Ausgabe indem Sie die auf Schaltflaumlche mit dem Symbol bdquoPauseldquo (zwei Balken) klicken
Klicken Sie auf die Schaltflaumlche bdquoAktualisierenldquo (zwei Pfeile) um die neuesten Protokolleintraumlge angezeigt zu bekommen
Klicken Sie auf das Symbol mit dem Papierkorb um die letzten Protokollmeldungen in der Anzeige zu loumlschen
Die Daten in den Protokolldateien auf der Festplatte des Servers sind davon nicht betroffen
Uumlber das Symbol bdquoLogging anpassenldquo (Schraubenschluumlssel) koumlnnen Sie die Ausgabe der Daten im Echtzeitfenster und in den Protokolldateien aumlndern jedoch ist diese Einstellung nur temporaumlr Die Standardeinstellungen koumlnnen ausschlieszliglich uumlber die Anpassung der Datei bdquologback-bssxmlldquo im Konfigurationsverzeichnis des Servers selbst geaumlndert werden
Release Notes BALVI Schnittstellenserver Seite 32 von 37
In der Logging-Parameter Konfiguration koumlnnen Sie verschiedene Parameter einstellen und uumlber die Schaltflaumlche bdquoAnwendenldquo dann sofort im Echtzeitprotokoll sehen Welche Einstellungen moumlglich sind erfahren Sie wenn es eine akute Fehlersituation gibt die detailliertere Ausgaben im Protokoll erfordert
Warnung Wenn Sie den Log-Level fuumlr ROOT oder eine andere Klasse auf TRACE einstellen werden sehr viele Protokollausgaben generiert die auch dazu fuumlhren koumlnnen dass der Server sehr langsam wird oder die Festplatte des Servers zulaumluft wenn fuumlr das Logging kein Dateilimit konfiguriert wurde
34 LogoutAbmeldung vom System Zum Abmelden waumlhlen Sie oben rechts das Kontextmenuuml
35 Cache loumlschen Der Cache wird in der Regel automatisch geloumlscht Wenn Sie jedoch gerade in BALVI iP eine Aumlnderung an den Schnittstellen eingespielt haben und moumlchten dass diese sofort wirksam wird kann die Funktion bdquoCache loumlschenldquo dazu verwendet werden dass der BALVI Schnittstellenserver die Einstellungen bei der naumlchsten Anfrage neu einliest
Release Notes BALVI Schnittstellenserver Seite 33 von 37
Release Notes BALVI Schnittstellenserver Seite 34 von 37
4 Einrichtung in BALVI iP Um die Verfahren fuumlr den BALVI Schnittstellenserver fuumlr Anwender freizuschalten wird das Objekt bdquoSystemeinstellungenldquo oder bdquoMandanten- und Benutzereinstellungenldquo verwendet Die Anpassung ist je Verfahren moumlglich so kann in BALVI iP fuumlr den Zugriff durch den BALVI Schnittstellenserver ein Benutzer bdquoAldquo am Verfahren bdquoMobilldquo berechtigt werden ein Benutzer bdquoBldquo nur am Verfahren bdquoSLA_FLESHldquo usw Die Logik ist jedoch einheitlich Je Verfahren wird durch BALVI eine Verfahrensgruppe mit dem Verfahrensnamen angelegt und mit den entsprechenden Einstellungen vorkonfiguriert welche durch das Verfahren erforderlich sind Dabei kann die Komplexitaumlt der Einstellungen variieren wie z B an den zu Version 23 verfuumlgbaren Verfahren bdquoMobilldquo und bdquoSLA_Fleshldquo ersichtlich wird
Im Verfahren BALVI Mobil sind diverse Anpassungen moumlglich welche je Bundesland oder eingesetzter Import- und Export-Variante durch den BALVI Schnittstellenserver bei der Bearbeitung von Anfragen gepruumlft werden siehe Punkt 3 Abb Mobil-Einstellung in BALVI iP
Abb Mobil-Einstellung in BALVI iP
Alle Verfahren verwenden jedoch die regulaumlre Benutzerverwaltung von BALVI iP Ein Benutzer ohne Passwort gilt fuumlr BALVI iP als gesperrt was fuumlr das Login bedeutet dass der Anwender sich nur uumlber die Active-Directory-Authentifizierung anmelden kann Ist das nicht moumlglich (bzw nicht konfiguriert) kann der Anwender sich weder in BALVI iP noch uumlber die Webservice-Schnittstelle authentifizieren
Fuumlr Dienste-Schnittstellen welche keine persoumlnliche Authentifizierung durch einen Anwender erfordern wird empfohlen einen separaten Benutzer in der Benutzerverwaltung anzulegen und ein sicheres Kennwort zu vergeben Das Anlegen von zusaumltzlichen Benutzern gilt nicht fuumlr BALVI mobil XT da beim Holen und Uumlbermitteln von Daten jeder Benutzer auch ein fachlich konfigurierter Anwender innerhalb von BALVI iP ist und die Anwendungsoberflaumlche ebenfalls zur Erfassung von Daten verwendet
Unter Punkt 2 der Abb Mobil-Einstellung in BALVI iP wird ein modales Fenster geoumlffnet (Abb BALVI mobil Benutzerverwaltung) Innerhalb dieses modalen Fensters werden mandantenweise die Benutzer fuumlr BALVI
Release Notes BALVI Schnittstellenserver Seite 35 von 37
mobil und den jeweiligen Fachbereich festgelegt Dabei ist es wichtig dass man die Haken bdquoAktiv fuumlr hellipldquo bei bdquohellip mobilldquo und bei einem Fachbereich (bdquohellip LMldquo bdquohellip FMldquo usw) setzt weil sonst uumlber den BALVI Schnittstellenserver keine Kommunikation mit BALVI iP moumlglich ist
Abb BALVI mobil Benutzerverwaltung
Alternativ zur Passwort-Authentifizierung wird wie beschrieben auch die Active-Directory-Authentifizierung angeboten Dazu muss der BALVI iP-Anwender uumlber die Schaltflaumlche bdquoDomaumlnen-Benutzer zuordnenldquo mit dem Active Directory verknuumlpft werden
Nur wenn die Active-Directory-Konfigurationen in BALVI iP und im BALVI Schnittstellenserver auf dieselbe Domaumlne verweisen sind die Domaumlnen-Zuordnung und die Active-Directory-Authentifizierung (z B uumlber BALVI mobil XT) moumlglich
Release Notes BALVI Schnittstellenserver Seite 36 von 37
5 Bekannte Probleme und Loumlsungen
51 ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner Bei der Job-Bearbeitung tritt folgender Fehler auf ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner
Behebung
Fuumlhren Sie das beiliegende IP-Patch (UPDATEexe) aus bevor Sie das WAR austauschen
52 Server startet nicht Sie finden folgende Zeilen im Protokoll (catalinaout oder bsslog)
ERROR [localhost-startStop-1] [IdentityServiceImpl] serverID must not be empty
ERROR [localhost-startStop-1] [ContextLoader] Context initialization failed
Behebung
Setzen Sie die Umgebungsvariable ldquoserverIDrdquo in der Datei bdquocontextxmlldquo
53 ORA-00942 table or view does not exist In vielen Faumlllen wird der Fehler ldquoTabelle oder View nicht vorhandenrdquo ausgeworfen (Java-Protokoll im Ordner logs von Apache Tomcat) wenn eine neue Schnittstelle eingerichtet oder ein neues BALVI iP Release bzw Update eingespielt wurde ohne anschlieszligend das aktuelle GRANT-Skript auszufuumlhren
Behebung
Fuumlhren Sie das GRANT-Skript erneut aus
54 ORA-0406x bdquoBestehender Paketstatus wurde aufgehobenldquo
ORA-04061 Bestehender Status von package body ABCXYZ wurde annulliert
ORA-04065 Ausfuumlhrung nicht erfolgreich package body ABCXYZ wurde geaumlndert oder geloumlscht
Release Notes BALVI Schnittstellenserver Seite 37 von 37
Der Fehler tritt haumlufig ein nachdem die UPDATEexe ausgefuumlhrt und in der Ausfuumlhrungsliste ein Package aktualisiert wurde Oracle merkt sich je User-Session bestimmte Werte im Package wenn der Anwender es verwendet hat Durch einen bdquoCREATE OR REPLACE PACKAGEldquo-Befehl kann dieser Status temporaumlr aufgehoben werden Normalerweise tritt dieser Fehler nach dem Update genau einmal in jeder aktiven Session auf wenn der BSS nicht neu gestartet wird
Behebung
Starten Sie nach jedem Update den BSS neu um alle laufenden Sessions zu beenden
55 Jobs sind nicht ausfuumlhrbar
1 Ein Job wird mit dem Status bdquoNicht unterstuumltztldquo angezeigt wenn fuumlr seine Ausfuumlhrung eine houmlhere Version des BSS erforderlich ist
2 Nach dem Klonen der Datenbank von der Produktions- auf die Testumgebung erhalten alle Jobs automatisch den Status bdquoDeaktiviertldquo wenn die bdquoserverIDldquo nicht identisch ist
Beide Statusaumlnderungen sind gewollt Damit soll verhindert werden dass Jobs nach einem Serverneustart oder nach einem Update automatisch starten und dabei Fehler verursachen
Um Jobs mit dem Status bdquoNicht unterstuumltztldquo nutzen und konfigurieren zu koumlnnen ist es erforderlich den BALVI Schnittstellenserver zu aktualisieren
Deaktivierte Jobs koumlnnen Sie aktivieren indem Sie den jeweiligen Job an den aktuellen Server binden und den Haken bei bdquoAktivldquo setzen
Release Notes BALVI Schnittstellenserver Seite 10 von 37
214 Nutzung von Java-Proxyeinstellungen Der BALVI Schnittstellenserver verwendet fuumlr ausgehende Verbindungen die Java-Net Einstellungen welche in der Java-Dokumentation1 beschrieben sind Falls Sie Jobs einsetzen welche ausgehenden Zugriff auf Adressen im Internet benoumltigen kann es passieren dass Sie z B eine bdquojavanetUnknownHostExceptionldquo im Protokoll finden dann muumlssen Sie ihre Proxy-Umgebung in den Java-Umgebungseinstellungen ergaumlnzen
Die folgenden Parameter sollten daher in Ihrer Umgebung gesetzt werden wenn der Zugriff auf das Internet nur uumlber einen Proxy moumlglich ist
-DproxySet=true
-DproxyHost=10111213
-DproxyPort=8888
-DhttpnonProxyHosts=domainorg|localhost|10
Starten Sie nach Aumlnderung der Einstellungen den Server neu damit die Einstellungen wirksam werden
2141 Proxy-Einstellung unter Windows (Tomcat-Dienst)
Verwenden Sie das Dienste-Konfigurationsprogramm (z B tomcat7wexe) und ergaumlnzen Sie die fehlenden Einstellungen
2142 Proxy-Einstellung unter Linux
In Linux wird in der Konfigurationsdatei (z B conftomcat7conf) die Variable bdquo$JAVA_OPTSldquo entsprechend erweitert und die Werte uumlbergeben Beachten Sie dabei dass die Variablen von Linux (bzw der Bash) gelesen werden Daher muss das bdquoPipeldquo-Zeichen bdquo|ldquo mit bdquoldquo maskiert werden ansonsten erhalten Sie bei der Verarbeitung der Umgebungsvariable bdquohttpnonProxyHostsldquo Fehlermeldungen in der Linux -Konsole welche dazu fuumlhren dass Java nicht korrekt konfiguriert werden kann
JAVA_OPTS=$JAVA_OPTS -DproxySet=true -DproxyHost=10111213 -DproxyPort=8888
JAVA_OPTS=$JAVA_OPTS -DhttpnonProxyHosts=domainorg|localhost|10
1 httpdocsoraclecomjavase8docstechnotesguidesnetpropertieshtml
Release Notes BALVI Schnittstellenserver Seite 11 von 37
215 Spracheinstellung Deutsch Es wurde festgestellt dass unter einigen Linux-Versionen die Spracheinstellung beim Starten des Apache Tomcat nicht auf eine deutsche Umgebung verweist Dieses kann technische Probleme verursachen Unter Linux sollte die Einstellung (Umgebungsvariable) entsprechend auf LANG=de_DEUTF-8 eingestellt sein
216 Datenbankverbindung Wenn Sie eine Firewall zwischen dem Oracle-Server und dem Database Connection Pool (DBCP) verwenden sollte unbedingt die bdquovalidationQueryldquo in der DBCP-Konfiguration aktiviert werden damit die Anwendung schneller freie Connections aus dem Pool erhalten kann Die Dokumentation zu den Einstellmoumlglichkeiten ist in der beiliegenden Contextxml ergaumlnzt worden
Bitte beachten Sie dass dringende empfohlen wird die bdquoFactoryldquo auf orgapachetomcatjdbcpoolDataSourceFactory anzupassen falls sie noch auf bdquoorgapachecommonsdbcpBasicDataSourceFactoryldquo eingestellt ist
217 Probleme beim Anlegen von LOB-Objekten Der BALVI Schnittstellen-Server erfordert die JDBC-Spezifikation DBCP V4 welche durch die Factory bdquoorgapachetomcatjdbcldquo ab Tomcat 7 automatisch bereitgestellt wird
Wenn die Pooling-Komponente oder der Oracle-Treiber nicht JDBC4-Kompatibel sind gibt es beim Bearbeiten von LOB-Objekten in Java diverse Exceptions z B
Servletservice() for servlet soapws threw exception
javalangAbstractMethodError
orgapachecommonsdbcpPoolingDataSource$PoolGuardConnectionWrappercreateClob()LjavasqlClob
at debalvicoreauditspyConnectionSpycreateClob(ConnectionSpyjava511)
Ursache dieses Problems ist meistens dass noch nicht auf bdquoorgapachetomcatjdbcldquo umgestellt wurde
218 Umbenennung der gelieferten WAR-Datei Das im Paket von BALVI gelieferte WAR kann jederzeit umbenannt werden (z B als ROOTwar) ohne dass dabei spezielle Einstellungen in der Datei bdquocontextxmlldquo erforderlich sind
Beachten Sie dabei jedoch dass die zum WAR zugehoumlrige Datei bdquocontextxmlldquo im Apache Tomcat immer denselben Namen erhaumllt wie das WAR z B bdquocommserverwarldquo und bdquocommserverxmlldquo Der Name ist dabei ausschlaggebend fuumlr die Zugriffs-Adresse (Context) im Apache Tomcat selbst Die Benennung des WAR in bdquocommserverwarldquo wuumlrde folgendermaszligen aufzurufen sein httpserverportcommserver
219 Server-Schnittstellen Die Uumlberarbeitung bzw Erweiterung der Export- und Importschnittstellen welche uumlber den Schnittstellenserver bereitgestellt werden ist unabhaumlngig vom Schnittstellenserver selbst Die Schnittstellen sind daher nicht Bestandteile des Schnittstellenserver und werden je Verfahren separat
Release Notes BALVI Schnittstellenserver Seite 12 von 37
ausgeliefert Ggf ist es fuumlr unterschiedliche Schnittstellen erforderlich die Grant-Rechte zu aktualisieren (Vgl bdquoWann ist die Ausfuumlhrung des Grant-Skripts erforderlichldquo)
22 Kompatibilitaumltsliste Diverse Verfahren setzen eine Mindestversion des BALVI Schnittstellenservers voraus Die Schnittstellen sind jedoch so konzipiert dass eine Aktualisierung auf eine houmlhere Version des Servers ohne Anpassung an den vorhandenen Schnittstellen jederzeit moumlglich ist
Derzeit sind folgende Mindestanforderungen gegeben
1 BALVI mobil XT 170 oder houmlher setzt BSS 265 und BALVI iP 124x voraus
2 BALVI mobil XT 183 oder houmlher setzt BSS 281 und BALVI iP 124x voraus
3 BALVI mobil 2 (DM) setzt BSS 311 und BALVI iP 124x voraus
4 Die Schnittstelle eFI setzt BSS 251 und BALVI iP 122c voraus
5 Die Schnittstelle LIMS setzt BSS 265 voraus
6 Die Schnittstelle TSK (SN) setzt BSS 265 voraus
7 Die Schnittstelle xDomea (SN) setzt BSS 265 und Java 7 voraus
8 Die Schnittstelle XGewerbeanzeigen 11 setzt BSS 281 BALVI iP 124x Java 8 mit der bdquoJava
Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy2ldquo voraus
9 Die Schnittstelle XGewerbeanzeigen 12 (ab Paket 7 Ausbaustufe 3) setzt BSS 302 BALVI iP
124x Java 8 mit der bdquoJava Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policyldquo
voraus
10 Die Schnittstelle RioPP LM (NRW) setzt BSS 303 und die ETL-Konfiguration voraus
11 Die Schnittstellen zu BALVI iP2 (Fachmodule BTS LM ZDA Stand Juni 2017) setzen BSS 32x
voraus
2 httpwwworaclecomtechnetworkjavajavasedownloadsjce8-download-2133166html
Release Notes BALVI Schnittstellenserver Seite 13 von 37
23 Erforderliche Bibliotheken fuumlr Apache Tomcat Dateiname Funktion Quelle ojdbc6jar Oracle 11gR2 Clientpaket Oracle JDBC Client fuumlr Java
16 ersetzt die bisherige Version bdquoojdbc14jarldquo Die alte Library muss auf jeden Fall entfernt werden
httpwwworaclecomtechnetworkdatabaseenterprise-editionjdbc-112010-090769html
encrypted-datasource-110-alljar
Die Library muss auf jeden Fall entfernt werden Wird derzeit nicht weiter gepflegt da kein Interesse an der Funktionalitaumlt bestand
slf4j-api-1511jar slf4j-log4j12-1511jar log4jdbc4-12beta2jar
Entfaumlllt nicht mehr erforderlich Es wird empfohlen diese zu entfernen falls diese im LIB-Verzeichnis vorhanden sein sollten
commons-dbcp-14jar commons-pool-154jar
Entfaumlllt nicht mehr erforderlich Es wird empfohlen diese zu entfernen falls diese im LIB-Verzeichnis vorhanden sein sollten
Erwartet wird stattdessen ab Tomcat7 die mitgelieferte bdquotomcat-jdbcjarldquo
log4j-1217jar (oder houmlher)
Logging-Funktionalitaumlt Apache Log4j httploggingapacheorglog4j12downloadhtml
bcprov-jdk15on-157jar (oder houmlher)
BouncyCastle Security Provider fuumlr SSLAES hellip wird ab Version 27 im Ordner bdquolibldquo des Tomcat erwartet Sollte es aus Sicherheitsgruumlnden erwuumlnscht sein eine aktuellere Version einzusetzen ist dieses idR moumlglich
httpmvnrepositorycomartifactorgbouncycastlebcprov-jdk15on157
24 Datenbank-Installation Der BALVI Schnittstellenserver benoumltigt auszligerhalb des angebundenen BALVI iP keine eigenen Tabellen Die Web-Anwendung kann im einfachsten Fall direkt auf das Schema von BALVI iP zugreifen indem der Benutzer und das Passwort des BALVI iP-Schemas in der Datei bdquocontextxmlldquo eingetragen werden (nicht empfohlen)
Sollte dies aus Sicherheitsgruumlnden nicht erwuumlnscht sein (empfohlen vom BSI und von BALVI) finden Sie im Paket ein GRANT-Skript um Zugriffsrechte vom BALVI iP Schema fuumlr den Webservice-Schema-Benutzer einzurichten
Zwischen dem Schema von BALVI iP und jeder Web-Anwendung ist dann eine Trennung moumlglich um sicherzustellen dass der Datenbank-Benutzer welcher in der Tomcat-Konfiguration fuumlr die Web-Anwendung eingetragen wird geaumlndert oder geloumlscht werden kann ohne dass die Windows-Anwendung BALVI iP davon betroffen ist Zudem vergibt das von BALVI gelieferte Grant-Skript keine Rechte zum Loumlschen von Tabellenstrukturen oder Tabelleninhalten so dass der Webservice nur festgelegte Daten aumlndern oder lesen darf Es wird empfohlen je Web-Anwendung einen eigenen Datenbank-Benutzer zu vergeben wenn Sie ein BALVI iP mit mehreren Webservices verbinden wollen
Die Moumlglichkeiten im Uumlberblick
1) Sie betreiben den Webservice mit einem eigenstaumlndigen Oracle-Benutzer In diesem Fall muss das
Grant-Skript ausgefuumlhrt werden um den Webservice-Benutzer und den BALVI iP-Benutzer
miteinander zu koppeln
2) In der Tomcat-Konfiguration wird der Oracle-Benutzer eingetragen welcher auch der BALVI iP
Schemabesitzer ist und in der bdquobalviip_conninildquo hinterlegt ist (NICHT Empfohlen) Der Webservice
Release Notes BALVI Schnittstellenserver Seite 14 von 37
hat 100 Zugriffsrechte (auch Loumlsch- oder Aumlnderungsrechte am Schema) es wird kein Grant-
Skript benoumltigt
Wenn Sie die Konfiguration 2) waumlhlen moumlchten koumlnnen Sie die folgenden Unterkapitel uumlberspringen und in Kapitel 0 bzw fortsetzen
241 Erstinstallation Datenbank-Benutzer anlegen Wenn Sie den Webservice-Benutzer vom BALVI iP Schema trennen moumlchten muss durch die DB-Administration in der Oracle-Server-Instanz wo auch BALVI iP sein Schema besitzt ein Benutzer (ggf je Web-Anwendung) angelegt werden welcher folgende Rechte benoumltigt
CONNECT
ALTER SESSION
CREATE JOB
CREATE PROCEDURE
CREATE SESSION
CREATE TABLE
CREATE TRIGGER
CREATE TYPE
CREATE VIEW
CREATE SEQUENCE
CREATE SYNONYM
QUERY REWRITE
Der Default-Tablespace ist frei waumlhlbar Der Benutzer braucht das Recht QUOTA UNLIMITED auf den Tablespace von BALVI iP (Default BALVI_IP) Ein Beispiel-Create-Skript bdquooraCreate_WEB_Usersqlldquo liegt der Auslieferung bei
242 Rechte zuweisen Wenn der BALVI iP Schemabesitzer NICHT in der Tomcat-Umgebung eingetragen werden soll muss ein Oracle DBA das beiliegende GRANT-Skript bdquooraGrantIP_to_Websqlldquo ausfuumlhren um dem jeweiligen Webservice (in Tomcat verwendeten Oracle-Benutzer) die minimalen Rechte auf das Schema von BALVI iP zu gewaumlhren
Dieses Skript setzt voraus dass es von einem Oracle Administrator als bdquoUser SYSTEMldquo ausgefuumlhrt wird Lesen Sie die im Skript enthaltenen README-Kommentare und passen Sie die Benutzer (BALVI iP Schema) und (WEB-Schema) an
====================================================
DEKLARATIVER TEIL MUSS vom KUNDEN geaumlndert
bzw auf die korrekten SCHEMA-Namen angepasst
werden
Die USER-Namen muumlssen in Groszligbuchstaben
geschrieben sein sonst werden sie nicht
gefunden
====================================================
sUserBALVI_IP = BALVI_IP_SCHEMABESITZER
sUserBALVI_WEB = BALVI_WEB_SCHEMABESITZER
Release Notes BALVI Schnittstellenserver Seite 15 von 37
Neu ab Grant-Skript 158 ist die Umbenennung der Verfahrenszuordnung
Pruumlfen Sie dass die Einstellung fuumlr Ihr BundeslandVerfahren korrekt ist dort muss eine 1 fuumlr min ein Verfahren gesetzt sein Diese Einstellung befindet sich direkt unter den Schemabesitzer-Angaben
-- Verfahrensbezogene Konfiguration
-- Setzen Sie fuumlr das jeweilige Verfahren eine 1
-- BALVI Schnittstellenserver (BSS)
-- bis V266 auch BALVI Kommunikationsserver (BKS) genannt
-- generell fuumlr die meisten Verfahren guumlltig
-- Ab Version 57 entfaumlllt mit der Einfuumlhrung der
-- Schnittstelle XGewerbeanzeigen auch der separate Schalter
-- WS_BTR beide Verfahren wurden vereinheitlicht
WS_BSS = 1
Fuumlhren Sie das Skript nach der Anpassung als User SYSTEM aus um die Grants durchzufuumlhren Dieses wurde mit dem von ORACLE gelieferten Programm SQLPLUS (Command-Line) SQLPLUS Worksheet (GUI) und Oracle SQL-Developer getestet
Das Skript generiert fuumlr jedes Objekt ein SYNONYM fuumlr den WEB-USER so dass dieser auf die Objekte ohne Angabe des Owners des IP-Schemas zugreifen kann Pruumlfen Sie nach der Ausfuumlhrung dass die SYNONYMS vorhanden und VALID sind dieses kann ggf nicht der Fall sein Das Skript kann jederzeit erneut ausgefuumlhrt werden um die Grants neu zu erzeugen und bietet ebenfalls die Option alle Grants und Synonyme wieder zu entfernen Detaillierte Informationen zur Nutzung des Skripts sind als Kommentar-Block im Skript enthalten
Hinweis Die Versionsinformation ist unter den Kommentaren direkt im Skript zu finden
Zugriffsberechtigungen fuumlr Webanwendungen auf BALVI iP anlegen
===============================================================
Version 158
Guumlltig fuumlr BALVI iP 123 oder houmlher
Autor Frank Holler
SVN Revisionsinformationen
$Revision 479 $
$Date 2016-02-15 152755 +0100 (Mo 15 Feb 2016) $
================================================================
243 Wann ist die Ausfuumlhrung des Grant-Skripts erforderlich Durch das Strukturupdate von BALVI iP (z B 1240 auf 1241) werden veraltete Strukturen geloumlscht und ggf neue Views oder Tabellen angelegt Die Grant-Rechte geht dabei ggf verloren Daher ist die Ausfuumlhrung des Grant-Skripts immer dann erforderlich wenn sich die Datenbank-Struktur von BALVI iP veraumlndert
Zudem kann es fachliche Neuerungen geben welche im alten Grant-Skript nicht vorhanden sind Daher muss das Skript ggf auch ausgefuumlhrt werden wenn eine neue Schnittstelle im Schnittstellenserver bereitgestellt wurde Dieses betrifft z B auch die Bereitstellung von neuen Versionen von BALVI mobil XT
Release Notes BALVI Schnittstellenserver Seite 16 von 37
da auch dort mit einem fachlich erweiterten Client die Moumlglichkeit besteht dass neue Schnittstellen bereitgestellt und somit mehr Schreibrechte auf Tabellen benoumltigt werden
244 Welche Version des Grant-Skripts soll ich nehmen Wie der Schnittstellenserver sind auch die Grant-Skripte versioniert Neuere Versionen des Grant-Skriptes sind abwaumlrts-kompatibel und koumlnnen immer verwendet werden auch wenn in einer Schnittstellenbeschreibung eine aumlltere Version des Grant-Skriptes explizit benannt wurde
245 Kombination von mehreren Verfahren Wenn Sie zwei oder mehr Schnittstellen im BSS verwenden moumlchten ist es ggf erforderlich auch mehrere Verfahren auf aktiv (bdquo1ldquo) zu setzen
Im Beispiel nehmen wir an Sie moumlchten bdquoeFildquo und bdquoBALVI mobil XTldquo im Schnittstellenserver bereitstellen In der Beschreibung von bdquoeFildquo steht dass das Grant-Skript V36 erforderlich ist BALVI mobil XT 18 erfordert jedoch schon V56
Wenn Sie beide Verfahren betreiben ist im Grant-Skript (V56 oder houmlher) die Einstellung fuumlr beide Verfahren zu aktivieren
====================================================
DEKLARATIVER TEIL MUSS vom KUNDEN geaumlndert
bzw auf die korrekten SCHEMA-Namen angepasst
werden
Die USER-Namen muumlssen in Groszligbuchstaben
geschrieben sein sonst werden sie nicht
gefunden
====================================================
sUserBALVI_IP = BALVI_IP_SCHEMA
sUserBALVI_WEB = WEBAPP_SCHEMA
-- Verfahrensbezogene Konfiguration
-- Setzen Sie fuumlr das jeweilige Verfahren eine 1
-- BALVI Schnittstellenserver (BSS)
-- bis V266 auch BALVI Kommunikationsserver (BKS) genannt
-- generell fuumlr die meisten Verfahren guumlltig
-- Ab Version 57 entfaumlllt mit der Einfuumlhrung der
-- Schnittstelle XGewerbeanzeigen auch der separate Schalter
-- WS_BTR beide Verfahren wurden vereinheitlicht
WS_BSS = 1
-- WebService BTR (Betriebsstaumlttenregister) (NRW TH)
-- entfernt mit Update V57 setzen Sie stattdessen bei WS_BSS = 1
--WS_BTR = 0
-- Probenahme Futtermittel im Browser(BY)
WS_PROBE_FM = 0
-- Risikoorientierte Probenplanung Futtermittel ndash RIOPP FM (BY)
WS_RIOPP_FM = 0
-- Verfahren Export an EFi (Status Pilotbetrieb)
WS_EFI = 1
-- neu ab Version 35 des Grant-Skriptes ist die Moumlglichkeit den Webuser
Release Notes BALVI Schnittstellenserver Seite 17 von 37
-- fuumlr das Loumlschen der Ausgangskoumlrbe explizit zu berechtigen bzw sogar einen
-- expliziten abweichenden User festzulegen Die Konfiguration in der
-- Job-Oberflaumlche sieht vor dass man die Oracle-Datenbank-Zugangsdaten fuumlr
-- das Loumlschen einstellen muss Hier muss im Normalfall derselbe Oracle
-- Datenbankbenutzer eingetragen werden wie in der Tomcat-Verbindungs-
-- konfiguration In diesem Fall sollte wenn WS_EFI = 1 eingestellt wurde
-- ebenfalls WS_EFI_DELETE = 1 eingestellt werden
-- Alternativen
-- 1) Datenbankbenutzer aumlndern
-- Wenn bei sUserEFI_TRUNC anstatt sUserBALVI_WEB (Standard) ein anderer
-- Oracle-Benutzername angegeben wird wird das Loumlschrecht fuumlr die EFi
-- Ausgangskoumlrbe Datenbankseitig exklusiv dem angegeben Datenbankbenutzer
-- zugewiesen
-- 2) Loumlschrecht verweigern
-- Setzen Sie die Variablen WS_EFI_DELETE = 0 damit kein Loumlschrecht
-- zugeweisen wird
WS_EFI_DELETE = 0
-- Beispiel Anderer Benutzer muss in der Datenbank existieren
-- Entfernen Sie die fuumlhrenden -- vor der Variable sUserEFI_TRUNC und
-- setzen den entsprechenden Oracle-Benutzer ein
--sUserEFI_TRUNC = TEST_EFI_TRUNC
hellip
25 Konfiguration des Schnittstellen-Servers
251 Die bdquocontextxmlldquo-Parameter Die von der Servlet-Spezifikation vorgegeben Rump-Struktur sieht folgendermaszligen aus
ltxml version=10 encoding=utf-8gt
ltDOCTYPE Contextgt
ltContextgt
lt-- Kundenspezifische Einstellungen --gt
ltContextgt
Anwendungsspezifische Einstellungen werden zwischen ltContextgt und ltContextgt eingefuumlgt Alle allgemeinguumlltigen Einstellungen in der Datei bdquocontextxmlldquo werden hier erlaumlutert Kommentare finden sich auch in der von BALVI ausgelieferten Beispiel-Konfiguration
Neben den im Folgenden beschriebenen Standard-Einstellungen kann es auch vorkommen dass bundeslandspezifische Erweiterungen vorhanden sind welche nicht in dieser Dokumentation aufgefuumlhrt werden Diese funktionieren trotzdem regulaumlr weiter wenn keine expliziten Informationen zu Kompatibilitaumltsproblemen in den Release-Notes aufgefuumlhrt wurden
2511 Datenbankverbindung jdbcDataSource
Die Datenbankverbindung wird uumlber die von DBCP und dem Oracle-Treiber vorgegebenen Moumlglichkeiten realisiert Der Einsatz der orgapachetomcatjdbcpoolDataSourceFactory (automatisch verfuumlgbar ab Apache Tomcat 7 in der mitgelieferten tomcat-dbcpjar) wird als Beispiel-Konfiguration ausgeliefert
ltResource
name=jdbcDataSource
auth=Container
Release Notes BALVI Schnittstellenserver Seite 18 von 37
type=javaxsqlDataSource
factory=orgapachetomcatjdbcpoolDataSourceFactory
maxActive=10 initialSize=3
maxIdle=5
maxWait=10000
url=jdbcoraclethinBL2-ORA10-KUNDENBALVIINTERN1521ORCL
driverClassName=oraclejdbcdriverOracleDriver
username=balvi_webservice_schema
password=balvi_webservice_password
description=Oracle Datasource
maxOpenPreparedStatements=50
removeAbandoned=false
removeAbandonedTimeout=100
logAbandoned=true
jdbcInterceptors=hellip
gt
Hinweise zur Einstellung der jdbcDataSource
Standard-Einstellungen fuumlr den Datenbank-Verbindungspool
Der Verbindungspool muss entsprechend der Anzahl der zu erwartenden gleichzeitigen Benutzer konfiguriert werden Wenn Sie erwarten dass 50 Anwender gleichzeitig arbeiten stellen Sie bitte folgende Werte ein
maxActive=(50 + 10 (fuumlr System und Jobs)) = 60
maxIdle= (50 10) = 5
1 maxActive - maximale Anzahl der gleichzeitigen aktiven Anfragen an die DB
Wenn der Werte maxActive erreicht ist z B wenn mehrere Benutzer gleichzeitig einen Export starten moumlchten welcher laumlngere Zeit in Anspruch nimmt dann kann der Server die Anfrage nicht mehr bedienen und der Anwender wird abgewiesen maxActive hat zudem Auswirkungen auf die im Hintergrund ausgefuumlhrten Jobs maxActive wird daher kalkuliert mit der Anzahl der Anwender und moumlglicher Datenbank-Connections fuumlr Hintergrund-Jobs Jeder aktiv ausgefuumlhrte Job benoumltigt mindestens eine Connection nur selten wird aus Performance-Gruumlnden mehr als eine Connection waumlhrend der Job-Ausfuumlhrung verwendet Im Normalfall sollten daher 10 Connections fuumlr Hintergrundprozesse ausreichend sein
2 maxIdle - Anzahl der offenen Verbindungen auch wenn der Server im Leerlauf ist
Jede offene Verbindung im Leerlauf haumllt auf dem Datenbankserver eine Session offen Auch diese erfordert Ressourcen Wenn die Verbindungen jedoch geschlossen werden kann die Anfragezeit fuumlr eine neue Verbindung steigen da diese Verbindung erst neu ausgehandelt werden muss Die Empfehlung fuumlr den Wert bdquomaxIdleldquo ist ca 10 der Einstellung von maxActive
KeepAlive-Einstellungen fuumlr den Pool
1 validationQuery
Diese wird ausgefuumlhrt um die Verbindung zu DB zu validieren Es MUSS ein Datensatz zuruumlckgegeben werden ansonsten nimmt der DBCP an dass die Abfrage nicht erfolgreich abgesetzt wurde Achten Sie also bitte darauf dass die Abfrage nicht zu leitungsintensiv ist und genau einen Datensatz liefert
Release Notes BALVI Schnittstellenserver Seite 19 von 37
Oracle bietet dafuumlr die virtuelle Tabelle DUAL an welche sich fuumlr die ValidationQuery sehr gut eignet da die Abfrage kaum Ressourcen verbraucht
validationQuery=select 1 from dual
2 testOnBorrow - Boolscher Wert true oder false
Diese Einstellung sorgt dafuumlr dass der Pool die Verfuumlgbarkeit anhand der validationQuery pruumlft bevor
die DB-Verbindung an die Anwendung ausgeliehen wird Empfehlung
testOnBorrow=true
3 testWhileIdle - Boolscher Wert true oder false
Diese Einstellung ist hilfreich wenn zwischen dem Tomcat und der DB eine Firewall mit Stateful
Packet Inspection verwendet wird Nach laumlngerer Inaktivitaumlt wird normalerweise durch die Firewall die
DB-Verbindung geschlossen Dieses loumlst dann beim Ausleihen der Verbindung eine Fehlermeldung im
Protokoll aus 2012-08-16 165418720 WARN [http-0000-8080-8]
[orgspringframeworkjdbcsupportSQLErrorCodesFactory] Error while extracting
database product name - falling back to empty error codes
orgspringframeworkjdbcsupportMetaDataAccessException Error while extracting
DatabaseMetaData nested exception is javasqlSQLRecoverableException Getrennte
Verbindung Um dieses Problem zu beheben sollte die Option testWhileIdle=true eingestellt werden
testWhileIdle=true
Damit diese weiszlig wie oft eine Pruumlfung durchgefuumlhrt werden muss sind jedoch noch zusaumltzliche Angaben erforderlich welche fuumlr die Einstellung der Zeit zusaumltzlich gesetzt werden muumlssen
a) minEvictableIdleTimeMillis - Long in Millisekunden
Min Zeit wie lange eine DB-Verbindung im Leerlauf ist bevor diese zur Pruumlfung
gekennzeichnet wird Dieses haumlngt stark von der Einstellung der Firewall ab Wenn Sie eine
sehr restriktive Firewall haben kann es sein dass diese die Verbindung nach wenigen
Minuten Leerlauf trennt Stellen Sie den Wert immer so ein dass dieser unter der Leerlaufzeit
der Firewall liegt empfohlen 300000 entspricht 300 Sek = 5 min
minEvictableIdleTimeMillis=300000
b) timeBetweenEvictionRunsMillis - Long in Millisekunden
Der Pruumlflauf startet in der Default-Konfiguration alle 1800000 Millisekunden = 30 Min n als
zu Pruumlfen markierte Verbindungen werden in einem Pruumlflauf getestet n wird bestimmt durch
die Einstellung numTestsPerEvictionRun Empfehlung Stellen Sie den Wert auf alle 15 Min
ein
timeBetweenEvictionRunsMillis=900000
Release Notes BALVI Schnittstellenserver Seite 20 von 37
c) numTestsPerEvictionRun - Integer
Wie viele Verbindungen sollen getestet werden waumlhrend der Pruumlflauf ausgefuumlhrt wird Im
Normalfall sollte die Anzahl der zu testenden Verbindungen nicht zu hoch eingestellt werden
Der Default ist 3 Wenn Sie houmlhere Sicherheit haben wollen dass keine bdquototenldquo
Datenbankverbindungen bestehen bleiben erhoumlhen Sie den Wert auf max bdquo(maxActive ndash
maxIdle) 2ldquo Wenn Ihnen 3 ausreichend erscheint muss der Wert nicht gesetzt sein dann
wird der Default verwendet
Beispiel numTestsPerEvictionRun=10
4 Interceptors konfigurieren Neu ergaumlnzt wurde die Moumlglichkeit spezielle bdquoInterceptorsldquo zu konfigurieren die ermoumlglichen das Verhalten des Pools zu steuern Wichtig hierbei ist dass die Angabe von Werten auf real existierende Java-Klassen erfolgt die im Classpath des Tomcat vorhanden sind Groszlig-und-Kleinschreibung ist zu beachten Folgende Default-Einstellung hat BALVI fuumlr den BSS festgelegt jdbcInterceptors=
orgapachetomcatjdbcpoolinterceptorConnectionState
orgapachetomcatjdbcpoolinterceptorStatementFinalizer
orgapachetomcatjdbcpoolinterceptorResetAbandonedTimer
Details zu den verwendeten Interceptor-Einstellungen finden Sie in der Tomcat-Dokumentation3
3 httptomcatapacheorgtomcat-80-docjdbc-poolhtmlJDBC_interceptors
Release Notes BALVI Schnittstellenserver Seite 21 von 37
2512 Datenbank-Zugangsdaten verschluumlsseln
Die Verschluumlsselung fuumlr die Datenbank-Verbindung (bdquoEncrypted Datasourceldquo) ist eine Ableitung der Bibliothek Apache-Common-DBCP-14 und daher nicht mehr mit Java 8 kompatibel Die Einrichtung der Verschluumlsselung wird daher mit der Auslieferung des BSS 30 nicht mehr angeboten
2513 Active-Directory-Authentifizierung
Uumlber die folgenden Parameter wird der Zugriff des Schnittstellen-Servers auf einen Microsoft Active Directory Domain-Controller konfiguriert
ldquoldapServerAddressrdquo
Syntax PROTOKOLLIP-Adresse oder DNS-NamePORT
ltEnvironment
name=ldapServerAddress
value=ldapbl2-dc02balviintern389
type=javalangString
override=true
gt
Als Protokoll besteht auch die Moumlglichkeit ldaps (LDAP+SSL) wenn der Domain-Controller entsprechend konfiguriert wurde Im Java Truststore muss dann das Zertifikat der CA vorhanden sein welche das Zertifikat des Domain-Controllers signiert hat Zudem darf bei ldaps keine IP-Adresse verwendet werden es muss der DNS-Name des Server-Zertifikats eingetragen sein Ansonsten gibt es beim Verbinden eine Sicherheits-Exception
lt-- SSL-Beispiel
ltEnvironment
name=ldapServerAddress
value=ldapsbl2-dc02balviintern636
type=javalangString
override=true
gt
--gt
bdquoldapBaseDnrdquo
LDAP-Suchpfad fuumlr die Domain-Basis Diese muss der LDAP-Syntax fuumlr den Domain-Suffix entsprechen
Syntax DC=SERVERDC=ROOTDN
ltEnvironment
name=ldapBaseDn
value=DC=BALVIDC=INTERN
type=javalangString
override=true
gt
Release Notes BALVI Schnittstellenserver Seite 22 von 37
bdquowebLoginUseActiveDirectoryAuthenticationrdquo
Die Authentifizierung in der Browser-Oberflaumlche kann uumlber die Active-Directory-Authentifizierung erfolgen In der ersten Version ist nur die Protokoll-Auswertung moumlglich wenn der ADMIN sich anmeldet Dieser hat normalerweise niemals AD-Kennungen zugeordnet BALVI empfiehlt diese Einstellung auf bdquofalseldquo zu belassen Webservices welche uumlber SOAPREST zugreifen koumlnnen die Active-Directory-Authentifizierung trotzdem verwenden
ltEnvironment
name=webLoginUseActiveDirectoryAuthentication
value=false
type=javalangBoolean
override=true
gt
ldquoldapDaysBeforeExpirationNotificationrdquo
Die Passwort-Aumlnderung im Active-Directory uumlber die Browser-Oberflaumlche ist in der ersten Version noch nicht implementiert der Parameter wird bislang nicht ausgewertet
ltEnvironment
name=ldapDaysBeforeExpirationNotification
value=14
type=javalangInteger
override=true
gt
2514 Statement-Protokollierung in BALVI iP
Diese Option aktiviert die Lese- und Aumlnderungsprotokollierung fuumlr BALVI iP Standard ist bdquofalseldquo und wird fuumlr alle Kunden empfohlen solange keine speziellen Datenbank-Jobs eingerichtet wurden welche zeitgesteuert die Protokolleintraumlge wieder loumlschen Fuumlr Bayern wurde ein spezielles Konzept zur Leseprotokollierung entworfen Wenn Sie mehr daruumlber erfahren moumlchten kontaktieren Sie bitte die BALVI GmbH
ltEnvironment
name=enableSqlStatementMonitoring
value=true
type=javalangBoolean
override=true
gt
Beachten Sie dass diese Option massive INSERT-Statements in BALVI iP in die Tabelle VIS_D92 ausfuumlhrt Jedes abgesetzte SQL-Statement wird dabei vollstaumlndig protokolliert Dieses erzeugt eine sehr hohe INSERT-Last und in der Folge auch erhoumlhte Redolog-Switches und COMMIT-Transaktionen
Optional Aktivieren der INSERT + APPEND - Logik
Beachten Sie bitte die Hinweise von Oracle zum Hint + APPEND
Release Notes BALVI Schnittstellenserver Seite 23 von 37
Wenn Sie dieses Verhalten aktivieren moumlchten ergaumlnzen Sie bitte den folgenden Environment-Parameter
ltEnvironment
name=statementMonitoringactivateAppendMode
value=true
type=javalangBoolean
override=true
gt
2515 Einstellungen fuumlr BALVI mobil XT (bzw den bdquopartitionedExportldquo)
Diese Logik des FIFO-Buffers wurde so konzipiert dass dem Rechenzentrum diverse Einstellmoumlglichkeiten uumlber die Datei bdquocontextxmlldquo zur Verfuumlgung stehen um die Steuerung des FIFO-Puffers zu beeinflussen
Schematische Darstellung des FIFO-Puffers
Das ermoumlglicht es z B dem BALVI mobil XT Client (14 oder houmlher) den aktiven Block abzuholen und dies beim Fehler bis zu 10-mal zu wiederholen Sobald der Block [001] erfolgreich beim Client angekommen ist und dieser den naumlchsten Block anfragt wird der Block [001] verworfen wird Der Server fuumlllt dann im Hintergrund den frei gewordenen Block wieder waumlhrend der Client den Block [002] abholt
Die Groumlszlige und Anzahl der vorgecachten Bloumlcke kann uumlber die folgenden Einstellungen in der Datei bdquocontextxmlldquo definiert werden
ltEnvironment
name=partitionedExportmaxBufferedPartitions
value=3 type=javalangInteger override=true
gt
ltEnvironment
name=partitionedExportpartitionSize
value=256000 type=javalangInteger override=true
gt
Die Einstellung partitionedExportmaxBufferedPartitions ist dabei die Anzahl der vorgecachten Bloumlcke mindestens muss 2 angegeben werden Der Puffercache wird ausschlieszliglich im RAM der JVM aufgebaut es wird folglich mehr Arbeitsspeicher verwendet Dieser Arbeitsspeicher muss je gleichzeitiger Session auf dem Server bereitgestellt werden die Default-Einstellung mit 3 Partitionen a 256 KB + dem aktiven Puffer erfordern 1 MB RAM je aktiven Anwender
Aktiv
er
Puffe
r
[001] Vorg
ecac
hter
Bl
ock
[002] Vorg
ecac
hter
Bl
ock
[003]
Aktiv
er P
uffe
r
[002] Vorg
ecac
hter
Bl
ock
[003] Vorg
ecac
hter
Bl
ock
[leer]
Release Notes BALVI Schnittstellenserver Seite 24 von 37
Gleichzeitig wurde die Moumlglichkeit geschaffen dass die maximale Anzahl an gleichzeitigen Exporten durch das Rechenzentrum eingeschraumlnkt werden kann um einem OutOfMemory-Fehler vorzubeugen Die Einstellung
ltEnvironment
name=partitionedExportmaxConcurrentExports
value=10 type=javalangInteger override=true
gt
muss entsprechend der zu erwartenden gleichzeitigen Zugriffe konzipiert werden ansonsten wird der Server einen Verbindungsversuch durch die Clients ablehnen
Beachten Sie dass die folgenden Einstellungen partitionedExportmaxBufferedPartitions partitionedExportmaxConcurrentExports und partitionedExportpartitionSize gemeinsam als Rechenbasis fuumlr den RAM-Bedarf des Webservers herangezogen werden muumlssen
Folgende Faustformel sollte fuumlr die Einrichtung verwendet werden
Min 256 MB (Serverbasis) + (11 partitionedExportmaxConcurrentExports partitionedExportmaxBufferedPartitions partitionedExportpartitionSize)
Beispiel 50 gleichzeitige Anwender Blockgroumlszlige 256 KB 4 Partitionen
256 MB + (11 50 256 4) KB = 312 MB fuumlr die JVM
Empf 512 MB (Serverbasis) + (12 partitionedExportmaxConcurrentExports partitionedExportmaxBufferedPartitions partitionedExportpartitionSize)
Beispiel 50 gleichzeitige Anwender Blockgroumlszlige 256 KB 4 Partitionen
512 MB + (12 50 256 4) KB = 572 MB fuumlr die JVM
partitionedExportmaxConcurrentExports
Bestimmt die Anzahl der maximalen Export Tasks (Threads) die fuumlr partitionierte Exporte bereitgestellt werden Wenn die Anzahl uumlberschritten wird wird die entsprechende Exportanfrage abgewiesen und der Client muss zu einem spaumlteren Zeitpunkt erneut anfragen Stellen Sie diesen Wert entsprechend der zu erwartenden Benutzeranzahl ein bei 50 Anwendern also 50
Exporte oumlffnen auf der Datenbank entsprechend zur Ausfuumlhrungszeit min einen Cursor ggf fuumlr rekursive Unterabfragen kurzfristig sogar mehr Die hier eingestellte Anzahl muss mit der Anzahl von maxActive korrelieren
ltEnvironment
name=partitionedExportmaxConcurrentExports
value=10 type=javalangInteger override=true
gt
partitionedExportmaxBufferedPartitions
Bestimmt die Anzahl der Datenbloumlcke (Partitionen) die vom Server bei Abruf eines Exportes gepuffert werden Die seit Version 24 eingefuumlhrte FIFO-Puffer-Logik ermoumlglicht dass der Server schon die Ergebnisse vorpuffert so dass der Client weniger Wartezeiten bei der Anfrage nach Daten hat Diese
Release Notes BALVI Schnittstellenserver Seite 25 von 37
Puffer-Logik unterteilt den Exportdatenstrom (je Export) in mehre Bloumlcke Der Client kann nun den letzten Block neu anfordern oder den naumlchsten Block wenn der letzte Block erfolgreich verarbeitet wurde Wie viele naumlchste Bloumlcke durch den Server bereit gestellt werden entscheidet diese Einstellung Sobald kein naumlchster Block mehr bereit gestellt werden muss wird der Datenbank-Cursor geschlossen eine Erhoumlhung kann also zu einer Entlastung der aktiven DB-Verbindungen fuumlhren erhoumlht jedoch den Bedarf an RAM des Servers
Der von BALVI voreingestellte Wert ist 3
ltEnvironment
name=partitionedExportmaxBufferedPartitions
value=3 type=javalangInteger override=true
gt
partitionedExportpartitionSizeldquo
Die Groumlszlige der Datenbloumlcke (Partitionen) die an den Client uumlbermittelt werden in Bytes Wenn Sie diesen Wert zu niedrig einstellen reduziert sich die Effizienz des Caches da der Client mehr Datenbloumlcke hintereinander abrufen muss Waumlhlen Sie einen zu groszligen Wert wird die neu zu uumlbertragende Datenmenge im Fall eines Fehlers houmlher
Der von BALVI voreingestellte Wert ist 256000 (256 KB)
ltEnvironment
name=partitionedExportpartitionSize
value=256000 type=javalangInteger override=true
gt
exportTokensmaxTokenCount
Maximale Anzahl der gleichzeitig vergebenen Token die vom Server gecached werden Jede Sitzung welche einen Export durchfuumlhrt erhaumllt einen Session-Token
Wenn eine Sitzung laumlngere Zeit nicht verwendet wurde wird dieser Session-Token wieder entfernt Wenn Sie den Wert zu niedrig einstellen fuumlhrt das zu einer generellen Session-Begrenzung auch fuumlr den nicht partitionierten Export-Modus welcher ab Version 21 verfuumlgbar ist
Ist die Anzahl der Tokens houmlher als die Datenbankeinstellung maxActive kann es vorkommen dass zwar eine Session gestartet werden kann jedoch kein Datenexport zustande kommt
Der von BALVI voreingestellte Wert ist 2000
ltEnvironment
name=exportTokensmaxTokenCount
value=20 type=javalangInteger override=true
gt
exportTokenstokenExpirationInSeconds
Zeit in Sekunden die verstreichen muss bis ein Token unguumlltig wird falls darauf kein Zugriff mehr erfolgt Nach einem erfolgreichen Export wird der Token automatisch geschlossen diese Option ist fuumlr den Abbruchfall vorgesehen Der von BALVI voreingestellte Wert ist 180 (180 s = 3 min)
Release Notes BALVI Schnittstellenserver Seite 26 von 37
ltEnvironment
name=exportTokenstokenExpirationInSeconds
value=180 type=javalangInteger override=true
gt
exportTokenstokenDisposalInSeconds
Zeit in Sekunden die verstreichen muss bis ein Token das erfolgreich abgearbeitet wurde aus dem Cache geloumlscht wird Um sicher zu stellen dass der letzte Exportblock noch erfolgreich abgerufen werden kann bleibt der Token auch nach Fertigmeldung des Clients noch N Sek guumlltig
Der von BALVI voreingestellte Wert ist 60 (60 s = 1 min)
ltEnvironment
name=exportTokenstokenDisposalInSeconds
value=60 type=javalangInteger override=true
gt
2516 Job-Verwaltung fuumlr den BSS konfigurieren Aktivierung der Jobverwaltung
Bis zur Version 28 des BSS gab es den Parameter bdquoavailableServicesldquo Dieser konnte bei Bedarf aktiviert werden wenn die Jobs benoumltigt wurden
Mit Version 30 ist die Einstellung bdquoavailableServicesldquo zu entfernen und kann durch den neuen optionalen Parameter bdquoisJobServiceEnabledldquo in der Datei bdquocontextxmlldquo ersetzt werden
lt-- Neue Parameter zur Aktivierung des Job Service Ersatz fuumlr availableServices --gt
ltEnvironment
name=isJobServiceEnabled
value=true
type=javalangBoolean
override=true
gt
Ab BSS 30 wird die Jobs-Engine standardmaumlszligig aktiviert Sollte die Jobs-Engine nicht benoumltigt werden muss bdquovalueldquo der Wert bdquofalseldquo zugewiesen werden Wird bdquoisJobServiceEnabledldquo nicht eingefuumlgt sind die Jobs trotzdem standardmaumlszligig aktiv
Nach dem Neustart des Servers und erneutem Einloggen erscheint nun zusaumltzlich der Menuumlpunkt bdquoJobsldquo
bdquopasswordKeyldquo fuumlr Jobs
In der Job-Logik wird ein von BALVI definierter Standard-Schluumlssel fuumlr die Ablagen von schuumltzenswerten Daten z B Passwoumlrtern verwendet Diese Einstellung ermoumlglicht den BALVI-Standard zu uumlberschreiben Wenn Sie diese Einstellung aumlndern muumlssen jedoch alle bislang verschluumlsselten Job-Parameter neu verschluumlsselt werden
ltEnvironment
name=javacompenvjobspasswordKey
value=MeinHochsicheresNeuesPasswort
type=javalangString
Release Notes BALVI Schnittstellenserver Seite 27 von 37
override=true
gt
bdquoJob ID enableddisabledldquo (Deprecated ersetzt ab 28 durch das bdquoBindenldquo von Jobs)
Sondereinstellungen fuumlr die Job-Verwaltung Da alle Jobs in einer Datenbank administriert werden jedoch ggf verteilt auf mehreren Tomcat-Servern ausgefuumlhrt werden sollen besteht hier die Option Jobs fuumlr die aktuelle Tomcat-Instanz separat zu deaktivieren
Die Einstellung ID koumlnnte z B folgendermaszligen aussehen javacompenvjobsC0DB58D8D52C4BBC966D1DC788A4EF8Benabled
Fuumlr weitere Fragen zu dieser Einstellung kontaktieren Sie bitte die BALVI GmbH
ltEnvironment
name=javacompenvjobsIDenabled
value=false
type=javalangBoolean
override=true
gt
2517 Weitere optionale Parameter
Es ist fuumlr diverse einzelne Schnittstellen ggf erforderlich Einstellungen in der Datei bdquocontextxmlldquo zu ergaumlnzen Hinweise zu diesen Parametern sind dann in dem der Schnittstelle beiliegenden Dokument enthalten Das gilt z B fuumlr die Schnittstelle bdquoXGewerbeanzeigenldquo
26 Logging mit logback Das Logging wurde komplett uumlberarbeitet Statt bdquoLog4Jldquo wird jetzt bdquologbackldquo4 benutzt Ab BSS 30 ist es zwingend notwendig die Einstellung vorzunehmen um das Logging der Anwendung zu steuern
Migration Ergaumlnzen Sie die neue Einstellung bdquologgingconfigldquo
lt-- Neue Paramter zur Angabe der Logback Config Ersatz fuumlr log4jConfigLocation --gt
ltEnvironment
name=loggingconfig
value=$catalinabaseconflogback-bssxml
type=javalangString
override=true
gt
Nach wie vor steht es Ihnen frei die Logging-Konfiguration eigenstaumlndig anzupassen
Wenn Sie jedoch dieselbe WAR in einer Tomcat-Instanz unter mehreren Context-Namen betreiben wuumlrden beide dieselbe Logging-Konfiguration verwenden so dass alle Protokolleintraumlge in einer Log-Datei aus
4 httplogbackqoschmanualappendershtml
Release Notes BALVI Schnittstellenserver Seite 28 von 37
mehreren Webanwendungen generiert werden Aumlndern Sie den Namen der Logging-Konfiguration entsprechend ab um fuumlr jede Anwendung eine spezifische Logging-Einstellung vornehmen zu koumlnnen
27 Tocmat Optional Suche im bdquoKlassenpfadldquo um den
Ordner bdquoconfldquo erweitern Die Suche nach Dateien uumlber bdquoclasspathldquo setzt voraus dass die Ordner- und Dateinamen im Apache Tomcat bekannt gegeben werden Der Klassenpfad kann in der Datei bdquocatalinapropertiesldquo angepasst werden Wenn Sie dort unter commonloader die folgenden Werte ergaumlnzen kann eine Datei auch im Ordner conf abgelegt werden damit Apache Tomcat diese findet Ansonsten muss die Datei im Ordner lib abgelegt werden
commonloader=$catalinabaseconf$catalinahomeconf
3 Die neue Browser-Oberflaumlche Der BALVI Schnittstellenserver hat seit Version 25 neben der Protokollierung auch die Moumlglichkeit Job-Konfigurationen zu pflegen Der Login ist nur fuumlr einen in BALVI iP eingetragenen ADMIN (z B Benutzer bdquoSYSTEMADMINldquo) mit dem in BALVI iP hinterlegten Passwort moumlglich Zur Anmeldung muss immer [SYSTEMBenutzername] im Feld Benutzer angegeben werden ansonsten schlaumlgt die Anmeldung fehl Bitte achten Sie darauf dass der bdquoldquo (Slash) und nicht der bdquoldquo (Backslash) verwendet werden muss
31 Server-Protokoll Um das Server-Protokoll anzuzeigen waumlhlen Sie den entsprechenden Menuumlpunkt Dort haben Sie seit BSS 26 die Moumlglichkeit uumlber alle Spalten der Protokolle nach Informationen zu suchen
Seit BSS 31 gibt es die Moumlglichkeit Verfahren in bdquoKopfsaumltzeldquo und bdquoDetailsaumltzeldquo zu unterteilen Wurde das Verfahren entsprechend konfiguriert (wie z B bei der Schnittstelle bdquoXGewerbeanzeigenldquo) dann wird im Protokoll-Kopfsatz nur der Start und das Ende der Ausfuumlhrung in der Liste angezeigt Erst bei einem Klick auf bdquoInformationenldquo wird die Liste aller Detailsaumltze angezeigt die im Durchlauf erzeugt wurden
Release Notes BALVI Schnittstellenserver Seite 29 von 37
Verfahren
Die Liste der verfuumlgbaren Verfahren die bei Ihnen im System installiert sind ZB
BEFUNDEhellip Schnittstelle Befunde LM FM oder TS
PROBEhellip Schnittstelle zum Export von Proben an Labore ebenfalls Spezifisch fuumlr einzelne Fachbereiche
MOBILXT Protokolle der BALVI Mobil XT Synchronisation
WEB Allgemeine nicht spezifizierte Protokolle hierunter ist bislang auch die eFi-Protokollierung zu finden
WEB_I0802 Protokolle zur Schnittstelle BALVI iP LIMS (Lebensmittelproben)
XGEWERBE Schnittstelle XGewerbeanzeigen
Klicken Sie auf die Schaltflaumlche so besteht bei den neuen Protokolldatensaumltzen die Moumlglichkeit Detail-Informationen zum Protokollsatz zu erhalten
Release Notes BALVI Schnittstellenserver Seite 30 von 37
Seit BSS 30x ist die Anzeige der Protokolle ebenfalls farblich abgesetzt so dass Protokolleintraumlge mit Fehlern hellrot und Warnungen hellgelb hinterlegt werden
32 Jobs Mit einem Klick auf den Menuumlpunkt Jobs rufen Sie die Oberflaumlche fuumlr die Job-Konfiguration auf Daraufhin werden alle Jobs aufgelistet die fuumlr den BSS freigegeben sind Hier koumlnnen Sie Einstellungen an den Jobs vornehmen und die Jobs aktivieren bzw deaktivieren Die Beschreibungen bzw Einstellungsmoumlglichkeiten fuumlr den jeweiligen SST-Job sind nicht Bestandteil dieser Dokumentation
33 Log-Ausgaben Uumlber den Menuumlpunkt Log-Ausgaben koumlnnen Sie die Ausgabe der Protokolleintraumlge in Echtzeit beobachten
Release Notes BALVI Schnittstellenserver Seite 31 von 37
Starten Sie die Echtzeit-Protokollierung indem Sie auf die Schaltflaumlche mit dem Symbol bdquoPlayldquo (Dreieck) klicken unterbrechen Sie die Ausgabe indem Sie die auf Schaltflaumlche mit dem Symbol bdquoPauseldquo (zwei Balken) klicken
Klicken Sie auf die Schaltflaumlche bdquoAktualisierenldquo (zwei Pfeile) um die neuesten Protokolleintraumlge angezeigt zu bekommen
Klicken Sie auf das Symbol mit dem Papierkorb um die letzten Protokollmeldungen in der Anzeige zu loumlschen
Die Daten in den Protokolldateien auf der Festplatte des Servers sind davon nicht betroffen
Uumlber das Symbol bdquoLogging anpassenldquo (Schraubenschluumlssel) koumlnnen Sie die Ausgabe der Daten im Echtzeitfenster und in den Protokolldateien aumlndern jedoch ist diese Einstellung nur temporaumlr Die Standardeinstellungen koumlnnen ausschlieszliglich uumlber die Anpassung der Datei bdquologback-bssxmlldquo im Konfigurationsverzeichnis des Servers selbst geaumlndert werden
Release Notes BALVI Schnittstellenserver Seite 32 von 37
In der Logging-Parameter Konfiguration koumlnnen Sie verschiedene Parameter einstellen und uumlber die Schaltflaumlche bdquoAnwendenldquo dann sofort im Echtzeitprotokoll sehen Welche Einstellungen moumlglich sind erfahren Sie wenn es eine akute Fehlersituation gibt die detailliertere Ausgaben im Protokoll erfordert
Warnung Wenn Sie den Log-Level fuumlr ROOT oder eine andere Klasse auf TRACE einstellen werden sehr viele Protokollausgaben generiert die auch dazu fuumlhren koumlnnen dass der Server sehr langsam wird oder die Festplatte des Servers zulaumluft wenn fuumlr das Logging kein Dateilimit konfiguriert wurde
34 LogoutAbmeldung vom System Zum Abmelden waumlhlen Sie oben rechts das Kontextmenuuml
35 Cache loumlschen Der Cache wird in der Regel automatisch geloumlscht Wenn Sie jedoch gerade in BALVI iP eine Aumlnderung an den Schnittstellen eingespielt haben und moumlchten dass diese sofort wirksam wird kann die Funktion bdquoCache loumlschenldquo dazu verwendet werden dass der BALVI Schnittstellenserver die Einstellungen bei der naumlchsten Anfrage neu einliest
Release Notes BALVI Schnittstellenserver Seite 33 von 37
Release Notes BALVI Schnittstellenserver Seite 34 von 37
4 Einrichtung in BALVI iP Um die Verfahren fuumlr den BALVI Schnittstellenserver fuumlr Anwender freizuschalten wird das Objekt bdquoSystemeinstellungenldquo oder bdquoMandanten- und Benutzereinstellungenldquo verwendet Die Anpassung ist je Verfahren moumlglich so kann in BALVI iP fuumlr den Zugriff durch den BALVI Schnittstellenserver ein Benutzer bdquoAldquo am Verfahren bdquoMobilldquo berechtigt werden ein Benutzer bdquoBldquo nur am Verfahren bdquoSLA_FLESHldquo usw Die Logik ist jedoch einheitlich Je Verfahren wird durch BALVI eine Verfahrensgruppe mit dem Verfahrensnamen angelegt und mit den entsprechenden Einstellungen vorkonfiguriert welche durch das Verfahren erforderlich sind Dabei kann die Komplexitaumlt der Einstellungen variieren wie z B an den zu Version 23 verfuumlgbaren Verfahren bdquoMobilldquo und bdquoSLA_Fleshldquo ersichtlich wird
Im Verfahren BALVI Mobil sind diverse Anpassungen moumlglich welche je Bundesland oder eingesetzter Import- und Export-Variante durch den BALVI Schnittstellenserver bei der Bearbeitung von Anfragen gepruumlft werden siehe Punkt 3 Abb Mobil-Einstellung in BALVI iP
Abb Mobil-Einstellung in BALVI iP
Alle Verfahren verwenden jedoch die regulaumlre Benutzerverwaltung von BALVI iP Ein Benutzer ohne Passwort gilt fuumlr BALVI iP als gesperrt was fuumlr das Login bedeutet dass der Anwender sich nur uumlber die Active-Directory-Authentifizierung anmelden kann Ist das nicht moumlglich (bzw nicht konfiguriert) kann der Anwender sich weder in BALVI iP noch uumlber die Webservice-Schnittstelle authentifizieren
Fuumlr Dienste-Schnittstellen welche keine persoumlnliche Authentifizierung durch einen Anwender erfordern wird empfohlen einen separaten Benutzer in der Benutzerverwaltung anzulegen und ein sicheres Kennwort zu vergeben Das Anlegen von zusaumltzlichen Benutzern gilt nicht fuumlr BALVI mobil XT da beim Holen und Uumlbermitteln von Daten jeder Benutzer auch ein fachlich konfigurierter Anwender innerhalb von BALVI iP ist und die Anwendungsoberflaumlche ebenfalls zur Erfassung von Daten verwendet
Unter Punkt 2 der Abb Mobil-Einstellung in BALVI iP wird ein modales Fenster geoumlffnet (Abb BALVI mobil Benutzerverwaltung) Innerhalb dieses modalen Fensters werden mandantenweise die Benutzer fuumlr BALVI
Release Notes BALVI Schnittstellenserver Seite 35 von 37
mobil und den jeweiligen Fachbereich festgelegt Dabei ist es wichtig dass man die Haken bdquoAktiv fuumlr hellipldquo bei bdquohellip mobilldquo und bei einem Fachbereich (bdquohellip LMldquo bdquohellip FMldquo usw) setzt weil sonst uumlber den BALVI Schnittstellenserver keine Kommunikation mit BALVI iP moumlglich ist
Abb BALVI mobil Benutzerverwaltung
Alternativ zur Passwort-Authentifizierung wird wie beschrieben auch die Active-Directory-Authentifizierung angeboten Dazu muss der BALVI iP-Anwender uumlber die Schaltflaumlche bdquoDomaumlnen-Benutzer zuordnenldquo mit dem Active Directory verknuumlpft werden
Nur wenn die Active-Directory-Konfigurationen in BALVI iP und im BALVI Schnittstellenserver auf dieselbe Domaumlne verweisen sind die Domaumlnen-Zuordnung und die Active-Directory-Authentifizierung (z B uumlber BALVI mobil XT) moumlglich
Release Notes BALVI Schnittstellenserver Seite 36 von 37
5 Bekannte Probleme und Loumlsungen
51 ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner Bei der Job-Bearbeitung tritt folgender Fehler auf ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner
Behebung
Fuumlhren Sie das beiliegende IP-Patch (UPDATEexe) aus bevor Sie das WAR austauschen
52 Server startet nicht Sie finden folgende Zeilen im Protokoll (catalinaout oder bsslog)
ERROR [localhost-startStop-1] [IdentityServiceImpl] serverID must not be empty
ERROR [localhost-startStop-1] [ContextLoader] Context initialization failed
Behebung
Setzen Sie die Umgebungsvariable ldquoserverIDrdquo in der Datei bdquocontextxmlldquo
53 ORA-00942 table or view does not exist In vielen Faumlllen wird der Fehler ldquoTabelle oder View nicht vorhandenrdquo ausgeworfen (Java-Protokoll im Ordner logs von Apache Tomcat) wenn eine neue Schnittstelle eingerichtet oder ein neues BALVI iP Release bzw Update eingespielt wurde ohne anschlieszligend das aktuelle GRANT-Skript auszufuumlhren
Behebung
Fuumlhren Sie das GRANT-Skript erneut aus
54 ORA-0406x bdquoBestehender Paketstatus wurde aufgehobenldquo
ORA-04061 Bestehender Status von package body ABCXYZ wurde annulliert
ORA-04065 Ausfuumlhrung nicht erfolgreich package body ABCXYZ wurde geaumlndert oder geloumlscht
Release Notes BALVI Schnittstellenserver Seite 37 von 37
Der Fehler tritt haumlufig ein nachdem die UPDATEexe ausgefuumlhrt und in der Ausfuumlhrungsliste ein Package aktualisiert wurde Oracle merkt sich je User-Session bestimmte Werte im Package wenn der Anwender es verwendet hat Durch einen bdquoCREATE OR REPLACE PACKAGEldquo-Befehl kann dieser Status temporaumlr aufgehoben werden Normalerweise tritt dieser Fehler nach dem Update genau einmal in jeder aktiven Session auf wenn der BSS nicht neu gestartet wird
Behebung
Starten Sie nach jedem Update den BSS neu um alle laufenden Sessions zu beenden
55 Jobs sind nicht ausfuumlhrbar
1 Ein Job wird mit dem Status bdquoNicht unterstuumltztldquo angezeigt wenn fuumlr seine Ausfuumlhrung eine houmlhere Version des BSS erforderlich ist
2 Nach dem Klonen der Datenbank von der Produktions- auf die Testumgebung erhalten alle Jobs automatisch den Status bdquoDeaktiviertldquo wenn die bdquoserverIDldquo nicht identisch ist
Beide Statusaumlnderungen sind gewollt Damit soll verhindert werden dass Jobs nach einem Serverneustart oder nach einem Update automatisch starten und dabei Fehler verursachen
Um Jobs mit dem Status bdquoNicht unterstuumltztldquo nutzen und konfigurieren zu koumlnnen ist es erforderlich den BALVI Schnittstellenserver zu aktualisieren
Deaktivierte Jobs koumlnnen Sie aktivieren indem Sie den jeweiligen Job an den aktuellen Server binden und den Haken bei bdquoAktivldquo setzen
Release Notes BALVI Schnittstellenserver Seite 11 von 37
215 Spracheinstellung Deutsch Es wurde festgestellt dass unter einigen Linux-Versionen die Spracheinstellung beim Starten des Apache Tomcat nicht auf eine deutsche Umgebung verweist Dieses kann technische Probleme verursachen Unter Linux sollte die Einstellung (Umgebungsvariable) entsprechend auf LANG=de_DEUTF-8 eingestellt sein
216 Datenbankverbindung Wenn Sie eine Firewall zwischen dem Oracle-Server und dem Database Connection Pool (DBCP) verwenden sollte unbedingt die bdquovalidationQueryldquo in der DBCP-Konfiguration aktiviert werden damit die Anwendung schneller freie Connections aus dem Pool erhalten kann Die Dokumentation zu den Einstellmoumlglichkeiten ist in der beiliegenden Contextxml ergaumlnzt worden
Bitte beachten Sie dass dringende empfohlen wird die bdquoFactoryldquo auf orgapachetomcatjdbcpoolDataSourceFactory anzupassen falls sie noch auf bdquoorgapachecommonsdbcpBasicDataSourceFactoryldquo eingestellt ist
217 Probleme beim Anlegen von LOB-Objekten Der BALVI Schnittstellen-Server erfordert die JDBC-Spezifikation DBCP V4 welche durch die Factory bdquoorgapachetomcatjdbcldquo ab Tomcat 7 automatisch bereitgestellt wird
Wenn die Pooling-Komponente oder der Oracle-Treiber nicht JDBC4-Kompatibel sind gibt es beim Bearbeiten von LOB-Objekten in Java diverse Exceptions z B
Servletservice() for servlet soapws threw exception
javalangAbstractMethodError
orgapachecommonsdbcpPoolingDataSource$PoolGuardConnectionWrappercreateClob()LjavasqlClob
at debalvicoreauditspyConnectionSpycreateClob(ConnectionSpyjava511)
Ursache dieses Problems ist meistens dass noch nicht auf bdquoorgapachetomcatjdbcldquo umgestellt wurde
218 Umbenennung der gelieferten WAR-Datei Das im Paket von BALVI gelieferte WAR kann jederzeit umbenannt werden (z B als ROOTwar) ohne dass dabei spezielle Einstellungen in der Datei bdquocontextxmlldquo erforderlich sind
Beachten Sie dabei jedoch dass die zum WAR zugehoumlrige Datei bdquocontextxmlldquo im Apache Tomcat immer denselben Namen erhaumllt wie das WAR z B bdquocommserverwarldquo und bdquocommserverxmlldquo Der Name ist dabei ausschlaggebend fuumlr die Zugriffs-Adresse (Context) im Apache Tomcat selbst Die Benennung des WAR in bdquocommserverwarldquo wuumlrde folgendermaszligen aufzurufen sein httpserverportcommserver
219 Server-Schnittstellen Die Uumlberarbeitung bzw Erweiterung der Export- und Importschnittstellen welche uumlber den Schnittstellenserver bereitgestellt werden ist unabhaumlngig vom Schnittstellenserver selbst Die Schnittstellen sind daher nicht Bestandteile des Schnittstellenserver und werden je Verfahren separat
Release Notes BALVI Schnittstellenserver Seite 12 von 37
ausgeliefert Ggf ist es fuumlr unterschiedliche Schnittstellen erforderlich die Grant-Rechte zu aktualisieren (Vgl bdquoWann ist die Ausfuumlhrung des Grant-Skripts erforderlichldquo)
22 Kompatibilitaumltsliste Diverse Verfahren setzen eine Mindestversion des BALVI Schnittstellenservers voraus Die Schnittstellen sind jedoch so konzipiert dass eine Aktualisierung auf eine houmlhere Version des Servers ohne Anpassung an den vorhandenen Schnittstellen jederzeit moumlglich ist
Derzeit sind folgende Mindestanforderungen gegeben
1 BALVI mobil XT 170 oder houmlher setzt BSS 265 und BALVI iP 124x voraus
2 BALVI mobil XT 183 oder houmlher setzt BSS 281 und BALVI iP 124x voraus
3 BALVI mobil 2 (DM) setzt BSS 311 und BALVI iP 124x voraus
4 Die Schnittstelle eFI setzt BSS 251 und BALVI iP 122c voraus
5 Die Schnittstelle LIMS setzt BSS 265 voraus
6 Die Schnittstelle TSK (SN) setzt BSS 265 voraus
7 Die Schnittstelle xDomea (SN) setzt BSS 265 und Java 7 voraus
8 Die Schnittstelle XGewerbeanzeigen 11 setzt BSS 281 BALVI iP 124x Java 8 mit der bdquoJava
Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy2ldquo voraus
9 Die Schnittstelle XGewerbeanzeigen 12 (ab Paket 7 Ausbaustufe 3) setzt BSS 302 BALVI iP
124x Java 8 mit der bdquoJava Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policyldquo
voraus
10 Die Schnittstelle RioPP LM (NRW) setzt BSS 303 und die ETL-Konfiguration voraus
11 Die Schnittstellen zu BALVI iP2 (Fachmodule BTS LM ZDA Stand Juni 2017) setzen BSS 32x
voraus
2 httpwwworaclecomtechnetworkjavajavasedownloadsjce8-download-2133166html
Release Notes BALVI Schnittstellenserver Seite 13 von 37
23 Erforderliche Bibliotheken fuumlr Apache Tomcat Dateiname Funktion Quelle ojdbc6jar Oracle 11gR2 Clientpaket Oracle JDBC Client fuumlr Java
16 ersetzt die bisherige Version bdquoojdbc14jarldquo Die alte Library muss auf jeden Fall entfernt werden
httpwwworaclecomtechnetworkdatabaseenterprise-editionjdbc-112010-090769html
encrypted-datasource-110-alljar
Die Library muss auf jeden Fall entfernt werden Wird derzeit nicht weiter gepflegt da kein Interesse an der Funktionalitaumlt bestand
slf4j-api-1511jar slf4j-log4j12-1511jar log4jdbc4-12beta2jar
Entfaumlllt nicht mehr erforderlich Es wird empfohlen diese zu entfernen falls diese im LIB-Verzeichnis vorhanden sein sollten
commons-dbcp-14jar commons-pool-154jar
Entfaumlllt nicht mehr erforderlich Es wird empfohlen diese zu entfernen falls diese im LIB-Verzeichnis vorhanden sein sollten
Erwartet wird stattdessen ab Tomcat7 die mitgelieferte bdquotomcat-jdbcjarldquo
log4j-1217jar (oder houmlher)
Logging-Funktionalitaumlt Apache Log4j httploggingapacheorglog4j12downloadhtml
bcprov-jdk15on-157jar (oder houmlher)
BouncyCastle Security Provider fuumlr SSLAES hellip wird ab Version 27 im Ordner bdquolibldquo des Tomcat erwartet Sollte es aus Sicherheitsgruumlnden erwuumlnscht sein eine aktuellere Version einzusetzen ist dieses idR moumlglich
httpmvnrepositorycomartifactorgbouncycastlebcprov-jdk15on157
24 Datenbank-Installation Der BALVI Schnittstellenserver benoumltigt auszligerhalb des angebundenen BALVI iP keine eigenen Tabellen Die Web-Anwendung kann im einfachsten Fall direkt auf das Schema von BALVI iP zugreifen indem der Benutzer und das Passwort des BALVI iP-Schemas in der Datei bdquocontextxmlldquo eingetragen werden (nicht empfohlen)
Sollte dies aus Sicherheitsgruumlnden nicht erwuumlnscht sein (empfohlen vom BSI und von BALVI) finden Sie im Paket ein GRANT-Skript um Zugriffsrechte vom BALVI iP Schema fuumlr den Webservice-Schema-Benutzer einzurichten
Zwischen dem Schema von BALVI iP und jeder Web-Anwendung ist dann eine Trennung moumlglich um sicherzustellen dass der Datenbank-Benutzer welcher in der Tomcat-Konfiguration fuumlr die Web-Anwendung eingetragen wird geaumlndert oder geloumlscht werden kann ohne dass die Windows-Anwendung BALVI iP davon betroffen ist Zudem vergibt das von BALVI gelieferte Grant-Skript keine Rechte zum Loumlschen von Tabellenstrukturen oder Tabelleninhalten so dass der Webservice nur festgelegte Daten aumlndern oder lesen darf Es wird empfohlen je Web-Anwendung einen eigenen Datenbank-Benutzer zu vergeben wenn Sie ein BALVI iP mit mehreren Webservices verbinden wollen
Die Moumlglichkeiten im Uumlberblick
1) Sie betreiben den Webservice mit einem eigenstaumlndigen Oracle-Benutzer In diesem Fall muss das
Grant-Skript ausgefuumlhrt werden um den Webservice-Benutzer und den BALVI iP-Benutzer
miteinander zu koppeln
2) In der Tomcat-Konfiguration wird der Oracle-Benutzer eingetragen welcher auch der BALVI iP
Schemabesitzer ist und in der bdquobalviip_conninildquo hinterlegt ist (NICHT Empfohlen) Der Webservice
Release Notes BALVI Schnittstellenserver Seite 14 von 37
hat 100 Zugriffsrechte (auch Loumlsch- oder Aumlnderungsrechte am Schema) es wird kein Grant-
Skript benoumltigt
Wenn Sie die Konfiguration 2) waumlhlen moumlchten koumlnnen Sie die folgenden Unterkapitel uumlberspringen und in Kapitel 0 bzw fortsetzen
241 Erstinstallation Datenbank-Benutzer anlegen Wenn Sie den Webservice-Benutzer vom BALVI iP Schema trennen moumlchten muss durch die DB-Administration in der Oracle-Server-Instanz wo auch BALVI iP sein Schema besitzt ein Benutzer (ggf je Web-Anwendung) angelegt werden welcher folgende Rechte benoumltigt
CONNECT
ALTER SESSION
CREATE JOB
CREATE PROCEDURE
CREATE SESSION
CREATE TABLE
CREATE TRIGGER
CREATE TYPE
CREATE VIEW
CREATE SEQUENCE
CREATE SYNONYM
QUERY REWRITE
Der Default-Tablespace ist frei waumlhlbar Der Benutzer braucht das Recht QUOTA UNLIMITED auf den Tablespace von BALVI iP (Default BALVI_IP) Ein Beispiel-Create-Skript bdquooraCreate_WEB_Usersqlldquo liegt der Auslieferung bei
242 Rechte zuweisen Wenn der BALVI iP Schemabesitzer NICHT in der Tomcat-Umgebung eingetragen werden soll muss ein Oracle DBA das beiliegende GRANT-Skript bdquooraGrantIP_to_Websqlldquo ausfuumlhren um dem jeweiligen Webservice (in Tomcat verwendeten Oracle-Benutzer) die minimalen Rechte auf das Schema von BALVI iP zu gewaumlhren
Dieses Skript setzt voraus dass es von einem Oracle Administrator als bdquoUser SYSTEMldquo ausgefuumlhrt wird Lesen Sie die im Skript enthaltenen README-Kommentare und passen Sie die Benutzer (BALVI iP Schema) und (WEB-Schema) an
====================================================
DEKLARATIVER TEIL MUSS vom KUNDEN geaumlndert
bzw auf die korrekten SCHEMA-Namen angepasst
werden
Die USER-Namen muumlssen in Groszligbuchstaben
geschrieben sein sonst werden sie nicht
gefunden
====================================================
sUserBALVI_IP = BALVI_IP_SCHEMABESITZER
sUserBALVI_WEB = BALVI_WEB_SCHEMABESITZER
Release Notes BALVI Schnittstellenserver Seite 15 von 37
Neu ab Grant-Skript 158 ist die Umbenennung der Verfahrenszuordnung
Pruumlfen Sie dass die Einstellung fuumlr Ihr BundeslandVerfahren korrekt ist dort muss eine 1 fuumlr min ein Verfahren gesetzt sein Diese Einstellung befindet sich direkt unter den Schemabesitzer-Angaben
-- Verfahrensbezogene Konfiguration
-- Setzen Sie fuumlr das jeweilige Verfahren eine 1
-- BALVI Schnittstellenserver (BSS)
-- bis V266 auch BALVI Kommunikationsserver (BKS) genannt
-- generell fuumlr die meisten Verfahren guumlltig
-- Ab Version 57 entfaumlllt mit der Einfuumlhrung der
-- Schnittstelle XGewerbeanzeigen auch der separate Schalter
-- WS_BTR beide Verfahren wurden vereinheitlicht
WS_BSS = 1
Fuumlhren Sie das Skript nach der Anpassung als User SYSTEM aus um die Grants durchzufuumlhren Dieses wurde mit dem von ORACLE gelieferten Programm SQLPLUS (Command-Line) SQLPLUS Worksheet (GUI) und Oracle SQL-Developer getestet
Das Skript generiert fuumlr jedes Objekt ein SYNONYM fuumlr den WEB-USER so dass dieser auf die Objekte ohne Angabe des Owners des IP-Schemas zugreifen kann Pruumlfen Sie nach der Ausfuumlhrung dass die SYNONYMS vorhanden und VALID sind dieses kann ggf nicht der Fall sein Das Skript kann jederzeit erneut ausgefuumlhrt werden um die Grants neu zu erzeugen und bietet ebenfalls die Option alle Grants und Synonyme wieder zu entfernen Detaillierte Informationen zur Nutzung des Skripts sind als Kommentar-Block im Skript enthalten
Hinweis Die Versionsinformation ist unter den Kommentaren direkt im Skript zu finden
Zugriffsberechtigungen fuumlr Webanwendungen auf BALVI iP anlegen
===============================================================
Version 158
Guumlltig fuumlr BALVI iP 123 oder houmlher
Autor Frank Holler
SVN Revisionsinformationen
$Revision 479 $
$Date 2016-02-15 152755 +0100 (Mo 15 Feb 2016) $
================================================================
243 Wann ist die Ausfuumlhrung des Grant-Skripts erforderlich Durch das Strukturupdate von BALVI iP (z B 1240 auf 1241) werden veraltete Strukturen geloumlscht und ggf neue Views oder Tabellen angelegt Die Grant-Rechte geht dabei ggf verloren Daher ist die Ausfuumlhrung des Grant-Skripts immer dann erforderlich wenn sich die Datenbank-Struktur von BALVI iP veraumlndert
Zudem kann es fachliche Neuerungen geben welche im alten Grant-Skript nicht vorhanden sind Daher muss das Skript ggf auch ausgefuumlhrt werden wenn eine neue Schnittstelle im Schnittstellenserver bereitgestellt wurde Dieses betrifft z B auch die Bereitstellung von neuen Versionen von BALVI mobil XT
Release Notes BALVI Schnittstellenserver Seite 16 von 37
da auch dort mit einem fachlich erweiterten Client die Moumlglichkeit besteht dass neue Schnittstellen bereitgestellt und somit mehr Schreibrechte auf Tabellen benoumltigt werden
244 Welche Version des Grant-Skripts soll ich nehmen Wie der Schnittstellenserver sind auch die Grant-Skripte versioniert Neuere Versionen des Grant-Skriptes sind abwaumlrts-kompatibel und koumlnnen immer verwendet werden auch wenn in einer Schnittstellenbeschreibung eine aumlltere Version des Grant-Skriptes explizit benannt wurde
245 Kombination von mehreren Verfahren Wenn Sie zwei oder mehr Schnittstellen im BSS verwenden moumlchten ist es ggf erforderlich auch mehrere Verfahren auf aktiv (bdquo1ldquo) zu setzen
Im Beispiel nehmen wir an Sie moumlchten bdquoeFildquo und bdquoBALVI mobil XTldquo im Schnittstellenserver bereitstellen In der Beschreibung von bdquoeFildquo steht dass das Grant-Skript V36 erforderlich ist BALVI mobil XT 18 erfordert jedoch schon V56
Wenn Sie beide Verfahren betreiben ist im Grant-Skript (V56 oder houmlher) die Einstellung fuumlr beide Verfahren zu aktivieren
====================================================
DEKLARATIVER TEIL MUSS vom KUNDEN geaumlndert
bzw auf die korrekten SCHEMA-Namen angepasst
werden
Die USER-Namen muumlssen in Groszligbuchstaben
geschrieben sein sonst werden sie nicht
gefunden
====================================================
sUserBALVI_IP = BALVI_IP_SCHEMA
sUserBALVI_WEB = WEBAPP_SCHEMA
-- Verfahrensbezogene Konfiguration
-- Setzen Sie fuumlr das jeweilige Verfahren eine 1
-- BALVI Schnittstellenserver (BSS)
-- bis V266 auch BALVI Kommunikationsserver (BKS) genannt
-- generell fuumlr die meisten Verfahren guumlltig
-- Ab Version 57 entfaumlllt mit der Einfuumlhrung der
-- Schnittstelle XGewerbeanzeigen auch der separate Schalter
-- WS_BTR beide Verfahren wurden vereinheitlicht
WS_BSS = 1
-- WebService BTR (Betriebsstaumlttenregister) (NRW TH)
-- entfernt mit Update V57 setzen Sie stattdessen bei WS_BSS = 1
--WS_BTR = 0
-- Probenahme Futtermittel im Browser(BY)
WS_PROBE_FM = 0
-- Risikoorientierte Probenplanung Futtermittel ndash RIOPP FM (BY)
WS_RIOPP_FM = 0
-- Verfahren Export an EFi (Status Pilotbetrieb)
WS_EFI = 1
-- neu ab Version 35 des Grant-Skriptes ist die Moumlglichkeit den Webuser
Release Notes BALVI Schnittstellenserver Seite 17 von 37
-- fuumlr das Loumlschen der Ausgangskoumlrbe explizit zu berechtigen bzw sogar einen
-- expliziten abweichenden User festzulegen Die Konfiguration in der
-- Job-Oberflaumlche sieht vor dass man die Oracle-Datenbank-Zugangsdaten fuumlr
-- das Loumlschen einstellen muss Hier muss im Normalfall derselbe Oracle
-- Datenbankbenutzer eingetragen werden wie in der Tomcat-Verbindungs-
-- konfiguration In diesem Fall sollte wenn WS_EFI = 1 eingestellt wurde
-- ebenfalls WS_EFI_DELETE = 1 eingestellt werden
-- Alternativen
-- 1) Datenbankbenutzer aumlndern
-- Wenn bei sUserEFI_TRUNC anstatt sUserBALVI_WEB (Standard) ein anderer
-- Oracle-Benutzername angegeben wird wird das Loumlschrecht fuumlr die EFi
-- Ausgangskoumlrbe Datenbankseitig exklusiv dem angegeben Datenbankbenutzer
-- zugewiesen
-- 2) Loumlschrecht verweigern
-- Setzen Sie die Variablen WS_EFI_DELETE = 0 damit kein Loumlschrecht
-- zugeweisen wird
WS_EFI_DELETE = 0
-- Beispiel Anderer Benutzer muss in der Datenbank existieren
-- Entfernen Sie die fuumlhrenden -- vor der Variable sUserEFI_TRUNC und
-- setzen den entsprechenden Oracle-Benutzer ein
--sUserEFI_TRUNC = TEST_EFI_TRUNC
hellip
25 Konfiguration des Schnittstellen-Servers
251 Die bdquocontextxmlldquo-Parameter Die von der Servlet-Spezifikation vorgegeben Rump-Struktur sieht folgendermaszligen aus
ltxml version=10 encoding=utf-8gt
ltDOCTYPE Contextgt
ltContextgt
lt-- Kundenspezifische Einstellungen --gt
ltContextgt
Anwendungsspezifische Einstellungen werden zwischen ltContextgt und ltContextgt eingefuumlgt Alle allgemeinguumlltigen Einstellungen in der Datei bdquocontextxmlldquo werden hier erlaumlutert Kommentare finden sich auch in der von BALVI ausgelieferten Beispiel-Konfiguration
Neben den im Folgenden beschriebenen Standard-Einstellungen kann es auch vorkommen dass bundeslandspezifische Erweiterungen vorhanden sind welche nicht in dieser Dokumentation aufgefuumlhrt werden Diese funktionieren trotzdem regulaumlr weiter wenn keine expliziten Informationen zu Kompatibilitaumltsproblemen in den Release-Notes aufgefuumlhrt wurden
2511 Datenbankverbindung jdbcDataSource
Die Datenbankverbindung wird uumlber die von DBCP und dem Oracle-Treiber vorgegebenen Moumlglichkeiten realisiert Der Einsatz der orgapachetomcatjdbcpoolDataSourceFactory (automatisch verfuumlgbar ab Apache Tomcat 7 in der mitgelieferten tomcat-dbcpjar) wird als Beispiel-Konfiguration ausgeliefert
ltResource
name=jdbcDataSource
auth=Container
Release Notes BALVI Schnittstellenserver Seite 18 von 37
type=javaxsqlDataSource
factory=orgapachetomcatjdbcpoolDataSourceFactory
maxActive=10 initialSize=3
maxIdle=5
maxWait=10000
url=jdbcoraclethinBL2-ORA10-KUNDENBALVIINTERN1521ORCL
driverClassName=oraclejdbcdriverOracleDriver
username=balvi_webservice_schema
password=balvi_webservice_password
description=Oracle Datasource
maxOpenPreparedStatements=50
removeAbandoned=false
removeAbandonedTimeout=100
logAbandoned=true
jdbcInterceptors=hellip
gt
Hinweise zur Einstellung der jdbcDataSource
Standard-Einstellungen fuumlr den Datenbank-Verbindungspool
Der Verbindungspool muss entsprechend der Anzahl der zu erwartenden gleichzeitigen Benutzer konfiguriert werden Wenn Sie erwarten dass 50 Anwender gleichzeitig arbeiten stellen Sie bitte folgende Werte ein
maxActive=(50 + 10 (fuumlr System und Jobs)) = 60
maxIdle= (50 10) = 5
1 maxActive - maximale Anzahl der gleichzeitigen aktiven Anfragen an die DB
Wenn der Werte maxActive erreicht ist z B wenn mehrere Benutzer gleichzeitig einen Export starten moumlchten welcher laumlngere Zeit in Anspruch nimmt dann kann der Server die Anfrage nicht mehr bedienen und der Anwender wird abgewiesen maxActive hat zudem Auswirkungen auf die im Hintergrund ausgefuumlhrten Jobs maxActive wird daher kalkuliert mit der Anzahl der Anwender und moumlglicher Datenbank-Connections fuumlr Hintergrund-Jobs Jeder aktiv ausgefuumlhrte Job benoumltigt mindestens eine Connection nur selten wird aus Performance-Gruumlnden mehr als eine Connection waumlhrend der Job-Ausfuumlhrung verwendet Im Normalfall sollten daher 10 Connections fuumlr Hintergrundprozesse ausreichend sein
2 maxIdle - Anzahl der offenen Verbindungen auch wenn der Server im Leerlauf ist
Jede offene Verbindung im Leerlauf haumllt auf dem Datenbankserver eine Session offen Auch diese erfordert Ressourcen Wenn die Verbindungen jedoch geschlossen werden kann die Anfragezeit fuumlr eine neue Verbindung steigen da diese Verbindung erst neu ausgehandelt werden muss Die Empfehlung fuumlr den Wert bdquomaxIdleldquo ist ca 10 der Einstellung von maxActive
KeepAlive-Einstellungen fuumlr den Pool
1 validationQuery
Diese wird ausgefuumlhrt um die Verbindung zu DB zu validieren Es MUSS ein Datensatz zuruumlckgegeben werden ansonsten nimmt der DBCP an dass die Abfrage nicht erfolgreich abgesetzt wurde Achten Sie also bitte darauf dass die Abfrage nicht zu leitungsintensiv ist und genau einen Datensatz liefert
Release Notes BALVI Schnittstellenserver Seite 19 von 37
Oracle bietet dafuumlr die virtuelle Tabelle DUAL an welche sich fuumlr die ValidationQuery sehr gut eignet da die Abfrage kaum Ressourcen verbraucht
validationQuery=select 1 from dual
2 testOnBorrow - Boolscher Wert true oder false
Diese Einstellung sorgt dafuumlr dass der Pool die Verfuumlgbarkeit anhand der validationQuery pruumlft bevor
die DB-Verbindung an die Anwendung ausgeliehen wird Empfehlung
testOnBorrow=true
3 testWhileIdle - Boolscher Wert true oder false
Diese Einstellung ist hilfreich wenn zwischen dem Tomcat und der DB eine Firewall mit Stateful
Packet Inspection verwendet wird Nach laumlngerer Inaktivitaumlt wird normalerweise durch die Firewall die
DB-Verbindung geschlossen Dieses loumlst dann beim Ausleihen der Verbindung eine Fehlermeldung im
Protokoll aus 2012-08-16 165418720 WARN [http-0000-8080-8]
[orgspringframeworkjdbcsupportSQLErrorCodesFactory] Error while extracting
database product name - falling back to empty error codes
orgspringframeworkjdbcsupportMetaDataAccessException Error while extracting
DatabaseMetaData nested exception is javasqlSQLRecoverableException Getrennte
Verbindung Um dieses Problem zu beheben sollte die Option testWhileIdle=true eingestellt werden
testWhileIdle=true
Damit diese weiszlig wie oft eine Pruumlfung durchgefuumlhrt werden muss sind jedoch noch zusaumltzliche Angaben erforderlich welche fuumlr die Einstellung der Zeit zusaumltzlich gesetzt werden muumlssen
a) minEvictableIdleTimeMillis - Long in Millisekunden
Min Zeit wie lange eine DB-Verbindung im Leerlauf ist bevor diese zur Pruumlfung
gekennzeichnet wird Dieses haumlngt stark von der Einstellung der Firewall ab Wenn Sie eine
sehr restriktive Firewall haben kann es sein dass diese die Verbindung nach wenigen
Minuten Leerlauf trennt Stellen Sie den Wert immer so ein dass dieser unter der Leerlaufzeit
der Firewall liegt empfohlen 300000 entspricht 300 Sek = 5 min
minEvictableIdleTimeMillis=300000
b) timeBetweenEvictionRunsMillis - Long in Millisekunden
Der Pruumlflauf startet in der Default-Konfiguration alle 1800000 Millisekunden = 30 Min n als
zu Pruumlfen markierte Verbindungen werden in einem Pruumlflauf getestet n wird bestimmt durch
die Einstellung numTestsPerEvictionRun Empfehlung Stellen Sie den Wert auf alle 15 Min
ein
timeBetweenEvictionRunsMillis=900000
Release Notes BALVI Schnittstellenserver Seite 20 von 37
c) numTestsPerEvictionRun - Integer
Wie viele Verbindungen sollen getestet werden waumlhrend der Pruumlflauf ausgefuumlhrt wird Im
Normalfall sollte die Anzahl der zu testenden Verbindungen nicht zu hoch eingestellt werden
Der Default ist 3 Wenn Sie houmlhere Sicherheit haben wollen dass keine bdquototenldquo
Datenbankverbindungen bestehen bleiben erhoumlhen Sie den Wert auf max bdquo(maxActive ndash
maxIdle) 2ldquo Wenn Ihnen 3 ausreichend erscheint muss der Wert nicht gesetzt sein dann
wird der Default verwendet
Beispiel numTestsPerEvictionRun=10
4 Interceptors konfigurieren Neu ergaumlnzt wurde die Moumlglichkeit spezielle bdquoInterceptorsldquo zu konfigurieren die ermoumlglichen das Verhalten des Pools zu steuern Wichtig hierbei ist dass die Angabe von Werten auf real existierende Java-Klassen erfolgt die im Classpath des Tomcat vorhanden sind Groszlig-und-Kleinschreibung ist zu beachten Folgende Default-Einstellung hat BALVI fuumlr den BSS festgelegt jdbcInterceptors=
orgapachetomcatjdbcpoolinterceptorConnectionState
orgapachetomcatjdbcpoolinterceptorStatementFinalizer
orgapachetomcatjdbcpoolinterceptorResetAbandonedTimer
Details zu den verwendeten Interceptor-Einstellungen finden Sie in der Tomcat-Dokumentation3
3 httptomcatapacheorgtomcat-80-docjdbc-poolhtmlJDBC_interceptors
Release Notes BALVI Schnittstellenserver Seite 21 von 37
2512 Datenbank-Zugangsdaten verschluumlsseln
Die Verschluumlsselung fuumlr die Datenbank-Verbindung (bdquoEncrypted Datasourceldquo) ist eine Ableitung der Bibliothek Apache-Common-DBCP-14 und daher nicht mehr mit Java 8 kompatibel Die Einrichtung der Verschluumlsselung wird daher mit der Auslieferung des BSS 30 nicht mehr angeboten
2513 Active-Directory-Authentifizierung
Uumlber die folgenden Parameter wird der Zugriff des Schnittstellen-Servers auf einen Microsoft Active Directory Domain-Controller konfiguriert
ldquoldapServerAddressrdquo
Syntax PROTOKOLLIP-Adresse oder DNS-NamePORT
ltEnvironment
name=ldapServerAddress
value=ldapbl2-dc02balviintern389
type=javalangString
override=true
gt
Als Protokoll besteht auch die Moumlglichkeit ldaps (LDAP+SSL) wenn der Domain-Controller entsprechend konfiguriert wurde Im Java Truststore muss dann das Zertifikat der CA vorhanden sein welche das Zertifikat des Domain-Controllers signiert hat Zudem darf bei ldaps keine IP-Adresse verwendet werden es muss der DNS-Name des Server-Zertifikats eingetragen sein Ansonsten gibt es beim Verbinden eine Sicherheits-Exception
lt-- SSL-Beispiel
ltEnvironment
name=ldapServerAddress
value=ldapsbl2-dc02balviintern636
type=javalangString
override=true
gt
--gt
bdquoldapBaseDnrdquo
LDAP-Suchpfad fuumlr die Domain-Basis Diese muss der LDAP-Syntax fuumlr den Domain-Suffix entsprechen
Syntax DC=SERVERDC=ROOTDN
ltEnvironment
name=ldapBaseDn
value=DC=BALVIDC=INTERN
type=javalangString
override=true
gt
Release Notes BALVI Schnittstellenserver Seite 22 von 37
bdquowebLoginUseActiveDirectoryAuthenticationrdquo
Die Authentifizierung in der Browser-Oberflaumlche kann uumlber die Active-Directory-Authentifizierung erfolgen In der ersten Version ist nur die Protokoll-Auswertung moumlglich wenn der ADMIN sich anmeldet Dieser hat normalerweise niemals AD-Kennungen zugeordnet BALVI empfiehlt diese Einstellung auf bdquofalseldquo zu belassen Webservices welche uumlber SOAPREST zugreifen koumlnnen die Active-Directory-Authentifizierung trotzdem verwenden
ltEnvironment
name=webLoginUseActiveDirectoryAuthentication
value=false
type=javalangBoolean
override=true
gt
ldquoldapDaysBeforeExpirationNotificationrdquo
Die Passwort-Aumlnderung im Active-Directory uumlber die Browser-Oberflaumlche ist in der ersten Version noch nicht implementiert der Parameter wird bislang nicht ausgewertet
ltEnvironment
name=ldapDaysBeforeExpirationNotification
value=14
type=javalangInteger
override=true
gt
2514 Statement-Protokollierung in BALVI iP
Diese Option aktiviert die Lese- und Aumlnderungsprotokollierung fuumlr BALVI iP Standard ist bdquofalseldquo und wird fuumlr alle Kunden empfohlen solange keine speziellen Datenbank-Jobs eingerichtet wurden welche zeitgesteuert die Protokolleintraumlge wieder loumlschen Fuumlr Bayern wurde ein spezielles Konzept zur Leseprotokollierung entworfen Wenn Sie mehr daruumlber erfahren moumlchten kontaktieren Sie bitte die BALVI GmbH
ltEnvironment
name=enableSqlStatementMonitoring
value=true
type=javalangBoolean
override=true
gt
Beachten Sie dass diese Option massive INSERT-Statements in BALVI iP in die Tabelle VIS_D92 ausfuumlhrt Jedes abgesetzte SQL-Statement wird dabei vollstaumlndig protokolliert Dieses erzeugt eine sehr hohe INSERT-Last und in der Folge auch erhoumlhte Redolog-Switches und COMMIT-Transaktionen
Optional Aktivieren der INSERT + APPEND - Logik
Beachten Sie bitte die Hinweise von Oracle zum Hint + APPEND
Release Notes BALVI Schnittstellenserver Seite 23 von 37
Wenn Sie dieses Verhalten aktivieren moumlchten ergaumlnzen Sie bitte den folgenden Environment-Parameter
ltEnvironment
name=statementMonitoringactivateAppendMode
value=true
type=javalangBoolean
override=true
gt
2515 Einstellungen fuumlr BALVI mobil XT (bzw den bdquopartitionedExportldquo)
Diese Logik des FIFO-Buffers wurde so konzipiert dass dem Rechenzentrum diverse Einstellmoumlglichkeiten uumlber die Datei bdquocontextxmlldquo zur Verfuumlgung stehen um die Steuerung des FIFO-Puffers zu beeinflussen
Schematische Darstellung des FIFO-Puffers
Das ermoumlglicht es z B dem BALVI mobil XT Client (14 oder houmlher) den aktiven Block abzuholen und dies beim Fehler bis zu 10-mal zu wiederholen Sobald der Block [001] erfolgreich beim Client angekommen ist und dieser den naumlchsten Block anfragt wird der Block [001] verworfen wird Der Server fuumlllt dann im Hintergrund den frei gewordenen Block wieder waumlhrend der Client den Block [002] abholt
Die Groumlszlige und Anzahl der vorgecachten Bloumlcke kann uumlber die folgenden Einstellungen in der Datei bdquocontextxmlldquo definiert werden
ltEnvironment
name=partitionedExportmaxBufferedPartitions
value=3 type=javalangInteger override=true
gt
ltEnvironment
name=partitionedExportpartitionSize
value=256000 type=javalangInteger override=true
gt
Die Einstellung partitionedExportmaxBufferedPartitions ist dabei die Anzahl der vorgecachten Bloumlcke mindestens muss 2 angegeben werden Der Puffercache wird ausschlieszliglich im RAM der JVM aufgebaut es wird folglich mehr Arbeitsspeicher verwendet Dieser Arbeitsspeicher muss je gleichzeitiger Session auf dem Server bereitgestellt werden die Default-Einstellung mit 3 Partitionen a 256 KB + dem aktiven Puffer erfordern 1 MB RAM je aktiven Anwender
Aktiv
er
Puffe
r
[001] Vorg
ecac
hter
Bl
ock
[002] Vorg
ecac
hter
Bl
ock
[003]
Aktiv
er P
uffe
r
[002] Vorg
ecac
hter
Bl
ock
[003] Vorg
ecac
hter
Bl
ock
[leer]
Release Notes BALVI Schnittstellenserver Seite 24 von 37
Gleichzeitig wurde die Moumlglichkeit geschaffen dass die maximale Anzahl an gleichzeitigen Exporten durch das Rechenzentrum eingeschraumlnkt werden kann um einem OutOfMemory-Fehler vorzubeugen Die Einstellung
ltEnvironment
name=partitionedExportmaxConcurrentExports
value=10 type=javalangInteger override=true
gt
muss entsprechend der zu erwartenden gleichzeitigen Zugriffe konzipiert werden ansonsten wird der Server einen Verbindungsversuch durch die Clients ablehnen
Beachten Sie dass die folgenden Einstellungen partitionedExportmaxBufferedPartitions partitionedExportmaxConcurrentExports und partitionedExportpartitionSize gemeinsam als Rechenbasis fuumlr den RAM-Bedarf des Webservers herangezogen werden muumlssen
Folgende Faustformel sollte fuumlr die Einrichtung verwendet werden
Min 256 MB (Serverbasis) + (11 partitionedExportmaxConcurrentExports partitionedExportmaxBufferedPartitions partitionedExportpartitionSize)
Beispiel 50 gleichzeitige Anwender Blockgroumlszlige 256 KB 4 Partitionen
256 MB + (11 50 256 4) KB = 312 MB fuumlr die JVM
Empf 512 MB (Serverbasis) + (12 partitionedExportmaxConcurrentExports partitionedExportmaxBufferedPartitions partitionedExportpartitionSize)
Beispiel 50 gleichzeitige Anwender Blockgroumlszlige 256 KB 4 Partitionen
512 MB + (12 50 256 4) KB = 572 MB fuumlr die JVM
partitionedExportmaxConcurrentExports
Bestimmt die Anzahl der maximalen Export Tasks (Threads) die fuumlr partitionierte Exporte bereitgestellt werden Wenn die Anzahl uumlberschritten wird wird die entsprechende Exportanfrage abgewiesen und der Client muss zu einem spaumlteren Zeitpunkt erneut anfragen Stellen Sie diesen Wert entsprechend der zu erwartenden Benutzeranzahl ein bei 50 Anwendern also 50
Exporte oumlffnen auf der Datenbank entsprechend zur Ausfuumlhrungszeit min einen Cursor ggf fuumlr rekursive Unterabfragen kurzfristig sogar mehr Die hier eingestellte Anzahl muss mit der Anzahl von maxActive korrelieren
ltEnvironment
name=partitionedExportmaxConcurrentExports
value=10 type=javalangInteger override=true
gt
partitionedExportmaxBufferedPartitions
Bestimmt die Anzahl der Datenbloumlcke (Partitionen) die vom Server bei Abruf eines Exportes gepuffert werden Die seit Version 24 eingefuumlhrte FIFO-Puffer-Logik ermoumlglicht dass der Server schon die Ergebnisse vorpuffert so dass der Client weniger Wartezeiten bei der Anfrage nach Daten hat Diese
Release Notes BALVI Schnittstellenserver Seite 25 von 37
Puffer-Logik unterteilt den Exportdatenstrom (je Export) in mehre Bloumlcke Der Client kann nun den letzten Block neu anfordern oder den naumlchsten Block wenn der letzte Block erfolgreich verarbeitet wurde Wie viele naumlchste Bloumlcke durch den Server bereit gestellt werden entscheidet diese Einstellung Sobald kein naumlchster Block mehr bereit gestellt werden muss wird der Datenbank-Cursor geschlossen eine Erhoumlhung kann also zu einer Entlastung der aktiven DB-Verbindungen fuumlhren erhoumlht jedoch den Bedarf an RAM des Servers
Der von BALVI voreingestellte Wert ist 3
ltEnvironment
name=partitionedExportmaxBufferedPartitions
value=3 type=javalangInteger override=true
gt
partitionedExportpartitionSizeldquo
Die Groumlszlige der Datenbloumlcke (Partitionen) die an den Client uumlbermittelt werden in Bytes Wenn Sie diesen Wert zu niedrig einstellen reduziert sich die Effizienz des Caches da der Client mehr Datenbloumlcke hintereinander abrufen muss Waumlhlen Sie einen zu groszligen Wert wird die neu zu uumlbertragende Datenmenge im Fall eines Fehlers houmlher
Der von BALVI voreingestellte Wert ist 256000 (256 KB)
ltEnvironment
name=partitionedExportpartitionSize
value=256000 type=javalangInteger override=true
gt
exportTokensmaxTokenCount
Maximale Anzahl der gleichzeitig vergebenen Token die vom Server gecached werden Jede Sitzung welche einen Export durchfuumlhrt erhaumllt einen Session-Token
Wenn eine Sitzung laumlngere Zeit nicht verwendet wurde wird dieser Session-Token wieder entfernt Wenn Sie den Wert zu niedrig einstellen fuumlhrt das zu einer generellen Session-Begrenzung auch fuumlr den nicht partitionierten Export-Modus welcher ab Version 21 verfuumlgbar ist
Ist die Anzahl der Tokens houmlher als die Datenbankeinstellung maxActive kann es vorkommen dass zwar eine Session gestartet werden kann jedoch kein Datenexport zustande kommt
Der von BALVI voreingestellte Wert ist 2000
ltEnvironment
name=exportTokensmaxTokenCount
value=20 type=javalangInteger override=true
gt
exportTokenstokenExpirationInSeconds
Zeit in Sekunden die verstreichen muss bis ein Token unguumlltig wird falls darauf kein Zugriff mehr erfolgt Nach einem erfolgreichen Export wird der Token automatisch geschlossen diese Option ist fuumlr den Abbruchfall vorgesehen Der von BALVI voreingestellte Wert ist 180 (180 s = 3 min)
Release Notes BALVI Schnittstellenserver Seite 26 von 37
ltEnvironment
name=exportTokenstokenExpirationInSeconds
value=180 type=javalangInteger override=true
gt
exportTokenstokenDisposalInSeconds
Zeit in Sekunden die verstreichen muss bis ein Token das erfolgreich abgearbeitet wurde aus dem Cache geloumlscht wird Um sicher zu stellen dass der letzte Exportblock noch erfolgreich abgerufen werden kann bleibt der Token auch nach Fertigmeldung des Clients noch N Sek guumlltig
Der von BALVI voreingestellte Wert ist 60 (60 s = 1 min)
ltEnvironment
name=exportTokenstokenDisposalInSeconds
value=60 type=javalangInteger override=true
gt
2516 Job-Verwaltung fuumlr den BSS konfigurieren Aktivierung der Jobverwaltung
Bis zur Version 28 des BSS gab es den Parameter bdquoavailableServicesldquo Dieser konnte bei Bedarf aktiviert werden wenn die Jobs benoumltigt wurden
Mit Version 30 ist die Einstellung bdquoavailableServicesldquo zu entfernen und kann durch den neuen optionalen Parameter bdquoisJobServiceEnabledldquo in der Datei bdquocontextxmlldquo ersetzt werden
lt-- Neue Parameter zur Aktivierung des Job Service Ersatz fuumlr availableServices --gt
ltEnvironment
name=isJobServiceEnabled
value=true
type=javalangBoolean
override=true
gt
Ab BSS 30 wird die Jobs-Engine standardmaumlszligig aktiviert Sollte die Jobs-Engine nicht benoumltigt werden muss bdquovalueldquo der Wert bdquofalseldquo zugewiesen werden Wird bdquoisJobServiceEnabledldquo nicht eingefuumlgt sind die Jobs trotzdem standardmaumlszligig aktiv
Nach dem Neustart des Servers und erneutem Einloggen erscheint nun zusaumltzlich der Menuumlpunkt bdquoJobsldquo
bdquopasswordKeyldquo fuumlr Jobs
In der Job-Logik wird ein von BALVI definierter Standard-Schluumlssel fuumlr die Ablagen von schuumltzenswerten Daten z B Passwoumlrtern verwendet Diese Einstellung ermoumlglicht den BALVI-Standard zu uumlberschreiben Wenn Sie diese Einstellung aumlndern muumlssen jedoch alle bislang verschluumlsselten Job-Parameter neu verschluumlsselt werden
ltEnvironment
name=javacompenvjobspasswordKey
value=MeinHochsicheresNeuesPasswort
type=javalangString
Release Notes BALVI Schnittstellenserver Seite 27 von 37
override=true
gt
bdquoJob ID enableddisabledldquo (Deprecated ersetzt ab 28 durch das bdquoBindenldquo von Jobs)
Sondereinstellungen fuumlr die Job-Verwaltung Da alle Jobs in einer Datenbank administriert werden jedoch ggf verteilt auf mehreren Tomcat-Servern ausgefuumlhrt werden sollen besteht hier die Option Jobs fuumlr die aktuelle Tomcat-Instanz separat zu deaktivieren
Die Einstellung ID koumlnnte z B folgendermaszligen aussehen javacompenvjobsC0DB58D8D52C4BBC966D1DC788A4EF8Benabled
Fuumlr weitere Fragen zu dieser Einstellung kontaktieren Sie bitte die BALVI GmbH
ltEnvironment
name=javacompenvjobsIDenabled
value=false
type=javalangBoolean
override=true
gt
2517 Weitere optionale Parameter
Es ist fuumlr diverse einzelne Schnittstellen ggf erforderlich Einstellungen in der Datei bdquocontextxmlldquo zu ergaumlnzen Hinweise zu diesen Parametern sind dann in dem der Schnittstelle beiliegenden Dokument enthalten Das gilt z B fuumlr die Schnittstelle bdquoXGewerbeanzeigenldquo
26 Logging mit logback Das Logging wurde komplett uumlberarbeitet Statt bdquoLog4Jldquo wird jetzt bdquologbackldquo4 benutzt Ab BSS 30 ist es zwingend notwendig die Einstellung vorzunehmen um das Logging der Anwendung zu steuern
Migration Ergaumlnzen Sie die neue Einstellung bdquologgingconfigldquo
lt-- Neue Paramter zur Angabe der Logback Config Ersatz fuumlr log4jConfigLocation --gt
ltEnvironment
name=loggingconfig
value=$catalinabaseconflogback-bssxml
type=javalangString
override=true
gt
Nach wie vor steht es Ihnen frei die Logging-Konfiguration eigenstaumlndig anzupassen
Wenn Sie jedoch dieselbe WAR in einer Tomcat-Instanz unter mehreren Context-Namen betreiben wuumlrden beide dieselbe Logging-Konfiguration verwenden so dass alle Protokolleintraumlge in einer Log-Datei aus
4 httplogbackqoschmanualappendershtml
Release Notes BALVI Schnittstellenserver Seite 28 von 37
mehreren Webanwendungen generiert werden Aumlndern Sie den Namen der Logging-Konfiguration entsprechend ab um fuumlr jede Anwendung eine spezifische Logging-Einstellung vornehmen zu koumlnnen
27 Tocmat Optional Suche im bdquoKlassenpfadldquo um den
Ordner bdquoconfldquo erweitern Die Suche nach Dateien uumlber bdquoclasspathldquo setzt voraus dass die Ordner- und Dateinamen im Apache Tomcat bekannt gegeben werden Der Klassenpfad kann in der Datei bdquocatalinapropertiesldquo angepasst werden Wenn Sie dort unter commonloader die folgenden Werte ergaumlnzen kann eine Datei auch im Ordner conf abgelegt werden damit Apache Tomcat diese findet Ansonsten muss die Datei im Ordner lib abgelegt werden
commonloader=$catalinabaseconf$catalinahomeconf
3 Die neue Browser-Oberflaumlche Der BALVI Schnittstellenserver hat seit Version 25 neben der Protokollierung auch die Moumlglichkeit Job-Konfigurationen zu pflegen Der Login ist nur fuumlr einen in BALVI iP eingetragenen ADMIN (z B Benutzer bdquoSYSTEMADMINldquo) mit dem in BALVI iP hinterlegten Passwort moumlglich Zur Anmeldung muss immer [SYSTEMBenutzername] im Feld Benutzer angegeben werden ansonsten schlaumlgt die Anmeldung fehl Bitte achten Sie darauf dass der bdquoldquo (Slash) und nicht der bdquoldquo (Backslash) verwendet werden muss
31 Server-Protokoll Um das Server-Protokoll anzuzeigen waumlhlen Sie den entsprechenden Menuumlpunkt Dort haben Sie seit BSS 26 die Moumlglichkeit uumlber alle Spalten der Protokolle nach Informationen zu suchen
Seit BSS 31 gibt es die Moumlglichkeit Verfahren in bdquoKopfsaumltzeldquo und bdquoDetailsaumltzeldquo zu unterteilen Wurde das Verfahren entsprechend konfiguriert (wie z B bei der Schnittstelle bdquoXGewerbeanzeigenldquo) dann wird im Protokoll-Kopfsatz nur der Start und das Ende der Ausfuumlhrung in der Liste angezeigt Erst bei einem Klick auf bdquoInformationenldquo wird die Liste aller Detailsaumltze angezeigt die im Durchlauf erzeugt wurden
Release Notes BALVI Schnittstellenserver Seite 29 von 37
Verfahren
Die Liste der verfuumlgbaren Verfahren die bei Ihnen im System installiert sind ZB
BEFUNDEhellip Schnittstelle Befunde LM FM oder TS
PROBEhellip Schnittstelle zum Export von Proben an Labore ebenfalls Spezifisch fuumlr einzelne Fachbereiche
MOBILXT Protokolle der BALVI Mobil XT Synchronisation
WEB Allgemeine nicht spezifizierte Protokolle hierunter ist bislang auch die eFi-Protokollierung zu finden
WEB_I0802 Protokolle zur Schnittstelle BALVI iP LIMS (Lebensmittelproben)
XGEWERBE Schnittstelle XGewerbeanzeigen
Klicken Sie auf die Schaltflaumlche so besteht bei den neuen Protokolldatensaumltzen die Moumlglichkeit Detail-Informationen zum Protokollsatz zu erhalten
Release Notes BALVI Schnittstellenserver Seite 30 von 37
Seit BSS 30x ist die Anzeige der Protokolle ebenfalls farblich abgesetzt so dass Protokolleintraumlge mit Fehlern hellrot und Warnungen hellgelb hinterlegt werden
32 Jobs Mit einem Klick auf den Menuumlpunkt Jobs rufen Sie die Oberflaumlche fuumlr die Job-Konfiguration auf Daraufhin werden alle Jobs aufgelistet die fuumlr den BSS freigegeben sind Hier koumlnnen Sie Einstellungen an den Jobs vornehmen und die Jobs aktivieren bzw deaktivieren Die Beschreibungen bzw Einstellungsmoumlglichkeiten fuumlr den jeweiligen SST-Job sind nicht Bestandteil dieser Dokumentation
33 Log-Ausgaben Uumlber den Menuumlpunkt Log-Ausgaben koumlnnen Sie die Ausgabe der Protokolleintraumlge in Echtzeit beobachten
Release Notes BALVI Schnittstellenserver Seite 31 von 37
Starten Sie die Echtzeit-Protokollierung indem Sie auf die Schaltflaumlche mit dem Symbol bdquoPlayldquo (Dreieck) klicken unterbrechen Sie die Ausgabe indem Sie die auf Schaltflaumlche mit dem Symbol bdquoPauseldquo (zwei Balken) klicken
Klicken Sie auf die Schaltflaumlche bdquoAktualisierenldquo (zwei Pfeile) um die neuesten Protokolleintraumlge angezeigt zu bekommen
Klicken Sie auf das Symbol mit dem Papierkorb um die letzten Protokollmeldungen in der Anzeige zu loumlschen
Die Daten in den Protokolldateien auf der Festplatte des Servers sind davon nicht betroffen
Uumlber das Symbol bdquoLogging anpassenldquo (Schraubenschluumlssel) koumlnnen Sie die Ausgabe der Daten im Echtzeitfenster und in den Protokolldateien aumlndern jedoch ist diese Einstellung nur temporaumlr Die Standardeinstellungen koumlnnen ausschlieszliglich uumlber die Anpassung der Datei bdquologback-bssxmlldquo im Konfigurationsverzeichnis des Servers selbst geaumlndert werden
Release Notes BALVI Schnittstellenserver Seite 32 von 37
In der Logging-Parameter Konfiguration koumlnnen Sie verschiedene Parameter einstellen und uumlber die Schaltflaumlche bdquoAnwendenldquo dann sofort im Echtzeitprotokoll sehen Welche Einstellungen moumlglich sind erfahren Sie wenn es eine akute Fehlersituation gibt die detailliertere Ausgaben im Protokoll erfordert
Warnung Wenn Sie den Log-Level fuumlr ROOT oder eine andere Klasse auf TRACE einstellen werden sehr viele Protokollausgaben generiert die auch dazu fuumlhren koumlnnen dass der Server sehr langsam wird oder die Festplatte des Servers zulaumluft wenn fuumlr das Logging kein Dateilimit konfiguriert wurde
34 LogoutAbmeldung vom System Zum Abmelden waumlhlen Sie oben rechts das Kontextmenuuml
35 Cache loumlschen Der Cache wird in der Regel automatisch geloumlscht Wenn Sie jedoch gerade in BALVI iP eine Aumlnderung an den Schnittstellen eingespielt haben und moumlchten dass diese sofort wirksam wird kann die Funktion bdquoCache loumlschenldquo dazu verwendet werden dass der BALVI Schnittstellenserver die Einstellungen bei der naumlchsten Anfrage neu einliest
Release Notes BALVI Schnittstellenserver Seite 33 von 37
Release Notes BALVI Schnittstellenserver Seite 34 von 37
4 Einrichtung in BALVI iP Um die Verfahren fuumlr den BALVI Schnittstellenserver fuumlr Anwender freizuschalten wird das Objekt bdquoSystemeinstellungenldquo oder bdquoMandanten- und Benutzereinstellungenldquo verwendet Die Anpassung ist je Verfahren moumlglich so kann in BALVI iP fuumlr den Zugriff durch den BALVI Schnittstellenserver ein Benutzer bdquoAldquo am Verfahren bdquoMobilldquo berechtigt werden ein Benutzer bdquoBldquo nur am Verfahren bdquoSLA_FLESHldquo usw Die Logik ist jedoch einheitlich Je Verfahren wird durch BALVI eine Verfahrensgruppe mit dem Verfahrensnamen angelegt und mit den entsprechenden Einstellungen vorkonfiguriert welche durch das Verfahren erforderlich sind Dabei kann die Komplexitaumlt der Einstellungen variieren wie z B an den zu Version 23 verfuumlgbaren Verfahren bdquoMobilldquo und bdquoSLA_Fleshldquo ersichtlich wird
Im Verfahren BALVI Mobil sind diverse Anpassungen moumlglich welche je Bundesland oder eingesetzter Import- und Export-Variante durch den BALVI Schnittstellenserver bei der Bearbeitung von Anfragen gepruumlft werden siehe Punkt 3 Abb Mobil-Einstellung in BALVI iP
Abb Mobil-Einstellung in BALVI iP
Alle Verfahren verwenden jedoch die regulaumlre Benutzerverwaltung von BALVI iP Ein Benutzer ohne Passwort gilt fuumlr BALVI iP als gesperrt was fuumlr das Login bedeutet dass der Anwender sich nur uumlber die Active-Directory-Authentifizierung anmelden kann Ist das nicht moumlglich (bzw nicht konfiguriert) kann der Anwender sich weder in BALVI iP noch uumlber die Webservice-Schnittstelle authentifizieren
Fuumlr Dienste-Schnittstellen welche keine persoumlnliche Authentifizierung durch einen Anwender erfordern wird empfohlen einen separaten Benutzer in der Benutzerverwaltung anzulegen und ein sicheres Kennwort zu vergeben Das Anlegen von zusaumltzlichen Benutzern gilt nicht fuumlr BALVI mobil XT da beim Holen und Uumlbermitteln von Daten jeder Benutzer auch ein fachlich konfigurierter Anwender innerhalb von BALVI iP ist und die Anwendungsoberflaumlche ebenfalls zur Erfassung von Daten verwendet
Unter Punkt 2 der Abb Mobil-Einstellung in BALVI iP wird ein modales Fenster geoumlffnet (Abb BALVI mobil Benutzerverwaltung) Innerhalb dieses modalen Fensters werden mandantenweise die Benutzer fuumlr BALVI
Release Notes BALVI Schnittstellenserver Seite 35 von 37
mobil und den jeweiligen Fachbereich festgelegt Dabei ist es wichtig dass man die Haken bdquoAktiv fuumlr hellipldquo bei bdquohellip mobilldquo und bei einem Fachbereich (bdquohellip LMldquo bdquohellip FMldquo usw) setzt weil sonst uumlber den BALVI Schnittstellenserver keine Kommunikation mit BALVI iP moumlglich ist
Abb BALVI mobil Benutzerverwaltung
Alternativ zur Passwort-Authentifizierung wird wie beschrieben auch die Active-Directory-Authentifizierung angeboten Dazu muss der BALVI iP-Anwender uumlber die Schaltflaumlche bdquoDomaumlnen-Benutzer zuordnenldquo mit dem Active Directory verknuumlpft werden
Nur wenn die Active-Directory-Konfigurationen in BALVI iP und im BALVI Schnittstellenserver auf dieselbe Domaumlne verweisen sind die Domaumlnen-Zuordnung und die Active-Directory-Authentifizierung (z B uumlber BALVI mobil XT) moumlglich
Release Notes BALVI Schnittstellenserver Seite 36 von 37
5 Bekannte Probleme und Loumlsungen
51 ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner Bei der Job-Bearbeitung tritt folgender Fehler auf ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner
Behebung
Fuumlhren Sie das beiliegende IP-Patch (UPDATEexe) aus bevor Sie das WAR austauschen
52 Server startet nicht Sie finden folgende Zeilen im Protokoll (catalinaout oder bsslog)
ERROR [localhost-startStop-1] [IdentityServiceImpl] serverID must not be empty
ERROR [localhost-startStop-1] [ContextLoader] Context initialization failed
Behebung
Setzen Sie die Umgebungsvariable ldquoserverIDrdquo in der Datei bdquocontextxmlldquo
53 ORA-00942 table or view does not exist In vielen Faumlllen wird der Fehler ldquoTabelle oder View nicht vorhandenrdquo ausgeworfen (Java-Protokoll im Ordner logs von Apache Tomcat) wenn eine neue Schnittstelle eingerichtet oder ein neues BALVI iP Release bzw Update eingespielt wurde ohne anschlieszligend das aktuelle GRANT-Skript auszufuumlhren
Behebung
Fuumlhren Sie das GRANT-Skript erneut aus
54 ORA-0406x bdquoBestehender Paketstatus wurde aufgehobenldquo
ORA-04061 Bestehender Status von package body ABCXYZ wurde annulliert
ORA-04065 Ausfuumlhrung nicht erfolgreich package body ABCXYZ wurde geaumlndert oder geloumlscht
Release Notes BALVI Schnittstellenserver Seite 37 von 37
Der Fehler tritt haumlufig ein nachdem die UPDATEexe ausgefuumlhrt und in der Ausfuumlhrungsliste ein Package aktualisiert wurde Oracle merkt sich je User-Session bestimmte Werte im Package wenn der Anwender es verwendet hat Durch einen bdquoCREATE OR REPLACE PACKAGEldquo-Befehl kann dieser Status temporaumlr aufgehoben werden Normalerweise tritt dieser Fehler nach dem Update genau einmal in jeder aktiven Session auf wenn der BSS nicht neu gestartet wird
Behebung
Starten Sie nach jedem Update den BSS neu um alle laufenden Sessions zu beenden
55 Jobs sind nicht ausfuumlhrbar
1 Ein Job wird mit dem Status bdquoNicht unterstuumltztldquo angezeigt wenn fuumlr seine Ausfuumlhrung eine houmlhere Version des BSS erforderlich ist
2 Nach dem Klonen der Datenbank von der Produktions- auf die Testumgebung erhalten alle Jobs automatisch den Status bdquoDeaktiviertldquo wenn die bdquoserverIDldquo nicht identisch ist
Beide Statusaumlnderungen sind gewollt Damit soll verhindert werden dass Jobs nach einem Serverneustart oder nach einem Update automatisch starten und dabei Fehler verursachen
Um Jobs mit dem Status bdquoNicht unterstuumltztldquo nutzen und konfigurieren zu koumlnnen ist es erforderlich den BALVI Schnittstellenserver zu aktualisieren
Deaktivierte Jobs koumlnnen Sie aktivieren indem Sie den jeweiligen Job an den aktuellen Server binden und den Haken bei bdquoAktivldquo setzen
Release Notes BALVI Schnittstellenserver Seite 12 von 37
ausgeliefert Ggf ist es fuumlr unterschiedliche Schnittstellen erforderlich die Grant-Rechte zu aktualisieren (Vgl bdquoWann ist die Ausfuumlhrung des Grant-Skripts erforderlichldquo)
22 Kompatibilitaumltsliste Diverse Verfahren setzen eine Mindestversion des BALVI Schnittstellenservers voraus Die Schnittstellen sind jedoch so konzipiert dass eine Aktualisierung auf eine houmlhere Version des Servers ohne Anpassung an den vorhandenen Schnittstellen jederzeit moumlglich ist
Derzeit sind folgende Mindestanforderungen gegeben
1 BALVI mobil XT 170 oder houmlher setzt BSS 265 und BALVI iP 124x voraus
2 BALVI mobil XT 183 oder houmlher setzt BSS 281 und BALVI iP 124x voraus
3 BALVI mobil 2 (DM) setzt BSS 311 und BALVI iP 124x voraus
4 Die Schnittstelle eFI setzt BSS 251 und BALVI iP 122c voraus
5 Die Schnittstelle LIMS setzt BSS 265 voraus
6 Die Schnittstelle TSK (SN) setzt BSS 265 voraus
7 Die Schnittstelle xDomea (SN) setzt BSS 265 und Java 7 voraus
8 Die Schnittstelle XGewerbeanzeigen 11 setzt BSS 281 BALVI iP 124x Java 8 mit der bdquoJava
Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy2ldquo voraus
9 Die Schnittstelle XGewerbeanzeigen 12 (ab Paket 7 Ausbaustufe 3) setzt BSS 302 BALVI iP
124x Java 8 mit der bdquoJava Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policyldquo
voraus
10 Die Schnittstelle RioPP LM (NRW) setzt BSS 303 und die ETL-Konfiguration voraus
11 Die Schnittstellen zu BALVI iP2 (Fachmodule BTS LM ZDA Stand Juni 2017) setzen BSS 32x
voraus
2 httpwwworaclecomtechnetworkjavajavasedownloadsjce8-download-2133166html
Release Notes BALVI Schnittstellenserver Seite 13 von 37
23 Erforderliche Bibliotheken fuumlr Apache Tomcat Dateiname Funktion Quelle ojdbc6jar Oracle 11gR2 Clientpaket Oracle JDBC Client fuumlr Java
16 ersetzt die bisherige Version bdquoojdbc14jarldquo Die alte Library muss auf jeden Fall entfernt werden
httpwwworaclecomtechnetworkdatabaseenterprise-editionjdbc-112010-090769html
encrypted-datasource-110-alljar
Die Library muss auf jeden Fall entfernt werden Wird derzeit nicht weiter gepflegt da kein Interesse an der Funktionalitaumlt bestand
slf4j-api-1511jar slf4j-log4j12-1511jar log4jdbc4-12beta2jar
Entfaumlllt nicht mehr erforderlich Es wird empfohlen diese zu entfernen falls diese im LIB-Verzeichnis vorhanden sein sollten
commons-dbcp-14jar commons-pool-154jar
Entfaumlllt nicht mehr erforderlich Es wird empfohlen diese zu entfernen falls diese im LIB-Verzeichnis vorhanden sein sollten
Erwartet wird stattdessen ab Tomcat7 die mitgelieferte bdquotomcat-jdbcjarldquo
log4j-1217jar (oder houmlher)
Logging-Funktionalitaumlt Apache Log4j httploggingapacheorglog4j12downloadhtml
bcprov-jdk15on-157jar (oder houmlher)
BouncyCastle Security Provider fuumlr SSLAES hellip wird ab Version 27 im Ordner bdquolibldquo des Tomcat erwartet Sollte es aus Sicherheitsgruumlnden erwuumlnscht sein eine aktuellere Version einzusetzen ist dieses idR moumlglich
httpmvnrepositorycomartifactorgbouncycastlebcprov-jdk15on157
24 Datenbank-Installation Der BALVI Schnittstellenserver benoumltigt auszligerhalb des angebundenen BALVI iP keine eigenen Tabellen Die Web-Anwendung kann im einfachsten Fall direkt auf das Schema von BALVI iP zugreifen indem der Benutzer und das Passwort des BALVI iP-Schemas in der Datei bdquocontextxmlldquo eingetragen werden (nicht empfohlen)
Sollte dies aus Sicherheitsgruumlnden nicht erwuumlnscht sein (empfohlen vom BSI und von BALVI) finden Sie im Paket ein GRANT-Skript um Zugriffsrechte vom BALVI iP Schema fuumlr den Webservice-Schema-Benutzer einzurichten
Zwischen dem Schema von BALVI iP und jeder Web-Anwendung ist dann eine Trennung moumlglich um sicherzustellen dass der Datenbank-Benutzer welcher in der Tomcat-Konfiguration fuumlr die Web-Anwendung eingetragen wird geaumlndert oder geloumlscht werden kann ohne dass die Windows-Anwendung BALVI iP davon betroffen ist Zudem vergibt das von BALVI gelieferte Grant-Skript keine Rechte zum Loumlschen von Tabellenstrukturen oder Tabelleninhalten so dass der Webservice nur festgelegte Daten aumlndern oder lesen darf Es wird empfohlen je Web-Anwendung einen eigenen Datenbank-Benutzer zu vergeben wenn Sie ein BALVI iP mit mehreren Webservices verbinden wollen
Die Moumlglichkeiten im Uumlberblick
1) Sie betreiben den Webservice mit einem eigenstaumlndigen Oracle-Benutzer In diesem Fall muss das
Grant-Skript ausgefuumlhrt werden um den Webservice-Benutzer und den BALVI iP-Benutzer
miteinander zu koppeln
2) In der Tomcat-Konfiguration wird der Oracle-Benutzer eingetragen welcher auch der BALVI iP
Schemabesitzer ist und in der bdquobalviip_conninildquo hinterlegt ist (NICHT Empfohlen) Der Webservice
Release Notes BALVI Schnittstellenserver Seite 14 von 37
hat 100 Zugriffsrechte (auch Loumlsch- oder Aumlnderungsrechte am Schema) es wird kein Grant-
Skript benoumltigt
Wenn Sie die Konfiguration 2) waumlhlen moumlchten koumlnnen Sie die folgenden Unterkapitel uumlberspringen und in Kapitel 0 bzw fortsetzen
241 Erstinstallation Datenbank-Benutzer anlegen Wenn Sie den Webservice-Benutzer vom BALVI iP Schema trennen moumlchten muss durch die DB-Administration in der Oracle-Server-Instanz wo auch BALVI iP sein Schema besitzt ein Benutzer (ggf je Web-Anwendung) angelegt werden welcher folgende Rechte benoumltigt
CONNECT
ALTER SESSION
CREATE JOB
CREATE PROCEDURE
CREATE SESSION
CREATE TABLE
CREATE TRIGGER
CREATE TYPE
CREATE VIEW
CREATE SEQUENCE
CREATE SYNONYM
QUERY REWRITE
Der Default-Tablespace ist frei waumlhlbar Der Benutzer braucht das Recht QUOTA UNLIMITED auf den Tablespace von BALVI iP (Default BALVI_IP) Ein Beispiel-Create-Skript bdquooraCreate_WEB_Usersqlldquo liegt der Auslieferung bei
242 Rechte zuweisen Wenn der BALVI iP Schemabesitzer NICHT in der Tomcat-Umgebung eingetragen werden soll muss ein Oracle DBA das beiliegende GRANT-Skript bdquooraGrantIP_to_Websqlldquo ausfuumlhren um dem jeweiligen Webservice (in Tomcat verwendeten Oracle-Benutzer) die minimalen Rechte auf das Schema von BALVI iP zu gewaumlhren
Dieses Skript setzt voraus dass es von einem Oracle Administrator als bdquoUser SYSTEMldquo ausgefuumlhrt wird Lesen Sie die im Skript enthaltenen README-Kommentare und passen Sie die Benutzer (BALVI iP Schema) und (WEB-Schema) an
====================================================
DEKLARATIVER TEIL MUSS vom KUNDEN geaumlndert
bzw auf die korrekten SCHEMA-Namen angepasst
werden
Die USER-Namen muumlssen in Groszligbuchstaben
geschrieben sein sonst werden sie nicht
gefunden
====================================================
sUserBALVI_IP = BALVI_IP_SCHEMABESITZER
sUserBALVI_WEB = BALVI_WEB_SCHEMABESITZER
Release Notes BALVI Schnittstellenserver Seite 15 von 37
Neu ab Grant-Skript 158 ist die Umbenennung der Verfahrenszuordnung
Pruumlfen Sie dass die Einstellung fuumlr Ihr BundeslandVerfahren korrekt ist dort muss eine 1 fuumlr min ein Verfahren gesetzt sein Diese Einstellung befindet sich direkt unter den Schemabesitzer-Angaben
-- Verfahrensbezogene Konfiguration
-- Setzen Sie fuumlr das jeweilige Verfahren eine 1
-- BALVI Schnittstellenserver (BSS)
-- bis V266 auch BALVI Kommunikationsserver (BKS) genannt
-- generell fuumlr die meisten Verfahren guumlltig
-- Ab Version 57 entfaumlllt mit der Einfuumlhrung der
-- Schnittstelle XGewerbeanzeigen auch der separate Schalter
-- WS_BTR beide Verfahren wurden vereinheitlicht
WS_BSS = 1
Fuumlhren Sie das Skript nach der Anpassung als User SYSTEM aus um die Grants durchzufuumlhren Dieses wurde mit dem von ORACLE gelieferten Programm SQLPLUS (Command-Line) SQLPLUS Worksheet (GUI) und Oracle SQL-Developer getestet
Das Skript generiert fuumlr jedes Objekt ein SYNONYM fuumlr den WEB-USER so dass dieser auf die Objekte ohne Angabe des Owners des IP-Schemas zugreifen kann Pruumlfen Sie nach der Ausfuumlhrung dass die SYNONYMS vorhanden und VALID sind dieses kann ggf nicht der Fall sein Das Skript kann jederzeit erneut ausgefuumlhrt werden um die Grants neu zu erzeugen und bietet ebenfalls die Option alle Grants und Synonyme wieder zu entfernen Detaillierte Informationen zur Nutzung des Skripts sind als Kommentar-Block im Skript enthalten
Hinweis Die Versionsinformation ist unter den Kommentaren direkt im Skript zu finden
Zugriffsberechtigungen fuumlr Webanwendungen auf BALVI iP anlegen
===============================================================
Version 158
Guumlltig fuumlr BALVI iP 123 oder houmlher
Autor Frank Holler
SVN Revisionsinformationen
$Revision 479 $
$Date 2016-02-15 152755 +0100 (Mo 15 Feb 2016) $
================================================================
243 Wann ist die Ausfuumlhrung des Grant-Skripts erforderlich Durch das Strukturupdate von BALVI iP (z B 1240 auf 1241) werden veraltete Strukturen geloumlscht und ggf neue Views oder Tabellen angelegt Die Grant-Rechte geht dabei ggf verloren Daher ist die Ausfuumlhrung des Grant-Skripts immer dann erforderlich wenn sich die Datenbank-Struktur von BALVI iP veraumlndert
Zudem kann es fachliche Neuerungen geben welche im alten Grant-Skript nicht vorhanden sind Daher muss das Skript ggf auch ausgefuumlhrt werden wenn eine neue Schnittstelle im Schnittstellenserver bereitgestellt wurde Dieses betrifft z B auch die Bereitstellung von neuen Versionen von BALVI mobil XT
Release Notes BALVI Schnittstellenserver Seite 16 von 37
da auch dort mit einem fachlich erweiterten Client die Moumlglichkeit besteht dass neue Schnittstellen bereitgestellt und somit mehr Schreibrechte auf Tabellen benoumltigt werden
244 Welche Version des Grant-Skripts soll ich nehmen Wie der Schnittstellenserver sind auch die Grant-Skripte versioniert Neuere Versionen des Grant-Skriptes sind abwaumlrts-kompatibel und koumlnnen immer verwendet werden auch wenn in einer Schnittstellenbeschreibung eine aumlltere Version des Grant-Skriptes explizit benannt wurde
245 Kombination von mehreren Verfahren Wenn Sie zwei oder mehr Schnittstellen im BSS verwenden moumlchten ist es ggf erforderlich auch mehrere Verfahren auf aktiv (bdquo1ldquo) zu setzen
Im Beispiel nehmen wir an Sie moumlchten bdquoeFildquo und bdquoBALVI mobil XTldquo im Schnittstellenserver bereitstellen In der Beschreibung von bdquoeFildquo steht dass das Grant-Skript V36 erforderlich ist BALVI mobil XT 18 erfordert jedoch schon V56
Wenn Sie beide Verfahren betreiben ist im Grant-Skript (V56 oder houmlher) die Einstellung fuumlr beide Verfahren zu aktivieren
====================================================
DEKLARATIVER TEIL MUSS vom KUNDEN geaumlndert
bzw auf die korrekten SCHEMA-Namen angepasst
werden
Die USER-Namen muumlssen in Groszligbuchstaben
geschrieben sein sonst werden sie nicht
gefunden
====================================================
sUserBALVI_IP = BALVI_IP_SCHEMA
sUserBALVI_WEB = WEBAPP_SCHEMA
-- Verfahrensbezogene Konfiguration
-- Setzen Sie fuumlr das jeweilige Verfahren eine 1
-- BALVI Schnittstellenserver (BSS)
-- bis V266 auch BALVI Kommunikationsserver (BKS) genannt
-- generell fuumlr die meisten Verfahren guumlltig
-- Ab Version 57 entfaumlllt mit der Einfuumlhrung der
-- Schnittstelle XGewerbeanzeigen auch der separate Schalter
-- WS_BTR beide Verfahren wurden vereinheitlicht
WS_BSS = 1
-- WebService BTR (Betriebsstaumlttenregister) (NRW TH)
-- entfernt mit Update V57 setzen Sie stattdessen bei WS_BSS = 1
--WS_BTR = 0
-- Probenahme Futtermittel im Browser(BY)
WS_PROBE_FM = 0
-- Risikoorientierte Probenplanung Futtermittel ndash RIOPP FM (BY)
WS_RIOPP_FM = 0
-- Verfahren Export an EFi (Status Pilotbetrieb)
WS_EFI = 1
-- neu ab Version 35 des Grant-Skriptes ist die Moumlglichkeit den Webuser
Release Notes BALVI Schnittstellenserver Seite 17 von 37
-- fuumlr das Loumlschen der Ausgangskoumlrbe explizit zu berechtigen bzw sogar einen
-- expliziten abweichenden User festzulegen Die Konfiguration in der
-- Job-Oberflaumlche sieht vor dass man die Oracle-Datenbank-Zugangsdaten fuumlr
-- das Loumlschen einstellen muss Hier muss im Normalfall derselbe Oracle
-- Datenbankbenutzer eingetragen werden wie in der Tomcat-Verbindungs-
-- konfiguration In diesem Fall sollte wenn WS_EFI = 1 eingestellt wurde
-- ebenfalls WS_EFI_DELETE = 1 eingestellt werden
-- Alternativen
-- 1) Datenbankbenutzer aumlndern
-- Wenn bei sUserEFI_TRUNC anstatt sUserBALVI_WEB (Standard) ein anderer
-- Oracle-Benutzername angegeben wird wird das Loumlschrecht fuumlr die EFi
-- Ausgangskoumlrbe Datenbankseitig exklusiv dem angegeben Datenbankbenutzer
-- zugewiesen
-- 2) Loumlschrecht verweigern
-- Setzen Sie die Variablen WS_EFI_DELETE = 0 damit kein Loumlschrecht
-- zugeweisen wird
WS_EFI_DELETE = 0
-- Beispiel Anderer Benutzer muss in der Datenbank existieren
-- Entfernen Sie die fuumlhrenden -- vor der Variable sUserEFI_TRUNC und
-- setzen den entsprechenden Oracle-Benutzer ein
--sUserEFI_TRUNC = TEST_EFI_TRUNC
hellip
25 Konfiguration des Schnittstellen-Servers
251 Die bdquocontextxmlldquo-Parameter Die von der Servlet-Spezifikation vorgegeben Rump-Struktur sieht folgendermaszligen aus
ltxml version=10 encoding=utf-8gt
ltDOCTYPE Contextgt
ltContextgt
lt-- Kundenspezifische Einstellungen --gt
ltContextgt
Anwendungsspezifische Einstellungen werden zwischen ltContextgt und ltContextgt eingefuumlgt Alle allgemeinguumlltigen Einstellungen in der Datei bdquocontextxmlldquo werden hier erlaumlutert Kommentare finden sich auch in der von BALVI ausgelieferten Beispiel-Konfiguration
Neben den im Folgenden beschriebenen Standard-Einstellungen kann es auch vorkommen dass bundeslandspezifische Erweiterungen vorhanden sind welche nicht in dieser Dokumentation aufgefuumlhrt werden Diese funktionieren trotzdem regulaumlr weiter wenn keine expliziten Informationen zu Kompatibilitaumltsproblemen in den Release-Notes aufgefuumlhrt wurden
2511 Datenbankverbindung jdbcDataSource
Die Datenbankverbindung wird uumlber die von DBCP und dem Oracle-Treiber vorgegebenen Moumlglichkeiten realisiert Der Einsatz der orgapachetomcatjdbcpoolDataSourceFactory (automatisch verfuumlgbar ab Apache Tomcat 7 in der mitgelieferten tomcat-dbcpjar) wird als Beispiel-Konfiguration ausgeliefert
ltResource
name=jdbcDataSource
auth=Container
Release Notes BALVI Schnittstellenserver Seite 18 von 37
type=javaxsqlDataSource
factory=orgapachetomcatjdbcpoolDataSourceFactory
maxActive=10 initialSize=3
maxIdle=5
maxWait=10000
url=jdbcoraclethinBL2-ORA10-KUNDENBALVIINTERN1521ORCL
driverClassName=oraclejdbcdriverOracleDriver
username=balvi_webservice_schema
password=balvi_webservice_password
description=Oracle Datasource
maxOpenPreparedStatements=50
removeAbandoned=false
removeAbandonedTimeout=100
logAbandoned=true
jdbcInterceptors=hellip
gt
Hinweise zur Einstellung der jdbcDataSource
Standard-Einstellungen fuumlr den Datenbank-Verbindungspool
Der Verbindungspool muss entsprechend der Anzahl der zu erwartenden gleichzeitigen Benutzer konfiguriert werden Wenn Sie erwarten dass 50 Anwender gleichzeitig arbeiten stellen Sie bitte folgende Werte ein
maxActive=(50 + 10 (fuumlr System und Jobs)) = 60
maxIdle= (50 10) = 5
1 maxActive - maximale Anzahl der gleichzeitigen aktiven Anfragen an die DB
Wenn der Werte maxActive erreicht ist z B wenn mehrere Benutzer gleichzeitig einen Export starten moumlchten welcher laumlngere Zeit in Anspruch nimmt dann kann der Server die Anfrage nicht mehr bedienen und der Anwender wird abgewiesen maxActive hat zudem Auswirkungen auf die im Hintergrund ausgefuumlhrten Jobs maxActive wird daher kalkuliert mit der Anzahl der Anwender und moumlglicher Datenbank-Connections fuumlr Hintergrund-Jobs Jeder aktiv ausgefuumlhrte Job benoumltigt mindestens eine Connection nur selten wird aus Performance-Gruumlnden mehr als eine Connection waumlhrend der Job-Ausfuumlhrung verwendet Im Normalfall sollten daher 10 Connections fuumlr Hintergrundprozesse ausreichend sein
2 maxIdle - Anzahl der offenen Verbindungen auch wenn der Server im Leerlauf ist
Jede offene Verbindung im Leerlauf haumllt auf dem Datenbankserver eine Session offen Auch diese erfordert Ressourcen Wenn die Verbindungen jedoch geschlossen werden kann die Anfragezeit fuumlr eine neue Verbindung steigen da diese Verbindung erst neu ausgehandelt werden muss Die Empfehlung fuumlr den Wert bdquomaxIdleldquo ist ca 10 der Einstellung von maxActive
KeepAlive-Einstellungen fuumlr den Pool
1 validationQuery
Diese wird ausgefuumlhrt um die Verbindung zu DB zu validieren Es MUSS ein Datensatz zuruumlckgegeben werden ansonsten nimmt der DBCP an dass die Abfrage nicht erfolgreich abgesetzt wurde Achten Sie also bitte darauf dass die Abfrage nicht zu leitungsintensiv ist und genau einen Datensatz liefert
Release Notes BALVI Schnittstellenserver Seite 19 von 37
Oracle bietet dafuumlr die virtuelle Tabelle DUAL an welche sich fuumlr die ValidationQuery sehr gut eignet da die Abfrage kaum Ressourcen verbraucht
validationQuery=select 1 from dual
2 testOnBorrow - Boolscher Wert true oder false
Diese Einstellung sorgt dafuumlr dass der Pool die Verfuumlgbarkeit anhand der validationQuery pruumlft bevor
die DB-Verbindung an die Anwendung ausgeliehen wird Empfehlung
testOnBorrow=true
3 testWhileIdle - Boolscher Wert true oder false
Diese Einstellung ist hilfreich wenn zwischen dem Tomcat und der DB eine Firewall mit Stateful
Packet Inspection verwendet wird Nach laumlngerer Inaktivitaumlt wird normalerweise durch die Firewall die
DB-Verbindung geschlossen Dieses loumlst dann beim Ausleihen der Verbindung eine Fehlermeldung im
Protokoll aus 2012-08-16 165418720 WARN [http-0000-8080-8]
[orgspringframeworkjdbcsupportSQLErrorCodesFactory] Error while extracting
database product name - falling back to empty error codes
orgspringframeworkjdbcsupportMetaDataAccessException Error while extracting
DatabaseMetaData nested exception is javasqlSQLRecoverableException Getrennte
Verbindung Um dieses Problem zu beheben sollte die Option testWhileIdle=true eingestellt werden
testWhileIdle=true
Damit diese weiszlig wie oft eine Pruumlfung durchgefuumlhrt werden muss sind jedoch noch zusaumltzliche Angaben erforderlich welche fuumlr die Einstellung der Zeit zusaumltzlich gesetzt werden muumlssen
a) minEvictableIdleTimeMillis - Long in Millisekunden
Min Zeit wie lange eine DB-Verbindung im Leerlauf ist bevor diese zur Pruumlfung
gekennzeichnet wird Dieses haumlngt stark von der Einstellung der Firewall ab Wenn Sie eine
sehr restriktive Firewall haben kann es sein dass diese die Verbindung nach wenigen
Minuten Leerlauf trennt Stellen Sie den Wert immer so ein dass dieser unter der Leerlaufzeit
der Firewall liegt empfohlen 300000 entspricht 300 Sek = 5 min
minEvictableIdleTimeMillis=300000
b) timeBetweenEvictionRunsMillis - Long in Millisekunden
Der Pruumlflauf startet in der Default-Konfiguration alle 1800000 Millisekunden = 30 Min n als
zu Pruumlfen markierte Verbindungen werden in einem Pruumlflauf getestet n wird bestimmt durch
die Einstellung numTestsPerEvictionRun Empfehlung Stellen Sie den Wert auf alle 15 Min
ein
timeBetweenEvictionRunsMillis=900000
Release Notes BALVI Schnittstellenserver Seite 20 von 37
c) numTestsPerEvictionRun - Integer
Wie viele Verbindungen sollen getestet werden waumlhrend der Pruumlflauf ausgefuumlhrt wird Im
Normalfall sollte die Anzahl der zu testenden Verbindungen nicht zu hoch eingestellt werden
Der Default ist 3 Wenn Sie houmlhere Sicherheit haben wollen dass keine bdquototenldquo
Datenbankverbindungen bestehen bleiben erhoumlhen Sie den Wert auf max bdquo(maxActive ndash
maxIdle) 2ldquo Wenn Ihnen 3 ausreichend erscheint muss der Wert nicht gesetzt sein dann
wird der Default verwendet
Beispiel numTestsPerEvictionRun=10
4 Interceptors konfigurieren Neu ergaumlnzt wurde die Moumlglichkeit spezielle bdquoInterceptorsldquo zu konfigurieren die ermoumlglichen das Verhalten des Pools zu steuern Wichtig hierbei ist dass die Angabe von Werten auf real existierende Java-Klassen erfolgt die im Classpath des Tomcat vorhanden sind Groszlig-und-Kleinschreibung ist zu beachten Folgende Default-Einstellung hat BALVI fuumlr den BSS festgelegt jdbcInterceptors=
orgapachetomcatjdbcpoolinterceptorConnectionState
orgapachetomcatjdbcpoolinterceptorStatementFinalizer
orgapachetomcatjdbcpoolinterceptorResetAbandonedTimer
Details zu den verwendeten Interceptor-Einstellungen finden Sie in der Tomcat-Dokumentation3
3 httptomcatapacheorgtomcat-80-docjdbc-poolhtmlJDBC_interceptors
Release Notes BALVI Schnittstellenserver Seite 21 von 37
2512 Datenbank-Zugangsdaten verschluumlsseln
Die Verschluumlsselung fuumlr die Datenbank-Verbindung (bdquoEncrypted Datasourceldquo) ist eine Ableitung der Bibliothek Apache-Common-DBCP-14 und daher nicht mehr mit Java 8 kompatibel Die Einrichtung der Verschluumlsselung wird daher mit der Auslieferung des BSS 30 nicht mehr angeboten
2513 Active-Directory-Authentifizierung
Uumlber die folgenden Parameter wird der Zugriff des Schnittstellen-Servers auf einen Microsoft Active Directory Domain-Controller konfiguriert
ldquoldapServerAddressrdquo
Syntax PROTOKOLLIP-Adresse oder DNS-NamePORT
ltEnvironment
name=ldapServerAddress
value=ldapbl2-dc02balviintern389
type=javalangString
override=true
gt
Als Protokoll besteht auch die Moumlglichkeit ldaps (LDAP+SSL) wenn der Domain-Controller entsprechend konfiguriert wurde Im Java Truststore muss dann das Zertifikat der CA vorhanden sein welche das Zertifikat des Domain-Controllers signiert hat Zudem darf bei ldaps keine IP-Adresse verwendet werden es muss der DNS-Name des Server-Zertifikats eingetragen sein Ansonsten gibt es beim Verbinden eine Sicherheits-Exception
lt-- SSL-Beispiel
ltEnvironment
name=ldapServerAddress
value=ldapsbl2-dc02balviintern636
type=javalangString
override=true
gt
--gt
bdquoldapBaseDnrdquo
LDAP-Suchpfad fuumlr die Domain-Basis Diese muss der LDAP-Syntax fuumlr den Domain-Suffix entsprechen
Syntax DC=SERVERDC=ROOTDN
ltEnvironment
name=ldapBaseDn
value=DC=BALVIDC=INTERN
type=javalangString
override=true
gt
Release Notes BALVI Schnittstellenserver Seite 22 von 37
bdquowebLoginUseActiveDirectoryAuthenticationrdquo
Die Authentifizierung in der Browser-Oberflaumlche kann uumlber die Active-Directory-Authentifizierung erfolgen In der ersten Version ist nur die Protokoll-Auswertung moumlglich wenn der ADMIN sich anmeldet Dieser hat normalerweise niemals AD-Kennungen zugeordnet BALVI empfiehlt diese Einstellung auf bdquofalseldquo zu belassen Webservices welche uumlber SOAPREST zugreifen koumlnnen die Active-Directory-Authentifizierung trotzdem verwenden
ltEnvironment
name=webLoginUseActiveDirectoryAuthentication
value=false
type=javalangBoolean
override=true
gt
ldquoldapDaysBeforeExpirationNotificationrdquo
Die Passwort-Aumlnderung im Active-Directory uumlber die Browser-Oberflaumlche ist in der ersten Version noch nicht implementiert der Parameter wird bislang nicht ausgewertet
ltEnvironment
name=ldapDaysBeforeExpirationNotification
value=14
type=javalangInteger
override=true
gt
2514 Statement-Protokollierung in BALVI iP
Diese Option aktiviert die Lese- und Aumlnderungsprotokollierung fuumlr BALVI iP Standard ist bdquofalseldquo und wird fuumlr alle Kunden empfohlen solange keine speziellen Datenbank-Jobs eingerichtet wurden welche zeitgesteuert die Protokolleintraumlge wieder loumlschen Fuumlr Bayern wurde ein spezielles Konzept zur Leseprotokollierung entworfen Wenn Sie mehr daruumlber erfahren moumlchten kontaktieren Sie bitte die BALVI GmbH
ltEnvironment
name=enableSqlStatementMonitoring
value=true
type=javalangBoolean
override=true
gt
Beachten Sie dass diese Option massive INSERT-Statements in BALVI iP in die Tabelle VIS_D92 ausfuumlhrt Jedes abgesetzte SQL-Statement wird dabei vollstaumlndig protokolliert Dieses erzeugt eine sehr hohe INSERT-Last und in der Folge auch erhoumlhte Redolog-Switches und COMMIT-Transaktionen
Optional Aktivieren der INSERT + APPEND - Logik
Beachten Sie bitte die Hinweise von Oracle zum Hint + APPEND
Release Notes BALVI Schnittstellenserver Seite 23 von 37
Wenn Sie dieses Verhalten aktivieren moumlchten ergaumlnzen Sie bitte den folgenden Environment-Parameter
ltEnvironment
name=statementMonitoringactivateAppendMode
value=true
type=javalangBoolean
override=true
gt
2515 Einstellungen fuumlr BALVI mobil XT (bzw den bdquopartitionedExportldquo)
Diese Logik des FIFO-Buffers wurde so konzipiert dass dem Rechenzentrum diverse Einstellmoumlglichkeiten uumlber die Datei bdquocontextxmlldquo zur Verfuumlgung stehen um die Steuerung des FIFO-Puffers zu beeinflussen
Schematische Darstellung des FIFO-Puffers
Das ermoumlglicht es z B dem BALVI mobil XT Client (14 oder houmlher) den aktiven Block abzuholen und dies beim Fehler bis zu 10-mal zu wiederholen Sobald der Block [001] erfolgreich beim Client angekommen ist und dieser den naumlchsten Block anfragt wird der Block [001] verworfen wird Der Server fuumlllt dann im Hintergrund den frei gewordenen Block wieder waumlhrend der Client den Block [002] abholt
Die Groumlszlige und Anzahl der vorgecachten Bloumlcke kann uumlber die folgenden Einstellungen in der Datei bdquocontextxmlldquo definiert werden
ltEnvironment
name=partitionedExportmaxBufferedPartitions
value=3 type=javalangInteger override=true
gt
ltEnvironment
name=partitionedExportpartitionSize
value=256000 type=javalangInteger override=true
gt
Die Einstellung partitionedExportmaxBufferedPartitions ist dabei die Anzahl der vorgecachten Bloumlcke mindestens muss 2 angegeben werden Der Puffercache wird ausschlieszliglich im RAM der JVM aufgebaut es wird folglich mehr Arbeitsspeicher verwendet Dieser Arbeitsspeicher muss je gleichzeitiger Session auf dem Server bereitgestellt werden die Default-Einstellung mit 3 Partitionen a 256 KB + dem aktiven Puffer erfordern 1 MB RAM je aktiven Anwender
Aktiv
er
Puffe
r
[001] Vorg
ecac
hter
Bl
ock
[002] Vorg
ecac
hter
Bl
ock
[003]
Aktiv
er P
uffe
r
[002] Vorg
ecac
hter
Bl
ock
[003] Vorg
ecac
hter
Bl
ock
[leer]
Release Notes BALVI Schnittstellenserver Seite 24 von 37
Gleichzeitig wurde die Moumlglichkeit geschaffen dass die maximale Anzahl an gleichzeitigen Exporten durch das Rechenzentrum eingeschraumlnkt werden kann um einem OutOfMemory-Fehler vorzubeugen Die Einstellung
ltEnvironment
name=partitionedExportmaxConcurrentExports
value=10 type=javalangInteger override=true
gt
muss entsprechend der zu erwartenden gleichzeitigen Zugriffe konzipiert werden ansonsten wird der Server einen Verbindungsversuch durch die Clients ablehnen
Beachten Sie dass die folgenden Einstellungen partitionedExportmaxBufferedPartitions partitionedExportmaxConcurrentExports und partitionedExportpartitionSize gemeinsam als Rechenbasis fuumlr den RAM-Bedarf des Webservers herangezogen werden muumlssen
Folgende Faustformel sollte fuumlr die Einrichtung verwendet werden
Min 256 MB (Serverbasis) + (11 partitionedExportmaxConcurrentExports partitionedExportmaxBufferedPartitions partitionedExportpartitionSize)
Beispiel 50 gleichzeitige Anwender Blockgroumlszlige 256 KB 4 Partitionen
256 MB + (11 50 256 4) KB = 312 MB fuumlr die JVM
Empf 512 MB (Serverbasis) + (12 partitionedExportmaxConcurrentExports partitionedExportmaxBufferedPartitions partitionedExportpartitionSize)
Beispiel 50 gleichzeitige Anwender Blockgroumlszlige 256 KB 4 Partitionen
512 MB + (12 50 256 4) KB = 572 MB fuumlr die JVM
partitionedExportmaxConcurrentExports
Bestimmt die Anzahl der maximalen Export Tasks (Threads) die fuumlr partitionierte Exporte bereitgestellt werden Wenn die Anzahl uumlberschritten wird wird die entsprechende Exportanfrage abgewiesen und der Client muss zu einem spaumlteren Zeitpunkt erneut anfragen Stellen Sie diesen Wert entsprechend der zu erwartenden Benutzeranzahl ein bei 50 Anwendern also 50
Exporte oumlffnen auf der Datenbank entsprechend zur Ausfuumlhrungszeit min einen Cursor ggf fuumlr rekursive Unterabfragen kurzfristig sogar mehr Die hier eingestellte Anzahl muss mit der Anzahl von maxActive korrelieren
ltEnvironment
name=partitionedExportmaxConcurrentExports
value=10 type=javalangInteger override=true
gt
partitionedExportmaxBufferedPartitions
Bestimmt die Anzahl der Datenbloumlcke (Partitionen) die vom Server bei Abruf eines Exportes gepuffert werden Die seit Version 24 eingefuumlhrte FIFO-Puffer-Logik ermoumlglicht dass der Server schon die Ergebnisse vorpuffert so dass der Client weniger Wartezeiten bei der Anfrage nach Daten hat Diese
Release Notes BALVI Schnittstellenserver Seite 25 von 37
Puffer-Logik unterteilt den Exportdatenstrom (je Export) in mehre Bloumlcke Der Client kann nun den letzten Block neu anfordern oder den naumlchsten Block wenn der letzte Block erfolgreich verarbeitet wurde Wie viele naumlchste Bloumlcke durch den Server bereit gestellt werden entscheidet diese Einstellung Sobald kein naumlchster Block mehr bereit gestellt werden muss wird der Datenbank-Cursor geschlossen eine Erhoumlhung kann also zu einer Entlastung der aktiven DB-Verbindungen fuumlhren erhoumlht jedoch den Bedarf an RAM des Servers
Der von BALVI voreingestellte Wert ist 3
ltEnvironment
name=partitionedExportmaxBufferedPartitions
value=3 type=javalangInteger override=true
gt
partitionedExportpartitionSizeldquo
Die Groumlszlige der Datenbloumlcke (Partitionen) die an den Client uumlbermittelt werden in Bytes Wenn Sie diesen Wert zu niedrig einstellen reduziert sich die Effizienz des Caches da der Client mehr Datenbloumlcke hintereinander abrufen muss Waumlhlen Sie einen zu groszligen Wert wird die neu zu uumlbertragende Datenmenge im Fall eines Fehlers houmlher
Der von BALVI voreingestellte Wert ist 256000 (256 KB)
ltEnvironment
name=partitionedExportpartitionSize
value=256000 type=javalangInteger override=true
gt
exportTokensmaxTokenCount
Maximale Anzahl der gleichzeitig vergebenen Token die vom Server gecached werden Jede Sitzung welche einen Export durchfuumlhrt erhaumllt einen Session-Token
Wenn eine Sitzung laumlngere Zeit nicht verwendet wurde wird dieser Session-Token wieder entfernt Wenn Sie den Wert zu niedrig einstellen fuumlhrt das zu einer generellen Session-Begrenzung auch fuumlr den nicht partitionierten Export-Modus welcher ab Version 21 verfuumlgbar ist
Ist die Anzahl der Tokens houmlher als die Datenbankeinstellung maxActive kann es vorkommen dass zwar eine Session gestartet werden kann jedoch kein Datenexport zustande kommt
Der von BALVI voreingestellte Wert ist 2000
ltEnvironment
name=exportTokensmaxTokenCount
value=20 type=javalangInteger override=true
gt
exportTokenstokenExpirationInSeconds
Zeit in Sekunden die verstreichen muss bis ein Token unguumlltig wird falls darauf kein Zugriff mehr erfolgt Nach einem erfolgreichen Export wird der Token automatisch geschlossen diese Option ist fuumlr den Abbruchfall vorgesehen Der von BALVI voreingestellte Wert ist 180 (180 s = 3 min)
Release Notes BALVI Schnittstellenserver Seite 26 von 37
ltEnvironment
name=exportTokenstokenExpirationInSeconds
value=180 type=javalangInteger override=true
gt
exportTokenstokenDisposalInSeconds
Zeit in Sekunden die verstreichen muss bis ein Token das erfolgreich abgearbeitet wurde aus dem Cache geloumlscht wird Um sicher zu stellen dass der letzte Exportblock noch erfolgreich abgerufen werden kann bleibt der Token auch nach Fertigmeldung des Clients noch N Sek guumlltig
Der von BALVI voreingestellte Wert ist 60 (60 s = 1 min)
ltEnvironment
name=exportTokenstokenDisposalInSeconds
value=60 type=javalangInteger override=true
gt
2516 Job-Verwaltung fuumlr den BSS konfigurieren Aktivierung der Jobverwaltung
Bis zur Version 28 des BSS gab es den Parameter bdquoavailableServicesldquo Dieser konnte bei Bedarf aktiviert werden wenn die Jobs benoumltigt wurden
Mit Version 30 ist die Einstellung bdquoavailableServicesldquo zu entfernen und kann durch den neuen optionalen Parameter bdquoisJobServiceEnabledldquo in der Datei bdquocontextxmlldquo ersetzt werden
lt-- Neue Parameter zur Aktivierung des Job Service Ersatz fuumlr availableServices --gt
ltEnvironment
name=isJobServiceEnabled
value=true
type=javalangBoolean
override=true
gt
Ab BSS 30 wird die Jobs-Engine standardmaumlszligig aktiviert Sollte die Jobs-Engine nicht benoumltigt werden muss bdquovalueldquo der Wert bdquofalseldquo zugewiesen werden Wird bdquoisJobServiceEnabledldquo nicht eingefuumlgt sind die Jobs trotzdem standardmaumlszligig aktiv
Nach dem Neustart des Servers und erneutem Einloggen erscheint nun zusaumltzlich der Menuumlpunkt bdquoJobsldquo
bdquopasswordKeyldquo fuumlr Jobs
In der Job-Logik wird ein von BALVI definierter Standard-Schluumlssel fuumlr die Ablagen von schuumltzenswerten Daten z B Passwoumlrtern verwendet Diese Einstellung ermoumlglicht den BALVI-Standard zu uumlberschreiben Wenn Sie diese Einstellung aumlndern muumlssen jedoch alle bislang verschluumlsselten Job-Parameter neu verschluumlsselt werden
ltEnvironment
name=javacompenvjobspasswordKey
value=MeinHochsicheresNeuesPasswort
type=javalangString
Release Notes BALVI Schnittstellenserver Seite 27 von 37
override=true
gt
bdquoJob ID enableddisabledldquo (Deprecated ersetzt ab 28 durch das bdquoBindenldquo von Jobs)
Sondereinstellungen fuumlr die Job-Verwaltung Da alle Jobs in einer Datenbank administriert werden jedoch ggf verteilt auf mehreren Tomcat-Servern ausgefuumlhrt werden sollen besteht hier die Option Jobs fuumlr die aktuelle Tomcat-Instanz separat zu deaktivieren
Die Einstellung ID koumlnnte z B folgendermaszligen aussehen javacompenvjobsC0DB58D8D52C4BBC966D1DC788A4EF8Benabled
Fuumlr weitere Fragen zu dieser Einstellung kontaktieren Sie bitte die BALVI GmbH
ltEnvironment
name=javacompenvjobsIDenabled
value=false
type=javalangBoolean
override=true
gt
2517 Weitere optionale Parameter
Es ist fuumlr diverse einzelne Schnittstellen ggf erforderlich Einstellungen in der Datei bdquocontextxmlldquo zu ergaumlnzen Hinweise zu diesen Parametern sind dann in dem der Schnittstelle beiliegenden Dokument enthalten Das gilt z B fuumlr die Schnittstelle bdquoXGewerbeanzeigenldquo
26 Logging mit logback Das Logging wurde komplett uumlberarbeitet Statt bdquoLog4Jldquo wird jetzt bdquologbackldquo4 benutzt Ab BSS 30 ist es zwingend notwendig die Einstellung vorzunehmen um das Logging der Anwendung zu steuern
Migration Ergaumlnzen Sie die neue Einstellung bdquologgingconfigldquo
lt-- Neue Paramter zur Angabe der Logback Config Ersatz fuumlr log4jConfigLocation --gt
ltEnvironment
name=loggingconfig
value=$catalinabaseconflogback-bssxml
type=javalangString
override=true
gt
Nach wie vor steht es Ihnen frei die Logging-Konfiguration eigenstaumlndig anzupassen
Wenn Sie jedoch dieselbe WAR in einer Tomcat-Instanz unter mehreren Context-Namen betreiben wuumlrden beide dieselbe Logging-Konfiguration verwenden so dass alle Protokolleintraumlge in einer Log-Datei aus
4 httplogbackqoschmanualappendershtml
Release Notes BALVI Schnittstellenserver Seite 28 von 37
mehreren Webanwendungen generiert werden Aumlndern Sie den Namen der Logging-Konfiguration entsprechend ab um fuumlr jede Anwendung eine spezifische Logging-Einstellung vornehmen zu koumlnnen
27 Tocmat Optional Suche im bdquoKlassenpfadldquo um den
Ordner bdquoconfldquo erweitern Die Suche nach Dateien uumlber bdquoclasspathldquo setzt voraus dass die Ordner- und Dateinamen im Apache Tomcat bekannt gegeben werden Der Klassenpfad kann in der Datei bdquocatalinapropertiesldquo angepasst werden Wenn Sie dort unter commonloader die folgenden Werte ergaumlnzen kann eine Datei auch im Ordner conf abgelegt werden damit Apache Tomcat diese findet Ansonsten muss die Datei im Ordner lib abgelegt werden
commonloader=$catalinabaseconf$catalinahomeconf
3 Die neue Browser-Oberflaumlche Der BALVI Schnittstellenserver hat seit Version 25 neben der Protokollierung auch die Moumlglichkeit Job-Konfigurationen zu pflegen Der Login ist nur fuumlr einen in BALVI iP eingetragenen ADMIN (z B Benutzer bdquoSYSTEMADMINldquo) mit dem in BALVI iP hinterlegten Passwort moumlglich Zur Anmeldung muss immer [SYSTEMBenutzername] im Feld Benutzer angegeben werden ansonsten schlaumlgt die Anmeldung fehl Bitte achten Sie darauf dass der bdquoldquo (Slash) und nicht der bdquoldquo (Backslash) verwendet werden muss
31 Server-Protokoll Um das Server-Protokoll anzuzeigen waumlhlen Sie den entsprechenden Menuumlpunkt Dort haben Sie seit BSS 26 die Moumlglichkeit uumlber alle Spalten der Protokolle nach Informationen zu suchen
Seit BSS 31 gibt es die Moumlglichkeit Verfahren in bdquoKopfsaumltzeldquo und bdquoDetailsaumltzeldquo zu unterteilen Wurde das Verfahren entsprechend konfiguriert (wie z B bei der Schnittstelle bdquoXGewerbeanzeigenldquo) dann wird im Protokoll-Kopfsatz nur der Start und das Ende der Ausfuumlhrung in der Liste angezeigt Erst bei einem Klick auf bdquoInformationenldquo wird die Liste aller Detailsaumltze angezeigt die im Durchlauf erzeugt wurden
Release Notes BALVI Schnittstellenserver Seite 29 von 37
Verfahren
Die Liste der verfuumlgbaren Verfahren die bei Ihnen im System installiert sind ZB
BEFUNDEhellip Schnittstelle Befunde LM FM oder TS
PROBEhellip Schnittstelle zum Export von Proben an Labore ebenfalls Spezifisch fuumlr einzelne Fachbereiche
MOBILXT Protokolle der BALVI Mobil XT Synchronisation
WEB Allgemeine nicht spezifizierte Protokolle hierunter ist bislang auch die eFi-Protokollierung zu finden
WEB_I0802 Protokolle zur Schnittstelle BALVI iP LIMS (Lebensmittelproben)
XGEWERBE Schnittstelle XGewerbeanzeigen
Klicken Sie auf die Schaltflaumlche so besteht bei den neuen Protokolldatensaumltzen die Moumlglichkeit Detail-Informationen zum Protokollsatz zu erhalten
Release Notes BALVI Schnittstellenserver Seite 30 von 37
Seit BSS 30x ist die Anzeige der Protokolle ebenfalls farblich abgesetzt so dass Protokolleintraumlge mit Fehlern hellrot und Warnungen hellgelb hinterlegt werden
32 Jobs Mit einem Klick auf den Menuumlpunkt Jobs rufen Sie die Oberflaumlche fuumlr die Job-Konfiguration auf Daraufhin werden alle Jobs aufgelistet die fuumlr den BSS freigegeben sind Hier koumlnnen Sie Einstellungen an den Jobs vornehmen und die Jobs aktivieren bzw deaktivieren Die Beschreibungen bzw Einstellungsmoumlglichkeiten fuumlr den jeweiligen SST-Job sind nicht Bestandteil dieser Dokumentation
33 Log-Ausgaben Uumlber den Menuumlpunkt Log-Ausgaben koumlnnen Sie die Ausgabe der Protokolleintraumlge in Echtzeit beobachten
Release Notes BALVI Schnittstellenserver Seite 31 von 37
Starten Sie die Echtzeit-Protokollierung indem Sie auf die Schaltflaumlche mit dem Symbol bdquoPlayldquo (Dreieck) klicken unterbrechen Sie die Ausgabe indem Sie die auf Schaltflaumlche mit dem Symbol bdquoPauseldquo (zwei Balken) klicken
Klicken Sie auf die Schaltflaumlche bdquoAktualisierenldquo (zwei Pfeile) um die neuesten Protokolleintraumlge angezeigt zu bekommen
Klicken Sie auf das Symbol mit dem Papierkorb um die letzten Protokollmeldungen in der Anzeige zu loumlschen
Die Daten in den Protokolldateien auf der Festplatte des Servers sind davon nicht betroffen
Uumlber das Symbol bdquoLogging anpassenldquo (Schraubenschluumlssel) koumlnnen Sie die Ausgabe der Daten im Echtzeitfenster und in den Protokolldateien aumlndern jedoch ist diese Einstellung nur temporaumlr Die Standardeinstellungen koumlnnen ausschlieszliglich uumlber die Anpassung der Datei bdquologback-bssxmlldquo im Konfigurationsverzeichnis des Servers selbst geaumlndert werden
Release Notes BALVI Schnittstellenserver Seite 32 von 37
In der Logging-Parameter Konfiguration koumlnnen Sie verschiedene Parameter einstellen und uumlber die Schaltflaumlche bdquoAnwendenldquo dann sofort im Echtzeitprotokoll sehen Welche Einstellungen moumlglich sind erfahren Sie wenn es eine akute Fehlersituation gibt die detailliertere Ausgaben im Protokoll erfordert
Warnung Wenn Sie den Log-Level fuumlr ROOT oder eine andere Klasse auf TRACE einstellen werden sehr viele Protokollausgaben generiert die auch dazu fuumlhren koumlnnen dass der Server sehr langsam wird oder die Festplatte des Servers zulaumluft wenn fuumlr das Logging kein Dateilimit konfiguriert wurde
34 LogoutAbmeldung vom System Zum Abmelden waumlhlen Sie oben rechts das Kontextmenuuml
35 Cache loumlschen Der Cache wird in der Regel automatisch geloumlscht Wenn Sie jedoch gerade in BALVI iP eine Aumlnderung an den Schnittstellen eingespielt haben und moumlchten dass diese sofort wirksam wird kann die Funktion bdquoCache loumlschenldquo dazu verwendet werden dass der BALVI Schnittstellenserver die Einstellungen bei der naumlchsten Anfrage neu einliest
Release Notes BALVI Schnittstellenserver Seite 33 von 37
Release Notes BALVI Schnittstellenserver Seite 34 von 37
4 Einrichtung in BALVI iP Um die Verfahren fuumlr den BALVI Schnittstellenserver fuumlr Anwender freizuschalten wird das Objekt bdquoSystemeinstellungenldquo oder bdquoMandanten- und Benutzereinstellungenldquo verwendet Die Anpassung ist je Verfahren moumlglich so kann in BALVI iP fuumlr den Zugriff durch den BALVI Schnittstellenserver ein Benutzer bdquoAldquo am Verfahren bdquoMobilldquo berechtigt werden ein Benutzer bdquoBldquo nur am Verfahren bdquoSLA_FLESHldquo usw Die Logik ist jedoch einheitlich Je Verfahren wird durch BALVI eine Verfahrensgruppe mit dem Verfahrensnamen angelegt und mit den entsprechenden Einstellungen vorkonfiguriert welche durch das Verfahren erforderlich sind Dabei kann die Komplexitaumlt der Einstellungen variieren wie z B an den zu Version 23 verfuumlgbaren Verfahren bdquoMobilldquo und bdquoSLA_Fleshldquo ersichtlich wird
Im Verfahren BALVI Mobil sind diverse Anpassungen moumlglich welche je Bundesland oder eingesetzter Import- und Export-Variante durch den BALVI Schnittstellenserver bei der Bearbeitung von Anfragen gepruumlft werden siehe Punkt 3 Abb Mobil-Einstellung in BALVI iP
Abb Mobil-Einstellung in BALVI iP
Alle Verfahren verwenden jedoch die regulaumlre Benutzerverwaltung von BALVI iP Ein Benutzer ohne Passwort gilt fuumlr BALVI iP als gesperrt was fuumlr das Login bedeutet dass der Anwender sich nur uumlber die Active-Directory-Authentifizierung anmelden kann Ist das nicht moumlglich (bzw nicht konfiguriert) kann der Anwender sich weder in BALVI iP noch uumlber die Webservice-Schnittstelle authentifizieren
Fuumlr Dienste-Schnittstellen welche keine persoumlnliche Authentifizierung durch einen Anwender erfordern wird empfohlen einen separaten Benutzer in der Benutzerverwaltung anzulegen und ein sicheres Kennwort zu vergeben Das Anlegen von zusaumltzlichen Benutzern gilt nicht fuumlr BALVI mobil XT da beim Holen und Uumlbermitteln von Daten jeder Benutzer auch ein fachlich konfigurierter Anwender innerhalb von BALVI iP ist und die Anwendungsoberflaumlche ebenfalls zur Erfassung von Daten verwendet
Unter Punkt 2 der Abb Mobil-Einstellung in BALVI iP wird ein modales Fenster geoumlffnet (Abb BALVI mobil Benutzerverwaltung) Innerhalb dieses modalen Fensters werden mandantenweise die Benutzer fuumlr BALVI
Release Notes BALVI Schnittstellenserver Seite 35 von 37
mobil und den jeweiligen Fachbereich festgelegt Dabei ist es wichtig dass man die Haken bdquoAktiv fuumlr hellipldquo bei bdquohellip mobilldquo und bei einem Fachbereich (bdquohellip LMldquo bdquohellip FMldquo usw) setzt weil sonst uumlber den BALVI Schnittstellenserver keine Kommunikation mit BALVI iP moumlglich ist
Abb BALVI mobil Benutzerverwaltung
Alternativ zur Passwort-Authentifizierung wird wie beschrieben auch die Active-Directory-Authentifizierung angeboten Dazu muss der BALVI iP-Anwender uumlber die Schaltflaumlche bdquoDomaumlnen-Benutzer zuordnenldquo mit dem Active Directory verknuumlpft werden
Nur wenn die Active-Directory-Konfigurationen in BALVI iP und im BALVI Schnittstellenserver auf dieselbe Domaumlne verweisen sind die Domaumlnen-Zuordnung und die Active-Directory-Authentifizierung (z B uumlber BALVI mobil XT) moumlglich
Release Notes BALVI Schnittstellenserver Seite 36 von 37
5 Bekannte Probleme und Loumlsungen
51 ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner Bei der Job-Bearbeitung tritt folgender Fehler auf ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner
Behebung
Fuumlhren Sie das beiliegende IP-Patch (UPDATEexe) aus bevor Sie das WAR austauschen
52 Server startet nicht Sie finden folgende Zeilen im Protokoll (catalinaout oder bsslog)
ERROR [localhost-startStop-1] [IdentityServiceImpl] serverID must not be empty
ERROR [localhost-startStop-1] [ContextLoader] Context initialization failed
Behebung
Setzen Sie die Umgebungsvariable ldquoserverIDrdquo in der Datei bdquocontextxmlldquo
53 ORA-00942 table or view does not exist In vielen Faumlllen wird der Fehler ldquoTabelle oder View nicht vorhandenrdquo ausgeworfen (Java-Protokoll im Ordner logs von Apache Tomcat) wenn eine neue Schnittstelle eingerichtet oder ein neues BALVI iP Release bzw Update eingespielt wurde ohne anschlieszligend das aktuelle GRANT-Skript auszufuumlhren
Behebung
Fuumlhren Sie das GRANT-Skript erneut aus
54 ORA-0406x bdquoBestehender Paketstatus wurde aufgehobenldquo
ORA-04061 Bestehender Status von package body ABCXYZ wurde annulliert
ORA-04065 Ausfuumlhrung nicht erfolgreich package body ABCXYZ wurde geaumlndert oder geloumlscht
Release Notes BALVI Schnittstellenserver Seite 37 von 37
Der Fehler tritt haumlufig ein nachdem die UPDATEexe ausgefuumlhrt und in der Ausfuumlhrungsliste ein Package aktualisiert wurde Oracle merkt sich je User-Session bestimmte Werte im Package wenn der Anwender es verwendet hat Durch einen bdquoCREATE OR REPLACE PACKAGEldquo-Befehl kann dieser Status temporaumlr aufgehoben werden Normalerweise tritt dieser Fehler nach dem Update genau einmal in jeder aktiven Session auf wenn der BSS nicht neu gestartet wird
Behebung
Starten Sie nach jedem Update den BSS neu um alle laufenden Sessions zu beenden
55 Jobs sind nicht ausfuumlhrbar
1 Ein Job wird mit dem Status bdquoNicht unterstuumltztldquo angezeigt wenn fuumlr seine Ausfuumlhrung eine houmlhere Version des BSS erforderlich ist
2 Nach dem Klonen der Datenbank von der Produktions- auf die Testumgebung erhalten alle Jobs automatisch den Status bdquoDeaktiviertldquo wenn die bdquoserverIDldquo nicht identisch ist
Beide Statusaumlnderungen sind gewollt Damit soll verhindert werden dass Jobs nach einem Serverneustart oder nach einem Update automatisch starten und dabei Fehler verursachen
Um Jobs mit dem Status bdquoNicht unterstuumltztldquo nutzen und konfigurieren zu koumlnnen ist es erforderlich den BALVI Schnittstellenserver zu aktualisieren
Deaktivierte Jobs koumlnnen Sie aktivieren indem Sie den jeweiligen Job an den aktuellen Server binden und den Haken bei bdquoAktivldquo setzen
Release Notes BALVI Schnittstellenserver Seite 13 von 37
23 Erforderliche Bibliotheken fuumlr Apache Tomcat Dateiname Funktion Quelle ojdbc6jar Oracle 11gR2 Clientpaket Oracle JDBC Client fuumlr Java
16 ersetzt die bisherige Version bdquoojdbc14jarldquo Die alte Library muss auf jeden Fall entfernt werden
httpwwworaclecomtechnetworkdatabaseenterprise-editionjdbc-112010-090769html
encrypted-datasource-110-alljar
Die Library muss auf jeden Fall entfernt werden Wird derzeit nicht weiter gepflegt da kein Interesse an der Funktionalitaumlt bestand
slf4j-api-1511jar slf4j-log4j12-1511jar log4jdbc4-12beta2jar
Entfaumlllt nicht mehr erforderlich Es wird empfohlen diese zu entfernen falls diese im LIB-Verzeichnis vorhanden sein sollten
commons-dbcp-14jar commons-pool-154jar
Entfaumlllt nicht mehr erforderlich Es wird empfohlen diese zu entfernen falls diese im LIB-Verzeichnis vorhanden sein sollten
Erwartet wird stattdessen ab Tomcat7 die mitgelieferte bdquotomcat-jdbcjarldquo
log4j-1217jar (oder houmlher)
Logging-Funktionalitaumlt Apache Log4j httploggingapacheorglog4j12downloadhtml
bcprov-jdk15on-157jar (oder houmlher)
BouncyCastle Security Provider fuumlr SSLAES hellip wird ab Version 27 im Ordner bdquolibldquo des Tomcat erwartet Sollte es aus Sicherheitsgruumlnden erwuumlnscht sein eine aktuellere Version einzusetzen ist dieses idR moumlglich
httpmvnrepositorycomartifactorgbouncycastlebcprov-jdk15on157
24 Datenbank-Installation Der BALVI Schnittstellenserver benoumltigt auszligerhalb des angebundenen BALVI iP keine eigenen Tabellen Die Web-Anwendung kann im einfachsten Fall direkt auf das Schema von BALVI iP zugreifen indem der Benutzer und das Passwort des BALVI iP-Schemas in der Datei bdquocontextxmlldquo eingetragen werden (nicht empfohlen)
Sollte dies aus Sicherheitsgruumlnden nicht erwuumlnscht sein (empfohlen vom BSI und von BALVI) finden Sie im Paket ein GRANT-Skript um Zugriffsrechte vom BALVI iP Schema fuumlr den Webservice-Schema-Benutzer einzurichten
Zwischen dem Schema von BALVI iP und jeder Web-Anwendung ist dann eine Trennung moumlglich um sicherzustellen dass der Datenbank-Benutzer welcher in der Tomcat-Konfiguration fuumlr die Web-Anwendung eingetragen wird geaumlndert oder geloumlscht werden kann ohne dass die Windows-Anwendung BALVI iP davon betroffen ist Zudem vergibt das von BALVI gelieferte Grant-Skript keine Rechte zum Loumlschen von Tabellenstrukturen oder Tabelleninhalten so dass der Webservice nur festgelegte Daten aumlndern oder lesen darf Es wird empfohlen je Web-Anwendung einen eigenen Datenbank-Benutzer zu vergeben wenn Sie ein BALVI iP mit mehreren Webservices verbinden wollen
Die Moumlglichkeiten im Uumlberblick
1) Sie betreiben den Webservice mit einem eigenstaumlndigen Oracle-Benutzer In diesem Fall muss das
Grant-Skript ausgefuumlhrt werden um den Webservice-Benutzer und den BALVI iP-Benutzer
miteinander zu koppeln
2) In der Tomcat-Konfiguration wird der Oracle-Benutzer eingetragen welcher auch der BALVI iP
Schemabesitzer ist und in der bdquobalviip_conninildquo hinterlegt ist (NICHT Empfohlen) Der Webservice
Release Notes BALVI Schnittstellenserver Seite 14 von 37
hat 100 Zugriffsrechte (auch Loumlsch- oder Aumlnderungsrechte am Schema) es wird kein Grant-
Skript benoumltigt
Wenn Sie die Konfiguration 2) waumlhlen moumlchten koumlnnen Sie die folgenden Unterkapitel uumlberspringen und in Kapitel 0 bzw fortsetzen
241 Erstinstallation Datenbank-Benutzer anlegen Wenn Sie den Webservice-Benutzer vom BALVI iP Schema trennen moumlchten muss durch die DB-Administration in der Oracle-Server-Instanz wo auch BALVI iP sein Schema besitzt ein Benutzer (ggf je Web-Anwendung) angelegt werden welcher folgende Rechte benoumltigt
CONNECT
ALTER SESSION
CREATE JOB
CREATE PROCEDURE
CREATE SESSION
CREATE TABLE
CREATE TRIGGER
CREATE TYPE
CREATE VIEW
CREATE SEQUENCE
CREATE SYNONYM
QUERY REWRITE
Der Default-Tablespace ist frei waumlhlbar Der Benutzer braucht das Recht QUOTA UNLIMITED auf den Tablespace von BALVI iP (Default BALVI_IP) Ein Beispiel-Create-Skript bdquooraCreate_WEB_Usersqlldquo liegt der Auslieferung bei
242 Rechte zuweisen Wenn der BALVI iP Schemabesitzer NICHT in der Tomcat-Umgebung eingetragen werden soll muss ein Oracle DBA das beiliegende GRANT-Skript bdquooraGrantIP_to_Websqlldquo ausfuumlhren um dem jeweiligen Webservice (in Tomcat verwendeten Oracle-Benutzer) die minimalen Rechte auf das Schema von BALVI iP zu gewaumlhren
Dieses Skript setzt voraus dass es von einem Oracle Administrator als bdquoUser SYSTEMldquo ausgefuumlhrt wird Lesen Sie die im Skript enthaltenen README-Kommentare und passen Sie die Benutzer (BALVI iP Schema) und (WEB-Schema) an
====================================================
DEKLARATIVER TEIL MUSS vom KUNDEN geaumlndert
bzw auf die korrekten SCHEMA-Namen angepasst
werden
Die USER-Namen muumlssen in Groszligbuchstaben
geschrieben sein sonst werden sie nicht
gefunden
====================================================
sUserBALVI_IP = BALVI_IP_SCHEMABESITZER
sUserBALVI_WEB = BALVI_WEB_SCHEMABESITZER
Release Notes BALVI Schnittstellenserver Seite 15 von 37
Neu ab Grant-Skript 158 ist die Umbenennung der Verfahrenszuordnung
Pruumlfen Sie dass die Einstellung fuumlr Ihr BundeslandVerfahren korrekt ist dort muss eine 1 fuumlr min ein Verfahren gesetzt sein Diese Einstellung befindet sich direkt unter den Schemabesitzer-Angaben
-- Verfahrensbezogene Konfiguration
-- Setzen Sie fuumlr das jeweilige Verfahren eine 1
-- BALVI Schnittstellenserver (BSS)
-- bis V266 auch BALVI Kommunikationsserver (BKS) genannt
-- generell fuumlr die meisten Verfahren guumlltig
-- Ab Version 57 entfaumlllt mit der Einfuumlhrung der
-- Schnittstelle XGewerbeanzeigen auch der separate Schalter
-- WS_BTR beide Verfahren wurden vereinheitlicht
WS_BSS = 1
Fuumlhren Sie das Skript nach der Anpassung als User SYSTEM aus um die Grants durchzufuumlhren Dieses wurde mit dem von ORACLE gelieferten Programm SQLPLUS (Command-Line) SQLPLUS Worksheet (GUI) und Oracle SQL-Developer getestet
Das Skript generiert fuumlr jedes Objekt ein SYNONYM fuumlr den WEB-USER so dass dieser auf die Objekte ohne Angabe des Owners des IP-Schemas zugreifen kann Pruumlfen Sie nach der Ausfuumlhrung dass die SYNONYMS vorhanden und VALID sind dieses kann ggf nicht der Fall sein Das Skript kann jederzeit erneut ausgefuumlhrt werden um die Grants neu zu erzeugen und bietet ebenfalls die Option alle Grants und Synonyme wieder zu entfernen Detaillierte Informationen zur Nutzung des Skripts sind als Kommentar-Block im Skript enthalten
Hinweis Die Versionsinformation ist unter den Kommentaren direkt im Skript zu finden
Zugriffsberechtigungen fuumlr Webanwendungen auf BALVI iP anlegen
===============================================================
Version 158
Guumlltig fuumlr BALVI iP 123 oder houmlher
Autor Frank Holler
SVN Revisionsinformationen
$Revision 479 $
$Date 2016-02-15 152755 +0100 (Mo 15 Feb 2016) $
================================================================
243 Wann ist die Ausfuumlhrung des Grant-Skripts erforderlich Durch das Strukturupdate von BALVI iP (z B 1240 auf 1241) werden veraltete Strukturen geloumlscht und ggf neue Views oder Tabellen angelegt Die Grant-Rechte geht dabei ggf verloren Daher ist die Ausfuumlhrung des Grant-Skripts immer dann erforderlich wenn sich die Datenbank-Struktur von BALVI iP veraumlndert
Zudem kann es fachliche Neuerungen geben welche im alten Grant-Skript nicht vorhanden sind Daher muss das Skript ggf auch ausgefuumlhrt werden wenn eine neue Schnittstelle im Schnittstellenserver bereitgestellt wurde Dieses betrifft z B auch die Bereitstellung von neuen Versionen von BALVI mobil XT
Release Notes BALVI Schnittstellenserver Seite 16 von 37
da auch dort mit einem fachlich erweiterten Client die Moumlglichkeit besteht dass neue Schnittstellen bereitgestellt und somit mehr Schreibrechte auf Tabellen benoumltigt werden
244 Welche Version des Grant-Skripts soll ich nehmen Wie der Schnittstellenserver sind auch die Grant-Skripte versioniert Neuere Versionen des Grant-Skriptes sind abwaumlrts-kompatibel und koumlnnen immer verwendet werden auch wenn in einer Schnittstellenbeschreibung eine aumlltere Version des Grant-Skriptes explizit benannt wurde
245 Kombination von mehreren Verfahren Wenn Sie zwei oder mehr Schnittstellen im BSS verwenden moumlchten ist es ggf erforderlich auch mehrere Verfahren auf aktiv (bdquo1ldquo) zu setzen
Im Beispiel nehmen wir an Sie moumlchten bdquoeFildquo und bdquoBALVI mobil XTldquo im Schnittstellenserver bereitstellen In der Beschreibung von bdquoeFildquo steht dass das Grant-Skript V36 erforderlich ist BALVI mobil XT 18 erfordert jedoch schon V56
Wenn Sie beide Verfahren betreiben ist im Grant-Skript (V56 oder houmlher) die Einstellung fuumlr beide Verfahren zu aktivieren
====================================================
DEKLARATIVER TEIL MUSS vom KUNDEN geaumlndert
bzw auf die korrekten SCHEMA-Namen angepasst
werden
Die USER-Namen muumlssen in Groszligbuchstaben
geschrieben sein sonst werden sie nicht
gefunden
====================================================
sUserBALVI_IP = BALVI_IP_SCHEMA
sUserBALVI_WEB = WEBAPP_SCHEMA
-- Verfahrensbezogene Konfiguration
-- Setzen Sie fuumlr das jeweilige Verfahren eine 1
-- BALVI Schnittstellenserver (BSS)
-- bis V266 auch BALVI Kommunikationsserver (BKS) genannt
-- generell fuumlr die meisten Verfahren guumlltig
-- Ab Version 57 entfaumlllt mit der Einfuumlhrung der
-- Schnittstelle XGewerbeanzeigen auch der separate Schalter
-- WS_BTR beide Verfahren wurden vereinheitlicht
WS_BSS = 1
-- WebService BTR (Betriebsstaumlttenregister) (NRW TH)
-- entfernt mit Update V57 setzen Sie stattdessen bei WS_BSS = 1
--WS_BTR = 0
-- Probenahme Futtermittel im Browser(BY)
WS_PROBE_FM = 0
-- Risikoorientierte Probenplanung Futtermittel ndash RIOPP FM (BY)
WS_RIOPP_FM = 0
-- Verfahren Export an EFi (Status Pilotbetrieb)
WS_EFI = 1
-- neu ab Version 35 des Grant-Skriptes ist die Moumlglichkeit den Webuser
Release Notes BALVI Schnittstellenserver Seite 17 von 37
-- fuumlr das Loumlschen der Ausgangskoumlrbe explizit zu berechtigen bzw sogar einen
-- expliziten abweichenden User festzulegen Die Konfiguration in der
-- Job-Oberflaumlche sieht vor dass man die Oracle-Datenbank-Zugangsdaten fuumlr
-- das Loumlschen einstellen muss Hier muss im Normalfall derselbe Oracle
-- Datenbankbenutzer eingetragen werden wie in der Tomcat-Verbindungs-
-- konfiguration In diesem Fall sollte wenn WS_EFI = 1 eingestellt wurde
-- ebenfalls WS_EFI_DELETE = 1 eingestellt werden
-- Alternativen
-- 1) Datenbankbenutzer aumlndern
-- Wenn bei sUserEFI_TRUNC anstatt sUserBALVI_WEB (Standard) ein anderer
-- Oracle-Benutzername angegeben wird wird das Loumlschrecht fuumlr die EFi
-- Ausgangskoumlrbe Datenbankseitig exklusiv dem angegeben Datenbankbenutzer
-- zugewiesen
-- 2) Loumlschrecht verweigern
-- Setzen Sie die Variablen WS_EFI_DELETE = 0 damit kein Loumlschrecht
-- zugeweisen wird
WS_EFI_DELETE = 0
-- Beispiel Anderer Benutzer muss in der Datenbank existieren
-- Entfernen Sie die fuumlhrenden -- vor der Variable sUserEFI_TRUNC und
-- setzen den entsprechenden Oracle-Benutzer ein
--sUserEFI_TRUNC = TEST_EFI_TRUNC
hellip
25 Konfiguration des Schnittstellen-Servers
251 Die bdquocontextxmlldquo-Parameter Die von der Servlet-Spezifikation vorgegeben Rump-Struktur sieht folgendermaszligen aus
ltxml version=10 encoding=utf-8gt
ltDOCTYPE Contextgt
ltContextgt
lt-- Kundenspezifische Einstellungen --gt
ltContextgt
Anwendungsspezifische Einstellungen werden zwischen ltContextgt und ltContextgt eingefuumlgt Alle allgemeinguumlltigen Einstellungen in der Datei bdquocontextxmlldquo werden hier erlaumlutert Kommentare finden sich auch in der von BALVI ausgelieferten Beispiel-Konfiguration
Neben den im Folgenden beschriebenen Standard-Einstellungen kann es auch vorkommen dass bundeslandspezifische Erweiterungen vorhanden sind welche nicht in dieser Dokumentation aufgefuumlhrt werden Diese funktionieren trotzdem regulaumlr weiter wenn keine expliziten Informationen zu Kompatibilitaumltsproblemen in den Release-Notes aufgefuumlhrt wurden
2511 Datenbankverbindung jdbcDataSource
Die Datenbankverbindung wird uumlber die von DBCP und dem Oracle-Treiber vorgegebenen Moumlglichkeiten realisiert Der Einsatz der orgapachetomcatjdbcpoolDataSourceFactory (automatisch verfuumlgbar ab Apache Tomcat 7 in der mitgelieferten tomcat-dbcpjar) wird als Beispiel-Konfiguration ausgeliefert
ltResource
name=jdbcDataSource
auth=Container
Release Notes BALVI Schnittstellenserver Seite 18 von 37
type=javaxsqlDataSource
factory=orgapachetomcatjdbcpoolDataSourceFactory
maxActive=10 initialSize=3
maxIdle=5
maxWait=10000
url=jdbcoraclethinBL2-ORA10-KUNDENBALVIINTERN1521ORCL
driverClassName=oraclejdbcdriverOracleDriver
username=balvi_webservice_schema
password=balvi_webservice_password
description=Oracle Datasource
maxOpenPreparedStatements=50
removeAbandoned=false
removeAbandonedTimeout=100
logAbandoned=true
jdbcInterceptors=hellip
gt
Hinweise zur Einstellung der jdbcDataSource
Standard-Einstellungen fuumlr den Datenbank-Verbindungspool
Der Verbindungspool muss entsprechend der Anzahl der zu erwartenden gleichzeitigen Benutzer konfiguriert werden Wenn Sie erwarten dass 50 Anwender gleichzeitig arbeiten stellen Sie bitte folgende Werte ein
maxActive=(50 + 10 (fuumlr System und Jobs)) = 60
maxIdle= (50 10) = 5
1 maxActive - maximale Anzahl der gleichzeitigen aktiven Anfragen an die DB
Wenn der Werte maxActive erreicht ist z B wenn mehrere Benutzer gleichzeitig einen Export starten moumlchten welcher laumlngere Zeit in Anspruch nimmt dann kann der Server die Anfrage nicht mehr bedienen und der Anwender wird abgewiesen maxActive hat zudem Auswirkungen auf die im Hintergrund ausgefuumlhrten Jobs maxActive wird daher kalkuliert mit der Anzahl der Anwender und moumlglicher Datenbank-Connections fuumlr Hintergrund-Jobs Jeder aktiv ausgefuumlhrte Job benoumltigt mindestens eine Connection nur selten wird aus Performance-Gruumlnden mehr als eine Connection waumlhrend der Job-Ausfuumlhrung verwendet Im Normalfall sollten daher 10 Connections fuumlr Hintergrundprozesse ausreichend sein
2 maxIdle - Anzahl der offenen Verbindungen auch wenn der Server im Leerlauf ist
Jede offene Verbindung im Leerlauf haumllt auf dem Datenbankserver eine Session offen Auch diese erfordert Ressourcen Wenn die Verbindungen jedoch geschlossen werden kann die Anfragezeit fuumlr eine neue Verbindung steigen da diese Verbindung erst neu ausgehandelt werden muss Die Empfehlung fuumlr den Wert bdquomaxIdleldquo ist ca 10 der Einstellung von maxActive
KeepAlive-Einstellungen fuumlr den Pool
1 validationQuery
Diese wird ausgefuumlhrt um die Verbindung zu DB zu validieren Es MUSS ein Datensatz zuruumlckgegeben werden ansonsten nimmt der DBCP an dass die Abfrage nicht erfolgreich abgesetzt wurde Achten Sie also bitte darauf dass die Abfrage nicht zu leitungsintensiv ist und genau einen Datensatz liefert
Release Notes BALVI Schnittstellenserver Seite 19 von 37
Oracle bietet dafuumlr die virtuelle Tabelle DUAL an welche sich fuumlr die ValidationQuery sehr gut eignet da die Abfrage kaum Ressourcen verbraucht
validationQuery=select 1 from dual
2 testOnBorrow - Boolscher Wert true oder false
Diese Einstellung sorgt dafuumlr dass der Pool die Verfuumlgbarkeit anhand der validationQuery pruumlft bevor
die DB-Verbindung an die Anwendung ausgeliehen wird Empfehlung
testOnBorrow=true
3 testWhileIdle - Boolscher Wert true oder false
Diese Einstellung ist hilfreich wenn zwischen dem Tomcat und der DB eine Firewall mit Stateful
Packet Inspection verwendet wird Nach laumlngerer Inaktivitaumlt wird normalerweise durch die Firewall die
DB-Verbindung geschlossen Dieses loumlst dann beim Ausleihen der Verbindung eine Fehlermeldung im
Protokoll aus 2012-08-16 165418720 WARN [http-0000-8080-8]
[orgspringframeworkjdbcsupportSQLErrorCodesFactory] Error while extracting
database product name - falling back to empty error codes
orgspringframeworkjdbcsupportMetaDataAccessException Error while extracting
DatabaseMetaData nested exception is javasqlSQLRecoverableException Getrennte
Verbindung Um dieses Problem zu beheben sollte die Option testWhileIdle=true eingestellt werden
testWhileIdle=true
Damit diese weiszlig wie oft eine Pruumlfung durchgefuumlhrt werden muss sind jedoch noch zusaumltzliche Angaben erforderlich welche fuumlr die Einstellung der Zeit zusaumltzlich gesetzt werden muumlssen
a) minEvictableIdleTimeMillis - Long in Millisekunden
Min Zeit wie lange eine DB-Verbindung im Leerlauf ist bevor diese zur Pruumlfung
gekennzeichnet wird Dieses haumlngt stark von der Einstellung der Firewall ab Wenn Sie eine
sehr restriktive Firewall haben kann es sein dass diese die Verbindung nach wenigen
Minuten Leerlauf trennt Stellen Sie den Wert immer so ein dass dieser unter der Leerlaufzeit
der Firewall liegt empfohlen 300000 entspricht 300 Sek = 5 min
minEvictableIdleTimeMillis=300000
b) timeBetweenEvictionRunsMillis - Long in Millisekunden
Der Pruumlflauf startet in der Default-Konfiguration alle 1800000 Millisekunden = 30 Min n als
zu Pruumlfen markierte Verbindungen werden in einem Pruumlflauf getestet n wird bestimmt durch
die Einstellung numTestsPerEvictionRun Empfehlung Stellen Sie den Wert auf alle 15 Min
ein
timeBetweenEvictionRunsMillis=900000
Release Notes BALVI Schnittstellenserver Seite 20 von 37
c) numTestsPerEvictionRun - Integer
Wie viele Verbindungen sollen getestet werden waumlhrend der Pruumlflauf ausgefuumlhrt wird Im
Normalfall sollte die Anzahl der zu testenden Verbindungen nicht zu hoch eingestellt werden
Der Default ist 3 Wenn Sie houmlhere Sicherheit haben wollen dass keine bdquototenldquo
Datenbankverbindungen bestehen bleiben erhoumlhen Sie den Wert auf max bdquo(maxActive ndash
maxIdle) 2ldquo Wenn Ihnen 3 ausreichend erscheint muss der Wert nicht gesetzt sein dann
wird der Default verwendet
Beispiel numTestsPerEvictionRun=10
4 Interceptors konfigurieren Neu ergaumlnzt wurde die Moumlglichkeit spezielle bdquoInterceptorsldquo zu konfigurieren die ermoumlglichen das Verhalten des Pools zu steuern Wichtig hierbei ist dass die Angabe von Werten auf real existierende Java-Klassen erfolgt die im Classpath des Tomcat vorhanden sind Groszlig-und-Kleinschreibung ist zu beachten Folgende Default-Einstellung hat BALVI fuumlr den BSS festgelegt jdbcInterceptors=
orgapachetomcatjdbcpoolinterceptorConnectionState
orgapachetomcatjdbcpoolinterceptorStatementFinalizer
orgapachetomcatjdbcpoolinterceptorResetAbandonedTimer
Details zu den verwendeten Interceptor-Einstellungen finden Sie in der Tomcat-Dokumentation3
3 httptomcatapacheorgtomcat-80-docjdbc-poolhtmlJDBC_interceptors
Release Notes BALVI Schnittstellenserver Seite 21 von 37
2512 Datenbank-Zugangsdaten verschluumlsseln
Die Verschluumlsselung fuumlr die Datenbank-Verbindung (bdquoEncrypted Datasourceldquo) ist eine Ableitung der Bibliothek Apache-Common-DBCP-14 und daher nicht mehr mit Java 8 kompatibel Die Einrichtung der Verschluumlsselung wird daher mit der Auslieferung des BSS 30 nicht mehr angeboten
2513 Active-Directory-Authentifizierung
Uumlber die folgenden Parameter wird der Zugriff des Schnittstellen-Servers auf einen Microsoft Active Directory Domain-Controller konfiguriert
ldquoldapServerAddressrdquo
Syntax PROTOKOLLIP-Adresse oder DNS-NamePORT
ltEnvironment
name=ldapServerAddress
value=ldapbl2-dc02balviintern389
type=javalangString
override=true
gt
Als Protokoll besteht auch die Moumlglichkeit ldaps (LDAP+SSL) wenn der Domain-Controller entsprechend konfiguriert wurde Im Java Truststore muss dann das Zertifikat der CA vorhanden sein welche das Zertifikat des Domain-Controllers signiert hat Zudem darf bei ldaps keine IP-Adresse verwendet werden es muss der DNS-Name des Server-Zertifikats eingetragen sein Ansonsten gibt es beim Verbinden eine Sicherheits-Exception
lt-- SSL-Beispiel
ltEnvironment
name=ldapServerAddress
value=ldapsbl2-dc02balviintern636
type=javalangString
override=true
gt
--gt
bdquoldapBaseDnrdquo
LDAP-Suchpfad fuumlr die Domain-Basis Diese muss der LDAP-Syntax fuumlr den Domain-Suffix entsprechen
Syntax DC=SERVERDC=ROOTDN
ltEnvironment
name=ldapBaseDn
value=DC=BALVIDC=INTERN
type=javalangString
override=true
gt
Release Notes BALVI Schnittstellenserver Seite 22 von 37
bdquowebLoginUseActiveDirectoryAuthenticationrdquo
Die Authentifizierung in der Browser-Oberflaumlche kann uumlber die Active-Directory-Authentifizierung erfolgen In der ersten Version ist nur die Protokoll-Auswertung moumlglich wenn der ADMIN sich anmeldet Dieser hat normalerweise niemals AD-Kennungen zugeordnet BALVI empfiehlt diese Einstellung auf bdquofalseldquo zu belassen Webservices welche uumlber SOAPREST zugreifen koumlnnen die Active-Directory-Authentifizierung trotzdem verwenden
ltEnvironment
name=webLoginUseActiveDirectoryAuthentication
value=false
type=javalangBoolean
override=true
gt
ldquoldapDaysBeforeExpirationNotificationrdquo
Die Passwort-Aumlnderung im Active-Directory uumlber die Browser-Oberflaumlche ist in der ersten Version noch nicht implementiert der Parameter wird bislang nicht ausgewertet
ltEnvironment
name=ldapDaysBeforeExpirationNotification
value=14
type=javalangInteger
override=true
gt
2514 Statement-Protokollierung in BALVI iP
Diese Option aktiviert die Lese- und Aumlnderungsprotokollierung fuumlr BALVI iP Standard ist bdquofalseldquo und wird fuumlr alle Kunden empfohlen solange keine speziellen Datenbank-Jobs eingerichtet wurden welche zeitgesteuert die Protokolleintraumlge wieder loumlschen Fuumlr Bayern wurde ein spezielles Konzept zur Leseprotokollierung entworfen Wenn Sie mehr daruumlber erfahren moumlchten kontaktieren Sie bitte die BALVI GmbH
ltEnvironment
name=enableSqlStatementMonitoring
value=true
type=javalangBoolean
override=true
gt
Beachten Sie dass diese Option massive INSERT-Statements in BALVI iP in die Tabelle VIS_D92 ausfuumlhrt Jedes abgesetzte SQL-Statement wird dabei vollstaumlndig protokolliert Dieses erzeugt eine sehr hohe INSERT-Last und in der Folge auch erhoumlhte Redolog-Switches und COMMIT-Transaktionen
Optional Aktivieren der INSERT + APPEND - Logik
Beachten Sie bitte die Hinweise von Oracle zum Hint + APPEND
Release Notes BALVI Schnittstellenserver Seite 23 von 37
Wenn Sie dieses Verhalten aktivieren moumlchten ergaumlnzen Sie bitte den folgenden Environment-Parameter
ltEnvironment
name=statementMonitoringactivateAppendMode
value=true
type=javalangBoolean
override=true
gt
2515 Einstellungen fuumlr BALVI mobil XT (bzw den bdquopartitionedExportldquo)
Diese Logik des FIFO-Buffers wurde so konzipiert dass dem Rechenzentrum diverse Einstellmoumlglichkeiten uumlber die Datei bdquocontextxmlldquo zur Verfuumlgung stehen um die Steuerung des FIFO-Puffers zu beeinflussen
Schematische Darstellung des FIFO-Puffers
Das ermoumlglicht es z B dem BALVI mobil XT Client (14 oder houmlher) den aktiven Block abzuholen und dies beim Fehler bis zu 10-mal zu wiederholen Sobald der Block [001] erfolgreich beim Client angekommen ist und dieser den naumlchsten Block anfragt wird der Block [001] verworfen wird Der Server fuumlllt dann im Hintergrund den frei gewordenen Block wieder waumlhrend der Client den Block [002] abholt
Die Groumlszlige und Anzahl der vorgecachten Bloumlcke kann uumlber die folgenden Einstellungen in der Datei bdquocontextxmlldquo definiert werden
ltEnvironment
name=partitionedExportmaxBufferedPartitions
value=3 type=javalangInteger override=true
gt
ltEnvironment
name=partitionedExportpartitionSize
value=256000 type=javalangInteger override=true
gt
Die Einstellung partitionedExportmaxBufferedPartitions ist dabei die Anzahl der vorgecachten Bloumlcke mindestens muss 2 angegeben werden Der Puffercache wird ausschlieszliglich im RAM der JVM aufgebaut es wird folglich mehr Arbeitsspeicher verwendet Dieser Arbeitsspeicher muss je gleichzeitiger Session auf dem Server bereitgestellt werden die Default-Einstellung mit 3 Partitionen a 256 KB + dem aktiven Puffer erfordern 1 MB RAM je aktiven Anwender
Aktiv
er
Puffe
r
[001] Vorg
ecac
hter
Bl
ock
[002] Vorg
ecac
hter
Bl
ock
[003]
Aktiv
er P
uffe
r
[002] Vorg
ecac
hter
Bl
ock
[003] Vorg
ecac
hter
Bl
ock
[leer]
Release Notes BALVI Schnittstellenserver Seite 24 von 37
Gleichzeitig wurde die Moumlglichkeit geschaffen dass die maximale Anzahl an gleichzeitigen Exporten durch das Rechenzentrum eingeschraumlnkt werden kann um einem OutOfMemory-Fehler vorzubeugen Die Einstellung
ltEnvironment
name=partitionedExportmaxConcurrentExports
value=10 type=javalangInteger override=true
gt
muss entsprechend der zu erwartenden gleichzeitigen Zugriffe konzipiert werden ansonsten wird der Server einen Verbindungsversuch durch die Clients ablehnen
Beachten Sie dass die folgenden Einstellungen partitionedExportmaxBufferedPartitions partitionedExportmaxConcurrentExports und partitionedExportpartitionSize gemeinsam als Rechenbasis fuumlr den RAM-Bedarf des Webservers herangezogen werden muumlssen
Folgende Faustformel sollte fuumlr die Einrichtung verwendet werden
Min 256 MB (Serverbasis) + (11 partitionedExportmaxConcurrentExports partitionedExportmaxBufferedPartitions partitionedExportpartitionSize)
Beispiel 50 gleichzeitige Anwender Blockgroumlszlige 256 KB 4 Partitionen
256 MB + (11 50 256 4) KB = 312 MB fuumlr die JVM
Empf 512 MB (Serverbasis) + (12 partitionedExportmaxConcurrentExports partitionedExportmaxBufferedPartitions partitionedExportpartitionSize)
Beispiel 50 gleichzeitige Anwender Blockgroumlszlige 256 KB 4 Partitionen
512 MB + (12 50 256 4) KB = 572 MB fuumlr die JVM
partitionedExportmaxConcurrentExports
Bestimmt die Anzahl der maximalen Export Tasks (Threads) die fuumlr partitionierte Exporte bereitgestellt werden Wenn die Anzahl uumlberschritten wird wird die entsprechende Exportanfrage abgewiesen und der Client muss zu einem spaumlteren Zeitpunkt erneut anfragen Stellen Sie diesen Wert entsprechend der zu erwartenden Benutzeranzahl ein bei 50 Anwendern also 50
Exporte oumlffnen auf der Datenbank entsprechend zur Ausfuumlhrungszeit min einen Cursor ggf fuumlr rekursive Unterabfragen kurzfristig sogar mehr Die hier eingestellte Anzahl muss mit der Anzahl von maxActive korrelieren
ltEnvironment
name=partitionedExportmaxConcurrentExports
value=10 type=javalangInteger override=true
gt
partitionedExportmaxBufferedPartitions
Bestimmt die Anzahl der Datenbloumlcke (Partitionen) die vom Server bei Abruf eines Exportes gepuffert werden Die seit Version 24 eingefuumlhrte FIFO-Puffer-Logik ermoumlglicht dass der Server schon die Ergebnisse vorpuffert so dass der Client weniger Wartezeiten bei der Anfrage nach Daten hat Diese
Release Notes BALVI Schnittstellenserver Seite 25 von 37
Puffer-Logik unterteilt den Exportdatenstrom (je Export) in mehre Bloumlcke Der Client kann nun den letzten Block neu anfordern oder den naumlchsten Block wenn der letzte Block erfolgreich verarbeitet wurde Wie viele naumlchste Bloumlcke durch den Server bereit gestellt werden entscheidet diese Einstellung Sobald kein naumlchster Block mehr bereit gestellt werden muss wird der Datenbank-Cursor geschlossen eine Erhoumlhung kann also zu einer Entlastung der aktiven DB-Verbindungen fuumlhren erhoumlht jedoch den Bedarf an RAM des Servers
Der von BALVI voreingestellte Wert ist 3
ltEnvironment
name=partitionedExportmaxBufferedPartitions
value=3 type=javalangInteger override=true
gt
partitionedExportpartitionSizeldquo
Die Groumlszlige der Datenbloumlcke (Partitionen) die an den Client uumlbermittelt werden in Bytes Wenn Sie diesen Wert zu niedrig einstellen reduziert sich die Effizienz des Caches da der Client mehr Datenbloumlcke hintereinander abrufen muss Waumlhlen Sie einen zu groszligen Wert wird die neu zu uumlbertragende Datenmenge im Fall eines Fehlers houmlher
Der von BALVI voreingestellte Wert ist 256000 (256 KB)
ltEnvironment
name=partitionedExportpartitionSize
value=256000 type=javalangInteger override=true
gt
exportTokensmaxTokenCount
Maximale Anzahl der gleichzeitig vergebenen Token die vom Server gecached werden Jede Sitzung welche einen Export durchfuumlhrt erhaumllt einen Session-Token
Wenn eine Sitzung laumlngere Zeit nicht verwendet wurde wird dieser Session-Token wieder entfernt Wenn Sie den Wert zu niedrig einstellen fuumlhrt das zu einer generellen Session-Begrenzung auch fuumlr den nicht partitionierten Export-Modus welcher ab Version 21 verfuumlgbar ist
Ist die Anzahl der Tokens houmlher als die Datenbankeinstellung maxActive kann es vorkommen dass zwar eine Session gestartet werden kann jedoch kein Datenexport zustande kommt
Der von BALVI voreingestellte Wert ist 2000
ltEnvironment
name=exportTokensmaxTokenCount
value=20 type=javalangInteger override=true
gt
exportTokenstokenExpirationInSeconds
Zeit in Sekunden die verstreichen muss bis ein Token unguumlltig wird falls darauf kein Zugriff mehr erfolgt Nach einem erfolgreichen Export wird der Token automatisch geschlossen diese Option ist fuumlr den Abbruchfall vorgesehen Der von BALVI voreingestellte Wert ist 180 (180 s = 3 min)
Release Notes BALVI Schnittstellenserver Seite 26 von 37
ltEnvironment
name=exportTokenstokenExpirationInSeconds
value=180 type=javalangInteger override=true
gt
exportTokenstokenDisposalInSeconds
Zeit in Sekunden die verstreichen muss bis ein Token das erfolgreich abgearbeitet wurde aus dem Cache geloumlscht wird Um sicher zu stellen dass der letzte Exportblock noch erfolgreich abgerufen werden kann bleibt der Token auch nach Fertigmeldung des Clients noch N Sek guumlltig
Der von BALVI voreingestellte Wert ist 60 (60 s = 1 min)
ltEnvironment
name=exportTokenstokenDisposalInSeconds
value=60 type=javalangInteger override=true
gt
2516 Job-Verwaltung fuumlr den BSS konfigurieren Aktivierung der Jobverwaltung
Bis zur Version 28 des BSS gab es den Parameter bdquoavailableServicesldquo Dieser konnte bei Bedarf aktiviert werden wenn die Jobs benoumltigt wurden
Mit Version 30 ist die Einstellung bdquoavailableServicesldquo zu entfernen und kann durch den neuen optionalen Parameter bdquoisJobServiceEnabledldquo in der Datei bdquocontextxmlldquo ersetzt werden
lt-- Neue Parameter zur Aktivierung des Job Service Ersatz fuumlr availableServices --gt
ltEnvironment
name=isJobServiceEnabled
value=true
type=javalangBoolean
override=true
gt
Ab BSS 30 wird die Jobs-Engine standardmaumlszligig aktiviert Sollte die Jobs-Engine nicht benoumltigt werden muss bdquovalueldquo der Wert bdquofalseldquo zugewiesen werden Wird bdquoisJobServiceEnabledldquo nicht eingefuumlgt sind die Jobs trotzdem standardmaumlszligig aktiv
Nach dem Neustart des Servers und erneutem Einloggen erscheint nun zusaumltzlich der Menuumlpunkt bdquoJobsldquo
bdquopasswordKeyldquo fuumlr Jobs
In der Job-Logik wird ein von BALVI definierter Standard-Schluumlssel fuumlr die Ablagen von schuumltzenswerten Daten z B Passwoumlrtern verwendet Diese Einstellung ermoumlglicht den BALVI-Standard zu uumlberschreiben Wenn Sie diese Einstellung aumlndern muumlssen jedoch alle bislang verschluumlsselten Job-Parameter neu verschluumlsselt werden
ltEnvironment
name=javacompenvjobspasswordKey
value=MeinHochsicheresNeuesPasswort
type=javalangString
Release Notes BALVI Schnittstellenserver Seite 27 von 37
override=true
gt
bdquoJob ID enableddisabledldquo (Deprecated ersetzt ab 28 durch das bdquoBindenldquo von Jobs)
Sondereinstellungen fuumlr die Job-Verwaltung Da alle Jobs in einer Datenbank administriert werden jedoch ggf verteilt auf mehreren Tomcat-Servern ausgefuumlhrt werden sollen besteht hier die Option Jobs fuumlr die aktuelle Tomcat-Instanz separat zu deaktivieren
Die Einstellung ID koumlnnte z B folgendermaszligen aussehen javacompenvjobsC0DB58D8D52C4BBC966D1DC788A4EF8Benabled
Fuumlr weitere Fragen zu dieser Einstellung kontaktieren Sie bitte die BALVI GmbH
ltEnvironment
name=javacompenvjobsIDenabled
value=false
type=javalangBoolean
override=true
gt
2517 Weitere optionale Parameter
Es ist fuumlr diverse einzelne Schnittstellen ggf erforderlich Einstellungen in der Datei bdquocontextxmlldquo zu ergaumlnzen Hinweise zu diesen Parametern sind dann in dem der Schnittstelle beiliegenden Dokument enthalten Das gilt z B fuumlr die Schnittstelle bdquoXGewerbeanzeigenldquo
26 Logging mit logback Das Logging wurde komplett uumlberarbeitet Statt bdquoLog4Jldquo wird jetzt bdquologbackldquo4 benutzt Ab BSS 30 ist es zwingend notwendig die Einstellung vorzunehmen um das Logging der Anwendung zu steuern
Migration Ergaumlnzen Sie die neue Einstellung bdquologgingconfigldquo
lt-- Neue Paramter zur Angabe der Logback Config Ersatz fuumlr log4jConfigLocation --gt
ltEnvironment
name=loggingconfig
value=$catalinabaseconflogback-bssxml
type=javalangString
override=true
gt
Nach wie vor steht es Ihnen frei die Logging-Konfiguration eigenstaumlndig anzupassen
Wenn Sie jedoch dieselbe WAR in einer Tomcat-Instanz unter mehreren Context-Namen betreiben wuumlrden beide dieselbe Logging-Konfiguration verwenden so dass alle Protokolleintraumlge in einer Log-Datei aus
4 httplogbackqoschmanualappendershtml
Release Notes BALVI Schnittstellenserver Seite 28 von 37
mehreren Webanwendungen generiert werden Aumlndern Sie den Namen der Logging-Konfiguration entsprechend ab um fuumlr jede Anwendung eine spezifische Logging-Einstellung vornehmen zu koumlnnen
27 Tocmat Optional Suche im bdquoKlassenpfadldquo um den
Ordner bdquoconfldquo erweitern Die Suche nach Dateien uumlber bdquoclasspathldquo setzt voraus dass die Ordner- und Dateinamen im Apache Tomcat bekannt gegeben werden Der Klassenpfad kann in der Datei bdquocatalinapropertiesldquo angepasst werden Wenn Sie dort unter commonloader die folgenden Werte ergaumlnzen kann eine Datei auch im Ordner conf abgelegt werden damit Apache Tomcat diese findet Ansonsten muss die Datei im Ordner lib abgelegt werden
commonloader=$catalinabaseconf$catalinahomeconf
3 Die neue Browser-Oberflaumlche Der BALVI Schnittstellenserver hat seit Version 25 neben der Protokollierung auch die Moumlglichkeit Job-Konfigurationen zu pflegen Der Login ist nur fuumlr einen in BALVI iP eingetragenen ADMIN (z B Benutzer bdquoSYSTEMADMINldquo) mit dem in BALVI iP hinterlegten Passwort moumlglich Zur Anmeldung muss immer [SYSTEMBenutzername] im Feld Benutzer angegeben werden ansonsten schlaumlgt die Anmeldung fehl Bitte achten Sie darauf dass der bdquoldquo (Slash) und nicht der bdquoldquo (Backslash) verwendet werden muss
31 Server-Protokoll Um das Server-Protokoll anzuzeigen waumlhlen Sie den entsprechenden Menuumlpunkt Dort haben Sie seit BSS 26 die Moumlglichkeit uumlber alle Spalten der Protokolle nach Informationen zu suchen
Seit BSS 31 gibt es die Moumlglichkeit Verfahren in bdquoKopfsaumltzeldquo und bdquoDetailsaumltzeldquo zu unterteilen Wurde das Verfahren entsprechend konfiguriert (wie z B bei der Schnittstelle bdquoXGewerbeanzeigenldquo) dann wird im Protokoll-Kopfsatz nur der Start und das Ende der Ausfuumlhrung in der Liste angezeigt Erst bei einem Klick auf bdquoInformationenldquo wird die Liste aller Detailsaumltze angezeigt die im Durchlauf erzeugt wurden
Release Notes BALVI Schnittstellenserver Seite 29 von 37
Verfahren
Die Liste der verfuumlgbaren Verfahren die bei Ihnen im System installiert sind ZB
BEFUNDEhellip Schnittstelle Befunde LM FM oder TS
PROBEhellip Schnittstelle zum Export von Proben an Labore ebenfalls Spezifisch fuumlr einzelne Fachbereiche
MOBILXT Protokolle der BALVI Mobil XT Synchronisation
WEB Allgemeine nicht spezifizierte Protokolle hierunter ist bislang auch die eFi-Protokollierung zu finden
WEB_I0802 Protokolle zur Schnittstelle BALVI iP LIMS (Lebensmittelproben)
XGEWERBE Schnittstelle XGewerbeanzeigen
Klicken Sie auf die Schaltflaumlche so besteht bei den neuen Protokolldatensaumltzen die Moumlglichkeit Detail-Informationen zum Protokollsatz zu erhalten
Release Notes BALVI Schnittstellenserver Seite 30 von 37
Seit BSS 30x ist die Anzeige der Protokolle ebenfalls farblich abgesetzt so dass Protokolleintraumlge mit Fehlern hellrot und Warnungen hellgelb hinterlegt werden
32 Jobs Mit einem Klick auf den Menuumlpunkt Jobs rufen Sie die Oberflaumlche fuumlr die Job-Konfiguration auf Daraufhin werden alle Jobs aufgelistet die fuumlr den BSS freigegeben sind Hier koumlnnen Sie Einstellungen an den Jobs vornehmen und die Jobs aktivieren bzw deaktivieren Die Beschreibungen bzw Einstellungsmoumlglichkeiten fuumlr den jeweiligen SST-Job sind nicht Bestandteil dieser Dokumentation
33 Log-Ausgaben Uumlber den Menuumlpunkt Log-Ausgaben koumlnnen Sie die Ausgabe der Protokolleintraumlge in Echtzeit beobachten
Release Notes BALVI Schnittstellenserver Seite 31 von 37
Starten Sie die Echtzeit-Protokollierung indem Sie auf die Schaltflaumlche mit dem Symbol bdquoPlayldquo (Dreieck) klicken unterbrechen Sie die Ausgabe indem Sie die auf Schaltflaumlche mit dem Symbol bdquoPauseldquo (zwei Balken) klicken
Klicken Sie auf die Schaltflaumlche bdquoAktualisierenldquo (zwei Pfeile) um die neuesten Protokolleintraumlge angezeigt zu bekommen
Klicken Sie auf das Symbol mit dem Papierkorb um die letzten Protokollmeldungen in der Anzeige zu loumlschen
Die Daten in den Protokolldateien auf der Festplatte des Servers sind davon nicht betroffen
Uumlber das Symbol bdquoLogging anpassenldquo (Schraubenschluumlssel) koumlnnen Sie die Ausgabe der Daten im Echtzeitfenster und in den Protokolldateien aumlndern jedoch ist diese Einstellung nur temporaumlr Die Standardeinstellungen koumlnnen ausschlieszliglich uumlber die Anpassung der Datei bdquologback-bssxmlldquo im Konfigurationsverzeichnis des Servers selbst geaumlndert werden
Release Notes BALVI Schnittstellenserver Seite 32 von 37
In der Logging-Parameter Konfiguration koumlnnen Sie verschiedene Parameter einstellen und uumlber die Schaltflaumlche bdquoAnwendenldquo dann sofort im Echtzeitprotokoll sehen Welche Einstellungen moumlglich sind erfahren Sie wenn es eine akute Fehlersituation gibt die detailliertere Ausgaben im Protokoll erfordert
Warnung Wenn Sie den Log-Level fuumlr ROOT oder eine andere Klasse auf TRACE einstellen werden sehr viele Protokollausgaben generiert die auch dazu fuumlhren koumlnnen dass der Server sehr langsam wird oder die Festplatte des Servers zulaumluft wenn fuumlr das Logging kein Dateilimit konfiguriert wurde
34 LogoutAbmeldung vom System Zum Abmelden waumlhlen Sie oben rechts das Kontextmenuuml
35 Cache loumlschen Der Cache wird in der Regel automatisch geloumlscht Wenn Sie jedoch gerade in BALVI iP eine Aumlnderung an den Schnittstellen eingespielt haben und moumlchten dass diese sofort wirksam wird kann die Funktion bdquoCache loumlschenldquo dazu verwendet werden dass der BALVI Schnittstellenserver die Einstellungen bei der naumlchsten Anfrage neu einliest
Release Notes BALVI Schnittstellenserver Seite 33 von 37
Release Notes BALVI Schnittstellenserver Seite 34 von 37
4 Einrichtung in BALVI iP Um die Verfahren fuumlr den BALVI Schnittstellenserver fuumlr Anwender freizuschalten wird das Objekt bdquoSystemeinstellungenldquo oder bdquoMandanten- und Benutzereinstellungenldquo verwendet Die Anpassung ist je Verfahren moumlglich so kann in BALVI iP fuumlr den Zugriff durch den BALVI Schnittstellenserver ein Benutzer bdquoAldquo am Verfahren bdquoMobilldquo berechtigt werden ein Benutzer bdquoBldquo nur am Verfahren bdquoSLA_FLESHldquo usw Die Logik ist jedoch einheitlich Je Verfahren wird durch BALVI eine Verfahrensgruppe mit dem Verfahrensnamen angelegt und mit den entsprechenden Einstellungen vorkonfiguriert welche durch das Verfahren erforderlich sind Dabei kann die Komplexitaumlt der Einstellungen variieren wie z B an den zu Version 23 verfuumlgbaren Verfahren bdquoMobilldquo und bdquoSLA_Fleshldquo ersichtlich wird
Im Verfahren BALVI Mobil sind diverse Anpassungen moumlglich welche je Bundesland oder eingesetzter Import- und Export-Variante durch den BALVI Schnittstellenserver bei der Bearbeitung von Anfragen gepruumlft werden siehe Punkt 3 Abb Mobil-Einstellung in BALVI iP
Abb Mobil-Einstellung in BALVI iP
Alle Verfahren verwenden jedoch die regulaumlre Benutzerverwaltung von BALVI iP Ein Benutzer ohne Passwort gilt fuumlr BALVI iP als gesperrt was fuumlr das Login bedeutet dass der Anwender sich nur uumlber die Active-Directory-Authentifizierung anmelden kann Ist das nicht moumlglich (bzw nicht konfiguriert) kann der Anwender sich weder in BALVI iP noch uumlber die Webservice-Schnittstelle authentifizieren
Fuumlr Dienste-Schnittstellen welche keine persoumlnliche Authentifizierung durch einen Anwender erfordern wird empfohlen einen separaten Benutzer in der Benutzerverwaltung anzulegen und ein sicheres Kennwort zu vergeben Das Anlegen von zusaumltzlichen Benutzern gilt nicht fuumlr BALVI mobil XT da beim Holen und Uumlbermitteln von Daten jeder Benutzer auch ein fachlich konfigurierter Anwender innerhalb von BALVI iP ist und die Anwendungsoberflaumlche ebenfalls zur Erfassung von Daten verwendet
Unter Punkt 2 der Abb Mobil-Einstellung in BALVI iP wird ein modales Fenster geoumlffnet (Abb BALVI mobil Benutzerverwaltung) Innerhalb dieses modalen Fensters werden mandantenweise die Benutzer fuumlr BALVI
Release Notes BALVI Schnittstellenserver Seite 35 von 37
mobil und den jeweiligen Fachbereich festgelegt Dabei ist es wichtig dass man die Haken bdquoAktiv fuumlr hellipldquo bei bdquohellip mobilldquo und bei einem Fachbereich (bdquohellip LMldquo bdquohellip FMldquo usw) setzt weil sonst uumlber den BALVI Schnittstellenserver keine Kommunikation mit BALVI iP moumlglich ist
Abb BALVI mobil Benutzerverwaltung
Alternativ zur Passwort-Authentifizierung wird wie beschrieben auch die Active-Directory-Authentifizierung angeboten Dazu muss der BALVI iP-Anwender uumlber die Schaltflaumlche bdquoDomaumlnen-Benutzer zuordnenldquo mit dem Active Directory verknuumlpft werden
Nur wenn die Active-Directory-Konfigurationen in BALVI iP und im BALVI Schnittstellenserver auf dieselbe Domaumlne verweisen sind die Domaumlnen-Zuordnung und die Active-Directory-Authentifizierung (z B uumlber BALVI mobil XT) moumlglich
Release Notes BALVI Schnittstellenserver Seite 36 von 37
5 Bekannte Probleme und Loumlsungen
51 ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner Bei der Job-Bearbeitung tritt folgender Fehler auf ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner
Behebung
Fuumlhren Sie das beiliegende IP-Patch (UPDATEexe) aus bevor Sie das WAR austauschen
52 Server startet nicht Sie finden folgende Zeilen im Protokoll (catalinaout oder bsslog)
ERROR [localhost-startStop-1] [IdentityServiceImpl] serverID must not be empty
ERROR [localhost-startStop-1] [ContextLoader] Context initialization failed
Behebung
Setzen Sie die Umgebungsvariable ldquoserverIDrdquo in der Datei bdquocontextxmlldquo
53 ORA-00942 table or view does not exist In vielen Faumlllen wird der Fehler ldquoTabelle oder View nicht vorhandenrdquo ausgeworfen (Java-Protokoll im Ordner logs von Apache Tomcat) wenn eine neue Schnittstelle eingerichtet oder ein neues BALVI iP Release bzw Update eingespielt wurde ohne anschlieszligend das aktuelle GRANT-Skript auszufuumlhren
Behebung
Fuumlhren Sie das GRANT-Skript erneut aus
54 ORA-0406x bdquoBestehender Paketstatus wurde aufgehobenldquo
ORA-04061 Bestehender Status von package body ABCXYZ wurde annulliert
ORA-04065 Ausfuumlhrung nicht erfolgreich package body ABCXYZ wurde geaumlndert oder geloumlscht
Release Notes BALVI Schnittstellenserver Seite 37 von 37
Der Fehler tritt haumlufig ein nachdem die UPDATEexe ausgefuumlhrt und in der Ausfuumlhrungsliste ein Package aktualisiert wurde Oracle merkt sich je User-Session bestimmte Werte im Package wenn der Anwender es verwendet hat Durch einen bdquoCREATE OR REPLACE PACKAGEldquo-Befehl kann dieser Status temporaumlr aufgehoben werden Normalerweise tritt dieser Fehler nach dem Update genau einmal in jeder aktiven Session auf wenn der BSS nicht neu gestartet wird
Behebung
Starten Sie nach jedem Update den BSS neu um alle laufenden Sessions zu beenden
55 Jobs sind nicht ausfuumlhrbar
1 Ein Job wird mit dem Status bdquoNicht unterstuumltztldquo angezeigt wenn fuumlr seine Ausfuumlhrung eine houmlhere Version des BSS erforderlich ist
2 Nach dem Klonen der Datenbank von der Produktions- auf die Testumgebung erhalten alle Jobs automatisch den Status bdquoDeaktiviertldquo wenn die bdquoserverIDldquo nicht identisch ist
Beide Statusaumlnderungen sind gewollt Damit soll verhindert werden dass Jobs nach einem Serverneustart oder nach einem Update automatisch starten und dabei Fehler verursachen
Um Jobs mit dem Status bdquoNicht unterstuumltztldquo nutzen und konfigurieren zu koumlnnen ist es erforderlich den BALVI Schnittstellenserver zu aktualisieren
Deaktivierte Jobs koumlnnen Sie aktivieren indem Sie den jeweiligen Job an den aktuellen Server binden und den Haken bei bdquoAktivldquo setzen
Release Notes BALVI Schnittstellenserver Seite 14 von 37
hat 100 Zugriffsrechte (auch Loumlsch- oder Aumlnderungsrechte am Schema) es wird kein Grant-
Skript benoumltigt
Wenn Sie die Konfiguration 2) waumlhlen moumlchten koumlnnen Sie die folgenden Unterkapitel uumlberspringen und in Kapitel 0 bzw fortsetzen
241 Erstinstallation Datenbank-Benutzer anlegen Wenn Sie den Webservice-Benutzer vom BALVI iP Schema trennen moumlchten muss durch die DB-Administration in der Oracle-Server-Instanz wo auch BALVI iP sein Schema besitzt ein Benutzer (ggf je Web-Anwendung) angelegt werden welcher folgende Rechte benoumltigt
CONNECT
ALTER SESSION
CREATE JOB
CREATE PROCEDURE
CREATE SESSION
CREATE TABLE
CREATE TRIGGER
CREATE TYPE
CREATE VIEW
CREATE SEQUENCE
CREATE SYNONYM
QUERY REWRITE
Der Default-Tablespace ist frei waumlhlbar Der Benutzer braucht das Recht QUOTA UNLIMITED auf den Tablespace von BALVI iP (Default BALVI_IP) Ein Beispiel-Create-Skript bdquooraCreate_WEB_Usersqlldquo liegt der Auslieferung bei
242 Rechte zuweisen Wenn der BALVI iP Schemabesitzer NICHT in der Tomcat-Umgebung eingetragen werden soll muss ein Oracle DBA das beiliegende GRANT-Skript bdquooraGrantIP_to_Websqlldquo ausfuumlhren um dem jeweiligen Webservice (in Tomcat verwendeten Oracle-Benutzer) die minimalen Rechte auf das Schema von BALVI iP zu gewaumlhren
Dieses Skript setzt voraus dass es von einem Oracle Administrator als bdquoUser SYSTEMldquo ausgefuumlhrt wird Lesen Sie die im Skript enthaltenen README-Kommentare und passen Sie die Benutzer (BALVI iP Schema) und (WEB-Schema) an
====================================================
DEKLARATIVER TEIL MUSS vom KUNDEN geaumlndert
bzw auf die korrekten SCHEMA-Namen angepasst
werden
Die USER-Namen muumlssen in Groszligbuchstaben
geschrieben sein sonst werden sie nicht
gefunden
====================================================
sUserBALVI_IP = BALVI_IP_SCHEMABESITZER
sUserBALVI_WEB = BALVI_WEB_SCHEMABESITZER
Release Notes BALVI Schnittstellenserver Seite 15 von 37
Neu ab Grant-Skript 158 ist die Umbenennung der Verfahrenszuordnung
Pruumlfen Sie dass die Einstellung fuumlr Ihr BundeslandVerfahren korrekt ist dort muss eine 1 fuumlr min ein Verfahren gesetzt sein Diese Einstellung befindet sich direkt unter den Schemabesitzer-Angaben
-- Verfahrensbezogene Konfiguration
-- Setzen Sie fuumlr das jeweilige Verfahren eine 1
-- BALVI Schnittstellenserver (BSS)
-- bis V266 auch BALVI Kommunikationsserver (BKS) genannt
-- generell fuumlr die meisten Verfahren guumlltig
-- Ab Version 57 entfaumlllt mit der Einfuumlhrung der
-- Schnittstelle XGewerbeanzeigen auch der separate Schalter
-- WS_BTR beide Verfahren wurden vereinheitlicht
WS_BSS = 1
Fuumlhren Sie das Skript nach der Anpassung als User SYSTEM aus um die Grants durchzufuumlhren Dieses wurde mit dem von ORACLE gelieferten Programm SQLPLUS (Command-Line) SQLPLUS Worksheet (GUI) und Oracle SQL-Developer getestet
Das Skript generiert fuumlr jedes Objekt ein SYNONYM fuumlr den WEB-USER so dass dieser auf die Objekte ohne Angabe des Owners des IP-Schemas zugreifen kann Pruumlfen Sie nach der Ausfuumlhrung dass die SYNONYMS vorhanden und VALID sind dieses kann ggf nicht der Fall sein Das Skript kann jederzeit erneut ausgefuumlhrt werden um die Grants neu zu erzeugen und bietet ebenfalls die Option alle Grants und Synonyme wieder zu entfernen Detaillierte Informationen zur Nutzung des Skripts sind als Kommentar-Block im Skript enthalten
Hinweis Die Versionsinformation ist unter den Kommentaren direkt im Skript zu finden
Zugriffsberechtigungen fuumlr Webanwendungen auf BALVI iP anlegen
===============================================================
Version 158
Guumlltig fuumlr BALVI iP 123 oder houmlher
Autor Frank Holler
SVN Revisionsinformationen
$Revision 479 $
$Date 2016-02-15 152755 +0100 (Mo 15 Feb 2016) $
================================================================
243 Wann ist die Ausfuumlhrung des Grant-Skripts erforderlich Durch das Strukturupdate von BALVI iP (z B 1240 auf 1241) werden veraltete Strukturen geloumlscht und ggf neue Views oder Tabellen angelegt Die Grant-Rechte geht dabei ggf verloren Daher ist die Ausfuumlhrung des Grant-Skripts immer dann erforderlich wenn sich die Datenbank-Struktur von BALVI iP veraumlndert
Zudem kann es fachliche Neuerungen geben welche im alten Grant-Skript nicht vorhanden sind Daher muss das Skript ggf auch ausgefuumlhrt werden wenn eine neue Schnittstelle im Schnittstellenserver bereitgestellt wurde Dieses betrifft z B auch die Bereitstellung von neuen Versionen von BALVI mobil XT
Release Notes BALVI Schnittstellenserver Seite 16 von 37
da auch dort mit einem fachlich erweiterten Client die Moumlglichkeit besteht dass neue Schnittstellen bereitgestellt und somit mehr Schreibrechte auf Tabellen benoumltigt werden
244 Welche Version des Grant-Skripts soll ich nehmen Wie der Schnittstellenserver sind auch die Grant-Skripte versioniert Neuere Versionen des Grant-Skriptes sind abwaumlrts-kompatibel und koumlnnen immer verwendet werden auch wenn in einer Schnittstellenbeschreibung eine aumlltere Version des Grant-Skriptes explizit benannt wurde
245 Kombination von mehreren Verfahren Wenn Sie zwei oder mehr Schnittstellen im BSS verwenden moumlchten ist es ggf erforderlich auch mehrere Verfahren auf aktiv (bdquo1ldquo) zu setzen
Im Beispiel nehmen wir an Sie moumlchten bdquoeFildquo und bdquoBALVI mobil XTldquo im Schnittstellenserver bereitstellen In der Beschreibung von bdquoeFildquo steht dass das Grant-Skript V36 erforderlich ist BALVI mobil XT 18 erfordert jedoch schon V56
Wenn Sie beide Verfahren betreiben ist im Grant-Skript (V56 oder houmlher) die Einstellung fuumlr beide Verfahren zu aktivieren
====================================================
DEKLARATIVER TEIL MUSS vom KUNDEN geaumlndert
bzw auf die korrekten SCHEMA-Namen angepasst
werden
Die USER-Namen muumlssen in Groszligbuchstaben
geschrieben sein sonst werden sie nicht
gefunden
====================================================
sUserBALVI_IP = BALVI_IP_SCHEMA
sUserBALVI_WEB = WEBAPP_SCHEMA
-- Verfahrensbezogene Konfiguration
-- Setzen Sie fuumlr das jeweilige Verfahren eine 1
-- BALVI Schnittstellenserver (BSS)
-- bis V266 auch BALVI Kommunikationsserver (BKS) genannt
-- generell fuumlr die meisten Verfahren guumlltig
-- Ab Version 57 entfaumlllt mit der Einfuumlhrung der
-- Schnittstelle XGewerbeanzeigen auch der separate Schalter
-- WS_BTR beide Verfahren wurden vereinheitlicht
WS_BSS = 1
-- WebService BTR (Betriebsstaumlttenregister) (NRW TH)
-- entfernt mit Update V57 setzen Sie stattdessen bei WS_BSS = 1
--WS_BTR = 0
-- Probenahme Futtermittel im Browser(BY)
WS_PROBE_FM = 0
-- Risikoorientierte Probenplanung Futtermittel ndash RIOPP FM (BY)
WS_RIOPP_FM = 0
-- Verfahren Export an EFi (Status Pilotbetrieb)
WS_EFI = 1
-- neu ab Version 35 des Grant-Skriptes ist die Moumlglichkeit den Webuser
Release Notes BALVI Schnittstellenserver Seite 17 von 37
-- fuumlr das Loumlschen der Ausgangskoumlrbe explizit zu berechtigen bzw sogar einen
-- expliziten abweichenden User festzulegen Die Konfiguration in der
-- Job-Oberflaumlche sieht vor dass man die Oracle-Datenbank-Zugangsdaten fuumlr
-- das Loumlschen einstellen muss Hier muss im Normalfall derselbe Oracle
-- Datenbankbenutzer eingetragen werden wie in der Tomcat-Verbindungs-
-- konfiguration In diesem Fall sollte wenn WS_EFI = 1 eingestellt wurde
-- ebenfalls WS_EFI_DELETE = 1 eingestellt werden
-- Alternativen
-- 1) Datenbankbenutzer aumlndern
-- Wenn bei sUserEFI_TRUNC anstatt sUserBALVI_WEB (Standard) ein anderer
-- Oracle-Benutzername angegeben wird wird das Loumlschrecht fuumlr die EFi
-- Ausgangskoumlrbe Datenbankseitig exklusiv dem angegeben Datenbankbenutzer
-- zugewiesen
-- 2) Loumlschrecht verweigern
-- Setzen Sie die Variablen WS_EFI_DELETE = 0 damit kein Loumlschrecht
-- zugeweisen wird
WS_EFI_DELETE = 0
-- Beispiel Anderer Benutzer muss in der Datenbank existieren
-- Entfernen Sie die fuumlhrenden -- vor der Variable sUserEFI_TRUNC und
-- setzen den entsprechenden Oracle-Benutzer ein
--sUserEFI_TRUNC = TEST_EFI_TRUNC
hellip
25 Konfiguration des Schnittstellen-Servers
251 Die bdquocontextxmlldquo-Parameter Die von der Servlet-Spezifikation vorgegeben Rump-Struktur sieht folgendermaszligen aus
ltxml version=10 encoding=utf-8gt
ltDOCTYPE Contextgt
ltContextgt
lt-- Kundenspezifische Einstellungen --gt
ltContextgt
Anwendungsspezifische Einstellungen werden zwischen ltContextgt und ltContextgt eingefuumlgt Alle allgemeinguumlltigen Einstellungen in der Datei bdquocontextxmlldquo werden hier erlaumlutert Kommentare finden sich auch in der von BALVI ausgelieferten Beispiel-Konfiguration
Neben den im Folgenden beschriebenen Standard-Einstellungen kann es auch vorkommen dass bundeslandspezifische Erweiterungen vorhanden sind welche nicht in dieser Dokumentation aufgefuumlhrt werden Diese funktionieren trotzdem regulaumlr weiter wenn keine expliziten Informationen zu Kompatibilitaumltsproblemen in den Release-Notes aufgefuumlhrt wurden
2511 Datenbankverbindung jdbcDataSource
Die Datenbankverbindung wird uumlber die von DBCP und dem Oracle-Treiber vorgegebenen Moumlglichkeiten realisiert Der Einsatz der orgapachetomcatjdbcpoolDataSourceFactory (automatisch verfuumlgbar ab Apache Tomcat 7 in der mitgelieferten tomcat-dbcpjar) wird als Beispiel-Konfiguration ausgeliefert
ltResource
name=jdbcDataSource
auth=Container
Release Notes BALVI Schnittstellenserver Seite 18 von 37
type=javaxsqlDataSource
factory=orgapachetomcatjdbcpoolDataSourceFactory
maxActive=10 initialSize=3
maxIdle=5
maxWait=10000
url=jdbcoraclethinBL2-ORA10-KUNDENBALVIINTERN1521ORCL
driverClassName=oraclejdbcdriverOracleDriver
username=balvi_webservice_schema
password=balvi_webservice_password
description=Oracle Datasource
maxOpenPreparedStatements=50
removeAbandoned=false
removeAbandonedTimeout=100
logAbandoned=true
jdbcInterceptors=hellip
gt
Hinweise zur Einstellung der jdbcDataSource
Standard-Einstellungen fuumlr den Datenbank-Verbindungspool
Der Verbindungspool muss entsprechend der Anzahl der zu erwartenden gleichzeitigen Benutzer konfiguriert werden Wenn Sie erwarten dass 50 Anwender gleichzeitig arbeiten stellen Sie bitte folgende Werte ein
maxActive=(50 + 10 (fuumlr System und Jobs)) = 60
maxIdle= (50 10) = 5
1 maxActive - maximale Anzahl der gleichzeitigen aktiven Anfragen an die DB
Wenn der Werte maxActive erreicht ist z B wenn mehrere Benutzer gleichzeitig einen Export starten moumlchten welcher laumlngere Zeit in Anspruch nimmt dann kann der Server die Anfrage nicht mehr bedienen und der Anwender wird abgewiesen maxActive hat zudem Auswirkungen auf die im Hintergrund ausgefuumlhrten Jobs maxActive wird daher kalkuliert mit der Anzahl der Anwender und moumlglicher Datenbank-Connections fuumlr Hintergrund-Jobs Jeder aktiv ausgefuumlhrte Job benoumltigt mindestens eine Connection nur selten wird aus Performance-Gruumlnden mehr als eine Connection waumlhrend der Job-Ausfuumlhrung verwendet Im Normalfall sollten daher 10 Connections fuumlr Hintergrundprozesse ausreichend sein
2 maxIdle - Anzahl der offenen Verbindungen auch wenn der Server im Leerlauf ist
Jede offene Verbindung im Leerlauf haumllt auf dem Datenbankserver eine Session offen Auch diese erfordert Ressourcen Wenn die Verbindungen jedoch geschlossen werden kann die Anfragezeit fuumlr eine neue Verbindung steigen da diese Verbindung erst neu ausgehandelt werden muss Die Empfehlung fuumlr den Wert bdquomaxIdleldquo ist ca 10 der Einstellung von maxActive
KeepAlive-Einstellungen fuumlr den Pool
1 validationQuery
Diese wird ausgefuumlhrt um die Verbindung zu DB zu validieren Es MUSS ein Datensatz zuruumlckgegeben werden ansonsten nimmt der DBCP an dass die Abfrage nicht erfolgreich abgesetzt wurde Achten Sie also bitte darauf dass die Abfrage nicht zu leitungsintensiv ist und genau einen Datensatz liefert
Release Notes BALVI Schnittstellenserver Seite 19 von 37
Oracle bietet dafuumlr die virtuelle Tabelle DUAL an welche sich fuumlr die ValidationQuery sehr gut eignet da die Abfrage kaum Ressourcen verbraucht
validationQuery=select 1 from dual
2 testOnBorrow - Boolscher Wert true oder false
Diese Einstellung sorgt dafuumlr dass der Pool die Verfuumlgbarkeit anhand der validationQuery pruumlft bevor
die DB-Verbindung an die Anwendung ausgeliehen wird Empfehlung
testOnBorrow=true
3 testWhileIdle - Boolscher Wert true oder false
Diese Einstellung ist hilfreich wenn zwischen dem Tomcat und der DB eine Firewall mit Stateful
Packet Inspection verwendet wird Nach laumlngerer Inaktivitaumlt wird normalerweise durch die Firewall die
DB-Verbindung geschlossen Dieses loumlst dann beim Ausleihen der Verbindung eine Fehlermeldung im
Protokoll aus 2012-08-16 165418720 WARN [http-0000-8080-8]
[orgspringframeworkjdbcsupportSQLErrorCodesFactory] Error while extracting
database product name - falling back to empty error codes
orgspringframeworkjdbcsupportMetaDataAccessException Error while extracting
DatabaseMetaData nested exception is javasqlSQLRecoverableException Getrennte
Verbindung Um dieses Problem zu beheben sollte die Option testWhileIdle=true eingestellt werden
testWhileIdle=true
Damit diese weiszlig wie oft eine Pruumlfung durchgefuumlhrt werden muss sind jedoch noch zusaumltzliche Angaben erforderlich welche fuumlr die Einstellung der Zeit zusaumltzlich gesetzt werden muumlssen
a) minEvictableIdleTimeMillis - Long in Millisekunden
Min Zeit wie lange eine DB-Verbindung im Leerlauf ist bevor diese zur Pruumlfung
gekennzeichnet wird Dieses haumlngt stark von der Einstellung der Firewall ab Wenn Sie eine
sehr restriktive Firewall haben kann es sein dass diese die Verbindung nach wenigen
Minuten Leerlauf trennt Stellen Sie den Wert immer so ein dass dieser unter der Leerlaufzeit
der Firewall liegt empfohlen 300000 entspricht 300 Sek = 5 min
minEvictableIdleTimeMillis=300000
b) timeBetweenEvictionRunsMillis - Long in Millisekunden
Der Pruumlflauf startet in der Default-Konfiguration alle 1800000 Millisekunden = 30 Min n als
zu Pruumlfen markierte Verbindungen werden in einem Pruumlflauf getestet n wird bestimmt durch
die Einstellung numTestsPerEvictionRun Empfehlung Stellen Sie den Wert auf alle 15 Min
ein
timeBetweenEvictionRunsMillis=900000
Release Notes BALVI Schnittstellenserver Seite 20 von 37
c) numTestsPerEvictionRun - Integer
Wie viele Verbindungen sollen getestet werden waumlhrend der Pruumlflauf ausgefuumlhrt wird Im
Normalfall sollte die Anzahl der zu testenden Verbindungen nicht zu hoch eingestellt werden
Der Default ist 3 Wenn Sie houmlhere Sicherheit haben wollen dass keine bdquototenldquo
Datenbankverbindungen bestehen bleiben erhoumlhen Sie den Wert auf max bdquo(maxActive ndash
maxIdle) 2ldquo Wenn Ihnen 3 ausreichend erscheint muss der Wert nicht gesetzt sein dann
wird der Default verwendet
Beispiel numTestsPerEvictionRun=10
4 Interceptors konfigurieren Neu ergaumlnzt wurde die Moumlglichkeit spezielle bdquoInterceptorsldquo zu konfigurieren die ermoumlglichen das Verhalten des Pools zu steuern Wichtig hierbei ist dass die Angabe von Werten auf real existierende Java-Klassen erfolgt die im Classpath des Tomcat vorhanden sind Groszlig-und-Kleinschreibung ist zu beachten Folgende Default-Einstellung hat BALVI fuumlr den BSS festgelegt jdbcInterceptors=
orgapachetomcatjdbcpoolinterceptorConnectionState
orgapachetomcatjdbcpoolinterceptorStatementFinalizer
orgapachetomcatjdbcpoolinterceptorResetAbandonedTimer
Details zu den verwendeten Interceptor-Einstellungen finden Sie in der Tomcat-Dokumentation3
3 httptomcatapacheorgtomcat-80-docjdbc-poolhtmlJDBC_interceptors
Release Notes BALVI Schnittstellenserver Seite 21 von 37
2512 Datenbank-Zugangsdaten verschluumlsseln
Die Verschluumlsselung fuumlr die Datenbank-Verbindung (bdquoEncrypted Datasourceldquo) ist eine Ableitung der Bibliothek Apache-Common-DBCP-14 und daher nicht mehr mit Java 8 kompatibel Die Einrichtung der Verschluumlsselung wird daher mit der Auslieferung des BSS 30 nicht mehr angeboten
2513 Active-Directory-Authentifizierung
Uumlber die folgenden Parameter wird der Zugriff des Schnittstellen-Servers auf einen Microsoft Active Directory Domain-Controller konfiguriert
ldquoldapServerAddressrdquo
Syntax PROTOKOLLIP-Adresse oder DNS-NamePORT
ltEnvironment
name=ldapServerAddress
value=ldapbl2-dc02balviintern389
type=javalangString
override=true
gt
Als Protokoll besteht auch die Moumlglichkeit ldaps (LDAP+SSL) wenn der Domain-Controller entsprechend konfiguriert wurde Im Java Truststore muss dann das Zertifikat der CA vorhanden sein welche das Zertifikat des Domain-Controllers signiert hat Zudem darf bei ldaps keine IP-Adresse verwendet werden es muss der DNS-Name des Server-Zertifikats eingetragen sein Ansonsten gibt es beim Verbinden eine Sicherheits-Exception
lt-- SSL-Beispiel
ltEnvironment
name=ldapServerAddress
value=ldapsbl2-dc02balviintern636
type=javalangString
override=true
gt
--gt
bdquoldapBaseDnrdquo
LDAP-Suchpfad fuumlr die Domain-Basis Diese muss der LDAP-Syntax fuumlr den Domain-Suffix entsprechen
Syntax DC=SERVERDC=ROOTDN
ltEnvironment
name=ldapBaseDn
value=DC=BALVIDC=INTERN
type=javalangString
override=true
gt
Release Notes BALVI Schnittstellenserver Seite 22 von 37
bdquowebLoginUseActiveDirectoryAuthenticationrdquo
Die Authentifizierung in der Browser-Oberflaumlche kann uumlber die Active-Directory-Authentifizierung erfolgen In der ersten Version ist nur die Protokoll-Auswertung moumlglich wenn der ADMIN sich anmeldet Dieser hat normalerweise niemals AD-Kennungen zugeordnet BALVI empfiehlt diese Einstellung auf bdquofalseldquo zu belassen Webservices welche uumlber SOAPREST zugreifen koumlnnen die Active-Directory-Authentifizierung trotzdem verwenden
ltEnvironment
name=webLoginUseActiveDirectoryAuthentication
value=false
type=javalangBoolean
override=true
gt
ldquoldapDaysBeforeExpirationNotificationrdquo
Die Passwort-Aumlnderung im Active-Directory uumlber die Browser-Oberflaumlche ist in der ersten Version noch nicht implementiert der Parameter wird bislang nicht ausgewertet
ltEnvironment
name=ldapDaysBeforeExpirationNotification
value=14
type=javalangInteger
override=true
gt
2514 Statement-Protokollierung in BALVI iP
Diese Option aktiviert die Lese- und Aumlnderungsprotokollierung fuumlr BALVI iP Standard ist bdquofalseldquo und wird fuumlr alle Kunden empfohlen solange keine speziellen Datenbank-Jobs eingerichtet wurden welche zeitgesteuert die Protokolleintraumlge wieder loumlschen Fuumlr Bayern wurde ein spezielles Konzept zur Leseprotokollierung entworfen Wenn Sie mehr daruumlber erfahren moumlchten kontaktieren Sie bitte die BALVI GmbH
ltEnvironment
name=enableSqlStatementMonitoring
value=true
type=javalangBoolean
override=true
gt
Beachten Sie dass diese Option massive INSERT-Statements in BALVI iP in die Tabelle VIS_D92 ausfuumlhrt Jedes abgesetzte SQL-Statement wird dabei vollstaumlndig protokolliert Dieses erzeugt eine sehr hohe INSERT-Last und in der Folge auch erhoumlhte Redolog-Switches und COMMIT-Transaktionen
Optional Aktivieren der INSERT + APPEND - Logik
Beachten Sie bitte die Hinweise von Oracle zum Hint + APPEND
Release Notes BALVI Schnittstellenserver Seite 23 von 37
Wenn Sie dieses Verhalten aktivieren moumlchten ergaumlnzen Sie bitte den folgenden Environment-Parameter
ltEnvironment
name=statementMonitoringactivateAppendMode
value=true
type=javalangBoolean
override=true
gt
2515 Einstellungen fuumlr BALVI mobil XT (bzw den bdquopartitionedExportldquo)
Diese Logik des FIFO-Buffers wurde so konzipiert dass dem Rechenzentrum diverse Einstellmoumlglichkeiten uumlber die Datei bdquocontextxmlldquo zur Verfuumlgung stehen um die Steuerung des FIFO-Puffers zu beeinflussen
Schematische Darstellung des FIFO-Puffers
Das ermoumlglicht es z B dem BALVI mobil XT Client (14 oder houmlher) den aktiven Block abzuholen und dies beim Fehler bis zu 10-mal zu wiederholen Sobald der Block [001] erfolgreich beim Client angekommen ist und dieser den naumlchsten Block anfragt wird der Block [001] verworfen wird Der Server fuumlllt dann im Hintergrund den frei gewordenen Block wieder waumlhrend der Client den Block [002] abholt
Die Groumlszlige und Anzahl der vorgecachten Bloumlcke kann uumlber die folgenden Einstellungen in der Datei bdquocontextxmlldquo definiert werden
ltEnvironment
name=partitionedExportmaxBufferedPartitions
value=3 type=javalangInteger override=true
gt
ltEnvironment
name=partitionedExportpartitionSize
value=256000 type=javalangInteger override=true
gt
Die Einstellung partitionedExportmaxBufferedPartitions ist dabei die Anzahl der vorgecachten Bloumlcke mindestens muss 2 angegeben werden Der Puffercache wird ausschlieszliglich im RAM der JVM aufgebaut es wird folglich mehr Arbeitsspeicher verwendet Dieser Arbeitsspeicher muss je gleichzeitiger Session auf dem Server bereitgestellt werden die Default-Einstellung mit 3 Partitionen a 256 KB + dem aktiven Puffer erfordern 1 MB RAM je aktiven Anwender
Aktiv
er
Puffe
r
[001] Vorg
ecac
hter
Bl
ock
[002] Vorg
ecac
hter
Bl
ock
[003]
Aktiv
er P
uffe
r
[002] Vorg
ecac
hter
Bl
ock
[003] Vorg
ecac
hter
Bl
ock
[leer]
Release Notes BALVI Schnittstellenserver Seite 24 von 37
Gleichzeitig wurde die Moumlglichkeit geschaffen dass die maximale Anzahl an gleichzeitigen Exporten durch das Rechenzentrum eingeschraumlnkt werden kann um einem OutOfMemory-Fehler vorzubeugen Die Einstellung
ltEnvironment
name=partitionedExportmaxConcurrentExports
value=10 type=javalangInteger override=true
gt
muss entsprechend der zu erwartenden gleichzeitigen Zugriffe konzipiert werden ansonsten wird der Server einen Verbindungsversuch durch die Clients ablehnen
Beachten Sie dass die folgenden Einstellungen partitionedExportmaxBufferedPartitions partitionedExportmaxConcurrentExports und partitionedExportpartitionSize gemeinsam als Rechenbasis fuumlr den RAM-Bedarf des Webservers herangezogen werden muumlssen
Folgende Faustformel sollte fuumlr die Einrichtung verwendet werden
Min 256 MB (Serverbasis) + (11 partitionedExportmaxConcurrentExports partitionedExportmaxBufferedPartitions partitionedExportpartitionSize)
Beispiel 50 gleichzeitige Anwender Blockgroumlszlige 256 KB 4 Partitionen
256 MB + (11 50 256 4) KB = 312 MB fuumlr die JVM
Empf 512 MB (Serverbasis) + (12 partitionedExportmaxConcurrentExports partitionedExportmaxBufferedPartitions partitionedExportpartitionSize)
Beispiel 50 gleichzeitige Anwender Blockgroumlszlige 256 KB 4 Partitionen
512 MB + (12 50 256 4) KB = 572 MB fuumlr die JVM
partitionedExportmaxConcurrentExports
Bestimmt die Anzahl der maximalen Export Tasks (Threads) die fuumlr partitionierte Exporte bereitgestellt werden Wenn die Anzahl uumlberschritten wird wird die entsprechende Exportanfrage abgewiesen und der Client muss zu einem spaumlteren Zeitpunkt erneut anfragen Stellen Sie diesen Wert entsprechend der zu erwartenden Benutzeranzahl ein bei 50 Anwendern also 50
Exporte oumlffnen auf der Datenbank entsprechend zur Ausfuumlhrungszeit min einen Cursor ggf fuumlr rekursive Unterabfragen kurzfristig sogar mehr Die hier eingestellte Anzahl muss mit der Anzahl von maxActive korrelieren
ltEnvironment
name=partitionedExportmaxConcurrentExports
value=10 type=javalangInteger override=true
gt
partitionedExportmaxBufferedPartitions
Bestimmt die Anzahl der Datenbloumlcke (Partitionen) die vom Server bei Abruf eines Exportes gepuffert werden Die seit Version 24 eingefuumlhrte FIFO-Puffer-Logik ermoumlglicht dass der Server schon die Ergebnisse vorpuffert so dass der Client weniger Wartezeiten bei der Anfrage nach Daten hat Diese
Release Notes BALVI Schnittstellenserver Seite 25 von 37
Puffer-Logik unterteilt den Exportdatenstrom (je Export) in mehre Bloumlcke Der Client kann nun den letzten Block neu anfordern oder den naumlchsten Block wenn der letzte Block erfolgreich verarbeitet wurde Wie viele naumlchste Bloumlcke durch den Server bereit gestellt werden entscheidet diese Einstellung Sobald kein naumlchster Block mehr bereit gestellt werden muss wird der Datenbank-Cursor geschlossen eine Erhoumlhung kann also zu einer Entlastung der aktiven DB-Verbindungen fuumlhren erhoumlht jedoch den Bedarf an RAM des Servers
Der von BALVI voreingestellte Wert ist 3
ltEnvironment
name=partitionedExportmaxBufferedPartitions
value=3 type=javalangInteger override=true
gt
partitionedExportpartitionSizeldquo
Die Groumlszlige der Datenbloumlcke (Partitionen) die an den Client uumlbermittelt werden in Bytes Wenn Sie diesen Wert zu niedrig einstellen reduziert sich die Effizienz des Caches da der Client mehr Datenbloumlcke hintereinander abrufen muss Waumlhlen Sie einen zu groszligen Wert wird die neu zu uumlbertragende Datenmenge im Fall eines Fehlers houmlher
Der von BALVI voreingestellte Wert ist 256000 (256 KB)
ltEnvironment
name=partitionedExportpartitionSize
value=256000 type=javalangInteger override=true
gt
exportTokensmaxTokenCount
Maximale Anzahl der gleichzeitig vergebenen Token die vom Server gecached werden Jede Sitzung welche einen Export durchfuumlhrt erhaumllt einen Session-Token
Wenn eine Sitzung laumlngere Zeit nicht verwendet wurde wird dieser Session-Token wieder entfernt Wenn Sie den Wert zu niedrig einstellen fuumlhrt das zu einer generellen Session-Begrenzung auch fuumlr den nicht partitionierten Export-Modus welcher ab Version 21 verfuumlgbar ist
Ist die Anzahl der Tokens houmlher als die Datenbankeinstellung maxActive kann es vorkommen dass zwar eine Session gestartet werden kann jedoch kein Datenexport zustande kommt
Der von BALVI voreingestellte Wert ist 2000
ltEnvironment
name=exportTokensmaxTokenCount
value=20 type=javalangInteger override=true
gt
exportTokenstokenExpirationInSeconds
Zeit in Sekunden die verstreichen muss bis ein Token unguumlltig wird falls darauf kein Zugriff mehr erfolgt Nach einem erfolgreichen Export wird der Token automatisch geschlossen diese Option ist fuumlr den Abbruchfall vorgesehen Der von BALVI voreingestellte Wert ist 180 (180 s = 3 min)
Release Notes BALVI Schnittstellenserver Seite 26 von 37
ltEnvironment
name=exportTokenstokenExpirationInSeconds
value=180 type=javalangInteger override=true
gt
exportTokenstokenDisposalInSeconds
Zeit in Sekunden die verstreichen muss bis ein Token das erfolgreich abgearbeitet wurde aus dem Cache geloumlscht wird Um sicher zu stellen dass der letzte Exportblock noch erfolgreich abgerufen werden kann bleibt der Token auch nach Fertigmeldung des Clients noch N Sek guumlltig
Der von BALVI voreingestellte Wert ist 60 (60 s = 1 min)
ltEnvironment
name=exportTokenstokenDisposalInSeconds
value=60 type=javalangInteger override=true
gt
2516 Job-Verwaltung fuumlr den BSS konfigurieren Aktivierung der Jobverwaltung
Bis zur Version 28 des BSS gab es den Parameter bdquoavailableServicesldquo Dieser konnte bei Bedarf aktiviert werden wenn die Jobs benoumltigt wurden
Mit Version 30 ist die Einstellung bdquoavailableServicesldquo zu entfernen und kann durch den neuen optionalen Parameter bdquoisJobServiceEnabledldquo in der Datei bdquocontextxmlldquo ersetzt werden
lt-- Neue Parameter zur Aktivierung des Job Service Ersatz fuumlr availableServices --gt
ltEnvironment
name=isJobServiceEnabled
value=true
type=javalangBoolean
override=true
gt
Ab BSS 30 wird die Jobs-Engine standardmaumlszligig aktiviert Sollte die Jobs-Engine nicht benoumltigt werden muss bdquovalueldquo der Wert bdquofalseldquo zugewiesen werden Wird bdquoisJobServiceEnabledldquo nicht eingefuumlgt sind die Jobs trotzdem standardmaumlszligig aktiv
Nach dem Neustart des Servers und erneutem Einloggen erscheint nun zusaumltzlich der Menuumlpunkt bdquoJobsldquo
bdquopasswordKeyldquo fuumlr Jobs
In der Job-Logik wird ein von BALVI definierter Standard-Schluumlssel fuumlr die Ablagen von schuumltzenswerten Daten z B Passwoumlrtern verwendet Diese Einstellung ermoumlglicht den BALVI-Standard zu uumlberschreiben Wenn Sie diese Einstellung aumlndern muumlssen jedoch alle bislang verschluumlsselten Job-Parameter neu verschluumlsselt werden
ltEnvironment
name=javacompenvjobspasswordKey
value=MeinHochsicheresNeuesPasswort
type=javalangString
Release Notes BALVI Schnittstellenserver Seite 27 von 37
override=true
gt
bdquoJob ID enableddisabledldquo (Deprecated ersetzt ab 28 durch das bdquoBindenldquo von Jobs)
Sondereinstellungen fuumlr die Job-Verwaltung Da alle Jobs in einer Datenbank administriert werden jedoch ggf verteilt auf mehreren Tomcat-Servern ausgefuumlhrt werden sollen besteht hier die Option Jobs fuumlr die aktuelle Tomcat-Instanz separat zu deaktivieren
Die Einstellung ID koumlnnte z B folgendermaszligen aussehen javacompenvjobsC0DB58D8D52C4BBC966D1DC788A4EF8Benabled
Fuumlr weitere Fragen zu dieser Einstellung kontaktieren Sie bitte die BALVI GmbH
ltEnvironment
name=javacompenvjobsIDenabled
value=false
type=javalangBoolean
override=true
gt
2517 Weitere optionale Parameter
Es ist fuumlr diverse einzelne Schnittstellen ggf erforderlich Einstellungen in der Datei bdquocontextxmlldquo zu ergaumlnzen Hinweise zu diesen Parametern sind dann in dem der Schnittstelle beiliegenden Dokument enthalten Das gilt z B fuumlr die Schnittstelle bdquoXGewerbeanzeigenldquo
26 Logging mit logback Das Logging wurde komplett uumlberarbeitet Statt bdquoLog4Jldquo wird jetzt bdquologbackldquo4 benutzt Ab BSS 30 ist es zwingend notwendig die Einstellung vorzunehmen um das Logging der Anwendung zu steuern
Migration Ergaumlnzen Sie die neue Einstellung bdquologgingconfigldquo
lt-- Neue Paramter zur Angabe der Logback Config Ersatz fuumlr log4jConfigLocation --gt
ltEnvironment
name=loggingconfig
value=$catalinabaseconflogback-bssxml
type=javalangString
override=true
gt
Nach wie vor steht es Ihnen frei die Logging-Konfiguration eigenstaumlndig anzupassen
Wenn Sie jedoch dieselbe WAR in einer Tomcat-Instanz unter mehreren Context-Namen betreiben wuumlrden beide dieselbe Logging-Konfiguration verwenden so dass alle Protokolleintraumlge in einer Log-Datei aus
4 httplogbackqoschmanualappendershtml
Release Notes BALVI Schnittstellenserver Seite 28 von 37
mehreren Webanwendungen generiert werden Aumlndern Sie den Namen der Logging-Konfiguration entsprechend ab um fuumlr jede Anwendung eine spezifische Logging-Einstellung vornehmen zu koumlnnen
27 Tocmat Optional Suche im bdquoKlassenpfadldquo um den
Ordner bdquoconfldquo erweitern Die Suche nach Dateien uumlber bdquoclasspathldquo setzt voraus dass die Ordner- und Dateinamen im Apache Tomcat bekannt gegeben werden Der Klassenpfad kann in der Datei bdquocatalinapropertiesldquo angepasst werden Wenn Sie dort unter commonloader die folgenden Werte ergaumlnzen kann eine Datei auch im Ordner conf abgelegt werden damit Apache Tomcat diese findet Ansonsten muss die Datei im Ordner lib abgelegt werden
commonloader=$catalinabaseconf$catalinahomeconf
3 Die neue Browser-Oberflaumlche Der BALVI Schnittstellenserver hat seit Version 25 neben der Protokollierung auch die Moumlglichkeit Job-Konfigurationen zu pflegen Der Login ist nur fuumlr einen in BALVI iP eingetragenen ADMIN (z B Benutzer bdquoSYSTEMADMINldquo) mit dem in BALVI iP hinterlegten Passwort moumlglich Zur Anmeldung muss immer [SYSTEMBenutzername] im Feld Benutzer angegeben werden ansonsten schlaumlgt die Anmeldung fehl Bitte achten Sie darauf dass der bdquoldquo (Slash) und nicht der bdquoldquo (Backslash) verwendet werden muss
31 Server-Protokoll Um das Server-Protokoll anzuzeigen waumlhlen Sie den entsprechenden Menuumlpunkt Dort haben Sie seit BSS 26 die Moumlglichkeit uumlber alle Spalten der Protokolle nach Informationen zu suchen
Seit BSS 31 gibt es die Moumlglichkeit Verfahren in bdquoKopfsaumltzeldquo und bdquoDetailsaumltzeldquo zu unterteilen Wurde das Verfahren entsprechend konfiguriert (wie z B bei der Schnittstelle bdquoXGewerbeanzeigenldquo) dann wird im Protokoll-Kopfsatz nur der Start und das Ende der Ausfuumlhrung in der Liste angezeigt Erst bei einem Klick auf bdquoInformationenldquo wird die Liste aller Detailsaumltze angezeigt die im Durchlauf erzeugt wurden
Release Notes BALVI Schnittstellenserver Seite 29 von 37
Verfahren
Die Liste der verfuumlgbaren Verfahren die bei Ihnen im System installiert sind ZB
BEFUNDEhellip Schnittstelle Befunde LM FM oder TS
PROBEhellip Schnittstelle zum Export von Proben an Labore ebenfalls Spezifisch fuumlr einzelne Fachbereiche
MOBILXT Protokolle der BALVI Mobil XT Synchronisation
WEB Allgemeine nicht spezifizierte Protokolle hierunter ist bislang auch die eFi-Protokollierung zu finden
WEB_I0802 Protokolle zur Schnittstelle BALVI iP LIMS (Lebensmittelproben)
XGEWERBE Schnittstelle XGewerbeanzeigen
Klicken Sie auf die Schaltflaumlche so besteht bei den neuen Protokolldatensaumltzen die Moumlglichkeit Detail-Informationen zum Protokollsatz zu erhalten
Release Notes BALVI Schnittstellenserver Seite 30 von 37
Seit BSS 30x ist die Anzeige der Protokolle ebenfalls farblich abgesetzt so dass Protokolleintraumlge mit Fehlern hellrot und Warnungen hellgelb hinterlegt werden
32 Jobs Mit einem Klick auf den Menuumlpunkt Jobs rufen Sie die Oberflaumlche fuumlr die Job-Konfiguration auf Daraufhin werden alle Jobs aufgelistet die fuumlr den BSS freigegeben sind Hier koumlnnen Sie Einstellungen an den Jobs vornehmen und die Jobs aktivieren bzw deaktivieren Die Beschreibungen bzw Einstellungsmoumlglichkeiten fuumlr den jeweiligen SST-Job sind nicht Bestandteil dieser Dokumentation
33 Log-Ausgaben Uumlber den Menuumlpunkt Log-Ausgaben koumlnnen Sie die Ausgabe der Protokolleintraumlge in Echtzeit beobachten
Release Notes BALVI Schnittstellenserver Seite 31 von 37
Starten Sie die Echtzeit-Protokollierung indem Sie auf die Schaltflaumlche mit dem Symbol bdquoPlayldquo (Dreieck) klicken unterbrechen Sie die Ausgabe indem Sie die auf Schaltflaumlche mit dem Symbol bdquoPauseldquo (zwei Balken) klicken
Klicken Sie auf die Schaltflaumlche bdquoAktualisierenldquo (zwei Pfeile) um die neuesten Protokolleintraumlge angezeigt zu bekommen
Klicken Sie auf das Symbol mit dem Papierkorb um die letzten Protokollmeldungen in der Anzeige zu loumlschen
Die Daten in den Protokolldateien auf der Festplatte des Servers sind davon nicht betroffen
Uumlber das Symbol bdquoLogging anpassenldquo (Schraubenschluumlssel) koumlnnen Sie die Ausgabe der Daten im Echtzeitfenster und in den Protokolldateien aumlndern jedoch ist diese Einstellung nur temporaumlr Die Standardeinstellungen koumlnnen ausschlieszliglich uumlber die Anpassung der Datei bdquologback-bssxmlldquo im Konfigurationsverzeichnis des Servers selbst geaumlndert werden
Release Notes BALVI Schnittstellenserver Seite 32 von 37
In der Logging-Parameter Konfiguration koumlnnen Sie verschiedene Parameter einstellen und uumlber die Schaltflaumlche bdquoAnwendenldquo dann sofort im Echtzeitprotokoll sehen Welche Einstellungen moumlglich sind erfahren Sie wenn es eine akute Fehlersituation gibt die detailliertere Ausgaben im Protokoll erfordert
Warnung Wenn Sie den Log-Level fuumlr ROOT oder eine andere Klasse auf TRACE einstellen werden sehr viele Protokollausgaben generiert die auch dazu fuumlhren koumlnnen dass der Server sehr langsam wird oder die Festplatte des Servers zulaumluft wenn fuumlr das Logging kein Dateilimit konfiguriert wurde
34 LogoutAbmeldung vom System Zum Abmelden waumlhlen Sie oben rechts das Kontextmenuuml
35 Cache loumlschen Der Cache wird in der Regel automatisch geloumlscht Wenn Sie jedoch gerade in BALVI iP eine Aumlnderung an den Schnittstellen eingespielt haben und moumlchten dass diese sofort wirksam wird kann die Funktion bdquoCache loumlschenldquo dazu verwendet werden dass der BALVI Schnittstellenserver die Einstellungen bei der naumlchsten Anfrage neu einliest
Release Notes BALVI Schnittstellenserver Seite 33 von 37
Release Notes BALVI Schnittstellenserver Seite 34 von 37
4 Einrichtung in BALVI iP Um die Verfahren fuumlr den BALVI Schnittstellenserver fuumlr Anwender freizuschalten wird das Objekt bdquoSystemeinstellungenldquo oder bdquoMandanten- und Benutzereinstellungenldquo verwendet Die Anpassung ist je Verfahren moumlglich so kann in BALVI iP fuumlr den Zugriff durch den BALVI Schnittstellenserver ein Benutzer bdquoAldquo am Verfahren bdquoMobilldquo berechtigt werden ein Benutzer bdquoBldquo nur am Verfahren bdquoSLA_FLESHldquo usw Die Logik ist jedoch einheitlich Je Verfahren wird durch BALVI eine Verfahrensgruppe mit dem Verfahrensnamen angelegt und mit den entsprechenden Einstellungen vorkonfiguriert welche durch das Verfahren erforderlich sind Dabei kann die Komplexitaumlt der Einstellungen variieren wie z B an den zu Version 23 verfuumlgbaren Verfahren bdquoMobilldquo und bdquoSLA_Fleshldquo ersichtlich wird
Im Verfahren BALVI Mobil sind diverse Anpassungen moumlglich welche je Bundesland oder eingesetzter Import- und Export-Variante durch den BALVI Schnittstellenserver bei der Bearbeitung von Anfragen gepruumlft werden siehe Punkt 3 Abb Mobil-Einstellung in BALVI iP
Abb Mobil-Einstellung in BALVI iP
Alle Verfahren verwenden jedoch die regulaumlre Benutzerverwaltung von BALVI iP Ein Benutzer ohne Passwort gilt fuumlr BALVI iP als gesperrt was fuumlr das Login bedeutet dass der Anwender sich nur uumlber die Active-Directory-Authentifizierung anmelden kann Ist das nicht moumlglich (bzw nicht konfiguriert) kann der Anwender sich weder in BALVI iP noch uumlber die Webservice-Schnittstelle authentifizieren
Fuumlr Dienste-Schnittstellen welche keine persoumlnliche Authentifizierung durch einen Anwender erfordern wird empfohlen einen separaten Benutzer in der Benutzerverwaltung anzulegen und ein sicheres Kennwort zu vergeben Das Anlegen von zusaumltzlichen Benutzern gilt nicht fuumlr BALVI mobil XT da beim Holen und Uumlbermitteln von Daten jeder Benutzer auch ein fachlich konfigurierter Anwender innerhalb von BALVI iP ist und die Anwendungsoberflaumlche ebenfalls zur Erfassung von Daten verwendet
Unter Punkt 2 der Abb Mobil-Einstellung in BALVI iP wird ein modales Fenster geoumlffnet (Abb BALVI mobil Benutzerverwaltung) Innerhalb dieses modalen Fensters werden mandantenweise die Benutzer fuumlr BALVI
Release Notes BALVI Schnittstellenserver Seite 35 von 37
mobil und den jeweiligen Fachbereich festgelegt Dabei ist es wichtig dass man die Haken bdquoAktiv fuumlr hellipldquo bei bdquohellip mobilldquo und bei einem Fachbereich (bdquohellip LMldquo bdquohellip FMldquo usw) setzt weil sonst uumlber den BALVI Schnittstellenserver keine Kommunikation mit BALVI iP moumlglich ist
Abb BALVI mobil Benutzerverwaltung
Alternativ zur Passwort-Authentifizierung wird wie beschrieben auch die Active-Directory-Authentifizierung angeboten Dazu muss der BALVI iP-Anwender uumlber die Schaltflaumlche bdquoDomaumlnen-Benutzer zuordnenldquo mit dem Active Directory verknuumlpft werden
Nur wenn die Active-Directory-Konfigurationen in BALVI iP und im BALVI Schnittstellenserver auf dieselbe Domaumlne verweisen sind die Domaumlnen-Zuordnung und die Active-Directory-Authentifizierung (z B uumlber BALVI mobil XT) moumlglich
Release Notes BALVI Schnittstellenserver Seite 36 von 37
5 Bekannte Probleme und Loumlsungen
51 ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner Bei der Job-Bearbeitung tritt folgender Fehler auf ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner
Behebung
Fuumlhren Sie das beiliegende IP-Patch (UPDATEexe) aus bevor Sie das WAR austauschen
52 Server startet nicht Sie finden folgende Zeilen im Protokoll (catalinaout oder bsslog)
ERROR [localhost-startStop-1] [IdentityServiceImpl] serverID must not be empty
ERROR [localhost-startStop-1] [ContextLoader] Context initialization failed
Behebung
Setzen Sie die Umgebungsvariable ldquoserverIDrdquo in der Datei bdquocontextxmlldquo
53 ORA-00942 table or view does not exist In vielen Faumlllen wird der Fehler ldquoTabelle oder View nicht vorhandenrdquo ausgeworfen (Java-Protokoll im Ordner logs von Apache Tomcat) wenn eine neue Schnittstelle eingerichtet oder ein neues BALVI iP Release bzw Update eingespielt wurde ohne anschlieszligend das aktuelle GRANT-Skript auszufuumlhren
Behebung
Fuumlhren Sie das GRANT-Skript erneut aus
54 ORA-0406x bdquoBestehender Paketstatus wurde aufgehobenldquo
ORA-04061 Bestehender Status von package body ABCXYZ wurde annulliert
ORA-04065 Ausfuumlhrung nicht erfolgreich package body ABCXYZ wurde geaumlndert oder geloumlscht
Release Notes BALVI Schnittstellenserver Seite 37 von 37
Der Fehler tritt haumlufig ein nachdem die UPDATEexe ausgefuumlhrt und in der Ausfuumlhrungsliste ein Package aktualisiert wurde Oracle merkt sich je User-Session bestimmte Werte im Package wenn der Anwender es verwendet hat Durch einen bdquoCREATE OR REPLACE PACKAGEldquo-Befehl kann dieser Status temporaumlr aufgehoben werden Normalerweise tritt dieser Fehler nach dem Update genau einmal in jeder aktiven Session auf wenn der BSS nicht neu gestartet wird
Behebung
Starten Sie nach jedem Update den BSS neu um alle laufenden Sessions zu beenden
55 Jobs sind nicht ausfuumlhrbar
1 Ein Job wird mit dem Status bdquoNicht unterstuumltztldquo angezeigt wenn fuumlr seine Ausfuumlhrung eine houmlhere Version des BSS erforderlich ist
2 Nach dem Klonen der Datenbank von der Produktions- auf die Testumgebung erhalten alle Jobs automatisch den Status bdquoDeaktiviertldquo wenn die bdquoserverIDldquo nicht identisch ist
Beide Statusaumlnderungen sind gewollt Damit soll verhindert werden dass Jobs nach einem Serverneustart oder nach einem Update automatisch starten und dabei Fehler verursachen
Um Jobs mit dem Status bdquoNicht unterstuumltztldquo nutzen und konfigurieren zu koumlnnen ist es erforderlich den BALVI Schnittstellenserver zu aktualisieren
Deaktivierte Jobs koumlnnen Sie aktivieren indem Sie den jeweiligen Job an den aktuellen Server binden und den Haken bei bdquoAktivldquo setzen
Release Notes BALVI Schnittstellenserver Seite 15 von 37
Neu ab Grant-Skript 158 ist die Umbenennung der Verfahrenszuordnung
Pruumlfen Sie dass die Einstellung fuumlr Ihr BundeslandVerfahren korrekt ist dort muss eine 1 fuumlr min ein Verfahren gesetzt sein Diese Einstellung befindet sich direkt unter den Schemabesitzer-Angaben
-- Verfahrensbezogene Konfiguration
-- Setzen Sie fuumlr das jeweilige Verfahren eine 1
-- BALVI Schnittstellenserver (BSS)
-- bis V266 auch BALVI Kommunikationsserver (BKS) genannt
-- generell fuumlr die meisten Verfahren guumlltig
-- Ab Version 57 entfaumlllt mit der Einfuumlhrung der
-- Schnittstelle XGewerbeanzeigen auch der separate Schalter
-- WS_BTR beide Verfahren wurden vereinheitlicht
WS_BSS = 1
Fuumlhren Sie das Skript nach der Anpassung als User SYSTEM aus um die Grants durchzufuumlhren Dieses wurde mit dem von ORACLE gelieferten Programm SQLPLUS (Command-Line) SQLPLUS Worksheet (GUI) und Oracle SQL-Developer getestet
Das Skript generiert fuumlr jedes Objekt ein SYNONYM fuumlr den WEB-USER so dass dieser auf die Objekte ohne Angabe des Owners des IP-Schemas zugreifen kann Pruumlfen Sie nach der Ausfuumlhrung dass die SYNONYMS vorhanden und VALID sind dieses kann ggf nicht der Fall sein Das Skript kann jederzeit erneut ausgefuumlhrt werden um die Grants neu zu erzeugen und bietet ebenfalls die Option alle Grants und Synonyme wieder zu entfernen Detaillierte Informationen zur Nutzung des Skripts sind als Kommentar-Block im Skript enthalten
Hinweis Die Versionsinformation ist unter den Kommentaren direkt im Skript zu finden
Zugriffsberechtigungen fuumlr Webanwendungen auf BALVI iP anlegen
===============================================================
Version 158
Guumlltig fuumlr BALVI iP 123 oder houmlher
Autor Frank Holler
SVN Revisionsinformationen
$Revision 479 $
$Date 2016-02-15 152755 +0100 (Mo 15 Feb 2016) $
================================================================
243 Wann ist die Ausfuumlhrung des Grant-Skripts erforderlich Durch das Strukturupdate von BALVI iP (z B 1240 auf 1241) werden veraltete Strukturen geloumlscht und ggf neue Views oder Tabellen angelegt Die Grant-Rechte geht dabei ggf verloren Daher ist die Ausfuumlhrung des Grant-Skripts immer dann erforderlich wenn sich die Datenbank-Struktur von BALVI iP veraumlndert
Zudem kann es fachliche Neuerungen geben welche im alten Grant-Skript nicht vorhanden sind Daher muss das Skript ggf auch ausgefuumlhrt werden wenn eine neue Schnittstelle im Schnittstellenserver bereitgestellt wurde Dieses betrifft z B auch die Bereitstellung von neuen Versionen von BALVI mobil XT
Release Notes BALVI Schnittstellenserver Seite 16 von 37
da auch dort mit einem fachlich erweiterten Client die Moumlglichkeit besteht dass neue Schnittstellen bereitgestellt und somit mehr Schreibrechte auf Tabellen benoumltigt werden
244 Welche Version des Grant-Skripts soll ich nehmen Wie der Schnittstellenserver sind auch die Grant-Skripte versioniert Neuere Versionen des Grant-Skriptes sind abwaumlrts-kompatibel und koumlnnen immer verwendet werden auch wenn in einer Schnittstellenbeschreibung eine aumlltere Version des Grant-Skriptes explizit benannt wurde
245 Kombination von mehreren Verfahren Wenn Sie zwei oder mehr Schnittstellen im BSS verwenden moumlchten ist es ggf erforderlich auch mehrere Verfahren auf aktiv (bdquo1ldquo) zu setzen
Im Beispiel nehmen wir an Sie moumlchten bdquoeFildquo und bdquoBALVI mobil XTldquo im Schnittstellenserver bereitstellen In der Beschreibung von bdquoeFildquo steht dass das Grant-Skript V36 erforderlich ist BALVI mobil XT 18 erfordert jedoch schon V56
Wenn Sie beide Verfahren betreiben ist im Grant-Skript (V56 oder houmlher) die Einstellung fuumlr beide Verfahren zu aktivieren
====================================================
DEKLARATIVER TEIL MUSS vom KUNDEN geaumlndert
bzw auf die korrekten SCHEMA-Namen angepasst
werden
Die USER-Namen muumlssen in Groszligbuchstaben
geschrieben sein sonst werden sie nicht
gefunden
====================================================
sUserBALVI_IP = BALVI_IP_SCHEMA
sUserBALVI_WEB = WEBAPP_SCHEMA
-- Verfahrensbezogene Konfiguration
-- Setzen Sie fuumlr das jeweilige Verfahren eine 1
-- BALVI Schnittstellenserver (BSS)
-- bis V266 auch BALVI Kommunikationsserver (BKS) genannt
-- generell fuumlr die meisten Verfahren guumlltig
-- Ab Version 57 entfaumlllt mit der Einfuumlhrung der
-- Schnittstelle XGewerbeanzeigen auch der separate Schalter
-- WS_BTR beide Verfahren wurden vereinheitlicht
WS_BSS = 1
-- WebService BTR (Betriebsstaumlttenregister) (NRW TH)
-- entfernt mit Update V57 setzen Sie stattdessen bei WS_BSS = 1
--WS_BTR = 0
-- Probenahme Futtermittel im Browser(BY)
WS_PROBE_FM = 0
-- Risikoorientierte Probenplanung Futtermittel ndash RIOPP FM (BY)
WS_RIOPP_FM = 0
-- Verfahren Export an EFi (Status Pilotbetrieb)
WS_EFI = 1
-- neu ab Version 35 des Grant-Skriptes ist die Moumlglichkeit den Webuser
Release Notes BALVI Schnittstellenserver Seite 17 von 37
-- fuumlr das Loumlschen der Ausgangskoumlrbe explizit zu berechtigen bzw sogar einen
-- expliziten abweichenden User festzulegen Die Konfiguration in der
-- Job-Oberflaumlche sieht vor dass man die Oracle-Datenbank-Zugangsdaten fuumlr
-- das Loumlschen einstellen muss Hier muss im Normalfall derselbe Oracle
-- Datenbankbenutzer eingetragen werden wie in der Tomcat-Verbindungs-
-- konfiguration In diesem Fall sollte wenn WS_EFI = 1 eingestellt wurde
-- ebenfalls WS_EFI_DELETE = 1 eingestellt werden
-- Alternativen
-- 1) Datenbankbenutzer aumlndern
-- Wenn bei sUserEFI_TRUNC anstatt sUserBALVI_WEB (Standard) ein anderer
-- Oracle-Benutzername angegeben wird wird das Loumlschrecht fuumlr die EFi
-- Ausgangskoumlrbe Datenbankseitig exklusiv dem angegeben Datenbankbenutzer
-- zugewiesen
-- 2) Loumlschrecht verweigern
-- Setzen Sie die Variablen WS_EFI_DELETE = 0 damit kein Loumlschrecht
-- zugeweisen wird
WS_EFI_DELETE = 0
-- Beispiel Anderer Benutzer muss in der Datenbank existieren
-- Entfernen Sie die fuumlhrenden -- vor der Variable sUserEFI_TRUNC und
-- setzen den entsprechenden Oracle-Benutzer ein
--sUserEFI_TRUNC = TEST_EFI_TRUNC
hellip
25 Konfiguration des Schnittstellen-Servers
251 Die bdquocontextxmlldquo-Parameter Die von der Servlet-Spezifikation vorgegeben Rump-Struktur sieht folgendermaszligen aus
ltxml version=10 encoding=utf-8gt
ltDOCTYPE Contextgt
ltContextgt
lt-- Kundenspezifische Einstellungen --gt
ltContextgt
Anwendungsspezifische Einstellungen werden zwischen ltContextgt und ltContextgt eingefuumlgt Alle allgemeinguumlltigen Einstellungen in der Datei bdquocontextxmlldquo werden hier erlaumlutert Kommentare finden sich auch in der von BALVI ausgelieferten Beispiel-Konfiguration
Neben den im Folgenden beschriebenen Standard-Einstellungen kann es auch vorkommen dass bundeslandspezifische Erweiterungen vorhanden sind welche nicht in dieser Dokumentation aufgefuumlhrt werden Diese funktionieren trotzdem regulaumlr weiter wenn keine expliziten Informationen zu Kompatibilitaumltsproblemen in den Release-Notes aufgefuumlhrt wurden
2511 Datenbankverbindung jdbcDataSource
Die Datenbankverbindung wird uumlber die von DBCP und dem Oracle-Treiber vorgegebenen Moumlglichkeiten realisiert Der Einsatz der orgapachetomcatjdbcpoolDataSourceFactory (automatisch verfuumlgbar ab Apache Tomcat 7 in der mitgelieferten tomcat-dbcpjar) wird als Beispiel-Konfiguration ausgeliefert
ltResource
name=jdbcDataSource
auth=Container
Release Notes BALVI Schnittstellenserver Seite 18 von 37
type=javaxsqlDataSource
factory=orgapachetomcatjdbcpoolDataSourceFactory
maxActive=10 initialSize=3
maxIdle=5
maxWait=10000
url=jdbcoraclethinBL2-ORA10-KUNDENBALVIINTERN1521ORCL
driverClassName=oraclejdbcdriverOracleDriver
username=balvi_webservice_schema
password=balvi_webservice_password
description=Oracle Datasource
maxOpenPreparedStatements=50
removeAbandoned=false
removeAbandonedTimeout=100
logAbandoned=true
jdbcInterceptors=hellip
gt
Hinweise zur Einstellung der jdbcDataSource
Standard-Einstellungen fuumlr den Datenbank-Verbindungspool
Der Verbindungspool muss entsprechend der Anzahl der zu erwartenden gleichzeitigen Benutzer konfiguriert werden Wenn Sie erwarten dass 50 Anwender gleichzeitig arbeiten stellen Sie bitte folgende Werte ein
maxActive=(50 + 10 (fuumlr System und Jobs)) = 60
maxIdle= (50 10) = 5
1 maxActive - maximale Anzahl der gleichzeitigen aktiven Anfragen an die DB
Wenn der Werte maxActive erreicht ist z B wenn mehrere Benutzer gleichzeitig einen Export starten moumlchten welcher laumlngere Zeit in Anspruch nimmt dann kann der Server die Anfrage nicht mehr bedienen und der Anwender wird abgewiesen maxActive hat zudem Auswirkungen auf die im Hintergrund ausgefuumlhrten Jobs maxActive wird daher kalkuliert mit der Anzahl der Anwender und moumlglicher Datenbank-Connections fuumlr Hintergrund-Jobs Jeder aktiv ausgefuumlhrte Job benoumltigt mindestens eine Connection nur selten wird aus Performance-Gruumlnden mehr als eine Connection waumlhrend der Job-Ausfuumlhrung verwendet Im Normalfall sollten daher 10 Connections fuumlr Hintergrundprozesse ausreichend sein
2 maxIdle - Anzahl der offenen Verbindungen auch wenn der Server im Leerlauf ist
Jede offene Verbindung im Leerlauf haumllt auf dem Datenbankserver eine Session offen Auch diese erfordert Ressourcen Wenn die Verbindungen jedoch geschlossen werden kann die Anfragezeit fuumlr eine neue Verbindung steigen da diese Verbindung erst neu ausgehandelt werden muss Die Empfehlung fuumlr den Wert bdquomaxIdleldquo ist ca 10 der Einstellung von maxActive
KeepAlive-Einstellungen fuumlr den Pool
1 validationQuery
Diese wird ausgefuumlhrt um die Verbindung zu DB zu validieren Es MUSS ein Datensatz zuruumlckgegeben werden ansonsten nimmt der DBCP an dass die Abfrage nicht erfolgreich abgesetzt wurde Achten Sie also bitte darauf dass die Abfrage nicht zu leitungsintensiv ist und genau einen Datensatz liefert
Release Notes BALVI Schnittstellenserver Seite 19 von 37
Oracle bietet dafuumlr die virtuelle Tabelle DUAL an welche sich fuumlr die ValidationQuery sehr gut eignet da die Abfrage kaum Ressourcen verbraucht
validationQuery=select 1 from dual
2 testOnBorrow - Boolscher Wert true oder false
Diese Einstellung sorgt dafuumlr dass der Pool die Verfuumlgbarkeit anhand der validationQuery pruumlft bevor
die DB-Verbindung an die Anwendung ausgeliehen wird Empfehlung
testOnBorrow=true
3 testWhileIdle - Boolscher Wert true oder false
Diese Einstellung ist hilfreich wenn zwischen dem Tomcat und der DB eine Firewall mit Stateful
Packet Inspection verwendet wird Nach laumlngerer Inaktivitaumlt wird normalerweise durch die Firewall die
DB-Verbindung geschlossen Dieses loumlst dann beim Ausleihen der Verbindung eine Fehlermeldung im
Protokoll aus 2012-08-16 165418720 WARN [http-0000-8080-8]
[orgspringframeworkjdbcsupportSQLErrorCodesFactory] Error while extracting
database product name - falling back to empty error codes
orgspringframeworkjdbcsupportMetaDataAccessException Error while extracting
DatabaseMetaData nested exception is javasqlSQLRecoverableException Getrennte
Verbindung Um dieses Problem zu beheben sollte die Option testWhileIdle=true eingestellt werden
testWhileIdle=true
Damit diese weiszlig wie oft eine Pruumlfung durchgefuumlhrt werden muss sind jedoch noch zusaumltzliche Angaben erforderlich welche fuumlr die Einstellung der Zeit zusaumltzlich gesetzt werden muumlssen
a) minEvictableIdleTimeMillis - Long in Millisekunden
Min Zeit wie lange eine DB-Verbindung im Leerlauf ist bevor diese zur Pruumlfung
gekennzeichnet wird Dieses haumlngt stark von der Einstellung der Firewall ab Wenn Sie eine
sehr restriktive Firewall haben kann es sein dass diese die Verbindung nach wenigen
Minuten Leerlauf trennt Stellen Sie den Wert immer so ein dass dieser unter der Leerlaufzeit
der Firewall liegt empfohlen 300000 entspricht 300 Sek = 5 min
minEvictableIdleTimeMillis=300000
b) timeBetweenEvictionRunsMillis - Long in Millisekunden
Der Pruumlflauf startet in der Default-Konfiguration alle 1800000 Millisekunden = 30 Min n als
zu Pruumlfen markierte Verbindungen werden in einem Pruumlflauf getestet n wird bestimmt durch
die Einstellung numTestsPerEvictionRun Empfehlung Stellen Sie den Wert auf alle 15 Min
ein
timeBetweenEvictionRunsMillis=900000
Release Notes BALVI Schnittstellenserver Seite 20 von 37
c) numTestsPerEvictionRun - Integer
Wie viele Verbindungen sollen getestet werden waumlhrend der Pruumlflauf ausgefuumlhrt wird Im
Normalfall sollte die Anzahl der zu testenden Verbindungen nicht zu hoch eingestellt werden
Der Default ist 3 Wenn Sie houmlhere Sicherheit haben wollen dass keine bdquototenldquo
Datenbankverbindungen bestehen bleiben erhoumlhen Sie den Wert auf max bdquo(maxActive ndash
maxIdle) 2ldquo Wenn Ihnen 3 ausreichend erscheint muss der Wert nicht gesetzt sein dann
wird der Default verwendet
Beispiel numTestsPerEvictionRun=10
4 Interceptors konfigurieren Neu ergaumlnzt wurde die Moumlglichkeit spezielle bdquoInterceptorsldquo zu konfigurieren die ermoumlglichen das Verhalten des Pools zu steuern Wichtig hierbei ist dass die Angabe von Werten auf real existierende Java-Klassen erfolgt die im Classpath des Tomcat vorhanden sind Groszlig-und-Kleinschreibung ist zu beachten Folgende Default-Einstellung hat BALVI fuumlr den BSS festgelegt jdbcInterceptors=
orgapachetomcatjdbcpoolinterceptorConnectionState
orgapachetomcatjdbcpoolinterceptorStatementFinalizer
orgapachetomcatjdbcpoolinterceptorResetAbandonedTimer
Details zu den verwendeten Interceptor-Einstellungen finden Sie in der Tomcat-Dokumentation3
3 httptomcatapacheorgtomcat-80-docjdbc-poolhtmlJDBC_interceptors
Release Notes BALVI Schnittstellenserver Seite 21 von 37
2512 Datenbank-Zugangsdaten verschluumlsseln
Die Verschluumlsselung fuumlr die Datenbank-Verbindung (bdquoEncrypted Datasourceldquo) ist eine Ableitung der Bibliothek Apache-Common-DBCP-14 und daher nicht mehr mit Java 8 kompatibel Die Einrichtung der Verschluumlsselung wird daher mit der Auslieferung des BSS 30 nicht mehr angeboten
2513 Active-Directory-Authentifizierung
Uumlber die folgenden Parameter wird der Zugriff des Schnittstellen-Servers auf einen Microsoft Active Directory Domain-Controller konfiguriert
ldquoldapServerAddressrdquo
Syntax PROTOKOLLIP-Adresse oder DNS-NamePORT
ltEnvironment
name=ldapServerAddress
value=ldapbl2-dc02balviintern389
type=javalangString
override=true
gt
Als Protokoll besteht auch die Moumlglichkeit ldaps (LDAP+SSL) wenn der Domain-Controller entsprechend konfiguriert wurde Im Java Truststore muss dann das Zertifikat der CA vorhanden sein welche das Zertifikat des Domain-Controllers signiert hat Zudem darf bei ldaps keine IP-Adresse verwendet werden es muss der DNS-Name des Server-Zertifikats eingetragen sein Ansonsten gibt es beim Verbinden eine Sicherheits-Exception
lt-- SSL-Beispiel
ltEnvironment
name=ldapServerAddress
value=ldapsbl2-dc02balviintern636
type=javalangString
override=true
gt
--gt
bdquoldapBaseDnrdquo
LDAP-Suchpfad fuumlr die Domain-Basis Diese muss der LDAP-Syntax fuumlr den Domain-Suffix entsprechen
Syntax DC=SERVERDC=ROOTDN
ltEnvironment
name=ldapBaseDn
value=DC=BALVIDC=INTERN
type=javalangString
override=true
gt
Release Notes BALVI Schnittstellenserver Seite 22 von 37
bdquowebLoginUseActiveDirectoryAuthenticationrdquo
Die Authentifizierung in der Browser-Oberflaumlche kann uumlber die Active-Directory-Authentifizierung erfolgen In der ersten Version ist nur die Protokoll-Auswertung moumlglich wenn der ADMIN sich anmeldet Dieser hat normalerweise niemals AD-Kennungen zugeordnet BALVI empfiehlt diese Einstellung auf bdquofalseldquo zu belassen Webservices welche uumlber SOAPREST zugreifen koumlnnen die Active-Directory-Authentifizierung trotzdem verwenden
ltEnvironment
name=webLoginUseActiveDirectoryAuthentication
value=false
type=javalangBoolean
override=true
gt
ldquoldapDaysBeforeExpirationNotificationrdquo
Die Passwort-Aumlnderung im Active-Directory uumlber die Browser-Oberflaumlche ist in der ersten Version noch nicht implementiert der Parameter wird bislang nicht ausgewertet
ltEnvironment
name=ldapDaysBeforeExpirationNotification
value=14
type=javalangInteger
override=true
gt
2514 Statement-Protokollierung in BALVI iP
Diese Option aktiviert die Lese- und Aumlnderungsprotokollierung fuumlr BALVI iP Standard ist bdquofalseldquo und wird fuumlr alle Kunden empfohlen solange keine speziellen Datenbank-Jobs eingerichtet wurden welche zeitgesteuert die Protokolleintraumlge wieder loumlschen Fuumlr Bayern wurde ein spezielles Konzept zur Leseprotokollierung entworfen Wenn Sie mehr daruumlber erfahren moumlchten kontaktieren Sie bitte die BALVI GmbH
ltEnvironment
name=enableSqlStatementMonitoring
value=true
type=javalangBoolean
override=true
gt
Beachten Sie dass diese Option massive INSERT-Statements in BALVI iP in die Tabelle VIS_D92 ausfuumlhrt Jedes abgesetzte SQL-Statement wird dabei vollstaumlndig protokolliert Dieses erzeugt eine sehr hohe INSERT-Last und in der Folge auch erhoumlhte Redolog-Switches und COMMIT-Transaktionen
Optional Aktivieren der INSERT + APPEND - Logik
Beachten Sie bitte die Hinweise von Oracle zum Hint + APPEND
Release Notes BALVI Schnittstellenserver Seite 23 von 37
Wenn Sie dieses Verhalten aktivieren moumlchten ergaumlnzen Sie bitte den folgenden Environment-Parameter
ltEnvironment
name=statementMonitoringactivateAppendMode
value=true
type=javalangBoolean
override=true
gt
2515 Einstellungen fuumlr BALVI mobil XT (bzw den bdquopartitionedExportldquo)
Diese Logik des FIFO-Buffers wurde so konzipiert dass dem Rechenzentrum diverse Einstellmoumlglichkeiten uumlber die Datei bdquocontextxmlldquo zur Verfuumlgung stehen um die Steuerung des FIFO-Puffers zu beeinflussen
Schematische Darstellung des FIFO-Puffers
Das ermoumlglicht es z B dem BALVI mobil XT Client (14 oder houmlher) den aktiven Block abzuholen und dies beim Fehler bis zu 10-mal zu wiederholen Sobald der Block [001] erfolgreich beim Client angekommen ist und dieser den naumlchsten Block anfragt wird der Block [001] verworfen wird Der Server fuumlllt dann im Hintergrund den frei gewordenen Block wieder waumlhrend der Client den Block [002] abholt
Die Groumlszlige und Anzahl der vorgecachten Bloumlcke kann uumlber die folgenden Einstellungen in der Datei bdquocontextxmlldquo definiert werden
ltEnvironment
name=partitionedExportmaxBufferedPartitions
value=3 type=javalangInteger override=true
gt
ltEnvironment
name=partitionedExportpartitionSize
value=256000 type=javalangInteger override=true
gt
Die Einstellung partitionedExportmaxBufferedPartitions ist dabei die Anzahl der vorgecachten Bloumlcke mindestens muss 2 angegeben werden Der Puffercache wird ausschlieszliglich im RAM der JVM aufgebaut es wird folglich mehr Arbeitsspeicher verwendet Dieser Arbeitsspeicher muss je gleichzeitiger Session auf dem Server bereitgestellt werden die Default-Einstellung mit 3 Partitionen a 256 KB + dem aktiven Puffer erfordern 1 MB RAM je aktiven Anwender
Aktiv
er
Puffe
r
[001] Vorg
ecac
hter
Bl
ock
[002] Vorg
ecac
hter
Bl
ock
[003]
Aktiv
er P
uffe
r
[002] Vorg
ecac
hter
Bl
ock
[003] Vorg
ecac
hter
Bl
ock
[leer]
Release Notes BALVI Schnittstellenserver Seite 24 von 37
Gleichzeitig wurde die Moumlglichkeit geschaffen dass die maximale Anzahl an gleichzeitigen Exporten durch das Rechenzentrum eingeschraumlnkt werden kann um einem OutOfMemory-Fehler vorzubeugen Die Einstellung
ltEnvironment
name=partitionedExportmaxConcurrentExports
value=10 type=javalangInteger override=true
gt
muss entsprechend der zu erwartenden gleichzeitigen Zugriffe konzipiert werden ansonsten wird der Server einen Verbindungsversuch durch die Clients ablehnen
Beachten Sie dass die folgenden Einstellungen partitionedExportmaxBufferedPartitions partitionedExportmaxConcurrentExports und partitionedExportpartitionSize gemeinsam als Rechenbasis fuumlr den RAM-Bedarf des Webservers herangezogen werden muumlssen
Folgende Faustformel sollte fuumlr die Einrichtung verwendet werden
Min 256 MB (Serverbasis) + (11 partitionedExportmaxConcurrentExports partitionedExportmaxBufferedPartitions partitionedExportpartitionSize)
Beispiel 50 gleichzeitige Anwender Blockgroumlszlige 256 KB 4 Partitionen
256 MB + (11 50 256 4) KB = 312 MB fuumlr die JVM
Empf 512 MB (Serverbasis) + (12 partitionedExportmaxConcurrentExports partitionedExportmaxBufferedPartitions partitionedExportpartitionSize)
Beispiel 50 gleichzeitige Anwender Blockgroumlszlige 256 KB 4 Partitionen
512 MB + (12 50 256 4) KB = 572 MB fuumlr die JVM
partitionedExportmaxConcurrentExports
Bestimmt die Anzahl der maximalen Export Tasks (Threads) die fuumlr partitionierte Exporte bereitgestellt werden Wenn die Anzahl uumlberschritten wird wird die entsprechende Exportanfrage abgewiesen und der Client muss zu einem spaumlteren Zeitpunkt erneut anfragen Stellen Sie diesen Wert entsprechend der zu erwartenden Benutzeranzahl ein bei 50 Anwendern also 50
Exporte oumlffnen auf der Datenbank entsprechend zur Ausfuumlhrungszeit min einen Cursor ggf fuumlr rekursive Unterabfragen kurzfristig sogar mehr Die hier eingestellte Anzahl muss mit der Anzahl von maxActive korrelieren
ltEnvironment
name=partitionedExportmaxConcurrentExports
value=10 type=javalangInteger override=true
gt
partitionedExportmaxBufferedPartitions
Bestimmt die Anzahl der Datenbloumlcke (Partitionen) die vom Server bei Abruf eines Exportes gepuffert werden Die seit Version 24 eingefuumlhrte FIFO-Puffer-Logik ermoumlglicht dass der Server schon die Ergebnisse vorpuffert so dass der Client weniger Wartezeiten bei der Anfrage nach Daten hat Diese
Release Notes BALVI Schnittstellenserver Seite 25 von 37
Puffer-Logik unterteilt den Exportdatenstrom (je Export) in mehre Bloumlcke Der Client kann nun den letzten Block neu anfordern oder den naumlchsten Block wenn der letzte Block erfolgreich verarbeitet wurde Wie viele naumlchste Bloumlcke durch den Server bereit gestellt werden entscheidet diese Einstellung Sobald kein naumlchster Block mehr bereit gestellt werden muss wird der Datenbank-Cursor geschlossen eine Erhoumlhung kann also zu einer Entlastung der aktiven DB-Verbindungen fuumlhren erhoumlht jedoch den Bedarf an RAM des Servers
Der von BALVI voreingestellte Wert ist 3
ltEnvironment
name=partitionedExportmaxBufferedPartitions
value=3 type=javalangInteger override=true
gt
partitionedExportpartitionSizeldquo
Die Groumlszlige der Datenbloumlcke (Partitionen) die an den Client uumlbermittelt werden in Bytes Wenn Sie diesen Wert zu niedrig einstellen reduziert sich die Effizienz des Caches da der Client mehr Datenbloumlcke hintereinander abrufen muss Waumlhlen Sie einen zu groszligen Wert wird die neu zu uumlbertragende Datenmenge im Fall eines Fehlers houmlher
Der von BALVI voreingestellte Wert ist 256000 (256 KB)
ltEnvironment
name=partitionedExportpartitionSize
value=256000 type=javalangInteger override=true
gt
exportTokensmaxTokenCount
Maximale Anzahl der gleichzeitig vergebenen Token die vom Server gecached werden Jede Sitzung welche einen Export durchfuumlhrt erhaumllt einen Session-Token
Wenn eine Sitzung laumlngere Zeit nicht verwendet wurde wird dieser Session-Token wieder entfernt Wenn Sie den Wert zu niedrig einstellen fuumlhrt das zu einer generellen Session-Begrenzung auch fuumlr den nicht partitionierten Export-Modus welcher ab Version 21 verfuumlgbar ist
Ist die Anzahl der Tokens houmlher als die Datenbankeinstellung maxActive kann es vorkommen dass zwar eine Session gestartet werden kann jedoch kein Datenexport zustande kommt
Der von BALVI voreingestellte Wert ist 2000
ltEnvironment
name=exportTokensmaxTokenCount
value=20 type=javalangInteger override=true
gt
exportTokenstokenExpirationInSeconds
Zeit in Sekunden die verstreichen muss bis ein Token unguumlltig wird falls darauf kein Zugriff mehr erfolgt Nach einem erfolgreichen Export wird der Token automatisch geschlossen diese Option ist fuumlr den Abbruchfall vorgesehen Der von BALVI voreingestellte Wert ist 180 (180 s = 3 min)
Release Notes BALVI Schnittstellenserver Seite 26 von 37
ltEnvironment
name=exportTokenstokenExpirationInSeconds
value=180 type=javalangInteger override=true
gt
exportTokenstokenDisposalInSeconds
Zeit in Sekunden die verstreichen muss bis ein Token das erfolgreich abgearbeitet wurde aus dem Cache geloumlscht wird Um sicher zu stellen dass der letzte Exportblock noch erfolgreich abgerufen werden kann bleibt der Token auch nach Fertigmeldung des Clients noch N Sek guumlltig
Der von BALVI voreingestellte Wert ist 60 (60 s = 1 min)
ltEnvironment
name=exportTokenstokenDisposalInSeconds
value=60 type=javalangInteger override=true
gt
2516 Job-Verwaltung fuumlr den BSS konfigurieren Aktivierung der Jobverwaltung
Bis zur Version 28 des BSS gab es den Parameter bdquoavailableServicesldquo Dieser konnte bei Bedarf aktiviert werden wenn die Jobs benoumltigt wurden
Mit Version 30 ist die Einstellung bdquoavailableServicesldquo zu entfernen und kann durch den neuen optionalen Parameter bdquoisJobServiceEnabledldquo in der Datei bdquocontextxmlldquo ersetzt werden
lt-- Neue Parameter zur Aktivierung des Job Service Ersatz fuumlr availableServices --gt
ltEnvironment
name=isJobServiceEnabled
value=true
type=javalangBoolean
override=true
gt
Ab BSS 30 wird die Jobs-Engine standardmaumlszligig aktiviert Sollte die Jobs-Engine nicht benoumltigt werden muss bdquovalueldquo der Wert bdquofalseldquo zugewiesen werden Wird bdquoisJobServiceEnabledldquo nicht eingefuumlgt sind die Jobs trotzdem standardmaumlszligig aktiv
Nach dem Neustart des Servers und erneutem Einloggen erscheint nun zusaumltzlich der Menuumlpunkt bdquoJobsldquo
bdquopasswordKeyldquo fuumlr Jobs
In der Job-Logik wird ein von BALVI definierter Standard-Schluumlssel fuumlr die Ablagen von schuumltzenswerten Daten z B Passwoumlrtern verwendet Diese Einstellung ermoumlglicht den BALVI-Standard zu uumlberschreiben Wenn Sie diese Einstellung aumlndern muumlssen jedoch alle bislang verschluumlsselten Job-Parameter neu verschluumlsselt werden
ltEnvironment
name=javacompenvjobspasswordKey
value=MeinHochsicheresNeuesPasswort
type=javalangString
Release Notes BALVI Schnittstellenserver Seite 27 von 37
override=true
gt
bdquoJob ID enableddisabledldquo (Deprecated ersetzt ab 28 durch das bdquoBindenldquo von Jobs)
Sondereinstellungen fuumlr die Job-Verwaltung Da alle Jobs in einer Datenbank administriert werden jedoch ggf verteilt auf mehreren Tomcat-Servern ausgefuumlhrt werden sollen besteht hier die Option Jobs fuumlr die aktuelle Tomcat-Instanz separat zu deaktivieren
Die Einstellung ID koumlnnte z B folgendermaszligen aussehen javacompenvjobsC0DB58D8D52C4BBC966D1DC788A4EF8Benabled
Fuumlr weitere Fragen zu dieser Einstellung kontaktieren Sie bitte die BALVI GmbH
ltEnvironment
name=javacompenvjobsIDenabled
value=false
type=javalangBoolean
override=true
gt
2517 Weitere optionale Parameter
Es ist fuumlr diverse einzelne Schnittstellen ggf erforderlich Einstellungen in der Datei bdquocontextxmlldquo zu ergaumlnzen Hinweise zu diesen Parametern sind dann in dem der Schnittstelle beiliegenden Dokument enthalten Das gilt z B fuumlr die Schnittstelle bdquoXGewerbeanzeigenldquo
26 Logging mit logback Das Logging wurde komplett uumlberarbeitet Statt bdquoLog4Jldquo wird jetzt bdquologbackldquo4 benutzt Ab BSS 30 ist es zwingend notwendig die Einstellung vorzunehmen um das Logging der Anwendung zu steuern
Migration Ergaumlnzen Sie die neue Einstellung bdquologgingconfigldquo
lt-- Neue Paramter zur Angabe der Logback Config Ersatz fuumlr log4jConfigLocation --gt
ltEnvironment
name=loggingconfig
value=$catalinabaseconflogback-bssxml
type=javalangString
override=true
gt
Nach wie vor steht es Ihnen frei die Logging-Konfiguration eigenstaumlndig anzupassen
Wenn Sie jedoch dieselbe WAR in einer Tomcat-Instanz unter mehreren Context-Namen betreiben wuumlrden beide dieselbe Logging-Konfiguration verwenden so dass alle Protokolleintraumlge in einer Log-Datei aus
4 httplogbackqoschmanualappendershtml
Release Notes BALVI Schnittstellenserver Seite 28 von 37
mehreren Webanwendungen generiert werden Aumlndern Sie den Namen der Logging-Konfiguration entsprechend ab um fuumlr jede Anwendung eine spezifische Logging-Einstellung vornehmen zu koumlnnen
27 Tocmat Optional Suche im bdquoKlassenpfadldquo um den
Ordner bdquoconfldquo erweitern Die Suche nach Dateien uumlber bdquoclasspathldquo setzt voraus dass die Ordner- und Dateinamen im Apache Tomcat bekannt gegeben werden Der Klassenpfad kann in der Datei bdquocatalinapropertiesldquo angepasst werden Wenn Sie dort unter commonloader die folgenden Werte ergaumlnzen kann eine Datei auch im Ordner conf abgelegt werden damit Apache Tomcat diese findet Ansonsten muss die Datei im Ordner lib abgelegt werden
commonloader=$catalinabaseconf$catalinahomeconf
3 Die neue Browser-Oberflaumlche Der BALVI Schnittstellenserver hat seit Version 25 neben der Protokollierung auch die Moumlglichkeit Job-Konfigurationen zu pflegen Der Login ist nur fuumlr einen in BALVI iP eingetragenen ADMIN (z B Benutzer bdquoSYSTEMADMINldquo) mit dem in BALVI iP hinterlegten Passwort moumlglich Zur Anmeldung muss immer [SYSTEMBenutzername] im Feld Benutzer angegeben werden ansonsten schlaumlgt die Anmeldung fehl Bitte achten Sie darauf dass der bdquoldquo (Slash) und nicht der bdquoldquo (Backslash) verwendet werden muss
31 Server-Protokoll Um das Server-Protokoll anzuzeigen waumlhlen Sie den entsprechenden Menuumlpunkt Dort haben Sie seit BSS 26 die Moumlglichkeit uumlber alle Spalten der Protokolle nach Informationen zu suchen
Seit BSS 31 gibt es die Moumlglichkeit Verfahren in bdquoKopfsaumltzeldquo und bdquoDetailsaumltzeldquo zu unterteilen Wurde das Verfahren entsprechend konfiguriert (wie z B bei der Schnittstelle bdquoXGewerbeanzeigenldquo) dann wird im Protokoll-Kopfsatz nur der Start und das Ende der Ausfuumlhrung in der Liste angezeigt Erst bei einem Klick auf bdquoInformationenldquo wird die Liste aller Detailsaumltze angezeigt die im Durchlauf erzeugt wurden
Release Notes BALVI Schnittstellenserver Seite 29 von 37
Verfahren
Die Liste der verfuumlgbaren Verfahren die bei Ihnen im System installiert sind ZB
BEFUNDEhellip Schnittstelle Befunde LM FM oder TS
PROBEhellip Schnittstelle zum Export von Proben an Labore ebenfalls Spezifisch fuumlr einzelne Fachbereiche
MOBILXT Protokolle der BALVI Mobil XT Synchronisation
WEB Allgemeine nicht spezifizierte Protokolle hierunter ist bislang auch die eFi-Protokollierung zu finden
WEB_I0802 Protokolle zur Schnittstelle BALVI iP LIMS (Lebensmittelproben)
XGEWERBE Schnittstelle XGewerbeanzeigen
Klicken Sie auf die Schaltflaumlche so besteht bei den neuen Protokolldatensaumltzen die Moumlglichkeit Detail-Informationen zum Protokollsatz zu erhalten
Release Notes BALVI Schnittstellenserver Seite 30 von 37
Seit BSS 30x ist die Anzeige der Protokolle ebenfalls farblich abgesetzt so dass Protokolleintraumlge mit Fehlern hellrot und Warnungen hellgelb hinterlegt werden
32 Jobs Mit einem Klick auf den Menuumlpunkt Jobs rufen Sie die Oberflaumlche fuumlr die Job-Konfiguration auf Daraufhin werden alle Jobs aufgelistet die fuumlr den BSS freigegeben sind Hier koumlnnen Sie Einstellungen an den Jobs vornehmen und die Jobs aktivieren bzw deaktivieren Die Beschreibungen bzw Einstellungsmoumlglichkeiten fuumlr den jeweiligen SST-Job sind nicht Bestandteil dieser Dokumentation
33 Log-Ausgaben Uumlber den Menuumlpunkt Log-Ausgaben koumlnnen Sie die Ausgabe der Protokolleintraumlge in Echtzeit beobachten
Release Notes BALVI Schnittstellenserver Seite 31 von 37
Starten Sie die Echtzeit-Protokollierung indem Sie auf die Schaltflaumlche mit dem Symbol bdquoPlayldquo (Dreieck) klicken unterbrechen Sie die Ausgabe indem Sie die auf Schaltflaumlche mit dem Symbol bdquoPauseldquo (zwei Balken) klicken
Klicken Sie auf die Schaltflaumlche bdquoAktualisierenldquo (zwei Pfeile) um die neuesten Protokolleintraumlge angezeigt zu bekommen
Klicken Sie auf das Symbol mit dem Papierkorb um die letzten Protokollmeldungen in der Anzeige zu loumlschen
Die Daten in den Protokolldateien auf der Festplatte des Servers sind davon nicht betroffen
Uumlber das Symbol bdquoLogging anpassenldquo (Schraubenschluumlssel) koumlnnen Sie die Ausgabe der Daten im Echtzeitfenster und in den Protokolldateien aumlndern jedoch ist diese Einstellung nur temporaumlr Die Standardeinstellungen koumlnnen ausschlieszliglich uumlber die Anpassung der Datei bdquologback-bssxmlldquo im Konfigurationsverzeichnis des Servers selbst geaumlndert werden
Release Notes BALVI Schnittstellenserver Seite 32 von 37
In der Logging-Parameter Konfiguration koumlnnen Sie verschiedene Parameter einstellen und uumlber die Schaltflaumlche bdquoAnwendenldquo dann sofort im Echtzeitprotokoll sehen Welche Einstellungen moumlglich sind erfahren Sie wenn es eine akute Fehlersituation gibt die detailliertere Ausgaben im Protokoll erfordert
Warnung Wenn Sie den Log-Level fuumlr ROOT oder eine andere Klasse auf TRACE einstellen werden sehr viele Protokollausgaben generiert die auch dazu fuumlhren koumlnnen dass der Server sehr langsam wird oder die Festplatte des Servers zulaumluft wenn fuumlr das Logging kein Dateilimit konfiguriert wurde
34 LogoutAbmeldung vom System Zum Abmelden waumlhlen Sie oben rechts das Kontextmenuuml
35 Cache loumlschen Der Cache wird in der Regel automatisch geloumlscht Wenn Sie jedoch gerade in BALVI iP eine Aumlnderung an den Schnittstellen eingespielt haben und moumlchten dass diese sofort wirksam wird kann die Funktion bdquoCache loumlschenldquo dazu verwendet werden dass der BALVI Schnittstellenserver die Einstellungen bei der naumlchsten Anfrage neu einliest
Release Notes BALVI Schnittstellenserver Seite 33 von 37
Release Notes BALVI Schnittstellenserver Seite 34 von 37
4 Einrichtung in BALVI iP Um die Verfahren fuumlr den BALVI Schnittstellenserver fuumlr Anwender freizuschalten wird das Objekt bdquoSystemeinstellungenldquo oder bdquoMandanten- und Benutzereinstellungenldquo verwendet Die Anpassung ist je Verfahren moumlglich so kann in BALVI iP fuumlr den Zugriff durch den BALVI Schnittstellenserver ein Benutzer bdquoAldquo am Verfahren bdquoMobilldquo berechtigt werden ein Benutzer bdquoBldquo nur am Verfahren bdquoSLA_FLESHldquo usw Die Logik ist jedoch einheitlich Je Verfahren wird durch BALVI eine Verfahrensgruppe mit dem Verfahrensnamen angelegt und mit den entsprechenden Einstellungen vorkonfiguriert welche durch das Verfahren erforderlich sind Dabei kann die Komplexitaumlt der Einstellungen variieren wie z B an den zu Version 23 verfuumlgbaren Verfahren bdquoMobilldquo und bdquoSLA_Fleshldquo ersichtlich wird
Im Verfahren BALVI Mobil sind diverse Anpassungen moumlglich welche je Bundesland oder eingesetzter Import- und Export-Variante durch den BALVI Schnittstellenserver bei der Bearbeitung von Anfragen gepruumlft werden siehe Punkt 3 Abb Mobil-Einstellung in BALVI iP
Abb Mobil-Einstellung in BALVI iP
Alle Verfahren verwenden jedoch die regulaumlre Benutzerverwaltung von BALVI iP Ein Benutzer ohne Passwort gilt fuumlr BALVI iP als gesperrt was fuumlr das Login bedeutet dass der Anwender sich nur uumlber die Active-Directory-Authentifizierung anmelden kann Ist das nicht moumlglich (bzw nicht konfiguriert) kann der Anwender sich weder in BALVI iP noch uumlber die Webservice-Schnittstelle authentifizieren
Fuumlr Dienste-Schnittstellen welche keine persoumlnliche Authentifizierung durch einen Anwender erfordern wird empfohlen einen separaten Benutzer in der Benutzerverwaltung anzulegen und ein sicheres Kennwort zu vergeben Das Anlegen von zusaumltzlichen Benutzern gilt nicht fuumlr BALVI mobil XT da beim Holen und Uumlbermitteln von Daten jeder Benutzer auch ein fachlich konfigurierter Anwender innerhalb von BALVI iP ist und die Anwendungsoberflaumlche ebenfalls zur Erfassung von Daten verwendet
Unter Punkt 2 der Abb Mobil-Einstellung in BALVI iP wird ein modales Fenster geoumlffnet (Abb BALVI mobil Benutzerverwaltung) Innerhalb dieses modalen Fensters werden mandantenweise die Benutzer fuumlr BALVI
Release Notes BALVI Schnittstellenserver Seite 35 von 37
mobil und den jeweiligen Fachbereich festgelegt Dabei ist es wichtig dass man die Haken bdquoAktiv fuumlr hellipldquo bei bdquohellip mobilldquo und bei einem Fachbereich (bdquohellip LMldquo bdquohellip FMldquo usw) setzt weil sonst uumlber den BALVI Schnittstellenserver keine Kommunikation mit BALVI iP moumlglich ist
Abb BALVI mobil Benutzerverwaltung
Alternativ zur Passwort-Authentifizierung wird wie beschrieben auch die Active-Directory-Authentifizierung angeboten Dazu muss der BALVI iP-Anwender uumlber die Schaltflaumlche bdquoDomaumlnen-Benutzer zuordnenldquo mit dem Active Directory verknuumlpft werden
Nur wenn die Active-Directory-Konfigurationen in BALVI iP und im BALVI Schnittstellenserver auf dieselbe Domaumlne verweisen sind die Domaumlnen-Zuordnung und die Active-Directory-Authentifizierung (z B uumlber BALVI mobil XT) moumlglich
Release Notes BALVI Schnittstellenserver Seite 36 von 37
5 Bekannte Probleme und Loumlsungen
51 ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner Bei der Job-Bearbeitung tritt folgender Fehler auf ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner
Behebung
Fuumlhren Sie das beiliegende IP-Patch (UPDATEexe) aus bevor Sie das WAR austauschen
52 Server startet nicht Sie finden folgende Zeilen im Protokoll (catalinaout oder bsslog)
ERROR [localhost-startStop-1] [IdentityServiceImpl] serverID must not be empty
ERROR [localhost-startStop-1] [ContextLoader] Context initialization failed
Behebung
Setzen Sie die Umgebungsvariable ldquoserverIDrdquo in der Datei bdquocontextxmlldquo
53 ORA-00942 table or view does not exist In vielen Faumlllen wird der Fehler ldquoTabelle oder View nicht vorhandenrdquo ausgeworfen (Java-Protokoll im Ordner logs von Apache Tomcat) wenn eine neue Schnittstelle eingerichtet oder ein neues BALVI iP Release bzw Update eingespielt wurde ohne anschlieszligend das aktuelle GRANT-Skript auszufuumlhren
Behebung
Fuumlhren Sie das GRANT-Skript erneut aus
54 ORA-0406x bdquoBestehender Paketstatus wurde aufgehobenldquo
ORA-04061 Bestehender Status von package body ABCXYZ wurde annulliert
ORA-04065 Ausfuumlhrung nicht erfolgreich package body ABCXYZ wurde geaumlndert oder geloumlscht
Release Notes BALVI Schnittstellenserver Seite 37 von 37
Der Fehler tritt haumlufig ein nachdem die UPDATEexe ausgefuumlhrt und in der Ausfuumlhrungsliste ein Package aktualisiert wurde Oracle merkt sich je User-Session bestimmte Werte im Package wenn der Anwender es verwendet hat Durch einen bdquoCREATE OR REPLACE PACKAGEldquo-Befehl kann dieser Status temporaumlr aufgehoben werden Normalerweise tritt dieser Fehler nach dem Update genau einmal in jeder aktiven Session auf wenn der BSS nicht neu gestartet wird
Behebung
Starten Sie nach jedem Update den BSS neu um alle laufenden Sessions zu beenden
55 Jobs sind nicht ausfuumlhrbar
1 Ein Job wird mit dem Status bdquoNicht unterstuumltztldquo angezeigt wenn fuumlr seine Ausfuumlhrung eine houmlhere Version des BSS erforderlich ist
2 Nach dem Klonen der Datenbank von der Produktions- auf die Testumgebung erhalten alle Jobs automatisch den Status bdquoDeaktiviertldquo wenn die bdquoserverIDldquo nicht identisch ist
Beide Statusaumlnderungen sind gewollt Damit soll verhindert werden dass Jobs nach einem Serverneustart oder nach einem Update automatisch starten und dabei Fehler verursachen
Um Jobs mit dem Status bdquoNicht unterstuumltztldquo nutzen und konfigurieren zu koumlnnen ist es erforderlich den BALVI Schnittstellenserver zu aktualisieren
Deaktivierte Jobs koumlnnen Sie aktivieren indem Sie den jeweiligen Job an den aktuellen Server binden und den Haken bei bdquoAktivldquo setzen
Release Notes BALVI Schnittstellenserver Seite 16 von 37
da auch dort mit einem fachlich erweiterten Client die Moumlglichkeit besteht dass neue Schnittstellen bereitgestellt und somit mehr Schreibrechte auf Tabellen benoumltigt werden
244 Welche Version des Grant-Skripts soll ich nehmen Wie der Schnittstellenserver sind auch die Grant-Skripte versioniert Neuere Versionen des Grant-Skriptes sind abwaumlrts-kompatibel und koumlnnen immer verwendet werden auch wenn in einer Schnittstellenbeschreibung eine aumlltere Version des Grant-Skriptes explizit benannt wurde
245 Kombination von mehreren Verfahren Wenn Sie zwei oder mehr Schnittstellen im BSS verwenden moumlchten ist es ggf erforderlich auch mehrere Verfahren auf aktiv (bdquo1ldquo) zu setzen
Im Beispiel nehmen wir an Sie moumlchten bdquoeFildquo und bdquoBALVI mobil XTldquo im Schnittstellenserver bereitstellen In der Beschreibung von bdquoeFildquo steht dass das Grant-Skript V36 erforderlich ist BALVI mobil XT 18 erfordert jedoch schon V56
Wenn Sie beide Verfahren betreiben ist im Grant-Skript (V56 oder houmlher) die Einstellung fuumlr beide Verfahren zu aktivieren
====================================================
DEKLARATIVER TEIL MUSS vom KUNDEN geaumlndert
bzw auf die korrekten SCHEMA-Namen angepasst
werden
Die USER-Namen muumlssen in Groszligbuchstaben
geschrieben sein sonst werden sie nicht
gefunden
====================================================
sUserBALVI_IP = BALVI_IP_SCHEMA
sUserBALVI_WEB = WEBAPP_SCHEMA
-- Verfahrensbezogene Konfiguration
-- Setzen Sie fuumlr das jeweilige Verfahren eine 1
-- BALVI Schnittstellenserver (BSS)
-- bis V266 auch BALVI Kommunikationsserver (BKS) genannt
-- generell fuumlr die meisten Verfahren guumlltig
-- Ab Version 57 entfaumlllt mit der Einfuumlhrung der
-- Schnittstelle XGewerbeanzeigen auch der separate Schalter
-- WS_BTR beide Verfahren wurden vereinheitlicht
WS_BSS = 1
-- WebService BTR (Betriebsstaumlttenregister) (NRW TH)
-- entfernt mit Update V57 setzen Sie stattdessen bei WS_BSS = 1
--WS_BTR = 0
-- Probenahme Futtermittel im Browser(BY)
WS_PROBE_FM = 0
-- Risikoorientierte Probenplanung Futtermittel ndash RIOPP FM (BY)
WS_RIOPP_FM = 0
-- Verfahren Export an EFi (Status Pilotbetrieb)
WS_EFI = 1
-- neu ab Version 35 des Grant-Skriptes ist die Moumlglichkeit den Webuser
Release Notes BALVI Schnittstellenserver Seite 17 von 37
-- fuumlr das Loumlschen der Ausgangskoumlrbe explizit zu berechtigen bzw sogar einen
-- expliziten abweichenden User festzulegen Die Konfiguration in der
-- Job-Oberflaumlche sieht vor dass man die Oracle-Datenbank-Zugangsdaten fuumlr
-- das Loumlschen einstellen muss Hier muss im Normalfall derselbe Oracle
-- Datenbankbenutzer eingetragen werden wie in der Tomcat-Verbindungs-
-- konfiguration In diesem Fall sollte wenn WS_EFI = 1 eingestellt wurde
-- ebenfalls WS_EFI_DELETE = 1 eingestellt werden
-- Alternativen
-- 1) Datenbankbenutzer aumlndern
-- Wenn bei sUserEFI_TRUNC anstatt sUserBALVI_WEB (Standard) ein anderer
-- Oracle-Benutzername angegeben wird wird das Loumlschrecht fuumlr die EFi
-- Ausgangskoumlrbe Datenbankseitig exklusiv dem angegeben Datenbankbenutzer
-- zugewiesen
-- 2) Loumlschrecht verweigern
-- Setzen Sie die Variablen WS_EFI_DELETE = 0 damit kein Loumlschrecht
-- zugeweisen wird
WS_EFI_DELETE = 0
-- Beispiel Anderer Benutzer muss in der Datenbank existieren
-- Entfernen Sie die fuumlhrenden -- vor der Variable sUserEFI_TRUNC und
-- setzen den entsprechenden Oracle-Benutzer ein
--sUserEFI_TRUNC = TEST_EFI_TRUNC
hellip
25 Konfiguration des Schnittstellen-Servers
251 Die bdquocontextxmlldquo-Parameter Die von der Servlet-Spezifikation vorgegeben Rump-Struktur sieht folgendermaszligen aus
ltxml version=10 encoding=utf-8gt
ltDOCTYPE Contextgt
ltContextgt
lt-- Kundenspezifische Einstellungen --gt
ltContextgt
Anwendungsspezifische Einstellungen werden zwischen ltContextgt und ltContextgt eingefuumlgt Alle allgemeinguumlltigen Einstellungen in der Datei bdquocontextxmlldquo werden hier erlaumlutert Kommentare finden sich auch in der von BALVI ausgelieferten Beispiel-Konfiguration
Neben den im Folgenden beschriebenen Standard-Einstellungen kann es auch vorkommen dass bundeslandspezifische Erweiterungen vorhanden sind welche nicht in dieser Dokumentation aufgefuumlhrt werden Diese funktionieren trotzdem regulaumlr weiter wenn keine expliziten Informationen zu Kompatibilitaumltsproblemen in den Release-Notes aufgefuumlhrt wurden
2511 Datenbankverbindung jdbcDataSource
Die Datenbankverbindung wird uumlber die von DBCP und dem Oracle-Treiber vorgegebenen Moumlglichkeiten realisiert Der Einsatz der orgapachetomcatjdbcpoolDataSourceFactory (automatisch verfuumlgbar ab Apache Tomcat 7 in der mitgelieferten tomcat-dbcpjar) wird als Beispiel-Konfiguration ausgeliefert
ltResource
name=jdbcDataSource
auth=Container
Release Notes BALVI Schnittstellenserver Seite 18 von 37
type=javaxsqlDataSource
factory=orgapachetomcatjdbcpoolDataSourceFactory
maxActive=10 initialSize=3
maxIdle=5
maxWait=10000
url=jdbcoraclethinBL2-ORA10-KUNDENBALVIINTERN1521ORCL
driverClassName=oraclejdbcdriverOracleDriver
username=balvi_webservice_schema
password=balvi_webservice_password
description=Oracle Datasource
maxOpenPreparedStatements=50
removeAbandoned=false
removeAbandonedTimeout=100
logAbandoned=true
jdbcInterceptors=hellip
gt
Hinweise zur Einstellung der jdbcDataSource
Standard-Einstellungen fuumlr den Datenbank-Verbindungspool
Der Verbindungspool muss entsprechend der Anzahl der zu erwartenden gleichzeitigen Benutzer konfiguriert werden Wenn Sie erwarten dass 50 Anwender gleichzeitig arbeiten stellen Sie bitte folgende Werte ein
maxActive=(50 + 10 (fuumlr System und Jobs)) = 60
maxIdle= (50 10) = 5
1 maxActive - maximale Anzahl der gleichzeitigen aktiven Anfragen an die DB
Wenn der Werte maxActive erreicht ist z B wenn mehrere Benutzer gleichzeitig einen Export starten moumlchten welcher laumlngere Zeit in Anspruch nimmt dann kann der Server die Anfrage nicht mehr bedienen und der Anwender wird abgewiesen maxActive hat zudem Auswirkungen auf die im Hintergrund ausgefuumlhrten Jobs maxActive wird daher kalkuliert mit der Anzahl der Anwender und moumlglicher Datenbank-Connections fuumlr Hintergrund-Jobs Jeder aktiv ausgefuumlhrte Job benoumltigt mindestens eine Connection nur selten wird aus Performance-Gruumlnden mehr als eine Connection waumlhrend der Job-Ausfuumlhrung verwendet Im Normalfall sollten daher 10 Connections fuumlr Hintergrundprozesse ausreichend sein
2 maxIdle - Anzahl der offenen Verbindungen auch wenn der Server im Leerlauf ist
Jede offene Verbindung im Leerlauf haumllt auf dem Datenbankserver eine Session offen Auch diese erfordert Ressourcen Wenn die Verbindungen jedoch geschlossen werden kann die Anfragezeit fuumlr eine neue Verbindung steigen da diese Verbindung erst neu ausgehandelt werden muss Die Empfehlung fuumlr den Wert bdquomaxIdleldquo ist ca 10 der Einstellung von maxActive
KeepAlive-Einstellungen fuumlr den Pool
1 validationQuery
Diese wird ausgefuumlhrt um die Verbindung zu DB zu validieren Es MUSS ein Datensatz zuruumlckgegeben werden ansonsten nimmt der DBCP an dass die Abfrage nicht erfolgreich abgesetzt wurde Achten Sie also bitte darauf dass die Abfrage nicht zu leitungsintensiv ist und genau einen Datensatz liefert
Release Notes BALVI Schnittstellenserver Seite 19 von 37
Oracle bietet dafuumlr die virtuelle Tabelle DUAL an welche sich fuumlr die ValidationQuery sehr gut eignet da die Abfrage kaum Ressourcen verbraucht
validationQuery=select 1 from dual
2 testOnBorrow - Boolscher Wert true oder false
Diese Einstellung sorgt dafuumlr dass der Pool die Verfuumlgbarkeit anhand der validationQuery pruumlft bevor
die DB-Verbindung an die Anwendung ausgeliehen wird Empfehlung
testOnBorrow=true
3 testWhileIdle - Boolscher Wert true oder false
Diese Einstellung ist hilfreich wenn zwischen dem Tomcat und der DB eine Firewall mit Stateful
Packet Inspection verwendet wird Nach laumlngerer Inaktivitaumlt wird normalerweise durch die Firewall die
DB-Verbindung geschlossen Dieses loumlst dann beim Ausleihen der Verbindung eine Fehlermeldung im
Protokoll aus 2012-08-16 165418720 WARN [http-0000-8080-8]
[orgspringframeworkjdbcsupportSQLErrorCodesFactory] Error while extracting
database product name - falling back to empty error codes
orgspringframeworkjdbcsupportMetaDataAccessException Error while extracting
DatabaseMetaData nested exception is javasqlSQLRecoverableException Getrennte
Verbindung Um dieses Problem zu beheben sollte die Option testWhileIdle=true eingestellt werden
testWhileIdle=true
Damit diese weiszlig wie oft eine Pruumlfung durchgefuumlhrt werden muss sind jedoch noch zusaumltzliche Angaben erforderlich welche fuumlr die Einstellung der Zeit zusaumltzlich gesetzt werden muumlssen
a) minEvictableIdleTimeMillis - Long in Millisekunden
Min Zeit wie lange eine DB-Verbindung im Leerlauf ist bevor diese zur Pruumlfung
gekennzeichnet wird Dieses haumlngt stark von der Einstellung der Firewall ab Wenn Sie eine
sehr restriktive Firewall haben kann es sein dass diese die Verbindung nach wenigen
Minuten Leerlauf trennt Stellen Sie den Wert immer so ein dass dieser unter der Leerlaufzeit
der Firewall liegt empfohlen 300000 entspricht 300 Sek = 5 min
minEvictableIdleTimeMillis=300000
b) timeBetweenEvictionRunsMillis - Long in Millisekunden
Der Pruumlflauf startet in der Default-Konfiguration alle 1800000 Millisekunden = 30 Min n als
zu Pruumlfen markierte Verbindungen werden in einem Pruumlflauf getestet n wird bestimmt durch
die Einstellung numTestsPerEvictionRun Empfehlung Stellen Sie den Wert auf alle 15 Min
ein
timeBetweenEvictionRunsMillis=900000
Release Notes BALVI Schnittstellenserver Seite 20 von 37
c) numTestsPerEvictionRun - Integer
Wie viele Verbindungen sollen getestet werden waumlhrend der Pruumlflauf ausgefuumlhrt wird Im
Normalfall sollte die Anzahl der zu testenden Verbindungen nicht zu hoch eingestellt werden
Der Default ist 3 Wenn Sie houmlhere Sicherheit haben wollen dass keine bdquototenldquo
Datenbankverbindungen bestehen bleiben erhoumlhen Sie den Wert auf max bdquo(maxActive ndash
maxIdle) 2ldquo Wenn Ihnen 3 ausreichend erscheint muss der Wert nicht gesetzt sein dann
wird der Default verwendet
Beispiel numTestsPerEvictionRun=10
4 Interceptors konfigurieren Neu ergaumlnzt wurde die Moumlglichkeit spezielle bdquoInterceptorsldquo zu konfigurieren die ermoumlglichen das Verhalten des Pools zu steuern Wichtig hierbei ist dass die Angabe von Werten auf real existierende Java-Klassen erfolgt die im Classpath des Tomcat vorhanden sind Groszlig-und-Kleinschreibung ist zu beachten Folgende Default-Einstellung hat BALVI fuumlr den BSS festgelegt jdbcInterceptors=
orgapachetomcatjdbcpoolinterceptorConnectionState
orgapachetomcatjdbcpoolinterceptorStatementFinalizer
orgapachetomcatjdbcpoolinterceptorResetAbandonedTimer
Details zu den verwendeten Interceptor-Einstellungen finden Sie in der Tomcat-Dokumentation3
3 httptomcatapacheorgtomcat-80-docjdbc-poolhtmlJDBC_interceptors
Release Notes BALVI Schnittstellenserver Seite 21 von 37
2512 Datenbank-Zugangsdaten verschluumlsseln
Die Verschluumlsselung fuumlr die Datenbank-Verbindung (bdquoEncrypted Datasourceldquo) ist eine Ableitung der Bibliothek Apache-Common-DBCP-14 und daher nicht mehr mit Java 8 kompatibel Die Einrichtung der Verschluumlsselung wird daher mit der Auslieferung des BSS 30 nicht mehr angeboten
2513 Active-Directory-Authentifizierung
Uumlber die folgenden Parameter wird der Zugriff des Schnittstellen-Servers auf einen Microsoft Active Directory Domain-Controller konfiguriert
ldquoldapServerAddressrdquo
Syntax PROTOKOLLIP-Adresse oder DNS-NamePORT
ltEnvironment
name=ldapServerAddress
value=ldapbl2-dc02balviintern389
type=javalangString
override=true
gt
Als Protokoll besteht auch die Moumlglichkeit ldaps (LDAP+SSL) wenn der Domain-Controller entsprechend konfiguriert wurde Im Java Truststore muss dann das Zertifikat der CA vorhanden sein welche das Zertifikat des Domain-Controllers signiert hat Zudem darf bei ldaps keine IP-Adresse verwendet werden es muss der DNS-Name des Server-Zertifikats eingetragen sein Ansonsten gibt es beim Verbinden eine Sicherheits-Exception
lt-- SSL-Beispiel
ltEnvironment
name=ldapServerAddress
value=ldapsbl2-dc02balviintern636
type=javalangString
override=true
gt
--gt
bdquoldapBaseDnrdquo
LDAP-Suchpfad fuumlr die Domain-Basis Diese muss der LDAP-Syntax fuumlr den Domain-Suffix entsprechen
Syntax DC=SERVERDC=ROOTDN
ltEnvironment
name=ldapBaseDn
value=DC=BALVIDC=INTERN
type=javalangString
override=true
gt
Release Notes BALVI Schnittstellenserver Seite 22 von 37
bdquowebLoginUseActiveDirectoryAuthenticationrdquo
Die Authentifizierung in der Browser-Oberflaumlche kann uumlber die Active-Directory-Authentifizierung erfolgen In der ersten Version ist nur die Protokoll-Auswertung moumlglich wenn der ADMIN sich anmeldet Dieser hat normalerweise niemals AD-Kennungen zugeordnet BALVI empfiehlt diese Einstellung auf bdquofalseldquo zu belassen Webservices welche uumlber SOAPREST zugreifen koumlnnen die Active-Directory-Authentifizierung trotzdem verwenden
ltEnvironment
name=webLoginUseActiveDirectoryAuthentication
value=false
type=javalangBoolean
override=true
gt
ldquoldapDaysBeforeExpirationNotificationrdquo
Die Passwort-Aumlnderung im Active-Directory uumlber die Browser-Oberflaumlche ist in der ersten Version noch nicht implementiert der Parameter wird bislang nicht ausgewertet
ltEnvironment
name=ldapDaysBeforeExpirationNotification
value=14
type=javalangInteger
override=true
gt
2514 Statement-Protokollierung in BALVI iP
Diese Option aktiviert die Lese- und Aumlnderungsprotokollierung fuumlr BALVI iP Standard ist bdquofalseldquo und wird fuumlr alle Kunden empfohlen solange keine speziellen Datenbank-Jobs eingerichtet wurden welche zeitgesteuert die Protokolleintraumlge wieder loumlschen Fuumlr Bayern wurde ein spezielles Konzept zur Leseprotokollierung entworfen Wenn Sie mehr daruumlber erfahren moumlchten kontaktieren Sie bitte die BALVI GmbH
ltEnvironment
name=enableSqlStatementMonitoring
value=true
type=javalangBoolean
override=true
gt
Beachten Sie dass diese Option massive INSERT-Statements in BALVI iP in die Tabelle VIS_D92 ausfuumlhrt Jedes abgesetzte SQL-Statement wird dabei vollstaumlndig protokolliert Dieses erzeugt eine sehr hohe INSERT-Last und in der Folge auch erhoumlhte Redolog-Switches und COMMIT-Transaktionen
Optional Aktivieren der INSERT + APPEND - Logik
Beachten Sie bitte die Hinweise von Oracle zum Hint + APPEND
Release Notes BALVI Schnittstellenserver Seite 23 von 37
Wenn Sie dieses Verhalten aktivieren moumlchten ergaumlnzen Sie bitte den folgenden Environment-Parameter
ltEnvironment
name=statementMonitoringactivateAppendMode
value=true
type=javalangBoolean
override=true
gt
2515 Einstellungen fuumlr BALVI mobil XT (bzw den bdquopartitionedExportldquo)
Diese Logik des FIFO-Buffers wurde so konzipiert dass dem Rechenzentrum diverse Einstellmoumlglichkeiten uumlber die Datei bdquocontextxmlldquo zur Verfuumlgung stehen um die Steuerung des FIFO-Puffers zu beeinflussen
Schematische Darstellung des FIFO-Puffers
Das ermoumlglicht es z B dem BALVI mobil XT Client (14 oder houmlher) den aktiven Block abzuholen und dies beim Fehler bis zu 10-mal zu wiederholen Sobald der Block [001] erfolgreich beim Client angekommen ist und dieser den naumlchsten Block anfragt wird der Block [001] verworfen wird Der Server fuumlllt dann im Hintergrund den frei gewordenen Block wieder waumlhrend der Client den Block [002] abholt
Die Groumlszlige und Anzahl der vorgecachten Bloumlcke kann uumlber die folgenden Einstellungen in der Datei bdquocontextxmlldquo definiert werden
ltEnvironment
name=partitionedExportmaxBufferedPartitions
value=3 type=javalangInteger override=true
gt
ltEnvironment
name=partitionedExportpartitionSize
value=256000 type=javalangInteger override=true
gt
Die Einstellung partitionedExportmaxBufferedPartitions ist dabei die Anzahl der vorgecachten Bloumlcke mindestens muss 2 angegeben werden Der Puffercache wird ausschlieszliglich im RAM der JVM aufgebaut es wird folglich mehr Arbeitsspeicher verwendet Dieser Arbeitsspeicher muss je gleichzeitiger Session auf dem Server bereitgestellt werden die Default-Einstellung mit 3 Partitionen a 256 KB + dem aktiven Puffer erfordern 1 MB RAM je aktiven Anwender
Aktiv
er
Puffe
r
[001] Vorg
ecac
hter
Bl
ock
[002] Vorg
ecac
hter
Bl
ock
[003]
Aktiv
er P
uffe
r
[002] Vorg
ecac
hter
Bl
ock
[003] Vorg
ecac
hter
Bl
ock
[leer]
Release Notes BALVI Schnittstellenserver Seite 24 von 37
Gleichzeitig wurde die Moumlglichkeit geschaffen dass die maximale Anzahl an gleichzeitigen Exporten durch das Rechenzentrum eingeschraumlnkt werden kann um einem OutOfMemory-Fehler vorzubeugen Die Einstellung
ltEnvironment
name=partitionedExportmaxConcurrentExports
value=10 type=javalangInteger override=true
gt
muss entsprechend der zu erwartenden gleichzeitigen Zugriffe konzipiert werden ansonsten wird der Server einen Verbindungsversuch durch die Clients ablehnen
Beachten Sie dass die folgenden Einstellungen partitionedExportmaxBufferedPartitions partitionedExportmaxConcurrentExports und partitionedExportpartitionSize gemeinsam als Rechenbasis fuumlr den RAM-Bedarf des Webservers herangezogen werden muumlssen
Folgende Faustformel sollte fuumlr die Einrichtung verwendet werden
Min 256 MB (Serverbasis) + (11 partitionedExportmaxConcurrentExports partitionedExportmaxBufferedPartitions partitionedExportpartitionSize)
Beispiel 50 gleichzeitige Anwender Blockgroumlszlige 256 KB 4 Partitionen
256 MB + (11 50 256 4) KB = 312 MB fuumlr die JVM
Empf 512 MB (Serverbasis) + (12 partitionedExportmaxConcurrentExports partitionedExportmaxBufferedPartitions partitionedExportpartitionSize)
Beispiel 50 gleichzeitige Anwender Blockgroumlszlige 256 KB 4 Partitionen
512 MB + (12 50 256 4) KB = 572 MB fuumlr die JVM
partitionedExportmaxConcurrentExports
Bestimmt die Anzahl der maximalen Export Tasks (Threads) die fuumlr partitionierte Exporte bereitgestellt werden Wenn die Anzahl uumlberschritten wird wird die entsprechende Exportanfrage abgewiesen und der Client muss zu einem spaumlteren Zeitpunkt erneut anfragen Stellen Sie diesen Wert entsprechend der zu erwartenden Benutzeranzahl ein bei 50 Anwendern also 50
Exporte oumlffnen auf der Datenbank entsprechend zur Ausfuumlhrungszeit min einen Cursor ggf fuumlr rekursive Unterabfragen kurzfristig sogar mehr Die hier eingestellte Anzahl muss mit der Anzahl von maxActive korrelieren
ltEnvironment
name=partitionedExportmaxConcurrentExports
value=10 type=javalangInteger override=true
gt
partitionedExportmaxBufferedPartitions
Bestimmt die Anzahl der Datenbloumlcke (Partitionen) die vom Server bei Abruf eines Exportes gepuffert werden Die seit Version 24 eingefuumlhrte FIFO-Puffer-Logik ermoumlglicht dass der Server schon die Ergebnisse vorpuffert so dass der Client weniger Wartezeiten bei der Anfrage nach Daten hat Diese
Release Notes BALVI Schnittstellenserver Seite 25 von 37
Puffer-Logik unterteilt den Exportdatenstrom (je Export) in mehre Bloumlcke Der Client kann nun den letzten Block neu anfordern oder den naumlchsten Block wenn der letzte Block erfolgreich verarbeitet wurde Wie viele naumlchste Bloumlcke durch den Server bereit gestellt werden entscheidet diese Einstellung Sobald kein naumlchster Block mehr bereit gestellt werden muss wird der Datenbank-Cursor geschlossen eine Erhoumlhung kann also zu einer Entlastung der aktiven DB-Verbindungen fuumlhren erhoumlht jedoch den Bedarf an RAM des Servers
Der von BALVI voreingestellte Wert ist 3
ltEnvironment
name=partitionedExportmaxBufferedPartitions
value=3 type=javalangInteger override=true
gt
partitionedExportpartitionSizeldquo
Die Groumlszlige der Datenbloumlcke (Partitionen) die an den Client uumlbermittelt werden in Bytes Wenn Sie diesen Wert zu niedrig einstellen reduziert sich die Effizienz des Caches da der Client mehr Datenbloumlcke hintereinander abrufen muss Waumlhlen Sie einen zu groszligen Wert wird die neu zu uumlbertragende Datenmenge im Fall eines Fehlers houmlher
Der von BALVI voreingestellte Wert ist 256000 (256 KB)
ltEnvironment
name=partitionedExportpartitionSize
value=256000 type=javalangInteger override=true
gt
exportTokensmaxTokenCount
Maximale Anzahl der gleichzeitig vergebenen Token die vom Server gecached werden Jede Sitzung welche einen Export durchfuumlhrt erhaumllt einen Session-Token
Wenn eine Sitzung laumlngere Zeit nicht verwendet wurde wird dieser Session-Token wieder entfernt Wenn Sie den Wert zu niedrig einstellen fuumlhrt das zu einer generellen Session-Begrenzung auch fuumlr den nicht partitionierten Export-Modus welcher ab Version 21 verfuumlgbar ist
Ist die Anzahl der Tokens houmlher als die Datenbankeinstellung maxActive kann es vorkommen dass zwar eine Session gestartet werden kann jedoch kein Datenexport zustande kommt
Der von BALVI voreingestellte Wert ist 2000
ltEnvironment
name=exportTokensmaxTokenCount
value=20 type=javalangInteger override=true
gt
exportTokenstokenExpirationInSeconds
Zeit in Sekunden die verstreichen muss bis ein Token unguumlltig wird falls darauf kein Zugriff mehr erfolgt Nach einem erfolgreichen Export wird der Token automatisch geschlossen diese Option ist fuumlr den Abbruchfall vorgesehen Der von BALVI voreingestellte Wert ist 180 (180 s = 3 min)
Release Notes BALVI Schnittstellenserver Seite 26 von 37
ltEnvironment
name=exportTokenstokenExpirationInSeconds
value=180 type=javalangInteger override=true
gt
exportTokenstokenDisposalInSeconds
Zeit in Sekunden die verstreichen muss bis ein Token das erfolgreich abgearbeitet wurde aus dem Cache geloumlscht wird Um sicher zu stellen dass der letzte Exportblock noch erfolgreich abgerufen werden kann bleibt der Token auch nach Fertigmeldung des Clients noch N Sek guumlltig
Der von BALVI voreingestellte Wert ist 60 (60 s = 1 min)
ltEnvironment
name=exportTokenstokenDisposalInSeconds
value=60 type=javalangInteger override=true
gt
2516 Job-Verwaltung fuumlr den BSS konfigurieren Aktivierung der Jobverwaltung
Bis zur Version 28 des BSS gab es den Parameter bdquoavailableServicesldquo Dieser konnte bei Bedarf aktiviert werden wenn die Jobs benoumltigt wurden
Mit Version 30 ist die Einstellung bdquoavailableServicesldquo zu entfernen und kann durch den neuen optionalen Parameter bdquoisJobServiceEnabledldquo in der Datei bdquocontextxmlldquo ersetzt werden
lt-- Neue Parameter zur Aktivierung des Job Service Ersatz fuumlr availableServices --gt
ltEnvironment
name=isJobServiceEnabled
value=true
type=javalangBoolean
override=true
gt
Ab BSS 30 wird die Jobs-Engine standardmaumlszligig aktiviert Sollte die Jobs-Engine nicht benoumltigt werden muss bdquovalueldquo der Wert bdquofalseldquo zugewiesen werden Wird bdquoisJobServiceEnabledldquo nicht eingefuumlgt sind die Jobs trotzdem standardmaumlszligig aktiv
Nach dem Neustart des Servers und erneutem Einloggen erscheint nun zusaumltzlich der Menuumlpunkt bdquoJobsldquo
bdquopasswordKeyldquo fuumlr Jobs
In der Job-Logik wird ein von BALVI definierter Standard-Schluumlssel fuumlr die Ablagen von schuumltzenswerten Daten z B Passwoumlrtern verwendet Diese Einstellung ermoumlglicht den BALVI-Standard zu uumlberschreiben Wenn Sie diese Einstellung aumlndern muumlssen jedoch alle bislang verschluumlsselten Job-Parameter neu verschluumlsselt werden
ltEnvironment
name=javacompenvjobspasswordKey
value=MeinHochsicheresNeuesPasswort
type=javalangString
Release Notes BALVI Schnittstellenserver Seite 27 von 37
override=true
gt
bdquoJob ID enableddisabledldquo (Deprecated ersetzt ab 28 durch das bdquoBindenldquo von Jobs)
Sondereinstellungen fuumlr die Job-Verwaltung Da alle Jobs in einer Datenbank administriert werden jedoch ggf verteilt auf mehreren Tomcat-Servern ausgefuumlhrt werden sollen besteht hier die Option Jobs fuumlr die aktuelle Tomcat-Instanz separat zu deaktivieren
Die Einstellung ID koumlnnte z B folgendermaszligen aussehen javacompenvjobsC0DB58D8D52C4BBC966D1DC788A4EF8Benabled
Fuumlr weitere Fragen zu dieser Einstellung kontaktieren Sie bitte die BALVI GmbH
ltEnvironment
name=javacompenvjobsIDenabled
value=false
type=javalangBoolean
override=true
gt
2517 Weitere optionale Parameter
Es ist fuumlr diverse einzelne Schnittstellen ggf erforderlich Einstellungen in der Datei bdquocontextxmlldquo zu ergaumlnzen Hinweise zu diesen Parametern sind dann in dem der Schnittstelle beiliegenden Dokument enthalten Das gilt z B fuumlr die Schnittstelle bdquoXGewerbeanzeigenldquo
26 Logging mit logback Das Logging wurde komplett uumlberarbeitet Statt bdquoLog4Jldquo wird jetzt bdquologbackldquo4 benutzt Ab BSS 30 ist es zwingend notwendig die Einstellung vorzunehmen um das Logging der Anwendung zu steuern
Migration Ergaumlnzen Sie die neue Einstellung bdquologgingconfigldquo
lt-- Neue Paramter zur Angabe der Logback Config Ersatz fuumlr log4jConfigLocation --gt
ltEnvironment
name=loggingconfig
value=$catalinabaseconflogback-bssxml
type=javalangString
override=true
gt
Nach wie vor steht es Ihnen frei die Logging-Konfiguration eigenstaumlndig anzupassen
Wenn Sie jedoch dieselbe WAR in einer Tomcat-Instanz unter mehreren Context-Namen betreiben wuumlrden beide dieselbe Logging-Konfiguration verwenden so dass alle Protokolleintraumlge in einer Log-Datei aus
4 httplogbackqoschmanualappendershtml
Release Notes BALVI Schnittstellenserver Seite 28 von 37
mehreren Webanwendungen generiert werden Aumlndern Sie den Namen der Logging-Konfiguration entsprechend ab um fuumlr jede Anwendung eine spezifische Logging-Einstellung vornehmen zu koumlnnen
27 Tocmat Optional Suche im bdquoKlassenpfadldquo um den
Ordner bdquoconfldquo erweitern Die Suche nach Dateien uumlber bdquoclasspathldquo setzt voraus dass die Ordner- und Dateinamen im Apache Tomcat bekannt gegeben werden Der Klassenpfad kann in der Datei bdquocatalinapropertiesldquo angepasst werden Wenn Sie dort unter commonloader die folgenden Werte ergaumlnzen kann eine Datei auch im Ordner conf abgelegt werden damit Apache Tomcat diese findet Ansonsten muss die Datei im Ordner lib abgelegt werden
commonloader=$catalinabaseconf$catalinahomeconf
3 Die neue Browser-Oberflaumlche Der BALVI Schnittstellenserver hat seit Version 25 neben der Protokollierung auch die Moumlglichkeit Job-Konfigurationen zu pflegen Der Login ist nur fuumlr einen in BALVI iP eingetragenen ADMIN (z B Benutzer bdquoSYSTEMADMINldquo) mit dem in BALVI iP hinterlegten Passwort moumlglich Zur Anmeldung muss immer [SYSTEMBenutzername] im Feld Benutzer angegeben werden ansonsten schlaumlgt die Anmeldung fehl Bitte achten Sie darauf dass der bdquoldquo (Slash) und nicht der bdquoldquo (Backslash) verwendet werden muss
31 Server-Protokoll Um das Server-Protokoll anzuzeigen waumlhlen Sie den entsprechenden Menuumlpunkt Dort haben Sie seit BSS 26 die Moumlglichkeit uumlber alle Spalten der Protokolle nach Informationen zu suchen
Seit BSS 31 gibt es die Moumlglichkeit Verfahren in bdquoKopfsaumltzeldquo und bdquoDetailsaumltzeldquo zu unterteilen Wurde das Verfahren entsprechend konfiguriert (wie z B bei der Schnittstelle bdquoXGewerbeanzeigenldquo) dann wird im Protokoll-Kopfsatz nur der Start und das Ende der Ausfuumlhrung in der Liste angezeigt Erst bei einem Klick auf bdquoInformationenldquo wird die Liste aller Detailsaumltze angezeigt die im Durchlauf erzeugt wurden
Release Notes BALVI Schnittstellenserver Seite 29 von 37
Verfahren
Die Liste der verfuumlgbaren Verfahren die bei Ihnen im System installiert sind ZB
BEFUNDEhellip Schnittstelle Befunde LM FM oder TS
PROBEhellip Schnittstelle zum Export von Proben an Labore ebenfalls Spezifisch fuumlr einzelne Fachbereiche
MOBILXT Protokolle der BALVI Mobil XT Synchronisation
WEB Allgemeine nicht spezifizierte Protokolle hierunter ist bislang auch die eFi-Protokollierung zu finden
WEB_I0802 Protokolle zur Schnittstelle BALVI iP LIMS (Lebensmittelproben)
XGEWERBE Schnittstelle XGewerbeanzeigen
Klicken Sie auf die Schaltflaumlche so besteht bei den neuen Protokolldatensaumltzen die Moumlglichkeit Detail-Informationen zum Protokollsatz zu erhalten
Release Notes BALVI Schnittstellenserver Seite 30 von 37
Seit BSS 30x ist die Anzeige der Protokolle ebenfalls farblich abgesetzt so dass Protokolleintraumlge mit Fehlern hellrot und Warnungen hellgelb hinterlegt werden
32 Jobs Mit einem Klick auf den Menuumlpunkt Jobs rufen Sie die Oberflaumlche fuumlr die Job-Konfiguration auf Daraufhin werden alle Jobs aufgelistet die fuumlr den BSS freigegeben sind Hier koumlnnen Sie Einstellungen an den Jobs vornehmen und die Jobs aktivieren bzw deaktivieren Die Beschreibungen bzw Einstellungsmoumlglichkeiten fuumlr den jeweiligen SST-Job sind nicht Bestandteil dieser Dokumentation
33 Log-Ausgaben Uumlber den Menuumlpunkt Log-Ausgaben koumlnnen Sie die Ausgabe der Protokolleintraumlge in Echtzeit beobachten
Release Notes BALVI Schnittstellenserver Seite 31 von 37
Starten Sie die Echtzeit-Protokollierung indem Sie auf die Schaltflaumlche mit dem Symbol bdquoPlayldquo (Dreieck) klicken unterbrechen Sie die Ausgabe indem Sie die auf Schaltflaumlche mit dem Symbol bdquoPauseldquo (zwei Balken) klicken
Klicken Sie auf die Schaltflaumlche bdquoAktualisierenldquo (zwei Pfeile) um die neuesten Protokolleintraumlge angezeigt zu bekommen
Klicken Sie auf das Symbol mit dem Papierkorb um die letzten Protokollmeldungen in der Anzeige zu loumlschen
Die Daten in den Protokolldateien auf der Festplatte des Servers sind davon nicht betroffen
Uumlber das Symbol bdquoLogging anpassenldquo (Schraubenschluumlssel) koumlnnen Sie die Ausgabe der Daten im Echtzeitfenster und in den Protokolldateien aumlndern jedoch ist diese Einstellung nur temporaumlr Die Standardeinstellungen koumlnnen ausschlieszliglich uumlber die Anpassung der Datei bdquologback-bssxmlldquo im Konfigurationsverzeichnis des Servers selbst geaumlndert werden
Release Notes BALVI Schnittstellenserver Seite 32 von 37
In der Logging-Parameter Konfiguration koumlnnen Sie verschiedene Parameter einstellen und uumlber die Schaltflaumlche bdquoAnwendenldquo dann sofort im Echtzeitprotokoll sehen Welche Einstellungen moumlglich sind erfahren Sie wenn es eine akute Fehlersituation gibt die detailliertere Ausgaben im Protokoll erfordert
Warnung Wenn Sie den Log-Level fuumlr ROOT oder eine andere Klasse auf TRACE einstellen werden sehr viele Protokollausgaben generiert die auch dazu fuumlhren koumlnnen dass der Server sehr langsam wird oder die Festplatte des Servers zulaumluft wenn fuumlr das Logging kein Dateilimit konfiguriert wurde
34 LogoutAbmeldung vom System Zum Abmelden waumlhlen Sie oben rechts das Kontextmenuuml
35 Cache loumlschen Der Cache wird in der Regel automatisch geloumlscht Wenn Sie jedoch gerade in BALVI iP eine Aumlnderung an den Schnittstellen eingespielt haben und moumlchten dass diese sofort wirksam wird kann die Funktion bdquoCache loumlschenldquo dazu verwendet werden dass der BALVI Schnittstellenserver die Einstellungen bei der naumlchsten Anfrage neu einliest
Release Notes BALVI Schnittstellenserver Seite 33 von 37
Release Notes BALVI Schnittstellenserver Seite 34 von 37
4 Einrichtung in BALVI iP Um die Verfahren fuumlr den BALVI Schnittstellenserver fuumlr Anwender freizuschalten wird das Objekt bdquoSystemeinstellungenldquo oder bdquoMandanten- und Benutzereinstellungenldquo verwendet Die Anpassung ist je Verfahren moumlglich so kann in BALVI iP fuumlr den Zugriff durch den BALVI Schnittstellenserver ein Benutzer bdquoAldquo am Verfahren bdquoMobilldquo berechtigt werden ein Benutzer bdquoBldquo nur am Verfahren bdquoSLA_FLESHldquo usw Die Logik ist jedoch einheitlich Je Verfahren wird durch BALVI eine Verfahrensgruppe mit dem Verfahrensnamen angelegt und mit den entsprechenden Einstellungen vorkonfiguriert welche durch das Verfahren erforderlich sind Dabei kann die Komplexitaumlt der Einstellungen variieren wie z B an den zu Version 23 verfuumlgbaren Verfahren bdquoMobilldquo und bdquoSLA_Fleshldquo ersichtlich wird
Im Verfahren BALVI Mobil sind diverse Anpassungen moumlglich welche je Bundesland oder eingesetzter Import- und Export-Variante durch den BALVI Schnittstellenserver bei der Bearbeitung von Anfragen gepruumlft werden siehe Punkt 3 Abb Mobil-Einstellung in BALVI iP
Abb Mobil-Einstellung in BALVI iP
Alle Verfahren verwenden jedoch die regulaumlre Benutzerverwaltung von BALVI iP Ein Benutzer ohne Passwort gilt fuumlr BALVI iP als gesperrt was fuumlr das Login bedeutet dass der Anwender sich nur uumlber die Active-Directory-Authentifizierung anmelden kann Ist das nicht moumlglich (bzw nicht konfiguriert) kann der Anwender sich weder in BALVI iP noch uumlber die Webservice-Schnittstelle authentifizieren
Fuumlr Dienste-Schnittstellen welche keine persoumlnliche Authentifizierung durch einen Anwender erfordern wird empfohlen einen separaten Benutzer in der Benutzerverwaltung anzulegen und ein sicheres Kennwort zu vergeben Das Anlegen von zusaumltzlichen Benutzern gilt nicht fuumlr BALVI mobil XT da beim Holen und Uumlbermitteln von Daten jeder Benutzer auch ein fachlich konfigurierter Anwender innerhalb von BALVI iP ist und die Anwendungsoberflaumlche ebenfalls zur Erfassung von Daten verwendet
Unter Punkt 2 der Abb Mobil-Einstellung in BALVI iP wird ein modales Fenster geoumlffnet (Abb BALVI mobil Benutzerverwaltung) Innerhalb dieses modalen Fensters werden mandantenweise die Benutzer fuumlr BALVI
Release Notes BALVI Schnittstellenserver Seite 35 von 37
mobil und den jeweiligen Fachbereich festgelegt Dabei ist es wichtig dass man die Haken bdquoAktiv fuumlr hellipldquo bei bdquohellip mobilldquo und bei einem Fachbereich (bdquohellip LMldquo bdquohellip FMldquo usw) setzt weil sonst uumlber den BALVI Schnittstellenserver keine Kommunikation mit BALVI iP moumlglich ist
Abb BALVI mobil Benutzerverwaltung
Alternativ zur Passwort-Authentifizierung wird wie beschrieben auch die Active-Directory-Authentifizierung angeboten Dazu muss der BALVI iP-Anwender uumlber die Schaltflaumlche bdquoDomaumlnen-Benutzer zuordnenldquo mit dem Active Directory verknuumlpft werden
Nur wenn die Active-Directory-Konfigurationen in BALVI iP und im BALVI Schnittstellenserver auf dieselbe Domaumlne verweisen sind die Domaumlnen-Zuordnung und die Active-Directory-Authentifizierung (z B uumlber BALVI mobil XT) moumlglich
Release Notes BALVI Schnittstellenserver Seite 36 von 37
5 Bekannte Probleme und Loumlsungen
51 ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner Bei der Job-Bearbeitung tritt folgender Fehler auf ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner
Behebung
Fuumlhren Sie das beiliegende IP-Patch (UPDATEexe) aus bevor Sie das WAR austauschen
52 Server startet nicht Sie finden folgende Zeilen im Protokoll (catalinaout oder bsslog)
ERROR [localhost-startStop-1] [IdentityServiceImpl] serverID must not be empty
ERROR [localhost-startStop-1] [ContextLoader] Context initialization failed
Behebung
Setzen Sie die Umgebungsvariable ldquoserverIDrdquo in der Datei bdquocontextxmlldquo
53 ORA-00942 table or view does not exist In vielen Faumlllen wird der Fehler ldquoTabelle oder View nicht vorhandenrdquo ausgeworfen (Java-Protokoll im Ordner logs von Apache Tomcat) wenn eine neue Schnittstelle eingerichtet oder ein neues BALVI iP Release bzw Update eingespielt wurde ohne anschlieszligend das aktuelle GRANT-Skript auszufuumlhren
Behebung
Fuumlhren Sie das GRANT-Skript erneut aus
54 ORA-0406x bdquoBestehender Paketstatus wurde aufgehobenldquo
ORA-04061 Bestehender Status von package body ABCXYZ wurde annulliert
ORA-04065 Ausfuumlhrung nicht erfolgreich package body ABCXYZ wurde geaumlndert oder geloumlscht
Release Notes BALVI Schnittstellenserver Seite 37 von 37
Der Fehler tritt haumlufig ein nachdem die UPDATEexe ausgefuumlhrt und in der Ausfuumlhrungsliste ein Package aktualisiert wurde Oracle merkt sich je User-Session bestimmte Werte im Package wenn der Anwender es verwendet hat Durch einen bdquoCREATE OR REPLACE PACKAGEldquo-Befehl kann dieser Status temporaumlr aufgehoben werden Normalerweise tritt dieser Fehler nach dem Update genau einmal in jeder aktiven Session auf wenn der BSS nicht neu gestartet wird
Behebung
Starten Sie nach jedem Update den BSS neu um alle laufenden Sessions zu beenden
55 Jobs sind nicht ausfuumlhrbar
1 Ein Job wird mit dem Status bdquoNicht unterstuumltztldquo angezeigt wenn fuumlr seine Ausfuumlhrung eine houmlhere Version des BSS erforderlich ist
2 Nach dem Klonen der Datenbank von der Produktions- auf die Testumgebung erhalten alle Jobs automatisch den Status bdquoDeaktiviertldquo wenn die bdquoserverIDldquo nicht identisch ist
Beide Statusaumlnderungen sind gewollt Damit soll verhindert werden dass Jobs nach einem Serverneustart oder nach einem Update automatisch starten und dabei Fehler verursachen
Um Jobs mit dem Status bdquoNicht unterstuumltztldquo nutzen und konfigurieren zu koumlnnen ist es erforderlich den BALVI Schnittstellenserver zu aktualisieren
Deaktivierte Jobs koumlnnen Sie aktivieren indem Sie den jeweiligen Job an den aktuellen Server binden und den Haken bei bdquoAktivldquo setzen
Release Notes BALVI Schnittstellenserver Seite 17 von 37
-- fuumlr das Loumlschen der Ausgangskoumlrbe explizit zu berechtigen bzw sogar einen
-- expliziten abweichenden User festzulegen Die Konfiguration in der
-- Job-Oberflaumlche sieht vor dass man die Oracle-Datenbank-Zugangsdaten fuumlr
-- das Loumlschen einstellen muss Hier muss im Normalfall derselbe Oracle
-- Datenbankbenutzer eingetragen werden wie in der Tomcat-Verbindungs-
-- konfiguration In diesem Fall sollte wenn WS_EFI = 1 eingestellt wurde
-- ebenfalls WS_EFI_DELETE = 1 eingestellt werden
-- Alternativen
-- 1) Datenbankbenutzer aumlndern
-- Wenn bei sUserEFI_TRUNC anstatt sUserBALVI_WEB (Standard) ein anderer
-- Oracle-Benutzername angegeben wird wird das Loumlschrecht fuumlr die EFi
-- Ausgangskoumlrbe Datenbankseitig exklusiv dem angegeben Datenbankbenutzer
-- zugewiesen
-- 2) Loumlschrecht verweigern
-- Setzen Sie die Variablen WS_EFI_DELETE = 0 damit kein Loumlschrecht
-- zugeweisen wird
WS_EFI_DELETE = 0
-- Beispiel Anderer Benutzer muss in der Datenbank existieren
-- Entfernen Sie die fuumlhrenden -- vor der Variable sUserEFI_TRUNC und
-- setzen den entsprechenden Oracle-Benutzer ein
--sUserEFI_TRUNC = TEST_EFI_TRUNC
hellip
25 Konfiguration des Schnittstellen-Servers
251 Die bdquocontextxmlldquo-Parameter Die von der Servlet-Spezifikation vorgegeben Rump-Struktur sieht folgendermaszligen aus
ltxml version=10 encoding=utf-8gt
ltDOCTYPE Contextgt
ltContextgt
lt-- Kundenspezifische Einstellungen --gt
ltContextgt
Anwendungsspezifische Einstellungen werden zwischen ltContextgt und ltContextgt eingefuumlgt Alle allgemeinguumlltigen Einstellungen in der Datei bdquocontextxmlldquo werden hier erlaumlutert Kommentare finden sich auch in der von BALVI ausgelieferten Beispiel-Konfiguration
Neben den im Folgenden beschriebenen Standard-Einstellungen kann es auch vorkommen dass bundeslandspezifische Erweiterungen vorhanden sind welche nicht in dieser Dokumentation aufgefuumlhrt werden Diese funktionieren trotzdem regulaumlr weiter wenn keine expliziten Informationen zu Kompatibilitaumltsproblemen in den Release-Notes aufgefuumlhrt wurden
2511 Datenbankverbindung jdbcDataSource
Die Datenbankverbindung wird uumlber die von DBCP und dem Oracle-Treiber vorgegebenen Moumlglichkeiten realisiert Der Einsatz der orgapachetomcatjdbcpoolDataSourceFactory (automatisch verfuumlgbar ab Apache Tomcat 7 in der mitgelieferten tomcat-dbcpjar) wird als Beispiel-Konfiguration ausgeliefert
ltResource
name=jdbcDataSource
auth=Container
Release Notes BALVI Schnittstellenserver Seite 18 von 37
type=javaxsqlDataSource
factory=orgapachetomcatjdbcpoolDataSourceFactory
maxActive=10 initialSize=3
maxIdle=5
maxWait=10000
url=jdbcoraclethinBL2-ORA10-KUNDENBALVIINTERN1521ORCL
driverClassName=oraclejdbcdriverOracleDriver
username=balvi_webservice_schema
password=balvi_webservice_password
description=Oracle Datasource
maxOpenPreparedStatements=50
removeAbandoned=false
removeAbandonedTimeout=100
logAbandoned=true
jdbcInterceptors=hellip
gt
Hinweise zur Einstellung der jdbcDataSource
Standard-Einstellungen fuumlr den Datenbank-Verbindungspool
Der Verbindungspool muss entsprechend der Anzahl der zu erwartenden gleichzeitigen Benutzer konfiguriert werden Wenn Sie erwarten dass 50 Anwender gleichzeitig arbeiten stellen Sie bitte folgende Werte ein
maxActive=(50 + 10 (fuumlr System und Jobs)) = 60
maxIdle= (50 10) = 5
1 maxActive - maximale Anzahl der gleichzeitigen aktiven Anfragen an die DB
Wenn der Werte maxActive erreicht ist z B wenn mehrere Benutzer gleichzeitig einen Export starten moumlchten welcher laumlngere Zeit in Anspruch nimmt dann kann der Server die Anfrage nicht mehr bedienen und der Anwender wird abgewiesen maxActive hat zudem Auswirkungen auf die im Hintergrund ausgefuumlhrten Jobs maxActive wird daher kalkuliert mit der Anzahl der Anwender und moumlglicher Datenbank-Connections fuumlr Hintergrund-Jobs Jeder aktiv ausgefuumlhrte Job benoumltigt mindestens eine Connection nur selten wird aus Performance-Gruumlnden mehr als eine Connection waumlhrend der Job-Ausfuumlhrung verwendet Im Normalfall sollten daher 10 Connections fuumlr Hintergrundprozesse ausreichend sein
2 maxIdle - Anzahl der offenen Verbindungen auch wenn der Server im Leerlauf ist
Jede offene Verbindung im Leerlauf haumllt auf dem Datenbankserver eine Session offen Auch diese erfordert Ressourcen Wenn die Verbindungen jedoch geschlossen werden kann die Anfragezeit fuumlr eine neue Verbindung steigen da diese Verbindung erst neu ausgehandelt werden muss Die Empfehlung fuumlr den Wert bdquomaxIdleldquo ist ca 10 der Einstellung von maxActive
KeepAlive-Einstellungen fuumlr den Pool
1 validationQuery
Diese wird ausgefuumlhrt um die Verbindung zu DB zu validieren Es MUSS ein Datensatz zuruumlckgegeben werden ansonsten nimmt der DBCP an dass die Abfrage nicht erfolgreich abgesetzt wurde Achten Sie also bitte darauf dass die Abfrage nicht zu leitungsintensiv ist und genau einen Datensatz liefert
Release Notes BALVI Schnittstellenserver Seite 19 von 37
Oracle bietet dafuumlr die virtuelle Tabelle DUAL an welche sich fuumlr die ValidationQuery sehr gut eignet da die Abfrage kaum Ressourcen verbraucht
validationQuery=select 1 from dual
2 testOnBorrow - Boolscher Wert true oder false
Diese Einstellung sorgt dafuumlr dass der Pool die Verfuumlgbarkeit anhand der validationQuery pruumlft bevor
die DB-Verbindung an die Anwendung ausgeliehen wird Empfehlung
testOnBorrow=true
3 testWhileIdle - Boolscher Wert true oder false
Diese Einstellung ist hilfreich wenn zwischen dem Tomcat und der DB eine Firewall mit Stateful
Packet Inspection verwendet wird Nach laumlngerer Inaktivitaumlt wird normalerweise durch die Firewall die
DB-Verbindung geschlossen Dieses loumlst dann beim Ausleihen der Verbindung eine Fehlermeldung im
Protokoll aus 2012-08-16 165418720 WARN [http-0000-8080-8]
[orgspringframeworkjdbcsupportSQLErrorCodesFactory] Error while extracting
database product name - falling back to empty error codes
orgspringframeworkjdbcsupportMetaDataAccessException Error while extracting
DatabaseMetaData nested exception is javasqlSQLRecoverableException Getrennte
Verbindung Um dieses Problem zu beheben sollte die Option testWhileIdle=true eingestellt werden
testWhileIdle=true
Damit diese weiszlig wie oft eine Pruumlfung durchgefuumlhrt werden muss sind jedoch noch zusaumltzliche Angaben erforderlich welche fuumlr die Einstellung der Zeit zusaumltzlich gesetzt werden muumlssen
a) minEvictableIdleTimeMillis - Long in Millisekunden
Min Zeit wie lange eine DB-Verbindung im Leerlauf ist bevor diese zur Pruumlfung
gekennzeichnet wird Dieses haumlngt stark von der Einstellung der Firewall ab Wenn Sie eine
sehr restriktive Firewall haben kann es sein dass diese die Verbindung nach wenigen
Minuten Leerlauf trennt Stellen Sie den Wert immer so ein dass dieser unter der Leerlaufzeit
der Firewall liegt empfohlen 300000 entspricht 300 Sek = 5 min
minEvictableIdleTimeMillis=300000
b) timeBetweenEvictionRunsMillis - Long in Millisekunden
Der Pruumlflauf startet in der Default-Konfiguration alle 1800000 Millisekunden = 30 Min n als
zu Pruumlfen markierte Verbindungen werden in einem Pruumlflauf getestet n wird bestimmt durch
die Einstellung numTestsPerEvictionRun Empfehlung Stellen Sie den Wert auf alle 15 Min
ein
timeBetweenEvictionRunsMillis=900000
Release Notes BALVI Schnittstellenserver Seite 20 von 37
c) numTestsPerEvictionRun - Integer
Wie viele Verbindungen sollen getestet werden waumlhrend der Pruumlflauf ausgefuumlhrt wird Im
Normalfall sollte die Anzahl der zu testenden Verbindungen nicht zu hoch eingestellt werden
Der Default ist 3 Wenn Sie houmlhere Sicherheit haben wollen dass keine bdquototenldquo
Datenbankverbindungen bestehen bleiben erhoumlhen Sie den Wert auf max bdquo(maxActive ndash
maxIdle) 2ldquo Wenn Ihnen 3 ausreichend erscheint muss der Wert nicht gesetzt sein dann
wird der Default verwendet
Beispiel numTestsPerEvictionRun=10
4 Interceptors konfigurieren Neu ergaumlnzt wurde die Moumlglichkeit spezielle bdquoInterceptorsldquo zu konfigurieren die ermoumlglichen das Verhalten des Pools zu steuern Wichtig hierbei ist dass die Angabe von Werten auf real existierende Java-Klassen erfolgt die im Classpath des Tomcat vorhanden sind Groszlig-und-Kleinschreibung ist zu beachten Folgende Default-Einstellung hat BALVI fuumlr den BSS festgelegt jdbcInterceptors=
orgapachetomcatjdbcpoolinterceptorConnectionState
orgapachetomcatjdbcpoolinterceptorStatementFinalizer
orgapachetomcatjdbcpoolinterceptorResetAbandonedTimer
Details zu den verwendeten Interceptor-Einstellungen finden Sie in der Tomcat-Dokumentation3
3 httptomcatapacheorgtomcat-80-docjdbc-poolhtmlJDBC_interceptors
Release Notes BALVI Schnittstellenserver Seite 21 von 37
2512 Datenbank-Zugangsdaten verschluumlsseln
Die Verschluumlsselung fuumlr die Datenbank-Verbindung (bdquoEncrypted Datasourceldquo) ist eine Ableitung der Bibliothek Apache-Common-DBCP-14 und daher nicht mehr mit Java 8 kompatibel Die Einrichtung der Verschluumlsselung wird daher mit der Auslieferung des BSS 30 nicht mehr angeboten
2513 Active-Directory-Authentifizierung
Uumlber die folgenden Parameter wird der Zugriff des Schnittstellen-Servers auf einen Microsoft Active Directory Domain-Controller konfiguriert
ldquoldapServerAddressrdquo
Syntax PROTOKOLLIP-Adresse oder DNS-NamePORT
ltEnvironment
name=ldapServerAddress
value=ldapbl2-dc02balviintern389
type=javalangString
override=true
gt
Als Protokoll besteht auch die Moumlglichkeit ldaps (LDAP+SSL) wenn der Domain-Controller entsprechend konfiguriert wurde Im Java Truststore muss dann das Zertifikat der CA vorhanden sein welche das Zertifikat des Domain-Controllers signiert hat Zudem darf bei ldaps keine IP-Adresse verwendet werden es muss der DNS-Name des Server-Zertifikats eingetragen sein Ansonsten gibt es beim Verbinden eine Sicherheits-Exception
lt-- SSL-Beispiel
ltEnvironment
name=ldapServerAddress
value=ldapsbl2-dc02balviintern636
type=javalangString
override=true
gt
--gt
bdquoldapBaseDnrdquo
LDAP-Suchpfad fuumlr die Domain-Basis Diese muss der LDAP-Syntax fuumlr den Domain-Suffix entsprechen
Syntax DC=SERVERDC=ROOTDN
ltEnvironment
name=ldapBaseDn
value=DC=BALVIDC=INTERN
type=javalangString
override=true
gt
Release Notes BALVI Schnittstellenserver Seite 22 von 37
bdquowebLoginUseActiveDirectoryAuthenticationrdquo
Die Authentifizierung in der Browser-Oberflaumlche kann uumlber die Active-Directory-Authentifizierung erfolgen In der ersten Version ist nur die Protokoll-Auswertung moumlglich wenn der ADMIN sich anmeldet Dieser hat normalerweise niemals AD-Kennungen zugeordnet BALVI empfiehlt diese Einstellung auf bdquofalseldquo zu belassen Webservices welche uumlber SOAPREST zugreifen koumlnnen die Active-Directory-Authentifizierung trotzdem verwenden
ltEnvironment
name=webLoginUseActiveDirectoryAuthentication
value=false
type=javalangBoolean
override=true
gt
ldquoldapDaysBeforeExpirationNotificationrdquo
Die Passwort-Aumlnderung im Active-Directory uumlber die Browser-Oberflaumlche ist in der ersten Version noch nicht implementiert der Parameter wird bislang nicht ausgewertet
ltEnvironment
name=ldapDaysBeforeExpirationNotification
value=14
type=javalangInteger
override=true
gt
2514 Statement-Protokollierung in BALVI iP
Diese Option aktiviert die Lese- und Aumlnderungsprotokollierung fuumlr BALVI iP Standard ist bdquofalseldquo und wird fuumlr alle Kunden empfohlen solange keine speziellen Datenbank-Jobs eingerichtet wurden welche zeitgesteuert die Protokolleintraumlge wieder loumlschen Fuumlr Bayern wurde ein spezielles Konzept zur Leseprotokollierung entworfen Wenn Sie mehr daruumlber erfahren moumlchten kontaktieren Sie bitte die BALVI GmbH
ltEnvironment
name=enableSqlStatementMonitoring
value=true
type=javalangBoolean
override=true
gt
Beachten Sie dass diese Option massive INSERT-Statements in BALVI iP in die Tabelle VIS_D92 ausfuumlhrt Jedes abgesetzte SQL-Statement wird dabei vollstaumlndig protokolliert Dieses erzeugt eine sehr hohe INSERT-Last und in der Folge auch erhoumlhte Redolog-Switches und COMMIT-Transaktionen
Optional Aktivieren der INSERT + APPEND - Logik
Beachten Sie bitte die Hinweise von Oracle zum Hint + APPEND
Release Notes BALVI Schnittstellenserver Seite 23 von 37
Wenn Sie dieses Verhalten aktivieren moumlchten ergaumlnzen Sie bitte den folgenden Environment-Parameter
ltEnvironment
name=statementMonitoringactivateAppendMode
value=true
type=javalangBoolean
override=true
gt
2515 Einstellungen fuumlr BALVI mobil XT (bzw den bdquopartitionedExportldquo)
Diese Logik des FIFO-Buffers wurde so konzipiert dass dem Rechenzentrum diverse Einstellmoumlglichkeiten uumlber die Datei bdquocontextxmlldquo zur Verfuumlgung stehen um die Steuerung des FIFO-Puffers zu beeinflussen
Schematische Darstellung des FIFO-Puffers
Das ermoumlglicht es z B dem BALVI mobil XT Client (14 oder houmlher) den aktiven Block abzuholen und dies beim Fehler bis zu 10-mal zu wiederholen Sobald der Block [001] erfolgreich beim Client angekommen ist und dieser den naumlchsten Block anfragt wird der Block [001] verworfen wird Der Server fuumlllt dann im Hintergrund den frei gewordenen Block wieder waumlhrend der Client den Block [002] abholt
Die Groumlszlige und Anzahl der vorgecachten Bloumlcke kann uumlber die folgenden Einstellungen in der Datei bdquocontextxmlldquo definiert werden
ltEnvironment
name=partitionedExportmaxBufferedPartitions
value=3 type=javalangInteger override=true
gt
ltEnvironment
name=partitionedExportpartitionSize
value=256000 type=javalangInteger override=true
gt
Die Einstellung partitionedExportmaxBufferedPartitions ist dabei die Anzahl der vorgecachten Bloumlcke mindestens muss 2 angegeben werden Der Puffercache wird ausschlieszliglich im RAM der JVM aufgebaut es wird folglich mehr Arbeitsspeicher verwendet Dieser Arbeitsspeicher muss je gleichzeitiger Session auf dem Server bereitgestellt werden die Default-Einstellung mit 3 Partitionen a 256 KB + dem aktiven Puffer erfordern 1 MB RAM je aktiven Anwender
Aktiv
er
Puffe
r
[001] Vorg
ecac
hter
Bl
ock
[002] Vorg
ecac
hter
Bl
ock
[003]
Aktiv
er P
uffe
r
[002] Vorg
ecac
hter
Bl
ock
[003] Vorg
ecac
hter
Bl
ock
[leer]
Release Notes BALVI Schnittstellenserver Seite 24 von 37
Gleichzeitig wurde die Moumlglichkeit geschaffen dass die maximale Anzahl an gleichzeitigen Exporten durch das Rechenzentrum eingeschraumlnkt werden kann um einem OutOfMemory-Fehler vorzubeugen Die Einstellung
ltEnvironment
name=partitionedExportmaxConcurrentExports
value=10 type=javalangInteger override=true
gt
muss entsprechend der zu erwartenden gleichzeitigen Zugriffe konzipiert werden ansonsten wird der Server einen Verbindungsversuch durch die Clients ablehnen
Beachten Sie dass die folgenden Einstellungen partitionedExportmaxBufferedPartitions partitionedExportmaxConcurrentExports und partitionedExportpartitionSize gemeinsam als Rechenbasis fuumlr den RAM-Bedarf des Webservers herangezogen werden muumlssen
Folgende Faustformel sollte fuumlr die Einrichtung verwendet werden
Min 256 MB (Serverbasis) + (11 partitionedExportmaxConcurrentExports partitionedExportmaxBufferedPartitions partitionedExportpartitionSize)
Beispiel 50 gleichzeitige Anwender Blockgroumlszlige 256 KB 4 Partitionen
256 MB + (11 50 256 4) KB = 312 MB fuumlr die JVM
Empf 512 MB (Serverbasis) + (12 partitionedExportmaxConcurrentExports partitionedExportmaxBufferedPartitions partitionedExportpartitionSize)
Beispiel 50 gleichzeitige Anwender Blockgroumlszlige 256 KB 4 Partitionen
512 MB + (12 50 256 4) KB = 572 MB fuumlr die JVM
partitionedExportmaxConcurrentExports
Bestimmt die Anzahl der maximalen Export Tasks (Threads) die fuumlr partitionierte Exporte bereitgestellt werden Wenn die Anzahl uumlberschritten wird wird die entsprechende Exportanfrage abgewiesen und der Client muss zu einem spaumlteren Zeitpunkt erneut anfragen Stellen Sie diesen Wert entsprechend der zu erwartenden Benutzeranzahl ein bei 50 Anwendern also 50
Exporte oumlffnen auf der Datenbank entsprechend zur Ausfuumlhrungszeit min einen Cursor ggf fuumlr rekursive Unterabfragen kurzfristig sogar mehr Die hier eingestellte Anzahl muss mit der Anzahl von maxActive korrelieren
ltEnvironment
name=partitionedExportmaxConcurrentExports
value=10 type=javalangInteger override=true
gt
partitionedExportmaxBufferedPartitions
Bestimmt die Anzahl der Datenbloumlcke (Partitionen) die vom Server bei Abruf eines Exportes gepuffert werden Die seit Version 24 eingefuumlhrte FIFO-Puffer-Logik ermoumlglicht dass der Server schon die Ergebnisse vorpuffert so dass der Client weniger Wartezeiten bei der Anfrage nach Daten hat Diese
Release Notes BALVI Schnittstellenserver Seite 25 von 37
Puffer-Logik unterteilt den Exportdatenstrom (je Export) in mehre Bloumlcke Der Client kann nun den letzten Block neu anfordern oder den naumlchsten Block wenn der letzte Block erfolgreich verarbeitet wurde Wie viele naumlchste Bloumlcke durch den Server bereit gestellt werden entscheidet diese Einstellung Sobald kein naumlchster Block mehr bereit gestellt werden muss wird der Datenbank-Cursor geschlossen eine Erhoumlhung kann also zu einer Entlastung der aktiven DB-Verbindungen fuumlhren erhoumlht jedoch den Bedarf an RAM des Servers
Der von BALVI voreingestellte Wert ist 3
ltEnvironment
name=partitionedExportmaxBufferedPartitions
value=3 type=javalangInteger override=true
gt
partitionedExportpartitionSizeldquo
Die Groumlszlige der Datenbloumlcke (Partitionen) die an den Client uumlbermittelt werden in Bytes Wenn Sie diesen Wert zu niedrig einstellen reduziert sich die Effizienz des Caches da der Client mehr Datenbloumlcke hintereinander abrufen muss Waumlhlen Sie einen zu groszligen Wert wird die neu zu uumlbertragende Datenmenge im Fall eines Fehlers houmlher
Der von BALVI voreingestellte Wert ist 256000 (256 KB)
ltEnvironment
name=partitionedExportpartitionSize
value=256000 type=javalangInteger override=true
gt
exportTokensmaxTokenCount
Maximale Anzahl der gleichzeitig vergebenen Token die vom Server gecached werden Jede Sitzung welche einen Export durchfuumlhrt erhaumllt einen Session-Token
Wenn eine Sitzung laumlngere Zeit nicht verwendet wurde wird dieser Session-Token wieder entfernt Wenn Sie den Wert zu niedrig einstellen fuumlhrt das zu einer generellen Session-Begrenzung auch fuumlr den nicht partitionierten Export-Modus welcher ab Version 21 verfuumlgbar ist
Ist die Anzahl der Tokens houmlher als die Datenbankeinstellung maxActive kann es vorkommen dass zwar eine Session gestartet werden kann jedoch kein Datenexport zustande kommt
Der von BALVI voreingestellte Wert ist 2000
ltEnvironment
name=exportTokensmaxTokenCount
value=20 type=javalangInteger override=true
gt
exportTokenstokenExpirationInSeconds
Zeit in Sekunden die verstreichen muss bis ein Token unguumlltig wird falls darauf kein Zugriff mehr erfolgt Nach einem erfolgreichen Export wird der Token automatisch geschlossen diese Option ist fuumlr den Abbruchfall vorgesehen Der von BALVI voreingestellte Wert ist 180 (180 s = 3 min)
Release Notes BALVI Schnittstellenserver Seite 26 von 37
ltEnvironment
name=exportTokenstokenExpirationInSeconds
value=180 type=javalangInteger override=true
gt
exportTokenstokenDisposalInSeconds
Zeit in Sekunden die verstreichen muss bis ein Token das erfolgreich abgearbeitet wurde aus dem Cache geloumlscht wird Um sicher zu stellen dass der letzte Exportblock noch erfolgreich abgerufen werden kann bleibt der Token auch nach Fertigmeldung des Clients noch N Sek guumlltig
Der von BALVI voreingestellte Wert ist 60 (60 s = 1 min)
ltEnvironment
name=exportTokenstokenDisposalInSeconds
value=60 type=javalangInteger override=true
gt
2516 Job-Verwaltung fuumlr den BSS konfigurieren Aktivierung der Jobverwaltung
Bis zur Version 28 des BSS gab es den Parameter bdquoavailableServicesldquo Dieser konnte bei Bedarf aktiviert werden wenn die Jobs benoumltigt wurden
Mit Version 30 ist die Einstellung bdquoavailableServicesldquo zu entfernen und kann durch den neuen optionalen Parameter bdquoisJobServiceEnabledldquo in der Datei bdquocontextxmlldquo ersetzt werden
lt-- Neue Parameter zur Aktivierung des Job Service Ersatz fuumlr availableServices --gt
ltEnvironment
name=isJobServiceEnabled
value=true
type=javalangBoolean
override=true
gt
Ab BSS 30 wird die Jobs-Engine standardmaumlszligig aktiviert Sollte die Jobs-Engine nicht benoumltigt werden muss bdquovalueldquo der Wert bdquofalseldquo zugewiesen werden Wird bdquoisJobServiceEnabledldquo nicht eingefuumlgt sind die Jobs trotzdem standardmaumlszligig aktiv
Nach dem Neustart des Servers und erneutem Einloggen erscheint nun zusaumltzlich der Menuumlpunkt bdquoJobsldquo
bdquopasswordKeyldquo fuumlr Jobs
In der Job-Logik wird ein von BALVI definierter Standard-Schluumlssel fuumlr die Ablagen von schuumltzenswerten Daten z B Passwoumlrtern verwendet Diese Einstellung ermoumlglicht den BALVI-Standard zu uumlberschreiben Wenn Sie diese Einstellung aumlndern muumlssen jedoch alle bislang verschluumlsselten Job-Parameter neu verschluumlsselt werden
ltEnvironment
name=javacompenvjobspasswordKey
value=MeinHochsicheresNeuesPasswort
type=javalangString
Release Notes BALVI Schnittstellenserver Seite 27 von 37
override=true
gt
bdquoJob ID enableddisabledldquo (Deprecated ersetzt ab 28 durch das bdquoBindenldquo von Jobs)
Sondereinstellungen fuumlr die Job-Verwaltung Da alle Jobs in einer Datenbank administriert werden jedoch ggf verteilt auf mehreren Tomcat-Servern ausgefuumlhrt werden sollen besteht hier die Option Jobs fuumlr die aktuelle Tomcat-Instanz separat zu deaktivieren
Die Einstellung ID koumlnnte z B folgendermaszligen aussehen javacompenvjobsC0DB58D8D52C4BBC966D1DC788A4EF8Benabled
Fuumlr weitere Fragen zu dieser Einstellung kontaktieren Sie bitte die BALVI GmbH
ltEnvironment
name=javacompenvjobsIDenabled
value=false
type=javalangBoolean
override=true
gt
2517 Weitere optionale Parameter
Es ist fuumlr diverse einzelne Schnittstellen ggf erforderlich Einstellungen in der Datei bdquocontextxmlldquo zu ergaumlnzen Hinweise zu diesen Parametern sind dann in dem der Schnittstelle beiliegenden Dokument enthalten Das gilt z B fuumlr die Schnittstelle bdquoXGewerbeanzeigenldquo
26 Logging mit logback Das Logging wurde komplett uumlberarbeitet Statt bdquoLog4Jldquo wird jetzt bdquologbackldquo4 benutzt Ab BSS 30 ist es zwingend notwendig die Einstellung vorzunehmen um das Logging der Anwendung zu steuern
Migration Ergaumlnzen Sie die neue Einstellung bdquologgingconfigldquo
lt-- Neue Paramter zur Angabe der Logback Config Ersatz fuumlr log4jConfigLocation --gt
ltEnvironment
name=loggingconfig
value=$catalinabaseconflogback-bssxml
type=javalangString
override=true
gt
Nach wie vor steht es Ihnen frei die Logging-Konfiguration eigenstaumlndig anzupassen
Wenn Sie jedoch dieselbe WAR in einer Tomcat-Instanz unter mehreren Context-Namen betreiben wuumlrden beide dieselbe Logging-Konfiguration verwenden so dass alle Protokolleintraumlge in einer Log-Datei aus
4 httplogbackqoschmanualappendershtml
Release Notes BALVI Schnittstellenserver Seite 28 von 37
mehreren Webanwendungen generiert werden Aumlndern Sie den Namen der Logging-Konfiguration entsprechend ab um fuumlr jede Anwendung eine spezifische Logging-Einstellung vornehmen zu koumlnnen
27 Tocmat Optional Suche im bdquoKlassenpfadldquo um den
Ordner bdquoconfldquo erweitern Die Suche nach Dateien uumlber bdquoclasspathldquo setzt voraus dass die Ordner- und Dateinamen im Apache Tomcat bekannt gegeben werden Der Klassenpfad kann in der Datei bdquocatalinapropertiesldquo angepasst werden Wenn Sie dort unter commonloader die folgenden Werte ergaumlnzen kann eine Datei auch im Ordner conf abgelegt werden damit Apache Tomcat diese findet Ansonsten muss die Datei im Ordner lib abgelegt werden
commonloader=$catalinabaseconf$catalinahomeconf
3 Die neue Browser-Oberflaumlche Der BALVI Schnittstellenserver hat seit Version 25 neben der Protokollierung auch die Moumlglichkeit Job-Konfigurationen zu pflegen Der Login ist nur fuumlr einen in BALVI iP eingetragenen ADMIN (z B Benutzer bdquoSYSTEMADMINldquo) mit dem in BALVI iP hinterlegten Passwort moumlglich Zur Anmeldung muss immer [SYSTEMBenutzername] im Feld Benutzer angegeben werden ansonsten schlaumlgt die Anmeldung fehl Bitte achten Sie darauf dass der bdquoldquo (Slash) und nicht der bdquoldquo (Backslash) verwendet werden muss
31 Server-Protokoll Um das Server-Protokoll anzuzeigen waumlhlen Sie den entsprechenden Menuumlpunkt Dort haben Sie seit BSS 26 die Moumlglichkeit uumlber alle Spalten der Protokolle nach Informationen zu suchen
Seit BSS 31 gibt es die Moumlglichkeit Verfahren in bdquoKopfsaumltzeldquo und bdquoDetailsaumltzeldquo zu unterteilen Wurde das Verfahren entsprechend konfiguriert (wie z B bei der Schnittstelle bdquoXGewerbeanzeigenldquo) dann wird im Protokoll-Kopfsatz nur der Start und das Ende der Ausfuumlhrung in der Liste angezeigt Erst bei einem Klick auf bdquoInformationenldquo wird die Liste aller Detailsaumltze angezeigt die im Durchlauf erzeugt wurden
Release Notes BALVI Schnittstellenserver Seite 29 von 37
Verfahren
Die Liste der verfuumlgbaren Verfahren die bei Ihnen im System installiert sind ZB
BEFUNDEhellip Schnittstelle Befunde LM FM oder TS
PROBEhellip Schnittstelle zum Export von Proben an Labore ebenfalls Spezifisch fuumlr einzelne Fachbereiche
MOBILXT Protokolle der BALVI Mobil XT Synchronisation
WEB Allgemeine nicht spezifizierte Protokolle hierunter ist bislang auch die eFi-Protokollierung zu finden
WEB_I0802 Protokolle zur Schnittstelle BALVI iP LIMS (Lebensmittelproben)
XGEWERBE Schnittstelle XGewerbeanzeigen
Klicken Sie auf die Schaltflaumlche so besteht bei den neuen Protokolldatensaumltzen die Moumlglichkeit Detail-Informationen zum Protokollsatz zu erhalten
Release Notes BALVI Schnittstellenserver Seite 30 von 37
Seit BSS 30x ist die Anzeige der Protokolle ebenfalls farblich abgesetzt so dass Protokolleintraumlge mit Fehlern hellrot und Warnungen hellgelb hinterlegt werden
32 Jobs Mit einem Klick auf den Menuumlpunkt Jobs rufen Sie die Oberflaumlche fuumlr die Job-Konfiguration auf Daraufhin werden alle Jobs aufgelistet die fuumlr den BSS freigegeben sind Hier koumlnnen Sie Einstellungen an den Jobs vornehmen und die Jobs aktivieren bzw deaktivieren Die Beschreibungen bzw Einstellungsmoumlglichkeiten fuumlr den jeweiligen SST-Job sind nicht Bestandteil dieser Dokumentation
33 Log-Ausgaben Uumlber den Menuumlpunkt Log-Ausgaben koumlnnen Sie die Ausgabe der Protokolleintraumlge in Echtzeit beobachten
Release Notes BALVI Schnittstellenserver Seite 31 von 37
Starten Sie die Echtzeit-Protokollierung indem Sie auf die Schaltflaumlche mit dem Symbol bdquoPlayldquo (Dreieck) klicken unterbrechen Sie die Ausgabe indem Sie die auf Schaltflaumlche mit dem Symbol bdquoPauseldquo (zwei Balken) klicken
Klicken Sie auf die Schaltflaumlche bdquoAktualisierenldquo (zwei Pfeile) um die neuesten Protokolleintraumlge angezeigt zu bekommen
Klicken Sie auf das Symbol mit dem Papierkorb um die letzten Protokollmeldungen in der Anzeige zu loumlschen
Die Daten in den Protokolldateien auf der Festplatte des Servers sind davon nicht betroffen
Uumlber das Symbol bdquoLogging anpassenldquo (Schraubenschluumlssel) koumlnnen Sie die Ausgabe der Daten im Echtzeitfenster und in den Protokolldateien aumlndern jedoch ist diese Einstellung nur temporaumlr Die Standardeinstellungen koumlnnen ausschlieszliglich uumlber die Anpassung der Datei bdquologback-bssxmlldquo im Konfigurationsverzeichnis des Servers selbst geaumlndert werden
Release Notes BALVI Schnittstellenserver Seite 32 von 37
In der Logging-Parameter Konfiguration koumlnnen Sie verschiedene Parameter einstellen und uumlber die Schaltflaumlche bdquoAnwendenldquo dann sofort im Echtzeitprotokoll sehen Welche Einstellungen moumlglich sind erfahren Sie wenn es eine akute Fehlersituation gibt die detailliertere Ausgaben im Protokoll erfordert
Warnung Wenn Sie den Log-Level fuumlr ROOT oder eine andere Klasse auf TRACE einstellen werden sehr viele Protokollausgaben generiert die auch dazu fuumlhren koumlnnen dass der Server sehr langsam wird oder die Festplatte des Servers zulaumluft wenn fuumlr das Logging kein Dateilimit konfiguriert wurde
34 LogoutAbmeldung vom System Zum Abmelden waumlhlen Sie oben rechts das Kontextmenuuml
35 Cache loumlschen Der Cache wird in der Regel automatisch geloumlscht Wenn Sie jedoch gerade in BALVI iP eine Aumlnderung an den Schnittstellen eingespielt haben und moumlchten dass diese sofort wirksam wird kann die Funktion bdquoCache loumlschenldquo dazu verwendet werden dass der BALVI Schnittstellenserver die Einstellungen bei der naumlchsten Anfrage neu einliest
Release Notes BALVI Schnittstellenserver Seite 33 von 37
Release Notes BALVI Schnittstellenserver Seite 34 von 37
4 Einrichtung in BALVI iP Um die Verfahren fuumlr den BALVI Schnittstellenserver fuumlr Anwender freizuschalten wird das Objekt bdquoSystemeinstellungenldquo oder bdquoMandanten- und Benutzereinstellungenldquo verwendet Die Anpassung ist je Verfahren moumlglich so kann in BALVI iP fuumlr den Zugriff durch den BALVI Schnittstellenserver ein Benutzer bdquoAldquo am Verfahren bdquoMobilldquo berechtigt werden ein Benutzer bdquoBldquo nur am Verfahren bdquoSLA_FLESHldquo usw Die Logik ist jedoch einheitlich Je Verfahren wird durch BALVI eine Verfahrensgruppe mit dem Verfahrensnamen angelegt und mit den entsprechenden Einstellungen vorkonfiguriert welche durch das Verfahren erforderlich sind Dabei kann die Komplexitaumlt der Einstellungen variieren wie z B an den zu Version 23 verfuumlgbaren Verfahren bdquoMobilldquo und bdquoSLA_Fleshldquo ersichtlich wird
Im Verfahren BALVI Mobil sind diverse Anpassungen moumlglich welche je Bundesland oder eingesetzter Import- und Export-Variante durch den BALVI Schnittstellenserver bei der Bearbeitung von Anfragen gepruumlft werden siehe Punkt 3 Abb Mobil-Einstellung in BALVI iP
Abb Mobil-Einstellung in BALVI iP
Alle Verfahren verwenden jedoch die regulaumlre Benutzerverwaltung von BALVI iP Ein Benutzer ohne Passwort gilt fuumlr BALVI iP als gesperrt was fuumlr das Login bedeutet dass der Anwender sich nur uumlber die Active-Directory-Authentifizierung anmelden kann Ist das nicht moumlglich (bzw nicht konfiguriert) kann der Anwender sich weder in BALVI iP noch uumlber die Webservice-Schnittstelle authentifizieren
Fuumlr Dienste-Schnittstellen welche keine persoumlnliche Authentifizierung durch einen Anwender erfordern wird empfohlen einen separaten Benutzer in der Benutzerverwaltung anzulegen und ein sicheres Kennwort zu vergeben Das Anlegen von zusaumltzlichen Benutzern gilt nicht fuumlr BALVI mobil XT da beim Holen und Uumlbermitteln von Daten jeder Benutzer auch ein fachlich konfigurierter Anwender innerhalb von BALVI iP ist und die Anwendungsoberflaumlche ebenfalls zur Erfassung von Daten verwendet
Unter Punkt 2 der Abb Mobil-Einstellung in BALVI iP wird ein modales Fenster geoumlffnet (Abb BALVI mobil Benutzerverwaltung) Innerhalb dieses modalen Fensters werden mandantenweise die Benutzer fuumlr BALVI
Release Notes BALVI Schnittstellenserver Seite 35 von 37
mobil und den jeweiligen Fachbereich festgelegt Dabei ist es wichtig dass man die Haken bdquoAktiv fuumlr hellipldquo bei bdquohellip mobilldquo und bei einem Fachbereich (bdquohellip LMldquo bdquohellip FMldquo usw) setzt weil sonst uumlber den BALVI Schnittstellenserver keine Kommunikation mit BALVI iP moumlglich ist
Abb BALVI mobil Benutzerverwaltung
Alternativ zur Passwort-Authentifizierung wird wie beschrieben auch die Active-Directory-Authentifizierung angeboten Dazu muss der BALVI iP-Anwender uumlber die Schaltflaumlche bdquoDomaumlnen-Benutzer zuordnenldquo mit dem Active Directory verknuumlpft werden
Nur wenn die Active-Directory-Konfigurationen in BALVI iP und im BALVI Schnittstellenserver auf dieselbe Domaumlne verweisen sind die Domaumlnen-Zuordnung und die Active-Directory-Authentifizierung (z B uumlber BALVI mobil XT) moumlglich
Release Notes BALVI Schnittstellenserver Seite 36 von 37
5 Bekannte Probleme und Loumlsungen
51 ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner Bei der Job-Bearbeitung tritt folgender Fehler auf ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner
Behebung
Fuumlhren Sie das beiliegende IP-Patch (UPDATEexe) aus bevor Sie das WAR austauschen
52 Server startet nicht Sie finden folgende Zeilen im Protokoll (catalinaout oder bsslog)
ERROR [localhost-startStop-1] [IdentityServiceImpl] serverID must not be empty
ERROR [localhost-startStop-1] [ContextLoader] Context initialization failed
Behebung
Setzen Sie die Umgebungsvariable ldquoserverIDrdquo in der Datei bdquocontextxmlldquo
53 ORA-00942 table or view does not exist In vielen Faumlllen wird der Fehler ldquoTabelle oder View nicht vorhandenrdquo ausgeworfen (Java-Protokoll im Ordner logs von Apache Tomcat) wenn eine neue Schnittstelle eingerichtet oder ein neues BALVI iP Release bzw Update eingespielt wurde ohne anschlieszligend das aktuelle GRANT-Skript auszufuumlhren
Behebung
Fuumlhren Sie das GRANT-Skript erneut aus
54 ORA-0406x bdquoBestehender Paketstatus wurde aufgehobenldquo
ORA-04061 Bestehender Status von package body ABCXYZ wurde annulliert
ORA-04065 Ausfuumlhrung nicht erfolgreich package body ABCXYZ wurde geaumlndert oder geloumlscht
Release Notes BALVI Schnittstellenserver Seite 37 von 37
Der Fehler tritt haumlufig ein nachdem die UPDATEexe ausgefuumlhrt und in der Ausfuumlhrungsliste ein Package aktualisiert wurde Oracle merkt sich je User-Session bestimmte Werte im Package wenn der Anwender es verwendet hat Durch einen bdquoCREATE OR REPLACE PACKAGEldquo-Befehl kann dieser Status temporaumlr aufgehoben werden Normalerweise tritt dieser Fehler nach dem Update genau einmal in jeder aktiven Session auf wenn der BSS nicht neu gestartet wird
Behebung
Starten Sie nach jedem Update den BSS neu um alle laufenden Sessions zu beenden
55 Jobs sind nicht ausfuumlhrbar
1 Ein Job wird mit dem Status bdquoNicht unterstuumltztldquo angezeigt wenn fuumlr seine Ausfuumlhrung eine houmlhere Version des BSS erforderlich ist
2 Nach dem Klonen der Datenbank von der Produktions- auf die Testumgebung erhalten alle Jobs automatisch den Status bdquoDeaktiviertldquo wenn die bdquoserverIDldquo nicht identisch ist
Beide Statusaumlnderungen sind gewollt Damit soll verhindert werden dass Jobs nach einem Serverneustart oder nach einem Update automatisch starten und dabei Fehler verursachen
Um Jobs mit dem Status bdquoNicht unterstuumltztldquo nutzen und konfigurieren zu koumlnnen ist es erforderlich den BALVI Schnittstellenserver zu aktualisieren
Deaktivierte Jobs koumlnnen Sie aktivieren indem Sie den jeweiligen Job an den aktuellen Server binden und den Haken bei bdquoAktivldquo setzen
Release Notes BALVI Schnittstellenserver Seite 18 von 37
type=javaxsqlDataSource
factory=orgapachetomcatjdbcpoolDataSourceFactory
maxActive=10 initialSize=3
maxIdle=5
maxWait=10000
url=jdbcoraclethinBL2-ORA10-KUNDENBALVIINTERN1521ORCL
driverClassName=oraclejdbcdriverOracleDriver
username=balvi_webservice_schema
password=balvi_webservice_password
description=Oracle Datasource
maxOpenPreparedStatements=50
removeAbandoned=false
removeAbandonedTimeout=100
logAbandoned=true
jdbcInterceptors=hellip
gt
Hinweise zur Einstellung der jdbcDataSource
Standard-Einstellungen fuumlr den Datenbank-Verbindungspool
Der Verbindungspool muss entsprechend der Anzahl der zu erwartenden gleichzeitigen Benutzer konfiguriert werden Wenn Sie erwarten dass 50 Anwender gleichzeitig arbeiten stellen Sie bitte folgende Werte ein
maxActive=(50 + 10 (fuumlr System und Jobs)) = 60
maxIdle= (50 10) = 5
1 maxActive - maximale Anzahl der gleichzeitigen aktiven Anfragen an die DB
Wenn der Werte maxActive erreicht ist z B wenn mehrere Benutzer gleichzeitig einen Export starten moumlchten welcher laumlngere Zeit in Anspruch nimmt dann kann der Server die Anfrage nicht mehr bedienen und der Anwender wird abgewiesen maxActive hat zudem Auswirkungen auf die im Hintergrund ausgefuumlhrten Jobs maxActive wird daher kalkuliert mit der Anzahl der Anwender und moumlglicher Datenbank-Connections fuumlr Hintergrund-Jobs Jeder aktiv ausgefuumlhrte Job benoumltigt mindestens eine Connection nur selten wird aus Performance-Gruumlnden mehr als eine Connection waumlhrend der Job-Ausfuumlhrung verwendet Im Normalfall sollten daher 10 Connections fuumlr Hintergrundprozesse ausreichend sein
2 maxIdle - Anzahl der offenen Verbindungen auch wenn der Server im Leerlauf ist
Jede offene Verbindung im Leerlauf haumllt auf dem Datenbankserver eine Session offen Auch diese erfordert Ressourcen Wenn die Verbindungen jedoch geschlossen werden kann die Anfragezeit fuumlr eine neue Verbindung steigen da diese Verbindung erst neu ausgehandelt werden muss Die Empfehlung fuumlr den Wert bdquomaxIdleldquo ist ca 10 der Einstellung von maxActive
KeepAlive-Einstellungen fuumlr den Pool
1 validationQuery
Diese wird ausgefuumlhrt um die Verbindung zu DB zu validieren Es MUSS ein Datensatz zuruumlckgegeben werden ansonsten nimmt der DBCP an dass die Abfrage nicht erfolgreich abgesetzt wurde Achten Sie also bitte darauf dass die Abfrage nicht zu leitungsintensiv ist und genau einen Datensatz liefert
Release Notes BALVI Schnittstellenserver Seite 19 von 37
Oracle bietet dafuumlr die virtuelle Tabelle DUAL an welche sich fuumlr die ValidationQuery sehr gut eignet da die Abfrage kaum Ressourcen verbraucht
validationQuery=select 1 from dual
2 testOnBorrow - Boolscher Wert true oder false
Diese Einstellung sorgt dafuumlr dass der Pool die Verfuumlgbarkeit anhand der validationQuery pruumlft bevor
die DB-Verbindung an die Anwendung ausgeliehen wird Empfehlung
testOnBorrow=true
3 testWhileIdle - Boolscher Wert true oder false
Diese Einstellung ist hilfreich wenn zwischen dem Tomcat und der DB eine Firewall mit Stateful
Packet Inspection verwendet wird Nach laumlngerer Inaktivitaumlt wird normalerweise durch die Firewall die
DB-Verbindung geschlossen Dieses loumlst dann beim Ausleihen der Verbindung eine Fehlermeldung im
Protokoll aus 2012-08-16 165418720 WARN [http-0000-8080-8]
[orgspringframeworkjdbcsupportSQLErrorCodesFactory] Error while extracting
database product name - falling back to empty error codes
orgspringframeworkjdbcsupportMetaDataAccessException Error while extracting
DatabaseMetaData nested exception is javasqlSQLRecoverableException Getrennte
Verbindung Um dieses Problem zu beheben sollte die Option testWhileIdle=true eingestellt werden
testWhileIdle=true
Damit diese weiszlig wie oft eine Pruumlfung durchgefuumlhrt werden muss sind jedoch noch zusaumltzliche Angaben erforderlich welche fuumlr die Einstellung der Zeit zusaumltzlich gesetzt werden muumlssen
a) minEvictableIdleTimeMillis - Long in Millisekunden
Min Zeit wie lange eine DB-Verbindung im Leerlauf ist bevor diese zur Pruumlfung
gekennzeichnet wird Dieses haumlngt stark von der Einstellung der Firewall ab Wenn Sie eine
sehr restriktive Firewall haben kann es sein dass diese die Verbindung nach wenigen
Minuten Leerlauf trennt Stellen Sie den Wert immer so ein dass dieser unter der Leerlaufzeit
der Firewall liegt empfohlen 300000 entspricht 300 Sek = 5 min
minEvictableIdleTimeMillis=300000
b) timeBetweenEvictionRunsMillis - Long in Millisekunden
Der Pruumlflauf startet in der Default-Konfiguration alle 1800000 Millisekunden = 30 Min n als
zu Pruumlfen markierte Verbindungen werden in einem Pruumlflauf getestet n wird bestimmt durch
die Einstellung numTestsPerEvictionRun Empfehlung Stellen Sie den Wert auf alle 15 Min
ein
timeBetweenEvictionRunsMillis=900000
Release Notes BALVI Schnittstellenserver Seite 20 von 37
c) numTestsPerEvictionRun - Integer
Wie viele Verbindungen sollen getestet werden waumlhrend der Pruumlflauf ausgefuumlhrt wird Im
Normalfall sollte die Anzahl der zu testenden Verbindungen nicht zu hoch eingestellt werden
Der Default ist 3 Wenn Sie houmlhere Sicherheit haben wollen dass keine bdquototenldquo
Datenbankverbindungen bestehen bleiben erhoumlhen Sie den Wert auf max bdquo(maxActive ndash
maxIdle) 2ldquo Wenn Ihnen 3 ausreichend erscheint muss der Wert nicht gesetzt sein dann
wird der Default verwendet
Beispiel numTestsPerEvictionRun=10
4 Interceptors konfigurieren Neu ergaumlnzt wurde die Moumlglichkeit spezielle bdquoInterceptorsldquo zu konfigurieren die ermoumlglichen das Verhalten des Pools zu steuern Wichtig hierbei ist dass die Angabe von Werten auf real existierende Java-Klassen erfolgt die im Classpath des Tomcat vorhanden sind Groszlig-und-Kleinschreibung ist zu beachten Folgende Default-Einstellung hat BALVI fuumlr den BSS festgelegt jdbcInterceptors=
orgapachetomcatjdbcpoolinterceptorConnectionState
orgapachetomcatjdbcpoolinterceptorStatementFinalizer
orgapachetomcatjdbcpoolinterceptorResetAbandonedTimer
Details zu den verwendeten Interceptor-Einstellungen finden Sie in der Tomcat-Dokumentation3
3 httptomcatapacheorgtomcat-80-docjdbc-poolhtmlJDBC_interceptors
Release Notes BALVI Schnittstellenserver Seite 21 von 37
2512 Datenbank-Zugangsdaten verschluumlsseln
Die Verschluumlsselung fuumlr die Datenbank-Verbindung (bdquoEncrypted Datasourceldquo) ist eine Ableitung der Bibliothek Apache-Common-DBCP-14 und daher nicht mehr mit Java 8 kompatibel Die Einrichtung der Verschluumlsselung wird daher mit der Auslieferung des BSS 30 nicht mehr angeboten
2513 Active-Directory-Authentifizierung
Uumlber die folgenden Parameter wird der Zugriff des Schnittstellen-Servers auf einen Microsoft Active Directory Domain-Controller konfiguriert
ldquoldapServerAddressrdquo
Syntax PROTOKOLLIP-Adresse oder DNS-NamePORT
ltEnvironment
name=ldapServerAddress
value=ldapbl2-dc02balviintern389
type=javalangString
override=true
gt
Als Protokoll besteht auch die Moumlglichkeit ldaps (LDAP+SSL) wenn der Domain-Controller entsprechend konfiguriert wurde Im Java Truststore muss dann das Zertifikat der CA vorhanden sein welche das Zertifikat des Domain-Controllers signiert hat Zudem darf bei ldaps keine IP-Adresse verwendet werden es muss der DNS-Name des Server-Zertifikats eingetragen sein Ansonsten gibt es beim Verbinden eine Sicherheits-Exception
lt-- SSL-Beispiel
ltEnvironment
name=ldapServerAddress
value=ldapsbl2-dc02balviintern636
type=javalangString
override=true
gt
--gt
bdquoldapBaseDnrdquo
LDAP-Suchpfad fuumlr die Domain-Basis Diese muss der LDAP-Syntax fuumlr den Domain-Suffix entsprechen
Syntax DC=SERVERDC=ROOTDN
ltEnvironment
name=ldapBaseDn
value=DC=BALVIDC=INTERN
type=javalangString
override=true
gt
Release Notes BALVI Schnittstellenserver Seite 22 von 37
bdquowebLoginUseActiveDirectoryAuthenticationrdquo
Die Authentifizierung in der Browser-Oberflaumlche kann uumlber die Active-Directory-Authentifizierung erfolgen In der ersten Version ist nur die Protokoll-Auswertung moumlglich wenn der ADMIN sich anmeldet Dieser hat normalerweise niemals AD-Kennungen zugeordnet BALVI empfiehlt diese Einstellung auf bdquofalseldquo zu belassen Webservices welche uumlber SOAPREST zugreifen koumlnnen die Active-Directory-Authentifizierung trotzdem verwenden
ltEnvironment
name=webLoginUseActiveDirectoryAuthentication
value=false
type=javalangBoolean
override=true
gt
ldquoldapDaysBeforeExpirationNotificationrdquo
Die Passwort-Aumlnderung im Active-Directory uumlber die Browser-Oberflaumlche ist in der ersten Version noch nicht implementiert der Parameter wird bislang nicht ausgewertet
ltEnvironment
name=ldapDaysBeforeExpirationNotification
value=14
type=javalangInteger
override=true
gt
2514 Statement-Protokollierung in BALVI iP
Diese Option aktiviert die Lese- und Aumlnderungsprotokollierung fuumlr BALVI iP Standard ist bdquofalseldquo und wird fuumlr alle Kunden empfohlen solange keine speziellen Datenbank-Jobs eingerichtet wurden welche zeitgesteuert die Protokolleintraumlge wieder loumlschen Fuumlr Bayern wurde ein spezielles Konzept zur Leseprotokollierung entworfen Wenn Sie mehr daruumlber erfahren moumlchten kontaktieren Sie bitte die BALVI GmbH
ltEnvironment
name=enableSqlStatementMonitoring
value=true
type=javalangBoolean
override=true
gt
Beachten Sie dass diese Option massive INSERT-Statements in BALVI iP in die Tabelle VIS_D92 ausfuumlhrt Jedes abgesetzte SQL-Statement wird dabei vollstaumlndig protokolliert Dieses erzeugt eine sehr hohe INSERT-Last und in der Folge auch erhoumlhte Redolog-Switches und COMMIT-Transaktionen
Optional Aktivieren der INSERT + APPEND - Logik
Beachten Sie bitte die Hinweise von Oracle zum Hint + APPEND
Release Notes BALVI Schnittstellenserver Seite 23 von 37
Wenn Sie dieses Verhalten aktivieren moumlchten ergaumlnzen Sie bitte den folgenden Environment-Parameter
ltEnvironment
name=statementMonitoringactivateAppendMode
value=true
type=javalangBoolean
override=true
gt
2515 Einstellungen fuumlr BALVI mobil XT (bzw den bdquopartitionedExportldquo)
Diese Logik des FIFO-Buffers wurde so konzipiert dass dem Rechenzentrum diverse Einstellmoumlglichkeiten uumlber die Datei bdquocontextxmlldquo zur Verfuumlgung stehen um die Steuerung des FIFO-Puffers zu beeinflussen
Schematische Darstellung des FIFO-Puffers
Das ermoumlglicht es z B dem BALVI mobil XT Client (14 oder houmlher) den aktiven Block abzuholen und dies beim Fehler bis zu 10-mal zu wiederholen Sobald der Block [001] erfolgreich beim Client angekommen ist und dieser den naumlchsten Block anfragt wird der Block [001] verworfen wird Der Server fuumlllt dann im Hintergrund den frei gewordenen Block wieder waumlhrend der Client den Block [002] abholt
Die Groumlszlige und Anzahl der vorgecachten Bloumlcke kann uumlber die folgenden Einstellungen in der Datei bdquocontextxmlldquo definiert werden
ltEnvironment
name=partitionedExportmaxBufferedPartitions
value=3 type=javalangInteger override=true
gt
ltEnvironment
name=partitionedExportpartitionSize
value=256000 type=javalangInteger override=true
gt
Die Einstellung partitionedExportmaxBufferedPartitions ist dabei die Anzahl der vorgecachten Bloumlcke mindestens muss 2 angegeben werden Der Puffercache wird ausschlieszliglich im RAM der JVM aufgebaut es wird folglich mehr Arbeitsspeicher verwendet Dieser Arbeitsspeicher muss je gleichzeitiger Session auf dem Server bereitgestellt werden die Default-Einstellung mit 3 Partitionen a 256 KB + dem aktiven Puffer erfordern 1 MB RAM je aktiven Anwender
Aktiv
er
Puffe
r
[001] Vorg
ecac
hter
Bl
ock
[002] Vorg
ecac
hter
Bl
ock
[003]
Aktiv
er P
uffe
r
[002] Vorg
ecac
hter
Bl
ock
[003] Vorg
ecac
hter
Bl
ock
[leer]
Release Notes BALVI Schnittstellenserver Seite 24 von 37
Gleichzeitig wurde die Moumlglichkeit geschaffen dass die maximale Anzahl an gleichzeitigen Exporten durch das Rechenzentrum eingeschraumlnkt werden kann um einem OutOfMemory-Fehler vorzubeugen Die Einstellung
ltEnvironment
name=partitionedExportmaxConcurrentExports
value=10 type=javalangInteger override=true
gt
muss entsprechend der zu erwartenden gleichzeitigen Zugriffe konzipiert werden ansonsten wird der Server einen Verbindungsversuch durch die Clients ablehnen
Beachten Sie dass die folgenden Einstellungen partitionedExportmaxBufferedPartitions partitionedExportmaxConcurrentExports und partitionedExportpartitionSize gemeinsam als Rechenbasis fuumlr den RAM-Bedarf des Webservers herangezogen werden muumlssen
Folgende Faustformel sollte fuumlr die Einrichtung verwendet werden
Min 256 MB (Serverbasis) + (11 partitionedExportmaxConcurrentExports partitionedExportmaxBufferedPartitions partitionedExportpartitionSize)
Beispiel 50 gleichzeitige Anwender Blockgroumlszlige 256 KB 4 Partitionen
256 MB + (11 50 256 4) KB = 312 MB fuumlr die JVM
Empf 512 MB (Serverbasis) + (12 partitionedExportmaxConcurrentExports partitionedExportmaxBufferedPartitions partitionedExportpartitionSize)
Beispiel 50 gleichzeitige Anwender Blockgroumlszlige 256 KB 4 Partitionen
512 MB + (12 50 256 4) KB = 572 MB fuumlr die JVM
partitionedExportmaxConcurrentExports
Bestimmt die Anzahl der maximalen Export Tasks (Threads) die fuumlr partitionierte Exporte bereitgestellt werden Wenn die Anzahl uumlberschritten wird wird die entsprechende Exportanfrage abgewiesen und der Client muss zu einem spaumlteren Zeitpunkt erneut anfragen Stellen Sie diesen Wert entsprechend der zu erwartenden Benutzeranzahl ein bei 50 Anwendern also 50
Exporte oumlffnen auf der Datenbank entsprechend zur Ausfuumlhrungszeit min einen Cursor ggf fuumlr rekursive Unterabfragen kurzfristig sogar mehr Die hier eingestellte Anzahl muss mit der Anzahl von maxActive korrelieren
ltEnvironment
name=partitionedExportmaxConcurrentExports
value=10 type=javalangInteger override=true
gt
partitionedExportmaxBufferedPartitions
Bestimmt die Anzahl der Datenbloumlcke (Partitionen) die vom Server bei Abruf eines Exportes gepuffert werden Die seit Version 24 eingefuumlhrte FIFO-Puffer-Logik ermoumlglicht dass der Server schon die Ergebnisse vorpuffert so dass der Client weniger Wartezeiten bei der Anfrage nach Daten hat Diese
Release Notes BALVI Schnittstellenserver Seite 25 von 37
Puffer-Logik unterteilt den Exportdatenstrom (je Export) in mehre Bloumlcke Der Client kann nun den letzten Block neu anfordern oder den naumlchsten Block wenn der letzte Block erfolgreich verarbeitet wurde Wie viele naumlchste Bloumlcke durch den Server bereit gestellt werden entscheidet diese Einstellung Sobald kein naumlchster Block mehr bereit gestellt werden muss wird der Datenbank-Cursor geschlossen eine Erhoumlhung kann also zu einer Entlastung der aktiven DB-Verbindungen fuumlhren erhoumlht jedoch den Bedarf an RAM des Servers
Der von BALVI voreingestellte Wert ist 3
ltEnvironment
name=partitionedExportmaxBufferedPartitions
value=3 type=javalangInteger override=true
gt
partitionedExportpartitionSizeldquo
Die Groumlszlige der Datenbloumlcke (Partitionen) die an den Client uumlbermittelt werden in Bytes Wenn Sie diesen Wert zu niedrig einstellen reduziert sich die Effizienz des Caches da der Client mehr Datenbloumlcke hintereinander abrufen muss Waumlhlen Sie einen zu groszligen Wert wird die neu zu uumlbertragende Datenmenge im Fall eines Fehlers houmlher
Der von BALVI voreingestellte Wert ist 256000 (256 KB)
ltEnvironment
name=partitionedExportpartitionSize
value=256000 type=javalangInteger override=true
gt
exportTokensmaxTokenCount
Maximale Anzahl der gleichzeitig vergebenen Token die vom Server gecached werden Jede Sitzung welche einen Export durchfuumlhrt erhaumllt einen Session-Token
Wenn eine Sitzung laumlngere Zeit nicht verwendet wurde wird dieser Session-Token wieder entfernt Wenn Sie den Wert zu niedrig einstellen fuumlhrt das zu einer generellen Session-Begrenzung auch fuumlr den nicht partitionierten Export-Modus welcher ab Version 21 verfuumlgbar ist
Ist die Anzahl der Tokens houmlher als die Datenbankeinstellung maxActive kann es vorkommen dass zwar eine Session gestartet werden kann jedoch kein Datenexport zustande kommt
Der von BALVI voreingestellte Wert ist 2000
ltEnvironment
name=exportTokensmaxTokenCount
value=20 type=javalangInteger override=true
gt
exportTokenstokenExpirationInSeconds
Zeit in Sekunden die verstreichen muss bis ein Token unguumlltig wird falls darauf kein Zugriff mehr erfolgt Nach einem erfolgreichen Export wird der Token automatisch geschlossen diese Option ist fuumlr den Abbruchfall vorgesehen Der von BALVI voreingestellte Wert ist 180 (180 s = 3 min)
Release Notes BALVI Schnittstellenserver Seite 26 von 37
ltEnvironment
name=exportTokenstokenExpirationInSeconds
value=180 type=javalangInteger override=true
gt
exportTokenstokenDisposalInSeconds
Zeit in Sekunden die verstreichen muss bis ein Token das erfolgreich abgearbeitet wurde aus dem Cache geloumlscht wird Um sicher zu stellen dass der letzte Exportblock noch erfolgreich abgerufen werden kann bleibt der Token auch nach Fertigmeldung des Clients noch N Sek guumlltig
Der von BALVI voreingestellte Wert ist 60 (60 s = 1 min)
ltEnvironment
name=exportTokenstokenDisposalInSeconds
value=60 type=javalangInteger override=true
gt
2516 Job-Verwaltung fuumlr den BSS konfigurieren Aktivierung der Jobverwaltung
Bis zur Version 28 des BSS gab es den Parameter bdquoavailableServicesldquo Dieser konnte bei Bedarf aktiviert werden wenn die Jobs benoumltigt wurden
Mit Version 30 ist die Einstellung bdquoavailableServicesldquo zu entfernen und kann durch den neuen optionalen Parameter bdquoisJobServiceEnabledldquo in der Datei bdquocontextxmlldquo ersetzt werden
lt-- Neue Parameter zur Aktivierung des Job Service Ersatz fuumlr availableServices --gt
ltEnvironment
name=isJobServiceEnabled
value=true
type=javalangBoolean
override=true
gt
Ab BSS 30 wird die Jobs-Engine standardmaumlszligig aktiviert Sollte die Jobs-Engine nicht benoumltigt werden muss bdquovalueldquo der Wert bdquofalseldquo zugewiesen werden Wird bdquoisJobServiceEnabledldquo nicht eingefuumlgt sind die Jobs trotzdem standardmaumlszligig aktiv
Nach dem Neustart des Servers und erneutem Einloggen erscheint nun zusaumltzlich der Menuumlpunkt bdquoJobsldquo
bdquopasswordKeyldquo fuumlr Jobs
In der Job-Logik wird ein von BALVI definierter Standard-Schluumlssel fuumlr die Ablagen von schuumltzenswerten Daten z B Passwoumlrtern verwendet Diese Einstellung ermoumlglicht den BALVI-Standard zu uumlberschreiben Wenn Sie diese Einstellung aumlndern muumlssen jedoch alle bislang verschluumlsselten Job-Parameter neu verschluumlsselt werden
ltEnvironment
name=javacompenvjobspasswordKey
value=MeinHochsicheresNeuesPasswort
type=javalangString
Release Notes BALVI Schnittstellenserver Seite 27 von 37
override=true
gt
bdquoJob ID enableddisabledldquo (Deprecated ersetzt ab 28 durch das bdquoBindenldquo von Jobs)
Sondereinstellungen fuumlr die Job-Verwaltung Da alle Jobs in einer Datenbank administriert werden jedoch ggf verteilt auf mehreren Tomcat-Servern ausgefuumlhrt werden sollen besteht hier die Option Jobs fuumlr die aktuelle Tomcat-Instanz separat zu deaktivieren
Die Einstellung ID koumlnnte z B folgendermaszligen aussehen javacompenvjobsC0DB58D8D52C4BBC966D1DC788A4EF8Benabled
Fuumlr weitere Fragen zu dieser Einstellung kontaktieren Sie bitte die BALVI GmbH
ltEnvironment
name=javacompenvjobsIDenabled
value=false
type=javalangBoolean
override=true
gt
2517 Weitere optionale Parameter
Es ist fuumlr diverse einzelne Schnittstellen ggf erforderlich Einstellungen in der Datei bdquocontextxmlldquo zu ergaumlnzen Hinweise zu diesen Parametern sind dann in dem der Schnittstelle beiliegenden Dokument enthalten Das gilt z B fuumlr die Schnittstelle bdquoXGewerbeanzeigenldquo
26 Logging mit logback Das Logging wurde komplett uumlberarbeitet Statt bdquoLog4Jldquo wird jetzt bdquologbackldquo4 benutzt Ab BSS 30 ist es zwingend notwendig die Einstellung vorzunehmen um das Logging der Anwendung zu steuern
Migration Ergaumlnzen Sie die neue Einstellung bdquologgingconfigldquo
lt-- Neue Paramter zur Angabe der Logback Config Ersatz fuumlr log4jConfigLocation --gt
ltEnvironment
name=loggingconfig
value=$catalinabaseconflogback-bssxml
type=javalangString
override=true
gt
Nach wie vor steht es Ihnen frei die Logging-Konfiguration eigenstaumlndig anzupassen
Wenn Sie jedoch dieselbe WAR in einer Tomcat-Instanz unter mehreren Context-Namen betreiben wuumlrden beide dieselbe Logging-Konfiguration verwenden so dass alle Protokolleintraumlge in einer Log-Datei aus
4 httplogbackqoschmanualappendershtml
Release Notes BALVI Schnittstellenserver Seite 28 von 37
mehreren Webanwendungen generiert werden Aumlndern Sie den Namen der Logging-Konfiguration entsprechend ab um fuumlr jede Anwendung eine spezifische Logging-Einstellung vornehmen zu koumlnnen
27 Tocmat Optional Suche im bdquoKlassenpfadldquo um den
Ordner bdquoconfldquo erweitern Die Suche nach Dateien uumlber bdquoclasspathldquo setzt voraus dass die Ordner- und Dateinamen im Apache Tomcat bekannt gegeben werden Der Klassenpfad kann in der Datei bdquocatalinapropertiesldquo angepasst werden Wenn Sie dort unter commonloader die folgenden Werte ergaumlnzen kann eine Datei auch im Ordner conf abgelegt werden damit Apache Tomcat diese findet Ansonsten muss die Datei im Ordner lib abgelegt werden
commonloader=$catalinabaseconf$catalinahomeconf
3 Die neue Browser-Oberflaumlche Der BALVI Schnittstellenserver hat seit Version 25 neben der Protokollierung auch die Moumlglichkeit Job-Konfigurationen zu pflegen Der Login ist nur fuumlr einen in BALVI iP eingetragenen ADMIN (z B Benutzer bdquoSYSTEMADMINldquo) mit dem in BALVI iP hinterlegten Passwort moumlglich Zur Anmeldung muss immer [SYSTEMBenutzername] im Feld Benutzer angegeben werden ansonsten schlaumlgt die Anmeldung fehl Bitte achten Sie darauf dass der bdquoldquo (Slash) und nicht der bdquoldquo (Backslash) verwendet werden muss
31 Server-Protokoll Um das Server-Protokoll anzuzeigen waumlhlen Sie den entsprechenden Menuumlpunkt Dort haben Sie seit BSS 26 die Moumlglichkeit uumlber alle Spalten der Protokolle nach Informationen zu suchen
Seit BSS 31 gibt es die Moumlglichkeit Verfahren in bdquoKopfsaumltzeldquo und bdquoDetailsaumltzeldquo zu unterteilen Wurde das Verfahren entsprechend konfiguriert (wie z B bei der Schnittstelle bdquoXGewerbeanzeigenldquo) dann wird im Protokoll-Kopfsatz nur der Start und das Ende der Ausfuumlhrung in der Liste angezeigt Erst bei einem Klick auf bdquoInformationenldquo wird die Liste aller Detailsaumltze angezeigt die im Durchlauf erzeugt wurden
Release Notes BALVI Schnittstellenserver Seite 29 von 37
Verfahren
Die Liste der verfuumlgbaren Verfahren die bei Ihnen im System installiert sind ZB
BEFUNDEhellip Schnittstelle Befunde LM FM oder TS
PROBEhellip Schnittstelle zum Export von Proben an Labore ebenfalls Spezifisch fuumlr einzelne Fachbereiche
MOBILXT Protokolle der BALVI Mobil XT Synchronisation
WEB Allgemeine nicht spezifizierte Protokolle hierunter ist bislang auch die eFi-Protokollierung zu finden
WEB_I0802 Protokolle zur Schnittstelle BALVI iP LIMS (Lebensmittelproben)
XGEWERBE Schnittstelle XGewerbeanzeigen
Klicken Sie auf die Schaltflaumlche so besteht bei den neuen Protokolldatensaumltzen die Moumlglichkeit Detail-Informationen zum Protokollsatz zu erhalten
Release Notes BALVI Schnittstellenserver Seite 30 von 37
Seit BSS 30x ist die Anzeige der Protokolle ebenfalls farblich abgesetzt so dass Protokolleintraumlge mit Fehlern hellrot und Warnungen hellgelb hinterlegt werden
32 Jobs Mit einem Klick auf den Menuumlpunkt Jobs rufen Sie die Oberflaumlche fuumlr die Job-Konfiguration auf Daraufhin werden alle Jobs aufgelistet die fuumlr den BSS freigegeben sind Hier koumlnnen Sie Einstellungen an den Jobs vornehmen und die Jobs aktivieren bzw deaktivieren Die Beschreibungen bzw Einstellungsmoumlglichkeiten fuumlr den jeweiligen SST-Job sind nicht Bestandteil dieser Dokumentation
33 Log-Ausgaben Uumlber den Menuumlpunkt Log-Ausgaben koumlnnen Sie die Ausgabe der Protokolleintraumlge in Echtzeit beobachten
Release Notes BALVI Schnittstellenserver Seite 31 von 37
Starten Sie die Echtzeit-Protokollierung indem Sie auf die Schaltflaumlche mit dem Symbol bdquoPlayldquo (Dreieck) klicken unterbrechen Sie die Ausgabe indem Sie die auf Schaltflaumlche mit dem Symbol bdquoPauseldquo (zwei Balken) klicken
Klicken Sie auf die Schaltflaumlche bdquoAktualisierenldquo (zwei Pfeile) um die neuesten Protokolleintraumlge angezeigt zu bekommen
Klicken Sie auf das Symbol mit dem Papierkorb um die letzten Protokollmeldungen in der Anzeige zu loumlschen
Die Daten in den Protokolldateien auf der Festplatte des Servers sind davon nicht betroffen
Uumlber das Symbol bdquoLogging anpassenldquo (Schraubenschluumlssel) koumlnnen Sie die Ausgabe der Daten im Echtzeitfenster und in den Protokolldateien aumlndern jedoch ist diese Einstellung nur temporaumlr Die Standardeinstellungen koumlnnen ausschlieszliglich uumlber die Anpassung der Datei bdquologback-bssxmlldquo im Konfigurationsverzeichnis des Servers selbst geaumlndert werden
Release Notes BALVI Schnittstellenserver Seite 32 von 37
In der Logging-Parameter Konfiguration koumlnnen Sie verschiedene Parameter einstellen und uumlber die Schaltflaumlche bdquoAnwendenldquo dann sofort im Echtzeitprotokoll sehen Welche Einstellungen moumlglich sind erfahren Sie wenn es eine akute Fehlersituation gibt die detailliertere Ausgaben im Protokoll erfordert
Warnung Wenn Sie den Log-Level fuumlr ROOT oder eine andere Klasse auf TRACE einstellen werden sehr viele Protokollausgaben generiert die auch dazu fuumlhren koumlnnen dass der Server sehr langsam wird oder die Festplatte des Servers zulaumluft wenn fuumlr das Logging kein Dateilimit konfiguriert wurde
34 LogoutAbmeldung vom System Zum Abmelden waumlhlen Sie oben rechts das Kontextmenuuml
35 Cache loumlschen Der Cache wird in der Regel automatisch geloumlscht Wenn Sie jedoch gerade in BALVI iP eine Aumlnderung an den Schnittstellen eingespielt haben und moumlchten dass diese sofort wirksam wird kann die Funktion bdquoCache loumlschenldquo dazu verwendet werden dass der BALVI Schnittstellenserver die Einstellungen bei der naumlchsten Anfrage neu einliest
Release Notes BALVI Schnittstellenserver Seite 33 von 37
Release Notes BALVI Schnittstellenserver Seite 34 von 37
4 Einrichtung in BALVI iP Um die Verfahren fuumlr den BALVI Schnittstellenserver fuumlr Anwender freizuschalten wird das Objekt bdquoSystemeinstellungenldquo oder bdquoMandanten- und Benutzereinstellungenldquo verwendet Die Anpassung ist je Verfahren moumlglich so kann in BALVI iP fuumlr den Zugriff durch den BALVI Schnittstellenserver ein Benutzer bdquoAldquo am Verfahren bdquoMobilldquo berechtigt werden ein Benutzer bdquoBldquo nur am Verfahren bdquoSLA_FLESHldquo usw Die Logik ist jedoch einheitlich Je Verfahren wird durch BALVI eine Verfahrensgruppe mit dem Verfahrensnamen angelegt und mit den entsprechenden Einstellungen vorkonfiguriert welche durch das Verfahren erforderlich sind Dabei kann die Komplexitaumlt der Einstellungen variieren wie z B an den zu Version 23 verfuumlgbaren Verfahren bdquoMobilldquo und bdquoSLA_Fleshldquo ersichtlich wird
Im Verfahren BALVI Mobil sind diverse Anpassungen moumlglich welche je Bundesland oder eingesetzter Import- und Export-Variante durch den BALVI Schnittstellenserver bei der Bearbeitung von Anfragen gepruumlft werden siehe Punkt 3 Abb Mobil-Einstellung in BALVI iP
Abb Mobil-Einstellung in BALVI iP
Alle Verfahren verwenden jedoch die regulaumlre Benutzerverwaltung von BALVI iP Ein Benutzer ohne Passwort gilt fuumlr BALVI iP als gesperrt was fuumlr das Login bedeutet dass der Anwender sich nur uumlber die Active-Directory-Authentifizierung anmelden kann Ist das nicht moumlglich (bzw nicht konfiguriert) kann der Anwender sich weder in BALVI iP noch uumlber die Webservice-Schnittstelle authentifizieren
Fuumlr Dienste-Schnittstellen welche keine persoumlnliche Authentifizierung durch einen Anwender erfordern wird empfohlen einen separaten Benutzer in der Benutzerverwaltung anzulegen und ein sicheres Kennwort zu vergeben Das Anlegen von zusaumltzlichen Benutzern gilt nicht fuumlr BALVI mobil XT da beim Holen und Uumlbermitteln von Daten jeder Benutzer auch ein fachlich konfigurierter Anwender innerhalb von BALVI iP ist und die Anwendungsoberflaumlche ebenfalls zur Erfassung von Daten verwendet
Unter Punkt 2 der Abb Mobil-Einstellung in BALVI iP wird ein modales Fenster geoumlffnet (Abb BALVI mobil Benutzerverwaltung) Innerhalb dieses modalen Fensters werden mandantenweise die Benutzer fuumlr BALVI
Release Notes BALVI Schnittstellenserver Seite 35 von 37
mobil und den jeweiligen Fachbereich festgelegt Dabei ist es wichtig dass man die Haken bdquoAktiv fuumlr hellipldquo bei bdquohellip mobilldquo und bei einem Fachbereich (bdquohellip LMldquo bdquohellip FMldquo usw) setzt weil sonst uumlber den BALVI Schnittstellenserver keine Kommunikation mit BALVI iP moumlglich ist
Abb BALVI mobil Benutzerverwaltung
Alternativ zur Passwort-Authentifizierung wird wie beschrieben auch die Active-Directory-Authentifizierung angeboten Dazu muss der BALVI iP-Anwender uumlber die Schaltflaumlche bdquoDomaumlnen-Benutzer zuordnenldquo mit dem Active Directory verknuumlpft werden
Nur wenn die Active-Directory-Konfigurationen in BALVI iP und im BALVI Schnittstellenserver auf dieselbe Domaumlne verweisen sind die Domaumlnen-Zuordnung und die Active-Directory-Authentifizierung (z B uumlber BALVI mobil XT) moumlglich
Release Notes BALVI Schnittstellenserver Seite 36 von 37
5 Bekannte Probleme und Loumlsungen
51 ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner Bei der Job-Bearbeitung tritt folgender Fehler auf ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner
Behebung
Fuumlhren Sie das beiliegende IP-Patch (UPDATEexe) aus bevor Sie das WAR austauschen
52 Server startet nicht Sie finden folgende Zeilen im Protokoll (catalinaout oder bsslog)
ERROR [localhost-startStop-1] [IdentityServiceImpl] serverID must not be empty
ERROR [localhost-startStop-1] [ContextLoader] Context initialization failed
Behebung
Setzen Sie die Umgebungsvariable ldquoserverIDrdquo in der Datei bdquocontextxmlldquo
53 ORA-00942 table or view does not exist In vielen Faumlllen wird der Fehler ldquoTabelle oder View nicht vorhandenrdquo ausgeworfen (Java-Protokoll im Ordner logs von Apache Tomcat) wenn eine neue Schnittstelle eingerichtet oder ein neues BALVI iP Release bzw Update eingespielt wurde ohne anschlieszligend das aktuelle GRANT-Skript auszufuumlhren
Behebung
Fuumlhren Sie das GRANT-Skript erneut aus
54 ORA-0406x bdquoBestehender Paketstatus wurde aufgehobenldquo
ORA-04061 Bestehender Status von package body ABCXYZ wurde annulliert
ORA-04065 Ausfuumlhrung nicht erfolgreich package body ABCXYZ wurde geaumlndert oder geloumlscht
Release Notes BALVI Schnittstellenserver Seite 37 von 37
Der Fehler tritt haumlufig ein nachdem die UPDATEexe ausgefuumlhrt und in der Ausfuumlhrungsliste ein Package aktualisiert wurde Oracle merkt sich je User-Session bestimmte Werte im Package wenn der Anwender es verwendet hat Durch einen bdquoCREATE OR REPLACE PACKAGEldquo-Befehl kann dieser Status temporaumlr aufgehoben werden Normalerweise tritt dieser Fehler nach dem Update genau einmal in jeder aktiven Session auf wenn der BSS nicht neu gestartet wird
Behebung
Starten Sie nach jedem Update den BSS neu um alle laufenden Sessions zu beenden
55 Jobs sind nicht ausfuumlhrbar
1 Ein Job wird mit dem Status bdquoNicht unterstuumltztldquo angezeigt wenn fuumlr seine Ausfuumlhrung eine houmlhere Version des BSS erforderlich ist
2 Nach dem Klonen der Datenbank von der Produktions- auf die Testumgebung erhalten alle Jobs automatisch den Status bdquoDeaktiviertldquo wenn die bdquoserverIDldquo nicht identisch ist
Beide Statusaumlnderungen sind gewollt Damit soll verhindert werden dass Jobs nach einem Serverneustart oder nach einem Update automatisch starten und dabei Fehler verursachen
Um Jobs mit dem Status bdquoNicht unterstuumltztldquo nutzen und konfigurieren zu koumlnnen ist es erforderlich den BALVI Schnittstellenserver zu aktualisieren
Deaktivierte Jobs koumlnnen Sie aktivieren indem Sie den jeweiligen Job an den aktuellen Server binden und den Haken bei bdquoAktivldquo setzen
Release Notes BALVI Schnittstellenserver Seite 19 von 37
Oracle bietet dafuumlr die virtuelle Tabelle DUAL an welche sich fuumlr die ValidationQuery sehr gut eignet da die Abfrage kaum Ressourcen verbraucht
validationQuery=select 1 from dual
2 testOnBorrow - Boolscher Wert true oder false
Diese Einstellung sorgt dafuumlr dass der Pool die Verfuumlgbarkeit anhand der validationQuery pruumlft bevor
die DB-Verbindung an die Anwendung ausgeliehen wird Empfehlung
testOnBorrow=true
3 testWhileIdle - Boolscher Wert true oder false
Diese Einstellung ist hilfreich wenn zwischen dem Tomcat und der DB eine Firewall mit Stateful
Packet Inspection verwendet wird Nach laumlngerer Inaktivitaumlt wird normalerweise durch die Firewall die
DB-Verbindung geschlossen Dieses loumlst dann beim Ausleihen der Verbindung eine Fehlermeldung im
Protokoll aus 2012-08-16 165418720 WARN [http-0000-8080-8]
[orgspringframeworkjdbcsupportSQLErrorCodesFactory] Error while extracting
database product name - falling back to empty error codes
orgspringframeworkjdbcsupportMetaDataAccessException Error while extracting
DatabaseMetaData nested exception is javasqlSQLRecoverableException Getrennte
Verbindung Um dieses Problem zu beheben sollte die Option testWhileIdle=true eingestellt werden
testWhileIdle=true
Damit diese weiszlig wie oft eine Pruumlfung durchgefuumlhrt werden muss sind jedoch noch zusaumltzliche Angaben erforderlich welche fuumlr die Einstellung der Zeit zusaumltzlich gesetzt werden muumlssen
a) minEvictableIdleTimeMillis - Long in Millisekunden
Min Zeit wie lange eine DB-Verbindung im Leerlauf ist bevor diese zur Pruumlfung
gekennzeichnet wird Dieses haumlngt stark von der Einstellung der Firewall ab Wenn Sie eine
sehr restriktive Firewall haben kann es sein dass diese die Verbindung nach wenigen
Minuten Leerlauf trennt Stellen Sie den Wert immer so ein dass dieser unter der Leerlaufzeit
der Firewall liegt empfohlen 300000 entspricht 300 Sek = 5 min
minEvictableIdleTimeMillis=300000
b) timeBetweenEvictionRunsMillis - Long in Millisekunden
Der Pruumlflauf startet in der Default-Konfiguration alle 1800000 Millisekunden = 30 Min n als
zu Pruumlfen markierte Verbindungen werden in einem Pruumlflauf getestet n wird bestimmt durch
die Einstellung numTestsPerEvictionRun Empfehlung Stellen Sie den Wert auf alle 15 Min
ein
timeBetweenEvictionRunsMillis=900000
Release Notes BALVI Schnittstellenserver Seite 20 von 37
c) numTestsPerEvictionRun - Integer
Wie viele Verbindungen sollen getestet werden waumlhrend der Pruumlflauf ausgefuumlhrt wird Im
Normalfall sollte die Anzahl der zu testenden Verbindungen nicht zu hoch eingestellt werden
Der Default ist 3 Wenn Sie houmlhere Sicherheit haben wollen dass keine bdquototenldquo
Datenbankverbindungen bestehen bleiben erhoumlhen Sie den Wert auf max bdquo(maxActive ndash
maxIdle) 2ldquo Wenn Ihnen 3 ausreichend erscheint muss der Wert nicht gesetzt sein dann
wird der Default verwendet
Beispiel numTestsPerEvictionRun=10
4 Interceptors konfigurieren Neu ergaumlnzt wurde die Moumlglichkeit spezielle bdquoInterceptorsldquo zu konfigurieren die ermoumlglichen das Verhalten des Pools zu steuern Wichtig hierbei ist dass die Angabe von Werten auf real existierende Java-Klassen erfolgt die im Classpath des Tomcat vorhanden sind Groszlig-und-Kleinschreibung ist zu beachten Folgende Default-Einstellung hat BALVI fuumlr den BSS festgelegt jdbcInterceptors=
orgapachetomcatjdbcpoolinterceptorConnectionState
orgapachetomcatjdbcpoolinterceptorStatementFinalizer
orgapachetomcatjdbcpoolinterceptorResetAbandonedTimer
Details zu den verwendeten Interceptor-Einstellungen finden Sie in der Tomcat-Dokumentation3
3 httptomcatapacheorgtomcat-80-docjdbc-poolhtmlJDBC_interceptors
Release Notes BALVI Schnittstellenserver Seite 21 von 37
2512 Datenbank-Zugangsdaten verschluumlsseln
Die Verschluumlsselung fuumlr die Datenbank-Verbindung (bdquoEncrypted Datasourceldquo) ist eine Ableitung der Bibliothek Apache-Common-DBCP-14 und daher nicht mehr mit Java 8 kompatibel Die Einrichtung der Verschluumlsselung wird daher mit der Auslieferung des BSS 30 nicht mehr angeboten
2513 Active-Directory-Authentifizierung
Uumlber die folgenden Parameter wird der Zugriff des Schnittstellen-Servers auf einen Microsoft Active Directory Domain-Controller konfiguriert
ldquoldapServerAddressrdquo
Syntax PROTOKOLLIP-Adresse oder DNS-NamePORT
ltEnvironment
name=ldapServerAddress
value=ldapbl2-dc02balviintern389
type=javalangString
override=true
gt
Als Protokoll besteht auch die Moumlglichkeit ldaps (LDAP+SSL) wenn der Domain-Controller entsprechend konfiguriert wurde Im Java Truststore muss dann das Zertifikat der CA vorhanden sein welche das Zertifikat des Domain-Controllers signiert hat Zudem darf bei ldaps keine IP-Adresse verwendet werden es muss der DNS-Name des Server-Zertifikats eingetragen sein Ansonsten gibt es beim Verbinden eine Sicherheits-Exception
lt-- SSL-Beispiel
ltEnvironment
name=ldapServerAddress
value=ldapsbl2-dc02balviintern636
type=javalangString
override=true
gt
--gt
bdquoldapBaseDnrdquo
LDAP-Suchpfad fuumlr die Domain-Basis Diese muss der LDAP-Syntax fuumlr den Domain-Suffix entsprechen
Syntax DC=SERVERDC=ROOTDN
ltEnvironment
name=ldapBaseDn
value=DC=BALVIDC=INTERN
type=javalangString
override=true
gt
Release Notes BALVI Schnittstellenserver Seite 22 von 37
bdquowebLoginUseActiveDirectoryAuthenticationrdquo
Die Authentifizierung in der Browser-Oberflaumlche kann uumlber die Active-Directory-Authentifizierung erfolgen In der ersten Version ist nur die Protokoll-Auswertung moumlglich wenn der ADMIN sich anmeldet Dieser hat normalerweise niemals AD-Kennungen zugeordnet BALVI empfiehlt diese Einstellung auf bdquofalseldquo zu belassen Webservices welche uumlber SOAPREST zugreifen koumlnnen die Active-Directory-Authentifizierung trotzdem verwenden
ltEnvironment
name=webLoginUseActiveDirectoryAuthentication
value=false
type=javalangBoolean
override=true
gt
ldquoldapDaysBeforeExpirationNotificationrdquo
Die Passwort-Aumlnderung im Active-Directory uumlber die Browser-Oberflaumlche ist in der ersten Version noch nicht implementiert der Parameter wird bislang nicht ausgewertet
ltEnvironment
name=ldapDaysBeforeExpirationNotification
value=14
type=javalangInteger
override=true
gt
2514 Statement-Protokollierung in BALVI iP
Diese Option aktiviert die Lese- und Aumlnderungsprotokollierung fuumlr BALVI iP Standard ist bdquofalseldquo und wird fuumlr alle Kunden empfohlen solange keine speziellen Datenbank-Jobs eingerichtet wurden welche zeitgesteuert die Protokolleintraumlge wieder loumlschen Fuumlr Bayern wurde ein spezielles Konzept zur Leseprotokollierung entworfen Wenn Sie mehr daruumlber erfahren moumlchten kontaktieren Sie bitte die BALVI GmbH
ltEnvironment
name=enableSqlStatementMonitoring
value=true
type=javalangBoolean
override=true
gt
Beachten Sie dass diese Option massive INSERT-Statements in BALVI iP in die Tabelle VIS_D92 ausfuumlhrt Jedes abgesetzte SQL-Statement wird dabei vollstaumlndig protokolliert Dieses erzeugt eine sehr hohe INSERT-Last und in der Folge auch erhoumlhte Redolog-Switches und COMMIT-Transaktionen
Optional Aktivieren der INSERT + APPEND - Logik
Beachten Sie bitte die Hinweise von Oracle zum Hint + APPEND
Release Notes BALVI Schnittstellenserver Seite 23 von 37
Wenn Sie dieses Verhalten aktivieren moumlchten ergaumlnzen Sie bitte den folgenden Environment-Parameter
ltEnvironment
name=statementMonitoringactivateAppendMode
value=true
type=javalangBoolean
override=true
gt
2515 Einstellungen fuumlr BALVI mobil XT (bzw den bdquopartitionedExportldquo)
Diese Logik des FIFO-Buffers wurde so konzipiert dass dem Rechenzentrum diverse Einstellmoumlglichkeiten uumlber die Datei bdquocontextxmlldquo zur Verfuumlgung stehen um die Steuerung des FIFO-Puffers zu beeinflussen
Schematische Darstellung des FIFO-Puffers
Das ermoumlglicht es z B dem BALVI mobil XT Client (14 oder houmlher) den aktiven Block abzuholen und dies beim Fehler bis zu 10-mal zu wiederholen Sobald der Block [001] erfolgreich beim Client angekommen ist und dieser den naumlchsten Block anfragt wird der Block [001] verworfen wird Der Server fuumlllt dann im Hintergrund den frei gewordenen Block wieder waumlhrend der Client den Block [002] abholt
Die Groumlszlige und Anzahl der vorgecachten Bloumlcke kann uumlber die folgenden Einstellungen in der Datei bdquocontextxmlldquo definiert werden
ltEnvironment
name=partitionedExportmaxBufferedPartitions
value=3 type=javalangInteger override=true
gt
ltEnvironment
name=partitionedExportpartitionSize
value=256000 type=javalangInteger override=true
gt
Die Einstellung partitionedExportmaxBufferedPartitions ist dabei die Anzahl der vorgecachten Bloumlcke mindestens muss 2 angegeben werden Der Puffercache wird ausschlieszliglich im RAM der JVM aufgebaut es wird folglich mehr Arbeitsspeicher verwendet Dieser Arbeitsspeicher muss je gleichzeitiger Session auf dem Server bereitgestellt werden die Default-Einstellung mit 3 Partitionen a 256 KB + dem aktiven Puffer erfordern 1 MB RAM je aktiven Anwender
Aktiv
er
Puffe
r
[001] Vorg
ecac
hter
Bl
ock
[002] Vorg
ecac
hter
Bl
ock
[003]
Aktiv
er P
uffe
r
[002] Vorg
ecac
hter
Bl
ock
[003] Vorg
ecac
hter
Bl
ock
[leer]
Release Notes BALVI Schnittstellenserver Seite 24 von 37
Gleichzeitig wurde die Moumlglichkeit geschaffen dass die maximale Anzahl an gleichzeitigen Exporten durch das Rechenzentrum eingeschraumlnkt werden kann um einem OutOfMemory-Fehler vorzubeugen Die Einstellung
ltEnvironment
name=partitionedExportmaxConcurrentExports
value=10 type=javalangInteger override=true
gt
muss entsprechend der zu erwartenden gleichzeitigen Zugriffe konzipiert werden ansonsten wird der Server einen Verbindungsversuch durch die Clients ablehnen
Beachten Sie dass die folgenden Einstellungen partitionedExportmaxBufferedPartitions partitionedExportmaxConcurrentExports und partitionedExportpartitionSize gemeinsam als Rechenbasis fuumlr den RAM-Bedarf des Webservers herangezogen werden muumlssen
Folgende Faustformel sollte fuumlr die Einrichtung verwendet werden
Min 256 MB (Serverbasis) + (11 partitionedExportmaxConcurrentExports partitionedExportmaxBufferedPartitions partitionedExportpartitionSize)
Beispiel 50 gleichzeitige Anwender Blockgroumlszlige 256 KB 4 Partitionen
256 MB + (11 50 256 4) KB = 312 MB fuumlr die JVM
Empf 512 MB (Serverbasis) + (12 partitionedExportmaxConcurrentExports partitionedExportmaxBufferedPartitions partitionedExportpartitionSize)
Beispiel 50 gleichzeitige Anwender Blockgroumlszlige 256 KB 4 Partitionen
512 MB + (12 50 256 4) KB = 572 MB fuumlr die JVM
partitionedExportmaxConcurrentExports
Bestimmt die Anzahl der maximalen Export Tasks (Threads) die fuumlr partitionierte Exporte bereitgestellt werden Wenn die Anzahl uumlberschritten wird wird die entsprechende Exportanfrage abgewiesen und der Client muss zu einem spaumlteren Zeitpunkt erneut anfragen Stellen Sie diesen Wert entsprechend der zu erwartenden Benutzeranzahl ein bei 50 Anwendern also 50
Exporte oumlffnen auf der Datenbank entsprechend zur Ausfuumlhrungszeit min einen Cursor ggf fuumlr rekursive Unterabfragen kurzfristig sogar mehr Die hier eingestellte Anzahl muss mit der Anzahl von maxActive korrelieren
ltEnvironment
name=partitionedExportmaxConcurrentExports
value=10 type=javalangInteger override=true
gt
partitionedExportmaxBufferedPartitions
Bestimmt die Anzahl der Datenbloumlcke (Partitionen) die vom Server bei Abruf eines Exportes gepuffert werden Die seit Version 24 eingefuumlhrte FIFO-Puffer-Logik ermoumlglicht dass der Server schon die Ergebnisse vorpuffert so dass der Client weniger Wartezeiten bei der Anfrage nach Daten hat Diese
Release Notes BALVI Schnittstellenserver Seite 25 von 37
Puffer-Logik unterteilt den Exportdatenstrom (je Export) in mehre Bloumlcke Der Client kann nun den letzten Block neu anfordern oder den naumlchsten Block wenn der letzte Block erfolgreich verarbeitet wurde Wie viele naumlchste Bloumlcke durch den Server bereit gestellt werden entscheidet diese Einstellung Sobald kein naumlchster Block mehr bereit gestellt werden muss wird der Datenbank-Cursor geschlossen eine Erhoumlhung kann also zu einer Entlastung der aktiven DB-Verbindungen fuumlhren erhoumlht jedoch den Bedarf an RAM des Servers
Der von BALVI voreingestellte Wert ist 3
ltEnvironment
name=partitionedExportmaxBufferedPartitions
value=3 type=javalangInteger override=true
gt
partitionedExportpartitionSizeldquo
Die Groumlszlige der Datenbloumlcke (Partitionen) die an den Client uumlbermittelt werden in Bytes Wenn Sie diesen Wert zu niedrig einstellen reduziert sich die Effizienz des Caches da der Client mehr Datenbloumlcke hintereinander abrufen muss Waumlhlen Sie einen zu groszligen Wert wird die neu zu uumlbertragende Datenmenge im Fall eines Fehlers houmlher
Der von BALVI voreingestellte Wert ist 256000 (256 KB)
ltEnvironment
name=partitionedExportpartitionSize
value=256000 type=javalangInteger override=true
gt
exportTokensmaxTokenCount
Maximale Anzahl der gleichzeitig vergebenen Token die vom Server gecached werden Jede Sitzung welche einen Export durchfuumlhrt erhaumllt einen Session-Token
Wenn eine Sitzung laumlngere Zeit nicht verwendet wurde wird dieser Session-Token wieder entfernt Wenn Sie den Wert zu niedrig einstellen fuumlhrt das zu einer generellen Session-Begrenzung auch fuumlr den nicht partitionierten Export-Modus welcher ab Version 21 verfuumlgbar ist
Ist die Anzahl der Tokens houmlher als die Datenbankeinstellung maxActive kann es vorkommen dass zwar eine Session gestartet werden kann jedoch kein Datenexport zustande kommt
Der von BALVI voreingestellte Wert ist 2000
ltEnvironment
name=exportTokensmaxTokenCount
value=20 type=javalangInteger override=true
gt
exportTokenstokenExpirationInSeconds
Zeit in Sekunden die verstreichen muss bis ein Token unguumlltig wird falls darauf kein Zugriff mehr erfolgt Nach einem erfolgreichen Export wird der Token automatisch geschlossen diese Option ist fuumlr den Abbruchfall vorgesehen Der von BALVI voreingestellte Wert ist 180 (180 s = 3 min)
Release Notes BALVI Schnittstellenserver Seite 26 von 37
ltEnvironment
name=exportTokenstokenExpirationInSeconds
value=180 type=javalangInteger override=true
gt
exportTokenstokenDisposalInSeconds
Zeit in Sekunden die verstreichen muss bis ein Token das erfolgreich abgearbeitet wurde aus dem Cache geloumlscht wird Um sicher zu stellen dass der letzte Exportblock noch erfolgreich abgerufen werden kann bleibt der Token auch nach Fertigmeldung des Clients noch N Sek guumlltig
Der von BALVI voreingestellte Wert ist 60 (60 s = 1 min)
ltEnvironment
name=exportTokenstokenDisposalInSeconds
value=60 type=javalangInteger override=true
gt
2516 Job-Verwaltung fuumlr den BSS konfigurieren Aktivierung der Jobverwaltung
Bis zur Version 28 des BSS gab es den Parameter bdquoavailableServicesldquo Dieser konnte bei Bedarf aktiviert werden wenn die Jobs benoumltigt wurden
Mit Version 30 ist die Einstellung bdquoavailableServicesldquo zu entfernen und kann durch den neuen optionalen Parameter bdquoisJobServiceEnabledldquo in der Datei bdquocontextxmlldquo ersetzt werden
lt-- Neue Parameter zur Aktivierung des Job Service Ersatz fuumlr availableServices --gt
ltEnvironment
name=isJobServiceEnabled
value=true
type=javalangBoolean
override=true
gt
Ab BSS 30 wird die Jobs-Engine standardmaumlszligig aktiviert Sollte die Jobs-Engine nicht benoumltigt werden muss bdquovalueldquo der Wert bdquofalseldquo zugewiesen werden Wird bdquoisJobServiceEnabledldquo nicht eingefuumlgt sind die Jobs trotzdem standardmaumlszligig aktiv
Nach dem Neustart des Servers und erneutem Einloggen erscheint nun zusaumltzlich der Menuumlpunkt bdquoJobsldquo
bdquopasswordKeyldquo fuumlr Jobs
In der Job-Logik wird ein von BALVI definierter Standard-Schluumlssel fuumlr die Ablagen von schuumltzenswerten Daten z B Passwoumlrtern verwendet Diese Einstellung ermoumlglicht den BALVI-Standard zu uumlberschreiben Wenn Sie diese Einstellung aumlndern muumlssen jedoch alle bislang verschluumlsselten Job-Parameter neu verschluumlsselt werden
ltEnvironment
name=javacompenvjobspasswordKey
value=MeinHochsicheresNeuesPasswort
type=javalangString
Release Notes BALVI Schnittstellenserver Seite 27 von 37
override=true
gt
bdquoJob ID enableddisabledldquo (Deprecated ersetzt ab 28 durch das bdquoBindenldquo von Jobs)
Sondereinstellungen fuumlr die Job-Verwaltung Da alle Jobs in einer Datenbank administriert werden jedoch ggf verteilt auf mehreren Tomcat-Servern ausgefuumlhrt werden sollen besteht hier die Option Jobs fuumlr die aktuelle Tomcat-Instanz separat zu deaktivieren
Die Einstellung ID koumlnnte z B folgendermaszligen aussehen javacompenvjobsC0DB58D8D52C4BBC966D1DC788A4EF8Benabled
Fuumlr weitere Fragen zu dieser Einstellung kontaktieren Sie bitte die BALVI GmbH
ltEnvironment
name=javacompenvjobsIDenabled
value=false
type=javalangBoolean
override=true
gt
2517 Weitere optionale Parameter
Es ist fuumlr diverse einzelne Schnittstellen ggf erforderlich Einstellungen in der Datei bdquocontextxmlldquo zu ergaumlnzen Hinweise zu diesen Parametern sind dann in dem der Schnittstelle beiliegenden Dokument enthalten Das gilt z B fuumlr die Schnittstelle bdquoXGewerbeanzeigenldquo
26 Logging mit logback Das Logging wurde komplett uumlberarbeitet Statt bdquoLog4Jldquo wird jetzt bdquologbackldquo4 benutzt Ab BSS 30 ist es zwingend notwendig die Einstellung vorzunehmen um das Logging der Anwendung zu steuern
Migration Ergaumlnzen Sie die neue Einstellung bdquologgingconfigldquo
lt-- Neue Paramter zur Angabe der Logback Config Ersatz fuumlr log4jConfigLocation --gt
ltEnvironment
name=loggingconfig
value=$catalinabaseconflogback-bssxml
type=javalangString
override=true
gt
Nach wie vor steht es Ihnen frei die Logging-Konfiguration eigenstaumlndig anzupassen
Wenn Sie jedoch dieselbe WAR in einer Tomcat-Instanz unter mehreren Context-Namen betreiben wuumlrden beide dieselbe Logging-Konfiguration verwenden so dass alle Protokolleintraumlge in einer Log-Datei aus
4 httplogbackqoschmanualappendershtml
Release Notes BALVI Schnittstellenserver Seite 28 von 37
mehreren Webanwendungen generiert werden Aumlndern Sie den Namen der Logging-Konfiguration entsprechend ab um fuumlr jede Anwendung eine spezifische Logging-Einstellung vornehmen zu koumlnnen
27 Tocmat Optional Suche im bdquoKlassenpfadldquo um den
Ordner bdquoconfldquo erweitern Die Suche nach Dateien uumlber bdquoclasspathldquo setzt voraus dass die Ordner- und Dateinamen im Apache Tomcat bekannt gegeben werden Der Klassenpfad kann in der Datei bdquocatalinapropertiesldquo angepasst werden Wenn Sie dort unter commonloader die folgenden Werte ergaumlnzen kann eine Datei auch im Ordner conf abgelegt werden damit Apache Tomcat diese findet Ansonsten muss die Datei im Ordner lib abgelegt werden
commonloader=$catalinabaseconf$catalinahomeconf
3 Die neue Browser-Oberflaumlche Der BALVI Schnittstellenserver hat seit Version 25 neben der Protokollierung auch die Moumlglichkeit Job-Konfigurationen zu pflegen Der Login ist nur fuumlr einen in BALVI iP eingetragenen ADMIN (z B Benutzer bdquoSYSTEMADMINldquo) mit dem in BALVI iP hinterlegten Passwort moumlglich Zur Anmeldung muss immer [SYSTEMBenutzername] im Feld Benutzer angegeben werden ansonsten schlaumlgt die Anmeldung fehl Bitte achten Sie darauf dass der bdquoldquo (Slash) und nicht der bdquoldquo (Backslash) verwendet werden muss
31 Server-Protokoll Um das Server-Protokoll anzuzeigen waumlhlen Sie den entsprechenden Menuumlpunkt Dort haben Sie seit BSS 26 die Moumlglichkeit uumlber alle Spalten der Protokolle nach Informationen zu suchen
Seit BSS 31 gibt es die Moumlglichkeit Verfahren in bdquoKopfsaumltzeldquo und bdquoDetailsaumltzeldquo zu unterteilen Wurde das Verfahren entsprechend konfiguriert (wie z B bei der Schnittstelle bdquoXGewerbeanzeigenldquo) dann wird im Protokoll-Kopfsatz nur der Start und das Ende der Ausfuumlhrung in der Liste angezeigt Erst bei einem Klick auf bdquoInformationenldquo wird die Liste aller Detailsaumltze angezeigt die im Durchlauf erzeugt wurden
Release Notes BALVI Schnittstellenserver Seite 29 von 37
Verfahren
Die Liste der verfuumlgbaren Verfahren die bei Ihnen im System installiert sind ZB
BEFUNDEhellip Schnittstelle Befunde LM FM oder TS
PROBEhellip Schnittstelle zum Export von Proben an Labore ebenfalls Spezifisch fuumlr einzelne Fachbereiche
MOBILXT Protokolle der BALVI Mobil XT Synchronisation
WEB Allgemeine nicht spezifizierte Protokolle hierunter ist bislang auch die eFi-Protokollierung zu finden
WEB_I0802 Protokolle zur Schnittstelle BALVI iP LIMS (Lebensmittelproben)
XGEWERBE Schnittstelle XGewerbeanzeigen
Klicken Sie auf die Schaltflaumlche so besteht bei den neuen Protokolldatensaumltzen die Moumlglichkeit Detail-Informationen zum Protokollsatz zu erhalten
Release Notes BALVI Schnittstellenserver Seite 30 von 37
Seit BSS 30x ist die Anzeige der Protokolle ebenfalls farblich abgesetzt so dass Protokolleintraumlge mit Fehlern hellrot und Warnungen hellgelb hinterlegt werden
32 Jobs Mit einem Klick auf den Menuumlpunkt Jobs rufen Sie die Oberflaumlche fuumlr die Job-Konfiguration auf Daraufhin werden alle Jobs aufgelistet die fuumlr den BSS freigegeben sind Hier koumlnnen Sie Einstellungen an den Jobs vornehmen und die Jobs aktivieren bzw deaktivieren Die Beschreibungen bzw Einstellungsmoumlglichkeiten fuumlr den jeweiligen SST-Job sind nicht Bestandteil dieser Dokumentation
33 Log-Ausgaben Uumlber den Menuumlpunkt Log-Ausgaben koumlnnen Sie die Ausgabe der Protokolleintraumlge in Echtzeit beobachten
Release Notes BALVI Schnittstellenserver Seite 31 von 37
Starten Sie die Echtzeit-Protokollierung indem Sie auf die Schaltflaumlche mit dem Symbol bdquoPlayldquo (Dreieck) klicken unterbrechen Sie die Ausgabe indem Sie die auf Schaltflaumlche mit dem Symbol bdquoPauseldquo (zwei Balken) klicken
Klicken Sie auf die Schaltflaumlche bdquoAktualisierenldquo (zwei Pfeile) um die neuesten Protokolleintraumlge angezeigt zu bekommen
Klicken Sie auf das Symbol mit dem Papierkorb um die letzten Protokollmeldungen in der Anzeige zu loumlschen
Die Daten in den Protokolldateien auf der Festplatte des Servers sind davon nicht betroffen
Uumlber das Symbol bdquoLogging anpassenldquo (Schraubenschluumlssel) koumlnnen Sie die Ausgabe der Daten im Echtzeitfenster und in den Protokolldateien aumlndern jedoch ist diese Einstellung nur temporaumlr Die Standardeinstellungen koumlnnen ausschlieszliglich uumlber die Anpassung der Datei bdquologback-bssxmlldquo im Konfigurationsverzeichnis des Servers selbst geaumlndert werden
Release Notes BALVI Schnittstellenserver Seite 32 von 37
In der Logging-Parameter Konfiguration koumlnnen Sie verschiedene Parameter einstellen und uumlber die Schaltflaumlche bdquoAnwendenldquo dann sofort im Echtzeitprotokoll sehen Welche Einstellungen moumlglich sind erfahren Sie wenn es eine akute Fehlersituation gibt die detailliertere Ausgaben im Protokoll erfordert
Warnung Wenn Sie den Log-Level fuumlr ROOT oder eine andere Klasse auf TRACE einstellen werden sehr viele Protokollausgaben generiert die auch dazu fuumlhren koumlnnen dass der Server sehr langsam wird oder die Festplatte des Servers zulaumluft wenn fuumlr das Logging kein Dateilimit konfiguriert wurde
34 LogoutAbmeldung vom System Zum Abmelden waumlhlen Sie oben rechts das Kontextmenuuml
35 Cache loumlschen Der Cache wird in der Regel automatisch geloumlscht Wenn Sie jedoch gerade in BALVI iP eine Aumlnderung an den Schnittstellen eingespielt haben und moumlchten dass diese sofort wirksam wird kann die Funktion bdquoCache loumlschenldquo dazu verwendet werden dass der BALVI Schnittstellenserver die Einstellungen bei der naumlchsten Anfrage neu einliest
Release Notes BALVI Schnittstellenserver Seite 33 von 37
Release Notes BALVI Schnittstellenserver Seite 34 von 37
4 Einrichtung in BALVI iP Um die Verfahren fuumlr den BALVI Schnittstellenserver fuumlr Anwender freizuschalten wird das Objekt bdquoSystemeinstellungenldquo oder bdquoMandanten- und Benutzereinstellungenldquo verwendet Die Anpassung ist je Verfahren moumlglich so kann in BALVI iP fuumlr den Zugriff durch den BALVI Schnittstellenserver ein Benutzer bdquoAldquo am Verfahren bdquoMobilldquo berechtigt werden ein Benutzer bdquoBldquo nur am Verfahren bdquoSLA_FLESHldquo usw Die Logik ist jedoch einheitlich Je Verfahren wird durch BALVI eine Verfahrensgruppe mit dem Verfahrensnamen angelegt und mit den entsprechenden Einstellungen vorkonfiguriert welche durch das Verfahren erforderlich sind Dabei kann die Komplexitaumlt der Einstellungen variieren wie z B an den zu Version 23 verfuumlgbaren Verfahren bdquoMobilldquo und bdquoSLA_Fleshldquo ersichtlich wird
Im Verfahren BALVI Mobil sind diverse Anpassungen moumlglich welche je Bundesland oder eingesetzter Import- und Export-Variante durch den BALVI Schnittstellenserver bei der Bearbeitung von Anfragen gepruumlft werden siehe Punkt 3 Abb Mobil-Einstellung in BALVI iP
Abb Mobil-Einstellung in BALVI iP
Alle Verfahren verwenden jedoch die regulaumlre Benutzerverwaltung von BALVI iP Ein Benutzer ohne Passwort gilt fuumlr BALVI iP als gesperrt was fuumlr das Login bedeutet dass der Anwender sich nur uumlber die Active-Directory-Authentifizierung anmelden kann Ist das nicht moumlglich (bzw nicht konfiguriert) kann der Anwender sich weder in BALVI iP noch uumlber die Webservice-Schnittstelle authentifizieren
Fuumlr Dienste-Schnittstellen welche keine persoumlnliche Authentifizierung durch einen Anwender erfordern wird empfohlen einen separaten Benutzer in der Benutzerverwaltung anzulegen und ein sicheres Kennwort zu vergeben Das Anlegen von zusaumltzlichen Benutzern gilt nicht fuumlr BALVI mobil XT da beim Holen und Uumlbermitteln von Daten jeder Benutzer auch ein fachlich konfigurierter Anwender innerhalb von BALVI iP ist und die Anwendungsoberflaumlche ebenfalls zur Erfassung von Daten verwendet
Unter Punkt 2 der Abb Mobil-Einstellung in BALVI iP wird ein modales Fenster geoumlffnet (Abb BALVI mobil Benutzerverwaltung) Innerhalb dieses modalen Fensters werden mandantenweise die Benutzer fuumlr BALVI
Release Notes BALVI Schnittstellenserver Seite 35 von 37
mobil und den jeweiligen Fachbereich festgelegt Dabei ist es wichtig dass man die Haken bdquoAktiv fuumlr hellipldquo bei bdquohellip mobilldquo und bei einem Fachbereich (bdquohellip LMldquo bdquohellip FMldquo usw) setzt weil sonst uumlber den BALVI Schnittstellenserver keine Kommunikation mit BALVI iP moumlglich ist
Abb BALVI mobil Benutzerverwaltung
Alternativ zur Passwort-Authentifizierung wird wie beschrieben auch die Active-Directory-Authentifizierung angeboten Dazu muss der BALVI iP-Anwender uumlber die Schaltflaumlche bdquoDomaumlnen-Benutzer zuordnenldquo mit dem Active Directory verknuumlpft werden
Nur wenn die Active-Directory-Konfigurationen in BALVI iP und im BALVI Schnittstellenserver auf dieselbe Domaumlne verweisen sind die Domaumlnen-Zuordnung und die Active-Directory-Authentifizierung (z B uumlber BALVI mobil XT) moumlglich
Release Notes BALVI Schnittstellenserver Seite 36 von 37
5 Bekannte Probleme und Loumlsungen
51 ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner Bei der Job-Bearbeitung tritt folgender Fehler auf ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner
Behebung
Fuumlhren Sie das beiliegende IP-Patch (UPDATEexe) aus bevor Sie das WAR austauschen
52 Server startet nicht Sie finden folgende Zeilen im Protokoll (catalinaout oder bsslog)
ERROR [localhost-startStop-1] [IdentityServiceImpl] serverID must not be empty
ERROR [localhost-startStop-1] [ContextLoader] Context initialization failed
Behebung
Setzen Sie die Umgebungsvariable ldquoserverIDrdquo in der Datei bdquocontextxmlldquo
53 ORA-00942 table or view does not exist In vielen Faumlllen wird der Fehler ldquoTabelle oder View nicht vorhandenrdquo ausgeworfen (Java-Protokoll im Ordner logs von Apache Tomcat) wenn eine neue Schnittstelle eingerichtet oder ein neues BALVI iP Release bzw Update eingespielt wurde ohne anschlieszligend das aktuelle GRANT-Skript auszufuumlhren
Behebung
Fuumlhren Sie das GRANT-Skript erneut aus
54 ORA-0406x bdquoBestehender Paketstatus wurde aufgehobenldquo
ORA-04061 Bestehender Status von package body ABCXYZ wurde annulliert
ORA-04065 Ausfuumlhrung nicht erfolgreich package body ABCXYZ wurde geaumlndert oder geloumlscht
Release Notes BALVI Schnittstellenserver Seite 37 von 37
Der Fehler tritt haumlufig ein nachdem die UPDATEexe ausgefuumlhrt und in der Ausfuumlhrungsliste ein Package aktualisiert wurde Oracle merkt sich je User-Session bestimmte Werte im Package wenn der Anwender es verwendet hat Durch einen bdquoCREATE OR REPLACE PACKAGEldquo-Befehl kann dieser Status temporaumlr aufgehoben werden Normalerweise tritt dieser Fehler nach dem Update genau einmal in jeder aktiven Session auf wenn der BSS nicht neu gestartet wird
Behebung
Starten Sie nach jedem Update den BSS neu um alle laufenden Sessions zu beenden
55 Jobs sind nicht ausfuumlhrbar
1 Ein Job wird mit dem Status bdquoNicht unterstuumltztldquo angezeigt wenn fuumlr seine Ausfuumlhrung eine houmlhere Version des BSS erforderlich ist
2 Nach dem Klonen der Datenbank von der Produktions- auf die Testumgebung erhalten alle Jobs automatisch den Status bdquoDeaktiviertldquo wenn die bdquoserverIDldquo nicht identisch ist
Beide Statusaumlnderungen sind gewollt Damit soll verhindert werden dass Jobs nach einem Serverneustart oder nach einem Update automatisch starten und dabei Fehler verursachen
Um Jobs mit dem Status bdquoNicht unterstuumltztldquo nutzen und konfigurieren zu koumlnnen ist es erforderlich den BALVI Schnittstellenserver zu aktualisieren
Deaktivierte Jobs koumlnnen Sie aktivieren indem Sie den jeweiligen Job an den aktuellen Server binden und den Haken bei bdquoAktivldquo setzen
Release Notes BALVI Schnittstellenserver Seite 20 von 37
c) numTestsPerEvictionRun - Integer
Wie viele Verbindungen sollen getestet werden waumlhrend der Pruumlflauf ausgefuumlhrt wird Im
Normalfall sollte die Anzahl der zu testenden Verbindungen nicht zu hoch eingestellt werden
Der Default ist 3 Wenn Sie houmlhere Sicherheit haben wollen dass keine bdquototenldquo
Datenbankverbindungen bestehen bleiben erhoumlhen Sie den Wert auf max bdquo(maxActive ndash
maxIdle) 2ldquo Wenn Ihnen 3 ausreichend erscheint muss der Wert nicht gesetzt sein dann
wird der Default verwendet
Beispiel numTestsPerEvictionRun=10
4 Interceptors konfigurieren Neu ergaumlnzt wurde die Moumlglichkeit spezielle bdquoInterceptorsldquo zu konfigurieren die ermoumlglichen das Verhalten des Pools zu steuern Wichtig hierbei ist dass die Angabe von Werten auf real existierende Java-Klassen erfolgt die im Classpath des Tomcat vorhanden sind Groszlig-und-Kleinschreibung ist zu beachten Folgende Default-Einstellung hat BALVI fuumlr den BSS festgelegt jdbcInterceptors=
orgapachetomcatjdbcpoolinterceptorConnectionState
orgapachetomcatjdbcpoolinterceptorStatementFinalizer
orgapachetomcatjdbcpoolinterceptorResetAbandonedTimer
Details zu den verwendeten Interceptor-Einstellungen finden Sie in der Tomcat-Dokumentation3
3 httptomcatapacheorgtomcat-80-docjdbc-poolhtmlJDBC_interceptors
Release Notes BALVI Schnittstellenserver Seite 21 von 37
2512 Datenbank-Zugangsdaten verschluumlsseln
Die Verschluumlsselung fuumlr die Datenbank-Verbindung (bdquoEncrypted Datasourceldquo) ist eine Ableitung der Bibliothek Apache-Common-DBCP-14 und daher nicht mehr mit Java 8 kompatibel Die Einrichtung der Verschluumlsselung wird daher mit der Auslieferung des BSS 30 nicht mehr angeboten
2513 Active-Directory-Authentifizierung
Uumlber die folgenden Parameter wird der Zugriff des Schnittstellen-Servers auf einen Microsoft Active Directory Domain-Controller konfiguriert
ldquoldapServerAddressrdquo
Syntax PROTOKOLLIP-Adresse oder DNS-NamePORT
ltEnvironment
name=ldapServerAddress
value=ldapbl2-dc02balviintern389
type=javalangString
override=true
gt
Als Protokoll besteht auch die Moumlglichkeit ldaps (LDAP+SSL) wenn der Domain-Controller entsprechend konfiguriert wurde Im Java Truststore muss dann das Zertifikat der CA vorhanden sein welche das Zertifikat des Domain-Controllers signiert hat Zudem darf bei ldaps keine IP-Adresse verwendet werden es muss der DNS-Name des Server-Zertifikats eingetragen sein Ansonsten gibt es beim Verbinden eine Sicherheits-Exception
lt-- SSL-Beispiel
ltEnvironment
name=ldapServerAddress
value=ldapsbl2-dc02balviintern636
type=javalangString
override=true
gt
--gt
bdquoldapBaseDnrdquo
LDAP-Suchpfad fuumlr die Domain-Basis Diese muss der LDAP-Syntax fuumlr den Domain-Suffix entsprechen
Syntax DC=SERVERDC=ROOTDN
ltEnvironment
name=ldapBaseDn
value=DC=BALVIDC=INTERN
type=javalangString
override=true
gt
Release Notes BALVI Schnittstellenserver Seite 22 von 37
bdquowebLoginUseActiveDirectoryAuthenticationrdquo
Die Authentifizierung in der Browser-Oberflaumlche kann uumlber die Active-Directory-Authentifizierung erfolgen In der ersten Version ist nur die Protokoll-Auswertung moumlglich wenn der ADMIN sich anmeldet Dieser hat normalerweise niemals AD-Kennungen zugeordnet BALVI empfiehlt diese Einstellung auf bdquofalseldquo zu belassen Webservices welche uumlber SOAPREST zugreifen koumlnnen die Active-Directory-Authentifizierung trotzdem verwenden
ltEnvironment
name=webLoginUseActiveDirectoryAuthentication
value=false
type=javalangBoolean
override=true
gt
ldquoldapDaysBeforeExpirationNotificationrdquo
Die Passwort-Aumlnderung im Active-Directory uumlber die Browser-Oberflaumlche ist in der ersten Version noch nicht implementiert der Parameter wird bislang nicht ausgewertet
ltEnvironment
name=ldapDaysBeforeExpirationNotification
value=14
type=javalangInteger
override=true
gt
2514 Statement-Protokollierung in BALVI iP
Diese Option aktiviert die Lese- und Aumlnderungsprotokollierung fuumlr BALVI iP Standard ist bdquofalseldquo und wird fuumlr alle Kunden empfohlen solange keine speziellen Datenbank-Jobs eingerichtet wurden welche zeitgesteuert die Protokolleintraumlge wieder loumlschen Fuumlr Bayern wurde ein spezielles Konzept zur Leseprotokollierung entworfen Wenn Sie mehr daruumlber erfahren moumlchten kontaktieren Sie bitte die BALVI GmbH
ltEnvironment
name=enableSqlStatementMonitoring
value=true
type=javalangBoolean
override=true
gt
Beachten Sie dass diese Option massive INSERT-Statements in BALVI iP in die Tabelle VIS_D92 ausfuumlhrt Jedes abgesetzte SQL-Statement wird dabei vollstaumlndig protokolliert Dieses erzeugt eine sehr hohe INSERT-Last und in der Folge auch erhoumlhte Redolog-Switches und COMMIT-Transaktionen
Optional Aktivieren der INSERT + APPEND - Logik
Beachten Sie bitte die Hinweise von Oracle zum Hint + APPEND
Release Notes BALVI Schnittstellenserver Seite 23 von 37
Wenn Sie dieses Verhalten aktivieren moumlchten ergaumlnzen Sie bitte den folgenden Environment-Parameter
ltEnvironment
name=statementMonitoringactivateAppendMode
value=true
type=javalangBoolean
override=true
gt
2515 Einstellungen fuumlr BALVI mobil XT (bzw den bdquopartitionedExportldquo)
Diese Logik des FIFO-Buffers wurde so konzipiert dass dem Rechenzentrum diverse Einstellmoumlglichkeiten uumlber die Datei bdquocontextxmlldquo zur Verfuumlgung stehen um die Steuerung des FIFO-Puffers zu beeinflussen
Schematische Darstellung des FIFO-Puffers
Das ermoumlglicht es z B dem BALVI mobil XT Client (14 oder houmlher) den aktiven Block abzuholen und dies beim Fehler bis zu 10-mal zu wiederholen Sobald der Block [001] erfolgreich beim Client angekommen ist und dieser den naumlchsten Block anfragt wird der Block [001] verworfen wird Der Server fuumlllt dann im Hintergrund den frei gewordenen Block wieder waumlhrend der Client den Block [002] abholt
Die Groumlszlige und Anzahl der vorgecachten Bloumlcke kann uumlber die folgenden Einstellungen in der Datei bdquocontextxmlldquo definiert werden
ltEnvironment
name=partitionedExportmaxBufferedPartitions
value=3 type=javalangInteger override=true
gt
ltEnvironment
name=partitionedExportpartitionSize
value=256000 type=javalangInteger override=true
gt
Die Einstellung partitionedExportmaxBufferedPartitions ist dabei die Anzahl der vorgecachten Bloumlcke mindestens muss 2 angegeben werden Der Puffercache wird ausschlieszliglich im RAM der JVM aufgebaut es wird folglich mehr Arbeitsspeicher verwendet Dieser Arbeitsspeicher muss je gleichzeitiger Session auf dem Server bereitgestellt werden die Default-Einstellung mit 3 Partitionen a 256 KB + dem aktiven Puffer erfordern 1 MB RAM je aktiven Anwender
Aktiv
er
Puffe
r
[001] Vorg
ecac
hter
Bl
ock
[002] Vorg
ecac
hter
Bl
ock
[003]
Aktiv
er P
uffe
r
[002] Vorg
ecac
hter
Bl
ock
[003] Vorg
ecac
hter
Bl
ock
[leer]
Release Notes BALVI Schnittstellenserver Seite 24 von 37
Gleichzeitig wurde die Moumlglichkeit geschaffen dass die maximale Anzahl an gleichzeitigen Exporten durch das Rechenzentrum eingeschraumlnkt werden kann um einem OutOfMemory-Fehler vorzubeugen Die Einstellung
ltEnvironment
name=partitionedExportmaxConcurrentExports
value=10 type=javalangInteger override=true
gt
muss entsprechend der zu erwartenden gleichzeitigen Zugriffe konzipiert werden ansonsten wird der Server einen Verbindungsversuch durch die Clients ablehnen
Beachten Sie dass die folgenden Einstellungen partitionedExportmaxBufferedPartitions partitionedExportmaxConcurrentExports und partitionedExportpartitionSize gemeinsam als Rechenbasis fuumlr den RAM-Bedarf des Webservers herangezogen werden muumlssen
Folgende Faustformel sollte fuumlr die Einrichtung verwendet werden
Min 256 MB (Serverbasis) + (11 partitionedExportmaxConcurrentExports partitionedExportmaxBufferedPartitions partitionedExportpartitionSize)
Beispiel 50 gleichzeitige Anwender Blockgroumlszlige 256 KB 4 Partitionen
256 MB + (11 50 256 4) KB = 312 MB fuumlr die JVM
Empf 512 MB (Serverbasis) + (12 partitionedExportmaxConcurrentExports partitionedExportmaxBufferedPartitions partitionedExportpartitionSize)
Beispiel 50 gleichzeitige Anwender Blockgroumlszlige 256 KB 4 Partitionen
512 MB + (12 50 256 4) KB = 572 MB fuumlr die JVM
partitionedExportmaxConcurrentExports
Bestimmt die Anzahl der maximalen Export Tasks (Threads) die fuumlr partitionierte Exporte bereitgestellt werden Wenn die Anzahl uumlberschritten wird wird die entsprechende Exportanfrage abgewiesen und der Client muss zu einem spaumlteren Zeitpunkt erneut anfragen Stellen Sie diesen Wert entsprechend der zu erwartenden Benutzeranzahl ein bei 50 Anwendern also 50
Exporte oumlffnen auf der Datenbank entsprechend zur Ausfuumlhrungszeit min einen Cursor ggf fuumlr rekursive Unterabfragen kurzfristig sogar mehr Die hier eingestellte Anzahl muss mit der Anzahl von maxActive korrelieren
ltEnvironment
name=partitionedExportmaxConcurrentExports
value=10 type=javalangInteger override=true
gt
partitionedExportmaxBufferedPartitions
Bestimmt die Anzahl der Datenbloumlcke (Partitionen) die vom Server bei Abruf eines Exportes gepuffert werden Die seit Version 24 eingefuumlhrte FIFO-Puffer-Logik ermoumlglicht dass der Server schon die Ergebnisse vorpuffert so dass der Client weniger Wartezeiten bei der Anfrage nach Daten hat Diese
Release Notes BALVI Schnittstellenserver Seite 25 von 37
Puffer-Logik unterteilt den Exportdatenstrom (je Export) in mehre Bloumlcke Der Client kann nun den letzten Block neu anfordern oder den naumlchsten Block wenn der letzte Block erfolgreich verarbeitet wurde Wie viele naumlchste Bloumlcke durch den Server bereit gestellt werden entscheidet diese Einstellung Sobald kein naumlchster Block mehr bereit gestellt werden muss wird der Datenbank-Cursor geschlossen eine Erhoumlhung kann also zu einer Entlastung der aktiven DB-Verbindungen fuumlhren erhoumlht jedoch den Bedarf an RAM des Servers
Der von BALVI voreingestellte Wert ist 3
ltEnvironment
name=partitionedExportmaxBufferedPartitions
value=3 type=javalangInteger override=true
gt
partitionedExportpartitionSizeldquo
Die Groumlszlige der Datenbloumlcke (Partitionen) die an den Client uumlbermittelt werden in Bytes Wenn Sie diesen Wert zu niedrig einstellen reduziert sich die Effizienz des Caches da der Client mehr Datenbloumlcke hintereinander abrufen muss Waumlhlen Sie einen zu groszligen Wert wird die neu zu uumlbertragende Datenmenge im Fall eines Fehlers houmlher
Der von BALVI voreingestellte Wert ist 256000 (256 KB)
ltEnvironment
name=partitionedExportpartitionSize
value=256000 type=javalangInteger override=true
gt
exportTokensmaxTokenCount
Maximale Anzahl der gleichzeitig vergebenen Token die vom Server gecached werden Jede Sitzung welche einen Export durchfuumlhrt erhaumllt einen Session-Token
Wenn eine Sitzung laumlngere Zeit nicht verwendet wurde wird dieser Session-Token wieder entfernt Wenn Sie den Wert zu niedrig einstellen fuumlhrt das zu einer generellen Session-Begrenzung auch fuumlr den nicht partitionierten Export-Modus welcher ab Version 21 verfuumlgbar ist
Ist die Anzahl der Tokens houmlher als die Datenbankeinstellung maxActive kann es vorkommen dass zwar eine Session gestartet werden kann jedoch kein Datenexport zustande kommt
Der von BALVI voreingestellte Wert ist 2000
ltEnvironment
name=exportTokensmaxTokenCount
value=20 type=javalangInteger override=true
gt
exportTokenstokenExpirationInSeconds
Zeit in Sekunden die verstreichen muss bis ein Token unguumlltig wird falls darauf kein Zugriff mehr erfolgt Nach einem erfolgreichen Export wird der Token automatisch geschlossen diese Option ist fuumlr den Abbruchfall vorgesehen Der von BALVI voreingestellte Wert ist 180 (180 s = 3 min)
Release Notes BALVI Schnittstellenserver Seite 26 von 37
ltEnvironment
name=exportTokenstokenExpirationInSeconds
value=180 type=javalangInteger override=true
gt
exportTokenstokenDisposalInSeconds
Zeit in Sekunden die verstreichen muss bis ein Token das erfolgreich abgearbeitet wurde aus dem Cache geloumlscht wird Um sicher zu stellen dass der letzte Exportblock noch erfolgreich abgerufen werden kann bleibt der Token auch nach Fertigmeldung des Clients noch N Sek guumlltig
Der von BALVI voreingestellte Wert ist 60 (60 s = 1 min)
ltEnvironment
name=exportTokenstokenDisposalInSeconds
value=60 type=javalangInteger override=true
gt
2516 Job-Verwaltung fuumlr den BSS konfigurieren Aktivierung der Jobverwaltung
Bis zur Version 28 des BSS gab es den Parameter bdquoavailableServicesldquo Dieser konnte bei Bedarf aktiviert werden wenn die Jobs benoumltigt wurden
Mit Version 30 ist die Einstellung bdquoavailableServicesldquo zu entfernen und kann durch den neuen optionalen Parameter bdquoisJobServiceEnabledldquo in der Datei bdquocontextxmlldquo ersetzt werden
lt-- Neue Parameter zur Aktivierung des Job Service Ersatz fuumlr availableServices --gt
ltEnvironment
name=isJobServiceEnabled
value=true
type=javalangBoolean
override=true
gt
Ab BSS 30 wird die Jobs-Engine standardmaumlszligig aktiviert Sollte die Jobs-Engine nicht benoumltigt werden muss bdquovalueldquo der Wert bdquofalseldquo zugewiesen werden Wird bdquoisJobServiceEnabledldquo nicht eingefuumlgt sind die Jobs trotzdem standardmaumlszligig aktiv
Nach dem Neustart des Servers und erneutem Einloggen erscheint nun zusaumltzlich der Menuumlpunkt bdquoJobsldquo
bdquopasswordKeyldquo fuumlr Jobs
In der Job-Logik wird ein von BALVI definierter Standard-Schluumlssel fuumlr die Ablagen von schuumltzenswerten Daten z B Passwoumlrtern verwendet Diese Einstellung ermoumlglicht den BALVI-Standard zu uumlberschreiben Wenn Sie diese Einstellung aumlndern muumlssen jedoch alle bislang verschluumlsselten Job-Parameter neu verschluumlsselt werden
ltEnvironment
name=javacompenvjobspasswordKey
value=MeinHochsicheresNeuesPasswort
type=javalangString
Release Notes BALVI Schnittstellenserver Seite 27 von 37
override=true
gt
bdquoJob ID enableddisabledldquo (Deprecated ersetzt ab 28 durch das bdquoBindenldquo von Jobs)
Sondereinstellungen fuumlr die Job-Verwaltung Da alle Jobs in einer Datenbank administriert werden jedoch ggf verteilt auf mehreren Tomcat-Servern ausgefuumlhrt werden sollen besteht hier die Option Jobs fuumlr die aktuelle Tomcat-Instanz separat zu deaktivieren
Die Einstellung ID koumlnnte z B folgendermaszligen aussehen javacompenvjobsC0DB58D8D52C4BBC966D1DC788A4EF8Benabled
Fuumlr weitere Fragen zu dieser Einstellung kontaktieren Sie bitte die BALVI GmbH
ltEnvironment
name=javacompenvjobsIDenabled
value=false
type=javalangBoolean
override=true
gt
2517 Weitere optionale Parameter
Es ist fuumlr diverse einzelne Schnittstellen ggf erforderlich Einstellungen in der Datei bdquocontextxmlldquo zu ergaumlnzen Hinweise zu diesen Parametern sind dann in dem der Schnittstelle beiliegenden Dokument enthalten Das gilt z B fuumlr die Schnittstelle bdquoXGewerbeanzeigenldquo
26 Logging mit logback Das Logging wurde komplett uumlberarbeitet Statt bdquoLog4Jldquo wird jetzt bdquologbackldquo4 benutzt Ab BSS 30 ist es zwingend notwendig die Einstellung vorzunehmen um das Logging der Anwendung zu steuern
Migration Ergaumlnzen Sie die neue Einstellung bdquologgingconfigldquo
lt-- Neue Paramter zur Angabe der Logback Config Ersatz fuumlr log4jConfigLocation --gt
ltEnvironment
name=loggingconfig
value=$catalinabaseconflogback-bssxml
type=javalangString
override=true
gt
Nach wie vor steht es Ihnen frei die Logging-Konfiguration eigenstaumlndig anzupassen
Wenn Sie jedoch dieselbe WAR in einer Tomcat-Instanz unter mehreren Context-Namen betreiben wuumlrden beide dieselbe Logging-Konfiguration verwenden so dass alle Protokolleintraumlge in einer Log-Datei aus
4 httplogbackqoschmanualappendershtml
Release Notes BALVI Schnittstellenserver Seite 28 von 37
mehreren Webanwendungen generiert werden Aumlndern Sie den Namen der Logging-Konfiguration entsprechend ab um fuumlr jede Anwendung eine spezifische Logging-Einstellung vornehmen zu koumlnnen
27 Tocmat Optional Suche im bdquoKlassenpfadldquo um den
Ordner bdquoconfldquo erweitern Die Suche nach Dateien uumlber bdquoclasspathldquo setzt voraus dass die Ordner- und Dateinamen im Apache Tomcat bekannt gegeben werden Der Klassenpfad kann in der Datei bdquocatalinapropertiesldquo angepasst werden Wenn Sie dort unter commonloader die folgenden Werte ergaumlnzen kann eine Datei auch im Ordner conf abgelegt werden damit Apache Tomcat diese findet Ansonsten muss die Datei im Ordner lib abgelegt werden
commonloader=$catalinabaseconf$catalinahomeconf
3 Die neue Browser-Oberflaumlche Der BALVI Schnittstellenserver hat seit Version 25 neben der Protokollierung auch die Moumlglichkeit Job-Konfigurationen zu pflegen Der Login ist nur fuumlr einen in BALVI iP eingetragenen ADMIN (z B Benutzer bdquoSYSTEMADMINldquo) mit dem in BALVI iP hinterlegten Passwort moumlglich Zur Anmeldung muss immer [SYSTEMBenutzername] im Feld Benutzer angegeben werden ansonsten schlaumlgt die Anmeldung fehl Bitte achten Sie darauf dass der bdquoldquo (Slash) und nicht der bdquoldquo (Backslash) verwendet werden muss
31 Server-Protokoll Um das Server-Protokoll anzuzeigen waumlhlen Sie den entsprechenden Menuumlpunkt Dort haben Sie seit BSS 26 die Moumlglichkeit uumlber alle Spalten der Protokolle nach Informationen zu suchen
Seit BSS 31 gibt es die Moumlglichkeit Verfahren in bdquoKopfsaumltzeldquo und bdquoDetailsaumltzeldquo zu unterteilen Wurde das Verfahren entsprechend konfiguriert (wie z B bei der Schnittstelle bdquoXGewerbeanzeigenldquo) dann wird im Protokoll-Kopfsatz nur der Start und das Ende der Ausfuumlhrung in der Liste angezeigt Erst bei einem Klick auf bdquoInformationenldquo wird die Liste aller Detailsaumltze angezeigt die im Durchlauf erzeugt wurden
Release Notes BALVI Schnittstellenserver Seite 29 von 37
Verfahren
Die Liste der verfuumlgbaren Verfahren die bei Ihnen im System installiert sind ZB
BEFUNDEhellip Schnittstelle Befunde LM FM oder TS
PROBEhellip Schnittstelle zum Export von Proben an Labore ebenfalls Spezifisch fuumlr einzelne Fachbereiche
MOBILXT Protokolle der BALVI Mobil XT Synchronisation
WEB Allgemeine nicht spezifizierte Protokolle hierunter ist bislang auch die eFi-Protokollierung zu finden
WEB_I0802 Protokolle zur Schnittstelle BALVI iP LIMS (Lebensmittelproben)
XGEWERBE Schnittstelle XGewerbeanzeigen
Klicken Sie auf die Schaltflaumlche so besteht bei den neuen Protokolldatensaumltzen die Moumlglichkeit Detail-Informationen zum Protokollsatz zu erhalten
Release Notes BALVI Schnittstellenserver Seite 30 von 37
Seit BSS 30x ist die Anzeige der Protokolle ebenfalls farblich abgesetzt so dass Protokolleintraumlge mit Fehlern hellrot und Warnungen hellgelb hinterlegt werden
32 Jobs Mit einem Klick auf den Menuumlpunkt Jobs rufen Sie die Oberflaumlche fuumlr die Job-Konfiguration auf Daraufhin werden alle Jobs aufgelistet die fuumlr den BSS freigegeben sind Hier koumlnnen Sie Einstellungen an den Jobs vornehmen und die Jobs aktivieren bzw deaktivieren Die Beschreibungen bzw Einstellungsmoumlglichkeiten fuumlr den jeweiligen SST-Job sind nicht Bestandteil dieser Dokumentation
33 Log-Ausgaben Uumlber den Menuumlpunkt Log-Ausgaben koumlnnen Sie die Ausgabe der Protokolleintraumlge in Echtzeit beobachten
Release Notes BALVI Schnittstellenserver Seite 31 von 37
Starten Sie die Echtzeit-Protokollierung indem Sie auf die Schaltflaumlche mit dem Symbol bdquoPlayldquo (Dreieck) klicken unterbrechen Sie die Ausgabe indem Sie die auf Schaltflaumlche mit dem Symbol bdquoPauseldquo (zwei Balken) klicken
Klicken Sie auf die Schaltflaumlche bdquoAktualisierenldquo (zwei Pfeile) um die neuesten Protokolleintraumlge angezeigt zu bekommen
Klicken Sie auf das Symbol mit dem Papierkorb um die letzten Protokollmeldungen in der Anzeige zu loumlschen
Die Daten in den Protokolldateien auf der Festplatte des Servers sind davon nicht betroffen
Uumlber das Symbol bdquoLogging anpassenldquo (Schraubenschluumlssel) koumlnnen Sie die Ausgabe der Daten im Echtzeitfenster und in den Protokolldateien aumlndern jedoch ist diese Einstellung nur temporaumlr Die Standardeinstellungen koumlnnen ausschlieszliglich uumlber die Anpassung der Datei bdquologback-bssxmlldquo im Konfigurationsverzeichnis des Servers selbst geaumlndert werden
Release Notes BALVI Schnittstellenserver Seite 32 von 37
In der Logging-Parameter Konfiguration koumlnnen Sie verschiedene Parameter einstellen und uumlber die Schaltflaumlche bdquoAnwendenldquo dann sofort im Echtzeitprotokoll sehen Welche Einstellungen moumlglich sind erfahren Sie wenn es eine akute Fehlersituation gibt die detailliertere Ausgaben im Protokoll erfordert
Warnung Wenn Sie den Log-Level fuumlr ROOT oder eine andere Klasse auf TRACE einstellen werden sehr viele Protokollausgaben generiert die auch dazu fuumlhren koumlnnen dass der Server sehr langsam wird oder die Festplatte des Servers zulaumluft wenn fuumlr das Logging kein Dateilimit konfiguriert wurde
34 LogoutAbmeldung vom System Zum Abmelden waumlhlen Sie oben rechts das Kontextmenuuml
35 Cache loumlschen Der Cache wird in der Regel automatisch geloumlscht Wenn Sie jedoch gerade in BALVI iP eine Aumlnderung an den Schnittstellen eingespielt haben und moumlchten dass diese sofort wirksam wird kann die Funktion bdquoCache loumlschenldquo dazu verwendet werden dass der BALVI Schnittstellenserver die Einstellungen bei der naumlchsten Anfrage neu einliest
Release Notes BALVI Schnittstellenserver Seite 33 von 37
Release Notes BALVI Schnittstellenserver Seite 34 von 37
4 Einrichtung in BALVI iP Um die Verfahren fuumlr den BALVI Schnittstellenserver fuumlr Anwender freizuschalten wird das Objekt bdquoSystemeinstellungenldquo oder bdquoMandanten- und Benutzereinstellungenldquo verwendet Die Anpassung ist je Verfahren moumlglich so kann in BALVI iP fuumlr den Zugriff durch den BALVI Schnittstellenserver ein Benutzer bdquoAldquo am Verfahren bdquoMobilldquo berechtigt werden ein Benutzer bdquoBldquo nur am Verfahren bdquoSLA_FLESHldquo usw Die Logik ist jedoch einheitlich Je Verfahren wird durch BALVI eine Verfahrensgruppe mit dem Verfahrensnamen angelegt und mit den entsprechenden Einstellungen vorkonfiguriert welche durch das Verfahren erforderlich sind Dabei kann die Komplexitaumlt der Einstellungen variieren wie z B an den zu Version 23 verfuumlgbaren Verfahren bdquoMobilldquo und bdquoSLA_Fleshldquo ersichtlich wird
Im Verfahren BALVI Mobil sind diverse Anpassungen moumlglich welche je Bundesland oder eingesetzter Import- und Export-Variante durch den BALVI Schnittstellenserver bei der Bearbeitung von Anfragen gepruumlft werden siehe Punkt 3 Abb Mobil-Einstellung in BALVI iP
Abb Mobil-Einstellung in BALVI iP
Alle Verfahren verwenden jedoch die regulaumlre Benutzerverwaltung von BALVI iP Ein Benutzer ohne Passwort gilt fuumlr BALVI iP als gesperrt was fuumlr das Login bedeutet dass der Anwender sich nur uumlber die Active-Directory-Authentifizierung anmelden kann Ist das nicht moumlglich (bzw nicht konfiguriert) kann der Anwender sich weder in BALVI iP noch uumlber die Webservice-Schnittstelle authentifizieren
Fuumlr Dienste-Schnittstellen welche keine persoumlnliche Authentifizierung durch einen Anwender erfordern wird empfohlen einen separaten Benutzer in der Benutzerverwaltung anzulegen und ein sicheres Kennwort zu vergeben Das Anlegen von zusaumltzlichen Benutzern gilt nicht fuumlr BALVI mobil XT da beim Holen und Uumlbermitteln von Daten jeder Benutzer auch ein fachlich konfigurierter Anwender innerhalb von BALVI iP ist und die Anwendungsoberflaumlche ebenfalls zur Erfassung von Daten verwendet
Unter Punkt 2 der Abb Mobil-Einstellung in BALVI iP wird ein modales Fenster geoumlffnet (Abb BALVI mobil Benutzerverwaltung) Innerhalb dieses modalen Fensters werden mandantenweise die Benutzer fuumlr BALVI
Release Notes BALVI Schnittstellenserver Seite 35 von 37
mobil und den jeweiligen Fachbereich festgelegt Dabei ist es wichtig dass man die Haken bdquoAktiv fuumlr hellipldquo bei bdquohellip mobilldquo und bei einem Fachbereich (bdquohellip LMldquo bdquohellip FMldquo usw) setzt weil sonst uumlber den BALVI Schnittstellenserver keine Kommunikation mit BALVI iP moumlglich ist
Abb BALVI mobil Benutzerverwaltung
Alternativ zur Passwort-Authentifizierung wird wie beschrieben auch die Active-Directory-Authentifizierung angeboten Dazu muss der BALVI iP-Anwender uumlber die Schaltflaumlche bdquoDomaumlnen-Benutzer zuordnenldquo mit dem Active Directory verknuumlpft werden
Nur wenn die Active-Directory-Konfigurationen in BALVI iP und im BALVI Schnittstellenserver auf dieselbe Domaumlne verweisen sind die Domaumlnen-Zuordnung und die Active-Directory-Authentifizierung (z B uumlber BALVI mobil XT) moumlglich
Release Notes BALVI Schnittstellenserver Seite 36 von 37
5 Bekannte Probleme und Loumlsungen
51 ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner Bei der Job-Bearbeitung tritt folgender Fehler auf ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner
Behebung
Fuumlhren Sie das beiliegende IP-Patch (UPDATEexe) aus bevor Sie das WAR austauschen
52 Server startet nicht Sie finden folgende Zeilen im Protokoll (catalinaout oder bsslog)
ERROR [localhost-startStop-1] [IdentityServiceImpl] serverID must not be empty
ERROR [localhost-startStop-1] [ContextLoader] Context initialization failed
Behebung
Setzen Sie die Umgebungsvariable ldquoserverIDrdquo in der Datei bdquocontextxmlldquo
53 ORA-00942 table or view does not exist In vielen Faumlllen wird der Fehler ldquoTabelle oder View nicht vorhandenrdquo ausgeworfen (Java-Protokoll im Ordner logs von Apache Tomcat) wenn eine neue Schnittstelle eingerichtet oder ein neues BALVI iP Release bzw Update eingespielt wurde ohne anschlieszligend das aktuelle GRANT-Skript auszufuumlhren
Behebung
Fuumlhren Sie das GRANT-Skript erneut aus
54 ORA-0406x bdquoBestehender Paketstatus wurde aufgehobenldquo
ORA-04061 Bestehender Status von package body ABCXYZ wurde annulliert
ORA-04065 Ausfuumlhrung nicht erfolgreich package body ABCXYZ wurde geaumlndert oder geloumlscht
Release Notes BALVI Schnittstellenserver Seite 37 von 37
Der Fehler tritt haumlufig ein nachdem die UPDATEexe ausgefuumlhrt und in der Ausfuumlhrungsliste ein Package aktualisiert wurde Oracle merkt sich je User-Session bestimmte Werte im Package wenn der Anwender es verwendet hat Durch einen bdquoCREATE OR REPLACE PACKAGEldquo-Befehl kann dieser Status temporaumlr aufgehoben werden Normalerweise tritt dieser Fehler nach dem Update genau einmal in jeder aktiven Session auf wenn der BSS nicht neu gestartet wird
Behebung
Starten Sie nach jedem Update den BSS neu um alle laufenden Sessions zu beenden
55 Jobs sind nicht ausfuumlhrbar
1 Ein Job wird mit dem Status bdquoNicht unterstuumltztldquo angezeigt wenn fuumlr seine Ausfuumlhrung eine houmlhere Version des BSS erforderlich ist
2 Nach dem Klonen der Datenbank von der Produktions- auf die Testumgebung erhalten alle Jobs automatisch den Status bdquoDeaktiviertldquo wenn die bdquoserverIDldquo nicht identisch ist
Beide Statusaumlnderungen sind gewollt Damit soll verhindert werden dass Jobs nach einem Serverneustart oder nach einem Update automatisch starten und dabei Fehler verursachen
Um Jobs mit dem Status bdquoNicht unterstuumltztldquo nutzen und konfigurieren zu koumlnnen ist es erforderlich den BALVI Schnittstellenserver zu aktualisieren
Deaktivierte Jobs koumlnnen Sie aktivieren indem Sie den jeweiligen Job an den aktuellen Server binden und den Haken bei bdquoAktivldquo setzen
Release Notes BALVI Schnittstellenserver Seite 21 von 37
2512 Datenbank-Zugangsdaten verschluumlsseln
Die Verschluumlsselung fuumlr die Datenbank-Verbindung (bdquoEncrypted Datasourceldquo) ist eine Ableitung der Bibliothek Apache-Common-DBCP-14 und daher nicht mehr mit Java 8 kompatibel Die Einrichtung der Verschluumlsselung wird daher mit der Auslieferung des BSS 30 nicht mehr angeboten
2513 Active-Directory-Authentifizierung
Uumlber die folgenden Parameter wird der Zugriff des Schnittstellen-Servers auf einen Microsoft Active Directory Domain-Controller konfiguriert
ldquoldapServerAddressrdquo
Syntax PROTOKOLLIP-Adresse oder DNS-NamePORT
ltEnvironment
name=ldapServerAddress
value=ldapbl2-dc02balviintern389
type=javalangString
override=true
gt
Als Protokoll besteht auch die Moumlglichkeit ldaps (LDAP+SSL) wenn der Domain-Controller entsprechend konfiguriert wurde Im Java Truststore muss dann das Zertifikat der CA vorhanden sein welche das Zertifikat des Domain-Controllers signiert hat Zudem darf bei ldaps keine IP-Adresse verwendet werden es muss der DNS-Name des Server-Zertifikats eingetragen sein Ansonsten gibt es beim Verbinden eine Sicherheits-Exception
lt-- SSL-Beispiel
ltEnvironment
name=ldapServerAddress
value=ldapsbl2-dc02balviintern636
type=javalangString
override=true
gt
--gt
bdquoldapBaseDnrdquo
LDAP-Suchpfad fuumlr die Domain-Basis Diese muss der LDAP-Syntax fuumlr den Domain-Suffix entsprechen
Syntax DC=SERVERDC=ROOTDN
ltEnvironment
name=ldapBaseDn
value=DC=BALVIDC=INTERN
type=javalangString
override=true
gt
Release Notes BALVI Schnittstellenserver Seite 22 von 37
bdquowebLoginUseActiveDirectoryAuthenticationrdquo
Die Authentifizierung in der Browser-Oberflaumlche kann uumlber die Active-Directory-Authentifizierung erfolgen In der ersten Version ist nur die Protokoll-Auswertung moumlglich wenn der ADMIN sich anmeldet Dieser hat normalerweise niemals AD-Kennungen zugeordnet BALVI empfiehlt diese Einstellung auf bdquofalseldquo zu belassen Webservices welche uumlber SOAPREST zugreifen koumlnnen die Active-Directory-Authentifizierung trotzdem verwenden
ltEnvironment
name=webLoginUseActiveDirectoryAuthentication
value=false
type=javalangBoolean
override=true
gt
ldquoldapDaysBeforeExpirationNotificationrdquo
Die Passwort-Aumlnderung im Active-Directory uumlber die Browser-Oberflaumlche ist in der ersten Version noch nicht implementiert der Parameter wird bislang nicht ausgewertet
ltEnvironment
name=ldapDaysBeforeExpirationNotification
value=14
type=javalangInteger
override=true
gt
2514 Statement-Protokollierung in BALVI iP
Diese Option aktiviert die Lese- und Aumlnderungsprotokollierung fuumlr BALVI iP Standard ist bdquofalseldquo und wird fuumlr alle Kunden empfohlen solange keine speziellen Datenbank-Jobs eingerichtet wurden welche zeitgesteuert die Protokolleintraumlge wieder loumlschen Fuumlr Bayern wurde ein spezielles Konzept zur Leseprotokollierung entworfen Wenn Sie mehr daruumlber erfahren moumlchten kontaktieren Sie bitte die BALVI GmbH
ltEnvironment
name=enableSqlStatementMonitoring
value=true
type=javalangBoolean
override=true
gt
Beachten Sie dass diese Option massive INSERT-Statements in BALVI iP in die Tabelle VIS_D92 ausfuumlhrt Jedes abgesetzte SQL-Statement wird dabei vollstaumlndig protokolliert Dieses erzeugt eine sehr hohe INSERT-Last und in der Folge auch erhoumlhte Redolog-Switches und COMMIT-Transaktionen
Optional Aktivieren der INSERT + APPEND - Logik
Beachten Sie bitte die Hinweise von Oracle zum Hint + APPEND
Release Notes BALVI Schnittstellenserver Seite 23 von 37
Wenn Sie dieses Verhalten aktivieren moumlchten ergaumlnzen Sie bitte den folgenden Environment-Parameter
ltEnvironment
name=statementMonitoringactivateAppendMode
value=true
type=javalangBoolean
override=true
gt
2515 Einstellungen fuumlr BALVI mobil XT (bzw den bdquopartitionedExportldquo)
Diese Logik des FIFO-Buffers wurde so konzipiert dass dem Rechenzentrum diverse Einstellmoumlglichkeiten uumlber die Datei bdquocontextxmlldquo zur Verfuumlgung stehen um die Steuerung des FIFO-Puffers zu beeinflussen
Schematische Darstellung des FIFO-Puffers
Das ermoumlglicht es z B dem BALVI mobil XT Client (14 oder houmlher) den aktiven Block abzuholen und dies beim Fehler bis zu 10-mal zu wiederholen Sobald der Block [001] erfolgreich beim Client angekommen ist und dieser den naumlchsten Block anfragt wird der Block [001] verworfen wird Der Server fuumlllt dann im Hintergrund den frei gewordenen Block wieder waumlhrend der Client den Block [002] abholt
Die Groumlszlige und Anzahl der vorgecachten Bloumlcke kann uumlber die folgenden Einstellungen in der Datei bdquocontextxmlldquo definiert werden
ltEnvironment
name=partitionedExportmaxBufferedPartitions
value=3 type=javalangInteger override=true
gt
ltEnvironment
name=partitionedExportpartitionSize
value=256000 type=javalangInteger override=true
gt
Die Einstellung partitionedExportmaxBufferedPartitions ist dabei die Anzahl der vorgecachten Bloumlcke mindestens muss 2 angegeben werden Der Puffercache wird ausschlieszliglich im RAM der JVM aufgebaut es wird folglich mehr Arbeitsspeicher verwendet Dieser Arbeitsspeicher muss je gleichzeitiger Session auf dem Server bereitgestellt werden die Default-Einstellung mit 3 Partitionen a 256 KB + dem aktiven Puffer erfordern 1 MB RAM je aktiven Anwender
Aktiv
er
Puffe
r
[001] Vorg
ecac
hter
Bl
ock
[002] Vorg
ecac
hter
Bl
ock
[003]
Aktiv
er P
uffe
r
[002] Vorg
ecac
hter
Bl
ock
[003] Vorg
ecac
hter
Bl
ock
[leer]
Release Notes BALVI Schnittstellenserver Seite 24 von 37
Gleichzeitig wurde die Moumlglichkeit geschaffen dass die maximale Anzahl an gleichzeitigen Exporten durch das Rechenzentrum eingeschraumlnkt werden kann um einem OutOfMemory-Fehler vorzubeugen Die Einstellung
ltEnvironment
name=partitionedExportmaxConcurrentExports
value=10 type=javalangInteger override=true
gt
muss entsprechend der zu erwartenden gleichzeitigen Zugriffe konzipiert werden ansonsten wird der Server einen Verbindungsversuch durch die Clients ablehnen
Beachten Sie dass die folgenden Einstellungen partitionedExportmaxBufferedPartitions partitionedExportmaxConcurrentExports und partitionedExportpartitionSize gemeinsam als Rechenbasis fuumlr den RAM-Bedarf des Webservers herangezogen werden muumlssen
Folgende Faustformel sollte fuumlr die Einrichtung verwendet werden
Min 256 MB (Serverbasis) + (11 partitionedExportmaxConcurrentExports partitionedExportmaxBufferedPartitions partitionedExportpartitionSize)
Beispiel 50 gleichzeitige Anwender Blockgroumlszlige 256 KB 4 Partitionen
256 MB + (11 50 256 4) KB = 312 MB fuumlr die JVM
Empf 512 MB (Serverbasis) + (12 partitionedExportmaxConcurrentExports partitionedExportmaxBufferedPartitions partitionedExportpartitionSize)
Beispiel 50 gleichzeitige Anwender Blockgroumlszlige 256 KB 4 Partitionen
512 MB + (12 50 256 4) KB = 572 MB fuumlr die JVM
partitionedExportmaxConcurrentExports
Bestimmt die Anzahl der maximalen Export Tasks (Threads) die fuumlr partitionierte Exporte bereitgestellt werden Wenn die Anzahl uumlberschritten wird wird die entsprechende Exportanfrage abgewiesen und der Client muss zu einem spaumlteren Zeitpunkt erneut anfragen Stellen Sie diesen Wert entsprechend der zu erwartenden Benutzeranzahl ein bei 50 Anwendern also 50
Exporte oumlffnen auf der Datenbank entsprechend zur Ausfuumlhrungszeit min einen Cursor ggf fuumlr rekursive Unterabfragen kurzfristig sogar mehr Die hier eingestellte Anzahl muss mit der Anzahl von maxActive korrelieren
ltEnvironment
name=partitionedExportmaxConcurrentExports
value=10 type=javalangInteger override=true
gt
partitionedExportmaxBufferedPartitions
Bestimmt die Anzahl der Datenbloumlcke (Partitionen) die vom Server bei Abruf eines Exportes gepuffert werden Die seit Version 24 eingefuumlhrte FIFO-Puffer-Logik ermoumlglicht dass der Server schon die Ergebnisse vorpuffert so dass der Client weniger Wartezeiten bei der Anfrage nach Daten hat Diese
Release Notes BALVI Schnittstellenserver Seite 25 von 37
Puffer-Logik unterteilt den Exportdatenstrom (je Export) in mehre Bloumlcke Der Client kann nun den letzten Block neu anfordern oder den naumlchsten Block wenn der letzte Block erfolgreich verarbeitet wurde Wie viele naumlchste Bloumlcke durch den Server bereit gestellt werden entscheidet diese Einstellung Sobald kein naumlchster Block mehr bereit gestellt werden muss wird der Datenbank-Cursor geschlossen eine Erhoumlhung kann also zu einer Entlastung der aktiven DB-Verbindungen fuumlhren erhoumlht jedoch den Bedarf an RAM des Servers
Der von BALVI voreingestellte Wert ist 3
ltEnvironment
name=partitionedExportmaxBufferedPartitions
value=3 type=javalangInteger override=true
gt
partitionedExportpartitionSizeldquo
Die Groumlszlige der Datenbloumlcke (Partitionen) die an den Client uumlbermittelt werden in Bytes Wenn Sie diesen Wert zu niedrig einstellen reduziert sich die Effizienz des Caches da der Client mehr Datenbloumlcke hintereinander abrufen muss Waumlhlen Sie einen zu groszligen Wert wird die neu zu uumlbertragende Datenmenge im Fall eines Fehlers houmlher
Der von BALVI voreingestellte Wert ist 256000 (256 KB)
ltEnvironment
name=partitionedExportpartitionSize
value=256000 type=javalangInteger override=true
gt
exportTokensmaxTokenCount
Maximale Anzahl der gleichzeitig vergebenen Token die vom Server gecached werden Jede Sitzung welche einen Export durchfuumlhrt erhaumllt einen Session-Token
Wenn eine Sitzung laumlngere Zeit nicht verwendet wurde wird dieser Session-Token wieder entfernt Wenn Sie den Wert zu niedrig einstellen fuumlhrt das zu einer generellen Session-Begrenzung auch fuumlr den nicht partitionierten Export-Modus welcher ab Version 21 verfuumlgbar ist
Ist die Anzahl der Tokens houmlher als die Datenbankeinstellung maxActive kann es vorkommen dass zwar eine Session gestartet werden kann jedoch kein Datenexport zustande kommt
Der von BALVI voreingestellte Wert ist 2000
ltEnvironment
name=exportTokensmaxTokenCount
value=20 type=javalangInteger override=true
gt
exportTokenstokenExpirationInSeconds
Zeit in Sekunden die verstreichen muss bis ein Token unguumlltig wird falls darauf kein Zugriff mehr erfolgt Nach einem erfolgreichen Export wird der Token automatisch geschlossen diese Option ist fuumlr den Abbruchfall vorgesehen Der von BALVI voreingestellte Wert ist 180 (180 s = 3 min)
Release Notes BALVI Schnittstellenserver Seite 26 von 37
ltEnvironment
name=exportTokenstokenExpirationInSeconds
value=180 type=javalangInteger override=true
gt
exportTokenstokenDisposalInSeconds
Zeit in Sekunden die verstreichen muss bis ein Token das erfolgreich abgearbeitet wurde aus dem Cache geloumlscht wird Um sicher zu stellen dass der letzte Exportblock noch erfolgreich abgerufen werden kann bleibt der Token auch nach Fertigmeldung des Clients noch N Sek guumlltig
Der von BALVI voreingestellte Wert ist 60 (60 s = 1 min)
ltEnvironment
name=exportTokenstokenDisposalInSeconds
value=60 type=javalangInteger override=true
gt
2516 Job-Verwaltung fuumlr den BSS konfigurieren Aktivierung der Jobverwaltung
Bis zur Version 28 des BSS gab es den Parameter bdquoavailableServicesldquo Dieser konnte bei Bedarf aktiviert werden wenn die Jobs benoumltigt wurden
Mit Version 30 ist die Einstellung bdquoavailableServicesldquo zu entfernen und kann durch den neuen optionalen Parameter bdquoisJobServiceEnabledldquo in der Datei bdquocontextxmlldquo ersetzt werden
lt-- Neue Parameter zur Aktivierung des Job Service Ersatz fuumlr availableServices --gt
ltEnvironment
name=isJobServiceEnabled
value=true
type=javalangBoolean
override=true
gt
Ab BSS 30 wird die Jobs-Engine standardmaumlszligig aktiviert Sollte die Jobs-Engine nicht benoumltigt werden muss bdquovalueldquo der Wert bdquofalseldquo zugewiesen werden Wird bdquoisJobServiceEnabledldquo nicht eingefuumlgt sind die Jobs trotzdem standardmaumlszligig aktiv
Nach dem Neustart des Servers und erneutem Einloggen erscheint nun zusaumltzlich der Menuumlpunkt bdquoJobsldquo
bdquopasswordKeyldquo fuumlr Jobs
In der Job-Logik wird ein von BALVI definierter Standard-Schluumlssel fuumlr die Ablagen von schuumltzenswerten Daten z B Passwoumlrtern verwendet Diese Einstellung ermoumlglicht den BALVI-Standard zu uumlberschreiben Wenn Sie diese Einstellung aumlndern muumlssen jedoch alle bislang verschluumlsselten Job-Parameter neu verschluumlsselt werden
ltEnvironment
name=javacompenvjobspasswordKey
value=MeinHochsicheresNeuesPasswort
type=javalangString
Release Notes BALVI Schnittstellenserver Seite 27 von 37
override=true
gt
bdquoJob ID enableddisabledldquo (Deprecated ersetzt ab 28 durch das bdquoBindenldquo von Jobs)
Sondereinstellungen fuumlr die Job-Verwaltung Da alle Jobs in einer Datenbank administriert werden jedoch ggf verteilt auf mehreren Tomcat-Servern ausgefuumlhrt werden sollen besteht hier die Option Jobs fuumlr die aktuelle Tomcat-Instanz separat zu deaktivieren
Die Einstellung ID koumlnnte z B folgendermaszligen aussehen javacompenvjobsC0DB58D8D52C4BBC966D1DC788A4EF8Benabled
Fuumlr weitere Fragen zu dieser Einstellung kontaktieren Sie bitte die BALVI GmbH
ltEnvironment
name=javacompenvjobsIDenabled
value=false
type=javalangBoolean
override=true
gt
2517 Weitere optionale Parameter
Es ist fuumlr diverse einzelne Schnittstellen ggf erforderlich Einstellungen in der Datei bdquocontextxmlldquo zu ergaumlnzen Hinweise zu diesen Parametern sind dann in dem der Schnittstelle beiliegenden Dokument enthalten Das gilt z B fuumlr die Schnittstelle bdquoXGewerbeanzeigenldquo
26 Logging mit logback Das Logging wurde komplett uumlberarbeitet Statt bdquoLog4Jldquo wird jetzt bdquologbackldquo4 benutzt Ab BSS 30 ist es zwingend notwendig die Einstellung vorzunehmen um das Logging der Anwendung zu steuern
Migration Ergaumlnzen Sie die neue Einstellung bdquologgingconfigldquo
lt-- Neue Paramter zur Angabe der Logback Config Ersatz fuumlr log4jConfigLocation --gt
ltEnvironment
name=loggingconfig
value=$catalinabaseconflogback-bssxml
type=javalangString
override=true
gt
Nach wie vor steht es Ihnen frei die Logging-Konfiguration eigenstaumlndig anzupassen
Wenn Sie jedoch dieselbe WAR in einer Tomcat-Instanz unter mehreren Context-Namen betreiben wuumlrden beide dieselbe Logging-Konfiguration verwenden so dass alle Protokolleintraumlge in einer Log-Datei aus
4 httplogbackqoschmanualappendershtml
Release Notes BALVI Schnittstellenserver Seite 28 von 37
mehreren Webanwendungen generiert werden Aumlndern Sie den Namen der Logging-Konfiguration entsprechend ab um fuumlr jede Anwendung eine spezifische Logging-Einstellung vornehmen zu koumlnnen
27 Tocmat Optional Suche im bdquoKlassenpfadldquo um den
Ordner bdquoconfldquo erweitern Die Suche nach Dateien uumlber bdquoclasspathldquo setzt voraus dass die Ordner- und Dateinamen im Apache Tomcat bekannt gegeben werden Der Klassenpfad kann in der Datei bdquocatalinapropertiesldquo angepasst werden Wenn Sie dort unter commonloader die folgenden Werte ergaumlnzen kann eine Datei auch im Ordner conf abgelegt werden damit Apache Tomcat diese findet Ansonsten muss die Datei im Ordner lib abgelegt werden
commonloader=$catalinabaseconf$catalinahomeconf
3 Die neue Browser-Oberflaumlche Der BALVI Schnittstellenserver hat seit Version 25 neben der Protokollierung auch die Moumlglichkeit Job-Konfigurationen zu pflegen Der Login ist nur fuumlr einen in BALVI iP eingetragenen ADMIN (z B Benutzer bdquoSYSTEMADMINldquo) mit dem in BALVI iP hinterlegten Passwort moumlglich Zur Anmeldung muss immer [SYSTEMBenutzername] im Feld Benutzer angegeben werden ansonsten schlaumlgt die Anmeldung fehl Bitte achten Sie darauf dass der bdquoldquo (Slash) und nicht der bdquoldquo (Backslash) verwendet werden muss
31 Server-Protokoll Um das Server-Protokoll anzuzeigen waumlhlen Sie den entsprechenden Menuumlpunkt Dort haben Sie seit BSS 26 die Moumlglichkeit uumlber alle Spalten der Protokolle nach Informationen zu suchen
Seit BSS 31 gibt es die Moumlglichkeit Verfahren in bdquoKopfsaumltzeldquo und bdquoDetailsaumltzeldquo zu unterteilen Wurde das Verfahren entsprechend konfiguriert (wie z B bei der Schnittstelle bdquoXGewerbeanzeigenldquo) dann wird im Protokoll-Kopfsatz nur der Start und das Ende der Ausfuumlhrung in der Liste angezeigt Erst bei einem Klick auf bdquoInformationenldquo wird die Liste aller Detailsaumltze angezeigt die im Durchlauf erzeugt wurden
Release Notes BALVI Schnittstellenserver Seite 29 von 37
Verfahren
Die Liste der verfuumlgbaren Verfahren die bei Ihnen im System installiert sind ZB
BEFUNDEhellip Schnittstelle Befunde LM FM oder TS
PROBEhellip Schnittstelle zum Export von Proben an Labore ebenfalls Spezifisch fuumlr einzelne Fachbereiche
MOBILXT Protokolle der BALVI Mobil XT Synchronisation
WEB Allgemeine nicht spezifizierte Protokolle hierunter ist bislang auch die eFi-Protokollierung zu finden
WEB_I0802 Protokolle zur Schnittstelle BALVI iP LIMS (Lebensmittelproben)
XGEWERBE Schnittstelle XGewerbeanzeigen
Klicken Sie auf die Schaltflaumlche so besteht bei den neuen Protokolldatensaumltzen die Moumlglichkeit Detail-Informationen zum Protokollsatz zu erhalten
Release Notes BALVI Schnittstellenserver Seite 30 von 37
Seit BSS 30x ist die Anzeige der Protokolle ebenfalls farblich abgesetzt so dass Protokolleintraumlge mit Fehlern hellrot und Warnungen hellgelb hinterlegt werden
32 Jobs Mit einem Klick auf den Menuumlpunkt Jobs rufen Sie die Oberflaumlche fuumlr die Job-Konfiguration auf Daraufhin werden alle Jobs aufgelistet die fuumlr den BSS freigegeben sind Hier koumlnnen Sie Einstellungen an den Jobs vornehmen und die Jobs aktivieren bzw deaktivieren Die Beschreibungen bzw Einstellungsmoumlglichkeiten fuumlr den jeweiligen SST-Job sind nicht Bestandteil dieser Dokumentation
33 Log-Ausgaben Uumlber den Menuumlpunkt Log-Ausgaben koumlnnen Sie die Ausgabe der Protokolleintraumlge in Echtzeit beobachten
Release Notes BALVI Schnittstellenserver Seite 31 von 37
Starten Sie die Echtzeit-Protokollierung indem Sie auf die Schaltflaumlche mit dem Symbol bdquoPlayldquo (Dreieck) klicken unterbrechen Sie die Ausgabe indem Sie die auf Schaltflaumlche mit dem Symbol bdquoPauseldquo (zwei Balken) klicken
Klicken Sie auf die Schaltflaumlche bdquoAktualisierenldquo (zwei Pfeile) um die neuesten Protokolleintraumlge angezeigt zu bekommen
Klicken Sie auf das Symbol mit dem Papierkorb um die letzten Protokollmeldungen in der Anzeige zu loumlschen
Die Daten in den Protokolldateien auf der Festplatte des Servers sind davon nicht betroffen
Uumlber das Symbol bdquoLogging anpassenldquo (Schraubenschluumlssel) koumlnnen Sie die Ausgabe der Daten im Echtzeitfenster und in den Protokolldateien aumlndern jedoch ist diese Einstellung nur temporaumlr Die Standardeinstellungen koumlnnen ausschlieszliglich uumlber die Anpassung der Datei bdquologback-bssxmlldquo im Konfigurationsverzeichnis des Servers selbst geaumlndert werden
Release Notes BALVI Schnittstellenserver Seite 32 von 37
In der Logging-Parameter Konfiguration koumlnnen Sie verschiedene Parameter einstellen und uumlber die Schaltflaumlche bdquoAnwendenldquo dann sofort im Echtzeitprotokoll sehen Welche Einstellungen moumlglich sind erfahren Sie wenn es eine akute Fehlersituation gibt die detailliertere Ausgaben im Protokoll erfordert
Warnung Wenn Sie den Log-Level fuumlr ROOT oder eine andere Klasse auf TRACE einstellen werden sehr viele Protokollausgaben generiert die auch dazu fuumlhren koumlnnen dass der Server sehr langsam wird oder die Festplatte des Servers zulaumluft wenn fuumlr das Logging kein Dateilimit konfiguriert wurde
34 LogoutAbmeldung vom System Zum Abmelden waumlhlen Sie oben rechts das Kontextmenuuml
35 Cache loumlschen Der Cache wird in der Regel automatisch geloumlscht Wenn Sie jedoch gerade in BALVI iP eine Aumlnderung an den Schnittstellen eingespielt haben und moumlchten dass diese sofort wirksam wird kann die Funktion bdquoCache loumlschenldquo dazu verwendet werden dass der BALVI Schnittstellenserver die Einstellungen bei der naumlchsten Anfrage neu einliest
Release Notes BALVI Schnittstellenserver Seite 33 von 37
Release Notes BALVI Schnittstellenserver Seite 34 von 37
4 Einrichtung in BALVI iP Um die Verfahren fuumlr den BALVI Schnittstellenserver fuumlr Anwender freizuschalten wird das Objekt bdquoSystemeinstellungenldquo oder bdquoMandanten- und Benutzereinstellungenldquo verwendet Die Anpassung ist je Verfahren moumlglich so kann in BALVI iP fuumlr den Zugriff durch den BALVI Schnittstellenserver ein Benutzer bdquoAldquo am Verfahren bdquoMobilldquo berechtigt werden ein Benutzer bdquoBldquo nur am Verfahren bdquoSLA_FLESHldquo usw Die Logik ist jedoch einheitlich Je Verfahren wird durch BALVI eine Verfahrensgruppe mit dem Verfahrensnamen angelegt und mit den entsprechenden Einstellungen vorkonfiguriert welche durch das Verfahren erforderlich sind Dabei kann die Komplexitaumlt der Einstellungen variieren wie z B an den zu Version 23 verfuumlgbaren Verfahren bdquoMobilldquo und bdquoSLA_Fleshldquo ersichtlich wird
Im Verfahren BALVI Mobil sind diverse Anpassungen moumlglich welche je Bundesland oder eingesetzter Import- und Export-Variante durch den BALVI Schnittstellenserver bei der Bearbeitung von Anfragen gepruumlft werden siehe Punkt 3 Abb Mobil-Einstellung in BALVI iP
Abb Mobil-Einstellung in BALVI iP
Alle Verfahren verwenden jedoch die regulaumlre Benutzerverwaltung von BALVI iP Ein Benutzer ohne Passwort gilt fuumlr BALVI iP als gesperrt was fuumlr das Login bedeutet dass der Anwender sich nur uumlber die Active-Directory-Authentifizierung anmelden kann Ist das nicht moumlglich (bzw nicht konfiguriert) kann der Anwender sich weder in BALVI iP noch uumlber die Webservice-Schnittstelle authentifizieren
Fuumlr Dienste-Schnittstellen welche keine persoumlnliche Authentifizierung durch einen Anwender erfordern wird empfohlen einen separaten Benutzer in der Benutzerverwaltung anzulegen und ein sicheres Kennwort zu vergeben Das Anlegen von zusaumltzlichen Benutzern gilt nicht fuumlr BALVI mobil XT da beim Holen und Uumlbermitteln von Daten jeder Benutzer auch ein fachlich konfigurierter Anwender innerhalb von BALVI iP ist und die Anwendungsoberflaumlche ebenfalls zur Erfassung von Daten verwendet
Unter Punkt 2 der Abb Mobil-Einstellung in BALVI iP wird ein modales Fenster geoumlffnet (Abb BALVI mobil Benutzerverwaltung) Innerhalb dieses modalen Fensters werden mandantenweise die Benutzer fuumlr BALVI
Release Notes BALVI Schnittstellenserver Seite 35 von 37
mobil und den jeweiligen Fachbereich festgelegt Dabei ist es wichtig dass man die Haken bdquoAktiv fuumlr hellipldquo bei bdquohellip mobilldquo und bei einem Fachbereich (bdquohellip LMldquo bdquohellip FMldquo usw) setzt weil sonst uumlber den BALVI Schnittstellenserver keine Kommunikation mit BALVI iP moumlglich ist
Abb BALVI mobil Benutzerverwaltung
Alternativ zur Passwort-Authentifizierung wird wie beschrieben auch die Active-Directory-Authentifizierung angeboten Dazu muss der BALVI iP-Anwender uumlber die Schaltflaumlche bdquoDomaumlnen-Benutzer zuordnenldquo mit dem Active Directory verknuumlpft werden
Nur wenn die Active-Directory-Konfigurationen in BALVI iP und im BALVI Schnittstellenserver auf dieselbe Domaumlne verweisen sind die Domaumlnen-Zuordnung und die Active-Directory-Authentifizierung (z B uumlber BALVI mobil XT) moumlglich
Release Notes BALVI Schnittstellenserver Seite 36 von 37
5 Bekannte Probleme und Loumlsungen
51 ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner Bei der Job-Bearbeitung tritt folgender Fehler auf ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner
Behebung
Fuumlhren Sie das beiliegende IP-Patch (UPDATEexe) aus bevor Sie das WAR austauschen
52 Server startet nicht Sie finden folgende Zeilen im Protokoll (catalinaout oder bsslog)
ERROR [localhost-startStop-1] [IdentityServiceImpl] serverID must not be empty
ERROR [localhost-startStop-1] [ContextLoader] Context initialization failed
Behebung
Setzen Sie die Umgebungsvariable ldquoserverIDrdquo in der Datei bdquocontextxmlldquo
53 ORA-00942 table or view does not exist In vielen Faumlllen wird der Fehler ldquoTabelle oder View nicht vorhandenrdquo ausgeworfen (Java-Protokoll im Ordner logs von Apache Tomcat) wenn eine neue Schnittstelle eingerichtet oder ein neues BALVI iP Release bzw Update eingespielt wurde ohne anschlieszligend das aktuelle GRANT-Skript auszufuumlhren
Behebung
Fuumlhren Sie das GRANT-Skript erneut aus
54 ORA-0406x bdquoBestehender Paketstatus wurde aufgehobenldquo
ORA-04061 Bestehender Status von package body ABCXYZ wurde annulliert
ORA-04065 Ausfuumlhrung nicht erfolgreich package body ABCXYZ wurde geaumlndert oder geloumlscht
Release Notes BALVI Schnittstellenserver Seite 37 von 37
Der Fehler tritt haumlufig ein nachdem die UPDATEexe ausgefuumlhrt und in der Ausfuumlhrungsliste ein Package aktualisiert wurde Oracle merkt sich je User-Session bestimmte Werte im Package wenn der Anwender es verwendet hat Durch einen bdquoCREATE OR REPLACE PACKAGEldquo-Befehl kann dieser Status temporaumlr aufgehoben werden Normalerweise tritt dieser Fehler nach dem Update genau einmal in jeder aktiven Session auf wenn der BSS nicht neu gestartet wird
Behebung
Starten Sie nach jedem Update den BSS neu um alle laufenden Sessions zu beenden
55 Jobs sind nicht ausfuumlhrbar
1 Ein Job wird mit dem Status bdquoNicht unterstuumltztldquo angezeigt wenn fuumlr seine Ausfuumlhrung eine houmlhere Version des BSS erforderlich ist
2 Nach dem Klonen der Datenbank von der Produktions- auf die Testumgebung erhalten alle Jobs automatisch den Status bdquoDeaktiviertldquo wenn die bdquoserverIDldquo nicht identisch ist
Beide Statusaumlnderungen sind gewollt Damit soll verhindert werden dass Jobs nach einem Serverneustart oder nach einem Update automatisch starten und dabei Fehler verursachen
Um Jobs mit dem Status bdquoNicht unterstuumltztldquo nutzen und konfigurieren zu koumlnnen ist es erforderlich den BALVI Schnittstellenserver zu aktualisieren
Deaktivierte Jobs koumlnnen Sie aktivieren indem Sie den jeweiligen Job an den aktuellen Server binden und den Haken bei bdquoAktivldquo setzen
Release Notes BALVI Schnittstellenserver Seite 22 von 37
bdquowebLoginUseActiveDirectoryAuthenticationrdquo
Die Authentifizierung in der Browser-Oberflaumlche kann uumlber die Active-Directory-Authentifizierung erfolgen In der ersten Version ist nur die Protokoll-Auswertung moumlglich wenn der ADMIN sich anmeldet Dieser hat normalerweise niemals AD-Kennungen zugeordnet BALVI empfiehlt diese Einstellung auf bdquofalseldquo zu belassen Webservices welche uumlber SOAPREST zugreifen koumlnnen die Active-Directory-Authentifizierung trotzdem verwenden
ltEnvironment
name=webLoginUseActiveDirectoryAuthentication
value=false
type=javalangBoolean
override=true
gt
ldquoldapDaysBeforeExpirationNotificationrdquo
Die Passwort-Aumlnderung im Active-Directory uumlber die Browser-Oberflaumlche ist in der ersten Version noch nicht implementiert der Parameter wird bislang nicht ausgewertet
ltEnvironment
name=ldapDaysBeforeExpirationNotification
value=14
type=javalangInteger
override=true
gt
2514 Statement-Protokollierung in BALVI iP
Diese Option aktiviert die Lese- und Aumlnderungsprotokollierung fuumlr BALVI iP Standard ist bdquofalseldquo und wird fuumlr alle Kunden empfohlen solange keine speziellen Datenbank-Jobs eingerichtet wurden welche zeitgesteuert die Protokolleintraumlge wieder loumlschen Fuumlr Bayern wurde ein spezielles Konzept zur Leseprotokollierung entworfen Wenn Sie mehr daruumlber erfahren moumlchten kontaktieren Sie bitte die BALVI GmbH
ltEnvironment
name=enableSqlStatementMonitoring
value=true
type=javalangBoolean
override=true
gt
Beachten Sie dass diese Option massive INSERT-Statements in BALVI iP in die Tabelle VIS_D92 ausfuumlhrt Jedes abgesetzte SQL-Statement wird dabei vollstaumlndig protokolliert Dieses erzeugt eine sehr hohe INSERT-Last und in der Folge auch erhoumlhte Redolog-Switches und COMMIT-Transaktionen
Optional Aktivieren der INSERT + APPEND - Logik
Beachten Sie bitte die Hinweise von Oracle zum Hint + APPEND
Release Notes BALVI Schnittstellenserver Seite 23 von 37
Wenn Sie dieses Verhalten aktivieren moumlchten ergaumlnzen Sie bitte den folgenden Environment-Parameter
ltEnvironment
name=statementMonitoringactivateAppendMode
value=true
type=javalangBoolean
override=true
gt
2515 Einstellungen fuumlr BALVI mobil XT (bzw den bdquopartitionedExportldquo)
Diese Logik des FIFO-Buffers wurde so konzipiert dass dem Rechenzentrum diverse Einstellmoumlglichkeiten uumlber die Datei bdquocontextxmlldquo zur Verfuumlgung stehen um die Steuerung des FIFO-Puffers zu beeinflussen
Schematische Darstellung des FIFO-Puffers
Das ermoumlglicht es z B dem BALVI mobil XT Client (14 oder houmlher) den aktiven Block abzuholen und dies beim Fehler bis zu 10-mal zu wiederholen Sobald der Block [001] erfolgreich beim Client angekommen ist und dieser den naumlchsten Block anfragt wird der Block [001] verworfen wird Der Server fuumlllt dann im Hintergrund den frei gewordenen Block wieder waumlhrend der Client den Block [002] abholt
Die Groumlszlige und Anzahl der vorgecachten Bloumlcke kann uumlber die folgenden Einstellungen in der Datei bdquocontextxmlldquo definiert werden
ltEnvironment
name=partitionedExportmaxBufferedPartitions
value=3 type=javalangInteger override=true
gt
ltEnvironment
name=partitionedExportpartitionSize
value=256000 type=javalangInteger override=true
gt
Die Einstellung partitionedExportmaxBufferedPartitions ist dabei die Anzahl der vorgecachten Bloumlcke mindestens muss 2 angegeben werden Der Puffercache wird ausschlieszliglich im RAM der JVM aufgebaut es wird folglich mehr Arbeitsspeicher verwendet Dieser Arbeitsspeicher muss je gleichzeitiger Session auf dem Server bereitgestellt werden die Default-Einstellung mit 3 Partitionen a 256 KB + dem aktiven Puffer erfordern 1 MB RAM je aktiven Anwender
Aktiv
er
Puffe
r
[001] Vorg
ecac
hter
Bl
ock
[002] Vorg
ecac
hter
Bl
ock
[003]
Aktiv
er P
uffe
r
[002] Vorg
ecac
hter
Bl
ock
[003] Vorg
ecac
hter
Bl
ock
[leer]
Release Notes BALVI Schnittstellenserver Seite 24 von 37
Gleichzeitig wurde die Moumlglichkeit geschaffen dass die maximale Anzahl an gleichzeitigen Exporten durch das Rechenzentrum eingeschraumlnkt werden kann um einem OutOfMemory-Fehler vorzubeugen Die Einstellung
ltEnvironment
name=partitionedExportmaxConcurrentExports
value=10 type=javalangInteger override=true
gt
muss entsprechend der zu erwartenden gleichzeitigen Zugriffe konzipiert werden ansonsten wird der Server einen Verbindungsversuch durch die Clients ablehnen
Beachten Sie dass die folgenden Einstellungen partitionedExportmaxBufferedPartitions partitionedExportmaxConcurrentExports und partitionedExportpartitionSize gemeinsam als Rechenbasis fuumlr den RAM-Bedarf des Webservers herangezogen werden muumlssen
Folgende Faustformel sollte fuumlr die Einrichtung verwendet werden
Min 256 MB (Serverbasis) + (11 partitionedExportmaxConcurrentExports partitionedExportmaxBufferedPartitions partitionedExportpartitionSize)
Beispiel 50 gleichzeitige Anwender Blockgroumlszlige 256 KB 4 Partitionen
256 MB + (11 50 256 4) KB = 312 MB fuumlr die JVM
Empf 512 MB (Serverbasis) + (12 partitionedExportmaxConcurrentExports partitionedExportmaxBufferedPartitions partitionedExportpartitionSize)
Beispiel 50 gleichzeitige Anwender Blockgroumlszlige 256 KB 4 Partitionen
512 MB + (12 50 256 4) KB = 572 MB fuumlr die JVM
partitionedExportmaxConcurrentExports
Bestimmt die Anzahl der maximalen Export Tasks (Threads) die fuumlr partitionierte Exporte bereitgestellt werden Wenn die Anzahl uumlberschritten wird wird die entsprechende Exportanfrage abgewiesen und der Client muss zu einem spaumlteren Zeitpunkt erneut anfragen Stellen Sie diesen Wert entsprechend der zu erwartenden Benutzeranzahl ein bei 50 Anwendern also 50
Exporte oumlffnen auf der Datenbank entsprechend zur Ausfuumlhrungszeit min einen Cursor ggf fuumlr rekursive Unterabfragen kurzfristig sogar mehr Die hier eingestellte Anzahl muss mit der Anzahl von maxActive korrelieren
ltEnvironment
name=partitionedExportmaxConcurrentExports
value=10 type=javalangInteger override=true
gt
partitionedExportmaxBufferedPartitions
Bestimmt die Anzahl der Datenbloumlcke (Partitionen) die vom Server bei Abruf eines Exportes gepuffert werden Die seit Version 24 eingefuumlhrte FIFO-Puffer-Logik ermoumlglicht dass der Server schon die Ergebnisse vorpuffert so dass der Client weniger Wartezeiten bei der Anfrage nach Daten hat Diese
Release Notes BALVI Schnittstellenserver Seite 25 von 37
Puffer-Logik unterteilt den Exportdatenstrom (je Export) in mehre Bloumlcke Der Client kann nun den letzten Block neu anfordern oder den naumlchsten Block wenn der letzte Block erfolgreich verarbeitet wurde Wie viele naumlchste Bloumlcke durch den Server bereit gestellt werden entscheidet diese Einstellung Sobald kein naumlchster Block mehr bereit gestellt werden muss wird der Datenbank-Cursor geschlossen eine Erhoumlhung kann also zu einer Entlastung der aktiven DB-Verbindungen fuumlhren erhoumlht jedoch den Bedarf an RAM des Servers
Der von BALVI voreingestellte Wert ist 3
ltEnvironment
name=partitionedExportmaxBufferedPartitions
value=3 type=javalangInteger override=true
gt
partitionedExportpartitionSizeldquo
Die Groumlszlige der Datenbloumlcke (Partitionen) die an den Client uumlbermittelt werden in Bytes Wenn Sie diesen Wert zu niedrig einstellen reduziert sich die Effizienz des Caches da der Client mehr Datenbloumlcke hintereinander abrufen muss Waumlhlen Sie einen zu groszligen Wert wird die neu zu uumlbertragende Datenmenge im Fall eines Fehlers houmlher
Der von BALVI voreingestellte Wert ist 256000 (256 KB)
ltEnvironment
name=partitionedExportpartitionSize
value=256000 type=javalangInteger override=true
gt
exportTokensmaxTokenCount
Maximale Anzahl der gleichzeitig vergebenen Token die vom Server gecached werden Jede Sitzung welche einen Export durchfuumlhrt erhaumllt einen Session-Token
Wenn eine Sitzung laumlngere Zeit nicht verwendet wurde wird dieser Session-Token wieder entfernt Wenn Sie den Wert zu niedrig einstellen fuumlhrt das zu einer generellen Session-Begrenzung auch fuumlr den nicht partitionierten Export-Modus welcher ab Version 21 verfuumlgbar ist
Ist die Anzahl der Tokens houmlher als die Datenbankeinstellung maxActive kann es vorkommen dass zwar eine Session gestartet werden kann jedoch kein Datenexport zustande kommt
Der von BALVI voreingestellte Wert ist 2000
ltEnvironment
name=exportTokensmaxTokenCount
value=20 type=javalangInteger override=true
gt
exportTokenstokenExpirationInSeconds
Zeit in Sekunden die verstreichen muss bis ein Token unguumlltig wird falls darauf kein Zugriff mehr erfolgt Nach einem erfolgreichen Export wird der Token automatisch geschlossen diese Option ist fuumlr den Abbruchfall vorgesehen Der von BALVI voreingestellte Wert ist 180 (180 s = 3 min)
Release Notes BALVI Schnittstellenserver Seite 26 von 37
ltEnvironment
name=exportTokenstokenExpirationInSeconds
value=180 type=javalangInteger override=true
gt
exportTokenstokenDisposalInSeconds
Zeit in Sekunden die verstreichen muss bis ein Token das erfolgreich abgearbeitet wurde aus dem Cache geloumlscht wird Um sicher zu stellen dass der letzte Exportblock noch erfolgreich abgerufen werden kann bleibt der Token auch nach Fertigmeldung des Clients noch N Sek guumlltig
Der von BALVI voreingestellte Wert ist 60 (60 s = 1 min)
ltEnvironment
name=exportTokenstokenDisposalInSeconds
value=60 type=javalangInteger override=true
gt
2516 Job-Verwaltung fuumlr den BSS konfigurieren Aktivierung der Jobverwaltung
Bis zur Version 28 des BSS gab es den Parameter bdquoavailableServicesldquo Dieser konnte bei Bedarf aktiviert werden wenn die Jobs benoumltigt wurden
Mit Version 30 ist die Einstellung bdquoavailableServicesldquo zu entfernen und kann durch den neuen optionalen Parameter bdquoisJobServiceEnabledldquo in der Datei bdquocontextxmlldquo ersetzt werden
lt-- Neue Parameter zur Aktivierung des Job Service Ersatz fuumlr availableServices --gt
ltEnvironment
name=isJobServiceEnabled
value=true
type=javalangBoolean
override=true
gt
Ab BSS 30 wird die Jobs-Engine standardmaumlszligig aktiviert Sollte die Jobs-Engine nicht benoumltigt werden muss bdquovalueldquo der Wert bdquofalseldquo zugewiesen werden Wird bdquoisJobServiceEnabledldquo nicht eingefuumlgt sind die Jobs trotzdem standardmaumlszligig aktiv
Nach dem Neustart des Servers und erneutem Einloggen erscheint nun zusaumltzlich der Menuumlpunkt bdquoJobsldquo
bdquopasswordKeyldquo fuumlr Jobs
In der Job-Logik wird ein von BALVI definierter Standard-Schluumlssel fuumlr die Ablagen von schuumltzenswerten Daten z B Passwoumlrtern verwendet Diese Einstellung ermoumlglicht den BALVI-Standard zu uumlberschreiben Wenn Sie diese Einstellung aumlndern muumlssen jedoch alle bislang verschluumlsselten Job-Parameter neu verschluumlsselt werden
ltEnvironment
name=javacompenvjobspasswordKey
value=MeinHochsicheresNeuesPasswort
type=javalangString
Release Notes BALVI Schnittstellenserver Seite 27 von 37
override=true
gt
bdquoJob ID enableddisabledldquo (Deprecated ersetzt ab 28 durch das bdquoBindenldquo von Jobs)
Sondereinstellungen fuumlr die Job-Verwaltung Da alle Jobs in einer Datenbank administriert werden jedoch ggf verteilt auf mehreren Tomcat-Servern ausgefuumlhrt werden sollen besteht hier die Option Jobs fuumlr die aktuelle Tomcat-Instanz separat zu deaktivieren
Die Einstellung ID koumlnnte z B folgendermaszligen aussehen javacompenvjobsC0DB58D8D52C4BBC966D1DC788A4EF8Benabled
Fuumlr weitere Fragen zu dieser Einstellung kontaktieren Sie bitte die BALVI GmbH
ltEnvironment
name=javacompenvjobsIDenabled
value=false
type=javalangBoolean
override=true
gt
2517 Weitere optionale Parameter
Es ist fuumlr diverse einzelne Schnittstellen ggf erforderlich Einstellungen in der Datei bdquocontextxmlldquo zu ergaumlnzen Hinweise zu diesen Parametern sind dann in dem der Schnittstelle beiliegenden Dokument enthalten Das gilt z B fuumlr die Schnittstelle bdquoXGewerbeanzeigenldquo
26 Logging mit logback Das Logging wurde komplett uumlberarbeitet Statt bdquoLog4Jldquo wird jetzt bdquologbackldquo4 benutzt Ab BSS 30 ist es zwingend notwendig die Einstellung vorzunehmen um das Logging der Anwendung zu steuern
Migration Ergaumlnzen Sie die neue Einstellung bdquologgingconfigldquo
lt-- Neue Paramter zur Angabe der Logback Config Ersatz fuumlr log4jConfigLocation --gt
ltEnvironment
name=loggingconfig
value=$catalinabaseconflogback-bssxml
type=javalangString
override=true
gt
Nach wie vor steht es Ihnen frei die Logging-Konfiguration eigenstaumlndig anzupassen
Wenn Sie jedoch dieselbe WAR in einer Tomcat-Instanz unter mehreren Context-Namen betreiben wuumlrden beide dieselbe Logging-Konfiguration verwenden so dass alle Protokolleintraumlge in einer Log-Datei aus
4 httplogbackqoschmanualappendershtml
Release Notes BALVI Schnittstellenserver Seite 28 von 37
mehreren Webanwendungen generiert werden Aumlndern Sie den Namen der Logging-Konfiguration entsprechend ab um fuumlr jede Anwendung eine spezifische Logging-Einstellung vornehmen zu koumlnnen
27 Tocmat Optional Suche im bdquoKlassenpfadldquo um den
Ordner bdquoconfldquo erweitern Die Suche nach Dateien uumlber bdquoclasspathldquo setzt voraus dass die Ordner- und Dateinamen im Apache Tomcat bekannt gegeben werden Der Klassenpfad kann in der Datei bdquocatalinapropertiesldquo angepasst werden Wenn Sie dort unter commonloader die folgenden Werte ergaumlnzen kann eine Datei auch im Ordner conf abgelegt werden damit Apache Tomcat diese findet Ansonsten muss die Datei im Ordner lib abgelegt werden
commonloader=$catalinabaseconf$catalinahomeconf
3 Die neue Browser-Oberflaumlche Der BALVI Schnittstellenserver hat seit Version 25 neben der Protokollierung auch die Moumlglichkeit Job-Konfigurationen zu pflegen Der Login ist nur fuumlr einen in BALVI iP eingetragenen ADMIN (z B Benutzer bdquoSYSTEMADMINldquo) mit dem in BALVI iP hinterlegten Passwort moumlglich Zur Anmeldung muss immer [SYSTEMBenutzername] im Feld Benutzer angegeben werden ansonsten schlaumlgt die Anmeldung fehl Bitte achten Sie darauf dass der bdquoldquo (Slash) und nicht der bdquoldquo (Backslash) verwendet werden muss
31 Server-Protokoll Um das Server-Protokoll anzuzeigen waumlhlen Sie den entsprechenden Menuumlpunkt Dort haben Sie seit BSS 26 die Moumlglichkeit uumlber alle Spalten der Protokolle nach Informationen zu suchen
Seit BSS 31 gibt es die Moumlglichkeit Verfahren in bdquoKopfsaumltzeldquo und bdquoDetailsaumltzeldquo zu unterteilen Wurde das Verfahren entsprechend konfiguriert (wie z B bei der Schnittstelle bdquoXGewerbeanzeigenldquo) dann wird im Protokoll-Kopfsatz nur der Start und das Ende der Ausfuumlhrung in der Liste angezeigt Erst bei einem Klick auf bdquoInformationenldquo wird die Liste aller Detailsaumltze angezeigt die im Durchlauf erzeugt wurden
Release Notes BALVI Schnittstellenserver Seite 29 von 37
Verfahren
Die Liste der verfuumlgbaren Verfahren die bei Ihnen im System installiert sind ZB
BEFUNDEhellip Schnittstelle Befunde LM FM oder TS
PROBEhellip Schnittstelle zum Export von Proben an Labore ebenfalls Spezifisch fuumlr einzelne Fachbereiche
MOBILXT Protokolle der BALVI Mobil XT Synchronisation
WEB Allgemeine nicht spezifizierte Protokolle hierunter ist bislang auch die eFi-Protokollierung zu finden
WEB_I0802 Protokolle zur Schnittstelle BALVI iP LIMS (Lebensmittelproben)
XGEWERBE Schnittstelle XGewerbeanzeigen
Klicken Sie auf die Schaltflaumlche so besteht bei den neuen Protokolldatensaumltzen die Moumlglichkeit Detail-Informationen zum Protokollsatz zu erhalten
Release Notes BALVI Schnittstellenserver Seite 30 von 37
Seit BSS 30x ist die Anzeige der Protokolle ebenfalls farblich abgesetzt so dass Protokolleintraumlge mit Fehlern hellrot und Warnungen hellgelb hinterlegt werden
32 Jobs Mit einem Klick auf den Menuumlpunkt Jobs rufen Sie die Oberflaumlche fuumlr die Job-Konfiguration auf Daraufhin werden alle Jobs aufgelistet die fuumlr den BSS freigegeben sind Hier koumlnnen Sie Einstellungen an den Jobs vornehmen und die Jobs aktivieren bzw deaktivieren Die Beschreibungen bzw Einstellungsmoumlglichkeiten fuumlr den jeweiligen SST-Job sind nicht Bestandteil dieser Dokumentation
33 Log-Ausgaben Uumlber den Menuumlpunkt Log-Ausgaben koumlnnen Sie die Ausgabe der Protokolleintraumlge in Echtzeit beobachten
Release Notes BALVI Schnittstellenserver Seite 31 von 37
Starten Sie die Echtzeit-Protokollierung indem Sie auf die Schaltflaumlche mit dem Symbol bdquoPlayldquo (Dreieck) klicken unterbrechen Sie die Ausgabe indem Sie die auf Schaltflaumlche mit dem Symbol bdquoPauseldquo (zwei Balken) klicken
Klicken Sie auf die Schaltflaumlche bdquoAktualisierenldquo (zwei Pfeile) um die neuesten Protokolleintraumlge angezeigt zu bekommen
Klicken Sie auf das Symbol mit dem Papierkorb um die letzten Protokollmeldungen in der Anzeige zu loumlschen
Die Daten in den Protokolldateien auf der Festplatte des Servers sind davon nicht betroffen
Uumlber das Symbol bdquoLogging anpassenldquo (Schraubenschluumlssel) koumlnnen Sie die Ausgabe der Daten im Echtzeitfenster und in den Protokolldateien aumlndern jedoch ist diese Einstellung nur temporaumlr Die Standardeinstellungen koumlnnen ausschlieszliglich uumlber die Anpassung der Datei bdquologback-bssxmlldquo im Konfigurationsverzeichnis des Servers selbst geaumlndert werden
Release Notes BALVI Schnittstellenserver Seite 32 von 37
In der Logging-Parameter Konfiguration koumlnnen Sie verschiedene Parameter einstellen und uumlber die Schaltflaumlche bdquoAnwendenldquo dann sofort im Echtzeitprotokoll sehen Welche Einstellungen moumlglich sind erfahren Sie wenn es eine akute Fehlersituation gibt die detailliertere Ausgaben im Protokoll erfordert
Warnung Wenn Sie den Log-Level fuumlr ROOT oder eine andere Klasse auf TRACE einstellen werden sehr viele Protokollausgaben generiert die auch dazu fuumlhren koumlnnen dass der Server sehr langsam wird oder die Festplatte des Servers zulaumluft wenn fuumlr das Logging kein Dateilimit konfiguriert wurde
34 LogoutAbmeldung vom System Zum Abmelden waumlhlen Sie oben rechts das Kontextmenuuml
35 Cache loumlschen Der Cache wird in der Regel automatisch geloumlscht Wenn Sie jedoch gerade in BALVI iP eine Aumlnderung an den Schnittstellen eingespielt haben und moumlchten dass diese sofort wirksam wird kann die Funktion bdquoCache loumlschenldquo dazu verwendet werden dass der BALVI Schnittstellenserver die Einstellungen bei der naumlchsten Anfrage neu einliest
Release Notes BALVI Schnittstellenserver Seite 33 von 37
Release Notes BALVI Schnittstellenserver Seite 34 von 37
4 Einrichtung in BALVI iP Um die Verfahren fuumlr den BALVI Schnittstellenserver fuumlr Anwender freizuschalten wird das Objekt bdquoSystemeinstellungenldquo oder bdquoMandanten- und Benutzereinstellungenldquo verwendet Die Anpassung ist je Verfahren moumlglich so kann in BALVI iP fuumlr den Zugriff durch den BALVI Schnittstellenserver ein Benutzer bdquoAldquo am Verfahren bdquoMobilldquo berechtigt werden ein Benutzer bdquoBldquo nur am Verfahren bdquoSLA_FLESHldquo usw Die Logik ist jedoch einheitlich Je Verfahren wird durch BALVI eine Verfahrensgruppe mit dem Verfahrensnamen angelegt und mit den entsprechenden Einstellungen vorkonfiguriert welche durch das Verfahren erforderlich sind Dabei kann die Komplexitaumlt der Einstellungen variieren wie z B an den zu Version 23 verfuumlgbaren Verfahren bdquoMobilldquo und bdquoSLA_Fleshldquo ersichtlich wird
Im Verfahren BALVI Mobil sind diverse Anpassungen moumlglich welche je Bundesland oder eingesetzter Import- und Export-Variante durch den BALVI Schnittstellenserver bei der Bearbeitung von Anfragen gepruumlft werden siehe Punkt 3 Abb Mobil-Einstellung in BALVI iP
Abb Mobil-Einstellung in BALVI iP
Alle Verfahren verwenden jedoch die regulaumlre Benutzerverwaltung von BALVI iP Ein Benutzer ohne Passwort gilt fuumlr BALVI iP als gesperrt was fuumlr das Login bedeutet dass der Anwender sich nur uumlber die Active-Directory-Authentifizierung anmelden kann Ist das nicht moumlglich (bzw nicht konfiguriert) kann der Anwender sich weder in BALVI iP noch uumlber die Webservice-Schnittstelle authentifizieren
Fuumlr Dienste-Schnittstellen welche keine persoumlnliche Authentifizierung durch einen Anwender erfordern wird empfohlen einen separaten Benutzer in der Benutzerverwaltung anzulegen und ein sicheres Kennwort zu vergeben Das Anlegen von zusaumltzlichen Benutzern gilt nicht fuumlr BALVI mobil XT da beim Holen und Uumlbermitteln von Daten jeder Benutzer auch ein fachlich konfigurierter Anwender innerhalb von BALVI iP ist und die Anwendungsoberflaumlche ebenfalls zur Erfassung von Daten verwendet
Unter Punkt 2 der Abb Mobil-Einstellung in BALVI iP wird ein modales Fenster geoumlffnet (Abb BALVI mobil Benutzerverwaltung) Innerhalb dieses modalen Fensters werden mandantenweise die Benutzer fuumlr BALVI
Release Notes BALVI Schnittstellenserver Seite 35 von 37
mobil und den jeweiligen Fachbereich festgelegt Dabei ist es wichtig dass man die Haken bdquoAktiv fuumlr hellipldquo bei bdquohellip mobilldquo und bei einem Fachbereich (bdquohellip LMldquo bdquohellip FMldquo usw) setzt weil sonst uumlber den BALVI Schnittstellenserver keine Kommunikation mit BALVI iP moumlglich ist
Abb BALVI mobil Benutzerverwaltung
Alternativ zur Passwort-Authentifizierung wird wie beschrieben auch die Active-Directory-Authentifizierung angeboten Dazu muss der BALVI iP-Anwender uumlber die Schaltflaumlche bdquoDomaumlnen-Benutzer zuordnenldquo mit dem Active Directory verknuumlpft werden
Nur wenn die Active-Directory-Konfigurationen in BALVI iP und im BALVI Schnittstellenserver auf dieselbe Domaumlne verweisen sind die Domaumlnen-Zuordnung und die Active-Directory-Authentifizierung (z B uumlber BALVI mobil XT) moumlglich
Release Notes BALVI Schnittstellenserver Seite 36 von 37
5 Bekannte Probleme und Loumlsungen
51 ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner Bei der Job-Bearbeitung tritt folgender Fehler auf ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner
Behebung
Fuumlhren Sie das beiliegende IP-Patch (UPDATEexe) aus bevor Sie das WAR austauschen
52 Server startet nicht Sie finden folgende Zeilen im Protokoll (catalinaout oder bsslog)
ERROR [localhost-startStop-1] [IdentityServiceImpl] serverID must not be empty
ERROR [localhost-startStop-1] [ContextLoader] Context initialization failed
Behebung
Setzen Sie die Umgebungsvariable ldquoserverIDrdquo in der Datei bdquocontextxmlldquo
53 ORA-00942 table or view does not exist In vielen Faumlllen wird der Fehler ldquoTabelle oder View nicht vorhandenrdquo ausgeworfen (Java-Protokoll im Ordner logs von Apache Tomcat) wenn eine neue Schnittstelle eingerichtet oder ein neues BALVI iP Release bzw Update eingespielt wurde ohne anschlieszligend das aktuelle GRANT-Skript auszufuumlhren
Behebung
Fuumlhren Sie das GRANT-Skript erneut aus
54 ORA-0406x bdquoBestehender Paketstatus wurde aufgehobenldquo
ORA-04061 Bestehender Status von package body ABCXYZ wurde annulliert
ORA-04065 Ausfuumlhrung nicht erfolgreich package body ABCXYZ wurde geaumlndert oder geloumlscht
Release Notes BALVI Schnittstellenserver Seite 37 von 37
Der Fehler tritt haumlufig ein nachdem die UPDATEexe ausgefuumlhrt und in der Ausfuumlhrungsliste ein Package aktualisiert wurde Oracle merkt sich je User-Session bestimmte Werte im Package wenn der Anwender es verwendet hat Durch einen bdquoCREATE OR REPLACE PACKAGEldquo-Befehl kann dieser Status temporaumlr aufgehoben werden Normalerweise tritt dieser Fehler nach dem Update genau einmal in jeder aktiven Session auf wenn der BSS nicht neu gestartet wird
Behebung
Starten Sie nach jedem Update den BSS neu um alle laufenden Sessions zu beenden
55 Jobs sind nicht ausfuumlhrbar
1 Ein Job wird mit dem Status bdquoNicht unterstuumltztldquo angezeigt wenn fuumlr seine Ausfuumlhrung eine houmlhere Version des BSS erforderlich ist
2 Nach dem Klonen der Datenbank von der Produktions- auf die Testumgebung erhalten alle Jobs automatisch den Status bdquoDeaktiviertldquo wenn die bdquoserverIDldquo nicht identisch ist
Beide Statusaumlnderungen sind gewollt Damit soll verhindert werden dass Jobs nach einem Serverneustart oder nach einem Update automatisch starten und dabei Fehler verursachen
Um Jobs mit dem Status bdquoNicht unterstuumltztldquo nutzen und konfigurieren zu koumlnnen ist es erforderlich den BALVI Schnittstellenserver zu aktualisieren
Deaktivierte Jobs koumlnnen Sie aktivieren indem Sie den jeweiligen Job an den aktuellen Server binden und den Haken bei bdquoAktivldquo setzen
Release Notes BALVI Schnittstellenserver Seite 23 von 37
Wenn Sie dieses Verhalten aktivieren moumlchten ergaumlnzen Sie bitte den folgenden Environment-Parameter
ltEnvironment
name=statementMonitoringactivateAppendMode
value=true
type=javalangBoolean
override=true
gt
2515 Einstellungen fuumlr BALVI mobil XT (bzw den bdquopartitionedExportldquo)
Diese Logik des FIFO-Buffers wurde so konzipiert dass dem Rechenzentrum diverse Einstellmoumlglichkeiten uumlber die Datei bdquocontextxmlldquo zur Verfuumlgung stehen um die Steuerung des FIFO-Puffers zu beeinflussen
Schematische Darstellung des FIFO-Puffers
Das ermoumlglicht es z B dem BALVI mobil XT Client (14 oder houmlher) den aktiven Block abzuholen und dies beim Fehler bis zu 10-mal zu wiederholen Sobald der Block [001] erfolgreich beim Client angekommen ist und dieser den naumlchsten Block anfragt wird der Block [001] verworfen wird Der Server fuumlllt dann im Hintergrund den frei gewordenen Block wieder waumlhrend der Client den Block [002] abholt
Die Groumlszlige und Anzahl der vorgecachten Bloumlcke kann uumlber die folgenden Einstellungen in der Datei bdquocontextxmlldquo definiert werden
ltEnvironment
name=partitionedExportmaxBufferedPartitions
value=3 type=javalangInteger override=true
gt
ltEnvironment
name=partitionedExportpartitionSize
value=256000 type=javalangInteger override=true
gt
Die Einstellung partitionedExportmaxBufferedPartitions ist dabei die Anzahl der vorgecachten Bloumlcke mindestens muss 2 angegeben werden Der Puffercache wird ausschlieszliglich im RAM der JVM aufgebaut es wird folglich mehr Arbeitsspeicher verwendet Dieser Arbeitsspeicher muss je gleichzeitiger Session auf dem Server bereitgestellt werden die Default-Einstellung mit 3 Partitionen a 256 KB + dem aktiven Puffer erfordern 1 MB RAM je aktiven Anwender
Aktiv
er
Puffe
r
[001] Vorg
ecac
hter
Bl
ock
[002] Vorg
ecac
hter
Bl
ock
[003]
Aktiv
er P
uffe
r
[002] Vorg
ecac
hter
Bl
ock
[003] Vorg
ecac
hter
Bl
ock
[leer]
Release Notes BALVI Schnittstellenserver Seite 24 von 37
Gleichzeitig wurde die Moumlglichkeit geschaffen dass die maximale Anzahl an gleichzeitigen Exporten durch das Rechenzentrum eingeschraumlnkt werden kann um einem OutOfMemory-Fehler vorzubeugen Die Einstellung
ltEnvironment
name=partitionedExportmaxConcurrentExports
value=10 type=javalangInteger override=true
gt
muss entsprechend der zu erwartenden gleichzeitigen Zugriffe konzipiert werden ansonsten wird der Server einen Verbindungsversuch durch die Clients ablehnen
Beachten Sie dass die folgenden Einstellungen partitionedExportmaxBufferedPartitions partitionedExportmaxConcurrentExports und partitionedExportpartitionSize gemeinsam als Rechenbasis fuumlr den RAM-Bedarf des Webservers herangezogen werden muumlssen
Folgende Faustformel sollte fuumlr die Einrichtung verwendet werden
Min 256 MB (Serverbasis) + (11 partitionedExportmaxConcurrentExports partitionedExportmaxBufferedPartitions partitionedExportpartitionSize)
Beispiel 50 gleichzeitige Anwender Blockgroumlszlige 256 KB 4 Partitionen
256 MB + (11 50 256 4) KB = 312 MB fuumlr die JVM
Empf 512 MB (Serverbasis) + (12 partitionedExportmaxConcurrentExports partitionedExportmaxBufferedPartitions partitionedExportpartitionSize)
Beispiel 50 gleichzeitige Anwender Blockgroumlszlige 256 KB 4 Partitionen
512 MB + (12 50 256 4) KB = 572 MB fuumlr die JVM
partitionedExportmaxConcurrentExports
Bestimmt die Anzahl der maximalen Export Tasks (Threads) die fuumlr partitionierte Exporte bereitgestellt werden Wenn die Anzahl uumlberschritten wird wird die entsprechende Exportanfrage abgewiesen und der Client muss zu einem spaumlteren Zeitpunkt erneut anfragen Stellen Sie diesen Wert entsprechend der zu erwartenden Benutzeranzahl ein bei 50 Anwendern also 50
Exporte oumlffnen auf der Datenbank entsprechend zur Ausfuumlhrungszeit min einen Cursor ggf fuumlr rekursive Unterabfragen kurzfristig sogar mehr Die hier eingestellte Anzahl muss mit der Anzahl von maxActive korrelieren
ltEnvironment
name=partitionedExportmaxConcurrentExports
value=10 type=javalangInteger override=true
gt
partitionedExportmaxBufferedPartitions
Bestimmt die Anzahl der Datenbloumlcke (Partitionen) die vom Server bei Abruf eines Exportes gepuffert werden Die seit Version 24 eingefuumlhrte FIFO-Puffer-Logik ermoumlglicht dass der Server schon die Ergebnisse vorpuffert so dass der Client weniger Wartezeiten bei der Anfrage nach Daten hat Diese
Release Notes BALVI Schnittstellenserver Seite 25 von 37
Puffer-Logik unterteilt den Exportdatenstrom (je Export) in mehre Bloumlcke Der Client kann nun den letzten Block neu anfordern oder den naumlchsten Block wenn der letzte Block erfolgreich verarbeitet wurde Wie viele naumlchste Bloumlcke durch den Server bereit gestellt werden entscheidet diese Einstellung Sobald kein naumlchster Block mehr bereit gestellt werden muss wird der Datenbank-Cursor geschlossen eine Erhoumlhung kann also zu einer Entlastung der aktiven DB-Verbindungen fuumlhren erhoumlht jedoch den Bedarf an RAM des Servers
Der von BALVI voreingestellte Wert ist 3
ltEnvironment
name=partitionedExportmaxBufferedPartitions
value=3 type=javalangInteger override=true
gt
partitionedExportpartitionSizeldquo
Die Groumlszlige der Datenbloumlcke (Partitionen) die an den Client uumlbermittelt werden in Bytes Wenn Sie diesen Wert zu niedrig einstellen reduziert sich die Effizienz des Caches da der Client mehr Datenbloumlcke hintereinander abrufen muss Waumlhlen Sie einen zu groszligen Wert wird die neu zu uumlbertragende Datenmenge im Fall eines Fehlers houmlher
Der von BALVI voreingestellte Wert ist 256000 (256 KB)
ltEnvironment
name=partitionedExportpartitionSize
value=256000 type=javalangInteger override=true
gt
exportTokensmaxTokenCount
Maximale Anzahl der gleichzeitig vergebenen Token die vom Server gecached werden Jede Sitzung welche einen Export durchfuumlhrt erhaumllt einen Session-Token
Wenn eine Sitzung laumlngere Zeit nicht verwendet wurde wird dieser Session-Token wieder entfernt Wenn Sie den Wert zu niedrig einstellen fuumlhrt das zu einer generellen Session-Begrenzung auch fuumlr den nicht partitionierten Export-Modus welcher ab Version 21 verfuumlgbar ist
Ist die Anzahl der Tokens houmlher als die Datenbankeinstellung maxActive kann es vorkommen dass zwar eine Session gestartet werden kann jedoch kein Datenexport zustande kommt
Der von BALVI voreingestellte Wert ist 2000
ltEnvironment
name=exportTokensmaxTokenCount
value=20 type=javalangInteger override=true
gt
exportTokenstokenExpirationInSeconds
Zeit in Sekunden die verstreichen muss bis ein Token unguumlltig wird falls darauf kein Zugriff mehr erfolgt Nach einem erfolgreichen Export wird der Token automatisch geschlossen diese Option ist fuumlr den Abbruchfall vorgesehen Der von BALVI voreingestellte Wert ist 180 (180 s = 3 min)
Release Notes BALVI Schnittstellenserver Seite 26 von 37
ltEnvironment
name=exportTokenstokenExpirationInSeconds
value=180 type=javalangInteger override=true
gt
exportTokenstokenDisposalInSeconds
Zeit in Sekunden die verstreichen muss bis ein Token das erfolgreich abgearbeitet wurde aus dem Cache geloumlscht wird Um sicher zu stellen dass der letzte Exportblock noch erfolgreich abgerufen werden kann bleibt der Token auch nach Fertigmeldung des Clients noch N Sek guumlltig
Der von BALVI voreingestellte Wert ist 60 (60 s = 1 min)
ltEnvironment
name=exportTokenstokenDisposalInSeconds
value=60 type=javalangInteger override=true
gt
2516 Job-Verwaltung fuumlr den BSS konfigurieren Aktivierung der Jobverwaltung
Bis zur Version 28 des BSS gab es den Parameter bdquoavailableServicesldquo Dieser konnte bei Bedarf aktiviert werden wenn die Jobs benoumltigt wurden
Mit Version 30 ist die Einstellung bdquoavailableServicesldquo zu entfernen und kann durch den neuen optionalen Parameter bdquoisJobServiceEnabledldquo in der Datei bdquocontextxmlldquo ersetzt werden
lt-- Neue Parameter zur Aktivierung des Job Service Ersatz fuumlr availableServices --gt
ltEnvironment
name=isJobServiceEnabled
value=true
type=javalangBoolean
override=true
gt
Ab BSS 30 wird die Jobs-Engine standardmaumlszligig aktiviert Sollte die Jobs-Engine nicht benoumltigt werden muss bdquovalueldquo der Wert bdquofalseldquo zugewiesen werden Wird bdquoisJobServiceEnabledldquo nicht eingefuumlgt sind die Jobs trotzdem standardmaumlszligig aktiv
Nach dem Neustart des Servers und erneutem Einloggen erscheint nun zusaumltzlich der Menuumlpunkt bdquoJobsldquo
bdquopasswordKeyldquo fuumlr Jobs
In der Job-Logik wird ein von BALVI definierter Standard-Schluumlssel fuumlr die Ablagen von schuumltzenswerten Daten z B Passwoumlrtern verwendet Diese Einstellung ermoumlglicht den BALVI-Standard zu uumlberschreiben Wenn Sie diese Einstellung aumlndern muumlssen jedoch alle bislang verschluumlsselten Job-Parameter neu verschluumlsselt werden
ltEnvironment
name=javacompenvjobspasswordKey
value=MeinHochsicheresNeuesPasswort
type=javalangString
Release Notes BALVI Schnittstellenserver Seite 27 von 37
override=true
gt
bdquoJob ID enableddisabledldquo (Deprecated ersetzt ab 28 durch das bdquoBindenldquo von Jobs)
Sondereinstellungen fuumlr die Job-Verwaltung Da alle Jobs in einer Datenbank administriert werden jedoch ggf verteilt auf mehreren Tomcat-Servern ausgefuumlhrt werden sollen besteht hier die Option Jobs fuumlr die aktuelle Tomcat-Instanz separat zu deaktivieren
Die Einstellung ID koumlnnte z B folgendermaszligen aussehen javacompenvjobsC0DB58D8D52C4BBC966D1DC788A4EF8Benabled
Fuumlr weitere Fragen zu dieser Einstellung kontaktieren Sie bitte die BALVI GmbH
ltEnvironment
name=javacompenvjobsIDenabled
value=false
type=javalangBoolean
override=true
gt
2517 Weitere optionale Parameter
Es ist fuumlr diverse einzelne Schnittstellen ggf erforderlich Einstellungen in der Datei bdquocontextxmlldquo zu ergaumlnzen Hinweise zu diesen Parametern sind dann in dem der Schnittstelle beiliegenden Dokument enthalten Das gilt z B fuumlr die Schnittstelle bdquoXGewerbeanzeigenldquo
26 Logging mit logback Das Logging wurde komplett uumlberarbeitet Statt bdquoLog4Jldquo wird jetzt bdquologbackldquo4 benutzt Ab BSS 30 ist es zwingend notwendig die Einstellung vorzunehmen um das Logging der Anwendung zu steuern
Migration Ergaumlnzen Sie die neue Einstellung bdquologgingconfigldquo
lt-- Neue Paramter zur Angabe der Logback Config Ersatz fuumlr log4jConfigLocation --gt
ltEnvironment
name=loggingconfig
value=$catalinabaseconflogback-bssxml
type=javalangString
override=true
gt
Nach wie vor steht es Ihnen frei die Logging-Konfiguration eigenstaumlndig anzupassen
Wenn Sie jedoch dieselbe WAR in einer Tomcat-Instanz unter mehreren Context-Namen betreiben wuumlrden beide dieselbe Logging-Konfiguration verwenden so dass alle Protokolleintraumlge in einer Log-Datei aus
4 httplogbackqoschmanualappendershtml
Release Notes BALVI Schnittstellenserver Seite 28 von 37
mehreren Webanwendungen generiert werden Aumlndern Sie den Namen der Logging-Konfiguration entsprechend ab um fuumlr jede Anwendung eine spezifische Logging-Einstellung vornehmen zu koumlnnen
27 Tocmat Optional Suche im bdquoKlassenpfadldquo um den
Ordner bdquoconfldquo erweitern Die Suche nach Dateien uumlber bdquoclasspathldquo setzt voraus dass die Ordner- und Dateinamen im Apache Tomcat bekannt gegeben werden Der Klassenpfad kann in der Datei bdquocatalinapropertiesldquo angepasst werden Wenn Sie dort unter commonloader die folgenden Werte ergaumlnzen kann eine Datei auch im Ordner conf abgelegt werden damit Apache Tomcat diese findet Ansonsten muss die Datei im Ordner lib abgelegt werden
commonloader=$catalinabaseconf$catalinahomeconf
3 Die neue Browser-Oberflaumlche Der BALVI Schnittstellenserver hat seit Version 25 neben der Protokollierung auch die Moumlglichkeit Job-Konfigurationen zu pflegen Der Login ist nur fuumlr einen in BALVI iP eingetragenen ADMIN (z B Benutzer bdquoSYSTEMADMINldquo) mit dem in BALVI iP hinterlegten Passwort moumlglich Zur Anmeldung muss immer [SYSTEMBenutzername] im Feld Benutzer angegeben werden ansonsten schlaumlgt die Anmeldung fehl Bitte achten Sie darauf dass der bdquoldquo (Slash) und nicht der bdquoldquo (Backslash) verwendet werden muss
31 Server-Protokoll Um das Server-Protokoll anzuzeigen waumlhlen Sie den entsprechenden Menuumlpunkt Dort haben Sie seit BSS 26 die Moumlglichkeit uumlber alle Spalten der Protokolle nach Informationen zu suchen
Seit BSS 31 gibt es die Moumlglichkeit Verfahren in bdquoKopfsaumltzeldquo und bdquoDetailsaumltzeldquo zu unterteilen Wurde das Verfahren entsprechend konfiguriert (wie z B bei der Schnittstelle bdquoXGewerbeanzeigenldquo) dann wird im Protokoll-Kopfsatz nur der Start und das Ende der Ausfuumlhrung in der Liste angezeigt Erst bei einem Klick auf bdquoInformationenldquo wird die Liste aller Detailsaumltze angezeigt die im Durchlauf erzeugt wurden
Release Notes BALVI Schnittstellenserver Seite 29 von 37
Verfahren
Die Liste der verfuumlgbaren Verfahren die bei Ihnen im System installiert sind ZB
BEFUNDEhellip Schnittstelle Befunde LM FM oder TS
PROBEhellip Schnittstelle zum Export von Proben an Labore ebenfalls Spezifisch fuumlr einzelne Fachbereiche
MOBILXT Protokolle der BALVI Mobil XT Synchronisation
WEB Allgemeine nicht spezifizierte Protokolle hierunter ist bislang auch die eFi-Protokollierung zu finden
WEB_I0802 Protokolle zur Schnittstelle BALVI iP LIMS (Lebensmittelproben)
XGEWERBE Schnittstelle XGewerbeanzeigen
Klicken Sie auf die Schaltflaumlche so besteht bei den neuen Protokolldatensaumltzen die Moumlglichkeit Detail-Informationen zum Protokollsatz zu erhalten
Release Notes BALVI Schnittstellenserver Seite 30 von 37
Seit BSS 30x ist die Anzeige der Protokolle ebenfalls farblich abgesetzt so dass Protokolleintraumlge mit Fehlern hellrot und Warnungen hellgelb hinterlegt werden
32 Jobs Mit einem Klick auf den Menuumlpunkt Jobs rufen Sie die Oberflaumlche fuumlr die Job-Konfiguration auf Daraufhin werden alle Jobs aufgelistet die fuumlr den BSS freigegeben sind Hier koumlnnen Sie Einstellungen an den Jobs vornehmen und die Jobs aktivieren bzw deaktivieren Die Beschreibungen bzw Einstellungsmoumlglichkeiten fuumlr den jeweiligen SST-Job sind nicht Bestandteil dieser Dokumentation
33 Log-Ausgaben Uumlber den Menuumlpunkt Log-Ausgaben koumlnnen Sie die Ausgabe der Protokolleintraumlge in Echtzeit beobachten
Release Notes BALVI Schnittstellenserver Seite 31 von 37
Starten Sie die Echtzeit-Protokollierung indem Sie auf die Schaltflaumlche mit dem Symbol bdquoPlayldquo (Dreieck) klicken unterbrechen Sie die Ausgabe indem Sie die auf Schaltflaumlche mit dem Symbol bdquoPauseldquo (zwei Balken) klicken
Klicken Sie auf die Schaltflaumlche bdquoAktualisierenldquo (zwei Pfeile) um die neuesten Protokolleintraumlge angezeigt zu bekommen
Klicken Sie auf das Symbol mit dem Papierkorb um die letzten Protokollmeldungen in der Anzeige zu loumlschen
Die Daten in den Protokolldateien auf der Festplatte des Servers sind davon nicht betroffen
Uumlber das Symbol bdquoLogging anpassenldquo (Schraubenschluumlssel) koumlnnen Sie die Ausgabe der Daten im Echtzeitfenster und in den Protokolldateien aumlndern jedoch ist diese Einstellung nur temporaumlr Die Standardeinstellungen koumlnnen ausschlieszliglich uumlber die Anpassung der Datei bdquologback-bssxmlldquo im Konfigurationsverzeichnis des Servers selbst geaumlndert werden
Release Notes BALVI Schnittstellenserver Seite 32 von 37
In der Logging-Parameter Konfiguration koumlnnen Sie verschiedene Parameter einstellen und uumlber die Schaltflaumlche bdquoAnwendenldquo dann sofort im Echtzeitprotokoll sehen Welche Einstellungen moumlglich sind erfahren Sie wenn es eine akute Fehlersituation gibt die detailliertere Ausgaben im Protokoll erfordert
Warnung Wenn Sie den Log-Level fuumlr ROOT oder eine andere Klasse auf TRACE einstellen werden sehr viele Protokollausgaben generiert die auch dazu fuumlhren koumlnnen dass der Server sehr langsam wird oder die Festplatte des Servers zulaumluft wenn fuumlr das Logging kein Dateilimit konfiguriert wurde
34 LogoutAbmeldung vom System Zum Abmelden waumlhlen Sie oben rechts das Kontextmenuuml
35 Cache loumlschen Der Cache wird in der Regel automatisch geloumlscht Wenn Sie jedoch gerade in BALVI iP eine Aumlnderung an den Schnittstellen eingespielt haben und moumlchten dass diese sofort wirksam wird kann die Funktion bdquoCache loumlschenldquo dazu verwendet werden dass der BALVI Schnittstellenserver die Einstellungen bei der naumlchsten Anfrage neu einliest
Release Notes BALVI Schnittstellenserver Seite 33 von 37
Release Notes BALVI Schnittstellenserver Seite 34 von 37
4 Einrichtung in BALVI iP Um die Verfahren fuumlr den BALVI Schnittstellenserver fuumlr Anwender freizuschalten wird das Objekt bdquoSystemeinstellungenldquo oder bdquoMandanten- und Benutzereinstellungenldquo verwendet Die Anpassung ist je Verfahren moumlglich so kann in BALVI iP fuumlr den Zugriff durch den BALVI Schnittstellenserver ein Benutzer bdquoAldquo am Verfahren bdquoMobilldquo berechtigt werden ein Benutzer bdquoBldquo nur am Verfahren bdquoSLA_FLESHldquo usw Die Logik ist jedoch einheitlich Je Verfahren wird durch BALVI eine Verfahrensgruppe mit dem Verfahrensnamen angelegt und mit den entsprechenden Einstellungen vorkonfiguriert welche durch das Verfahren erforderlich sind Dabei kann die Komplexitaumlt der Einstellungen variieren wie z B an den zu Version 23 verfuumlgbaren Verfahren bdquoMobilldquo und bdquoSLA_Fleshldquo ersichtlich wird
Im Verfahren BALVI Mobil sind diverse Anpassungen moumlglich welche je Bundesland oder eingesetzter Import- und Export-Variante durch den BALVI Schnittstellenserver bei der Bearbeitung von Anfragen gepruumlft werden siehe Punkt 3 Abb Mobil-Einstellung in BALVI iP
Abb Mobil-Einstellung in BALVI iP
Alle Verfahren verwenden jedoch die regulaumlre Benutzerverwaltung von BALVI iP Ein Benutzer ohne Passwort gilt fuumlr BALVI iP als gesperrt was fuumlr das Login bedeutet dass der Anwender sich nur uumlber die Active-Directory-Authentifizierung anmelden kann Ist das nicht moumlglich (bzw nicht konfiguriert) kann der Anwender sich weder in BALVI iP noch uumlber die Webservice-Schnittstelle authentifizieren
Fuumlr Dienste-Schnittstellen welche keine persoumlnliche Authentifizierung durch einen Anwender erfordern wird empfohlen einen separaten Benutzer in der Benutzerverwaltung anzulegen und ein sicheres Kennwort zu vergeben Das Anlegen von zusaumltzlichen Benutzern gilt nicht fuumlr BALVI mobil XT da beim Holen und Uumlbermitteln von Daten jeder Benutzer auch ein fachlich konfigurierter Anwender innerhalb von BALVI iP ist und die Anwendungsoberflaumlche ebenfalls zur Erfassung von Daten verwendet
Unter Punkt 2 der Abb Mobil-Einstellung in BALVI iP wird ein modales Fenster geoumlffnet (Abb BALVI mobil Benutzerverwaltung) Innerhalb dieses modalen Fensters werden mandantenweise die Benutzer fuumlr BALVI
Release Notes BALVI Schnittstellenserver Seite 35 von 37
mobil und den jeweiligen Fachbereich festgelegt Dabei ist es wichtig dass man die Haken bdquoAktiv fuumlr hellipldquo bei bdquohellip mobilldquo und bei einem Fachbereich (bdquohellip LMldquo bdquohellip FMldquo usw) setzt weil sonst uumlber den BALVI Schnittstellenserver keine Kommunikation mit BALVI iP moumlglich ist
Abb BALVI mobil Benutzerverwaltung
Alternativ zur Passwort-Authentifizierung wird wie beschrieben auch die Active-Directory-Authentifizierung angeboten Dazu muss der BALVI iP-Anwender uumlber die Schaltflaumlche bdquoDomaumlnen-Benutzer zuordnenldquo mit dem Active Directory verknuumlpft werden
Nur wenn die Active-Directory-Konfigurationen in BALVI iP und im BALVI Schnittstellenserver auf dieselbe Domaumlne verweisen sind die Domaumlnen-Zuordnung und die Active-Directory-Authentifizierung (z B uumlber BALVI mobil XT) moumlglich
Release Notes BALVI Schnittstellenserver Seite 36 von 37
5 Bekannte Probleme und Loumlsungen
51 ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner Bei der Job-Bearbeitung tritt folgender Fehler auf ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner
Behebung
Fuumlhren Sie das beiliegende IP-Patch (UPDATEexe) aus bevor Sie das WAR austauschen
52 Server startet nicht Sie finden folgende Zeilen im Protokoll (catalinaout oder bsslog)
ERROR [localhost-startStop-1] [IdentityServiceImpl] serverID must not be empty
ERROR [localhost-startStop-1] [ContextLoader] Context initialization failed
Behebung
Setzen Sie die Umgebungsvariable ldquoserverIDrdquo in der Datei bdquocontextxmlldquo
53 ORA-00942 table or view does not exist In vielen Faumlllen wird der Fehler ldquoTabelle oder View nicht vorhandenrdquo ausgeworfen (Java-Protokoll im Ordner logs von Apache Tomcat) wenn eine neue Schnittstelle eingerichtet oder ein neues BALVI iP Release bzw Update eingespielt wurde ohne anschlieszligend das aktuelle GRANT-Skript auszufuumlhren
Behebung
Fuumlhren Sie das GRANT-Skript erneut aus
54 ORA-0406x bdquoBestehender Paketstatus wurde aufgehobenldquo
ORA-04061 Bestehender Status von package body ABCXYZ wurde annulliert
ORA-04065 Ausfuumlhrung nicht erfolgreich package body ABCXYZ wurde geaumlndert oder geloumlscht
Release Notes BALVI Schnittstellenserver Seite 37 von 37
Der Fehler tritt haumlufig ein nachdem die UPDATEexe ausgefuumlhrt und in der Ausfuumlhrungsliste ein Package aktualisiert wurde Oracle merkt sich je User-Session bestimmte Werte im Package wenn der Anwender es verwendet hat Durch einen bdquoCREATE OR REPLACE PACKAGEldquo-Befehl kann dieser Status temporaumlr aufgehoben werden Normalerweise tritt dieser Fehler nach dem Update genau einmal in jeder aktiven Session auf wenn der BSS nicht neu gestartet wird
Behebung
Starten Sie nach jedem Update den BSS neu um alle laufenden Sessions zu beenden
55 Jobs sind nicht ausfuumlhrbar
1 Ein Job wird mit dem Status bdquoNicht unterstuumltztldquo angezeigt wenn fuumlr seine Ausfuumlhrung eine houmlhere Version des BSS erforderlich ist
2 Nach dem Klonen der Datenbank von der Produktions- auf die Testumgebung erhalten alle Jobs automatisch den Status bdquoDeaktiviertldquo wenn die bdquoserverIDldquo nicht identisch ist
Beide Statusaumlnderungen sind gewollt Damit soll verhindert werden dass Jobs nach einem Serverneustart oder nach einem Update automatisch starten und dabei Fehler verursachen
Um Jobs mit dem Status bdquoNicht unterstuumltztldquo nutzen und konfigurieren zu koumlnnen ist es erforderlich den BALVI Schnittstellenserver zu aktualisieren
Deaktivierte Jobs koumlnnen Sie aktivieren indem Sie den jeweiligen Job an den aktuellen Server binden und den Haken bei bdquoAktivldquo setzen
Release Notes BALVI Schnittstellenserver Seite 24 von 37
Gleichzeitig wurde die Moumlglichkeit geschaffen dass die maximale Anzahl an gleichzeitigen Exporten durch das Rechenzentrum eingeschraumlnkt werden kann um einem OutOfMemory-Fehler vorzubeugen Die Einstellung
ltEnvironment
name=partitionedExportmaxConcurrentExports
value=10 type=javalangInteger override=true
gt
muss entsprechend der zu erwartenden gleichzeitigen Zugriffe konzipiert werden ansonsten wird der Server einen Verbindungsversuch durch die Clients ablehnen
Beachten Sie dass die folgenden Einstellungen partitionedExportmaxBufferedPartitions partitionedExportmaxConcurrentExports und partitionedExportpartitionSize gemeinsam als Rechenbasis fuumlr den RAM-Bedarf des Webservers herangezogen werden muumlssen
Folgende Faustformel sollte fuumlr die Einrichtung verwendet werden
Min 256 MB (Serverbasis) + (11 partitionedExportmaxConcurrentExports partitionedExportmaxBufferedPartitions partitionedExportpartitionSize)
Beispiel 50 gleichzeitige Anwender Blockgroumlszlige 256 KB 4 Partitionen
256 MB + (11 50 256 4) KB = 312 MB fuumlr die JVM
Empf 512 MB (Serverbasis) + (12 partitionedExportmaxConcurrentExports partitionedExportmaxBufferedPartitions partitionedExportpartitionSize)
Beispiel 50 gleichzeitige Anwender Blockgroumlszlige 256 KB 4 Partitionen
512 MB + (12 50 256 4) KB = 572 MB fuumlr die JVM
partitionedExportmaxConcurrentExports
Bestimmt die Anzahl der maximalen Export Tasks (Threads) die fuumlr partitionierte Exporte bereitgestellt werden Wenn die Anzahl uumlberschritten wird wird die entsprechende Exportanfrage abgewiesen und der Client muss zu einem spaumlteren Zeitpunkt erneut anfragen Stellen Sie diesen Wert entsprechend der zu erwartenden Benutzeranzahl ein bei 50 Anwendern also 50
Exporte oumlffnen auf der Datenbank entsprechend zur Ausfuumlhrungszeit min einen Cursor ggf fuumlr rekursive Unterabfragen kurzfristig sogar mehr Die hier eingestellte Anzahl muss mit der Anzahl von maxActive korrelieren
ltEnvironment
name=partitionedExportmaxConcurrentExports
value=10 type=javalangInteger override=true
gt
partitionedExportmaxBufferedPartitions
Bestimmt die Anzahl der Datenbloumlcke (Partitionen) die vom Server bei Abruf eines Exportes gepuffert werden Die seit Version 24 eingefuumlhrte FIFO-Puffer-Logik ermoumlglicht dass der Server schon die Ergebnisse vorpuffert so dass der Client weniger Wartezeiten bei der Anfrage nach Daten hat Diese
Release Notes BALVI Schnittstellenserver Seite 25 von 37
Puffer-Logik unterteilt den Exportdatenstrom (je Export) in mehre Bloumlcke Der Client kann nun den letzten Block neu anfordern oder den naumlchsten Block wenn der letzte Block erfolgreich verarbeitet wurde Wie viele naumlchste Bloumlcke durch den Server bereit gestellt werden entscheidet diese Einstellung Sobald kein naumlchster Block mehr bereit gestellt werden muss wird der Datenbank-Cursor geschlossen eine Erhoumlhung kann also zu einer Entlastung der aktiven DB-Verbindungen fuumlhren erhoumlht jedoch den Bedarf an RAM des Servers
Der von BALVI voreingestellte Wert ist 3
ltEnvironment
name=partitionedExportmaxBufferedPartitions
value=3 type=javalangInteger override=true
gt
partitionedExportpartitionSizeldquo
Die Groumlszlige der Datenbloumlcke (Partitionen) die an den Client uumlbermittelt werden in Bytes Wenn Sie diesen Wert zu niedrig einstellen reduziert sich die Effizienz des Caches da der Client mehr Datenbloumlcke hintereinander abrufen muss Waumlhlen Sie einen zu groszligen Wert wird die neu zu uumlbertragende Datenmenge im Fall eines Fehlers houmlher
Der von BALVI voreingestellte Wert ist 256000 (256 KB)
ltEnvironment
name=partitionedExportpartitionSize
value=256000 type=javalangInteger override=true
gt
exportTokensmaxTokenCount
Maximale Anzahl der gleichzeitig vergebenen Token die vom Server gecached werden Jede Sitzung welche einen Export durchfuumlhrt erhaumllt einen Session-Token
Wenn eine Sitzung laumlngere Zeit nicht verwendet wurde wird dieser Session-Token wieder entfernt Wenn Sie den Wert zu niedrig einstellen fuumlhrt das zu einer generellen Session-Begrenzung auch fuumlr den nicht partitionierten Export-Modus welcher ab Version 21 verfuumlgbar ist
Ist die Anzahl der Tokens houmlher als die Datenbankeinstellung maxActive kann es vorkommen dass zwar eine Session gestartet werden kann jedoch kein Datenexport zustande kommt
Der von BALVI voreingestellte Wert ist 2000
ltEnvironment
name=exportTokensmaxTokenCount
value=20 type=javalangInteger override=true
gt
exportTokenstokenExpirationInSeconds
Zeit in Sekunden die verstreichen muss bis ein Token unguumlltig wird falls darauf kein Zugriff mehr erfolgt Nach einem erfolgreichen Export wird der Token automatisch geschlossen diese Option ist fuumlr den Abbruchfall vorgesehen Der von BALVI voreingestellte Wert ist 180 (180 s = 3 min)
Release Notes BALVI Schnittstellenserver Seite 26 von 37
ltEnvironment
name=exportTokenstokenExpirationInSeconds
value=180 type=javalangInteger override=true
gt
exportTokenstokenDisposalInSeconds
Zeit in Sekunden die verstreichen muss bis ein Token das erfolgreich abgearbeitet wurde aus dem Cache geloumlscht wird Um sicher zu stellen dass der letzte Exportblock noch erfolgreich abgerufen werden kann bleibt der Token auch nach Fertigmeldung des Clients noch N Sek guumlltig
Der von BALVI voreingestellte Wert ist 60 (60 s = 1 min)
ltEnvironment
name=exportTokenstokenDisposalInSeconds
value=60 type=javalangInteger override=true
gt
2516 Job-Verwaltung fuumlr den BSS konfigurieren Aktivierung der Jobverwaltung
Bis zur Version 28 des BSS gab es den Parameter bdquoavailableServicesldquo Dieser konnte bei Bedarf aktiviert werden wenn die Jobs benoumltigt wurden
Mit Version 30 ist die Einstellung bdquoavailableServicesldquo zu entfernen und kann durch den neuen optionalen Parameter bdquoisJobServiceEnabledldquo in der Datei bdquocontextxmlldquo ersetzt werden
lt-- Neue Parameter zur Aktivierung des Job Service Ersatz fuumlr availableServices --gt
ltEnvironment
name=isJobServiceEnabled
value=true
type=javalangBoolean
override=true
gt
Ab BSS 30 wird die Jobs-Engine standardmaumlszligig aktiviert Sollte die Jobs-Engine nicht benoumltigt werden muss bdquovalueldquo der Wert bdquofalseldquo zugewiesen werden Wird bdquoisJobServiceEnabledldquo nicht eingefuumlgt sind die Jobs trotzdem standardmaumlszligig aktiv
Nach dem Neustart des Servers und erneutem Einloggen erscheint nun zusaumltzlich der Menuumlpunkt bdquoJobsldquo
bdquopasswordKeyldquo fuumlr Jobs
In der Job-Logik wird ein von BALVI definierter Standard-Schluumlssel fuumlr die Ablagen von schuumltzenswerten Daten z B Passwoumlrtern verwendet Diese Einstellung ermoumlglicht den BALVI-Standard zu uumlberschreiben Wenn Sie diese Einstellung aumlndern muumlssen jedoch alle bislang verschluumlsselten Job-Parameter neu verschluumlsselt werden
ltEnvironment
name=javacompenvjobspasswordKey
value=MeinHochsicheresNeuesPasswort
type=javalangString
Release Notes BALVI Schnittstellenserver Seite 27 von 37
override=true
gt
bdquoJob ID enableddisabledldquo (Deprecated ersetzt ab 28 durch das bdquoBindenldquo von Jobs)
Sondereinstellungen fuumlr die Job-Verwaltung Da alle Jobs in einer Datenbank administriert werden jedoch ggf verteilt auf mehreren Tomcat-Servern ausgefuumlhrt werden sollen besteht hier die Option Jobs fuumlr die aktuelle Tomcat-Instanz separat zu deaktivieren
Die Einstellung ID koumlnnte z B folgendermaszligen aussehen javacompenvjobsC0DB58D8D52C4BBC966D1DC788A4EF8Benabled
Fuumlr weitere Fragen zu dieser Einstellung kontaktieren Sie bitte die BALVI GmbH
ltEnvironment
name=javacompenvjobsIDenabled
value=false
type=javalangBoolean
override=true
gt
2517 Weitere optionale Parameter
Es ist fuumlr diverse einzelne Schnittstellen ggf erforderlich Einstellungen in der Datei bdquocontextxmlldquo zu ergaumlnzen Hinweise zu diesen Parametern sind dann in dem der Schnittstelle beiliegenden Dokument enthalten Das gilt z B fuumlr die Schnittstelle bdquoXGewerbeanzeigenldquo
26 Logging mit logback Das Logging wurde komplett uumlberarbeitet Statt bdquoLog4Jldquo wird jetzt bdquologbackldquo4 benutzt Ab BSS 30 ist es zwingend notwendig die Einstellung vorzunehmen um das Logging der Anwendung zu steuern
Migration Ergaumlnzen Sie die neue Einstellung bdquologgingconfigldquo
lt-- Neue Paramter zur Angabe der Logback Config Ersatz fuumlr log4jConfigLocation --gt
ltEnvironment
name=loggingconfig
value=$catalinabaseconflogback-bssxml
type=javalangString
override=true
gt
Nach wie vor steht es Ihnen frei die Logging-Konfiguration eigenstaumlndig anzupassen
Wenn Sie jedoch dieselbe WAR in einer Tomcat-Instanz unter mehreren Context-Namen betreiben wuumlrden beide dieselbe Logging-Konfiguration verwenden so dass alle Protokolleintraumlge in einer Log-Datei aus
4 httplogbackqoschmanualappendershtml
Release Notes BALVI Schnittstellenserver Seite 28 von 37
mehreren Webanwendungen generiert werden Aumlndern Sie den Namen der Logging-Konfiguration entsprechend ab um fuumlr jede Anwendung eine spezifische Logging-Einstellung vornehmen zu koumlnnen
27 Tocmat Optional Suche im bdquoKlassenpfadldquo um den
Ordner bdquoconfldquo erweitern Die Suche nach Dateien uumlber bdquoclasspathldquo setzt voraus dass die Ordner- und Dateinamen im Apache Tomcat bekannt gegeben werden Der Klassenpfad kann in der Datei bdquocatalinapropertiesldquo angepasst werden Wenn Sie dort unter commonloader die folgenden Werte ergaumlnzen kann eine Datei auch im Ordner conf abgelegt werden damit Apache Tomcat diese findet Ansonsten muss die Datei im Ordner lib abgelegt werden
commonloader=$catalinabaseconf$catalinahomeconf
3 Die neue Browser-Oberflaumlche Der BALVI Schnittstellenserver hat seit Version 25 neben der Protokollierung auch die Moumlglichkeit Job-Konfigurationen zu pflegen Der Login ist nur fuumlr einen in BALVI iP eingetragenen ADMIN (z B Benutzer bdquoSYSTEMADMINldquo) mit dem in BALVI iP hinterlegten Passwort moumlglich Zur Anmeldung muss immer [SYSTEMBenutzername] im Feld Benutzer angegeben werden ansonsten schlaumlgt die Anmeldung fehl Bitte achten Sie darauf dass der bdquoldquo (Slash) und nicht der bdquoldquo (Backslash) verwendet werden muss
31 Server-Protokoll Um das Server-Protokoll anzuzeigen waumlhlen Sie den entsprechenden Menuumlpunkt Dort haben Sie seit BSS 26 die Moumlglichkeit uumlber alle Spalten der Protokolle nach Informationen zu suchen
Seit BSS 31 gibt es die Moumlglichkeit Verfahren in bdquoKopfsaumltzeldquo und bdquoDetailsaumltzeldquo zu unterteilen Wurde das Verfahren entsprechend konfiguriert (wie z B bei der Schnittstelle bdquoXGewerbeanzeigenldquo) dann wird im Protokoll-Kopfsatz nur der Start und das Ende der Ausfuumlhrung in der Liste angezeigt Erst bei einem Klick auf bdquoInformationenldquo wird die Liste aller Detailsaumltze angezeigt die im Durchlauf erzeugt wurden
Release Notes BALVI Schnittstellenserver Seite 29 von 37
Verfahren
Die Liste der verfuumlgbaren Verfahren die bei Ihnen im System installiert sind ZB
BEFUNDEhellip Schnittstelle Befunde LM FM oder TS
PROBEhellip Schnittstelle zum Export von Proben an Labore ebenfalls Spezifisch fuumlr einzelne Fachbereiche
MOBILXT Protokolle der BALVI Mobil XT Synchronisation
WEB Allgemeine nicht spezifizierte Protokolle hierunter ist bislang auch die eFi-Protokollierung zu finden
WEB_I0802 Protokolle zur Schnittstelle BALVI iP LIMS (Lebensmittelproben)
XGEWERBE Schnittstelle XGewerbeanzeigen
Klicken Sie auf die Schaltflaumlche so besteht bei den neuen Protokolldatensaumltzen die Moumlglichkeit Detail-Informationen zum Protokollsatz zu erhalten
Release Notes BALVI Schnittstellenserver Seite 30 von 37
Seit BSS 30x ist die Anzeige der Protokolle ebenfalls farblich abgesetzt so dass Protokolleintraumlge mit Fehlern hellrot und Warnungen hellgelb hinterlegt werden
32 Jobs Mit einem Klick auf den Menuumlpunkt Jobs rufen Sie die Oberflaumlche fuumlr die Job-Konfiguration auf Daraufhin werden alle Jobs aufgelistet die fuumlr den BSS freigegeben sind Hier koumlnnen Sie Einstellungen an den Jobs vornehmen und die Jobs aktivieren bzw deaktivieren Die Beschreibungen bzw Einstellungsmoumlglichkeiten fuumlr den jeweiligen SST-Job sind nicht Bestandteil dieser Dokumentation
33 Log-Ausgaben Uumlber den Menuumlpunkt Log-Ausgaben koumlnnen Sie die Ausgabe der Protokolleintraumlge in Echtzeit beobachten
Release Notes BALVI Schnittstellenserver Seite 31 von 37
Starten Sie die Echtzeit-Protokollierung indem Sie auf die Schaltflaumlche mit dem Symbol bdquoPlayldquo (Dreieck) klicken unterbrechen Sie die Ausgabe indem Sie die auf Schaltflaumlche mit dem Symbol bdquoPauseldquo (zwei Balken) klicken
Klicken Sie auf die Schaltflaumlche bdquoAktualisierenldquo (zwei Pfeile) um die neuesten Protokolleintraumlge angezeigt zu bekommen
Klicken Sie auf das Symbol mit dem Papierkorb um die letzten Protokollmeldungen in der Anzeige zu loumlschen
Die Daten in den Protokolldateien auf der Festplatte des Servers sind davon nicht betroffen
Uumlber das Symbol bdquoLogging anpassenldquo (Schraubenschluumlssel) koumlnnen Sie die Ausgabe der Daten im Echtzeitfenster und in den Protokolldateien aumlndern jedoch ist diese Einstellung nur temporaumlr Die Standardeinstellungen koumlnnen ausschlieszliglich uumlber die Anpassung der Datei bdquologback-bssxmlldquo im Konfigurationsverzeichnis des Servers selbst geaumlndert werden
Release Notes BALVI Schnittstellenserver Seite 32 von 37
In der Logging-Parameter Konfiguration koumlnnen Sie verschiedene Parameter einstellen und uumlber die Schaltflaumlche bdquoAnwendenldquo dann sofort im Echtzeitprotokoll sehen Welche Einstellungen moumlglich sind erfahren Sie wenn es eine akute Fehlersituation gibt die detailliertere Ausgaben im Protokoll erfordert
Warnung Wenn Sie den Log-Level fuumlr ROOT oder eine andere Klasse auf TRACE einstellen werden sehr viele Protokollausgaben generiert die auch dazu fuumlhren koumlnnen dass der Server sehr langsam wird oder die Festplatte des Servers zulaumluft wenn fuumlr das Logging kein Dateilimit konfiguriert wurde
34 LogoutAbmeldung vom System Zum Abmelden waumlhlen Sie oben rechts das Kontextmenuuml
35 Cache loumlschen Der Cache wird in der Regel automatisch geloumlscht Wenn Sie jedoch gerade in BALVI iP eine Aumlnderung an den Schnittstellen eingespielt haben und moumlchten dass diese sofort wirksam wird kann die Funktion bdquoCache loumlschenldquo dazu verwendet werden dass der BALVI Schnittstellenserver die Einstellungen bei der naumlchsten Anfrage neu einliest
Release Notes BALVI Schnittstellenserver Seite 33 von 37
Release Notes BALVI Schnittstellenserver Seite 34 von 37
4 Einrichtung in BALVI iP Um die Verfahren fuumlr den BALVI Schnittstellenserver fuumlr Anwender freizuschalten wird das Objekt bdquoSystemeinstellungenldquo oder bdquoMandanten- und Benutzereinstellungenldquo verwendet Die Anpassung ist je Verfahren moumlglich so kann in BALVI iP fuumlr den Zugriff durch den BALVI Schnittstellenserver ein Benutzer bdquoAldquo am Verfahren bdquoMobilldquo berechtigt werden ein Benutzer bdquoBldquo nur am Verfahren bdquoSLA_FLESHldquo usw Die Logik ist jedoch einheitlich Je Verfahren wird durch BALVI eine Verfahrensgruppe mit dem Verfahrensnamen angelegt und mit den entsprechenden Einstellungen vorkonfiguriert welche durch das Verfahren erforderlich sind Dabei kann die Komplexitaumlt der Einstellungen variieren wie z B an den zu Version 23 verfuumlgbaren Verfahren bdquoMobilldquo und bdquoSLA_Fleshldquo ersichtlich wird
Im Verfahren BALVI Mobil sind diverse Anpassungen moumlglich welche je Bundesland oder eingesetzter Import- und Export-Variante durch den BALVI Schnittstellenserver bei der Bearbeitung von Anfragen gepruumlft werden siehe Punkt 3 Abb Mobil-Einstellung in BALVI iP
Abb Mobil-Einstellung in BALVI iP
Alle Verfahren verwenden jedoch die regulaumlre Benutzerverwaltung von BALVI iP Ein Benutzer ohne Passwort gilt fuumlr BALVI iP als gesperrt was fuumlr das Login bedeutet dass der Anwender sich nur uumlber die Active-Directory-Authentifizierung anmelden kann Ist das nicht moumlglich (bzw nicht konfiguriert) kann der Anwender sich weder in BALVI iP noch uumlber die Webservice-Schnittstelle authentifizieren
Fuumlr Dienste-Schnittstellen welche keine persoumlnliche Authentifizierung durch einen Anwender erfordern wird empfohlen einen separaten Benutzer in der Benutzerverwaltung anzulegen und ein sicheres Kennwort zu vergeben Das Anlegen von zusaumltzlichen Benutzern gilt nicht fuumlr BALVI mobil XT da beim Holen und Uumlbermitteln von Daten jeder Benutzer auch ein fachlich konfigurierter Anwender innerhalb von BALVI iP ist und die Anwendungsoberflaumlche ebenfalls zur Erfassung von Daten verwendet
Unter Punkt 2 der Abb Mobil-Einstellung in BALVI iP wird ein modales Fenster geoumlffnet (Abb BALVI mobil Benutzerverwaltung) Innerhalb dieses modalen Fensters werden mandantenweise die Benutzer fuumlr BALVI
Release Notes BALVI Schnittstellenserver Seite 35 von 37
mobil und den jeweiligen Fachbereich festgelegt Dabei ist es wichtig dass man die Haken bdquoAktiv fuumlr hellipldquo bei bdquohellip mobilldquo und bei einem Fachbereich (bdquohellip LMldquo bdquohellip FMldquo usw) setzt weil sonst uumlber den BALVI Schnittstellenserver keine Kommunikation mit BALVI iP moumlglich ist
Abb BALVI mobil Benutzerverwaltung
Alternativ zur Passwort-Authentifizierung wird wie beschrieben auch die Active-Directory-Authentifizierung angeboten Dazu muss der BALVI iP-Anwender uumlber die Schaltflaumlche bdquoDomaumlnen-Benutzer zuordnenldquo mit dem Active Directory verknuumlpft werden
Nur wenn die Active-Directory-Konfigurationen in BALVI iP und im BALVI Schnittstellenserver auf dieselbe Domaumlne verweisen sind die Domaumlnen-Zuordnung und die Active-Directory-Authentifizierung (z B uumlber BALVI mobil XT) moumlglich
Release Notes BALVI Schnittstellenserver Seite 36 von 37
5 Bekannte Probleme und Loumlsungen
51 ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner Bei der Job-Bearbeitung tritt folgender Fehler auf ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner
Behebung
Fuumlhren Sie das beiliegende IP-Patch (UPDATEexe) aus bevor Sie das WAR austauschen
52 Server startet nicht Sie finden folgende Zeilen im Protokoll (catalinaout oder bsslog)
ERROR [localhost-startStop-1] [IdentityServiceImpl] serverID must not be empty
ERROR [localhost-startStop-1] [ContextLoader] Context initialization failed
Behebung
Setzen Sie die Umgebungsvariable ldquoserverIDrdquo in der Datei bdquocontextxmlldquo
53 ORA-00942 table or view does not exist In vielen Faumlllen wird der Fehler ldquoTabelle oder View nicht vorhandenrdquo ausgeworfen (Java-Protokoll im Ordner logs von Apache Tomcat) wenn eine neue Schnittstelle eingerichtet oder ein neues BALVI iP Release bzw Update eingespielt wurde ohne anschlieszligend das aktuelle GRANT-Skript auszufuumlhren
Behebung
Fuumlhren Sie das GRANT-Skript erneut aus
54 ORA-0406x bdquoBestehender Paketstatus wurde aufgehobenldquo
ORA-04061 Bestehender Status von package body ABCXYZ wurde annulliert
ORA-04065 Ausfuumlhrung nicht erfolgreich package body ABCXYZ wurde geaumlndert oder geloumlscht
Release Notes BALVI Schnittstellenserver Seite 37 von 37
Der Fehler tritt haumlufig ein nachdem die UPDATEexe ausgefuumlhrt und in der Ausfuumlhrungsliste ein Package aktualisiert wurde Oracle merkt sich je User-Session bestimmte Werte im Package wenn der Anwender es verwendet hat Durch einen bdquoCREATE OR REPLACE PACKAGEldquo-Befehl kann dieser Status temporaumlr aufgehoben werden Normalerweise tritt dieser Fehler nach dem Update genau einmal in jeder aktiven Session auf wenn der BSS nicht neu gestartet wird
Behebung
Starten Sie nach jedem Update den BSS neu um alle laufenden Sessions zu beenden
55 Jobs sind nicht ausfuumlhrbar
1 Ein Job wird mit dem Status bdquoNicht unterstuumltztldquo angezeigt wenn fuumlr seine Ausfuumlhrung eine houmlhere Version des BSS erforderlich ist
2 Nach dem Klonen der Datenbank von der Produktions- auf die Testumgebung erhalten alle Jobs automatisch den Status bdquoDeaktiviertldquo wenn die bdquoserverIDldquo nicht identisch ist
Beide Statusaumlnderungen sind gewollt Damit soll verhindert werden dass Jobs nach einem Serverneustart oder nach einem Update automatisch starten und dabei Fehler verursachen
Um Jobs mit dem Status bdquoNicht unterstuumltztldquo nutzen und konfigurieren zu koumlnnen ist es erforderlich den BALVI Schnittstellenserver zu aktualisieren
Deaktivierte Jobs koumlnnen Sie aktivieren indem Sie den jeweiligen Job an den aktuellen Server binden und den Haken bei bdquoAktivldquo setzen
Release Notes BALVI Schnittstellenserver Seite 25 von 37
Puffer-Logik unterteilt den Exportdatenstrom (je Export) in mehre Bloumlcke Der Client kann nun den letzten Block neu anfordern oder den naumlchsten Block wenn der letzte Block erfolgreich verarbeitet wurde Wie viele naumlchste Bloumlcke durch den Server bereit gestellt werden entscheidet diese Einstellung Sobald kein naumlchster Block mehr bereit gestellt werden muss wird der Datenbank-Cursor geschlossen eine Erhoumlhung kann also zu einer Entlastung der aktiven DB-Verbindungen fuumlhren erhoumlht jedoch den Bedarf an RAM des Servers
Der von BALVI voreingestellte Wert ist 3
ltEnvironment
name=partitionedExportmaxBufferedPartitions
value=3 type=javalangInteger override=true
gt
partitionedExportpartitionSizeldquo
Die Groumlszlige der Datenbloumlcke (Partitionen) die an den Client uumlbermittelt werden in Bytes Wenn Sie diesen Wert zu niedrig einstellen reduziert sich die Effizienz des Caches da der Client mehr Datenbloumlcke hintereinander abrufen muss Waumlhlen Sie einen zu groszligen Wert wird die neu zu uumlbertragende Datenmenge im Fall eines Fehlers houmlher
Der von BALVI voreingestellte Wert ist 256000 (256 KB)
ltEnvironment
name=partitionedExportpartitionSize
value=256000 type=javalangInteger override=true
gt
exportTokensmaxTokenCount
Maximale Anzahl der gleichzeitig vergebenen Token die vom Server gecached werden Jede Sitzung welche einen Export durchfuumlhrt erhaumllt einen Session-Token
Wenn eine Sitzung laumlngere Zeit nicht verwendet wurde wird dieser Session-Token wieder entfernt Wenn Sie den Wert zu niedrig einstellen fuumlhrt das zu einer generellen Session-Begrenzung auch fuumlr den nicht partitionierten Export-Modus welcher ab Version 21 verfuumlgbar ist
Ist die Anzahl der Tokens houmlher als die Datenbankeinstellung maxActive kann es vorkommen dass zwar eine Session gestartet werden kann jedoch kein Datenexport zustande kommt
Der von BALVI voreingestellte Wert ist 2000
ltEnvironment
name=exportTokensmaxTokenCount
value=20 type=javalangInteger override=true
gt
exportTokenstokenExpirationInSeconds
Zeit in Sekunden die verstreichen muss bis ein Token unguumlltig wird falls darauf kein Zugriff mehr erfolgt Nach einem erfolgreichen Export wird der Token automatisch geschlossen diese Option ist fuumlr den Abbruchfall vorgesehen Der von BALVI voreingestellte Wert ist 180 (180 s = 3 min)
Release Notes BALVI Schnittstellenserver Seite 26 von 37
ltEnvironment
name=exportTokenstokenExpirationInSeconds
value=180 type=javalangInteger override=true
gt
exportTokenstokenDisposalInSeconds
Zeit in Sekunden die verstreichen muss bis ein Token das erfolgreich abgearbeitet wurde aus dem Cache geloumlscht wird Um sicher zu stellen dass der letzte Exportblock noch erfolgreich abgerufen werden kann bleibt der Token auch nach Fertigmeldung des Clients noch N Sek guumlltig
Der von BALVI voreingestellte Wert ist 60 (60 s = 1 min)
ltEnvironment
name=exportTokenstokenDisposalInSeconds
value=60 type=javalangInteger override=true
gt
2516 Job-Verwaltung fuumlr den BSS konfigurieren Aktivierung der Jobverwaltung
Bis zur Version 28 des BSS gab es den Parameter bdquoavailableServicesldquo Dieser konnte bei Bedarf aktiviert werden wenn die Jobs benoumltigt wurden
Mit Version 30 ist die Einstellung bdquoavailableServicesldquo zu entfernen und kann durch den neuen optionalen Parameter bdquoisJobServiceEnabledldquo in der Datei bdquocontextxmlldquo ersetzt werden
lt-- Neue Parameter zur Aktivierung des Job Service Ersatz fuumlr availableServices --gt
ltEnvironment
name=isJobServiceEnabled
value=true
type=javalangBoolean
override=true
gt
Ab BSS 30 wird die Jobs-Engine standardmaumlszligig aktiviert Sollte die Jobs-Engine nicht benoumltigt werden muss bdquovalueldquo der Wert bdquofalseldquo zugewiesen werden Wird bdquoisJobServiceEnabledldquo nicht eingefuumlgt sind die Jobs trotzdem standardmaumlszligig aktiv
Nach dem Neustart des Servers und erneutem Einloggen erscheint nun zusaumltzlich der Menuumlpunkt bdquoJobsldquo
bdquopasswordKeyldquo fuumlr Jobs
In der Job-Logik wird ein von BALVI definierter Standard-Schluumlssel fuumlr die Ablagen von schuumltzenswerten Daten z B Passwoumlrtern verwendet Diese Einstellung ermoumlglicht den BALVI-Standard zu uumlberschreiben Wenn Sie diese Einstellung aumlndern muumlssen jedoch alle bislang verschluumlsselten Job-Parameter neu verschluumlsselt werden
ltEnvironment
name=javacompenvjobspasswordKey
value=MeinHochsicheresNeuesPasswort
type=javalangString
Release Notes BALVI Schnittstellenserver Seite 27 von 37
override=true
gt
bdquoJob ID enableddisabledldquo (Deprecated ersetzt ab 28 durch das bdquoBindenldquo von Jobs)
Sondereinstellungen fuumlr die Job-Verwaltung Da alle Jobs in einer Datenbank administriert werden jedoch ggf verteilt auf mehreren Tomcat-Servern ausgefuumlhrt werden sollen besteht hier die Option Jobs fuumlr die aktuelle Tomcat-Instanz separat zu deaktivieren
Die Einstellung ID koumlnnte z B folgendermaszligen aussehen javacompenvjobsC0DB58D8D52C4BBC966D1DC788A4EF8Benabled
Fuumlr weitere Fragen zu dieser Einstellung kontaktieren Sie bitte die BALVI GmbH
ltEnvironment
name=javacompenvjobsIDenabled
value=false
type=javalangBoolean
override=true
gt
2517 Weitere optionale Parameter
Es ist fuumlr diverse einzelne Schnittstellen ggf erforderlich Einstellungen in der Datei bdquocontextxmlldquo zu ergaumlnzen Hinweise zu diesen Parametern sind dann in dem der Schnittstelle beiliegenden Dokument enthalten Das gilt z B fuumlr die Schnittstelle bdquoXGewerbeanzeigenldquo
26 Logging mit logback Das Logging wurde komplett uumlberarbeitet Statt bdquoLog4Jldquo wird jetzt bdquologbackldquo4 benutzt Ab BSS 30 ist es zwingend notwendig die Einstellung vorzunehmen um das Logging der Anwendung zu steuern
Migration Ergaumlnzen Sie die neue Einstellung bdquologgingconfigldquo
lt-- Neue Paramter zur Angabe der Logback Config Ersatz fuumlr log4jConfigLocation --gt
ltEnvironment
name=loggingconfig
value=$catalinabaseconflogback-bssxml
type=javalangString
override=true
gt
Nach wie vor steht es Ihnen frei die Logging-Konfiguration eigenstaumlndig anzupassen
Wenn Sie jedoch dieselbe WAR in einer Tomcat-Instanz unter mehreren Context-Namen betreiben wuumlrden beide dieselbe Logging-Konfiguration verwenden so dass alle Protokolleintraumlge in einer Log-Datei aus
4 httplogbackqoschmanualappendershtml
Release Notes BALVI Schnittstellenserver Seite 28 von 37
mehreren Webanwendungen generiert werden Aumlndern Sie den Namen der Logging-Konfiguration entsprechend ab um fuumlr jede Anwendung eine spezifische Logging-Einstellung vornehmen zu koumlnnen
27 Tocmat Optional Suche im bdquoKlassenpfadldquo um den
Ordner bdquoconfldquo erweitern Die Suche nach Dateien uumlber bdquoclasspathldquo setzt voraus dass die Ordner- und Dateinamen im Apache Tomcat bekannt gegeben werden Der Klassenpfad kann in der Datei bdquocatalinapropertiesldquo angepasst werden Wenn Sie dort unter commonloader die folgenden Werte ergaumlnzen kann eine Datei auch im Ordner conf abgelegt werden damit Apache Tomcat diese findet Ansonsten muss die Datei im Ordner lib abgelegt werden
commonloader=$catalinabaseconf$catalinahomeconf
3 Die neue Browser-Oberflaumlche Der BALVI Schnittstellenserver hat seit Version 25 neben der Protokollierung auch die Moumlglichkeit Job-Konfigurationen zu pflegen Der Login ist nur fuumlr einen in BALVI iP eingetragenen ADMIN (z B Benutzer bdquoSYSTEMADMINldquo) mit dem in BALVI iP hinterlegten Passwort moumlglich Zur Anmeldung muss immer [SYSTEMBenutzername] im Feld Benutzer angegeben werden ansonsten schlaumlgt die Anmeldung fehl Bitte achten Sie darauf dass der bdquoldquo (Slash) und nicht der bdquoldquo (Backslash) verwendet werden muss
31 Server-Protokoll Um das Server-Protokoll anzuzeigen waumlhlen Sie den entsprechenden Menuumlpunkt Dort haben Sie seit BSS 26 die Moumlglichkeit uumlber alle Spalten der Protokolle nach Informationen zu suchen
Seit BSS 31 gibt es die Moumlglichkeit Verfahren in bdquoKopfsaumltzeldquo und bdquoDetailsaumltzeldquo zu unterteilen Wurde das Verfahren entsprechend konfiguriert (wie z B bei der Schnittstelle bdquoXGewerbeanzeigenldquo) dann wird im Protokoll-Kopfsatz nur der Start und das Ende der Ausfuumlhrung in der Liste angezeigt Erst bei einem Klick auf bdquoInformationenldquo wird die Liste aller Detailsaumltze angezeigt die im Durchlauf erzeugt wurden
Release Notes BALVI Schnittstellenserver Seite 29 von 37
Verfahren
Die Liste der verfuumlgbaren Verfahren die bei Ihnen im System installiert sind ZB
BEFUNDEhellip Schnittstelle Befunde LM FM oder TS
PROBEhellip Schnittstelle zum Export von Proben an Labore ebenfalls Spezifisch fuumlr einzelne Fachbereiche
MOBILXT Protokolle der BALVI Mobil XT Synchronisation
WEB Allgemeine nicht spezifizierte Protokolle hierunter ist bislang auch die eFi-Protokollierung zu finden
WEB_I0802 Protokolle zur Schnittstelle BALVI iP LIMS (Lebensmittelproben)
XGEWERBE Schnittstelle XGewerbeanzeigen
Klicken Sie auf die Schaltflaumlche so besteht bei den neuen Protokolldatensaumltzen die Moumlglichkeit Detail-Informationen zum Protokollsatz zu erhalten
Release Notes BALVI Schnittstellenserver Seite 30 von 37
Seit BSS 30x ist die Anzeige der Protokolle ebenfalls farblich abgesetzt so dass Protokolleintraumlge mit Fehlern hellrot und Warnungen hellgelb hinterlegt werden
32 Jobs Mit einem Klick auf den Menuumlpunkt Jobs rufen Sie die Oberflaumlche fuumlr die Job-Konfiguration auf Daraufhin werden alle Jobs aufgelistet die fuumlr den BSS freigegeben sind Hier koumlnnen Sie Einstellungen an den Jobs vornehmen und die Jobs aktivieren bzw deaktivieren Die Beschreibungen bzw Einstellungsmoumlglichkeiten fuumlr den jeweiligen SST-Job sind nicht Bestandteil dieser Dokumentation
33 Log-Ausgaben Uumlber den Menuumlpunkt Log-Ausgaben koumlnnen Sie die Ausgabe der Protokolleintraumlge in Echtzeit beobachten
Release Notes BALVI Schnittstellenserver Seite 31 von 37
Starten Sie die Echtzeit-Protokollierung indem Sie auf die Schaltflaumlche mit dem Symbol bdquoPlayldquo (Dreieck) klicken unterbrechen Sie die Ausgabe indem Sie die auf Schaltflaumlche mit dem Symbol bdquoPauseldquo (zwei Balken) klicken
Klicken Sie auf die Schaltflaumlche bdquoAktualisierenldquo (zwei Pfeile) um die neuesten Protokolleintraumlge angezeigt zu bekommen
Klicken Sie auf das Symbol mit dem Papierkorb um die letzten Protokollmeldungen in der Anzeige zu loumlschen
Die Daten in den Protokolldateien auf der Festplatte des Servers sind davon nicht betroffen
Uumlber das Symbol bdquoLogging anpassenldquo (Schraubenschluumlssel) koumlnnen Sie die Ausgabe der Daten im Echtzeitfenster und in den Protokolldateien aumlndern jedoch ist diese Einstellung nur temporaumlr Die Standardeinstellungen koumlnnen ausschlieszliglich uumlber die Anpassung der Datei bdquologback-bssxmlldquo im Konfigurationsverzeichnis des Servers selbst geaumlndert werden
Release Notes BALVI Schnittstellenserver Seite 32 von 37
In der Logging-Parameter Konfiguration koumlnnen Sie verschiedene Parameter einstellen und uumlber die Schaltflaumlche bdquoAnwendenldquo dann sofort im Echtzeitprotokoll sehen Welche Einstellungen moumlglich sind erfahren Sie wenn es eine akute Fehlersituation gibt die detailliertere Ausgaben im Protokoll erfordert
Warnung Wenn Sie den Log-Level fuumlr ROOT oder eine andere Klasse auf TRACE einstellen werden sehr viele Protokollausgaben generiert die auch dazu fuumlhren koumlnnen dass der Server sehr langsam wird oder die Festplatte des Servers zulaumluft wenn fuumlr das Logging kein Dateilimit konfiguriert wurde
34 LogoutAbmeldung vom System Zum Abmelden waumlhlen Sie oben rechts das Kontextmenuuml
35 Cache loumlschen Der Cache wird in der Regel automatisch geloumlscht Wenn Sie jedoch gerade in BALVI iP eine Aumlnderung an den Schnittstellen eingespielt haben und moumlchten dass diese sofort wirksam wird kann die Funktion bdquoCache loumlschenldquo dazu verwendet werden dass der BALVI Schnittstellenserver die Einstellungen bei der naumlchsten Anfrage neu einliest
Release Notes BALVI Schnittstellenserver Seite 33 von 37
Release Notes BALVI Schnittstellenserver Seite 34 von 37
4 Einrichtung in BALVI iP Um die Verfahren fuumlr den BALVI Schnittstellenserver fuumlr Anwender freizuschalten wird das Objekt bdquoSystemeinstellungenldquo oder bdquoMandanten- und Benutzereinstellungenldquo verwendet Die Anpassung ist je Verfahren moumlglich so kann in BALVI iP fuumlr den Zugriff durch den BALVI Schnittstellenserver ein Benutzer bdquoAldquo am Verfahren bdquoMobilldquo berechtigt werden ein Benutzer bdquoBldquo nur am Verfahren bdquoSLA_FLESHldquo usw Die Logik ist jedoch einheitlich Je Verfahren wird durch BALVI eine Verfahrensgruppe mit dem Verfahrensnamen angelegt und mit den entsprechenden Einstellungen vorkonfiguriert welche durch das Verfahren erforderlich sind Dabei kann die Komplexitaumlt der Einstellungen variieren wie z B an den zu Version 23 verfuumlgbaren Verfahren bdquoMobilldquo und bdquoSLA_Fleshldquo ersichtlich wird
Im Verfahren BALVI Mobil sind diverse Anpassungen moumlglich welche je Bundesland oder eingesetzter Import- und Export-Variante durch den BALVI Schnittstellenserver bei der Bearbeitung von Anfragen gepruumlft werden siehe Punkt 3 Abb Mobil-Einstellung in BALVI iP
Abb Mobil-Einstellung in BALVI iP
Alle Verfahren verwenden jedoch die regulaumlre Benutzerverwaltung von BALVI iP Ein Benutzer ohne Passwort gilt fuumlr BALVI iP als gesperrt was fuumlr das Login bedeutet dass der Anwender sich nur uumlber die Active-Directory-Authentifizierung anmelden kann Ist das nicht moumlglich (bzw nicht konfiguriert) kann der Anwender sich weder in BALVI iP noch uumlber die Webservice-Schnittstelle authentifizieren
Fuumlr Dienste-Schnittstellen welche keine persoumlnliche Authentifizierung durch einen Anwender erfordern wird empfohlen einen separaten Benutzer in der Benutzerverwaltung anzulegen und ein sicheres Kennwort zu vergeben Das Anlegen von zusaumltzlichen Benutzern gilt nicht fuumlr BALVI mobil XT da beim Holen und Uumlbermitteln von Daten jeder Benutzer auch ein fachlich konfigurierter Anwender innerhalb von BALVI iP ist und die Anwendungsoberflaumlche ebenfalls zur Erfassung von Daten verwendet
Unter Punkt 2 der Abb Mobil-Einstellung in BALVI iP wird ein modales Fenster geoumlffnet (Abb BALVI mobil Benutzerverwaltung) Innerhalb dieses modalen Fensters werden mandantenweise die Benutzer fuumlr BALVI
Release Notes BALVI Schnittstellenserver Seite 35 von 37
mobil und den jeweiligen Fachbereich festgelegt Dabei ist es wichtig dass man die Haken bdquoAktiv fuumlr hellipldquo bei bdquohellip mobilldquo und bei einem Fachbereich (bdquohellip LMldquo bdquohellip FMldquo usw) setzt weil sonst uumlber den BALVI Schnittstellenserver keine Kommunikation mit BALVI iP moumlglich ist
Abb BALVI mobil Benutzerverwaltung
Alternativ zur Passwort-Authentifizierung wird wie beschrieben auch die Active-Directory-Authentifizierung angeboten Dazu muss der BALVI iP-Anwender uumlber die Schaltflaumlche bdquoDomaumlnen-Benutzer zuordnenldquo mit dem Active Directory verknuumlpft werden
Nur wenn die Active-Directory-Konfigurationen in BALVI iP und im BALVI Schnittstellenserver auf dieselbe Domaumlne verweisen sind die Domaumlnen-Zuordnung und die Active-Directory-Authentifizierung (z B uumlber BALVI mobil XT) moumlglich
Release Notes BALVI Schnittstellenserver Seite 36 von 37
5 Bekannte Probleme und Loumlsungen
51 ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner Bei der Job-Bearbeitung tritt folgender Fehler auf ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner
Behebung
Fuumlhren Sie das beiliegende IP-Patch (UPDATEexe) aus bevor Sie das WAR austauschen
52 Server startet nicht Sie finden folgende Zeilen im Protokoll (catalinaout oder bsslog)
ERROR [localhost-startStop-1] [IdentityServiceImpl] serverID must not be empty
ERROR [localhost-startStop-1] [ContextLoader] Context initialization failed
Behebung
Setzen Sie die Umgebungsvariable ldquoserverIDrdquo in der Datei bdquocontextxmlldquo
53 ORA-00942 table or view does not exist In vielen Faumlllen wird der Fehler ldquoTabelle oder View nicht vorhandenrdquo ausgeworfen (Java-Protokoll im Ordner logs von Apache Tomcat) wenn eine neue Schnittstelle eingerichtet oder ein neues BALVI iP Release bzw Update eingespielt wurde ohne anschlieszligend das aktuelle GRANT-Skript auszufuumlhren
Behebung
Fuumlhren Sie das GRANT-Skript erneut aus
54 ORA-0406x bdquoBestehender Paketstatus wurde aufgehobenldquo
ORA-04061 Bestehender Status von package body ABCXYZ wurde annulliert
ORA-04065 Ausfuumlhrung nicht erfolgreich package body ABCXYZ wurde geaumlndert oder geloumlscht
Release Notes BALVI Schnittstellenserver Seite 37 von 37
Der Fehler tritt haumlufig ein nachdem die UPDATEexe ausgefuumlhrt und in der Ausfuumlhrungsliste ein Package aktualisiert wurde Oracle merkt sich je User-Session bestimmte Werte im Package wenn der Anwender es verwendet hat Durch einen bdquoCREATE OR REPLACE PACKAGEldquo-Befehl kann dieser Status temporaumlr aufgehoben werden Normalerweise tritt dieser Fehler nach dem Update genau einmal in jeder aktiven Session auf wenn der BSS nicht neu gestartet wird
Behebung
Starten Sie nach jedem Update den BSS neu um alle laufenden Sessions zu beenden
55 Jobs sind nicht ausfuumlhrbar
1 Ein Job wird mit dem Status bdquoNicht unterstuumltztldquo angezeigt wenn fuumlr seine Ausfuumlhrung eine houmlhere Version des BSS erforderlich ist
2 Nach dem Klonen der Datenbank von der Produktions- auf die Testumgebung erhalten alle Jobs automatisch den Status bdquoDeaktiviertldquo wenn die bdquoserverIDldquo nicht identisch ist
Beide Statusaumlnderungen sind gewollt Damit soll verhindert werden dass Jobs nach einem Serverneustart oder nach einem Update automatisch starten und dabei Fehler verursachen
Um Jobs mit dem Status bdquoNicht unterstuumltztldquo nutzen und konfigurieren zu koumlnnen ist es erforderlich den BALVI Schnittstellenserver zu aktualisieren
Deaktivierte Jobs koumlnnen Sie aktivieren indem Sie den jeweiligen Job an den aktuellen Server binden und den Haken bei bdquoAktivldquo setzen
Release Notes BALVI Schnittstellenserver Seite 26 von 37
ltEnvironment
name=exportTokenstokenExpirationInSeconds
value=180 type=javalangInteger override=true
gt
exportTokenstokenDisposalInSeconds
Zeit in Sekunden die verstreichen muss bis ein Token das erfolgreich abgearbeitet wurde aus dem Cache geloumlscht wird Um sicher zu stellen dass der letzte Exportblock noch erfolgreich abgerufen werden kann bleibt der Token auch nach Fertigmeldung des Clients noch N Sek guumlltig
Der von BALVI voreingestellte Wert ist 60 (60 s = 1 min)
ltEnvironment
name=exportTokenstokenDisposalInSeconds
value=60 type=javalangInteger override=true
gt
2516 Job-Verwaltung fuumlr den BSS konfigurieren Aktivierung der Jobverwaltung
Bis zur Version 28 des BSS gab es den Parameter bdquoavailableServicesldquo Dieser konnte bei Bedarf aktiviert werden wenn die Jobs benoumltigt wurden
Mit Version 30 ist die Einstellung bdquoavailableServicesldquo zu entfernen und kann durch den neuen optionalen Parameter bdquoisJobServiceEnabledldquo in der Datei bdquocontextxmlldquo ersetzt werden
lt-- Neue Parameter zur Aktivierung des Job Service Ersatz fuumlr availableServices --gt
ltEnvironment
name=isJobServiceEnabled
value=true
type=javalangBoolean
override=true
gt
Ab BSS 30 wird die Jobs-Engine standardmaumlszligig aktiviert Sollte die Jobs-Engine nicht benoumltigt werden muss bdquovalueldquo der Wert bdquofalseldquo zugewiesen werden Wird bdquoisJobServiceEnabledldquo nicht eingefuumlgt sind die Jobs trotzdem standardmaumlszligig aktiv
Nach dem Neustart des Servers und erneutem Einloggen erscheint nun zusaumltzlich der Menuumlpunkt bdquoJobsldquo
bdquopasswordKeyldquo fuumlr Jobs
In der Job-Logik wird ein von BALVI definierter Standard-Schluumlssel fuumlr die Ablagen von schuumltzenswerten Daten z B Passwoumlrtern verwendet Diese Einstellung ermoumlglicht den BALVI-Standard zu uumlberschreiben Wenn Sie diese Einstellung aumlndern muumlssen jedoch alle bislang verschluumlsselten Job-Parameter neu verschluumlsselt werden
ltEnvironment
name=javacompenvjobspasswordKey
value=MeinHochsicheresNeuesPasswort
type=javalangString
Release Notes BALVI Schnittstellenserver Seite 27 von 37
override=true
gt
bdquoJob ID enableddisabledldquo (Deprecated ersetzt ab 28 durch das bdquoBindenldquo von Jobs)
Sondereinstellungen fuumlr die Job-Verwaltung Da alle Jobs in einer Datenbank administriert werden jedoch ggf verteilt auf mehreren Tomcat-Servern ausgefuumlhrt werden sollen besteht hier die Option Jobs fuumlr die aktuelle Tomcat-Instanz separat zu deaktivieren
Die Einstellung ID koumlnnte z B folgendermaszligen aussehen javacompenvjobsC0DB58D8D52C4BBC966D1DC788A4EF8Benabled
Fuumlr weitere Fragen zu dieser Einstellung kontaktieren Sie bitte die BALVI GmbH
ltEnvironment
name=javacompenvjobsIDenabled
value=false
type=javalangBoolean
override=true
gt
2517 Weitere optionale Parameter
Es ist fuumlr diverse einzelne Schnittstellen ggf erforderlich Einstellungen in der Datei bdquocontextxmlldquo zu ergaumlnzen Hinweise zu diesen Parametern sind dann in dem der Schnittstelle beiliegenden Dokument enthalten Das gilt z B fuumlr die Schnittstelle bdquoXGewerbeanzeigenldquo
26 Logging mit logback Das Logging wurde komplett uumlberarbeitet Statt bdquoLog4Jldquo wird jetzt bdquologbackldquo4 benutzt Ab BSS 30 ist es zwingend notwendig die Einstellung vorzunehmen um das Logging der Anwendung zu steuern
Migration Ergaumlnzen Sie die neue Einstellung bdquologgingconfigldquo
lt-- Neue Paramter zur Angabe der Logback Config Ersatz fuumlr log4jConfigLocation --gt
ltEnvironment
name=loggingconfig
value=$catalinabaseconflogback-bssxml
type=javalangString
override=true
gt
Nach wie vor steht es Ihnen frei die Logging-Konfiguration eigenstaumlndig anzupassen
Wenn Sie jedoch dieselbe WAR in einer Tomcat-Instanz unter mehreren Context-Namen betreiben wuumlrden beide dieselbe Logging-Konfiguration verwenden so dass alle Protokolleintraumlge in einer Log-Datei aus
4 httplogbackqoschmanualappendershtml
Release Notes BALVI Schnittstellenserver Seite 28 von 37
mehreren Webanwendungen generiert werden Aumlndern Sie den Namen der Logging-Konfiguration entsprechend ab um fuumlr jede Anwendung eine spezifische Logging-Einstellung vornehmen zu koumlnnen
27 Tocmat Optional Suche im bdquoKlassenpfadldquo um den
Ordner bdquoconfldquo erweitern Die Suche nach Dateien uumlber bdquoclasspathldquo setzt voraus dass die Ordner- und Dateinamen im Apache Tomcat bekannt gegeben werden Der Klassenpfad kann in der Datei bdquocatalinapropertiesldquo angepasst werden Wenn Sie dort unter commonloader die folgenden Werte ergaumlnzen kann eine Datei auch im Ordner conf abgelegt werden damit Apache Tomcat diese findet Ansonsten muss die Datei im Ordner lib abgelegt werden
commonloader=$catalinabaseconf$catalinahomeconf
3 Die neue Browser-Oberflaumlche Der BALVI Schnittstellenserver hat seit Version 25 neben der Protokollierung auch die Moumlglichkeit Job-Konfigurationen zu pflegen Der Login ist nur fuumlr einen in BALVI iP eingetragenen ADMIN (z B Benutzer bdquoSYSTEMADMINldquo) mit dem in BALVI iP hinterlegten Passwort moumlglich Zur Anmeldung muss immer [SYSTEMBenutzername] im Feld Benutzer angegeben werden ansonsten schlaumlgt die Anmeldung fehl Bitte achten Sie darauf dass der bdquoldquo (Slash) und nicht der bdquoldquo (Backslash) verwendet werden muss
31 Server-Protokoll Um das Server-Protokoll anzuzeigen waumlhlen Sie den entsprechenden Menuumlpunkt Dort haben Sie seit BSS 26 die Moumlglichkeit uumlber alle Spalten der Protokolle nach Informationen zu suchen
Seit BSS 31 gibt es die Moumlglichkeit Verfahren in bdquoKopfsaumltzeldquo und bdquoDetailsaumltzeldquo zu unterteilen Wurde das Verfahren entsprechend konfiguriert (wie z B bei der Schnittstelle bdquoXGewerbeanzeigenldquo) dann wird im Protokoll-Kopfsatz nur der Start und das Ende der Ausfuumlhrung in der Liste angezeigt Erst bei einem Klick auf bdquoInformationenldquo wird die Liste aller Detailsaumltze angezeigt die im Durchlauf erzeugt wurden
Release Notes BALVI Schnittstellenserver Seite 29 von 37
Verfahren
Die Liste der verfuumlgbaren Verfahren die bei Ihnen im System installiert sind ZB
BEFUNDEhellip Schnittstelle Befunde LM FM oder TS
PROBEhellip Schnittstelle zum Export von Proben an Labore ebenfalls Spezifisch fuumlr einzelne Fachbereiche
MOBILXT Protokolle der BALVI Mobil XT Synchronisation
WEB Allgemeine nicht spezifizierte Protokolle hierunter ist bislang auch die eFi-Protokollierung zu finden
WEB_I0802 Protokolle zur Schnittstelle BALVI iP LIMS (Lebensmittelproben)
XGEWERBE Schnittstelle XGewerbeanzeigen
Klicken Sie auf die Schaltflaumlche so besteht bei den neuen Protokolldatensaumltzen die Moumlglichkeit Detail-Informationen zum Protokollsatz zu erhalten
Release Notes BALVI Schnittstellenserver Seite 30 von 37
Seit BSS 30x ist die Anzeige der Protokolle ebenfalls farblich abgesetzt so dass Protokolleintraumlge mit Fehlern hellrot und Warnungen hellgelb hinterlegt werden
32 Jobs Mit einem Klick auf den Menuumlpunkt Jobs rufen Sie die Oberflaumlche fuumlr die Job-Konfiguration auf Daraufhin werden alle Jobs aufgelistet die fuumlr den BSS freigegeben sind Hier koumlnnen Sie Einstellungen an den Jobs vornehmen und die Jobs aktivieren bzw deaktivieren Die Beschreibungen bzw Einstellungsmoumlglichkeiten fuumlr den jeweiligen SST-Job sind nicht Bestandteil dieser Dokumentation
33 Log-Ausgaben Uumlber den Menuumlpunkt Log-Ausgaben koumlnnen Sie die Ausgabe der Protokolleintraumlge in Echtzeit beobachten
Release Notes BALVI Schnittstellenserver Seite 31 von 37
Starten Sie die Echtzeit-Protokollierung indem Sie auf die Schaltflaumlche mit dem Symbol bdquoPlayldquo (Dreieck) klicken unterbrechen Sie die Ausgabe indem Sie die auf Schaltflaumlche mit dem Symbol bdquoPauseldquo (zwei Balken) klicken
Klicken Sie auf die Schaltflaumlche bdquoAktualisierenldquo (zwei Pfeile) um die neuesten Protokolleintraumlge angezeigt zu bekommen
Klicken Sie auf das Symbol mit dem Papierkorb um die letzten Protokollmeldungen in der Anzeige zu loumlschen
Die Daten in den Protokolldateien auf der Festplatte des Servers sind davon nicht betroffen
Uumlber das Symbol bdquoLogging anpassenldquo (Schraubenschluumlssel) koumlnnen Sie die Ausgabe der Daten im Echtzeitfenster und in den Protokolldateien aumlndern jedoch ist diese Einstellung nur temporaumlr Die Standardeinstellungen koumlnnen ausschlieszliglich uumlber die Anpassung der Datei bdquologback-bssxmlldquo im Konfigurationsverzeichnis des Servers selbst geaumlndert werden
Release Notes BALVI Schnittstellenserver Seite 32 von 37
In der Logging-Parameter Konfiguration koumlnnen Sie verschiedene Parameter einstellen und uumlber die Schaltflaumlche bdquoAnwendenldquo dann sofort im Echtzeitprotokoll sehen Welche Einstellungen moumlglich sind erfahren Sie wenn es eine akute Fehlersituation gibt die detailliertere Ausgaben im Protokoll erfordert
Warnung Wenn Sie den Log-Level fuumlr ROOT oder eine andere Klasse auf TRACE einstellen werden sehr viele Protokollausgaben generiert die auch dazu fuumlhren koumlnnen dass der Server sehr langsam wird oder die Festplatte des Servers zulaumluft wenn fuumlr das Logging kein Dateilimit konfiguriert wurde
34 LogoutAbmeldung vom System Zum Abmelden waumlhlen Sie oben rechts das Kontextmenuuml
35 Cache loumlschen Der Cache wird in der Regel automatisch geloumlscht Wenn Sie jedoch gerade in BALVI iP eine Aumlnderung an den Schnittstellen eingespielt haben und moumlchten dass diese sofort wirksam wird kann die Funktion bdquoCache loumlschenldquo dazu verwendet werden dass der BALVI Schnittstellenserver die Einstellungen bei der naumlchsten Anfrage neu einliest
Release Notes BALVI Schnittstellenserver Seite 33 von 37
Release Notes BALVI Schnittstellenserver Seite 34 von 37
4 Einrichtung in BALVI iP Um die Verfahren fuumlr den BALVI Schnittstellenserver fuumlr Anwender freizuschalten wird das Objekt bdquoSystemeinstellungenldquo oder bdquoMandanten- und Benutzereinstellungenldquo verwendet Die Anpassung ist je Verfahren moumlglich so kann in BALVI iP fuumlr den Zugriff durch den BALVI Schnittstellenserver ein Benutzer bdquoAldquo am Verfahren bdquoMobilldquo berechtigt werden ein Benutzer bdquoBldquo nur am Verfahren bdquoSLA_FLESHldquo usw Die Logik ist jedoch einheitlich Je Verfahren wird durch BALVI eine Verfahrensgruppe mit dem Verfahrensnamen angelegt und mit den entsprechenden Einstellungen vorkonfiguriert welche durch das Verfahren erforderlich sind Dabei kann die Komplexitaumlt der Einstellungen variieren wie z B an den zu Version 23 verfuumlgbaren Verfahren bdquoMobilldquo und bdquoSLA_Fleshldquo ersichtlich wird
Im Verfahren BALVI Mobil sind diverse Anpassungen moumlglich welche je Bundesland oder eingesetzter Import- und Export-Variante durch den BALVI Schnittstellenserver bei der Bearbeitung von Anfragen gepruumlft werden siehe Punkt 3 Abb Mobil-Einstellung in BALVI iP
Abb Mobil-Einstellung in BALVI iP
Alle Verfahren verwenden jedoch die regulaumlre Benutzerverwaltung von BALVI iP Ein Benutzer ohne Passwort gilt fuumlr BALVI iP als gesperrt was fuumlr das Login bedeutet dass der Anwender sich nur uumlber die Active-Directory-Authentifizierung anmelden kann Ist das nicht moumlglich (bzw nicht konfiguriert) kann der Anwender sich weder in BALVI iP noch uumlber die Webservice-Schnittstelle authentifizieren
Fuumlr Dienste-Schnittstellen welche keine persoumlnliche Authentifizierung durch einen Anwender erfordern wird empfohlen einen separaten Benutzer in der Benutzerverwaltung anzulegen und ein sicheres Kennwort zu vergeben Das Anlegen von zusaumltzlichen Benutzern gilt nicht fuumlr BALVI mobil XT da beim Holen und Uumlbermitteln von Daten jeder Benutzer auch ein fachlich konfigurierter Anwender innerhalb von BALVI iP ist und die Anwendungsoberflaumlche ebenfalls zur Erfassung von Daten verwendet
Unter Punkt 2 der Abb Mobil-Einstellung in BALVI iP wird ein modales Fenster geoumlffnet (Abb BALVI mobil Benutzerverwaltung) Innerhalb dieses modalen Fensters werden mandantenweise die Benutzer fuumlr BALVI
Release Notes BALVI Schnittstellenserver Seite 35 von 37
mobil und den jeweiligen Fachbereich festgelegt Dabei ist es wichtig dass man die Haken bdquoAktiv fuumlr hellipldquo bei bdquohellip mobilldquo und bei einem Fachbereich (bdquohellip LMldquo bdquohellip FMldquo usw) setzt weil sonst uumlber den BALVI Schnittstellenserver keine Kommunikation mit BALVI iP moumlglich ist
Abb BALVI mobil Benutzerverwaltung
Alternativ zur Passwort-Authentifizierung wird wie beschrieben auch die Active-Directory-Authentifizierung angeboten Dazu muss der BALVI iP-Anwender uumlber die Schaltflaumlche bdquoDomaumlnen-Benutzer zuordnenldquo mit dem Active Directory verknuumlpft werden
Nur wenn die Active-Directory-Konfigurationen in BALVI iP und im BALVI Schnittstellenserver auf dieselbe Domaumlne verweisen sind die Domaumlnen-Zuordnung und die Active-Directory-Authentifizierung (z B uumlber BALVI mobil XT) moumlglich
Release Notes BALVI Schnittstellenserver Seite 36 von 37
5 Bekannte Probleme und Loumlsungen
51 ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner Bei der Job-Bearbeitung tritt folgender Fehler auf ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner
Behebung
Fuumlhren Sie das beiliegende IP-Patch (UPDATEexe) aus bevor Sie das WAR austauschen
52 Server startet nicht Sie finden folgende Zeilen im Protokoll (catalinaout oder bsslog)
ERROR [localhost-startStop-1] [IdentityServiceImpl] serverID must not be empty
ERROR [localhost-startStop-1] [ContextLoader] Context initialization failed
Behebung
Setzen Sie die Umgebungsvariable ldquoserverIDrdquo in der Datei bdquocontextxmlldquo
53 ORA-00942 table or view does not exist In vielen Faumlllen wird der Fehler ldquoTabelle oder View nicht vorhandenrdquo ausgeworfen (Java-Protokoll im Ordner logs von Apache Tomcat) wenn eine neue Schnittstelle eingerichtet oder ein neues BALVI iP Release bzw Update eingespielt wurde ohne anschlieszligend das aktuelle GRANT-Skript auszufuumlhren
Behebung
Fuumlhren Sie das GRANT-Skript erneut aus
54 ORA-0406x bdquoBestehender Paketstatus wurde aufgehobenldquo
ORA-04061 Bestehender Status von package body ABCXYZ wurde annulliert
ORA-04065 Ausfuumlhrung nicht erfolgreich package body ABCXYZ wurde geaumlndert oder geloumlscht
Release Notes BALVI Schnittstellenserver Seite 37 von 37
Der Fehler tritt haumlufig ein nachdem die UPDATEexe ausgefuumlhrt und in der Ausfuumlhrungsliste ein Package aktualisiert wurde Oracle merkt sich je User-Session bestimmte Werte im Package wenn der Anwender es verwendet hat Durch einen bdquoCREATE OR REPLACE PACKAGEldquo-Befehl kann dieser Status temporaumlr aufgehoben werden Normalerweise tritt dieser Fehler nach dem Update genau einmal in jeder aktiven Session auf wenn der BSS nicht neu gestartet wird
Behebung
Starten Sie nach jedem Update den BSS neu um alle laufenden Sessions zu beenden
55 Jobs sind nicht ausfuumlhrbar
1 Ein Job wird mit dem Status bdquoNicht unterstuumltztldquo angezeigt wenn fuumlr seine Ausfuumlhrung eine houmlhere Version des BSS erforderlich ist
2 Nach dem Klonen der Datenbank von der Produktions- auf die Testumgebung erhalten alle Jobs automatisch den Status bdquoDeaktiviertldquo wenn die bdquoserverIDldquo nicht identisch ist
Beide Statusaumlnderungen sind gewollt Damit soll verhindert werden dass Jobs nach einem Serverneustart oder nach einem Update automatisch starten und dabei Fehler verursachen
Um Jobs mit dem Status bdquoNicht unterstuumltztldquo nutzen und konfigurieren zu koumlnnen ist es erforderlich den BALVI Schnittstellenserver zu aktualisieren
Deaktivierte Jobs koumlnnen Sie aktivieren indem Sie den jeweiligen Job an den aktuellen Server binden und den Haken bei bdquoAktivldquo setzen
Release Notes BALVI Schnittstellenserver Seite 27 von 37
override=true
gt
bdquoJob ID enableddisabledldquo (Deprecated ersetzt ab 28 durch das bdquoBindenldquo von Jobs)
Sondereinstellungen fuumlr die Job-Verwaltung Da alle Jobs in einer Datenbank administriert werden jedoch ggf verteilt auf mehreren Tomcat-Servern ausgefuumlhrt werden sollen besteht hier die Option Jobs fuumlr die aktuelle Tomcat-Instanz separat zu deaktivieren
Die Einstellung ID koumlnnte z B folgendermaszligen aussehen javacompenvjobsC0DB58D8D52C4BBC966D1DC788A4EF8Benabled
Fuumlr weitere Fragen zu dieser Einstellung kontaktieren Sie bitte die BALVI GmbH
ltEnvironment
name=javacompenvjobsIDenabled
value=false
type=javalangBoolean
override=true
gt
2517 Weitere optionale Parameter
Es ist fuumlr diverse einzelne Schnittstellen ggf erforderlich Einstellungen in der Datei bdquocontextxmlldquo zu ergaumlnzen Hinweise zu diesen Parametern sind dann in dem der Schnittstelle beiliegenden Dokument enthalten Das gilt z B fuumlr die Schnittstelle bdquoXGewerbeanzeigenldquo
26 Logging mit logback Das Logging wurde komplett uumlberarbeitet Statt bdquoLog4Jldquo wird jetzt bdquologbackldquo4 benutzt Ab BSS 30 ist es zwingend notwendig die Einstellung vorzunehmen um das Logging der Anwendung zu steuern
Migration Ergaumlnzen Sie die neue Einstellung bdquologgingconfigldquo
lt-- Neue Paramter zur Angabe der Logback Config Ersatz fuumlr log4jConfigLocation --gt
ltEnvironment
name=loggingconfig
value=$catalinabaseconflogback-bssxml
type=javalangString
override=true
gt
Nach wie vor steht es Ihnen frei die Logging-Konfiguration eigenstaumlndig anzupassen
Wenn Sie jedoch dieselbe WAR in einer Tomcat-Instanz unter mehreren Context-Namen betreiben wuumlrden beide dieselbe Logging-Konfiguration verwenden so dass alle Protokolleintraumlge in einer Log-Datei aus
4 httplogbackqoschmanualappendershtml
Release Notes BALVI Schnittstellenserver Seite 28 von 37
mehreren Webanwendungen generiert werden Aumlndern Sie den Namen der Logging-Konfiguration entsprechend ab um fuumlr jede Anwendung eine spezifische Logging-Einstellung vornehmen zu koumlnnen
27 Tocmat Optional Suche im bdquoKlassenpfadldquo um den
Ordner bdquoconfldquo erweitern Die Suche nach Dateien uumlber bdquoclasspathldquo setzt voraus dass die Ordner- und Dateinamen im Apache Tomcat bekannt gegeben werden Der Klassenpfad kann in der Datei bdquocatalinapropertiesldquo angepasst werden Wenn Sie dort unter commonloader die folgenden Werte ergaumlnzen kann eine Datei auch im Ordner conf abgelegt werden damit Apache Tomcat diese findet Ansonsten muss die Datei im Ordner lib abgelegt werden
commonloader=$catalinabaseconf$catalinahomeconf
3 Die neue Browser-Oberflaumlche Der BALVI Schnittstellenserver hat seit Version 25 neben der Protokollierung auch die Moumlglichkeit Job-Konfigurationen zu pflegen Der Login ist nur fuumlr einen in BALVI iP eingetragenen ADMIN (z B Benutzer bdquoSYSTEMADMINldquo) mit dem in BALVI iP hinterlegten Passwort moumlglich Zur Anmeldung muss immer [SYSTEMBenutzername] im Feld Benutzer angegeben werden ansonsten schlaumlgt die Anmeldung fehl Bitte achten Sie darauf dass der bdquoldquo (Slash) und nicht der bdquoldquo (Backslash) verwendet werden muss
31 Server-Protokoll Um das Server-Protokoll anzuzeigen waumlhlen Sie den entsprechenden Menuumlpunkt Dort haben Sie seit BSS 26 die Moumlglichkeit uumlber alle Spalten der Protokolle nach Informationen zu suchen
Seit BSS 31 gibt es die Moumlglichkeit Verfahren in bdquoKopfsaumltzeldquo und bdquoDetailsaumltzeldquo zu unterteilen Wurde das Verfahren entsprechend konfiguriert (wie z B bei der Schnittstelle bdquoXGewerbeanzeigenldquo) dann wird im Protokoll-Kopfsatz nur der Start und das Ende der Ausfuumlhrung in der Liste angezeigt Erst bei einem Klick auf bdquoInformationenldquo wird die Liste aller Detailsaumltze angezeigt die im Durchlauf erzeugt wurden
Release Notes BALVI Schnittstellenserver Seite 29 von 37
Verfahren
Die Liste der verfuumlgbaren Verfahren die bei Ihnen im System installiert sind ZB
BEFUNDEhellip Schnittstelle Befunde LM FM oder TS
PROBEhellip Schnittstelle zum Export von Proben an Labore ebenfalls Spezifisch fuumlr einzelne Fachbereiche
MOBILXT Protokolle der BALVI Mobil XT Synchronisation
WEB Allgemeine nicht spezifizierte Protokolle hierunter ist bislang auch die eFi-Protokollierung zu finden
WEB_I0802 Protokolle zur Schnittstelle BALVI iP LIMS (Lebensmittelproben)
XGEWERBE Schnittstelle XGewerbeanzeigen
Klicken Sie auf die Schaltflaumlche so besteht bei den neuen Protokolldatensaumltzen die Moumlglichkeit Detail-Informationen zum Protokollsatz zu erhalten
Release Notes BALVI Schnittstellenserver Seite 30 von 37
Seit BSS 30x ist die Anzeige der Protokolle ebenfalls farblich abgesetzt so dass Protokolleintraumlge mit Fehlern hellrot und Warnungen hellgelb hinterlegt werden
32 Jobs Mit einem Klick auf den Menuumlpunkt Jobs rufen Sie die Oberflaumlche fuumlr die Job-Konfiguration auf Daraufhin werden alle Jobs aufgelistet die fuumlr den BSS freigegeben sind Hier koumlnnen Sie Einstellungen an den Jobs vornehmen und die Jobs aktivieren bzw deaktivieren Die Beschreibungen bzw Einstellungsmoumlglichkeiten fuumlr den jeweiligen SST-Job sind nicht Bestandteil dieser Dokumentation
33 Log-Ausgaben Uumlber den Menuumlpunkt Log-Ausgaben koumlnnen Sie die Ausgabe der Protokolleintraumlge in Echtzeit beobachten
Release Notes BALVI Schnittstellenserver Seite 31 von 37
Starten Sie die Echtzeit-Protokollierung indem Sie auf die Schaltflaumlche mit dem Symbol bdquoPlayldquo (Dreieck) klicken unterbrechen Sie die Ausgabe indem Sie die auf Schaltflaumlche mit dem Symbol bdquoPauseldquo (zwei Balken) klicken
Klicken Sie auf die Schaltflaumlche bdquoAktualisierenldquo (zwei Pfeile) um die neuesten Protokolleintraumlge angezeigt zu bekommen
Klicken Sie auf das Symbol mit dem Papierkorb um die letzten Protokollmeldungen in der Anzeige zu loumlschen
Die Daten in den Protokolldateien auf der Festplatte des Servers sind davon nicht betroffen
Uumlber das Symbol bdquoLogging anpassenldquo (Schraubenschluumlssel) koumlnnen Sie die Ausgabe der Daten im Echtzeitfenster und in den Protokolldateien aumlndern jedoch ist diese Einstellung nur temporaumlr Die Standardeinstellungen koumlnnen ausschlieszliglich uumlber die Anpassung der Datei bdquologback-bssxmlldquo im Konfigurationsverzeichnis des Servers selbst geaumlndert werden
Release Notes BALVI Schnittstellenserver Seite 32 von 37
In der Logging-Parameter Konfiguration koumlnnen Sie verschiedene Parameter einstellen und uumlber die Schaltflaumlche bdquoAnwendenldquo dann sofort im Echtzeitprotokoll sehen Welche Einstellungen moumlglich sind erfahren Sie wenn es eine akute Fehlersituation gibt die detailliertere Ausgaben im Protokoll erfordert
Warnung Wenn Sie den Log-Level fuumlr ROOT oder eine andere Klasse auf TRACE einstellen werden sehr viele Protokollausgaben generiert die auch dazu fuumlhren koumlnnen dass der Server sehr langsam wird oder die Festplatte des Servers zulaumluft wenn fuumlr das Logging kein Dateilimit konfiguriert wurde
34 LogoutAbmeldung vom System Zum Abmelden waumlhlen Sie oben rechts das Kontextmenuuml
35 Cache loumlschen Der Cache wird in der Regel automatisch geloumlscht Wenn Sie jedoch gerade in BALVI iP eine Aumlnderung an den Schnittstellen eingespielt haben und moumlchten dass diese sofort wirksam wird kann die Funktion bdquoCache loumlschenldquo dazu verwendet werden dass der BALVI Schnittstellenserver die Einstellungen bei der naumlchsten Anfrage neu einliest
Release Notes BALVI Schnittstellenserver Seite 33 von 37
Release Notes BALVI Schnittstellenserver Seite 34 von 37
4 Einrichtung in BALVI iP Um die Verfahren fuumlr den BALVI Schnittstellenserver fuumlr Anwender freizuschalten wird das Objekt bdquoSystemeinstellungenldquo oder bdquoMandanten- und Benutzereinstellungenldquo verwendet Die Anpassung ist je Verfahren moumlglich so kann in BALVI iP fuumlr den Zugriff durch den BALVI Schnittstellenserver ein Benutzer bdquoAldquo am Verfahren bdquoMobilldquo berechtigt werden ein Benutzer bdquoBldquo nur am Verfahren bdquoSLA_FLESHldquo usw Die Logik ist jedoch einheitlich Je Verfahren wird durch BALVI eine Verfahrensgruppe mit dem Verfahrensnamen angelegt und mit den entsprechenden Einstellungen vorkonfiguriert welche durch das Verfahren erforderlich sind Dabei kann die Komplexitaumlt der Einstellungen variieren wie z B an den zu Version 23 verfuumlgbaren Verfahren bdquoMobilldquo und bdquoSLA_Fleshldquo ersichtlich wird
Im Verfahren BALVI Mobil sind diverse Anpassungen moumlglich welche je Bundesland oder eingesetzter Import- und Export-Variante durch den BALVI Schnittstellenserver bei der Bearbeitung von Anfragen gepruumlft werden siehe Punkt 3 Abb Mobil-Einstellung in BALVI iP
Abb Mobil-Einstellung in BALVI iP
Alle Verfahren verwenden jedoch die regulaumlre Benutzerverwaltung von BALVI iP Ein Benutzer ohne Passwort gilt fuumlr BALVI iP als gesperrt was fuumlr das Login bedeutet dass der Anwender sich nur uumlber die Active-Directory-Authentifizierung anmelden kann Ist das nicht moumlglich (bzw nicht konfiguriert) kann der Anwender sich weder in BALVI iP noch uumlber die Webservice-Schnittstelle authentifizieren
Fuumlr Dienste-Schnittstellen welche keine persoumlnliche Authentifizierung durch einen Anwender erfordern wird empfohlen einen separaten Benutzer in der Benutzerverwaltung anzulegen und ein sicheres Kennwort zu vergeben Das Anlegen von zusaumltzlichen Benutzern gilt nicht fuumlr BALVI mobil XT da beim Holen und Uumlbermitteln von Daten jeder Benutzer auch ein fachlich konfigurierter Anwender innerhalb von BALVI iP ist und die Anwendungsoberflaumlche ebenfalls zur Erfassung von Daten verwendet
Unter Punkt 2 der Abb Mobil-Einstellung in BALVI iP wird ein modales Fenster geoumlffnet (Abb BALVI mobil Benutzerverwaltung) Innerhalb dieses modalen Fensters werden mandantenweise die Benutzer fuumlr BALVI
Release Notes BALVI Schnittstellenserver Seite 35 von 37
mobil und den jeweiligen Fachbereich festgelegt Dabei ist es wichtig dass man die Haken bdquoAktiv fuumlr hellipldquo bei bdquohellip mobilldquo und bei einem Fachbereich (bdquohellip LMldquo bdquohellip FMldquo usw) setzt weil sonst uumlber den BALVI Schnittstellenserver keine Kommunikation mit BALVI iP moumlglich ist
Abb BALVI mobil Benutzerverwaltung
Alternativ zur Passwort-Authentifizierung wird wie beschrieben auch die Active-Directory-Authentifizierung angeboten Dazu muss der BALVI iP-Anwender uumlber die Schaltflaumlche bdquoDomaumlnen-Benutzer zuordnenldquo mit dem Active Directory verknuumlpft werden
Nur wenn die Active-Directory-Konfigurationen in BALVI iP und im BALVI Schnittstellenserver auf dieselbe Domaumlne verweisen sind die Domaumlnen-Zuordnung und die Active-Directory-Authentifizierung (z B uumlber BALVI mobil XT) moumlglich
Release Notes BALVI Schnittstellenserver Seite 36 von 37
5 Bekannte Probleme und Loumlsungen
51 ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner Bei der Job-Bearbeitung tritt folgender Fehler auf ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner
Behebung
Fuumlhren Sie das beiliegende IP-Patch (UPDATEexe) aus bevor Sie das WAR austauschen
52 Server startet nicht Sie finden folgende Zeilen im Protokoll (catalinaout oder bsslog)
ERROR [localhost-startStop-1] [IdentityServiceImpl] serverID must not be empty
ERROR [localhost-startStop-1] [ContextLoader] Context initialization failed
Behebung
Setzen Sie die Umgebungsvariable ldquoserverIDrdquo in der Datei bdquocontextxmlldquo
53 ORA-00942 table or view does not exist In vielen Faumlllen wird der Fehler ldquoTabelle oder View nicht vorhandenrdquo ausgeworfen (Java-Protokoll im Ordner logs von Apache Tomcat) wenn eine neue Schnittstelle eingerichtet oder ein neues BALVI iP Release bzw Update eingespielt wurde ohne anschlieszligend das aktuelle GRANT-Skript auszufuumlhren
Behebung
Fuumlhren Sie das GRANT-Skript erneut aus
54 ORA-0406x bdquoBestehender Paketstatus wurde aufgehobenldquo
ORA-04061 Bestehender Status von package body ABCXYZ wurde annulliert
ORA-04065 Ausfuumlhrung nicht erfolgreich package body ABCXYZ wurde geaumlndert oder geloumlscht
Release Notes BALVI Schnittstellenserver Seite 37 von 37
Der Fehler tritt haumlufig ein nachdem die UPDATEexe ausgefuumlhrt und in der Ausfuumlhrungsliste ein Package aktualisiert wurde Oracle merkt sich je User-Session bestimmte Werte im Package wenn der Anwender es verwendet hat Durch einen bdquoCREATE OR REPLACE PACKAGEldquo-Befehl kann dieser Status temporaumlr aufgehoben werden Normalerweise tritt dieser Fehler nach dem Update genau einmal in jeder aktiven Session auf wenn der BSS nicht neu gestartet wird
Behebung
Starten Sie nach jedem Update den BSS neu um alle laufenden Sessions zu beenden
55 Jobs sind nicht ausfuumlhrbar
1 Ein Job wird mit dem Status bdquoNicht unterstuumltztldquo angezeigt wenn fuumlr seine Ausfuumlhrung eine houmlhere Version des BSS erforderlich ist
2 Nach dem Klonen der Datenbank von der Produktions- auf die Testumgebung erhalten alle Jobs automatisch den Status bdquoDeaktiviertldquo wenn die bdquoserverIDldquo nicht identisch ist
Beide Statusaumlnderungen sind gewollt Damit soll verhindert werden dass Jobs nach einem Serverneustart oder nach einem Update automatisch starten und dabei Fehler verursachen
Um Jobs mit dem Status bdquoNicht unterstuumltztldquo nutzen und konfigurieren zu koumlnnen ist es erforderlich den BALVI Schnittstellenserver zu aktualisieren
Deaktivierte Jobs koumlnnen Sie aktivieren indem Sie den jeweiligen Job an den aktuellen Server binden und den Haken bei bdquoAktivldquo setzen
Release Notes BALVI Schnittstellenserver Seite 28 von 37
mehreren Webanwendungen generiert werden Aumlndern Sie den Namen der Logging-Konfiguration entsprechend ab um fuumlr jede Anwendung eine spezifische Logging-Einstellung vornehmen zu koumlnnen
27 Tocmat Optional Suche im bdquoKlassenpfadldquo um den
Ordner bdquoconfldquo erweitern Die Suche nach Dateien uumlber bdquoclasspathldquo setzt voraus dass die Ordner- und Dateinamen im Apache Tomcat bekannt gegeben werden Der Klassenpfad kann in der Datei bdquocatalinapropertiesldquo angepasst werden Wenn Sie dort unter commonloader die folgenden Werte ergaumlnzen kann eine Datei auch im Ordner conf abgelegt werden damit Apache Tomcat diese findet Ansonsten muss die Datei im Ordner lib abgelegt werden
commonloader=$catalinabaseconf$catalinahomeconf
3 Die neue Browser-Oberflaumlche Der BALVI Schnittstellenserver hat seit Version 25 neben der Protokollierung auch die Moumlglichkeit Job-Konfigurationen zu pflegen Der Login ist nur fuumlr einen in BALVI iP eingetragenen ADMIN (z B Benutzer bdquoSYSTEMADMINldquo) mit dem in BALVI iP hinterlegten Passwort moumlglich Zur Anmeldung muss immer [SYSTEMBenutzername] im Feld Benutzer angegeben werden ansonsten schlaumlgt die Anmeldung fehl Bitte achten Sie darauf dass der bdquoldquo (Slash) und nicht der bdquoldquo (Backslash) verwendet werden muss
31 Server-Protokoll Um das Server-Protokoll anzuzeigen waumlhlen Sie den entsprechenden Menuumlpunkt Dort haben Sie seit BSS 26 die Moumlglichkeit uumlber alle Spalten der Protokolle nach Informationen zu suchen
Seit BSS 31 gibt es die Moumlglichkeit Verfahren in bdquoKopfsaumltzeldquo und bdquoDetailsaumltzeldquo zu unterteilen Wurde das Verfahren entsprechend konfiguriert (wie z B bei der Schnittstelle bdquoXGewerbeanzeigenldquo) dann wird im Protokoll-Kopfsatz nur der Start und das Ende der Ausfuumlhrung in der Liste angezeigt Erst bei einem Klick auf bdquoInformationenldquo wird die Liste aller Detailsaumltze angezeigt die im Durchlauf erzeugt wurden
Release Notes BALVI Schnittstellenserver Seite 29 von 37
Verfahren
Die Liste der verfuumlgbaren Verfahren die bei Ihnen im System installiert sind ZB
BEFUNDEhellip Schnittstelle Befunde LM FM oder TS
PROBEhellip Schnittstelle zum Export von Proben an Labore ebenfalls Spezifisch fuumlr einzelne Fachbereiche
MOBILXT Protokolle der BALVI Mobil XT Synchronisation
WEB Allgemeine nicht spezifizierte Protokolle hierunter ist bislang auch die eFi-Protokollierung zu finden
WEB_I0802 Protokolle zur Schnittstelle BALVI iP LIMS (Lebensmittelproben)
XGEWERBE Schnittstelle XGewerbeanzeigen
Klicken Sie auf die Schaltflaumlche so besteht bei den neuen Protokolldatensaumltzen die Moumlglichkeit Detail-Informationen zum Protokollsatz zu erhalten
Release Notes BALVI Schnittstellenserver Seite 30 von 37
Seit BSS 30x ist die Anzeige der Protokolle ebenfalls farblich abgesetzt so dass Protokolleintraumlge mit Fehlern hellrot und Warnungen hellgelb hinterlegt werden
32 Jobs Mit einem Klick auf den Menuumlpunkt Jobs rufen Sie die Oberflaumlche fuumlr die Job-Konfiguration auf Daraufhin werden alle Jobs aufgelistet die fuumlr den BSS freigegeben sind Hier koumlnnen Sie Einstellungen an den Jobs vornehmen und die Jobs aktivieren bzw deaktivieren Die Beschreibungen bzw Einstellungsmoumlglichkeiten fuumlr den jeweiligen SST-Job sind nicht Bestandteil dieser Dokumentation
33 Log-Ausgaben Uumlber den Menuumlpunkt Log-Ausgaben koumlnnen Sie die Ausgabe der Protokolleintraumlge in Echtzeit beobachten
Release Notes BALVI Schnittstellenserver Seite 31 von 37
Starten Sie die Echtzeit-Protokollierung indem Sie auf die Schaltflaumlche mit dem Symbol bdquoPlayldquo (Dreieck) klicken unterbrechen Sie die Ausgabe indem Sie die auf Schaltflaumlche mit dem Symbol bdquoPauseldquo (zwei Balken) klicken
Klicken Sie auf die Schaltflaumlche bdquoAktualisierenldquo (zwei Pfeile) um die neuesten Protokolleintraumlge angezeigt zu bekommen
Klicken Sie auf das Symbol mit dem Papierkorb um die letzten Protokollmeldungen in der Anzeige zu loumlschen
Die Daten in den Protokolldateien auf der Festplatte des Servers sind davon nicht betroffen
Uumlber das Symbol bdquoLogging anpassenldquo (Schraubenschluumlssel) koumlnnen Sie die Ausgabe der Daten im Echtzeitfenster und in den Protokolldateien aumlndern jedoch ist diese Einstellung nur temporaumlr Die Standardeinstellungen koumlnnen ausschlieszliglich uumlber die Anpassung der Datei bdquologback-bssxmlldquo im Konfigurationsverzeichnis des Servers selbst geaumlndert werden
Release Notes BALVI Schnittstellenserver Seite 32 von 37
In der Logging-Parameter Konfiguration koumlnnen Sie verschiedene Parameter einstellen und uumlber die Schaltflaumlche bdquoAnwendenldquo dann sofort im Echtzeitprotokoll sehen Welche Einstellungen moumlglich sind erfahren Sie wenn es eine akute Fehlersituation gibt die detailliertere Ausgaben im Protokoll erfordert
Warnung Wenn Sie den Log-Level fuumlr ROOT oder eine andere Klasse auf TRACE einstellen werden sehr viele Protokollausgaben generiert die auch dazu fuumlhren koumlnnen dass der Server sehr langsam wird oder die Festplatte des Servers zulaumluft wenn fuumlr das Logging kein Dateilimit konfiguriert wurde
34 LogoutAbmeldung vom System Zum Abmelden waumlhlen Sie oben rechts das Kontextmenuuml
35 Cache loumlschen Der Cache wird in der Regel automatisch geloumlscht Wenn Sie jedoch gerade in BALVI iP eine Aumlnderung an den Schnittstellen eingespielt haben und moumlchten dass diese sofort wirksam wird kann die Funktion bdquoCache loumlschenldquo dazu verwendet werden dass der BALVI Schnittstellenserver die Einstellungen bei der naumlchsten Anfrage neu einliest
Release Notes BALVI Schnittstellenserver Seite 33 von 37
Release Notes BALVI Schnittstellenserver Seite 34 von 37
4 Einrichtung in BALVI iP Um die Verfahren fuumlr den BALVI Schnittstellenserver fuumlr Anwender freizuschalten wird das Objekt bdquoSystemeinstellungenldquo oder bdquoMandanten- und Benutzereinstellungenldquo verwendet Die Anpassung ist je Verfahren moumlglich so kann in BALVI iP fuumlr den Zugriff durch den BALVI Schnittstellenserver ein Benutzer bdquoAldquo am Verfahren bdquoMobilldquo berechtigt werden ein Benutzer bdquoBldquo nur am Verfahren bdquoSLA_FLESHldquo usw Die Logik ist jedoch einheitlich Je Verfahren wird durch BALVI eine Verfahrensgruppe mit dem Verfahrensnamen angelegt und mit den entsprechenden Einstellungen vorkonfiguriert welche durch das Verfahren erforderlich sind Dabei kann die Komplexitaumlt der Einstellungen variieren wie z B an den zu Version 23 verfuumlgbaren Verfahren bdquoMobilldquo und bdquoSLA_Fleshldquo ersichtlich wird
Im Verfahren BALVI Mobil sind diverse Anpassungen moumlglich welche je Bundesland oder eingesetzter Import- und Export-Variante durch den BALVI Schnittstellenserver bei der Bearbeitung von Anfragen gepruumlft werden siehe Punkt 3 Abb Mobil-Einstellung in BALVI iP
Abb Mobil-Einstellung in BALVI iP
Alle Verfahren verwenden jedoch die regulaumlre Benutzerverwaltung von BALVI iP Ein Benutzer ohne Passwort gilt fuumlr BALVI iP als gesperrt was fuumlr das Login bedeutet dass der Anwender sich nur uumlber die Active-Directory-Authentifizierung anmelden kann Ist das nicht moumlglich (bzw nicht konfiguriert) kann der Anwender sich weder in BALVI iP noch uumlber die Webservice-Schnittstelle authentifizieren
Fuumlr Dienste-Schnittstellen welche keine persoumlnliche Authentifizierung durch einen Anwender erfordern wird empfohlen einen separaten Benutzer in der Benutzerverwaltung anzulegen und ein sicheres Kennwort zu vergeben Das Anlegen von zusaumltzlichen Benutzern gilt nicht fuumlr BALVI mobil XT da beim Holen und Uumlbermitteln von Daten jeder Benutzer auch ein fachlich konfigurierter Anwender innerhalb von BALVI iP ist und die Anwendungsoberflaumlche ebenfalls zur Erfassung von Daten verwendet
Unter Punkt 2 der Abb Mobil-Einstellung in BALVI iP wird ein modales Fenster geoumlffnet (Abb BALVI mobil Benutzerverwaltung) Innerhalb dieses modalen Fensters werden mandantenweise die Benutzer fuumlr BALVI
Release Notes BALVI Schnittstellenserver Seite 35 von 37
mobil und den jeweiligen Fachbereich festgelegt Dabei ist es wichtig dass man die Haken bdquoAktiv fuumlr hellipldquo bei bdquohellip mobilldquo und bei einem Fachbereich (bdquohellip LMldquo bdquohellip FMldquo usw) setzt weil sonst uumlber den BALVI Schnittstellenserver keine Kommunikation mit BALVI iP moumlglich ist
Abb BALVI mobil Benutzerverwaltung
Alternativ zur Passwort-Authentifizierung wird wie beschrieben auch die Active-Directory-Authentifizierung angeboten Dazu muss der BALVI iP-Anwender uumlber die Schaltflaumlche bdquoDomaumlnen-Benutzer zuordnenldquo mit dem Active Directory verknuumlpft werden
Nur wenn die Active-Directory-Konfigurationen in BALVI iP und im BALVI Schnittstellenserver auf dieselbe Domaumlne verweisen sind die Domaumlnen-Zuordnung und die Active-Directory-Authentifizierung (z B uumlber BALVI mobil XT) moumlglich
Release Notes BALVI Schnittstellenserver Seite 36 von 37
5 Bekannte Probleme und Loumlsungen
51 ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner Bei der Job-Bearbeitung tritt folgender Fehler auf ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner
Behebung
Fuumlhren Sie das beiliegende IP-Patch (UPDATEexe) aus bevor Sie das WAR austauschen
52 Server startet nicht Sie finden folgende Zeilen im Protokoll (catalinaout oder bsslog)
ERROR [localhost-startStop-1] [IdentityServiceImpl] serverID must not be empty
ERROR [localhost-startStop-1] [ContextLoader] Context initialization failed
Behebung
Setzen Sie die Umgebungsvariable ldquoserverIDrdquo in der Datei bdquocontextxmlldquo
53 ORA-00942 table or view does not exist In vielen Faumlllen wird der Fehler ldquoTabelle oder View nicht vorhandenrdquo ausgeworfen (Java-Protokoll im Ordner logs von Apache Tomcat) wenn eine neue Schnittstelle eingerichtet oder ein neues BALVI iP Release bzw Update eingespielt wurde ohne anschlieszligend das aktuelle GRANT-Skript auszufuumlhren
Behebung
Fuumlhren Sie das GRANT-Skript erneut aus
54 ORA-0406x bdquoBestehender Paketstatus wurde aufgehobenldquo
ORA-04061 Bestehender Status von package body ABCXYZ wurde annulliert
ORA-04065 Ausfuumlhrung nicht erfolgreich package body ABCXYZ wurde geaumlndert oder geloumlscht
Release Notes BALVI Schnittstellenserver Seite 37 von 37
Der Fehler tritt haumlufig ein nachdem die UPDATEexe ausgefuumlhrt und in der Ausfuumlhrungsliste ein Package aktualisiert wurde Oracle merkt sich je User-Session bestimmte Werte im Package wenn der Anwender es verwendet hat Durch einen bdquoCREATE OR REPLACE PACKAGEldquo-Befehl kann dieser Status temporaumlr aufgehoben werden Normalerweise tritt dieser Fehler nach dem Update genau einmal in jeder aktiven Session auf wenn der BSS nicht neu gestartet wird
Behebung
Starten Sie nach jedem Update den BSS neu um alle laufenden Sessions zu beenden
55 Jobs sind nicht ausfuumlhrbar
1 Ein Job wird mit dem Status bdquoNicht unterstuumltztldquo angezeigt wenn fuumlr seine Ausfuumlhrung eine houmlhere Version des BSS erforderlich ist
2 Nach dem Klonen der Datenbank von der Produktions- auf die Testumgebung erhalten alle Jobs automatisch den Status bdquoDeaktiviertldquo wenn die bdquoserverIDldquo nicht identisch ist
Beide Statusaumlnderungen sind gewollt Damit soll verhindert werden dass Jobs nach einem Serverneustart oder nach einem Update automatisch starten und dabei Fehler verursachen
Um Jobs mit dem Status bdquoNicht unterstuumltztldquo nutzen und konfigurieren zu koumlnnen ist es erforderlich den BALVI Schnittstellenserver zu aktualisieren
Deaktivierte Jobs koumlnnen Sie aktivieren indem Sie den jeweiligen Job an den aktuellen Server binden und den Haken bei bdquoAktivldquo setzen
Release Notes BALVI Schnittstellenserver Seite 29 von 37
Verfahren
Die Liste der verfuumlgbaren Verfahren die bei Ihnen im System installiert sind ZB
BEFUNDEhellip Schnittstelle Befunde LM FM oder TS
PROBEhellip Schnittstelle zum Export von Proben an Labore ebenfalls Spezifisch fuumlr einzelne Fachbereiche
MOBILXT Protokolle der BALVI Mobil XT Synchronisation
WEB Allgemeine nicht spezifizierte Protokolle hierunter ist bislang auch die eFi-Protokollierung zu finden
WEB_I0802 Protokolle zur Schnittstelle BALVI iP LIMS (Lebensmittelproben)
XGEWERBE Schnittstelle XGewerbeanzeigen
Klicken Sie auf die Schaltflaumlche so besteht bei den neuen Protokolldatensaumltzen die Moumlglichkeit Detail-Informationen zum Protokollsatz zu erhalten
Release Notes BALVI Schnittstellenserver Seite 30 von 37
Seit BSS 30x ist die Anzeige der Protokolle ebenfalls farblich abgesetzt so dass Protokolleintraumlge mit Fehlern hellrot und Warnungen hellgelb hinterlegt werden
32 Jobs Mit einem Klick auf den Menuumlpunkt Jobs rufen Sie die Oberflaumlche fuumlr die Job-Konfiguration auf Daraufhin werden alle Jobs aufgelistet die fuumlr den BSS freigegeben sind Hier koumlnnen Sie Einstellungen an den Jobs vornehmen und die Jobs aktivieren bzw deaktivieren Die Beschreibungen bzw Einstellungsmoumlglichkeiten fuumlr den jeweiligen SST-Job sind nicht Bestandteil dieser Dokumentation
33 Log-Ausgaben Uumlber den Menuumlpunkt Log-Ausgaben koumlnnen Sie die Ausgabe der Protokolleintraumlge in Echtzeit beobachten
Release Notes BALVI Schnittstellenserver Seite 31 von 37
Starten Sie die Echtzeit-Protokollierung indem Sie auf die Schaltflaumlche mit dem Symbol bdquoPlayldquo (Dreieck) klicken unterbrechen Sie die Ausgabe indem Sie die auf Schaltflaumlche mit dem Symbol bdquoPauseldquo (zwei Balken) klicken
Klicken Sie auf die Schaltflaumlche bdquoAktualisierenldquo (zwei Pfeile) um die neuesten Protokolleintraumlge angezeigt zu bekommen
Klicken Sie auf das Symbol mit dem Papierkorb um die letzten Protokollmeldungen in der Anzeige zu loumlschen
Die Daten in den Protokolldateien auf der Festplatte des Servers sind davon nicht betroffen
Uumlber das Symbol bdquoLogging anpassenldquo (Schraubenschluumlssel) koumlnnen Sie die Ausgabe der Daten im Echtzeitfenster und in den Protokolldateien aumlndern jedoch ist diese Einstellung nur temporaumlr Die Standardeinstellungen koumlnnen ausschlieszliglich uumlber die Anpassung der Datei bdquologback-bssxmlldquo im Konfigurationsverzeichnis des Servers selbst geaumlndert werden
Release Notes BALVI Schnittstellenserver Seite 32 von 37
In der Logging-Parameter Konfiguration koumlnnen Sie verschiedene Parameter einstellen und uumlber die Schaltflaumlche bdquoAnwendenldquo dann sofort im Echtzeitprotokoll sehen Welche Einstellungen moumlglich sind erfahren Sie wenn es eine akute Fehlersituation gibt die detailliertere Ausgaben im Protokoll erfordert
Warnung Wenn Sie den Log-Level fuumlr ROOT oder eine andere Klasse auf TRACE einstellen werden sehr viele Protokollausgaben generiert die auch dazu fuumlhren koumlnnen dass der Server sehr langsam wird oder die Festplatte des Servers zulaumluft wenn fuumlr das Logging kein Dateilimit konfiguriert wurde
34 LogoutAbmeldung vom System Zum Abmelden waumlhlen Sie oben rechts das Kontextmenuuml
35 Cache loumlschen Der Cache wird in der Regel automatisch geloumlscht Wenn Sie jedoch gerade in BALVI iP eine Aumlnderung an den Schnittstellen eingespielt haben und moumlchten dass diese sofort wirksam wird kann die Funktion bdquoCache loumlschenldquo dazu verwendet werden dass der BALVI Schnittstellenserver die Einstellungen bei der naumlchsten Anfrage neu einliest
Release Notes BALVI Schnittstellenserver Seite 33 von 37
Release Notes BALVI Schnittstellenserver Seite 34 von 37
4 Einrichtung in BALVI iP Um die Verfahren fuumlr den BALVI Schnittstellenserver fuumlr Anwender freizuschalten wird das Objekt bdquoSystemeinstellungenldquo oder bdquoMandanten- und Benutzereinstellungenldquo verwendet Die Anpassung ist je Verfahren moumlglich so kann in BALVI iP fuumlr den Zugriff durch den BALVI Schnittstellenserver ein Benutzer bdquoAldquo am Verfahren bdquoMobilldquo berechtigt werden ein Benutzer bdquoBldquo nur am Verfahren bdquoSLA_FLESHldquo usw Die Logik ist jedoch einheitlich Je Verfahren wird durch BALVI eine Verfahrensgruppe mit dem Verfahrensnamen angelegt und mit den entsprechenden Einstellungen vorkonfiguriert welche durch das Verfahren erforderlich sind Dabei kann die Komplexitaumlt der Einstellungen variieren wie z B an den zu Version 23 verfuumlgbaren Verfahren bdquoMobilldquo und bdquoSLA_Fleshldquo ersichtlich wird
Im Verfahren BALVI Mobil sind diverse Anpassungen moumlglich welche je Bundesland oder eingesetzter Import- und Export-Variante durch den BALVI Schnittstellenserver bei der Bearbeitung von Anfragen gepruumlft werden siehe Punkt 3 Abb Mobil-Einstellung in BALVI iP
Abb Mobil-Einstellung in BALVI iP
Alle Verfahren verwenden jedoch die regulaumlre Benutzerverwaltung von BALVI iP Ein Benutzer ohne Passwort gilt fuumlr BALVI iP als gesperrt was fuumlr das Login bedeutet dass der Anwender sich nur uumlber die Active-Directory-Authentifizierung anmelden kann Ist das nicht moumlglich (bzw nicht konfiguriert) kann der Anwender sich weder in BALVI iP noch uumlber die Webservice-Schnittstelle authentifizieren
Fuumlr Dienste-Schnittstellen welche keine persoumlnliche Authentifizierung durch einen Anwender erfordern wird empfohlen einen separaten Benutzer in der Benutzerverwaltung anzulegen und ein sicheres Kennwort zu vergeben Das Anlegen von zusaumltzlichen Benutzern gilt nicht fuumlr BALVI mobil XT da beim Holen und Uumlbermitteln von Daten jeder Benutzer auch ein fachlich konfigurierter Anwender innerhalb von BALVI iP ist und die Anwendungsoberflaumlche ebenfalls zur Erfassung von Daten verwendet
Unter Punkt 2 der Abb Mobil-Einstellung in BALVI iP wird ein modales Fenster geoumlffnet (Abb BALVI mobil Benutzerverwaltung) Innerhalb dieses modalen Fensters werden mandantenweise die Benutzer fuumlr BALVI
Release Notes BALVI Schnittstellenserver Seite 35 von 37
mobil und den jeweiligen Fachbereich festgelegt Dabei ist es wichtig dass man die Haken bdquoAktiv fuumlr hellipldquo bei bdquohellip mobilldquo und bei einem Fachbereich (bdquohellip LMldquo bdquohellip FMldquo usw) setzt weil sonst uumlber den BALVI Schnittstellenserver keine Kommunikation mit BALVI iP moumlglich ist
Abb BALVI mobil Benutzerverwaltung
Alternativ zur Passwort-Authentifizierung wird wie beschrieben auch die Active-Directory-Authentifizierung angeboten Dazu muss der BALVI iP-Anwender uumlber die Schaltflaumlche bdquoDomaumlnen-Benutzer zuordnenldquo mit dem Active Directory verknuumlpft werden
Nur wenn die Active-Directory-Konfigurationen in BALVI iP und im BALVI Schnittstellenserver auf dieselbe Domaumlne verweisen sind die Domaumlnen-Zuordnung und die Active-Directory-Authentifizierung (z B uumlber BALVI mobil XT) moumlglich
Release Notes BALVI Schnittstellenserver Seite 36 von 37
5 Bekannte Probleme und Loumlsungen
51 ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner Bei der Job-Bearbeitung tritt folgender Fehler auf ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner
Behebung
Fuumlhren Sie das beiliegende IP-Patch (UPDATEexe) aus bevor Sie das WAR austauschen
52 Server startet nicht Sie finden folgende Zeilen im Protokoll (catalinaout oder bsslog)
ERROR [localhost-startStop-1] [IdentityServiceImpl] serverID must not be empty
ERROR [localhost-startStop-1] [ContextLoader] Context initialization failed
Behebung
Setzen Sie die Umgebungsvariable ldquoserverIDrdquo in der Datei bdquocontextxmlldquo
53 ORA-00942 table or view does not exist In vielen Faumlllen wird der Fehler ldquoTabelle oder View nicht vorhandenrdquo ausgeworfen (Java-Protokoll im Ordner logs von Apache Tomcat) wenn eine neue Schnittstelle eingerichtet oder ein neues BALVI iP Release bzw Update eingespielt wurde ohne anschlieszligend das aktuelle GRANT-Skript auszufuumlhren
Behebung
Fuumlhren Sie das GRANT-Skript erneut aus
54 ORA-0406x bdquoBestehender Paketstatus wurde aufgehobenldquo
ORA-04061 Bestehender Status von package body ABCXYZ wurde annulliert
ORA-04065 Ausfuumlhrung nicht erfolgreich package body ABCXYZ wurde geaumlndert oder geloumlscht
Release Notes BALVI Schnittstellenserver Seite 37 von 37
Der Fehler tritt haumlufig ein nachdem die UPDATEexe ausgefuumlhrt und in der Ausfuumlhrungsliste ein Package aktualisiert wurde Oracle merkt sich je User-Session bestimmte Werte im Package wenn der Anwender es verwendet hat Durch einen bdquoCREATE OR REPLACE PACKAGEldquo-Befehl kann dieser Status temporaumlr aufgehoben werden Normalerweise tritt dieser Fehler nach dem Update genau einmal in jeder aktiven Session auf wenn der BSS nicht neu gestartet wird
Behebung
Starten Sie nach jedem Update den BSS neu um alle laufenden Sessions zu beenden
55 Jobs sind nicht ausfuumlhrbar
1 Ein Job wird mit dem Status bdquoNicht unterstuumltztldquo angezeigt wenn fuumlr seine Ausfuumlhrung eine houmlhere Version des BSS erforderlich ist
2 Nach dem Klonen der Datenbank von der Produktions- auf die Testumgebung erhalten alle Jobs automatisch den Status bdquoDeaktiviertldquo wenn die bdquoserverIDldquo nicht identisch ist
Beide Statusaumlnderungen sind gewollt Damit soll verhindert werden dass Jobs nach einem Serverneustart oder nach einem Update automatisch starten und dabei Fehler verursachen
Um Jobs mit dem Status bdquoNicht unterstuumltztldquo nutzen und konfigurieren zu koumlnnen ist es erforderlich den BALVI Schnittstellenserver zu aktualisieren
Deaktivierte Jobs koumlnnen Sie aktivieren indem Sie den jeweiligen Job an den aktuellen Server binden und den Haken bei bdquoAktivldquo setzen
Release Notes BALVI Schnittstellenserver Seite 30 von 37
Seit BSS 30x ist die Anzeige der Protokolle ebenfalls farblich abgesetzt so dass Protokolleintraumlge mit Fehlern hellrot und Warnungen hellgelb hinterlegt werden
32 Jobs Mit einem Klick auf den Menuumlpunkt Jobs rufen Sie die Oberflaumlche fuumlr die Job-Konfiguration auf Daraufhin werden alle Jobs aufgelistet die fuumlr den BSS freigegeben sind Hier koumlnnen Sie Einstellungen an den Jobs vornehmen und die Jobs aktivieren bzw deaktivieren Die Beschreibungen bzw Einstellungsmoumlglichkeiten fuumlr den jeweiligen SST-Job sind nicht Bestandteil dieser Dokumentation
33 Log-Ausgaben Uumlber den Menuumlpunkt Log-Ausgaben koumlnnen Sie die Ausgabe der Protokolleintraumlge in Echtzeit beobachten
Release Notes BALVI Schnittstellenserver Seite 31 von 37
Starten Sie die Echtzeit-Protokollierung indem Sie auf die Schaltflaumlche mit dem Symbol bdquoPlayldquo (Dreieck) klicken unterbrechen Sie die Ausgabe indem Sie die auf Schaltflaumlche mit dem Symbol bdquoPauseldquo (zwei Balken) klicken
Klicken Sie auf die Schaltflaumlche bdquoAktualisierenldquo (zwei Pfeile) um die neuesten Protokolleintraumlge angezeigt zu bekommen
Klicken Sie auf das Symbol mit dem Papierkorb um die letzten Protokollmeldungen in der Anzeige zu loumlschen
Die Daten in den Protokolldateien auf der Festplatte des Servers sind davon nicht betroffen
Uumlber das Symbol bdquoLogging anpassenldquo (Schraubenschluumlssel) koumlnnen Sie die Ausgabe der Daten im Echtzeitfenster und in den Protokolldateien aumlndern jedoch ist diese Einstellung nur temporaumlr Die Standardeinstellungen koumlnnen ausschlieszliglich uumlber die Anpassung der Datei bdquologback-bssxmlldquo im Konfigurationsverzeichnis des Servers selbst geaumlndert werden
Release Notes BALVI Schnittstellenserver Seite 32 von 37
In der Logging-Parameter Konfiguration koumlnnen Sie verschiedene Parameter einstellen und uumlber die Schaltflaumlche bdquoAnwendenldquo dann sofort im Echtzeitprotokoll sehen Welche Einstellungen moumlglich sind erfahren Sie wenn es eine akute Fehlersituation gibt die detailliertere Ausgaben im Protokoll erfordert
Warnung Wenn Sie den Log-Level fuumlr ROOT oder eine andere Klasse auf TRACE einstellen werden sehr viele Protokollausgaben generiert die auch dazu fuumlhren koumlnnen dass der Server sehr langsam wird oder die Festplatte des Servers zulaumluft wenn fuumlr das Logging kein Dateilimit konfiguriert wurde
34 LogoutAbmeldung vom System Zum Abmelden waumlhlen Sie oben rechts das Kontextmenuuml
35 Cache loumlschen Der Cache wird in der Regel automatisch geloumlscht Wenn Sie jedoch gerade in BALVI iP eine Aumlnderung an den Schnittstellen eingespielt haben und moumlchten dass diese sofort wirksam wird kann die Funktion bdquoCache loumlschenldquo dazu verwendet werden dass der BALVI Schnittstellenserver die Einstellungen bei der naumlchsten Anfrage neu einliest
Release Notes BALVI Schnittstellenserver Seite 33 von 37
Release Notes BALVI Schnittstellenserver Seite 34 von 37
4 Einrichtung in BALVI iP Um die Verfahren fuumlr den BALVI Schnittstellenserver fuumlr Anwender freizuschalten wird das Objekt bdquoSystemeinstellungenldquo oder bdquoMandanten- und Benutzereinstellungenldquo verwendet Die Anpassung ist je Verfahren moumlglich so kann in BALVI iP fuumlr den Zugriff durch den BALVI Schnittstellenserver ein Benutzer bdquoAldquo am Verfahren bdquoMobilldquo berechtigt werden ein Benutzer bdquoBldquo nur am Verfahren bdquoSLA_FLESHldquo usw Die Logik ist jedoch einheitlich Je Verfahren wird durch BALVI eine Verfahrensgruppe mit dem Verfahrensnamen angelegt und mit den entsprechenden Einstellungen vorkonfiguriert welche durch das Verfahren erforderlich sind Dabei kann die Komplexitaumlt der Einstellungen variieren wie z B an den zu Version 23 verfuumlgbaren Verfahren bdquoMobilldquo und bdquoSLA_Fleshldquo ersichtlich wird
Im Verfahren BALVI Mobil sind diverse Anpassungen moumlglich welche je Bundesland oder eingesetzter Import- und Export-Variante durch den BALVI Schnittstellenserver bei der Bearbeitung von Anfragen gepruumlft werden siehe Punkt 3 Abb Mobil-Einstellung in BALVI iP
Abb Mobil-Einstellung in BALVI iP
Alle Verfahren verwenden jedoch die regulaumlre Benutzerverwaltung von BALVI iP Ein Benutzer ohne Passwort gilt fuumlr BALVI iP als gesperrt was fuumlr das Login bedeutet dass der Anwender sich nur uumlber die Active-Directory-Authentifizierung anmelden kann Ist das nicht moumlglich (bzw nicht konfiguriert) kann der Anwender sich weder in BALVI iP noch uumlber die Webservice-Schnittstelle authentifizieren
Fuumlr Dienste-Schnittstellen welche keine persoumlnliche Authentifizierung durch einen Anwender erfordern wird empfohlen einen separaten Benutzer in der Benutzerverwaltung anzulegen und ein sicheres Kennwort zu vergeben Das Anlegen von zusaumltzlichen Benutzern gilt nicht fuumlr BALVI mobil XT da beim Holen und Uumlbermitteln von Daten jeder Benutzer auch ein fachlich konfigurierter Anwender innerhalb von BALVI iP ist und die Anwendungsoberflaumlche ebenfalls zur Erfassung von Daten verwendet
Unter Punkt 2 der Abb Mobil-Einstellung in BALVI iP wird ein modales Fenster geoumlffnet (Abb BALVI mobil Benutzerverwaltung) Innerhalb dieses modalen Fensters werden mandantenweise die Benutzer fuumlr BALVI
Release Notes BALVI Schnittstellenserver Seite 35 von 37
mobil und den jeweiligen Fachbereich festgelegt Dabei ist es wichtig dass man die Haken bdquoAktiv fuumlr hellipldquo bei bdquohellip mobilldquo und bei einem Fachbereich (bdquohellip LMldquo bdquohellip FMldquo usw) setzt weil sonst uumlber den BALVI Schnittstellenserver keine Kommunikation mit BALVI iP moumlglich ist
Abb BALVI mobil Benutzerverwaltung
Alternativ zur Passwort-Authentifizierung wird wie beschrieben auch die Active-Directory-Authentifizierung angeboten Dazu muss der BALVI iP-Anwender uumlber die Schaltflaumlche bdquoDomaumlnen-Benutzer zuordnenldquo mit dem Active Directory verknuumlpft werden
Nur wenn die Active-Directory-Konfigurationen in BALVI iP und im BALVI Schnittstellenserver auf dieselbe Domaumlne verweisen sind die Domaumlnen-Zuordnung und die Active-Directory-Authentifizierung (z B uumlber BALVI mobil XT) moumlglich
Release Notes BALVI Schnittstellenserver Seite 36 von 37
5 Bekannte Probleme und Loumlsungen
51 ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner Bei der Job-Bearbeitung tritt folgender Fehler auf ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner
Behebung
Fuumlhren Sie das beiliegende IP-Patch (UPDATEexe) aus bevor Sie das WAR austauschen
52 Server startet nicht Sie finden folgende Zeilen im Protokoll (catalinaout oder bsslog)
ERROR [localhost-startStop-1] [IdentityServiceImpl] serverID must not be empty
ERROR [localhost-startStop-1] [ContextLoader] Context initialization failed
Behebung
Setzen Sie die Umgebungsvariable ldquoserverIDrdquo in der Datei bdquocontextxmlldquo
53 ORA-00942 table or view does not exist In vielen Faumlllen wird der Fehler ldquoTabelle oder View nicht vorhandenrdquo ausgeworfen (Java-Protokoll im Ordner logs von Apache Tomcat) wenn eine neue Schnittstelle eingerichtet oder ein neues BALVI iP Release bzw Update eingespielt wurde ohne anschlieszligend das aktuelle GRANT-Skript auszufuumlhren
Behebung
Fuumlhren Sie das GRANT-Skript erneut aus
54 ORA-0406x bdquoBestehender Paketstatus wurde aufgehobenldquo
ORA-04061 Bestehender Status von package body ABCXYZ wurde annulliert
ORA-04065 Ausfuumlhrung nicht erfolgreich package body ABCXYZ wurde geaumlndert oder geloumlscht
Release Notes BALVI Schnittstellenserver Seite 37 von 37
Der Fehler tritt haumlufig ein nachdem die UPDATEexe ausgefuumlhrt und in der Ausfuumlhrungsliste ein Package aktualisiert wurde Oracle merkt sich je User-Session bestimmte Werte im Package wenn der Anwender es verwendet hat Durch einen bdquoCREATE OR REPLACE PACKAGEldquo-Befehl kann dieser Status temporaumlr aufgehoben werden Normalerweise tritt dieser Fehler nach dem Update genau einmal in jeder aktiven Session auf wenn der BSS nicht neu gestartet wird
Behebung
Starten Sie nach jedem Update den BSS neu um alle laufenden Sessions zu beenden
55 Jobs sind nicht ausfuumlhrbar
1 Ein Job wird mit dem Status bdquoNicht unterstuumltztldquo angezeigt wenn fuumlr seine Ausfuumlhrung eine houmlhere Version des BSS erforderlich ist
2 Nach dem Klonen der Datenbank von der Produktions- auf die Testumgebung erhalten alle Jobs automatisch den Status bdquoDeaktiviertldquo wenn die bdquoserverIDldquo nicht identisch ist
Beide Statusaumlnderungen sind gewollt Damit soll verhindert werden dass Jobs nach einem Serverneustart oder nach einem Update automatisch starten und dabei Fehler verursachen
Um Jobs mit dem Status bdquoNicht unterstuumltztldquo nutzen und konfigurieren zu koumlnnen ist es erforderlich den BALVI Schnittstellenserver zu aktualisieren
Deaktivierte Jobs koumlnnen Sie aktivieren indem Sie den jeweiligen Job an den aktuellen Server binden und den Haken bei bdquoAktivldquo setzen
Release Notes BALVI Schnittstellenserver Seite 31 von 37
Starten Sie die Echtzeit-Protokollierung indem Sie auf die Schaltflaumlche mit dem Symbol bdquoPlayldquo (Dreieck) klicken unterbrechen Sie die Ausgabe indem Sie die auf Schaltflaumlche mit dem Symbol bdquoPauseldquo (zwei Balken) klicken
Klicken Sie auf die Schaltflaumlche bdquoAktualisierenldquo (zwei Pfeile) um die neuesten Protokolleintraumlge angezeigt zu bekommen
Klicken Sie auf das Symbol mit dem Papierkorb um die letzten Protokollmeldungen in der Anzeige zu loumlschen
Die Daten in den Protokolldateien auf der Festplatte des Servers sind davon nicht betroffen
Uumlber das Symbol bdquoLogging anpassenldquo (Schraubenschluumlssel) koumlnnen Sie die Ausgabe der Daten im Echtzeitfenster und in den Protokolldateien aumlndern jedoch ist diese Einstellung nur temporaumlr Die Standardeinstellungen koumlnnen ausschlieszliglich uumlber die Anpassung der Datei bdquologback-bssxmlldquo im Konfigurationsverzeichnis des Servers selbst geaumlndert werden
Release Notes BALVI Schnittstellenserver Seite 32 von 37
In der Logging-Parameter Konfiguration koumlnnen Sie verschiedene Parameter einstellen und uumlber die Schaltflaumlche bdquoAnwendenldquo dann sofort im Echtzeitprotokoll sehen Welche Einstellungen moumlglich sind erfahren Sie wenn es eine akute Fehlersituation gibt die detailliertere Ausgaben im Protokoll erfordert
Warnung Wenn Sie den Log-Level fuumlr ROOT oder eine andere Klasse auf TRACE einstellen werden sehr viele Protokollausgaben generiert die auch dazu fuumlhren koumlnnen dass der Server sehr langsam wird oder die Festplatte des Servers zulaumluft wenn fuumlr das Logging kein Dateilimit konfiguriert wurde
34 LogoutAbmeldung vom System Zum Abmelden waumlhlen Sie oben rechts das Kontextmenuuml
35 Cache loumlschen Der Cache wird in der Regel automatisch geloumlscht Wenn Sie jedoch gerade in BALVI iP eine Aumlnderung an den Schnittstellen eingespielt haben und moumlchten dass diese sofort wirksam wird kann die Funktion bdquoCache loumlschenldquo dazu verwendet werden dass der BALVI Schnittstellenserver die Einstellungen bei der naumlchsten Anfrage neu einliest
Release Notes BALVI Schnittstellenserver Seite 33 von 37
Release Notes BALVI Schnittstellenserver Seite 34 von 37
4 Einrichtung in BALVI iP Um die Verfahren fuumlr den BALVI Schnittstellenserver fuumlr Anwender freizuschalten wird das Objekt bdquoSystemeinstellungenldquo oder bdquoMandanten- und Benutzereinstellungenldquo verwendet Die Anpassung ist je Verfahren moumlglich so kann in BALVI iP fuumlr den Zugriff durch den BALVI Schnittstellenserver ein Benutzer bdquoAldquo am Verfahren bdquoMobilldquo berechtigt werden ein Benutzer bdquoBldquo nur am Verfahren bdquoSLA_FLESHldquo usw Die Logik ist jedoch einheitlich Je Verfahren wird durch BALVI eine Verfahrensgruppe mit dem Verfahrensnamen angelegt und mit den entsprechenden Einstellungen vorkonfiguriert welche durch das Verfahren erforderlich sind Dabei kann die Komplexitaumlt der Einstellungen variieren wie z B an den zu Version 23 verfuumlgbaren Verfahren bdquoMobilldquo und bdquoSLA_Fleshldquo ersichtlich wird
Im Verfahren BALVI Mobil sind diverse Anpassungen moumlglich welche je Bundesland oder eingesetzter Import- und Export-Variante durch den BALVI Schnittstellenserver bei der Bearbeitung von Anfragen gepruumlft werden siehe Punkt 3 Abb Mobil-Einstellung in BALVI iP
Abb Mobil-Einstellung in BALVI iP
Alle Verfahren verwenden jedoch die regulaumlre Benutzerverwaltung von BALVI iP Ein Benutzer ohne Passwort gilt fuumlr BALVI iP als gesperrt was fuumlr das Login bedeutet dass der Anwender sich nur uumlber die Active-Directory-Authentifizierung anmelden kann Ist das nicht moumlglich (bzw nicht konfiguriert) kann der Anwender sich weder in BALVI iP noch uumlber die Webservice-Schnittstelle authentifizieren
Fuumlr Dienste-Schnittstellen welche keine persoumlnliche Authentifizierung durch einen Anwender erfordern wird empfohlen einen separaten Benutzer in der Benutzerverwaltung anzulegen und ein sicheres Kennwort zu vergeben Das Anlegen von zusaumltzlichen Benutzern gilt nicht fuumlr BALVI mobil XT da beim Holen und Uumlbermitteln von Daten jeder Benutzer auch ein fachlich konfigurierter Anwender innerhalb von BALVI iP ist und die Anwendungsoberflaumlche ebenfalls zur Erfassung von Daten verwendet
Unter Punkt 2 der Abb Mobil-Einstellung in BALVI iP wird ein modales Fenster geoumlffnet (Abb BALVI mobil Benutzerverwaltung) Innerhalb dieses modalen Fensters werden mandantenweise die Benutzer fuumlr BALVI
Release Notes BALVI Schnittstellenserver Seite 35 von 37
mobil und den jeweiligen Fachbereich festgelegt Dabei ist es wichtig dass man die Haken bdquoAktiv fuumlr hellipldquo bei bdquohellip mobilldquo und bei einem Fachbereich (bdquohellip LMldquo bdquohellip FMldquo usw) setzt weil sonst uumlber den BALVI Schnittstellenserver keine Kommunikation mit BALVI iP moumlglich ist
Abb BALVI mobil Benutzerverwaltung
Alternativ zur Passwort-Authentifizierung wird wie beschrieben auch die Active-Directory-Authentifizierung angeboten Dazu muss der BALVI iP-Anwender uumlber die Schaltflaumlche bdquoDomaumlnen-Benutzer zuordnenldquo mit dem Active Directory verknuumlpft werden
Nur wenn die Active-Directory-Konfigurationen in BALVI iP und im BALVI Schnittstellenserver auf dieselbe Domaumlne verweisen sind die Domaumlnen-Zuordnung und die Active-Directory-Authentifizierung (z B uumlber BALVI mobil XT) moumlglich
Release Notes BALVI Schnittstellenserver Seite 36 von 37
5 Bekannte Probleme und Loumlsungen
51 ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner Bei der Job-Bearbeitung tritt folgender Fehler auf ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner
Behebung
Fuumlhren Sie das beiliegende IP-Patch (UPDATEexe) aus bevor Sie das WAR austauschen
52 Server startet nicht Sie finden folgende Zeilen im Protokoll (catalinaout oder bsslog)
ERROR [localhost-startStop-1] [IdentityServiceImpl] serverID must not be empty
ERROR [localhost-startStop-1] [ContextLoader] Context initialization failed
Behebung
Setzen Sie die Umgebungsvariable ldquoserverIDrdquo in der Datei bdquocontextxmlldquo
53 ORA-00942 table or view does not exist In vielen Faumlllen wird der Fehler ldquoTabelle oder View nicht vorhandenrdquo ausgeworfen (Java-Protokoll im Ordner logs von Apache Tomcat) wenn eine neue Schnittstelle eingerichtet oder ein neues BALVI iP Release bzw Update eingespielt wurde ohne anschlieszligend das aktuelle GRANT-Skript auszufuumlhren
Behebung
Fuumlhren Sie das GRANT-Skript erneut aus
54 ORA-0406x bdquoBestehender Paketstatus wurde aufgehobenldquo
ORA-04061 Bestehender Status von package body ABCXYZ wurde annulliert
ORA-04065 Ausfuumlhrung nicht erfolgreich package body ABCXYZ wurde geaumlndert oder geloumlscht
Release Notes BALVI Schnittstellenserver Seite 37 von 37
Der Fehler tritt haumlufig ein nachdem die UPDATEexe ausgefuumlhrt und in der Ausfuumlhrungsliste ein Package aktualisiert wurde Oracle merkt sich je User-Session bestimmte Werte im Package wenn der Anwender es verwendet hat Durch einen bdquoCREATE OR REPLACE PACKAGEldquo-Befehl kann dieser Status temporaumlr aufgehoben werden Normalerweise tritt dieser Fehler nach dem Update genau einmal in jeder aktiven Session auf wenn der BSS nicht neu gestartet wird
Behebung
Starten Sie nach jedem Update den BSS neu um alle laufenden Sessions zu beenden
55 Jobs sind nicht ausfuumlhrbar
1 Ein Job wird mit dem Status bdquoNicht unterstuumltztldquo angezeigt wenn fuumlr seine Ausfuumlhrung eine houmlhere Version des BSS erforderlich ist
2 Nach dem Klonen der Datenbank von der Produktions- auf die Testumgebung erhalten alle Jobs automatisch den Status bdquoDeaktiviertldquo wenn die bdquoserverIDldquo nicht identisch ist
Beide Statusaumlnderungen sind gewollt Damit soll verhindert werden dass Jobs nach einem Serverneustart oder nach einem Update automatisch starten und dabei Fehler verursachen
Um Jobs mit dem Status bdquoNicht unterstuumltztldquo nutzen und konfigurieren zu koumlnnen ist es erforderlich den BALVI Schnittstellenserver zu aktualisieren
Deaktivierte Jobs koumlnnen Sie aktivieren indem Sie den jeweiligen Job an den aktuellen Server binden und den Haken bei bdquoAktivldquo setzen
Release Notes BALVI Schnittstellenserver Seite 32 von 37
In der Logging-Parameter Konfiguration koumlnnen Sie verschiedene Parameter einstellen und uumlber die Schaltflaumlche bdquoAnwendenldquo dann sofort im Echtzeitprotokoll sehen Welche Einstellungen moumlglich sind erfahren Sie wenn es eine akute Fehlersituation gibt die detailliertere Ausgaben im Protokoll erfordert
Warnung Wenn Sie den Log-Level fuumlr ROOT oder eine andere Klasse auf TRACE einstellen werden sehr viele Protokollausgaben generiert die auch dazu fuumlhren koumlnnen dass der Server sehr langsam wird oder die Festplatte des Servers zulaumluft wenn fuumlr das Logging kein Dateilimit konfiguriert wurde
34 LogoutAbmeldung vom System Zum Abmelden waumlhlen Sie oben rechts das Kontextmenuuml
35 Cache loumlschen Der Cache wird in der Regel automatisch geloumlscht Wenn Sie jedoch gerade in BALVI iP eine Aumlnderung an den Schnittstellen eingespielt haben und moumlchten dass diese sofort wirksam wird kann die Funktion bdquoCache loumlschenldquo dazu verwendet werden dass der BALVI Schnittstellenserver die Einstellungen bei der naumlchsten Anfrage neu einliest
Release Notes BALVI Schnittstellenserver Seite 33 von 37
Release Notes BALVI Schnittstellenserver Seite 34 von 37
4 Einrichtung in BALVI iP Um die Verfahren fuumlr den BALVI Schnittstellenserver fuumlr Anwender freizuschalten wird das Objekt bdquoSystemeinstellungenldquo oder bdquoMandanten- und Benutzereinstellungenldquo verwendet Die Anpassung ist je Verfahren moumlglich so kann in BALVI iP fuumlr den Zugriff durch den BALVI Schnittstellenserver ein Benutzer bdquoAldquo am Verfahren bdquoMobilldquo berechtigt werden ein Benutzer bdquoBldquo nur am Verfahren bdquoSLA_FLESHldquo usw Die Logik ist jedoch einheitlich Je Verfahren wird durch BALVI eine Verfahrensgruppe mit dem Verfahrensnamen angelegt und mit den entsprechenden Einstellungen vorkonfiguriert welche durch das Verfahren erforderlich sind Dabei kann die Komplexitaumlt der Einstellungen variieren wie z B an den zu Version 23 verfuumlgbaren Verfahren bdquoMobilldquo und bdquoSLA_Fleshldquo ersichtlich wird
Im Verfahren BALVI Mobil sind diverse Anpassungen moumlglich welche je Bundesland oder eingesetzter Import- und Export-Variante durch den BALVI Schnittstellenserver bei der Bearbeitung von Anfragen gepruumlft werden siehe Punkt 3 Abb Mobil-Einstellung in BALVI iP
Abb Mobil-Einstellung in BALVI iP
Alle Verfahren verwenden jedoch die regulaumlre Benutzerverwaltung von BALVI iP Ein Benutzer ohne Passwort gilt fuumlr BALVI iP als gesperrt was fuumlr das Login bedeutet dass der Anwender sich nur uumlber die Active-Directory-Authentifizierung anmelden kann Ist das nicht moumlglich (bzw nicht konfiguriert) kann der Anwender sich weder in BALVI iP noch uumlber die Webservice-Schnittstelle authentifizieren
Fuumlr Dienste-Schnittstellen welche keine persoumlnliche Authentifizierung durch einen Anwender erfordern wird empfohlen einen separaten Benutzer in der Benutzerverwaltung anzulegen und ein sicheres Kennwort zu vergeben Das Anlegen von zusaumltzlichen Benutzern gilt nicht fuumlr BALVI mobil XT da beim Holen und Uumlbermitteln von Daten jeder Benutzer auch ein fachlich konfigurierter Anwender innerhalb von BALVI iP ist und die Anwendungsoberflaumlche ebenfalls zur Erfassung von Daten verwendet
Unter Punkt 2 der Abb Mobil-Einstellung in BALVI iP wird ein modales Fenster geoumlffnet (Abb BALVI mobil Benutzerverwaltung) Innerhalb dieses modalen Fensters werden mandantenweise die Benutzer fuumlr BALVI
Release Notes BALVI Schnittstellenserver Seite 35 von 37
mobil und den jeweiligen Fachbereich festgelegt Dabei ist es wichtig dass man die Haken bdquoAktiv fuumlr hellipldquo bei bdquohellip mobilldquo und bei einem Fachbereich (bdquohellip LMldquo bdquohellip FMldquo usw) setzt weil sonst uumlber den BALVI Schnittstellenserver keine Kommunikation mit BALVI iP moumlglich ist
Abb BALVI mobil Benutzerverwaltung
Alternativ zur Passwort-Authentifizierung wird wie beschrieben auch die Active-Directory-Authentifizierung angeboten Dazu muss der BALVI iP-Anwender uumlber die Schaltflaumlche bdquoDomaumlnen-Benutzer zuordnenldquo mit dem Active Directory verknuumlpft werden
Nur wenn die Active-Directory-Konfigurationen in BALVI iP und im BALVI Schnittstellenserver auf dieselbe Domaumlne verweisen sind die Domaumlnen-Zuordnung und die Active-Directory-Authentifizierung (z B uumlber BALVI mobil XT) moumlglich
Release Notes BALVI Schnittstellenserver Seite 36 von 37
5 Bekannte Probleme und Loumlsungen
51 ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner Bei der Job-Bearbeitung tritt folgender Fehler auf ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner
Behebung
Fuumlhren Sie das beiliegende IP-Patch (UPDATEexe) aus bevor Sie das WAR austauschen
52 Server startet nicht Sie finden folgende Zeilen im Protokoll (catalinaout oder bsslog)
ERROR [localhost-startStop-1] [IdentityServiceImpl] serverID must not be empty
ERROR [localhost-startStop-1] [ContextLoader] Context initialization failed
Behebung
Setzen Sie die Umgebungsvariable ldquoserverIDrdquo in der Datei bdquocontextxmlldquo
53 ORA-00942 table or view does not exist In vielen Faumlllen wird der Fehler ldquoTabelle oder View nicht vorhandenrdquo ausgeworfen (Java-Protokoll im Ordner logs von Apache Tomcat) wenn eine neue Schnittstelle eingerichtet oder ein neues BALVI iP Release bzw Update eingespielt wurde ohne anschlieszligend das aktuelle GRANT-Skript auszufuumlhren
Behebung
Fuumlhren Sie das GRANT-Skript erneut aus
54 ORA-0406x bdquoBestehender Paketstatus wurde aufgehobenldquo
ORA-04061 Bestehender Status von package body ABCXYZ wurde annulliert
ORA-04065 Ausfuumlhrung nicht erfolgreich package body ABCXYZ wurde geaumlndert oder geloumlscht
Release Notes BALVI Schnittstellenserver Seite 37 von 37
Der Fehler tritt haumlufig ein nachdem die UPDATEexe ausgefuumlhrt und in der Ausfuumlhrungsliste ein Package aktualisiert wurde Oracle merkt sich je User-Session bestimmte Werte im Package wenn der Anwender es verwendet hat Durch einen bdquoCREATE OR REPLACE PACKAGEldquo-Befehl kann dieser Status temporaumlr aufgehoben werden Normalerweise tritt dieser Fehler nach dem Update genau einmal in jeder aktiven Session auf wenn der BSS nicht neu gestartet wird
Behebung
Starten Sie nach jedem Update den BSS neu um alle laufenden Sessions zu beenden
55 Jobs sind nicht ausfuumlhrbar
1 Ein Job wird mit dem Status bdquoNicht unterstuumltztldquo angezeigt wenn fuumlr seine Ausfuumlhrung eine houmlhere Version des BSS erforderlich ist
2 Nach dem Klonen der Datenbank von der Produktions- auf die Testumgebung erhalten alle Jobs automatisch den Status bdquoDeaktiviertldquo wenn die bdquoserverIDldquo nicht identisch ist
Beide Statusaumlnderungen sind gewollt Damit soll verhindert werden dass Jobs nach einem Serverneustart oder nach einem Update automatisch starten und dabei Fehler verursachen
Um Jobs mit dem Status bdquoNicht unterstuumltztldquo nutzen und konfigurieren zu koumlnnen ist es erforderlich den BALVI Schnittstellenserver zu aktualisieren
Deaktivierte Jobs koumlnnen Sie aktivieren indem Sie den jeweiligen Job an den aktuellen Server binden und den Haken bei bdquoAktivldquo setzen
Release Notes BALVI Schnittstellenserver Seite 33 von 37
Release Notes BALVI Schnittstellenserver Seite 34 von 37
4 Einrichtung in BALVI iP Um die Verfahren fuumlr den BALVI Schnittstellenserver fuumlr Anwender freizuschalten wird das Objekt bdquoSystemeinstellungenldquo oder bdquoMandanten- und Benutzereinstellungenldquo verwendet Die Anpassung ist je Verfahren moumlglich so kann in BALVI iP fuumlr den Zugriff durch den BALVI Schnittstellenserver ein Benutzer bdquoAldquo am Verfahren bdquoMobilldquo berechtigt werden ein Benutzer bdquoBldquo nur am Verfahren bdquoSLA_FLESHldquo usw Die Logik ist jedoch einheitlich Je Verfahren wird durch BALVI eine Verfahrensgruppe mit dem Verfahrensnamen angelegt und mit den entsprechenden Einstellungen vorkonfiguriert welche durch das Verfahren erforderlich sind Dabei kann die Komplexitaumlt der Einstellungen variieren wie z B an den zu Version 23 verfuumlgbaren Verfahren bdquoMobilldquo und bdquoSLA_Fleshldquo ersichtlich wird
Im Verfahren BALVI Mobil sind diverse Anpassungen moumlglich welche je Bundesland oder eingesetzter Import- und Export-Variante durch den BALVI Schnittstellenserver bei der Bearbeitung von Anfragen gepruumlft werden siehe Punkt 3 Abb Mobil-Einstellung in BALVI iP
Abb Mobil-Einstellung in BALVI iP
Alle Verfahren verwenden jedoch die regulaumlre Benutzerverwaltung von BALVI iP Ein Benutzer ohne Passwort gilt fuumlr BALVI iP als gesperrt was fuumlr das Login bedeutet dass der Anwender sich nur uumlber die Active-Directory-Authentifizierung anmelden kann Ist das nicht moumlglich (bzw nicht konfiguriert) kann der Anwender sich weder in BALVI iP noch uumlber die Webservice-Schnittstelle authentifizieren
Fuumlr Dienste-Schnittstellen welche keine persoumlnliche Authentifizierung durch einen Anwender erfordern wird empfohlen einen separaten Benutzer in der Benutzerverwaltung anzulegen und ein sicheres Kennwort zu vergeben Das Anlegen von zusaumltzlichen Benutzern gilt nicht fuumlr BALVI mobil XT da beim Holen und Uumlbermitteln von Daten jeder Benutzer auch ein fachlich konfigurierter Anwender innerhalb von BALVI iP ist und die Anwendungsoberflaumlche ebenfalls zur Erfassung von Daten verwendet
Unter Punkt 2 der Abb Mobil-Einstellung in BALVI iP wird ein modales Fenster geoumlffnet (Abb BALVI mobil Benutzerverwaltung) Innerhalb dieses modalen Fensters werden mandantenweise die Benutzer fuumlr BALVI
Release Notes BALVI Schnittstellenserver Seite 35 von 37
mobil und den jeweiligen Fachbereich festgelegt Dabei ist es wichtig dass man die Haken bdquoAktiv fuumlr hellipldquo bei bdquohellip mobilldquo und bei einem Fachbereich (bdquohellip LMldquo bdquohellip FMldquo usw) setzt weil sonst uumlber den BALVI Schnittstellenserver keine Kommunikation mit BALVI iP moumlglich ist
Abb BALVI mobil Benutzerverwaltung
Alternativ zur Passwort-Authentifizierung wird wie beschrieben auch die Active-Directory-Authentifizierung angeboten Dazu muss der BALVI iP-Anwender uumlber die Schaltflaumlche bdquoDomaumlnen-Benutzer zuordnenldquo mit dem Active Directory verknuumlpft werden
Nur wenn die Active-Directory-Konfigurationen in BALVI iP und im BALVI Schnittstellenserver auf dieselbe Domaumlne verweisen sind die Domaumlnen-Zuordnung und die Active-Directory-Authentifizierung (z B uumlber BALVI mobil XT) moumlglich
Release Notes BALVI Schnittstellenserver Seite 36 von 37
5 Bekannte Probleme und Loumlsungen
51 ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner Bei der Job-Bearbeitung tritt folgender Fehler auf ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner
Behebung
Fuumlhren Sie das beiliegende IP-Patch (UPDATEexe) aus bevor Sie das WAR austauschen
52 Server startet nicht Sie finden folgende Zeilen im Protokoll (catalinaout oder bsslog)
ERROR [localhost-startStop-1] [IdentityServiceImpl] serverID must not be empty
ERROR [localhost-startStop-1] [ContextLoader] Context initialization failed
Behebung
Setzen Sie die Umgebungsvariable ldquoserverIDrdquo in der Datei bdquocontextxmlldquo
53 ORA-00942 table or view does not exist In vielen Faumlllen wird der Fehler ldquoTabelle oder View nicht vorhandenrdquo ausgeworfen (Java-Protokoll im Ordner logs von Apache Tomcat) wenn eine neue Schnittstelle eingerichtet oder ein neues BALVI iP Release bzw Update eingespielt wurde ohne anschlieszligend das aktuelle GRANT-Skript auszufuumlhren
Behebung
Fuumlhren Sie das GRANT-Skript erneut aus
54 ORA-0406x bdquoBestehender Paketstatus wurde aufgehobenldquo
ORA-04061 Bestehender Status von package body ABCXYZ wurde annulliert
ORA-04065 Ausfuumlhrung nicht erfolgreich package body ABCXYZ wurde geaumlndert oder geloumlscht
Release Notes BALVI Schnittstellenserver Seite 37 von 37
Der Fehler tritt haumlufig ein nachdem die UPDATEexe ausgefuumlhrt und in der Ausfuumlhrungsliste ein Package aktualisiert wurde Oracle merkt sich je User-Session bestimmte Werte im Package wenn der Anwender es verwendet hat Durch einen bdquoCREATE OR REPLACE PACKAGEldquo-Befehl kann dieser Status temporaumlr aufgehoben werden Normalerweise tritt dieser Fehler nach dem Update genau einmal in jeder aktiven Session auf wenn der BSS nicht neu gestartet wird
Behebung
Starten Sie nach jedem Update den BSS neu um alle laufenden Sessions zu beenden
55 Jobs sind nicht ausfuumlhrbar
1 Ein Job wird mit dem Status bdquoNicht unterstuumltztldquo angezeigt wenn fuumlr seine Ausfuumlhrung eine houmlhere Version des BSS erforderlich ist
2 Nach dem Klonen der Datenbank von der Produktions- auf die Testumgebung erhalten alle Jobs automatisch den Status bdquoDeaktiviertldquo wenn die bdquoserverIDldquo nicht identisch ist
Beide Statusaumlnderungen sind gewollt Damit soll verhindert werden dass Jobs nach einem Serverneustart oder nach einem Update automatisch starten und dabei Fehler verursachen
Um Jobs mit dem Status bdquoNicht unterstuumltztldquo nutzen und konfigurieren zu koumlnnen ist es erforderlich den BALVI Schnittstellenserver zu aktualisieren
Deaktivierte Jobs koumlnnen Sie aktivieren indem Sie den jeweiligen Job an den aktuellen Server binden und den Haken bei bdquoAktivldquo setzen
Release Notes BALVI Schnittstellenserver Seite 34 von 37
4 Einrichtung in BALVI iP Um die Verfahren fuumlr den BALVI Schnittstellenserver fuumlr Anwender freizuschalten wird das Objekt bdquoSystemeinstellungenldquo oder bdquoMandanten- und Benutzereinstellungenldquo verwendet Die Anpassung ist je Verfahren moumlglich so kann in BALVI iP fuumlr den Zugriff durch den BALVI Schnittstellenserver ein Benutzer bdquoAldquo am Verfahren bdquoMobilldquo berechtigt werden ein Benutzer bdquoBldquo nur am Verfahren bdquoSLA_FLESHldquo usw Die Logik ist jedoch einheitlich Je Verfahren wird durch BALVI eine Verfahrensgruppe mit dem Verfahrensnamen angelegt und mit den entsprechenden Einstellungen vorkonfiguriert welche durch das Verfahren erforderlich sind Dabei kann die Komplexitaumlt der Einstellungen variieren wie z B an den zu Version 23 verfuumlgbaren Verfahren bdquoMobilldquo und bdquoSLA_Fleshldquo ersichtlich wird
Im Verfahren BALVI Mobil sind diverse Anpassungen moumlglich welche je Bundesland oder eingesetzter Import- und Export-Variante durch den BALVI Schnittstellenserver bei der Bearbeitung von Anfragen gepruumlft werden siehe Punkt 3 Abb Mobil-Einstellung in BALVI iP
Abb Mobil-Einstellung in BALVI iP
Alle Verfahren verwenden jedoch die regulaumlre Benutzerverwaltung von BALVI iP Ein Benutzer ohne Passwort gilt fuumlr BALVI iP als gesperrt was fuumlr das Login bedeutet dass der Anwender sich nur uumlber die Active-Directory-Authentifizierung anmelden kann Ist das nicht moumlglich (bzw nicht konfiguriert) kann der Anwender sich weder in BALVI iP noch uumlber die Webservice-Schnittstelle authentifizieren
Fuumlr Dienste-Schnittstellen welche keine persoumlnliche Authentifizierung durch einen Anwender erfordern wird empfohlen einen separaten Benutzer in der Benutzerverwaltung anzulegen und ein sicheres Kennwort zu vergeben Das Anlegen von zusaumltzlichen Benutzern gilt nicht fuumlr BALVI mobil XT da beim Holen und Uumlbermitteln von Daten jeder Benutzer auch ein fachlich konfigurierter Anwender innerhalb von BALVI iP ist und die Anwendungsoberflaumlche ebenfalls zur Erfassung von Daten verwendet
Unter Punkt 2 der Abb Mobil-Einstellung in BALVI iP wird ein modales Fenster geoumlffnet (Abb BALVI mobil Benutzerverwaltung) Innerhalb dieses modalen Fensters werden mandantenweise die Benutzer fuumlr BALVI
Release Notes BALVI Schnittstellenserver Seite 35 von 37
mobil und den jeweiligen Fachbereich festgelegt Dabei ist es wichtig dass man die Haken bdquoAktiv fuumlr hellipldquo bei bdquohellip mobilldquo und bei einem Fachbereich (bdquohellip LMldquo bdquohellip FMldquo usw) setzt weil sonst uumlber den BALVI Schnittstellenserver keine Kommunikation mit BALVI iP moumlglich ist
Abb BALVI mobil Benutzerverwaltung
Alternativ zur Passwort-Authentifizierung wird wie beschrieben auch die Active-Directory-Authentifizierung angeboten Dazu muss der BALVI iP-Anwender uumlber die Schaltflaumlche bdquoDomaumlnen-Benutzer zuordnenldquo mit dem Active Directory verknuumlpft werden
Nur wenn die Active-Directory-Konfigurationen in BALVI iP und im BALVI Schnittstellenserver auf dieselbe Domaumlne verweisen sind die Domaumlnen-Zuordnung und die Active-Directory-Authentifizierung (z B uumlber BALVI mobil XT) moumlglich
Release Notes BALVI Schnittstellenserver Seite 36 von 37
5 Bekannte Probleme und Loumlsungen
51 ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner Bei der Job-Bearbeitung tritt folgender Fehler auf ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner
Behebung
Fuumlhren Sie das beiliegende IP-Patch (UPDATEexe) aus bevor Sie das WAR austauschen
52 Server startet nicht Sie finden folgende Zeilen im Protokoll (catalinaout oder bsslog)
ERROR [localhost-startStop-1] [IdentityServiceImpl] serverID must not be empty
ERROR [localhost-startStop-1] [ContextLoader] Context initialization failed
Behebung
Setzen Sie die Umgebungsvariable ldquoserverIDrdquo in der Datei bdquocontextxmlldquo
53 ORA-00942 table or view does not exist In vielen Faumlllen wird der Fehler ldquoTabelle oder View nicht vorhandenrdquo ausgeworfen (Java-Protokoll im Ordner logs von Apache Tomcat) wenn eine neue Schnittstelle eingerichtet oder ein neues BALVI iP Release bzw Update eingespielt wurde ohne anschlieszligend das aktuelle GRANT-Skript auszufuumlhren
Behebung
Fuumlhren Sie das GRANT-Skript erneut aus
54 ORA-0406x bdquoBestehender Paketstatus wurde aufgehobenldquo
ORA-04061 Bestehender Status von package body ABCXYZ wurde annulliert
ORA-04065 Ausfuumlhrung nicht erfolgreich package body ABCXYZ wurde geaumlndert oder geloumlscht
Release Notes BALVI Schnittstellenserver Seite 37 von 37
Der Fehler tritt haumlufig ein nachdem die UPDATEexe ausgefuumlhrt und in der Ausfuumlhrungsliste ein Package aktualisiert wurde Oracle merkt sich je User-Session bestimmte Werte im Package wenn der Anwender es verwendet hat Durch einen bdquoCREATE OR REPLACE PACKAGEldquo-Befehl kann dieser Status temporaumlr aufgehoben werden Normalerweise tritt dieser Fehler nach dem Update genau einmal in jeder aktiven Session auf wenn der BSS nicht neu gestartet wird
Behebung
Starten Sie nach jedem Update den BSS neu um alle laufenden Sessions zu beenden
55 Jobs sind nicht ausfuumlhrbar
1 Ein Job wird mit dem Status bdquoNicht unterstuumltztldquo angezeigt wenn fuumlr seine Ausfuumlhrung eine houmlhere Version des BSS erforderlich ist
2 Nach dem Klonen der Datenbank von der Produktions- auf die Testumgebung erhalten alle Jobs automatisch den Status bdquoDeaktiviertldquo wenn die bdquoserverIDldquo nicht identisch ist
Beide Statusaumlnderungen sind gewollt Damit soll verhindert werden dass Jobs nach einem Serverneustart oder nach einem Update automatisch starten und dabei Fehler verursachen
Um Jobs mit dem Status bdquoNicht unterstuumltztldquo nutzen und konfigurieren zu koumlnnen ist es erforderlich den BALVI Schnittstellenserver zu aktualisieren
Deaktivierte Jobs koumlnnen Sie aktivieren indem Sie den jeweiligen Job an den aktuellen Server binden und den Haken bei bdquoAktivldquo setzen
Release Notes BALVI Schnittstellenserver Seite 35 von 37
mobil und den jeweiligen Fachbereich festgelegt Dabei ist es wichtig dass man die Haken bdquoAktiv fuumlr hellipldquo bei bdquohellip mobilldquo und bei einem Fachbereich (bdquohellip LMldquo bdquohellip FMldquo usw) setzt weil sonst uumlber den BALVI Schnittstellenserver keine Kommunikation mit BALVI iP moumlglich ist
Abb BALVI mobil Benutzerverwaltung
Alternativ zur Passwort-Authentifizierung wird wie beschrieben auch die Active-Directory-Authentifizierung angeboten Dazu muss der BALVI iP-Anwender uumlber die Schaltflaumlche bdquoDomaumlnen-Benutzer zuordnenldquo mit dem Active Directory verknuumlpft werden
Nur wenn die Active-Directory-Konfigurationen in BALVI iP und im BALVI Schnittstellenserver auf dieselbe Domaumlne verweisen sind die Domaumlnen-Zuordnung und die Active-Directory-Authentifizierung (z B uumlber BALVI mobil XT) moumlglich
Release Notes BALVI Schnittstellenserver Seite 36 von 37
5 Bekannte Probleme und Loumlsungen
51 ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner Bei der Job-Bearbeitung tritt folgender Fehler auf ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner
Behebung
Fuumlhren Sie das beiliegende IP-Patch (UPDATEexe) aus bevor Sie das WAR austauschen
52 Server startet nicht Sie finden folgende Zeilen im Protokoll (catalinaout oder bsslog)
ERROR [localhost-startStop-1] [IdentityServiceImpl] serverID must not be empty
ERROR [localhost-startStop-1] [ContextLoader] Context initialization failed
Behebung
Setzen Sie die Umgebungsvariable ldquoserverIDrdquo in der Datei bdquocontextxmlldquo
53 ORA-00942 table or view does not exist In vielen Faumlllen wird der Fehler ldquoTabelle oder View nicht vorhandenrdquo ausgeworfen (Java-Protokoll im Ordner logs von Apache Tomcat) wenn eine neue Schnittstelle eingerichtet oder ein neues BALVI iP Release bzw Update eingespielt wurde ohne anschlieszligend das aktuelle GRANT-Skript auszufuumlhren
Behebung
Fuumlhren Sie das GRANT-Skript erneut aus
54 ORA-0406x bdquoBestehender Paketstatus wurde aufgehobenldquo
ORA-04061 Bestehender Status von package body ABCXYZ wurde annulliert
ORA-04065 Ausfuumlhrung nicht erfolgreich package body ABCXYZ wurde geaumlndert oder geloumlscht
Release Notes BALVI Schnittstellenserver Seite 37 von 37
Der Fehler tritt haumlufig ein nachdem die UPDATEexe ausgefuumlhrt und in der Ausfuumlhrungsliste ein Package aktualisiert wurde Oracle merkt sich je User-Session bestimmte Werte im Package wenn der Anwender es verwendet hat Durch einen bdquoCREATE OR REPLACE PACKAGEldquo-Befehl kann dieser Status temporaumlr aufgehoben werden Normalerweise tritt dieser Fehler nach dem Update genau einmal in jeder aktiven Session auf wenn der BSS nicht neu gestartet wird
Behebung
Starten Sie nach jedem Update den BSS neu um alle laufenden Sessions zu beenden
55 Jobs sind nicht ausfuumlhrbar
1 Ein Job wird mit dem Status bdquoNicht unterstuumltztldquo angezeigt wenn fuumlr seine Ausfuumlhrung eine houmlhere Version des BSS erforderlich ist
2 Nach dem Klonen der Datenbank von der Produktions- auf die Testumgebung erhalten alle Jobs automatisch den Status bdquoDeaktiviertldquo wenn die bdquoserverIDldquo nicht identisch ist
Beide Statusaumlnderungen sind gewollt Damit soll verhindert werden dass Jobs nach einem Serverneustart oder nach einem Update automatisch starten und dabei Fehler verursachen
Um Jobs mit dem Status bdquoNicht unterstuumltztldquo nutzen und konfigurieren zu koumlnnen ist es erforderlich den BALVI Schnittstellenserver zu aktualisieren
Deaktivierte Jobs koumlnnen Sie aktivieren indem Sie den jeweiligen Job an den aktuellen Server binden und den Haken bei bdquoAktivldquo setzen
Release Notes BALVI Schnittstellenserver Seite 36 von 37
5 Bekannte Probleme und Loumlsungen
51 ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner Bei der Job-Bearbeitung tritt folgender Fehler auf ORA-00904 bdquoSERVER_IDldquo unguumlltiger Bezeichner
Behebung
Fuumlhren Sie das beiliegende IP-Patch (UPDATEexe) aus bevor Sie das WAR austauschen
52 Server startet nicht Sie finden folgende Zeilen im Protokoll (catalinaout oder bsslog)
ERROR [localhost-startStop-1] [IdentityServiceImpl] serverID must not be empty
ERROR [localhost-startStop-1] [ContextLoader] Context initialization failed
Behebung
Setzen Sie die Umgebungsvariable ldquoserverIDrdquo in der Datei bdquocontextxmlldquo
53 ORA-00942 table or view does not exist In vielen Faumlllen wird der Fehler ldquoTabelle oder View nicht vorhandenrdquo ausgeworfen (Java-Protokoll im Ordner logs von Apache Tomcat) wenn eine neue Schnittstelle eingerichtet oder ein neues BALVI iP Release bzw Update eingespielt wurde ohne anschlieszligend das aktuelle GRANT-Skript auszufuumlhren
Behebung
Fuumlhren Sie das GRANT-Skript erneut aus
54 ORA-0406x bdquoBestehender Paketstatus wurde aufgehobenldquo
ORA-04061 Bestehender Status von package body ABCXYZ wurde annulliert
ORA-04065 Ausfuumlhrung nicht erfolgreich package body ABCXYZ wurde geaumlndert oder geloumlscht
Release Notes BALVI Schnittstellenserver Seite 37 von 37
Der Fehler tritt haumlufig ein nachdem die UPDATEexe ausgefuumlhrt und in der Ausfuumlhrungsliste ein Package aktualisiert wurde Oracle merkt sich je User-Session bestimmte Werte im Package wenn der Anwender es verwendet hat Durch einen bdquoCREATE OR REPLACE PACKAGEldquo-Befehl kann dieser Status temporaumlr aufgehoben werden Normalerweise tritt dieser Fehler nach dem Update genau einmal in jeder aktiven Session auf wenn der BSS nicht neu gestartet wird
Behebung
Starten Sie nach jedem Update den BSS neu um alle laufenden Sessions zu beenden
55 Jobs sind nicht ausfuumlhrbar
1 Ein Job wird mit dem Status bdquoNicht unterstuumltztldquo angezeigt wenn fuumlr seine Ausfuumlhrung eine houmlhere Version des BSS erforderlich ist
2 Nach dem Klonen der Datenbank von der Produktions- auf die Testumgebung erhalten alle Jobs automatisch den Status bdquoDeaktiviertldquo wenn die bdquoserverIDldquo nicht identisch ist
Beide Statusaumlnderungen sind gewollt Damit soll verhindert werden dass Jobs nach einem Serverneustart oder nach einem Update automatisch starten und dabei Fehler verursachen
Um Jobs mit dem Status bdquoNicht unterstuumltztldquo nutzen und konfigurieren zu koumlnnen ist es erforderlich den BALVI Schnittstellenserver zu aktualisieren
Deaktivierte Jobs koumlnnen Sie aktivieren indem Sie den jeweiligen Job an den aktuellen Server binden und den Haken bei bdquoAktivldquo setzen
Release Notes BALVI Schnittstellenserver Seite 37 von 37
Der Fehler tritt haumlufig ein nachdem die UPDATEexe ausgefuumlhrt und in der Ausfuumlhrungsliste ein Package aktualisiert wurde Oracle merkt sich je User-Session bestimmte Werte im Package wenn der Anwender es verwendet hat Durch einen bdquoCREATE OR REPLACE PACKAGEldquo-Befehl kann dieser Status temporaumlr aufgehoben werden Normalerweise tritt dieser Fehler nach dem Update genau einmal in jeder aktiven Session auf wenn der BSS nicht neu gestartet wird
Behebung
Starten Sie nach jedem Update den BSS neu um alle laufenden Sessions zu beenden
55 Jobs sind nicht ausfuumlhrbar
1 Ein Job wird mit dem Status bdquoNicht unterstuumltztldquo angezeigt wenn fuumlr seine Ausfuumlhrung eine houmlhere Version des BSS erforderlich ist
2 Nach dem Klonen der Datenbank von der Produktions- auf die Testumgebung erhalten alle Jobs automatisch den Status bdquoDeaktiviertldquo wenn die bdquoserverIDldquo nicht identisch ist
Beide Statusaumlnderungen sind gewollt Damit soll verhindert werden dass Jobs nach einem Serverneustart oder nach einem Update automatisch starten und dabei Fehler verursachen
Um Jobs mit dem Status bdquoNicht unterstuumltztldquo nutzen und konfigurieren zu koumlnnen ist es erforderlich den BALVI Schnittstellenserver zu aktualisieren
Deaktivierte Jobs koumlnnen Sie aktivieren indem Sie den jeweiligen Job an den aktuellen Server binden und den Haken bei bdquoAktivldquo setzen