CIB documentServer technischer Leitfaden (DE)

Schneller Einstieg

Konfiguration

Sie können die Anzahl der gestarteten Socketserver, verschiedene Timeouts und andere Parameter, die auch das Framework anbietet leicht konfigurieren. Dieser Abschnitt gibt einen Überblick, wie Sie die Konfiguration des CIB documentServers auf Ihre individuellen Bedürfnisse anpassen können. Hier finden Sie eine Beschreibung des Inhalts der Konfigurationsdatei CibDocumentServer.properties und wie Sie diese verändern müssen, um Einstellungen am CIB documentServer vorzunehmen.


CibDocumentServer.properties
CibDocumentServer-Forward.properties (ab 1.4.19d)
Angabe von Konfigurationen auf der Kommandozeile
Inhalt der CibDocumentServer.properties
Jobconfig.xml für CIB docgen Default-Properties
Konfiguration von Sprachdateien für Texterkennung durch CIB ocr
Beispielsituation zur Konfiguration einschließlich forward-Properties
Monitoring mit MBean DocservRuntime (ab 1.5.55f)

CibDocumentServer.properties

Konfigurieren Sie Ihren CIB documentServer, indem Sie die Einstellungen in der Datei CibDocumentServer.properties anpassen, nicht in der Datei CibDocumentServer/WEB-INF/web.xml, da diese bei der Lieferung einer aktualisierten CIB documentServer Version ersetzt wird.

Diese Datei enthält dann Ihre kunden- und serverspezifische Konfiguration.

Eine umfangreich kommentierte Vorlage wird für Ihre Plattform mitgeliefert.

Sollten Sie den CIB documentServer als EAR-Datei deployen, so legen sie die CibDocumentServer.properties ins EAR neben die CibDocumentServer.war.

 Deployen Sie den CIB documentServer als WAR-Datei, so legen Sie die CibDocumentServer.properties neben das WAR (abhängig vom Application-Server).

Zuerst wird die CibDocumentServer.properties stets im Classpath der CibDocumentServer-Webanwendung gesucht. Hierüber wird auch die Properties-Datei im EAR gefunden.


CibDocumentServer-Forward.properties (ab 1.4.19d)

Falls Sie die CibDocumentServer.properties außerhalb der Verzeichnisstruktur Ihres Application-Servers konfigurieren möchten, so verwenden Sie die Einstellung de.cib.docserv.ForwardConfigurationFilename, um aus dem Application-Server auf Ihre gewünschte .properties-Datei zu verweisen. Im Application-Server wird also eine verkürzte und konstante CibDocumentServer.properties-Datei deployed, die auf die eigentliche Konfiguration verweist. Eine Vorlage mit enthaltener Kurzanleitung finden Sie mit der CibDocumentServer-Forward.properties.

Beispiel:

##CIB documentserver Forward Configuration. 
# Requires CIB documentserver 1.4.19d or newer
# Forward to this configuration:
de.cib.docserv.ForwardConfigurationFilename=
/opt/cib/conf/CibDocumentServer.properties


Falls Sie den CIB documentServer in mehreren Instanzen betreiben, kann durch Angabe des ForwardConfiguration­Filenames für jede Instanz ein getrennter Baum an Konfigurationseinstellungen aufgespannt werden (siehe Grafik zur Beispielsituation in diesem Abschnitt).


Angabe von Konfigurationen auf der Kommandozeile

Diese Konfigurationseinstellungen, angefangen mit dem ForwardConfigurationFilename können darüber hinaus auf der Kommandozeile der Java VM angegeben werden mit –D, falls dies in Ihrer Situation praktikabel sein sollte, etwa auf den beiden Nodes eines Clusters:

-Dde.cib.docserv.ForwardConfigurationFilename=
/opt/cib/conf/CibDocumentServer.properties

Im Fall, dass Sie eine Konfigurationsdatei im Anwedungsverzeichnis verwenden, beachten Sie bitte, dass die Angabe der Property ForwardConfigurationFilename über die Kommandozeile Vorrang hat.


Inhalt der CibDocumentServer.properties

