37
Release Notes BALVI Schnittstellenserver Seite 1 von 37 Inhaltsverzeichnis 1 Allgemeine Hinweise 3 1.1 Neuerungen in Version 3.1/3.2 3 1.2 Neuerungen in Version 3.0 5 1.3 Hinweise zum Update von älteren Versionen (vor 3.0.x) 6 1.4 Nacharbeiten nach dem Update auf Version 2.8 (ADMIN**) 7 1.5 Neuerungen in Version 2.8 7 1.5.1 Jeder Schnittstellen-Server benötigt eine Kennung „serverID“ 7 1.5.2 Optional ist nun eine Namensvergabe möglich 8 2 Einrichtungshinweise 9 2.1 Allgemeine Hinweise zum Betrieb 9 2.1.1 Kompatibilität zu Apache Tomcat und Java SE 9 2.1.2 Oracle Java SE Lizenzierung 9 2.1.3 Einsatz von TLS/SSL 9 2.1.4 Nutzung von Java-Proxyeinstellungen 10 2.1.5 Spracheinstellung Deutsch 11 2.1.6 Datenbankverbindung 11 2.1.7 Probleme beim Anlegen von LOB-Objekten 11 2.1.8 Umbenennung der gelieferten WAR-Datei 11 2.1.9 Server-Schnittstellen 11 2.2 Kompatibilitätsliste 12 2.3 Erforderliche Bibliotheken für Apache Tomcat 13 2.4 Datenbank-Installation 13 2.4.1 Erstinstallation: Datenbank-Benutzer anlegen 14 2.4.2 Rechte zuweisen 14 2.4.3 Wann ist die Ausführung des Grant-Skripts erforderlich? 15 2.4.4 Welche Version des Grant-Skripts soll ich nehmen? 16 2.4.5 Kombination von mehreren Verfahren 16 2.5 Konfiguration des Schnittstellen-Servers 17 2.5.1 Die „context.xml“-Parameter 17 2.6 Logging mit logback 27 2.7 Tocmat Optional: Suche im „Klassenpfad“ um den Ordner „conf“ erweitern 28 3 Die neue Browser-Oberfläche 28 3.1 Server-Protokoll 28 3.2 Jobs 30 3.3 Log-Ausgaben 30 3.4 Logout/Abmeldung vom System 32 3.5 Cache löschen 32 4 Einrichtung in BALVI iP 34 5 Bekannte Probleme und Lösungen 36 5.1 ORA-00904: „SERVER_ID“ ungültiger Bezeichner 36

Release Notes BALVI Schnittstellenserver€¦ · 2.5.1 Die „context.xml“-Parameter 17 ... Zu BSS 3.0 wurde auf eine neue Logging-Klasse umgestellt ... auszuführende Modul benötigt,

Embed Size (px)

Citation preview

Page 1: Release Notes BALVI Schnittstellenserver€¦ · 2.5.1 Die „context.xml“-Parameter 17 ... Zu BSS 3.0 wurde auf eine neue Logging-Klasse umgestellt ... auszuführende Modul benötigt,

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

Page 2: Release Notes BALVI Schnittstellenserver€¦ · 2.5.1 Die „context.xml“-Parameter 17 ... Zu BSS 3.0 wurde auf eine neue Logging-Klasse umgestellt ... auszuführende Modul benötigt,

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

Page 3: Release Notes BALVI Schnittstellenserver€¦ · 2.5.1 Die „context.xml“-Parameter 17 ... Zu BSS 3.0 wurde auf eine neue Logging-Klasse umgestellt ... auszuführende Modul benötigt,

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

Page 4: Release Notes BALVI Schnittstellenserver€¦ · 2.5.1 Die „context.xml“-Parameter 17 ... Zu BSS 3.0 wurde auf eine neue Logging-Klasse umgestellt ... auszuführende Modul benötigt,

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

Page 5: Release Notes BALVI Schnittstellenserver€¦ · 2.5.1 Die „context.xml“-Parameter 17 ... Zu BSS 3.0 wurde auf eine neue Logging-Klasse umgestellt ... auszuführende Modul benötigt,

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

