CIB documentServer technical documentation (EN)

Installation

Depending on whether the CIB documentServer will be installed in a servlet container like Tomcat or on an application servers like JBoss or BEA Weblogic, there are different procedures. In the following, Tomcat, JBoss and BEA Weblogic are used as examples to describe how the CIB documentServer can be deployed in the respective environment.

If you want to install the CIB documentServer as a web service, you will find all necessary information for deployment in this chapter. The installation as a web service is described using SOAP and JAX-WS.

Please observe the installation requirements.

Installation Requirements

To use the CIB documentServer on a server, a Java runtime environment (JRE or JDK) and a JEE servlet container or a JEE application server are required.

Please install a suitable and recent Java Runtime Environment (JRE or JDK) 32bit or 64bit as standard installation on your desired server platform. Configure the Java VM suitable for usage in production: memory settings, selection of garbage collector, further settings.

Then deploy a servlet container or application server according to the manufacturer's instructions. In the simplest case, unzip a recent Tomcat.zip suitable for your platform. Configure the servlet container or application server suitable for usage in production: memory settings, threads, timeouts, load balancing, upstream web server, other settings.

Install the CIB documentServer as described in the following.

It is especially important to note that the CibDocumentServer.war must be available unpacked in the servlet container or application server after deployment. Otherwise it is not possible to operate the CIB documentServer.

The use of EAR files is always necessary if the CibDocumentServer.properties file cannot be deployed next to the .war in any other way. Most application servers therefore require this step.

It is especially important to note that the CibDocumentServer.war must be available unpacked in the servlet container or application server after deployment. Otherwise it is not possible to operate the CIB documentServer.

The use of EAR files is always necessary if the CibDocumentServer.properties file cannot be deployed next to the .war in any other way. Most application servers therefore require this step.

Usage of CIB doXichange

(supported from CIB documentServer version 1.9, requires CIB job 2.0.1)

With CIB doXichange a document is converted into a PDF (version 1.4). For this purpose LibreOffice powered by CIB is used.

The platforms Windows 32/64bit and Linux 32/64bit are supported

The document conversion is offered for the following extensions: 

.123, .602, .abw, .bmp, .cdr, .cgm, .cmx, .cwk, .dbf, .dif, .doc, .docm, .docx, .dot, .dotm, .dotx, .dxf, .emf, .eps, .fb2, .fh, .fh1, .fh10, .fh11, .fh2, .fh3, .fh4, .fh5, .fh6, .fh7, .fh8, .fh9, .fodg, .fodp, .fods, .fodt, .gnm, .gnumeric, .htm, .html, .hwp, .key, .lrf, .lwp, .mcw, .met, .mml, .mw, .mwd, .numbers, .nx^d, .odc, .odf, .odg, .odg, .odm, .odp, .ods, .odt, .otg, .otm, .otp, .ots, .ott, .p65, .pages, .pbm, .pcd, .pct, .pcx, .pgm, .pict, .pm, .pm6, .pmd, .pot, .potm, .potm, .potx, .potx, .ppm, .pps, .ppsx, .ppsx, .ppt, .pptm, .pptm, .pptx, .psd, .pub, .ras, .sgf, .sgv, .slk, .stc, .std, .sti, .stw, .svg, .svgz, .svm, .sxc, .sxd, .sxg, .sxi, .sxm, .sxw, .sylk, .tga, .tif, .tiff, .uof, .uop, .uos, .uot, .vdx, .vsd, .vsdm, .vsdx, .wb2, .wdb, .wk1, .wk1, .wk3, .wks, .wmf, .wn, .wpd, .wpg, .wps, .wps, .wq1, .wq2, .wri, .xbm, .xlc, .xlk, .xlm, .xls, .xlsb, .xlsm, .xlsx, .xlt, .xltm, .xltx, .xlw, .xpm, .zabw.

LibreOffice powered by CIB installations

The Linux versions 32/64 bit are delivered as .tar.gz archives.

The Windows versions 32/64 bit as ZIP archives.

The LibreOffice installation directory must be set in the configuration, see Configuration CIB doXichange.

Attention:

On Windows it is required that the VisualC++ redistributables are installed for the architecture you are using (x86/x64). They can be found at:

