CIB documentServer technical documentation (EN)

Overview

The CIB documentServer described in this document serves to optimize the use of the CIB office modules (CoMod) especially when used on servers (document and print services).

The required high flexibility for integration into the respective customer environment is achieved by the realisation as a modular system of components. With the standard package, a quick realisation - even of complex document requirements - is possible in the respective customer system. In addition, the customer can realize individual or application-specific subcomponents using the customizing options provided.

Calling and using the CIB documentServer liberates the programmers of the calling application from the details of the respective technical connection of the CIB docgen modules. Calling the document generation is done by a standardized job description.

This means that a textual job description in XML format is transferred via the corresponding technical interfaces (e.g. Java, Socket, MQSeries), in which the inputs, outputs, options and even data are specified formally.

Therefore the job description is independent of the technical environment and can be generated very flexibly.

The generated document is returned directly in the desired output format or also in XML format.

Layer model

The CIB documentServer offers calling options at various logical and technical levels.

The levels correspond to different communication layers, which provide additional functionalities (service) besides the transport of information. Each layer can be addressed from the layer above or below with the components of the CIB documentServer.

In addition, each layer also has open interfaces that can be directly addressed by a customer application. The user who calls the CIB documentServer decides which call layer and which additional functionality he wants to use.

Illustration of the layer model:

Here are the layers listed from inside to outside:

Components

You can also find the products used in the CIB documentServer on our product overview:

CIB docgen

The extensive range of CIB office modules contains the CIB docgen products as a basis, which are dialogue-free and therefore suitable for server use. See the product overview.

The basic functionality available with these modules includes:

CIB merge: Text data integration, conditional text modules, loops over detailed data, report generation, dynamic business graphics, etc.

CIB format/output: Format conversion, PDF generation, direct printing, form generation, dynamic barcodes, etc.

CIB pdf toolbox: Extract text data from PDF forms, merge PDF documents, insert text into PDF afterwards, etc.

CIB pdf formfields: Addition to CIB format/pdf to create corresponding input fields in the PDF output document for placeholders in the input document.

CIB mail: E-mail transmission via SMTP or MAPI

Please find an overview here:

https://www.cib.de/en/products/cib-office-module-comod/product-overview.html

Detailed descriptions of the individual products can be found in the corresponding technical guides.

CIB job

CIB job provides the individual functionality of CIB docgen in a uniform way and extends its call interfaces by a document-oriented, XML-based job processing:

A single XML-based interface,

Transfer of the data for text data integration in XML

No creation of intermediate files,

Script and batch processing

Custom extensions

If an order is given to CIB job (order manager), this component converts the XML job description into the corresponding calls of the executing modules (CIB docgen).

CIB documentServer

For server use of the CIB docgen modules including the job manager CIB job, the software package CIB documentServer supports a large number of different server environments:

Windows, Linux, HPUX, IBM AIX, Sun Solaris and further environments
Java, .net, Native,
http, Sockets, RMI
JEE,MQSeries, MTS/COM+, SOAP, OCI and further environments

Siehe hierzu auch den nachfolgenden Abschnitt Nutzungsvarianten.

The CIB documentServer software package offers solutions for the standard requirements

multiple access, parallel processing, queue
scalability, load balancing
platform independence
interfaces, network protocols and
offline usage.

The CIB documentServer standard package contains the conversion for JEE and is specified for all the platforms listed above.

See also usage variants in the following section.

CIB pdf formserver

The CIB formserver is an add-on to the CIB documentServer in the integration layer and is delivered with it.

If PDF forms are filled out by the user with Adobe Reader, the user cannot save the form together with the entered data with the Reader and is his input is not available to the form provider.

With the CIB formserver a PDF document is created that contains the data entered and is displayed to the user.

The data entered can be extracted from the completed form by the CIB documentServer. These are provided as CSV or xfdf.

Usage Options

The CIB documentServer combines the above-mentioned components into a software package and extends the order processing by practice-relevant, standardized technologies and protocols. This provides powerful document generation with queuing, load balancing, multi-user usage, etc. in numerous system environments.

The different demands on a server solution for document generation require the support of different operating systems (Windows, Linux, Unix), different programming environments (Java, .net, Native) and different protocols (http, Sockets, RMI) as well as technologies (JEE, MQSeries, MTS, SOAP).

Therefore, the CIB documentServer package contains modules and pre-built solutions to support as many of these usage options as possible with as little programming effort as possible.

For example, the CIB documentServer can be used "out of the box" without any changes when used in JEE servlet containers. A provided framework allows a comfortable programming of the interfaces.

Repetitive requirements such as queuing, scalability, stability and decoupling of subsystems are solved modularly, so that the provided functionality can be used flexibly in own applications.

Quick Start

Below you will find descriptions that will help you get started with the CIB documentServer. It is described how the CIB documentServer is installed on the server, what you have to take into account for the individual configuration and how the CIB documentServer can be called by the client.

If problems or questions should arise, please check the chapter FAQs first, to see if your questions are already answered there. If you cannot find a solution for your problem there or need support for environments not listed, please contact the CIB Support.

As described in the section Scope of Delivery, the CIB documentServer comes with two packages, the client package and the server package.

The server package contains the necessary files that you need for the installation on the server (see section Installation). This includes the application archive CibDocumentServer.war and the files CibDocumentServer.properties or CibDocumentServer-Forward.properties to make individual settings to the configuration of the CIB documentServer (see section Configuration).

The client package contains the templates (example/templates directory) that are required to execute the examples (see section Calling the Examples). The job files required for this are contained in the client package (subdirectory example/jobs). In the client package you will also find the CIB documentServer framework (subdirectory lib) to integrate the CIB documentServer comfortably in your own applications (see section Calling CIB documentServer).

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

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

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

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

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

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.

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.

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>

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

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.