Folgende wichtigen Einstellungen stehen zur Verfügung, um den CIB documentServer bezüglich Konfigurationspfad, Leistung, Ports und Logging zu konfigurieren.

Hinweis: Benutzen Sie zur Pfadangabe auch unter Windows immer Slashes (/).


Konfigurationspfad

de.cib.docserv.JobConfigfilename=/opt/cib/conf/jobconfig.xml

Legen Sie hier den Pfad zur Konfiguration von CIB job und CIB docgen fest. In der angegebenen Datei befinden sich keine Einstellungen zum CIB documentServer selbst.


Leistung

de.cib.docserv.http.PrestartOnLoad=true

Wenn die Socketserver-Prozesse beim Start der CIB documentServer Webanwendung gleich gestartet werden sollen, also auch beim Start des Application-Servers, geben Sie hier true an.

de.cib.docserv.socket.IdleShutdownTime=3600

Wenn in bestimmten Zeiträumen keine Last auf der Maschine ist, können sich die Socketserver-Prozesse nach dieser Zeit (in Sekunden) automatisch beenden. Sie werden bei Bedarf automatisch wieder gestartet. Bei einer Angabe von 0 werden die SocketServer-Prozesse nicht automatisch beendet.

de.cib.docserv.MaxProcessCount=10

An dieser Stelle sollten Sie den CIB documentServer an Ihre Serverhardware und den gewünschten Durchsatz anpassen. Mehr Socketserver-Prozesse lassen weniger Rechenleistung für andere Anwendungen. Weniger Prozesse erreichen gegebenenfalls die gesetzten Durchsatzzahlen nicht. Andere wesentliche performance-relevante Einstellungen gibt es im CIB documentServer nicht.

de.cib.docserv.MaxJobCountPerProcess=100

Damit aktivieren Sie einen automatischen Neustart der Socketserver-Prozesse, wenn die angegebene Zahl an Jobs bearbeitet wurde. Die Logdateien von CIB job und den CIB docgen werden dabei neu begonnen, und können auf diese Weise in der Größe begrenzt werden. Eine Angabe von -1 schaltet den automatischen Neustart ab.

de.cib.docserv.job.MaxJobExecutionTime=600000

Falls Anwender einen Einfluss auf die Laufzeit der Aufträge haben (RTF, Datensatzanzahl), kann mit dieser Einstellung die Laufzeit von Aufträgen begrenzt werden. Diese werden dann abgebrochen, und der Socketserver beendet. Die aufrufende Anwendung erhält eine Fehlerantwort, aber die Anwender können somit den Server nicht für längere Zeit blockieren. Bei einer Angabe von 0 wird kein Abbruch vorgenommen.

Diese Einstellung benötigt CIB socketserver 1.6.1, CIB job 1.6.2 und CIB merge 3.10.3. Die Funktion ist derzeit nur für „merge“-Kommandos wirksam.

de.cib.docserv.socket.MaxMemory=250

Mit dieser Einstellung kann die maximale Anzahl des allokierbaren Arbeitsspeichers für jeden Prozess des CIB socketserver in Megabyte definiert werden. Erreicht ein CIB socketserver dieses Limit, beendet sich der Prozess. Diese Einstellung, multipliziert mit der Anzahl der CIB socketserver (siehe Property de.cib.docserv.MaxProcessCount), ergibt einen groben Wert für den maximal verwendeten Arbeitsspeicher der nativen Prozesse.

Diese Einstellung benötigt den CIB socketserver 1.6.2 und steht derzeit unter den Plattformen Linux-x86, Solaris-x86 und Solaris Sparc zur Verfügung.

 

de.cib.docserv.MaxProcessCountAsync=3

Maximale Anzahl der SocketServer Ports für asynchrone Anfragen.

Die Anfragen werden zunächst in eine Queue abgelegt und dann sequenziell bearbeitet.


Ports

de.cib.docserv.socket.FirstPort=50000

Falls auf Ihrem System Ports bereits belegt sind oder Vorgaben für Ports existieren kann hier die Nummer des ersten Ports aus der Port-Range spezifiziert werden. Jeder weitere Socketserver-Prozess vergrößert die Range um eins (siehe MaxProcessCount).

