CIB documentServer technical documentation (EN)
Quick Start
Configuration
You can easily configure the number of started socket servers, different timeouts and other parameters that the framework also offers. This section gives an overview of how you can customize the configuration of the CIB documentServer to your individual needs. Here is a description of the contents of the configuration file CibDocumentServer.properties and how to modify it to make settings on the CIB documentServer.
CibDocumentServer.properties
CibDocumentServer-Forward.properties (from 1.4.19d)
Specifying configurations on the command line
Content of the CibDocumentServer.properties
Jobconfig.xml for CIB docgen default properties
Configuration of language files for text recognition with CIB ocr
Example situation to configure forward properties as well
Monitoring with MBean DocservRuntime (ab 1.5.55f)
CibDocumentServer.properties
Configure your CIB documentServer by adjusting the settings in the CibDocumentServer.properties file, not in the CibDocumentServer/WEB-INF/web.xml file, as it will be replaced when an updated CIB documentServer version is delivered.
This file then contains your customer and server-specific configuration.
An extensively annotated template is supplied for your platform.
If you deploy the CIB documentServer as an EAR file, place the CibDocumentServer.properties in the EAR next to the CibDocumentServer.war.
If you deploy the CIB documentServer as a WAR file, place the CibDocumentServer.properties next to the WAR (depending on the application server).
First, the CibDocumentServer.properties is always searched for in the class path of the CibDocumentServer Web application. This is also used to find the properties file in the EAR.
CibDocumentServer-Forward.properties (from 1.4.19d)
Example:
##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
If you run the CIB documentServer in several instances, you can create a separate tree of configuration settings for each instance by specifying the ForwardConfiguration Filename.
Specifying confgurations on the command line
These configuration settings, starting with the ForwardConfigurationFilename, can also be specified on the command line of the Java VM with -D, if this is practical in your situation, for example on the two nodes of a cluster:
-Dde.cib.docserv.ForwardConfigurationFilename= /opt/cib/conf/CibDocumentServer.properties
In case you are using a configuration file in the application directory, please note that specifying the property ForwardConfigurationFilename on the command line has priority.
Content of the CibDocumentServer.properties
The following important settings are available to configure the CIB documentServer with regard to configuration path, performance, ports and logging.
Note: Always use slashes (/) for the path specification also under Windows.
de.cib.docserv.JobConfigfilename=/opt/cib/conf/jobconfig.xml
Specify the path for the configuration of CIB job and CIB docgen here. The specified file contains no settings for the CIB documentServer itself.
en.cib.docserv.http.PrestartOnLoad=true
If the socket server processes should be started immediately when the CIB documentServer Web application is started, i.e. also when the application server is started, specify true here.
en.cib.docserv.socket.IdleShutdownTime=3600
If there is no load on the machine during certain periods of time, the socket server processes can terminate automatically after this time (in seconds). They are restarted automatically if necessary. If 0 is specified, the socket server processes are not automatically terminated.
en.cib.docserv.MaxProcessCount=10
At this point you should adapt the CIB documentServer to your server hardware and the desired throughput. More socket server processes leave less processing power for other applications. Fewer processes may not reach the set throughput numbers. There are no other essential performance relevant settings in the CIB documentServer.
en.cib.docserv.MaxJobCountPerProcess=100
This enables an automatic restart of the socket server processes when the specified number of jobs has been processed. The log files of CIB job and CIB docgen are restarted and can be limited in size. A value of -1 disables the automatic restart.
en.cib.docserv.job.MaxJobExecutionTime=600000
If users have an influence on the runtime of orders (RTF, number of data records), this setting can be used to limit the runtime of orders. These are then terminated and the socket server is terminated. The calling application receives an error response, but the users cannot block the server for a long time. If 0 is specified, no termination is performed.
This setting requires CIB socketserver 1.6.1, CIB job 1.6.2 and CIB merge 3.10.3. The function is currently only effective for "merge" commands.
en.cib.docserv.socket.MaxMemory=250
With this setting the maximum amount of RAM that can be allocated for each process of the CIB socketserver can be defined in megabytes. If a CIB socketserver reaches this limit, the process will terminate. This setting, multiplied by the number of CIB socket servers (see property de.cib.docserv.MaxProcessCount), gives a rough value for the maximum memory used by the native processes.
This setting requires CIB socketserver 1.6.2 and is currently available on Linux-x86, Solaris-x86 and Solaris Sparc platforms.
en.cib.docserv.MaxProcessCountAsync=3
Maximum number of SocketServer ports for asynchronous requests.
The requests are first stored in a queue and then processed sequentially.
de.cib.docserv.socket.FirstPort=50000
If ports are already in use on your system or if there are specifications for ports, the number of the first port in the port range can be specified here. Each additional socket server process increases the range by one (see MaxProcessCount).
In the case of dynamic port reservation, this value specifies the
beginning of the range in which the CIB documentServer attempts to reserve
ports. As of version 1.20.0 it is no longer necessary to use an initial port
for dynamic port reservation. See UseDynamicPortSelection.
de.cib.docserv.socket.LastPort=50200
When using dynamic port reservation, this value indicates the end of the range in which the CIB documentServer tries to reserve ports. See UseDynamicPortSelection. From version 1.5.20.
de.cib.docserv.socket.UseDynamicPortSelection=true
Enable dynamic port reservation if you want to use more than one CIB documentServer on a machine or do not want to specify the exact port range. See also FirstPort and LastPort. As of 1.5.26
As of version 1.20.0, the behaviour of the property has been changed. It is no longer searched by a specific portrange. It is dynamically checked for free ports and as many are reserved as are used in the property MaxProcessCount.
The insertion of the property LastPort is no longer required and from version 1.20.0 this is no longer available.
The selected port range depends on the operating system and is usually:
- 49152 - 65535 for Windows
- 32765 - 60999 for Linux
de.cib.formserv.FormsPath=/opt/cib/forms
Set the path to the fillable forms for the CIB formserver here. These can then be called via the URL of the CIB documentServer supplemented by /forms.
The path to the forms in which the entered data is stored is defined in the jobconfig.xml (pdfmerge, WorkSpace). From Version 1.5.x.
de.cib.docserv.LogConfigFilename = /opt/cib/conf/log4j.xml
de.cib.docserv.LoggingMode = log4j (ab CIB documentServer 1.16.0)
If a LogConfigFilename is given, it will be corrected for the configuration of the logging.
If the file does not exist, only the console is logged.
By specifying the logging mode you can set log4j or log4j2.
By default log4j is used if the property is empty or not set.
Loggin of the CIB docgen modules
de.cib.docserv.LogOptions=SJ
de.cib.docserv.LogPath=/opt/cib/logs
These two parameters control the type and location of the log files.
By specifying a letter sequence in the LogOptions (e.g. de.cib.docserv.LogOptions=SMPFJEOIZ) log files are created. The file names are predefined.
If a LogPath is specified, the log files will be created there. Otherwise, the log files will be created in the working directory of the socket server process.
If the specified LogPath does not exist, the log files are created in the working directory (specified via the property "de.cib.docserv.ServerWorkingDirectory") of the socket server process (from version 1.11.1).
The log output of the corresponding module can be activated by entering the following character:
|
Character |
Module |
Log filename |
|
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 (Character O) |
CIB ocr |
ocrtrace.log |
|
I |
CIB image toolbox |
imgtrace.log |
|
Z |
CIB invoice toolbox |
invtrace.log |
Configuration of the Maintenance Feature
The properties of the Maintenance Feature to be set are described below.
de.cib.docserv.AutoMaintenance
If the maintenance functionality should be started immediately when the application server is started, enter "true" here.
de.cib.docserv.KnownErrorCodes
Define here for which error messages the orders should not be executed again by the maintenance process.
de.cib.docserv.ExecutionsNumber
de.cib.docserv.TimeSection
These two settings can be used to define the maximum number of jobs per specified time period that are executed by the maintenance process. If the maintenance process reaches this limit, no further requests are executed until the specified time has expired.
de.cib.docserv.MaintenanceLogPath
Please enter a specific directory for the output of the generated log files. The directory has to exist already.
Note: The generated log files are stored in a subdirectory named after the current timestamp (Example: "21-10-2016_13.39.29.569").
de.cib.docserv.socket.Environment=
de.cib.docserv.socket.Environment1=
…
de.cib.docserv.socket.Environment9=
It is possible to configure up to 10 different environment variables. For example, you can set the LD_LIBRARY_PATH, LIBPATH or the time zone. If the value of this parameter is empty, it is not evaluated.
Example:
de.cib.docserv.socket.Environment=LD_LIBRARY_PATH=../bin
de.cib.docserv.socket.Environment1=TZ=AST+04ADT
These and all other configuration settings are documented sufficiently in the template CibDocumentServer.properties.
Example time zone definition AIX
To correctly set the time zone used on AIX systems, the property de.cib.docserv.socket.Environment1 is used. Summer time/winter time must be taken into account.
In the following example, the time zone is set to Central European Time and time changes are taken into account:
de.cib.docserv.socket.Environment1=TZ=CET-1DFT,M3.5.0/2,M10.5.0/3
|
CET |
Central European Time |
|
-1 |
Difference from CET to UTC |
|
DFT |
Respects summer time (Daylight Saving Time) from March to October |
|
M3.5.0/2 |
Sets the start time for Daylight Saving Time M3 represents the month March 5 represents the last week oft he month 0 represents sunday /2 represents 2:00 a.m. |
|
M10.5.0/3 |
Sets the end of summer time/beginning of winter time Similar to the description above on the last Sunday in October at 3:00 |
Note:
If the start and end times of daylight saving time are not dedicated, the system standard is used. This follows the US key date and is therefore the second Sunday in March, 2:00 a.m. or the first Sunday in October, 2:00 a.m.
Configuration of the implementation of LibreOffice
The CIB documentServer offers the possibility to configure an integration with LibreOffice, which is required by other projects, such as CIB doXichange.
For this purpose the following parameters have to be set in the CibDocumentServer.properties:
- 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 the examples, c:\opt\cib or /opt/cib is assumed to be the path for the installation; if the installation paths differ, the configuration has to be adjusted.
From version 1.11.3 you can optionally set the work directory of CIB LibreOffice to a specified directory. The environment variable LOWorkerFolder is used for this:
- Linux
- de.cib.docserv.socket.Environment2=LOWorkerFolder=/opt/cib/LOWorkerFolder
- Windows
- de.cib.docserv.socket.Environment2=LOWorkerFolder=c: \\opt\\cib\\LOWorkerFolder
If you do not set this directory, the work directory will be created under the LibreOffice Program Path (LOPath) by default.
Jobconfig.xml für CIB docgen Default-Properties
The path to jobconfig.xml is set in the configuration file CibDocumentServer.properties (see Configuration Path).
The jobconfig.xml contains default values for all CIB docgen properties which can be specified in jobs, ordered by command. Details are described in the CIB job guide. From the point of view of the CIB documentServer, it is only important that the path to the jobconfig.xml is correctly stored in the .properties file which points to fonts, templates and printer settings.
The paths to the templates in jobconfig.xml are preset on Windows to the value "C:/cib/templates" and on Unix "/opt/cib/templates". If you store your templates in a different location, you have to adjust the settings accordingly.
Configuration of the language file for text recognition with CIB ocr
From version 1.8.0 CIB documentServer offers optical character recognition (OCR) on Windows and Linux for the languages German, Russian and English. From version 1.9.6 additionally supported are: Chinese, French, Italian, Japanese and Spanish.
This extends the range of functions to support automatic text and barcode recognition. This can be done via the module CIB ocr, which requires corresponding files for each language to be recognized.
These language files are accordingly extensive (file size approx. 15 MB) and are therefore no longer included in the documentServer package since version 1.9.6, but can be downloaded from the following link: https://download.cib.de/CIBdocumentServer/anon/CIBocr-tessdata.zip
The paths to the language files in the jobconfig.xml file are preset to the following default values depending on the system:
Windows: "C:\opt\cib\tessdata"
Linux:"/opt/cib/tessdata"
If you want to store the language files elsewhere, the settings must be adjusted accordingly here.
Example situation to configure forward properties as well
The CibDocumentServer.properties file in the EAR uses the forward configuration setting to point to a CibDocumentServer.properties file located in the desired central directory /opt/cib/conf (example JBoss):
/opt/jboss/servers/default/deploy/CibDocumentServer-1.4.19d.ear contains the following CibDocumentServer.properties:
# Forward to this configuration:
de.cib.docserv.ForwardConfigurationFilename= /opt/cib/conf/CibDocumentServer.properties
You have created the following directories:
/opt/cib/conf
/opt/cib/logs
/opt/cib/ppd
/opt/cib/fonts
/opt/cib/templates
/opt/cib/forms
In the following files the following path specifications are set in addition to other specifications /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:
<Comod>
<defaults>
<properties command="merge">
<property name="-a">/opt/cib/templates</property>
<property name="-q">/opt/cib/templates</property>
</properties>
<properties command="format">
<property name="WorkSpace">/opt/cib/templates</property>
<property name="PpdFilename">/opt/cib/ppd/hp4050_6.ppd</property>
<property name="FontWorkSpace">/opt/cib/fonts</property>
</properties>
<properties command="pdfjoin">
<property name="WorkSpace">/opt/cib/templates</property>
</properties>
<properties command="pdfmerge">
<property name="WorkSpace">/opt/cib/templates</property>
</properties>
</defaults>
</Comod>
This gives the following picture of configuration settings:
Monitoring wih MBean DocservRuntime (ab 1.5.55f)
Activate the monitoring funcionTo use the monitoring functionality, the Java Management Extensions (JMX) must be activated on the application server.
Using the example of a Tomcat, the following has to be configured in the catalina.bat (catalina.sh) script (the call has to be written in one line, the breaks here have been inserted for better readability. In catalina.sh the "set" has to be removed):
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
See also: https://tomcat.apache.org/tomcat-7.0-doc/monitoring.html#Enabling_JMX_Remote
A listener has to be registered in the CIB documentServer web.xml. By default, the line
<listener-class> de.cib.docserv.http.jmx.RegisterMBeansListener </listener-class>
is commented out. To activate the DocservRuntime MBean, this line must be
commented:
<listener> <listener-class> de.cib.docserv.http.ContextListener </listener-class> <!-- enable DocservRuntime MBean --> <listener-class> de.cib.docserv.http.jmx.RegisterMBeansListener </listener-class>
</listener>
Now you can
access the MBean "DocservRuntime" from your monitoring application.
Monitored key indicators
The following key indicators are monitored or can be read:
- "de.cib.docserv.NumberOfQueuedRequests": Amount of requests in the queue
- "de.cib.docserv.NumberOfSocketServersInUse": Amount socket servers in use
- "de.cib.docserv.MaxServerQueueLength": The default value for the maximum server queue length
- Using the example of the Java Monitoring & Management Console:
Note:
A query by the monitoring component via MBean always provides only a snapshot
of the status at the time of the query. Therefore, no intermediate values are
collected by MBean until the next query. This means, for example, that load
peaks that occur before or after a query are not recorded by the query.
To collect data continuously over a period of time, polling must be set to short intervals. Depending on the monitoring tool used, this must be configured in the MBean control.