"https://www.microsoft.com/de-de/download/details.aspx?id=40784"

When using a LibreOffice 64bit, a CIB documentServer 64bit is required. The same applies to the 32bit versions.

Using installed macros

From CIB documentServer 1.10.5 it is possible to run a macro installed in LibreOffice.

Details are described in the CIB job guide.

Installation in a JEE Servlet-Container

To install the CIB documentServer in a servlet container, the following genereal procedure has to be followed:

Installation in Apache Tomcat

1. Versions of Apache Tomcat from 8.5.38 in combination with Java JDK from 8u161 are recommended.
2. Copy the application archive CibDocumentServer.war into the webapps subdirectory of your Tomcat installation.
3. Delete the context file CibDocumentServer.xml from the subdirectory conf/Catalina/localhost if necessary.
4. Make sure that there is no entry <Context path= "/CibDocumentServer"…</Context> in the conf/server.xml file.
5. There are two ways to store the CibDocumentServer.properties:
   Copy the file to the webapps folder so that you do not need to make any further settings
   If you store the properties file in a different location, this directory must be in the class path of the CIB documentServer web application. You can find out how to adapt the settings to your individual requirements in the chapter Configuration.
6. Launch Tomcat. In the log an entry "Context CIB documentServer initialized." must appear during the start of the container.

Installation in a JEE Application Server

If the CIB documentServer is to be installed on an application server such as JBoss, GlassFish or BEA Weblogic, 

this can be done via the WAR file or via a so-called EAR file. 

There are two procedures for creating an EAR file (WAR unpacked/not unpacked), which are described below. 

Which procedure is to be used for which server product is described in the respective installation instructions.

The EAR contains:

1. File CibDocumentServer.war (unchanged archive as received from CIB)
2. File CibDocumentServer.properties (configuration or forward configuration)
3. Subdirectory META-INF
4. File META-INF/application.xml (EAR-Descriptor)

Minimal content of the file application.xml in the subdirectory META-INF:

<?xml version="1.0" encoding="UTF-8"?>
<application>
<display-name>CIB documentserver</display-name>
<description>Deployment package for CIB
documentserver</description>
<module><web>
       <web-uri>CibDocumentServer.war</web-uri>
       <context-root>CibDocumentServer</context-root>
</web></module>
</application>

Finally, you need to create a zip archive from the four elements mentioned above, rename it to CibDocumentServer-<version>.ear and deploy it.

The EAR contains:

1. Folder CibDocumentServer (unpacked CibDocumentServer.war)
2. File CibDocumentServer.properties (configuration or forward configuration)
3. Subdirectory META-INF
4. File META-INF/application.xml (EAR-Descriptor)

Minimum content oft he file application.xml in the subdirectory META-INF:

<?xml version="1.0" encoding="UTF-8"?>
<application>
<display-name>CIB documentserver</display-name>
<description>Deployment package for CIB documentserver</description>
<module><web>
       <web-uri>CibDocumentServer</web-uri>
       <context-root>CibDocumentServer</context-root>
</web></module>
</application>

Finally, you need to create a zip archive from the above four elements, rename it to CibDocumentServer-<version>.ear and deploy it.

This is supported from version 1.15.6. For earlier Versionen please go to chapter 3.1.3.3.2 Installation of an unpacked WAR.

1. Download Wildfly
2. Define the following directory structure under the subdirectory „modulescib/documentserver/main“
3. Copy the „CibDocumentServer.properties“ file in the subdirectory „cib/documentserver/main“
4. Create the following new file module.xml in the subdirectory „cib/documentserver/main“  with the following content

<?xml version="1.0" encoding="UTF-8"?>  
<module xmlns="urn:jboss:module:1.1" name="cib.documentserver">     
<resources>         
<resource-root path="."/>     
</resources>  
</module>

5. Copy the application archive CibDocumentServer.war in the subdirectory „standalone/deployments“
6. Restart Wildfly