Bei dynamischer Portreservierung gibt dieser Wert den Beginn des Bereichs an, in dem der CIB documentServer versucht, Ports zu reservieren. Ab Version 1.20.0 es nicht mehr notwendig, für die dynamische Portreservierung ein Initialport einzusetzen. Siehe UseDynamicPortSelection.

de.cib.docserv.socket.LastPort=50200

Bei Einsatz von dynamischer Portreservierung gibt dieser Wert das Ende des Bereichs an, in dem der CIB documentServer versucht, Ports zu reservieren. Ab Version 1.20.0 wird diese Property nicht mehr unterstützt. Siehe UseDynamicPortSelection.

 

de.cib.docserv.socket.UseDynamicPortSelection=true

Aktivieren Sie die dynamische Portreservierung, wenn Sie mehr als einen CIB documentServer auf einer Maschine einsetzen wollen oder die genaue Portrange nicht festlegen wollen. Siehe auch FirstPort und LastPort. Ab 1.5.26

Ab Version 1.20.0 wurde das Verhalten der Property geändert. Es wird nicht mehr durch einen bestimmten Portrange gesucht. Es wird dynamisch für freie Ports geprüft und so viele reserviert wie in der Property MaxProcessCount eingesetzt.

Das Einsetzen der Propery LastPort wird nicht mehr benötigt und ab der Version 1.20.0 steht diese nicht mehr zur Verfügung.

Der ausgesuchte Portrange hängt von dem Betriebsystem und ist normallerweise:

-         49152 – 65535 für Windows

-         32765 – 60999 für Linux


Formulare

de.cib.formserv.FormsPath=/opt/cib/forms

Legen Sie hier den Pfad zu den ausfüllbaren Formularen für den CIB formserver fest. Diese können dann über die URL des CIB documentServers ergänzt um /forms aufgerufen werden.

Der Pfad zu den Formularen, in die die eingegebenen Daten gespeichert werden, wird in der jobconfig.xml festgelegt (pdfmerge, WorkSpace).

Ab 1.5.x


Logging

CIB documentServer

de.cib.docserv.LogConfigFilename = /opt/cib/conf/log4j.xml

de.cib.docserv.LoggingMode = log4j (ab CIB documentServer 1.16.0)

Ist ein LogConfigFilename angegeben, wird dieser für die Konfiguration des Loggings berückichtigt.

Wenn die Datei nicht existiert wird ausschliesslich auf der Konsole geloggt.

Durch Angabe des LoggingMode kann man log4j oder log4j2 setzen.

Per Default wird log4j verwendet wenn die Property leer oder nicht gesetzt ist.


Logging der CIB docgen Module

de.cib.docserv.LogOptions=SJ

de.cib.docserv.LogPath=/opt/cib/logs

Diese beiden Parameter steuern die Art und den Ort der Logdateien.

Durch Angabe einer Buchstabenfolge in den LogOptions (z.B. de.cib.docserv.LogOptions=SMPFJEOIZ) werden Logdateien erstellt. Die Dateinamen sind fest vorgegeben.

Ist ein LogPath angegeben, werden die Logdateien dort erzeugt. Ansonsten werden die Logdateien im Arbeitsverzeichnis des Socketserver-Prozesses angelegt.

Wenn der angegebene LogPath nicht existiert, werden die Logdateien im Arbeitsverzeichnis (Angabe über die Property „de.cib.docserv.ServerWorkingDirectory“) des Socketserver Prozesses angelegt (ab 1.11.1)

Durch Angabe folgender Buchstaben kann die Logausgabe des entsprechenden Moduls aktiviert werden:

Buchstabe

Modul

Logdateiname

S

Socketserver

socketserver.log

M

CIB merge

mrgtrace.log

P

CIB pdf toolbox

pdftrace.log

F

CIB format/output

prtrace.log

J

CIB job

jobtrace.log

E

CIB mail

mailtrace.log

O (Buchstabe O)

CIB ocr

ocrtrace.log

I

CIB image toolbox

imgtrace.log

Z

CIB invoice toolbox

invtrace.log


Konfiguration Maintenance Feature

Im Folgenden werden die zu setzenden Properties des Maintenance Features beschrieben.

de.cib.docserv.AutoMaintenance