Calling CIB Documentserver

In the following you will find descriptions of how you can comfortably integrate the CIB documentServer into JAVA from the client package. This section also contains instructions on how to call the CIB documentServer webservice in Visual basic .net, C# .net and with the JAX-WS framework.

CIB documentServer Framework/Java

The CIB documentServer framework enables a comfortable integration of the CIB documentServer in Java. Due to the similarity of the concepts of the two platforms as well as of Java and C#, the corresponding section remains short.

With the CIB documentServer framework, Java application developers can generate the job files, analyze the job result files, and retrieve the result documents.

Concept

The order processing is represented by the framework in several levels according to the layer model.

On this level (the lowest in Java), the communication to the native components takes place and process monitoring, locking, internal load balancing and queuing are implemented.

Job and job result files are considered and processed as byte[] and byte[][] respectively.

You can use these classes to achieve a close cooperation with the CIB documentServer if you want to extend the server layer or develop your own server layer.

In the application layer as well as in the supply of classes for the integration layer, classes are provided for the convenient creation and execution of job files.

At this level, an order is an object of type de.cib.docserv.job.Request and the order results file of type de.cib.docserv.job.Response. The result documents are made available as streams.

An order is passed to a class that implements the interface de.cib.docserv.DocumentServer, such as de.cib.docserv.UrlDocumentServerImpl, which completely encapsulates the communication with a CIB documentServer via the usage option http.