1. Download Wildfly.
2. Create inside the folder „standalone/deployments“ another folder called „CibDocumentServer.war“.
3. Unpack the unchanged „.war“in this folder.
4. Copy the file „CibDocumentServer.properties“ in the directory „standalone/deployments“.
5. Create an empty marker file named „CibDocumentServer.war.dodeploy“.
6. Open this file „CibDocumentServer.war.dodeploy“ with a text editor, enter the text „CibDocumentServer.war“ (without quotation marks) and save the file.
7. Restart Wildfly

The CibDocumentServer.war can be deployed using the GlassFish command line tools or the graphical WebUI without any further changes.

The CibDocumentServer.properties configuration file can be placed in the glassfish\domains\<domain>\applications directory of your GlassFish domain.

Installation of an EAR in GlassFish 5

The EAR has to be used without the unpacked WAR in the GlassFish application server.

The compatibility with Oracle Weblogic 12 is only given from versions 1.15.2.

The following methods can be used for deployment.

The automatic deployment of a war file is considered only from versions 1.15.8.

Shut down the BEA weblogic 12 Server

Copy the EAR file in the folder „autodeploy“ of the weblogic domain (<beahome>/.../<domain>/autodeploy)

Start BEA weblogic 12 Server

The deployment of the CIB documentServer takes places automatically. Additionally, there will be made an entry in the file „config.xml“ (<beahome>/.../<domain>/config/config.xml).

To delete the CIB documentServer, shut down the weblogic server and remove the EAR file from the "autodeploy" directory. The next time the weblogic server is started, the corresponding entry from the "config.xml" file will be removed automatically.

Shut down BEA weblogic 12 Server

Remove all <app-deployment> elements that refer to the CibDocumentServer from the Weblogic 12 configuration file:

<bea-home>/.../<domain>/config/config.xml

Configure the CIB documentServer in CibDocumentServer.properties

Deploy the unpacked WAR archive:

• Unpack the WAR into the directory

<bea-home>/.../<domain>/autodeploy/CibDocumentServer

• Copy the CibDocumentServer.properties to

<bea-home>/.../<domain>/autodeploy/CibDocumentServer.properties

Start BEA weblogic 12 Server

After starting the Weblogic Server the CIB documentServer is deployed. Additionally, the necessary entry in the Weblogic Server configuration file "config.xml" is made automatically. This file is located in the following directory:

<bea-home>/.../<domain>/config/

To delete the CIB documentServer, please shut down the BEA weblogic server. Then remove the CibDocumentServer directory and the CibDocumentServer.properties file from the autodeploy directory. The next time you start the weblogic server, the corresponding entry in the "config.xml" file will be removed automatically.

Shut down the BEA weblogic server

Remove all <app-deployment> elements that refer to the CibDocumentServer from the Weblogic Server configuration file

<bea-home>/.../<domain>/config/config.xml

Configure the CIB documentServer in CibDocumentServer.properties

Define another directory for external configuration files. For example:

<bea-home>/.../<domain>/config/cib

Copy your CibDocumentServer.properties to

<bea-home>/.../<domain>/config/cib/CibDocumentServer.properties

Copy the WAR archive to

<bea-home>/.../<domain>/autodeploy/

Start the BEA weblogic 12 Server

After starting the Weblogic Server the CIB documentServer is deployed. Additionally, the necessary entry in the Weblogic Server configuration file "config.xml" is made automatically. This file is located in the following directory

<bea-home>/.../<domain>/config/

To delete the CIB documentServer, please shut down the BEA weblogic server. Then remove the CibDocumentServer directory and the CibDocumentServer.properties file from the autodeploy directory. The next time you start the weblogic server, the corresponding entry in the "config.xml" file will be removed automatically.

As an example, this section describes a step-by-step installation of the CIB documentServer and all necessary components in a Windows environment from the basis.

Please make sure that Tomcat and the Java environment used are compatible with each other, i.e. both are available in a 32bit or both in a 64bit version. For this example JDK8 and Tomcat version 9.0.5 are used.

Install Java:

1. JDK8 with all features is to install in the standard directory.
2. JRE8 is to install in the standard directory.

Unpack Tomcat:

1. Unpack Tomcat archive file to C:/cib/apache-tomcat-9.0.5
2. Alternatively, install Tomcat with the Windows Installer as a service in this directory.
3. Configure file C:/cib/apache-tomcat-9.0.5/conf/server.xml:

   To enable Tomcat access logging, enable the entry "org.apache.catalina.valves.AccessLogValve“.