Wenn die Maintenance Funktionalität beim Start des Application Servers gleich gestartet werden soll, geben Sie hier "true" an.

 

de.cib.docserv.KnownErrorCodes

Legen Sie hier fest, für welche Fehlermeldungen die Aufträge durch den Maintenance-Prozess nicht erneut ausgeführt werden sollen.

 

de.cib.docserv.ExecutionsNumber

de.cib.docserv.TimeSection

Mit diesen beiden Einstellungen kann die maximale Anzahl Aufträge pro angegebenen Zeitabschnitt, die durch den Maintenance-Prozess ausgeführt werden, definiert werden. Erreicht der Maintenance-Prozess dieses Limit, dann werden keine weiteren Aufträge durchgeführt, bis die angegebene Zeit abgelaufen ist.

 

de.cib.docserv.MaintenanceLogPath

Geben Sie hier bitte ein spezifisches Verzeichnis zur Ausgabe der erzeugten Logdateien an. Das Verzeichnis muss bereits existieren.

Wird hier kein Verzeichnis angegeben, wird das Arbeitsverzeichnis unter CibDocumentServer/work verwendet.

 

Hinweis: Die erzeugten Logdateien werden in einem Unterverzeichnis gespeichert, benannt nach dem aktuellen Timestamp (Beispiel: "21-10-2016_13.39.29.569").


Umgebungsvariablen

de.cib.docserv.socket.Environment=

de.cib.docserv.socket.Environment1=

de.cib.docserv.socket.Environment9=

Es besteht die Möglichkeit, bis zu 10 unterschiedliche Umgebungsvariablen zu konfigurieren. So können Sie beispielsweise den LD_LIBRARY_PATH, LIBPATH oder die Zeitzone setzen. Falls der Wert dieses Parameters leer ist, wird er nicht ausgewertet.

 

Beispiel:

de.cib.docserv.socket.Environment=LD_LIBRARY_PATH=../bin

de.cib.docserv.socket.Environment1=TZ=AST+04ADT

 

Diese und alle weiteren Konfigurationseinstellungen sind in der Vorlage CibDocumentServer.properties ausreichend dokumentiert.


Beispiel Zeitzonendefinition AIX

Um auf AIX Systemen die verwendete Zeitzone korrekt zu setzen, wird die Property de.cib.docserv.socket.Environment1 verwendet. Sommerzeit/Winterzeit müssen berücksichtigt werden.

Im folgenden Beispiel wird die Zeitzone auf Mitteleuropäsche Zeit festgelegt und Zeitumstellungen berücksichtigt:

 

de.cib.docserv.socket.Environment1=TZ=CET-1DFT,M3.5.0/2,M10.5.0/3

 

CET

Central European Time, Mitteleuropäische Zeit

-1

Unterschied von CET zu UTC

DFT

Berücksichtigt die Sommerzeit (Daylight Saving Time) ab März bis Oktober

M3.5.0/2

Setzt den Startzeitpunkt für die Sommerzeit fest:

M3 steht für den Monat März

5 steht für die letzte Woche im Monat

0 steht für Sonntag

/2 steht für 2:00 Uhr

M10.5.0/3

Setzt das Ende der Sommerzeit/ Beginn Winterzeit fest

Analog zur Beschreibung oben am letzten Sonntag im Oktober um 3:00 Uhr

 

Hinweis:

Gibt man die Start- und Endzeitpunkte der Sommerzeit nicht dediziert vor, wird der Systemstandard verwendet. Dieser folgt dem US-amerikanischen Stichtag und ist folglich der zweite Sonntag im März, 2:00 Uhr bzw. der erste Sonntag im Oktober, 2:00 Uhr


Konfiguration der Einbindung mit LibreOffice

CIB documentServer bietet die Möglichkeit eine Einbindung mit LibreOffice zu konfigurieren, die von anderen Projekten benötigt wird, wie beispielsweise CIB doXichange.

Dafür müssen folgende Parameter im CibDocumentServer.properties gesetzt werden: 

· Linux

     - de.cib.docserv.socket.Environment=LD_LIBRARY_PATH=../bin:/opt/cib/LO/program

     - de.cib.docserv.socket.Environment1=LOPath=/opt/cib/LO/program