Page 6: Release Notes BALVI Schnittstellenserver€¦ · 2.5.1 Die „context.xml“-Parameter 17 ... Zu BSS 3.0 wurde auf eine neue Logging-Klasse umgestellt ... auszuführende Modul benötigt,

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

Page 7: Release Notes BALVI Schnittstellenserver€¦ · 2.5.1 Die „context.xml“-Parameter 17 ... Zu BSS 3.0 wurde auf eine neue Logging-Klasse umgestellt ... auszuführende Modul benötigt,

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

Page 8: Release Notes BALVI Schnittstellenserver€¦ · 2.5.1 Die „context.xml“-Parameter 17 ... Zu BSS 3.0 wurde auf eine neue Logging-Klasse umgestellt ... auszuführende Modul benötigt,

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

Page 9: Release Notes BALVI Schnittstellenserver€¦ · 2.5.1 Die „context.xml“-Parameter 17 ... Zu BSS 3.0 wurde auf eine neue Logging-Klasse umgestellt ... auszuführende Modul benötigt,

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

Page 10: Release Notes BALVI Schnittstellenserver€¦ · 2.5.1 Die „context.xml“-Parameter 17 ... Zu BSS 3.0 wurde auf eine neue Logging-Klasse umgestellt ... auszuführende Modul benötigt,

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

Page 11: Release Notes BALVI Schnittstellenserver€¦ · 2.5.1 Die „context.xml“-Parameter 17 ... Zu BSS 3.0 wurde auf eine neue Logging-Klasse umgestellt ... auszuführende Modul benötigt,

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

Page 12: Release Notes BALVI Schnittstellenserver€¦ · 2.5.1 Die „context.xml“-Parameter 17 ... Zu BSS 3.0 wurde auf eine neue Logging-Klasse umgestellt ... auszuführende Modul benötigt,

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

Page 13: Release Notes BALVI Schnittstellenserver€¦ · 2.5.1 Die „context.xml“-Parameter 17 ... Zu BSS 3.0 wurde auf eine neue Logging-Klasse umgestellt ... auszuführende Modul benötigt,

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

Page 14: Release Notes BALVI Schnittstellenserver€¦ · 2.5.1 Die „context.xml“-Parameter 17 ... Zu BSS 3.0 wurde auf eine neue Logging-Klasse umgestellt ... auszuführende Modul benötigt,

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

Page 15: Release Notes BALVI Schnittstellenserver€¦ · 2.5.1 Die „context.xml“-Parameter 17 ... Zu BSS 3.0 wurde auf eine neue Logging-Klasse umgestellt ... auszuführende Modul benötigt,

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

Page 16: Release Notes BALVI Schnittstellenserver€¦ · 2.5.1 Die „context.xml“-Parameter 17 ... Zu BSS 3.0 wurde auf eine neue Logging-Klasse umgestellt ... auszuführende Modul benötigt,

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

Page 17: Release Notes BALVI Schnittstellenserver€¦ · 2.5.1 Die „context.xml“-Parameter 17 ... Zu BSS 3.0 wurde auf eine neue Logging-Klasse umgestellt ... auszuführende Modul benötigt,

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

Page 18: Release Notes BALVI Schnittstellenserver€¦ · 2.5.1 Die „context.xml“-Parameter 17 ... Zu BSS 3.0 wurde auf eine neue Logging-Klasse umgestellt ... auszuführende Modul benötigt,

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

Page 19: Release Notes BALVI Schnittstellenserver€¦ · 2.5.1 Die „context.xml“-Parameter 17 ... Zu BSS 3.0 wurde auf eine neue Logging-Klasse umgestellt ... auszuführende Modul benötigt,

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

Page 20: Release Notes BALVI Schnittstellenserver€¦ · 2.5.1 Die „context.xml“-Parameter 17 ... Zu BSS 3.0 wurde auf eine neue Logging-Klasse umgestellt ... auszuführende Modul benötigt,

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

Page 21: Release Notes BALVI Schnittstellenserver€¦ · 2.5.1 Die „context.xml“-Parameter 17 ... Zu BSS 3.0 wurde auf eine neue Logging-Klasse umgestellt ... auszuführende Modul benötigt,

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