Install Tomcat as a service to be available immediately after system start:

1. Set JAVA_HOME for all users in the sistem tot he file path to the desired JDK, e.g.  JAVA_HOME= C:\Program Files\Java\jdk1.8.0_161
2. Authorize the file C:/cib/apache-tomcat-9.0.5/bin/tomcat9.exe (Win7 und Server2008):
   Right-click ➔ Properties ➔ Security ➔ Allow.
   Compability ➔ All Users ➔ Run as administrator
3. Same applies for tomcat6w.exe, tomcat7.exe, tomcat7w.exe (d Tomcat Version).
4. Open the command prompt console with administrator rights (Start Menu>All Programs>Accessories>Control Panel Right Click>Run as Administrator)
5. C:/cib/apache-tomcat-9.0.5/bin/service.bat remove to call in command promt console.
6. C:/cib/apache-tomcat-9.0.5/bin/service.bat install to call in command promt console.
7. C:/cib/apache-tomcat-9.0.5/bin/tomcat9.exe to run (Win7, Server2008), authorize all UAC and Windows Firewall security notes for Tomcat and socketserver.exe.
8. Close command promt console, to shut down Tomcat.
9. On the desktop, create a shortcut to „C:/cib/apache-tomcat-9.0.5/bin/tomcat9w.exe“.
10. Switch to the "Shortcut" tab in the shortcut properties and click the "Advanced..." button.
11. Activate the "Run as administrator" option in the "Advanced Settings" menu.

Install CIB documentServer:

1. Using Tomcat9w.exe, which is started via the shortcut or via the installed "Configure Tomcat" shortcut, various Tomcat parameters can now be set:
Configure the service to Startup "Automatic".
If necessary, increase the memory values in the Java settings, for example 512/512.
Add the following garbage collection settings to the VM parameters:
-Xincgc -XX:MaxGCPauseMillis=500
Note: The server JVM of the JDK is set as default for Tomcat in the Java settings.
2. To start the service, restart the Windows computer, or start it via Tomcat9w in the "General" tab (click on the "Start" button).
3. Open the adress „localhost:8080“ in browser.
   Check, if the Tomcat Homepage appears in the browser with the text „If you're seeing this page via a web browser, it means you've setup Tomcat successfully."

Install CIB documentServer:

1. Copy CibDocumentServer-Forward.properties to C:/cib/apache-tomcat-9.0.5/webapps.
2. Rename CibDocumentServer-Forward.properties to CibDocumentServer.properties.
3. Configure CibDocumentServer-Forward.properties:
   de.cib.docserv.ForwardConfigurationFilename=C:/cib/conf/CibDocumentServer.properties
4. Copy content of the directory opt/cib kopieren to C:/cib
   Configure file C:/cib/conf/CibDocumentServer.properties:
   de.cib.docserv.JobConfigfilename=C:/cib/conf/jobconfig.xml
   de.cib.docserv.LogConfigFilename=C:/cib/conf/log4j.xml
   de.cib.docserv.LogPath=C:/cib/logs
5. When using async jobs with long run time: de.cib.docserv.socket.SocketTimeout=36000000
6. Configure C:/cib/conf/jobconfig.xml:
   Set LicenseCompany and LicenseKey
   Set templates directory to c:/cib/templates (the individual directory entries can also be individually adapted to your own requirements)
7. Configure file C:/cib/conf/log4j.xml:
   Change path to cibdocserv.log: <param name ="FileNamePattern" value= "C:/cib/logs/cibdocserv.%d{yyyy-MM-dd}.log"/>
8. Copy CibDocumentServer.war to C:/cib/apache-tomcat-9.0.5/webapps.
   It should be noted that in a 64bit Windows environment, both the 32bit and 64bit versions of the DocumentServer can be operated, regardless of the bit count of the installed Java or Tomcat environment.

Checking the functionality:

1. Continue with the chapters Initial tests and troubleshooting.
2. Call Web Interface and Startup Test CIB documentServer.
3. Further information on the settings of the document server can be found in the chapter Configuration.