· Windows

     - de.cib.docserv.socket.Environment1=LOPath=c: \\opt\\cib\\LO\\program

In den Beispielen wird c:\opt\cib bzw. /opt/cib als Pfad für die Installation angenommen, bei abweichenden Installationspfaden muss die Konfiguration angepasst werden.

Ab Version 1.11.3 kann man dazu optional das Workverzeichnis von CIB LibreOffice auf ein angegebenes Verzeichnis setzen. Dafür wird die Umgebungsvariable LOWorkerFolder verwendet:

· Linux

     - de.cib.docserv.socket.Environment2=LOWorkerFolder=/opt/cib/LOWorkerFolder

· Windows

     - de.cib.docserv.socket.Environment2=LOWorkerFolder=c: \\opt\\cib\\LOWorkerFolder

Setz man dieses Verzeichnis nicht, dann wird das Workverzeichnis standardmässig unter dem LibreOffice Program Pfad (LOPath) erstellt.

Jobconfig.xml für CIB docgen Default-Properties

Der Pfad zur jobconfig.xml wird in der Konfigurationsdatei CibDocumentServer.properties angegeben (siehe Abschnitt Konfigurationspfad).

Die jobconfig.xml enthält Defaultwerte für alle in Aufträgen angebbaren Properties der CIB docgen, und zwar geordnet nach Kommando. Details hierzu werden im Leitfaden für CIB job ausführlich dargestellt. Aus Sicht des CIB documentServers ist es lediglich wichtig, dass der Pfad zur jobconfig.xml korrekt in der .properties Datei hinterlegt ist, und diese wiederum auf Fonts, Templates und Druckereinstellungen zeigt.

Die Pfadangaben zu den Templates in der jobconfig.xml sind unter Windows auf den Wert „C:/cib/templates“ und Unter Unix auf den Wert „/opt/cib/templates“ voreingestellt. Legen Sie ihre Templates an einer anderen Stelle ab, müssen Sie hier die Einstellungen entsprechend anpassen.

Das Beispiel in Kapitel 3.2.7 zeigt das empfohlene Vorgehen.


Konfiguration von Sprachdateien für Texterkennung durch CIB ocr

CIB documentServer bietet ab Version 1.8.0 optische Zeichenerkennung (OCR) unter Windows und Linux für die Sprachen Deutsch, Russisch und Englisch. Ab Version 1.9.6 werden zusätzlich unterstützt: Chinesisch, Französisch, Italienisch, Japanisch und Spanisch.

Damit wird der Funktionsumfang um die Unterstützung von automatischer Text- und Barcodeerkennung erweitert. Diese kann über das Modul CIB ocr erfolgen, welches hierzu entsprechende Dateien für jede zu erkennende Sprache benötigt.

Diese Sprachdateien sind entsprechend umfangreich (Dateigröße ca. 15 MB) und werden daher seit Version 1.9.6 nicht mehr im documentServer Paket mitgeliefert, sondern können bei entsprechender Anforderung unter folgendem Link bezogen werden: https://download.cib.de/CIBdocumentServer/anon/CIBocr-tessdata.zip

 

Die Pfadangaben zu den Sprachdateien in der Datei jobconfig.xml sind je nach System auf folgende Standardwerte voreingestellt:

     Windows: "C:\opt\cib\tessdata"

     Linux:"/opt/cib/tessdata"

Wenn Sie die Sprachdateien an anderer Stelle ablegen wollen, müssen die Einstellungen hier entsprechend angepasst werden.


Beispielsituation zur Konfiguration einschließlich forward-Properties

Die CibDocumentServer.properties-Datei im EAR verwendet die Forward-Konfigurations-Einstellung, um auf eine CibDocumentServer.properties-Datei zu verweisen, die im gewünschten zentralen Verzeichnis /opt/cib/conf liegt (Beispiel JBoss):

/opt/jboss/servers/default/deploy/CibDocumentServer-1.4.19d.ear enthält folgende CibDocumentServer.properties:

# Forward to this configuration:

de.cib.docserv.ForwardConfigurationFilename=

/opt/cib/conf/CibDocumentServer.properties