…
Response t_Response = new
UrlDocumentServerImpl(t_Hostname, t_Port).execute(t_Request);
if (!t_Response.hasErrors()) 
{
       JobResult t_JobResult = t_Response.getJobResult();
       StepResult t_StepResult = t_JobResult.getStepResult();
       String t_ContentType = t_StepResult.getMimeType();
       InputStream t_Document  = t_StepResult.getStepData(); 

Packages

The most important packages are listed below.

de.cib.docserv

Together with the subpackages, this package contains the classes required for the usage variants Java, JEE Servlet Container and JEE EJB Container.

Especially the interface classes that implement the interface de.cib.docserv.DocumentServer are listed here. Furthermore, the basic implementation of the CIB documentServer in the form of de.cib.docserv.ServerManager, de.cib.docserv.ServerQueue, as well as the exception and error classes.

de.cib.docserv.job

This package contains, among other things, the auxiliary classes de.cib.docserv.job.Request and de.cib.docserv.job.Response, which are important for you and which can be used to generate and analyze jobs. Additionally, use the class de.cib.xml.dom.Dom.Dom to add your XML with the user data to the job.

de.cib.xml.dom

The class de.cib.xml.dom.Dom, with which other classes of the framework receive XML data, should be emphasized. Therefore pack your XML with the user data into a de.cib.xml.dom.Dom.

Calling example from JAVA

The CIB documentServer framework enables the CIB documentServer to be integrated. In the first step, the order file is read in and the request for the CIB documentServer is created from it. In the next step the CIB documentServer is generated and configured to process the request. As a result the CIB documentServer delivers a response which is processed in the last step. The following code snippet shows the integration of a CIB documentServer into a Java application.

//create request for the CIB documentServer
Request request = new RequestXmlParser().parseRequest(new File("Job.xml"));
//create documentServer with following parameters: hostname: remote computer, where 
the CIB documentServer servlet is configured; port: port number of servlet.

DocumentServer documentServer = new UrlDocumentServerImpl(“localhost“, 8080);
//get the response from the CIB documentserver
Response response = null;
if (request != null) {
	response = documentServer.execute(request);
	//check if all jobs were successful
	if (response.hasErrors() || response == null {
		System.err.println("Response: "+response);
		System.out.println("Bytes written: "+0);
		response.throwException(); // optional
	} else {
		//Save the JobResult in a client file
		InputStream input = null;
		OutputStream output = null;
		int bytesWritten = 0;
		Set enumStepResults = response.getJobResult().getStepNames();
		if (enumStepResults != null) {
			Iterator iterator = enumStepResults.iterator();
			while (iterator.hasNext()) {
				String name = (String) iterator.next();
				try {
					input = response.getJobResult().
						getStepResult(name).getStepData();
					if (input.available() <= 0)
						continue;
					// only one result is available and the 
					// mimetype is application/pdf
					output = new FileOutputStream(new File(request
						.getJob().getName() + "-" + name +
						".pdf"));
					byte[] buffer = new byte[0xffff];
					int bytesRead = 0;
					while ((bytesRead = input.read(buffer)) >= 0) {
						output.write(buffer, 0, bytesRead);
						bytesWritten += bytesRead;
					}
					if (bytesWritten <= 0) {
						byte[] text = "Empty Result".getBytes();
						output.write(text, 0, text.length);
						bytesWritten += text.length;
					}
					input.close();
					output.close();
				} catch (IOException e) {
					e.printStackTrace();
				}
			}
		}
		System.out.println("Bytes written: " + bytesWritten);
	}
} 

Further examples can be found in the client package under example/de/cib/docserv/samples.

Buiding a job from JAVA

It is also possible to create an XML job using the CIB documentServer framework.

//build new Request
Request request = new Request();
Job job = new Job("testJob");
job.setProperty("OutputMode", "XML");
Step pdfJoinStep = new Step((new CommandFactory()).createCommand(CommandFactory.COMMAND_PDFJOIN), "PdfJoinStep");
//Set the propertys for the request
pdfJoinStep.setProperty("OutputFilename", "ZUGFeRD-invoice.xml");
pdfJoinStep.setProperty("ZUGFeRDDoCheck", "1");
pdfJoinStep.setProperty("OutputFormat", "FormatInfo");
pdfJoinStep.setProperty("FilterInfo", "EmbeddedFilesInfo");
pdfJoinStep.setProperty("EmbeddedFilesInfoFilter", "EmbeddedFiles");
//Set a property with setPropertyMode and “out” value in order to obtain its value in the //response
pdfJoinStep.setPropertyMode("EmbeddedFilesInfo", "out");
pdfJoinStep.setPropertyMode("ModuleName", "out");
//Use setPropertyMode with value “inout”in order to hint, that the value of an input //property will also be obtained in the response. 
pdfJoinStep.setProperty("InputFilename", “Test.pdf”);
pdfJoinStep.setPropertyMode("InputFilename", "inout");
job.addStep(pdfJoinStep);
request.addJob(job);
 

In this example, an order is created with a "PdfJoin" step. A series of properties is declared programmatically for the corresponding order.

It is also possible to retrieve the value of desired properties in the result-response by using the method "setPropertyMode" when setting up the request (from version 1.10.6).

The property values can be retrieved as follows:

JobResult t_JobResult = response.getJobResult();
StepResult t_StepResult = t_JobResult.getStepResult("PdfJoinStep ");
String ModuleName = t_StepResult.getProperty("ModuleName");
String embeddedFilesInfo = t_StepResult.getProperty("EmbeddedFilesInfo");
String inputFilename = t_StepResult.getProperty("InputFilename"); 

CIB documentServer Framework/.net

Similar to the framework/Java, the framework/.net allows the integration of the order functionality in customer-specific .net applications.

Calling CIB documentServer web service

In this section you will find descriptions of how to call the CIB document web service in different environments. VB.net, C#.net and the JAX-WS client framework are described.

VB.net

Design a method that calls the CIB documentServer web service.

Adding the web service

Register the web service by adding a web resource to your project. Complete the URL at the end with ?wsdl. The web service "CibDocumentServer" should be displayed with a method "generate". Enter the package name from de.cib.docserv.web as "web reference name”.

Generate classes by selecting "Update". To perform this step successfully, you need internet access to www.cib.de.

Calling the web service

Now create instances of the service and request classes as follows:

Dim service As New de.cib.docserv.web.CibDocumentServer
Dim request As New de.cib.docserv.web.Request

Add the necessary steps to the request. (See Code examples in Appendix)

Dim mergeStep As New de.cib.docserv.web.StepType
Dim mergeProps(4) As de.cib.docserv.web.PropertyType
mergeStep.name = "step1"
mergeStep.command = "merge"

mergeStep.properties = New de.cib.docserv.web.PropertiesType()
mergeStep.properties.property = mergeProps
mergeStep.properties.property(0) = New de.cib.docserv.web.PropertyType()
mergeStep.properties.property(0).name = "-i"
mergeStep.properties.property(0).Value = "Test.rtf"

Add your user data to the request. The structure is arbitrary, but needs to match the input template (-i) of the merge step and the option -d.

Dim XmlString As String = "Otto..."
Dim xmldata As New System.Xml.XmlDocument
xmldata.LoadXml(XmlString)

request.Data = xmldata.DocumentElement

Now call the web service and prepare it to receive the result:

Dim response As de.cib.docserv.web.Response
response = service.generate(request)

Processing results

If server errors occur, the above call throws an exception.

If errors occur during document generation, no exceptions are thrown. Instead, you receive a response object. You should retrieve the error code from the job result to decide whether an execution error has occurred. An example of an error message is: "CIB merge error 10: Unknown variable in template"

Dim jobResults As de.cib.docserv.web.JobResultsType
jobResults = CType(response.Comod.Items(0), de.cib.docserv.web.JobResultsType)
If (jobResults.jobresult(0).jobresultcode = 0) Then

            ' Success
        Dim stepData As de.cib.docserv.web.StepDataType
        stepData = jobResults.jobresult(0).stepresults(1).stepdata

                ...     
Else
        ' A step failed
        Debug.Print("Error " & jobResults.jobresult(0).jobresultcode & ": " _

                           & jobResults.jobresult(0).jobresulttext)
        Debug.Print("Failed step(s): " _

                               & jobResults.jobresult(0).failed.name)
        ...
End If

If successful, you have to retrieve the generated documents from the response. The result is base64-encoded. You must decode it accordingly.

' Extract base64 encoded pdf from stepdata
saveDocument(stepData.Value)

Please find the complete VB.net Sourcecode attached to this document. 

The corresponding examples of SOAP requests and responses can also be found attached.

C# .net

If the CIB documentServer is to be called from C#.net as a web service, the procedure is the same as under VB.net. The calls only differ in their syntax. An example code can be found attached.  Anhang.

When calling from C#.net using an HTTP connection, there may be communication problems in connection with an application server. In this case it may help to disable the "Expect100Continue" property of the client-server connection (the default value is true).

Example:

webRequest.ServicePoint.Expect100Continue = false;

CIB documentServer Framework/JAX-WS

The JAX-WS (Java API for XML Web Services) client provides an easy way to call the CIB documentServer webservice. The functionality is integrated in the CibDocumentServer.jar To use JAX-WS at least a JRE 5.0 is required.

Calling CIB job locally (offline)

This section still needs to be revised with regard to JobDocumentServerImpl.

The modular structure of the CIB documentServer allows its installation on the client even without a local server environment like JEE Servlet Container, MTS or .net.

The application passes a request (XML) to the existing components of the CIB documentServer, which generates a corresponding document.

The transfer takes place via call interfaces from Java code or from native code (interfaces Java Call, Native Call). No JEE application server is required for this.

If several threads send requests to a server manager but no web context is available, suitable classes are available to take over the administration of the server manager (de.cib.docserv.LocalDocumentServerImpl).

In normal Java applications that also want to use the CIB documentServer framework instead of JNI, it is not necessary to start multiple socket servers in parallel.

Instead, a single external process is sufficient, which is started automatically by the framework. In addition to the order classes (de.cib.job.Request, de.cib.job.Response), suitable administration classes are also available for this situation (de.cib.docserv.SingleDocumentServerImpl).

Calling the CIB documentServer asynchronous

To execute jobs asynchronously with the CIB documentServer, use the asyncExecute method of the CIB documentServer framework.

When using other CIB documentServer commands from other languages, please set the header field async-action:

Start asyncronous call: async-action: new

Get the result of the asynchronous call with the ID 12345: async-action: 12345

For the XML content exchanged in asynchronous calls, please refer to the technical guide for CIB job in the sections additional settings for asynchronously executed requests and contents of a request result for an asynchronously executed request.

Changing version

The following changes must be taken into account when changing the version of the CIB documentServer. They may affect your client code or individual installation steps.

Migration from CIB documentServer 1.4 to 1.5

Now requires JDK5 on the server. Tomcat 5.0 is no longer supported.

The CibDocumentServer.jar used in client applications is replaced by the new .jar files cibdocserv-common-1.5.x.jar, cibdocserv-client-1.5.x.jar.

HttpDocumentServerImpl is deprecated. Please use UrlDocumentServerImpl instead.

The default configuration setting of en.cib.docserv.ServerProcessFactoryClass has been changed to en.cib.docserv.socket.UrlSocketServerProcessFactory. Please adjust your old configuration files.

Some utility packages have been renamed from de.cib.paketname to de.cib.docserv.packetname.

DocumentServerException public member was replaced by public getter/setter methods.

AIX4 and Sparc Solaris 8 are no longer supported.

Migration from CIB documentServer 1.5 to 1.6

Requires JDK8 now.

The CibDocumentServer.jar used in client applications is replaced by the new .jar files cibdocserv-common-1.6.x.jar, cibdocserv-client-1.6.x.jar.

Support for Apache Tomcat 8

Migration from CIB documentServer 1.6 to 1.7

The CibDocumentServer.jar used in client applications is replaced by the new .jar files cibdocserv-common-1.7.x.jar, cibdocserv-client-1.7.x.jar.

New functionality for optical character recognition by CIB ocr

Migration from CIB documentServer 1.7 to 1.8

Die the CibDocumentServer.jar used in client applications is replaced by the new .jar files cibdocserv-common-1.8.x.jar, cibdocserv-client-1.8.x.jar.

CIB servermanager is no longer supported

Update: CIB ocr funcionality

Migration from CIB documentServer 1.8 to 1.9

Die the CibDocumentServer.jar used in client applications is replaced by the new .jar files cibdocserv-common-1.9.x.jar, cibdocserv-client-1.9.x.jar.

Compatibility with CIB LibreOffice corresponding released versions for the conversion of LibreOffice compatible document formats to PDFNew functionality for the conversion and processing of image formats via CIB image toolbox

Migration from CIB documentServer 1.9 to 1.10

The CibDocumentServer.jar used in client applications is replaced by the new .jar files cibdocserv-common-1.10.x.jar, cibdocserv-client-1.10.x.jar.

Migration from CIB documentServer 1.10 to 1.11

The CibDocumentServer.jar used in client applications is replaced by the new .jar files cibdocserv-common-1.11.x.jar, cibdocserv-client-1.11.x.jar.

Migration from CIB documentServer 1.11 to 1.12

The CibDocumentServer.jar used in client applications is replaced by the new .jar files cibdocserv-common-1.12.x.jar, cibdocserv-client-1.12.x.jar.

Migration from CIB documentServer 1.12 to 1.13

The CibDocumentServer.jar used in client applications is replaced by the new .jar files cibdocserv-common-1.12.x.jar, cibdocserv-client-1.13.x.jar.

Migration from CIB documentServer 1.13 to 1.14

The CibDocumentServer.jar used in client applications is replaced by the new .jar files cibdocserv-common-1.13.x.jar, cibdocserv-client-1.14.x.jar.

Special command "htmltopdf" is now supported to convert Html files to Pdf. The library wkhtmltopdf is used for this.

Important: Linux requires at least gclib 2.10.

Migration from CIB documentServer 1.14 to 1.15

The CibDocumentServer.jar used in client applications is replaced by the new .jar files cibdocserv-common-1.14.x.jar, cibdocserv-client-1.15.x.jar.

Migration from CIB documentServer 1.15 to 1.16

The CibDocumentServer.jar used in client applications is replaced by the new .jar files cibdocserv-common-1.15.x.jar, cibdocserv-client-1.16.x.jar.

Instructions

Instructions are already available for many well-known application scenarios. These can be found in the separate technical guide CIB job document. There you will find general information frequently required, for example, how to store necessary license keys or where to store forms and text modules. The CIB job guide also describes a complete call with the framework: Create job file, call DocumentServer, analyze job result file, read out result documents. In addition, you will also find help there for designing job files.

Appendix

Überblick CIB Module
Beispielaufruf SOAP Webservice mit VB.net
Beispielaufruf SOAP Webservice mit C#
Beispiel für einen XML request
Beispiel für eine XML response
Fehlercodes der Socketserver
Fehlercodes des CIB documentserver
Fehlercodes des Servermanagers
WSDL Webservice Description

Overview CIB Module

Example call SOAP Web service with VB.net

Example call Web service

Public
Class Form1
 
       Private Sub Button1_Click(ByVal sender As System.Object, ByVal e As System.EventArgs)
Handles Button1.Click
             Dim service As New de.cib.docserv.web.CibDocumentServer
             Dim request As New de.cib.docserv.web.Request
 
             Dim comodtype As New de.cib.docserv.web.ComodType
             Dim testjob As New de.cib.docserv.web.JobType
             Dim testjobs As New de.cib.docserv.web.JobsType
             Dim formatStep As New de.cib.docserv.web.StepType
             Dim formatProps(1) As de.cib.docserv.web.PropertyType
             Dim stepArray(2) As de.cib.docserv.web.StepType
             Dim comodArray(1) As Object
             Dim jobsArray(1) As de.cib.docserv.web.JobType
 
             Dim mergeStep As New de.cib.docserv.web.StepType
             Dim mergeProps(4) As de.cib.docserv.web.PropertyType
             mergeStep.name = "step1"
             mergeStep.command = "merge"
 
             mergeStep.properties = New de.cib.docserv.web.PropertiesType()
             mergeStep.properties.property = mergeProps
             mergeStep.properties.property(0) = New de.cib.docserv.web.PropertyType()
             mergeStep.properties.property(0).name = "-i"
             mergeStep.properties.property(0).Value = "Test.rtf"
 
             mergeStep.properties.property(1) = New de.cib.docserv.web.PropertyType()
             mergeStep.properties.property(1).name = "-h"
             mergeStep.properties.property(1).Value = "XML:$(inline)"
 
             mergeStep.properties.property(2) = New de.cib.docserv.web.PropertyType()
              mergeStep.properties.property(2).name = "-d"
             mergeStep.properties.property(2).Value = "//Data/Person"
 
             mergeStep.properties.property(3) = New de.cib.docserv.web.PropertyType()
             mergeStep.properties.property(3).name = "-l"
             mergeStep.properties.property(3).Value = "!merge.log"
 
             mergeStep.trace = "merge.log"
 
             formatStep.name = "step2"
             formatStep.command = "format"
 
             formatStep.properties = New de.cib.docserv.web.PropertiesType()
             formatStep.properties.property = formatProps
             formatStep.properties.property(0) = New de.cib.docserv.web.PropertyType()
             formatStep.properties.property(0).name = "OutputFormat"
             formatStep.properties.property(0).Value = "FormatPdf"
 
             testjob.steps = stepArray
             testjob.steps(0) = mergeStep
             testjob.steps(1) = formatStep
 
             comodtype.Items = comodArray
             testjobs.job = jobsArray
             testjobs.job(0) = testjob
             comodtype.Items(0) = testjobs
             comodtype.producer = "VB.net"
 
             request.Comod = comodtype
 
             Dim XmlString As String = "<Person><Vorname>Otto</Vorname><Name>Krause</Name><Strasse> 
             Musterstrasse</Strasse><Nummer>1</Nummer><PLZ>12345</PLZ><Ort>Musterstadt</Ort></Person>"
             Dim xmldata As New System.Xml.XmlDocument
             xmldata.LoadXml(XmlString)
 
             request.Data = xmldata.DocumentElement
 
             Dim response As de.cib.docserv.web.Response
 
             response = service.generate(request)
 
             Dim jobResults As de.cib.docserv.web.JobResultsType
             jobResults = CType(response.Comod.Items(0), de.cib.docserv.web.JobResultsType)
             If (jobResults.jobresult(0).jobresultcode = 0) Then
                    ' Success
                    Dim stepData As de.cib.docserv.web.StepDataType
                    stepData = jobResults.jobresult(0).stepresults(1).stepdata
 
                    Debug.Print(stepData.mimetype)
                    Debug.Print(stepData.encoding)
 
                    ' TODO: Extract base64 encoded pdf from here: stepData.Value
             Else
                    ' A step failed
                    Debug.Print("Error " & jobResults.jobresult(0).jobresultcode & ": " _
                           & jobResults.jobresult(0).jobresulttext)
                    Debug.Print("Failed step(s): " _
                           & jobResults.jobresult(0).failed(0).name)
 
                    ' TODO loop step results to find error code of failed step.
                    ' TODO in case of merge extract content of trace property
             End If
 
       End Sub
End
Class

Beispielaufruf SOAP Webservice mit C#

Example call Web service

using Webservice2.de.cib.docserv.web;
 
…
 
private
void button1_Click(object sender, EventArgs e)
{
       CibDocumentServer service = new CibDocumentServer();
       Request request = new Request();
 
       StepType mergeStep = new StepType();
       StepType formatStep = new StepType();
       ComodType comodtype = new ComodType();
       JobsType testjobs = new JobsType();
       JobType testjob = new JobType();
       PropertyType[] formatProps = new PropertyType[1];
       StepType[] stepArray = new StepType[2];
       Object[] comodArray = new Object[1];
       JobType[] jobsArray = new JobType[1];
       PropertyType[] mergeProps = new PropertyType[4];
 
       mergeStep.name = "step1";
       mergeStep.command = "merge";
 
       mergeStep.properties = new PropertiesType();
       mergeStep.properties.property = mergeProps;
       mergeStep.properties.property[0] = new PropertyType();
       mergeStep.properties.property[0].name = "-i";
       mergeStep.properties.property[0].Value = "Test.rtf";
 
       mergeStep.properties.property[1] = new PropertyType();
       mergeStep.properties.property[1].name = "-h";
       mergeStep.properties.property[1].Value = "XML:$(inline)";
 
       mergeStep.properties.property[2] = new PropertyType();
       mergeStep.properties.property[2].name = "-d";
       mergeStep.properties.property[2].Value = "//Data/Person";
 
       mergeStep.properties.property[3] = new PropertyType();
       mergeStep.properties.property[3].name = "-l";
       mergeStep.properties.property[3].Value = "!merge.log";
 
       mergeStep.trace = "merge.log";
 
       formatStep.name = "step2";
       formatStep.command = "format";
 
       formatStep.properties = new PropertiesType();
       formatStep.properties.property = formatProps;
       formatStep.properties.property[0] = new PropertyType();
       formatStep.properties.property[0].name = "OutputFormat";
       formatStep.properties.property[0].Value = "FormatPdf";
 
       testjob.steps = stepArray;
       testjob.steps[0] = mergeStep;
       testjob.steps[1] = formatStep;
 
       comodtype.Items = comodArray;
       testjobs.job = jobsArray;
       testjobs.job[0] = testjob;
       comodtype.Items[0] = testjobs;
       comodtype.producer = "C#.net";
 
       request.Comod = comodtype;
 
       String xmlString =
"<Person><Vorname>Otto</Vorname><Name>Krause</Name><Strasse>Musterstrasse</Strasse>
<Nummer>1</Nummer><PLZ>12345</PLZ><Ort>Musterstadt</Ort></Person>";
       System.Xml.XmlDocument xmldata = new System.Xml.XmlDocument();
       xmldata.LoadXml(xmlString);
 
       request.Data = xmldata.DocumentElement;
 
       Response response = service.generate(request);
 
       JobResultsType jobResults = (JobResultsType)response.Comod.Items[0];
       if (jobResults.jobresult[0].jobresultcode == 0) {
             // Success
             StepDataType stepData = jobResults.jobresult[0].stepresults[1].stepdata;
 
             System.Console.Out.WriteLine(stepData.mimetype);
             System.Console.Out.WriteLine(stepData.encoding);
 
             // TODO: Extract base64 encoded pdf from here: stepData.Value
       }
       else {
             // A step failed
             System.Console.Out.WriteLine("Error " + jobResults.jobresult[0].jobresultcode + ": " 
             + jobResults.jobresult[0].jobresulttext);
             System.Console.Out.WriteLine("Failed step(s): " 
             + jobResults.jobresult[0].failed[0].name);
 
             // TODO loop step results to find error code of failed step.
             // TODO in case of merge extract content of trace property
       }
}

Example for an XML request

<?xml
version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:xsd="http://www.w3.org/2001/XMLSchema">
       <soap:Body>
             <Generate xmlns="http://www.cib.de/schemas/soap/job/1.1">
                    <Comod xmlns="">
                           <producer>VB.net</producer>
                           <jobs>
                                  <job>
                                        <steps>
                                               <step name="step1" command="merge">
                                                      <properties>
                                                             <property name="-i">
                                                                   Test.rtf
                                                             </property>
                                                            <property name="-h">
                                                                   XML:$(inline)
                                                             </property>
                                                             <property name="-d">
                                                                   //Data/Person
                                                             </property>
                                                             <property name="-l">
                                                                   !merge.log
                                                             </property>
                                                      </properties>
                                                      <trace>merge.log</trace>
                                               </step>
                                               <step name="step2" command="format">
                                                      <properties>
                                                             <property name="OutputFormat">
                                                                   FormatPdf
                                                             </property>
                                                      </properties>
                                               </step>
                                        </steps>
                                  </job>
                           </jobs>
                    </Comod>
                    <Data xmlns="">
                           <Person>
                                  <Vorname>Otto</Vorname>
                                  <Name>Krause</Name>
                                  <Strasse>Musterstrasse</Strasse>
                                  <Nummer>1</Nummer>
                                  <PLZ>12345</PLZ>
                                  <Ort>Musterstadt</Ort>
                           </Person>
                    </Data>
             </Generate>
       </soap:Body>
</soap:Envelope>

Example for an XML response

<?xml
version="1.0" encoding="UTF-8" standalone="no" ?>
<soap:Envelope
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="
http://www.cib.de/schemas/job/1.1
http://www.cib.de/schemas/job/1.1/cibjob.xsd
http://schemas.xmlsoap.org/soap/envelope/
http://schemas.xmlsoap.org/soap/envelope/
http://www.cib.de/schemas/soap/job/1.1
http://www.cib.de/schemas/soap/job/1.1/cibjobsoap.xsd
">
 
       <soap:Body>
             <cibjobsoap:GenerateResult
                    xmlns:cibjobsoap="http://www.cib.de/schemas/soap/job/1.1">
                    <Comod xmlns="">
                           <!--CIB job Ausgabe 07.11.2007 10:01:15 -->
                           <version>1.1</version>
                           <producer>CIB job 1.3.12b</producer>
                           <job-results>
                                  <job-result name="">
                                        <job-result-code>0</job-result-code>
                                        <job-result-text>Erfolgreich</job-result-text>
                                        <job-timing>0:00:00,156</job-timing>
                                        <!--Liste aller Ergebnisse-->
                                        <step-results>
                                               <!-- step1 -->
                                               <step-result name="step1">
                                                      <step-result-code>0</step-result-code>
                                                      <step-result-text>
                                                             Erfolgreich
                                                      </step-result-text>
                                                      <step-timing>0:00:00,015</step-timing>
                                               </step-result>
                                               <!-- step2 -->
                                               <step-result name="step2">
                                                      <step-result-code>0</step-result-code>
                                                      <step-result-text>
                                                             Erfolgreich
                                                      </step-result-text>
                                                      <step-timing>0:00:00,141</step-timing>
                                                      <step-data encoding="base64"
                                                             mimetype="application/pdf">
JVBERi0xLjQNCiXi48/TCjYgMCBvYmoKPDwKL0xlbmd0aCA3IDAgUgovRmls
dGVyIC9GbGF0ZURlY29kZQo+PgpzdHJlYW0KeJydjb0KwjAQgPc8xY26nLkk
bdNRQR1EBMkLVJsKDgpJiuDTmx+qs70b7rif7yOgmO7GKDfnPdsYxiFlHK52
HEggBzMwjjwGmCujVN7xyrh49mINR11BU7WpmB4W64u3j966JZg725qE/Isk
BYpCOoXwhIwRCqWC9JoXB9eN3s4VkEZVBMfRB+t8cJ33tphqja3+mWiuhCus
i4SEjLrMkTJxv/BJ3/Vh0nwAR/BbawplbmRzdHJlYW0KZW5kb2JqCjcgMCBv
YmoKMTc1DQplbmRvYmoKNSAwIG9iago8PAovVHlwZSAvUGFnZQovUGFyZW50
IDMgMCBSCi9NZWRpYUJveCBbMCAwIDU5NSA4NDJdCi9SZXNvdXJjZXMgOSAw
IFIKL0NvbnRlbnRzIFs2IDAgUiBdCj4+CmVuZG9iago0IDAgb2JqCjw8Ci9U
eXBlIC9DYXRhbG9nCi9QYWdlcyAzIDAgUgo+PgplbmRvYmoKMTAgMCBvYmoK
PDwNCi9Qcm9kdWNlciAoQ0lCIGZvcm1hdC9wZGYgNS4zLjIwMyAtIHd3dy5j
aWIuZGUpCi9BdXRob3IgKEhvbGdlcikKL1RpdGxlIChBYnNlbmRlcikKL0Ny
ZWF0aW9uRGF0ZSAoRDoyMDA3MTEwNzEwMDExNSswMScwMCcpCi9Nb2REYXRl
IChEOjIwMDcxMTA3MTAwMTE1KzAxJzAwJykKPj4KZW5kb2JqCjEgMCBvYmoK
PDwgL0YwIDggMCBSID4+CmVuZG9iago5IDAgb2JqCjw8L0ZvbnQgMSAwIFIg
IC9Qcm9jU2V0IFsvUERGL1RleHRdID4+CmVuZG9iagozIDAgb2JqCjw8Ci9U
eXBlL1BhZ2VzCi9Db3VudCAxCi9LaWRzIFsgNSAwIFIgXQo+PgplbmRvYmoK
OCAwIG9iago8PAovVHlwZS9Gb250Ci9TdWJ0eXBlL1RydWVUeXBlCi9OYW1l
L0YwCi9CYXNlRm9udC9UaW1lc05ld1JvbWFuUFNNVAovRW5jb2RpbmcvV2lu
QW5zaUVuY29kaW5nCi9GaXJzdENoYXIgMzIKL0xhc3RDaGFyIDExNwovV2lk
dGhzIFsgMjUwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgNTAw
IDUwMCA1MDAgNTAwIDUwMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgNzIyIDAg
MCAwIDAgMCAwIDAgMCAwIDcyMiAwIDg4OSAwIDcyMiAwIDAgMCAwIDAgMCAw
IDAgMCAwIDAgMCAwIDAgMCAwIDAgNDQ0IDUwMCAwIDUwMCA0NDQgMCAwIDAg
MCAwIDAgMCAwIDUwMCA1MDAgMCAwIDMzMyAzODkgMjc4IDUwMCBdCi9Gb250
RGVzY3JpcHRvciAxMSAwIFIKPj4KZW5kb2JqCjExIDAgb2JqCjw8Ci9UeXBl
L0ZvbnREZXNjcmlwdG9yCi9Gb250TmFtZS9UaW1lc05ld1JvbWFuUFNNVAov
RmxhZ3MgMzQvRm9udEJCb3ggWy03NiAtMjE2IDEwMDkgOTMzXQovQXNjZW50
IDg5MS9EZXNjZW50IC0yMTYKL0l0YWxpY0FuZ2xlIDAvQ2FwSGVpZ2h0IDEy
MDAvU3RlbVYgODAKPj4KZW5kb2JqCnhyZWYNCjAgMTINCjAwMDAwMDAwMDIg
NjU1MzUgZg0KMDAwMDAwMDYyMiAwMDAwMCBuDQowMDAwMDAwMDAwIDAwMDAw
IGYNCjAwMDAwMDA3MDcgMDAwMDAgbg0KMDAwMDAwMDM5MiAwMDAwMCBuDQow
MDAwMDAwMjg1IDAwMDAwIG4NCjAwMDAwMDAwMTYgMDAwMDAgbg0KMDAwMDAw
MDI2NSAwMDAwMCBuDQowMDAwMDAwNzY1IDAwMDAwIG4NCjAwMDAwMDA2NTMg
MDAwMDAgbg0KMDAwMDAwMDQ0MSAwMDAwMCBuDQowMDAwMDAxMTUzIDAwMDAw
IG4NCnRyYWlsZXIKPDwNCi9TaXplIDEyCi9Sb290IDQgMCBSCi9JbmZvIDEw
IDAgUgovSURbPGY4ZDVmNjA1YjEzNjBiMGRmZmVjZjg2YWU1ZGVhMmFhPjxm
OGQ1ZjYwNWIxMzYwYjBkZmZlY2Y4NmFlNWRlYTJhYT5dCj4+CnN0YXJ0eHJl
ZgoxMzI3CiUlRU9GCg==
                                                      </step-data>
                                               </step-result>
                                        </step-results>
                                  </job-result>
                           </job-results>
                    </Comod>
             </cibjobsoap:GenerateResult>
       </soap:Body>
 
</soap:Envelope>

Error codes of the Socketserver

The specified return values can be read in the logs of the application server (processor native CIB socketserver process at localhost:5000x terminated with exit code nnn) as well as in the socketserver.log if necessary.

The following list gives an overview of possible error returns by the socket server.

The error numbers have the following meaning:

Error codes of the CIB documentserver

The following error codes can occur via the call interface of the CIB documentServer. The specified error codes are contained in the XML response of the CIB documentServer and originate either from CIB job or from the CIB documentServer Java framework.

Error codes of the Servermanager

The specified return values are triggered by the native server manager if it is used (not recommended).

WSDL Webservice Description

This section contains the WSDL file for the SOAP interface.

The current version can be obtained at any time from http://www.cib.de/schemas/soap/job/1.1/Cib­Document­Server.wsdl.

<?xml version="1.0" encoding="UTF-8"?>
<!-- 
        CIB job/SOAP XML Schema/WSDL 1.1 for CIB job from Version 1.4.x. onwards
        
        (c) CIB software GmbH 2005-2006
        $Revision: 2 $
        
        INTRODUCTION:
        This schema formally describes the XML structure of the SOAP Envelope, into which
        CIB job job files and job result files can be embedded.
        
        EXAMPLE:
        A SOAP message to execute the "generate" operation contains, in addition to the
        Envelope a "Generate" element that contains the nodes "Comod" and "Data".
        The namespaces are left out.        <envelope>
               <header/>
               <body>
                       <Generate>
                              <Comod>
                                      <jobs>...</jobs>
                              </Comod>
                               <Data>...</Data>
                       </Generate>
               </body>
        </envelope>
        
        And the response:
        
        <envelope>
               <header/>
               <body>
                       <GenerateResult>
                              <Comod>
                                      <job-results>...</job-results>
                              </Comod>
                       </GenerateResult>
               </body>
        </envelope>
        
        $Header: /CIB documentserver/jobs/soap/cibjob.wsdl 2    7.08.06 12:15 Georg $
-->
 
<wsdl:definitions name="CibDocumentServer"
 targetNamespace="http://www.cib.de/schemas/soap/job/1.1"
 xmlns:soapjob="http://www.cib.de/schemas/soap/job/1.1"
 xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
 xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema">
 
        <!--
Define types for the messages -->
        <wsdl:types>
               <xsd:scheme
                targetNamespace="http://www.cib.de/schemas/soap/job/1.1"
                xmlns:pref="http://www.cib.de/schemas/job/1.1">
                       
                       <!-- Import the cibjob syntax -->
                       <xsd:import namespace="http://www.cib.de/schemas/job/1.1"
                        schemaLocation="http://www.cib.de/schemas/job/1.1/cibjob.xsd">
                       </xsd:import>
                       
                       <!-- Define the structure of the messages -->
                       <xsd:complexType name="Request">
                              <xsd:sequence>
                                      <xsd:element name="Comod" type="pref:ComodType">
                                      </xsd:element>
          <xsd:element name="Data" type="pref:UserData"></xsd:element>
                               </xsd:sequence>
                       </xsd:complexType>
                       <xsd:complexType name="Response">
                              <xsd:sequence>
                                      <xsd:element name="Comod" type="pref:ComodType">
                                      </xsd:element>
                               </xsd:sequence>
                       </xsd:complexType>
                       
                       <!-- These two element names appear in the body of Request and 
                       Response, and each has a comod element. -->
                       <xsd:element name="Generate" type="soapjob:Request" />
                       <xsd:element name="GenerateResult" type="soapjob:Response" />
 
               </xsd:schema>
        </wsdl:types>
 
        <!-- Declare messages of the operation described below. -->
        <wsdl:message name="generateMessage">
               <wsdl:part name="parameter"
                       element="soapjob:Generate" />
        </wsdl:message>
        <wsdl:message name="generateResultMessage">
               <wsdl:part name="parameter"
                       element="soapjob:GenerateResult" />
        </wsdl:message>
 
        <!-- Declare concrete operation -->
        <wsdl:portType name="cibjobInterface">
               <wsdl:operation name="generate">
                       <wsdl:input message="soapjob:generateMessage" />
                       <wsdl:output message="soapjob:generateResultMessage" />
               </wsdl:operation>
        </wsdl:portType>
 
        <!-- Declare concrete operation. Because of use="literal", the SOAP
        Messages the elements assigned to the messages (Generate and ~Result) expected. -->
        <wsdl:binding name="cibjobBinding" type="soapjob:cibjobInterface">
               <soap:binding style="document"
                transport="http://schemas.xmlsoap.org/soap/http" />
               <wsdl:operation name="generate">
                       <soap:operation
                        soapAction="http://www.cib.de/soap/job/generate" />
                       <wsdl:input>
                              <soap:body use="literal" />
                       </wsdl:input>
                       <wsdl:output>
                              <soap:body use="literal" />
                       </wsdl:output>
               </wsdl:operation>
        </wsdl:binding>
        
        <!-- Declare the service to the concrete operations -->
        <wsdl:service name="CibDocumentServer">
               <wsdl:port binding="soapjob:cibjobBinding"
                       name="cibjobService">
                       <!-- The implementing address -->
                       <soap:address
location="http://desiderata:8080/CibDocumentServer/soap/Generate" />
               </wsdl:port>
        </wsdl:service>

Delivery Scope

The CIB documentServer comes with a client and a server package consisting of the following components:

The client package:

The client package contains, among other things, the CIB documentServer framework, which enables the CIB documentServer for Java to be integrated. You will find the Javadoc of the API as well as code examples and sample jobs with templates.

Server package:

To install the CIB documentServer on a server, the application archive CibDocumentServer.war included in this package is required. The supplied configuration files facilitate the configuration.