Page 22: Release Notes BALVI Schnittstellenserver€¦ · 2.5.1 Die „context.xml“-Parameter 17 ... Zu BSS 3.0 wurde auf eine neue Logging-Klasse umgestellt ... auszuführende Modul benötigt,

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

Page 23: Release Notes BALVI Schnittstellenserver€¦ · 2.5.1 Die „context.xml“-Parameter 17 ... Zu BSS 3.0 wurde auf eine neue Logging-Klasse umgestellt ... auszuführende Modul benötigt,

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

Page 24: Release Notes BALVI Schnittstellenserver€¦ · 2.5.1 Die „context.xml“-Parameter 17 ... Zu BSS 3.0 wurde auf eine neue Logging-Klasse umgestellt ... auszuführende Modul benötigt,

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

Page 25: Release Notes BALVI Schnittstellenserver€¦ · 2.5.1 Die „context.xml“-Parameter 17 ... Zu BSS 3.0 wurde auf eine neue Logging-Klasse umgestellt ... auszuführende Modul benötigt,

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

Page 26: Release Notes BALVI Schnittstellenserver€¦ · 2.5.1 Die „context.xml“-Parameter 17 ... Zu BSS 3.0 wurde auf eine neue Logging-Klasse umgestellt ... auszuführende Modul benötigt,

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

Page 27: Release Notes BALVI Schnittstellenserver€¦ · 2.5.1 Die „context.xml“-Parameter 17 ... Zu BSS 3.0 wurde auf eine neue Logging-Klasse umgestellt ... auszuführende Modul benötigt,

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

Page 28: Release Notes BALVI Schnittstellenserver€¦ · 2.5.1 Die „context.xml“-Parameter 17 ... Zu BSS 3.0 wurde auf eine neue Logging-Klasse umgestellt ... auszuführende Modul benötigt,

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

Page 29: Release Notes BALVI Schnittstellenserver€¦ · 2.5.1 Die „context.xml“-Parameter 17 ... Zu BSS 3.0 wurde auf eine neue Logging-Klasse umgestellt ... auszuführende Modul benötigt,

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

Page 30: Release Notes BALVI Schnittstellenserver€¦ · 2.5.1 Die „context.xml“-Parameter 17 ... Zu BSS 3.0 wurde auf eine neue Logging-Klasse umgestellt ... auszuführende Modul benötigt,

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

Page 31: Release Notes BALVI Schnittstellenserver€¦ · 2.5.1 Die „context.xml“-Parameter 17 ... Zu BSS 3.0 wurde auf eine neue Logging-Klasse umgestellt ... auszuführende Modul benötigt,

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

Page 32: Release Notes BALVI Schnittstellenserver€¦ · 2.5.1 Die „context.xml“-Parameter 17 ... Zu BSS 3.0 wurde auf eine neue Logging-Klasse umgestellt ... auszuführende Modul benötigt,

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

Page 33: Release Notes BALVI Schnittstellenserver€¦ · 2.5.1 Die „context.xml“-Parameter 17 ... Zu BSS 3.0 wurde auf eine neue Logging-Klasse umgestellt ... auszuführende Modul benötigt,

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

Page 34: Release Notes BALVI Schnittstellenserver€¦ · 2.5.1 Die „context.xml“-Parameter 17 ... Zu BSS 3.0 wurde auf eine neue Logging-Klasse umgestellt ... auszuführende Modul benötigt,

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

Page 35: Release Notes BALVI Schnittstellenserver€¦ · 2.5.1 Die „context.xml“-Parameter 17 ... Zu BSS 3.0 wurde auf eine neue Logging-Klasse umgestellt ... auszuführende Modul benötigt,

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

Page 36: Release Notes BALVI Schnittstellenserver€¦ · 2.5.1 Die „context.xml“-Parameter 17 ... Zu BSS 3.0 wurde auf eine neue Logging-Klasse umgestellt ... auszuführende Modul benötigt,

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

Page 37: Release Notes BALVI Schnittstellenserver€¦ · 2.5.1 Die „context.xml“-Parameter 17 ... Zu BSS 3.0 wurde auf eine neue Logging-Klasse umgestellt ... auszuführende Modul benötigt,

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