Sie haben die folgenden Verzeichnisse angelegt:

/opt/cib/conf

/opt/cib/logs

/opt/cib/ppd

/opt/cib/fonts

/opt/cib/templates

/opt/cib/forms

Darin sind in folgenden Dateien neben weiteren Angaben folgende Pfadangaben gesetzt: /opt/cib/conf/CibDocumentServer.properties

# Path to configuration file for CIB job (jobconfig.xml)
de.cib.docserv.JobConfigfilename=/opt/cib/conf/jobconfig.xml

# Logpath for Socketserver and CIB docgen modules
de.cib.docserv.LogPath=/opt/cib/logs

# Forms for CIB formserver 
de.cib.formserv.FormsPath=/opt/cib/forms

/opt/cib/conf/jobconfig.xml:

/opt/cib/templates
/opt/cib/templates		
		
/opt/cib/templates
/opt/cib/ppd/hp4050_6.ppd
/opt/cib/fonts		
		
/opt/cib/templates	
	
/opt/cib/templates
		
	

Das ergibt folgendes Bild an Konfigurationseinstellungen:



Monitoring mit MBean DocservRuntime (ab 1.5.55f)

Der Java Managed Extensions Spezifikation folgend ermöglicht CIB documentServer über die Managed Bean (MBean) „DocservRuntime“, bestimmte Kennzahlen während des Betriebes auszulesen und zu überwachen. Das Monitoring über diese MBean ist auf allen Plattformen verfügbar ab der CIB documentServer Version 1.5.55f.

Monitoring-Funktionalität Aktivieren

Um die Monitoring-Funktionalität nutzen zu können, müssen am Applikationsserver die Java Management Extensions (JMX) aktiviert sein.

Am Beispiel eines Tomcat ist Folgendes im catalina.bat (catalina.sh) Skript zu konfigurieren (der Aufruf ist in einer Zeile zu schreiben, die Umbrüche hier wurden zur besseren Lesbarkeit eingefügt. Im Catalina.sh ist das „set“ zu entfernen):

set CATALINA_OPTS=-Dcom.sun.management.jmxremote
  -Dcom.sun.management.jmxremote.port=%my.jmx.port%
  -Dcom.sun.management.jmxremote.ssl=false
  -Dcom.sun.management.jmxremote.authenticate=false

Siehe auch: https://tomcat.apache.org/tomcat-7.0-doc/monitoring.html#Enabling_JMX_Remote

In der CIB documentServer web.xml ist ein Listener zu registrieren. Standardmäßig ist die Zeile 

 de.cib.docserv.http.jmx.RegisterMBeansListener 
auskommentiert. Um die DocservRuntime MBean zu aktivieren, muss diese Zeile einkommentiert werden:


 de.cib.docserv.http.ContextListener 
 de.cib.docserv.http.jmx.RegisterMBeansListener 

Nun können Sie aus Ihrer Monitoring Anwendung die MBean "DocservRuntime" ansteuern.


Überwachte Kennzahlen

Die folgenden Kennzahlen werden überwacht bzw. können ausgelesen werden:

  • "de.cib.docserv.NumberOfQueuedRequests": Anzahl der Requests in der Warteschlange
  • "de.cib.docserv.NumberOfSocketServersInUse": Anzahl der belegten Socketserver
  • "de.cib.docserv.MaxServerQueueLength": Der voreingestellte Wert für die maximale Länge der Serverwarteschlange

Am Beispiel der Java Monitoring & Management Console:



Hinweis:
Eine Abfrage durch die Monitoring Komponente über die MBean liefert immer nur eine Momentaufnahme des Zustands zum Zeitpunkt der Abfrage. Es werden also von der MBean keine Zwischenwerte bis zur nächsten Abfrage gesammelt. Das bedeutet z. B., dass Lastspitzen, die vor oder nach einer Abfrage auftreten, von dieser nicht erfasst werden.
Um über einen Zeitraum kontinuierlich Daten zu erheben muss das Polling auf entsprechend kurze Intervalle eingestellt werden. Dies ist abhängig vom eingesetzten Monitoring Tool in der Ansteuerung der MBean zu konfigurieren.