Other installation topics

What to consider when installing the CIB documentServer as a JAX-WS web service is also explained in this section. How to call the web service with the JAX-WS client framework is explained in a later section JAX-WS Client Framework.

To install the CIB documentServer as a SOAP web service, proceed as follows:

1. Deploy the CibDocumentServer.war as usual.
2. Copy the CibDocumentServer.properties file to the same directory. The file must be accessible from the root directory of the CibDocumentServer web application with the relative path specification ../CibDocumentServer.properties.
3. Copy the CibDocumentServer.wsdl file to the same directory. The CibDocumentServer application must be able to access it with the relative path ../CibDocumentServer.wsdl.
4. In the CibDocumentServer.wsdl file, change the URL of your service endpoint. Usually the extension is CibDocumentServer/soap/Generate. Please pay attention to upper and lower case.
5. To check whether the CIB documentServer was installed as a SOAP web service, please call the URL of the service endpoint with the parameter "wsdl". If the web service has been installed correctly, the content of the "wsdl" file will appear when you call it. Example: http://localhost:8080/CibDocumentServer/soap/Generate?wsdl

In most cases, it is best to pack the three files mentioned above into an EAR file, whereby you must have adapted the files beforehand. Your JEE application server will then unpack the files into the specified directories when you deploy the ear file.

To install the CIB documentServer as a JAX-WS web service, JAX-WS must be installed on the server.

For example, to install JAX-WS in Tomcat, proceed as follows:

1. Unpacking JAX-WS
2. Execute the JAXWS<version>-<date>.jar (double click on the file)
3. Accept the license terms (scroll down to the bottom)
4. The archive is unpacked into a subdirectory jaxws-ri
5. Adding JAX-WS to Tomcat
6. Copy jaxws-ri/lib/*.jar to TOMCATHOME/shared/lib
7. Customizing the TOMCATHOME/conf/catalina.properties file
8. Use the shared.loader entry to refer to the copied jar files:
9. shared.loader=${catalina.home}/shared/lib,${catalina.home}/shared/lib/*.jar'.
10. Adjust the rights in the file TOMCATHOME/conf/catalina.policy if necessary
11. Restart Tomcat

1. The URLs must be different: Copy the CibDocumentServer.war file of the desired version for one or each instance and rename it.

2. In the META-INF/Context.xml file in the respective war file, adjust the URL according to the file name.

3. For version 1.4.x of the CIB documentServer, the instances must use separate configurations: To do this, assign individual values in each war file to the configuration values in the WEB-INF/web.xml file, or refer to separate CibDocumentServer.properties in the WEB-INF/web.xml using the setting de.cib.docserv.ForwardConfigurationFilename

4. Starting with version 1.5.x, the instances can also use identical configurations. See Port Selection.

5. With version 1.4.x, the socket servers must use a separate port range: Set the corresponding settings in the individual configurations to disjoint port numbers: de.cib.docserv.socket.FirstPort. Note that the port numbers used are also influenced by de.cib.docserv.MaxProcessCount.

6. With version 1.5.x the socket servers can make a "dynamic port selection". This must be activated (de.cib.docserv.socket.UseDynamicPort¬Selection), and a sufficiently large port range for the total number of socket servers (de.cib.docserv.MaxProcessCount) must be specified (de.cib.docserv.socket.FirstPort, de.cib.docserv.socket.LastPort.

7. As of SocketServer 1.7.0 and documentServer 1.20.0, the pre-allocation of a port range is no longer required. By activating the property, the number of required free ports is searched for and pre-reserved.

8. Recommended is an individual log directory, although the same can be used (de.cib.docserv.LogPath). Individual log settings are possible (en.cib.docserv.LogOptions).

9. The same jobconfig.xml should be used if the two instances have the same version and the same tasks, otherwise two separate jobconfig.xml should be configured (de.cib.docserv.JobConfigfilename).

10. Fonts and printer description files (fonts, ppd files) are usually shared. If not, this requires a separate jobconfig.xml.

Example 1 CIB documentServer 1.4.x:

Example 2 CIB documentServer 1.4.x:

Example 3 CIB documentServer 1.5.x:

Initial tests and troubleshooting

Calling the web interface

After installing the application archive CibDocumentServer.war on the MyServername machine and successfully starting the servlet container, the web interface of the CIB documentServer can be accessed in the standard browser using the following link:

Protokoll://MyServername:Port/CibDocumentServer/

The server MyServer must be accessible from the client via the protocol used and the corresponding port.

Example (Tomcat):

http://MyServername:8080/CibDocumentServer/

You may have to enter a different port for other servlet containers.

This web interface allows you to perform a first startup test of the CIB documentServer, execute jobs directly and make logging settings (from version 1.4.19d).

The "Show configuration" button can be used to display the corresponding settings and paths (from version 1.10.1):

Example (Tomcat):

http://MyServername:8080/CibDocumentServer/forms/formserver-sample.pdf

The following procedure is recommended to prepare the environment for the CIB documentServer optimally. This is not necessary for the execution of the startup tests. For a detailed description of this default configuration, see the section Example situation for configuration including forward properties.

Create the following directories:

/opt/cib/conf

/opt/cib/logs

/opt/cib/ppd

/opt/cib/fonts

/opt/cib/templates

/opt/cib/forms

The template directory is located in the client package under examples/templates. Store the contents of this directory in the created directory /opt/cib/templates. In order for the CIB documentServer to be able to access the templates, the path specifications in the jobconfig.xml must be adjusted if necessary. The example job files are located in the example/jobs directory of the client package.

The CibDocumentServer.properties should be located in the created directory /opt/cib/conf This directory also contains the jobconfig.xml file whose path must be specified in the CibDocumentServer.properties. The path to the log files is also specified there (/opt/cib/logs directory). In addition to the path to the templates (/opt/cib/templates), the jobconfig.xml also contains the paths to the fonts (/opt/cib/fonts) and the printer settings (/opt/cib/ppd).

The fillable forms for the CIB pdf formserver are stored in the forms directory (/opt/cib/forms). The PDF into which the data is merged, on the other hand, is stored in the template directory (/opt/cib/templates).

Some logging settings can be made via the web interface. It is possible to switch off logging completely (link "Logging off"), to switch on logging that creates log files for socket server and CIB job (link "Normal logging (SJ)"), or to set logging to create all possible log files (link "Full logging (SJFMPA)"). In the Configuration section you will find further logging settings that can be defined in the configuration file CibDocumentServer.properties.

For troubleshooting you can evaluate the corresponding log files. Errors that are caused in the Java Web application itself can be found in the log files of the application server. Errors in the socket server are logged by the logging setting "S" in the file socketserver.log. If errors occur during job processing, these are contained in the jobtrace.log log file (logging setting "J"). If errors occur in the CIB modules, these are output in the corresponding log files (separate log file for each module: Logging settings "MPF“).

If you need help evaluating these log files and the problem is not answered in the FAQs section, please contact the CIB support .

In section "Configuration" of this guide, you will find the settings for the Maintenance Feature that can be defined via the configuration file CibDocumentServer.properties.

The maintenance feature can be switched on or off via the web interface. This is done via the two links "Maintenance off" or "Maintenance on". (See also the screenshots at the end of this chapter)

If the maintenance feature is activated, an additional port is created in case an unknown or unexpected error message occurs during a job. The job is then executed again via this special port when logging is activated.

Further settings can be made by clicking on the "Maintenance on" link.

If a concrete error message is already known, it can be excluded via the form field "Known error codes". This means that for the specified error messages the requests will not be executed again via the Maintenance Port.

Here it is also possible to enter a list of known error messages. For this purpose, please use ";" as separator (example: "404;437;454").

To avoid load situations, it is also possible to limit the number of requests that are executed via the Maintenance Port. This can be set for a specific time range. The form fields "Max of executions" and "Time range" can be used to specify the maximum number of jobs that can be executed per time period.

Only after filling in the form fields the Maintenance Feature is activated by clicking the "Configure" button.

For troubleshooting you can evaluate the corresponding log files.

If you need help in evaluating these log files and the sample is not answered in the FAQs section, please contact the CIB Support.

Screenshot: activate Maintenance Feature

Screenshot: Maintenance settings