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)

If you want to configure the CibDocumentServer.properties outside of the directory structure of your application server, use the setting de.cib.docserv.ForwardConfigurationFilename to reference your desired .properties file from the application server. This means that a shortened and constant CibDocumentServer.properties file is deployed in the application server that refers to the actual configuration. You can find a template with a quick guide in the CibDocumentServer-Forward.properties.

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.


Configuation path

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.


Performance

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.


Ports

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

Forms

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.


Logging

CIB documentServer

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").


Environment variables

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)

Following the Java Managed Extensions specification, CIB documentServer enables "DocservRuntime" via the Managed Bean (MBean) to read and monitor certain key figures during operation. Monitoring via this MBean is available on all platforms from CIB documentServer version 1.5.55f.


Activate the monitoring funcion

To 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.