CIB documentServer technischer Leitfaden (DE)

Überblick

Der in diesem Dokument beschriebene CIB documentServer dient zur Optimierung des Einsatzes der CIB office Module (CoMod) insbesondere beim Einsatz auf Servern (Dokument und Druckdienste).

Die geforderte hohe Flexibilität zur Integration in das jeweilige Kundenumfeld wird durch die Realisierung als Baukastensystem aus Komponenten erreicht. Mit dem Standardpaket ist eine schnelle Realisierung - auch komplexer Dokumentanforderungen - im jeweiligen Kundensystem möglich. Darüber hinaus kann der Kunde über die gebotenen Customizing-Möglichkeiten individuelle bzw. anwendungsspezifische Teilkomponenten realisieren.

Der Aufruf und die Nutzung des CIB documentServers befreit die Programmierer der aufrufenden Anwendung von den Details der jeweiligen technischen Anbindung der CIB docgen Module. Der Aufruf der Dokumentgenerierung erfolgt mittels einer standardisierten Auftragsbeschreibung.

Das heißt, über die entsprechenden technischen Schnittstellen (z. B. Java, Socket, MQSeries) wird eine textuelle Auftragsbeschreibung im XML-Format übergeben, in der die Eingabe, die Ausgaben, Optionen und sogar Daten formal angegeben sind.

Die Auftragsbeschreibung ist dadurch unabhängig von der technischen Umgebung und kann sehr flexibel erzeugt werden.

Die Rückgabe des erzeugten Dokuments erfolgt direkt im gewünschten Zielformat oder ebenfalls im XML-Format.

Schichtenmodell

Der CIB documentServer bietet Aufrufmöglichkeiten auf verschiedenen logischen und technischen Ebenen.

Die Ebenen entsprechen dabei unterschiedlichen Kommunikationsschichten, die neben dem Transport der Informationen zusätzliche Funktionalitäten (Service) zur Verfügung stellen. Jede Schicht kann aus der jeweils darüber bzw. darunter liegenden Schicht mit den Komponenten des CIB documentServers angesprochen werden.

Zusätzlich verfügt jede Schicht auch über offen gelegte Schnittstellen, die eine Kundenanwendung direkt ansprechen kann. Der Aufrufer des CIB documentServers entscheidet selbst, welche Aufrufebene und welche Zusatzfunktionalität er nutzen möchte.

Darstellung des Schichtenmodells:

Hier sind die Schichten von innen nach außen aufgelistet:

Komponenten

Die im CIB documentServer eingesetzten Produkte finden Sie auch auf unserer Produktübersicht:

CIB docgen

Die umfangreiche Produktpalette der CIB office Module enthält als Basis die dialoglosen, und damit für den Servereinsatz geeigneten CIB docgen Produkte. Siehe hierzu die Produktübersicht:

Die damit verfügbare Basisfunktionalität umfasst

CIB merge: Text-Daten-Integration, bedingte Textbausteine, Schleifen über Detaildaten, Berichtserstellung, dynamische Geschäftsgrafiken, usw.

CIB format/output: Formatkonvertierung, PDF Erzeugung, Direktdruck, Formulargenerierung, dynamische Barcodes, usw.

CIB pdf toolbox: Text-Daten-extrahieren bei PDF-Formularen, PDF Dokumente zusammenfügen, nachträglich Texte ins PDF einfügen, usw.

CIB pdf formfields: Ergänzung zu CIB format/pdf, um zu Platzhaltern im Eingabedokument entsprechende Eingabefelder im PDF Ausgabedokument anzulegen.

CIB mail: E-Mail Versand über SMTP oder MAPI

Eine Übersicht finden Sie hier:

https://www.cib.de/de/produkte/cib-office-module-comod.html

Detaillierte Beschreibungen zu den einzelnen Produkten entnehmen Sie bitte den entsprechenden technischen Leitfäden.

CIB job

CIB job stellt die individuelle Funktionalität der CIB docgen auf eine einheitliche Weise zur Verfügung und erweitert deren Aufrufschnittstellen um eine dokumentorientierte, XML-basierte Auftragsverarbeitung

Eine einzige XML-basierte Schnittstelle,

Übergabe der Nutzdaten zur Text-Daten-Integration im XML

Keine Erzeugung von Zwischendateien,

Skript- und Batchverarbeitung

Benutzerdefinierte Erweiterungen

Wird ein Auftrag an CIB job (Auftragsmanager) gegeben, so setzt diese Komponente die XML Auftragsbeschreibung in die entsprechenden Aufrufe der ausführenden Module (CIB docgen) um.

CIB documentServer

Für den Servereinsatz der CIB docgen Module einschließlich dem Auftragsmanager CIB job werden mit dem Softwarepaket CIB documentServer eine große Zahl von verschiedenen Serverszenarien unterstützt:

Windows, Linux, HPUX, Sun Solaris, weitere

Java, .net, Native,

http, Sockets, RMI

JEE, MQSeries, MTS/COM+, SOAP, OCI, weitere

Das CIB documentServer Softwarepaket bietet dabei Lösungen für die Standardanforderungen

Mehrfachzugriff, Parallele Verarbeitung, Warteschlange

Skalierbarkeit, Lastverteilung

Plattformunabhängigkeit

Schnittstellen, Netzwerkprotokolle

Offlinebetrieb

Das CIB documentServer Standardpaket enthält die Umsetzung für JEE und wird für alle oben angegebenen Plattformen angegeben.

Siehe hierzu auch den nachfolgenden Abschnitt Nutzungsvarianten.

CIB pdf formserver

Der CIB formserver ist ein Aufsatz zum CIB documentServer in der Integrationsschicht und wird mit diesem ausgeliefert.

Werden PDF-Formulare vom Anwender mit dem Adobe Reader ausgefüllt, kann der Anwender mit dem Reader weder das Formular zusammen mit den eingegebenen Daten speichern, noch stehen seine Eingaben dem Formularbereitsteller zur Verfügung.

Mit dem CIB formserver wird dagegen ein PDF-Dokument erstellt, das diese eingegebenen Daten enthält und dem Anwender angezeigt wird.

Nutzungsvarianten

Der CIB documentServer fasst die vorgenannten Komponenten zu einem Softwarepaket zusammen und erweitert die Auftragsverarbeitung um praxisrelevante, standardisierte Technologien und Protokolle. So wird eine leistungsfähige Dokumentgenerierung mit Warteschlange, Lastverteilung, Multiuserbetrieb, usw. in zahlreichen Systemumgebungen zur Verfügung gestellt.

Die unterschiedlichen Anforderungen an eine Serverlösung zur Dokumentgenerierung erfordern die Unterstützung verschiedener Betriebssysteme (Windows, Linux, Unix), verschiedener Programmierumgebungen (Java, .net, Native) und verschiedener Protokolle (http, Sockets, RMI) sowie Technologien (JEE, MQSeries, MTS, SOAP).

Daher enthält das CIB documentServer Paket Module und vorgefertigte Lösungen, um möglichst viele dieser Nutzungsvarianten mit möglichst geringem Programmieraufwand zu unterstützen.

Der CIB documentServer kann beispielsweise beim Einsatz in JEE Servlet Containern "out of the box" sofort ohne Änderung eingesetzt werden. Ein mitgeliefertes Framework ermöglicht ein komfortables Programmieren der Schnittstellen.

Schneller Einstieg

Im Folgenden finden Sie Beschreibungen, die Ihnen den Start mit dem CIB documentServer erleichtern. Es wird beschrieben, wie der CIB documentServer auf dem Server installiert wird, was Sie bei der individuellen Konfiguration zu beachten haben und wie der CIB documentServer vom Client aufgerufen werden kann.

Sollten hierbei Probleme oder Fragen auftreten, schauen Sie bitte zunächst im Kapitel FAQs nach, ob dort Ihre Fragen bereits beantwortet werden. Sollten Sie dort keine Lösung für Ihr Problem finden oder Unterstützung bei nicht aufgeführten Umgebungen benötigen, wenden Sie sich an den CIB Support.

Wie im Abschnitt Lieferumfang beschrieben, erhalten Sie mit dem CIB documentServer zwei Pakete, das Client-Paket und das Server-Paket.

Das Server-Paket enthält die notwendigen Dateien, die Sie für die Installation auf dem Server benötigen (siehe Abschnitt Installation). Dazu gehört das Applikationsarchiv CibDocumentServer.war und die Dateien CibDocumentServer.properties bzw. CibDocumentServer-Forward.properties, um individuelle Einstellungen an der Konfiguration des CIB documentServer vorzunehmen (siehe Abschnitt Konfiguration).

Installation

Je nachdem, ob der CIB documentServer in einem Servlet Container wie Tomcat oder auf einem Application-Server wie JBoss oder BEA Weblogic installiert werden soll, gibt es verschiedene Vorgehensweisen. Im Folgenden wird exemplarisch anhand von Tomcat, JBoss und BEA Weblogic beschrieben, wie der CIB documentServer im jeweiligen Umfeld deployed werden kann.

Falls Sie den CIB documentServer als Webservice installieren möchten, finden Sie in diesem Kapitel ebenfalls alle notwendigen Informationen zum Deployment. Anhand von SOAP und JAX-WS wird die Installation als Webservice beschrieben.

Installationsvoraussetzungen

Für die Verwendung des CIB documentServer auf einem Server werden eine Java-Laufzeitumgebung (JRE oder JDK) und ein JEE Servlet-Container oder ein JEE Application-Server benötigt.

Bitte installieren Sie eine geeignete aktuelle Java-Laufzeitumgebung (JRE oder JDK) 32bit oder 64bit als Standardinstallation auf Ihrer gewünschten Serverplattform. Konfigurieren Sie die Java VM geeignet für einen Produktionsbetrieb: Speichereinstellungen, Auswahl Garbage-Collector, weitere Einstellungen.

Stellen Sie dann einen Servlet-Container oder Application-Server bereit, laut der Anleitungen der Hersteller. Im einfachsten Fall entpacken Sie ein aktuelles Tomcat.zip, das für Ihre Plattform geeignet ist. Konfigurieren Sie den Servlet-Container bzw. Application-Server geeignet für einen Produktionsbetrieb: Speichereinstellungen, Threads, Timeouts, Loadbalancing, vorgelagerter Webserver, weitere Einstellungen.

Installieren Sie den CIB documentServer wie nachfolgend beschrieben.

Dabei ist insbesondere darauf zu achten, dass das CibDocumentServer.war nach dem Deployment entpackt im Servlet-Container oder Application-Server vorliegen muss. Ein Betrieb des CIB documentServer ist sonst nicht möglich.

Der Einsatz von EAR-Dateien ist immer dann erforderlich, wenn die CibDocumentServer.properties-Datei anders nicht neben das .war deployed werden kann. Die meisten Application-Server erfordern daher diesen Schritt.

Verwendung von CIB doXichange

(Unterstützt ab CIB documentServer Version 1.9, vorausgesetzt wird CIB job 2.0.1)

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

Bei Verwendung eines LibreOffice 64bit ist auch ein CIB documentserver 64bit erforderlich. Das analoge gilt für die 32bit Versionen.

Installierte makros ausführen

Ab CIB documentServer 1.10.5 ist es möglich ein in LibreOffice installiertes Macro ausführen.

Details hierzu werden im Leitfaden für CIB job ausführlich dargestellt, konkrett im Kapitel 4.11.

Installation in einem JEE Servlet-Container

Um den CIB documentServer in einem Servlet-Container zu installieren, ist im Allgemeinen wie folgt vorzugehen:

Installation in Apache Tomcat

1.     Versionen von Apache Tomcat ab 8.5.38 in Kombination mit Java JDK ab 8u161 werden empfohlen.

5.     Sie haben zwei Möglichkeiten, die CibDocumentServer.properties abzulegen: 
Kopieren Sie die Datei in den Ordner webapps, so müssen Sie keine weiteren Einstellungen vornehmen. 
Legen Sie die Properties-Datei an einem anderen Ort ab, so muss dieses Verzeichnis im Classpath der Webanwendung CIB documentServer sein. Wie Sie die Einstellungen Ihren individuellen Bedürfnissen anpassen, finden Sie im Abschnitt Konfiguration.

6.     Starten Sie Tomcat. Im Log muss während des Starts des Containers ein Eintrag "Context CIB documentServer initialized." erscheinen.

Installation in einem JEE Application-Server

Soll der CIB documentServer auf einem Application-Server wie JBoss, GlassFish oder BEA Weblogic installiert werden, kann das über die WAR-Datei oder über eine sogenannte EAR-Datei erfolgen. Zur Erstellung einer EAR-Datei gibt es zwei Verfahren (WAR entpackt/nicht entpackt), die nachfolgend beschrieben werden. Welches Verfahren bei welchem Serverprodukt einzusetzen ist wird dann bei den jeweiligen Installationsanleitungen benannt.

Der Inhalt des EAR besteht aus:

1.     Datei CibDocumentServer.war (unverändertes Archiv wie von CIB erhalten)

2.     Datei CibDocumentServer.properties (Konfiguration oder Forward-Konfiguration)

3.     Unterordner META-INF

4.     Datei META-INF/application.xml (EAR-Descriptor)

Minimaler Inhalt der Datei application.xml im Unterordner 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>

Abschließend müssen Sie aus den genannten vier Elementen ein Zip-Archiv erzeugen, in CibDocumentServer-<version>.ear umbenennen und deployen.

Der Inhalt des EAR besteht aus:

1.     Ordner CibDocumentServer (entpackte CibDocumentServer.war)

2.     Datei CibDocumentServer.properties (Konfiguration oder Forward-Konfiguration)

3.     Unterordner META-INF

4.     Datei META-INF/application.xml (EAR-Descriptor)

Minimaler Inhalt der Datei application.xml im Unterordner 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>

Abschließend müssen Sie aus den genannten vier Elementen ein Zip-Archiv erzeugen, in CibDocumentServer-<version>.ear umbenennen und deployen.

Dies ist ab Version 1.15.6 unterstützt. Für vorherige Versionen gehen Sie bitte zum Abschnitt 3.1.3.3.2 Installation eines entpackten WAR

1.     Wildfly herunterfahren.

2.     Legen Sie folgende Verzeichnisstruktur unter das Unterverzeichnis „modulescib/documentserver/main“

3.     Die „CibDocumentServer.properties“-Datei ins Unterverzeichnis „cib/documentserver/main“ kopieren

4.     Im Unterverzeichnis „cib/documentserver/main“ eine neue Datei module.xml mit dem folgenden Inhalt erzeugen

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

5.     Kopieren Sie das Applikationsarchiv CibDocumentServer.war in das Unterverzeichnis „standalone/deployments“

6.     Wildfly neustarten

1.     Wildfly herunterfahren.

2.     In dem Ordner „standalone/deployments“ einen weiteren Ordner „CibDocumentServer.war“ erstellen.

3.     In diesen Ordner das unveränderte „.war“ entpacken.

4.     Die „CibDocumentServer.properties“-Datei ins Verzeichnis „standalone/deployments“ kopieren.

5.     Eine leere Marker-Datei mit dem Namen „CibDocumentServer.war.dodeploy“ erstellen

6.     Diese Datei „CibDocumentServer.war.dodeploy“ mit einem Texteditor öffnen, den Text „CibDocumentServer.war“ (Ohne Anfürungszeichen) eintragenund die Datei speichern.

7.     Wildfly neustarten

Das CibDocumentServer.war kann mit den GlassFish Kommandozeilentools oder der grafischen WebUI ohne weitere Änderungen deployed werden.

Die Konfigurationsdatei CibDocumentServer.properties kann im Verzeichnis glassfish\domains\<domain>\applications Ihrer GlassFish domain abgelegt werden.

Installation eines EAR in GlassFish 5

Im GlassFish Application-Server muss das EAR ohne entpacktem WAR verwendet werden, siehe oben.

Die Kompatibilität mit Oracle Weblogic 12 ist erst ab Version 1.15.2 gegeben.

Für das Deployment können folgende Wege verwendet werden.

Erst ab Version 1.15.8 ist das automatische Deployment einer War-Datei berücksichtigt.

1.     Beenden Sie den BEA weblogic 12 Server

2.     Die EAR-Datei in den Ordner „autodeploy“ der weblogic-Domain kopieren (<beahome>/.../<domain>/autodeploy)

3.      BEA weblogic 12 Server starten

4.     Das Deployen des CIB documentServer geschieht nun automatisch. Es wird zusätzlich automatisch ein entsprechender Eintrag in der Datei „config.xml“ (<beahome>/.../<domain>/config/config.xml) vorgenommen

5.     Zum Löschen des CIB documentServer den weblogic-Server herunterfahren und die EARDatei aus dem „autodeploy“-Verzeichnis entfernen. Beim nächsten Start des weblogic Servers wird der zugehörige Eintrag aus der „config.xml“-Datei automatisch entfernt.

1.     Beenden Sie den BEA weblogic 12 Server

2.     Entfernen Sie sämtliche <app-deployment>-Elemente die auf den CibDocumentServer verweisen, aus der Weblogic 12 Konfigurationsdatei:

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

3.     Konfiguration des CIB documentServers in CibDocumentServer.properties vornehmen

4.     Deployen des ausgepackten WAR Archivs:

-          Entpacken Sie das WAR in das Verzeichnis

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

-          Kopieren Sie Ihre CibDocumentServer.properties nach

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

5.     Starten Sie den BEA weblogic 12 Server

Nach dem Start des Weblogic Servers wird der CIB documentServer deployed. Es wird zusätzlich automatisch der notwendige Eintrag in der Weblogic Server Konfigurationsdatei „config.xml“ vorgenommen. Diese befindet sich im folgenden Verzeichnis

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

Zum Löschen des CIB documentServer beenden Sie bitte den BEA weblogic-Server. Entfernen Sie danach das CibDocumentServer-Verzeichnis sowie die CibDocumentServer.properties-Datei aus dem autodeploy-Verzeichnis. Beim nächsten Start des weblogic Servers wird der zugehörige Eintrag aus der „config.xml“-Datei automatisch entfernt.

1.     Beenden Sie den BEA weblogic 12 Server

2.     Entfernen Sie sämtliche <app-deployment>-Elemente die auf den CibDocumentServer verweisen, aus der Weblogic 12 Konfigurationsdatei:

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

3.     Konfiguration des CIB documentServers in CibDocumentServer.properties vornehmen

4.     Legen Sie ein weiteres Verzeichnis für externe Konfigurationsdateien fest. Zum Beispiel:

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

5.     Kopieren Sie Ihre CibDocumentServer.properties nach

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

6.     Kopieren Sie das WAR Archiv nach

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

7.     Starten Sie den BEA weblogic 12 Server

Nach dem Start des Weblogic Servers wird der CIB documentServer deployed. Es wird zusätzlich automatisch der notwendige Eintrag in der Weblogic Server Konfigurationsdatei „config.xml“ vorgenommen. Diese befindet sich im folgenden Verzeichnis

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

Zum Löschen des CIB documentServer beenden Sie bitte den BEA weblogic-Server. Entfernen Sie danach das CibDocumentServer-Verzeichnis sowie die CibDocumentServer.properties-Datei aus dem autodeploy-Verzeichnis. Beim nächsten Start des weblogic Servers wird der zugehörige Eintrag aus der „config.xml“-Datei automatisch entfernt.

In diesem Abschnitt wird als Beispiel eine Schritt-für-Schritt-Installation des CIB documentServer und aller nötigen Komponenten in einer Windowsumgebung von Grund auf beschrieben.

Es ist darauf zu achten, dass Tomcat und die verwendete Java-Umgebung kompatibel zueinander sind, also beides in einer 32bit- bzw. beides in einer 64bit-Version vorliegt. Es wird für dieses Beispiel JDK8 und Tomcat in der Version 9.0.5 herangezogen.

1.     Java installieren:

a.     JDK8 mit allen Features im Standardverzeichnis installieren.

b.     JRE8 im Standardverzeichnis installieren.

2.     Tomcat entpacken:

a.     Tomcat-Archivdatei entpacken nach C:/cib/apache-tomcat-9.0.5
Alternativ Tomcat mit dem Windows-Installer als Service in dieses Verzeichnis installieren. Dann entfällt Schritt 3.

b.     Datei C:/cib/apache-tomcat-9.0.5/conf/server.xml konfigurieren:
Um das Tomcat Access Logging zu aktivieren, den Eintrag „org.apache.catalina.valves.AccessLogValve“ aktivieren.

3.     Tomcat als Service installieren, um direkt nach dem Systemstart zur Verfügung zu stehen:

a.     JAVA_HOME im System für alle User auf Pfad zu gewünschtem JDK setzen, zum Beispiel JAVA_HOME= C:\Program Files\Java\jdk1.8.0_161

b.     Die Datei C:/cib/apache-tomcat-9.0.5/bin/tomcat9.exe berechtigen (Win7 und Server2008):
Rechtsklick->Eigenschaften->Sicherheit: Zulassen klicken.
Bei Kompatibilität->Alle Benutzer->Als Administrator starten. Ok.

c.     Ebenso für tomcat6w.exe, tomcat7.exe, tomcat7w.exe (je nach Tomcat Version).

d.     Eingabeaufforderungskonsole mit Administratorrechten öffnen (Startmenü>Alle Programme>Zubehör>Eingabeaufforderung Rechtsklick>Als Administrator ausführen)

e.     C:/cib/apache-tomcat-9.0.5/bin/service.bat remove in Eingabeaufforderung aufrufen.

f.      C:/cib/apache-tomcat-9.0.5/bin/service.bat install in Eingabeaufforderung aufrufen.

g.     C:/cib/apache-tomcat-9.0.5/bin/tomcat9.exe aufrufen (Win7, Server2008), alle UAC und Windows Firewall Sicherheitsmeldungen zu Tomcat und socketserver.exe genehmigen.

h.     Eingabeaufforderung schließen, um Tomcat wieder zu beenden.

i.      Auf dem Desktop eine Verknüpfung auf „C:/cib/apache-tomcat-9.0.5/bin/tomcat9w.exe“ anlegen.

j.      In den Eigenschaften der Verknüpfung auf den Reiter „Verknüpfung“ wechseln und Schaltfläche „Erweitert…“ anklicken.

k.     Im Menü „Erweiterte Eigenschaften“ die Option „Als Administrator ausführen“ aktivieren.

4.     CIB documentServer installieren:

a.     Mittels Tomcat9w.exe, welches über die Verknüpfung oder über die installierte Verknüpfung „Configure Tomcat“ gestartet wird, können nun diverse Tomcat-Parameter eingestellt werden:
Konfigurieren Sie damit den Service auf Startup "Automatic".
Erhöhen Sie ggf. die Speicherwerte bei den Java-Einstellungen, zum Beispiel 512/512.
Fügen Sie folgende Garbage-Collection-Einstellungen den VM-Parametern hinzu:
-Xincgc -XX:MaxGCPauseMillis=500
Hinweis: In den Java-Einstellungen ist für Tomcat standardmäßig die Server-JVM des JDK eingestellt.

b.     Um den Dienst in Betrieb zu nehmen, den Windows-Rechner neu starten, oder über Tomcat9w im Reiter „General“ starten (klicken auf die „Start“-Schaltfläche).

c.     Im Browser die Adresse „localhost:8080“ aufrufen.
Prüfen, ob im Browser die Tomcat Homepage angezeigt wird, mit dem Text „If you're seeing this page via a web browser, it means you've setup Tomcat successfully."

5.     CIB documentServer installieren:

a.     CibDocumentServer-Forward.properties nach C:/cib/apache-tomcat-9.0.5/webapps kopieren.

b.     CibDocumentServer-Forward.properties nach CibDocumentServer.properties umbenennen.

c.     CibDocumentServer-Forward.properties konfigurieren:
de.cib.docserv.ForwardConfigurationFilename=C:/cib/conf/CibDocumentServer.properties

d.     Inhalt des Verzeichnisses opt/cib kopieren nach C:/cib

e.     Datei C:/cib/conf/CibDocumentServer.properties konfigurieren:
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

f.      Bei asynchronen Jobs mit langer Laufzeit: de.cib.docserv.socket.SocketTimeout=36000000

g.     Datei C:/cib/conf/jobconfig.xml konfigurieren:
LicenseCompany und LicenseKey eintragen oder LicenseFile hinterlegen (siehe Kapitel 6.30 CIB Job – Technischer Leitfaden)
Templates-Verzeichnisse setzten auf c:/cib/templates (die einzelnen Verzeichniseinträge können bei Bedarf auch individuell den eigenen Anforderungen gemäß angepasst werden)

h.     Datei C:/cib/conf/log4j.xml konfigurieren:
Pfad zu cibdocserv.log anpassen: <param name ="FileNamePattern" value= "C:/cib/logs/cibdocserv.%d{yyyy-MM-dd}.log"/>

i.      CibDocumentServer.war nach C:/cib/apache-tomcat-9.0.5/webapps kopieren.
Hier ist anzumerken, dass in einer 64bit-Windowsumgebung sowohl die 32bit- als auch als 64bit-Version des DocumentServers betrieben werden kann, ungeachtet der Bitanzahl der installierten Java- bzw. Tomcat-Umgebung.

6.     Überprüfung der Funktionsfähigkeit:

a.     Fortfahren mit den Kapiteln „Anlauftests und Fehlersuche

b.     Aufruf Weboberfläche“ und „Anlauftest CIB documentServer“.

c.     Weiterführende Hinweise zu den Einstellungen des DocumentServers können im Kapitel „Konfiguration“ vorgefunden werden.

Andere Installationsthemen

Um den CIB documentServer als JAX-WS Webservice zu installieren, muss JAX-WS auf dem Server installiert sein. Eine aktuelle Version von JAX-WS kann hier heruntergeladen werden: https://jax-ws.dev.java.net/.

Um JAX-WS beispielsweise in Tomcat zu installieren, ist folgendermaßen vorzugehen:

1.     Auspacken von JAX-WS

Anlauftests und Fehlersuche

Aufruf Weboberfläche

Nach der Installation des Applikationsarchivs CibDocumentServer.war auf der Maschine MyServername und dem erfolgreichen Start des Servlet-Containers kann mit folgendem Link im Standardbrowser die Weboberfläche des CIB documentServers aufgerufen werden:

Protokoll://MyServername:Port/CibDocumentServer/

Der Server MyServer muss über das verwendete Protokoll und den entsprechenden Port vom Client aus erreichbar sein.

Beispiel (Tomcat):

http://MyServername:8080/CibDocumentServer/

Gegebenenfalls müssen Sie bei anderen Servlet-Containern einen anderen Port eingeben.

Diese Weboberfläche bietet Ihnen die Möglichkeit, einen ersten Anlauftest des CIB documentServers durchzuführen, Aufträge direkt auszuführen und Logging-Einstellungen vorzunehmen (ab Version 1.4.19d).

Über die Schaltfläche „Show configuration“ können die entsprechenden gesetzten Einstellungen und Pfade angezeigt werden (ab Version 1.10.1):

Folgendes Vorgehen wird empfohlen, um die Umgebung für den CIB documentServer optimal vorzubereiten. Für die Durchführung der Anlauftests ist das nicht erforderlich. Eine detaillierte Beschreibung für diese Standard-Konfiguration finden Sie im Abschnitt „Beispielsituation zur Konfiguration einschließlich forward-Properties“.

Legen Sie folgende Verzeichnisse an:

/opt/cib/conf

/opt/cib/logs

/opt/cib/ppd

/opt/cib/fonts

/opt/cib/templates

/opt/cib/forms

Das Template-Verzeichnis befindet sich im Client-Paket unter examples/templates. Legen Sie den Inhalt dieses Verzeichnisses im angelegten Verzeichnis /opt/cib/templates ab. Damit der CIB documentServer auf  die Templates zugreifen kann, müssen Sie die Pfadangaben in der jobconfig.xml ggf. anpassen (siehe auch Abschnitt Konfiguration). Die Beispielauftragsdateien befinden sich im Verzeichnis example/jobs des Clientpakets.

Die CibDocumentServer.properties sollte im angelegten Verzeichnis /opt/cib/conf liegen. In diesem Verzeichnis ist auch die Datei jobconfig.xml zu finden, deren Pfad in der CibDocumentServer.properties angegeben werden muss. Außerdem wird dort auch der Pfad zu den Logdateien angegeben (Verzeichnis /opt/cib/logs). Die jobconfig.xml enthält neben dem Pfad zu den Templates (/opt/cib/templates) auch die Pfade zu den Fonts (/opt/cib/fonts) und den Druckereinstellungen (/opt/cib/ppd).

Zur Fehlersuche können Sie die entsprechenden Logfiles auswerten. Fehler, die in der Java Webanwendung selbst verursacht werden, sind in den Logfiles des Application-Servers zu finden. Fehler im Socketserver werden durch die Logging-Einstellung „S“ in der Datei socketserver.log protokolliert. Treten Fehler bei der Jobverarbeitung auf, sind diese im Logfile jobtrace.log (Logging-Einstellung „J“) enthalten. Sollten Fehler in den CIB-Modulen auftreten, werden diese in den entsprechenden Logfiles ausgegeben (separates Logfile je Modul: Logging-Einstellungen „MPF“).

Konfiguration

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

CibDocumentServer.properties

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

CibDocumentServer-Forward.properties (ab 1.4.19d)

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

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

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

Angabe von Konfigurationen auf der Kommandozeile

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

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

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

Inhalt der CibDocumentServer.properties

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

Konfigurationspfad

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

Leistung

de.cib.docserv.http.PrestartOnLoad=true

de.cib.docserv.MaxProcessCountAsync=3

Maximale Anzahl der SocketServer Ports für asynchrone Anfragen.

Ports

de.cib.docserv.socket.FirstPort=50000

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

Logging

CIB documentServer

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

Logging der CIB docgen Module

de.cib.docserv.LogOptions=SJ

Konfiguration Maintenance Feature

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

Umgebungsvariablen

de.cib.docserv.socket.Environment=

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


Beispiel Zeitzonendefinition AIX

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

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

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

Hinweis:

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

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

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

· Linux

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

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

· Windows

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

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

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

· Linux

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

· Windows

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

Jobconfig.xml für CIB docgen Default-Properties

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

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

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

Das Beispiel in Kapitel 3.2.7 zeigt das empfohlene Vorgehen.

Konfiguration von Sprachdateien für Texterkennung durch CIB ocr

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

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

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

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

     Linux:"/opt/cib/tessdata"

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

Beispielsituation zur Konfiguration einschließlich forward-Properties

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

# Forward to this configuration:

de.cib.docserv.ForwardConfigurationFilename=
/opt/cib/conf/CibDocumentServer.properties

Sie haben die folgenden Verzeichnisse angelegt:

/opt/cib/conf

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

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

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

/opt/cib/conf/jobconfig.xml:

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

Das ergibt folgendes Bild an Konfigurationseinstellungen:

Monitoring mit MBean DocservRuntime (ab 1.5.55f)

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

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

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

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

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

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

 de.cib.docserv.http.jmx.RegisterMBeansListener 

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

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

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

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

Am Beispiel der Java Monitoring & Management Console:

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

Aufruf CIB documentServer

Im Folgenden finden Sie Beschreibungen, wie Sie aus dem Client-Paket den CIB documentServer komfortabel in JAVA einbinden können. Außerdem enthält dieser Abschnitt Anleitungen, wie Sie den CIB documentServer webservice in Visual basic .net, C# .net und mit dem JAX-WS Framework aufrufen können.

CIB documentServer Framework/Java

Das CIB documentServer Framework ermöglicht für Java eine komfortable Einbindung des CIB documentServers. Aufgrund der Ähnlichkeit der Konzepte der beiden Plattformen sowie von Java und C# wird bleibt der entsprechende Abschnitt kurz.

…
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

Im Folgenden sind die wichtigsten Packages aufgelistet.

de.cib.docserv

Dieses Package enthält zusammen mit den Unterpackages die Klassen, die für die Nutzungsvarianten Java, JEE Servlet Container und JEE EJB Container benötigt werden.

Speziell die für Sie wichtigen Schnittstellenklassen, die das Interface de.cib.docserv.DocumentServer implementieren finden Sie hier. Außerdem die Basisimplementierung des CIB documentServer in Form von de.cib.docserv.ServerManager, de.cib.docserv.ServerQueue, sowie die Exception- und Error-Klassen.

de.cib.docserv.job

Dieses Package enthält unter anderem die für Sie wichtigen Hilfsklassen de.cib.docserv.job.Request und de.cib.docserv.job.Response, mit denen Aufträge erzeugt und analysiert werden können. Benutzen Sie zusätzlich die Klasse de.cib.xml.dom.Dom, um Ihr XML mit den Nutzdaten dem Auftrag hinzuzufügen.

de.cib.xml.dom

Hervorgehoben sei die Klasse de.cib.xml.dom.Dom, mit der andere Klassen des Frameworks XML-Daten entgegennehmen. Verpacken Sie also Ihr XML mit den Nutzdaten in einen de.cib.xml.dom.Dom.

Beispiel-Aufruf aus JAVA

//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);
	}
} 

Weitere Beispiele finden Sie im Client-Paket unter example/de/cib/docserv/samples.

Aufbau eines Auftrags aus JAVA

Es ist auch möglich einen XML-Auftrag erst durch das CIB documentServer Framework aufzubauen.

//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 diesem Beispiel wird ein Auftrag mit einem “PdfJoin” Step aufgebaut. Eine Reihe von Properties wird für den entsprechenden Auftrag programmatisch deklariert.

Es ist auch möglich den Wert von gewünschten Properties im Ergebnis-Response abzuholen durch die Verwendung der Methode “setPropertyMode” beim Request-Aufbau (ab Version 1.10.6).

Die Propertywerte können wie folgt abgeholt werden:

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

Analog zum Framework/Java erlaubt das Framework/.net eine Einbindung der Auftrags-Funktionalität in kundeneigene .net-Anwendungen.

Aufruf CIB documentServer webservice

In diesem Abschnitt finden Sie Beschreibungen, wie Sie in unterschiedlichen Umgebungen den CIB document webservice aufrufen können. Dabei wird auf VB.net, C#.net und das JAX-WS Client Framework eingegangen.

VB.net

Entwerfen Sie eine Methode, die den CIB documentServer webservice aufruft.

Hinzufügen des Webservice

Registrieren Sie den Webservice, indem Sie Ihrem Projekt eine Webressource hinzufügen. Ergänzen Sie die URL am Ende mit ?wsdl. Der Webservice “CibDocumentServer” sollte mit einer Methode “generate” angezeigt werden. Geben Sie den Paketnamen aus de.cib.docserv.web als „Web reference name“ an.

Generieren Sie Klassen, indem Sie „Update“ auswählen. Um diesen Schritt erfolgreich auszuführen, benötigen Sie Internetzugriff auf www.cib.de.

Aufruf des Webservice

Entwerfen Sie jetzt Instanzen der Service und Request Klassen z. B. folgendermaßen:

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

Fügen Sie dem Request die benötigten Steps hinzu. (siehe auch Codebeispiel im Anhang)

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"

Fügen Sie dem Request Ihre Nutzdaten hinzu. Der Aufbau ist beliebig, muss aber zum Eingabe-Template (-i) des merge-Steps passen und zur Option -d.

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

request.Data = xmldata.DocumentElement

Rufen Sie jetzt den Webservice auf und bereiten ihn auf den Empfang des Ergebnisses vor:

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

Verarbeiten von Ergebnissen

Treten Server-Fehler auf, wird durch obigen Aufruf eine Exception geworfen.

Im Falle von Fehlern, die bei der Dokumentgenerierung auftreten, werden keine Exceptions geworfen. Sie erhalten stattdessen ein Response-Objekt. Sie sollten den Fehlercode vom Jobresult abholen, um zu entscheiden, ob ein Ausführungsfehler aufgetreten ist. Ein Beispiel für eine Fehlermeldung lautet: „CIB merge error 10: Unbekannte Variable im 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

Im Erfolgsfall müssen Sie die erzeugten Dokumente aus dem Response herausholen. Das Ergebnis ist base64-kodiert. Dieses müssen Sie entsprechend dekodieren.

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

Den kompletten VB.net Sourcecode finden Sie im Anhang dieses Dokuments.

Die entsprechenden Beispiele für SOAP Requests und Responses finden Sie ebenfalls im Anhang.

C# .net

Soll der CIB documentServer aus C#.net als Webservice aufgerufen werden, ist genauso vorzugehen wie unter VB.net. Die Aufrufe unterscheiden sich lediglich in ihrer Syntax. Einen Beispielcode finden Sie im Anhang.

Bei dem Aufruf aus C#.net mittels einer HTTP-Verbindung kann es Kommunikationsprobleme im Zusammenhang mit einem Applikationsserver geben. In diesem Fall kann es möglicherweise helfen, die „Expect100Continue“-Eigenschaft der Client-Server Verbindung zu deaktivieren (der Standardwert ist true). Beispiel:

webRequest.ServicePoint.Expect100Continue = false;

CIB documentServer Framework/JAX-WS

Der JAX-WS (Java API for XML-Web Services) Client stellt eine einfache Möglichkeit dar, den CIB documentServer webservice aufzurufen. Die Funktionalität ist im CibDocumentServer.jar integriert. Um JAX-WS zu benutzen ist mindestens ein JRE 5.0 notwendig.

Lokaler Aufruf von CIB job (Offline)

Dieser Abschnitt muss noch überarbeitet werden bzgl. JobDocumentServerImpl.

Der modulare Aufbau des CIB documentServer erlaubt dessen Installation auf dem Client auch ohne lokale Serverumgebung wie JEE Servlet Container, MTS oder .net.

Die Anwendung übergibt einen Auftrag (XML) an die vorhandenen Komponenten des CIB documentServer, der ein entsprechendes Dokument erzeugt.

Die Übergabe erfolgt dabei über Aufrufschnittstellen aus Javacode oder aus native Code (Schnittstellen Java Call, Native Call). Hierfür ist kein JEE Application-Server erforderlich.

Wenn mehrere Threads Aufträge an einen Servermanager senden, jedoch kein Webcontext vorliegt, stehen geeignete Klassen bereit, um die Verwaltung des Servermanagers zu übernehmen (de.cib.docserv.LocalDocumentServerImpl).

In normalen Java-Anwendungen, die statt JNI ebenfalls das CIB documentServer Framework einsetzen möchten, ist es nicht erforderlich, mehrere Socketserver parallel zu starten.

Aufruf CIB documentServer asynchron

Um Aufträge asynchron mit dem CIB documentServer auszuführen, verwenden Sie bitte die Methode asyncExecute des CIB documentServer Frameworks.

Bei Verwendung anderer Ansteuerungen des CIB documentServers aus anderen Sprachen, setzen Sie bitte zusätzlich zu allen üblichen http header fields noch das Headerfield async-action:

Asynchronen Aufruf starten:

async-action: new

Ergebnis des asynchronen Aufrufs mit der ID 12345 abholen:

async-action: 12345

Die bei asynchronen Aufrufen ausgetauschten XML-Inhalte entnehmen Sie bitte dem technischen Leitfaden für CIB job aus den Abschnitten Zusatzeinstellungen für asynchron ausgeführte Aufträge und Inhalt eines Auftragsergebnisses zu einem asynchron ausgeführten Auftrag.

Versionswechsel

Die folgenden Änderungen müssen bei einem Versionswechsel des CIB documentServer beachtet werden. Es sind Auswirkungen auf Ihren Client-Code oder auf einzelne Installationsschritte möglich.

Migration von CIB documentServer 1.4 auf 1.5

1. Benötigt nun JDK5 auf dem Server. Tomcat 5.0 wird nicht mehr unterstützt.
2. Die in Client-Anwendungen verwendete CibDocumentServer.jar wird ersetzt durch die neuen .jar Dateien cibdocserv-common-1.5.x.jar, cibdocserv-client-1.5.x.jar.
3. HttpDocumentServerImpl ist veraltet. Bitte verwenden Sie UrlDocumentServerImpl stattdessen.
4. Die Standardkonfigurationseinstellung von de.cib.docserv.ServerProcessFactoryClass wurde geändert in de.cib.docserv.socket.UrlSocketServerProcessFactory. Bitte passen Sie Ihre alten Konfigurationsdateien an.
5. Einige Utility Pakete wurden umbenannt von de.cib.paketname in de.cib.docserv.packetname.
6. DocumentServerException public member wurde durch public getter/setter Methoden ersetzt.
7. AIX4 und Sparc Solaris 8 werden nicht mehr unterstützt.

Migration von CIB documentServer 1.5 auf 1.6

1. Benötigt nun JDK6 auf dem Server
2. Unterstützung von JDK8
3. Die in Client-Anwendungen verwendete CibDocumentServer.jar wird ersetzt durch die neuen .jar Dateien cibdocserv-common-1.6.x.jar, cibdocserv-client-1.6.x.jar.
4. Unterstützung für Apache Tomcat 8

Migration von CIB documentServer 1.6 auf 1.7

1. Die in Client-Anwendungen verwendete CibDocumentServer.jar wird ersetzt durch die neuen .jar Dateien cibdocserv-common-1.7.x.jar, cibdocserv-client-1.7.x.jar.
2. Neue Funktionalität für die optische Charaktererkennung durch CIB ocr

Migration von CIB documentServer 1.7 auf 1.8

1. Die in Client-Anwendungen verwendete CibDocumentServer.jar wird ersetzt durch die neuen .jar Dateien cibdocserv-common-1.8.x.jar, cibdocserv-client-1.8.x.jar.
2. CIB servermanager wird nicht mehr unterstützt
3. Update: CIB ocr Funktionalitäten

Migration von CIB documentServer 1.8 auf 1.9

1. Die in Client-Anwendungen verwendete CibDocumentServer.jar wird ersetzt durch die neuen .jar Dateien cibdocserv-common-1.9.x.jar, cibdocserv-client-1.9.x.jar.
2. Kompatibilität mit CIB LibreOffice entsprechende freigegebene Versionen für die Konvertierung von LibreOffice kompatibel Dokumentformate nach PDF
3. Neue Funktionalität für die Konvertierung und Verarbeitung von Bildformaten durch CIB image toolbox

Migration von CIB documentServer 1.9 auf 1.10

1. Die in Client-Anwendungen verwendete CibDocumentServer.jar wird ersetzt durch die neuen .jar Dateien cibdocserv-common-1.10.x.jar, cibdocserv-client-1.10.x.jar.
2. Neue Funktionalität für das Tracing von fehlenden Jobs (Maintanance Manager).

Migration von CIB documentServer 1.10 auf 1.11

1. Die in Client-Anwendungen verwendete CibDocumentServer.jar wird ersetzt durch die neuen .jar Dateien cibdocserv-common-1.11.x.jar, cibdocserv-client-1.11.x.jar.
2. Neue Funktionalität für die Erstellung von ZUGFeRD konformen Rechnungen durch das Modul CIB invoice toolbox.
3. Unterstützung durch das Client Framework für CIB invoice toolbox Steps.

Migration von CIB documentServer 1.11 auf 1.12

1. Die in Client-Anwendungen verwendete CibDocumentServer.jar wird ersetzt durch die neuen .jar Dateien cibdocserv-common-1.12.x.jar, cibdocserv-client-1.12.x.jar.
2. Behandlung von unerwerteten Problemen bei der SocketServer Verbindung. Diese Behandlung findet statt durch die Verwendung der Property SocketTimeout. Nachdem die eingegebene Zeit überschritten ist, wird eine entsprechende Fehlermeldung geliefert und der betroffene SocketServer automatisch neugestartet. Diese Behandlung wird duch die Verwendung der Property SocketTimeout und mit dem Einsatz von Java 8 unterstützt

Migration von CIB documentServer 1.12 auf 1.13

1. Die in Client-Anwendungen verwendete CibDocumentServer.jar wird ersetzt durch die neuen .jar Dateien cibdocserv-common-1.12.x.jar, cibdocserv-client-1.13.x.jar.
2. LibreOffice Versionsnummer und mehr Information über Properties für die Kommandos lo-conversion, image-processing und image-conversion wird im Browser-Interface angezeigt.
3. Neue cibjob.xsd Schema v1.6, um Data Nodes für Merge Steps im Xml-Request zu unterstützen.
4. Verbesserung, um SocketServet-Prozesse mit einer Terminierunsnachricht ordentlich zu beenden.
5. Verbesserung im Maintenance Manager Feature, um die erzeugten Requests und Responses als Datei zu speichern.

Migration von CIB documentServer 1.13 auf 1.14

1. Die in Client-Anwendungen verwendete CibDocumentServer.jar wird ersetzt durch die neuen .jar Dateien cibdocserv-common-1.13.x.jar, cibdocserv-client-1.14.x.jar.
2. Sonderkommando „htmltopdf“ wird jetzt unterstützt, um Html-Dateien nach Pdf konvertieren zu können. Dafür wird die Library wkhtmltopdf verwendet.
   Wichtig: Für Linux ist mindestens gclib 2.10 erforderlich

Migration von CIB documentServer 1.14 auf 1.15

1. Die in Client-Anwendungen verwendete CibDocumentServer.jar wird ersetzt durch die neuen .jar Dateien cibdocserv-common-1.14.x.jar, cibdocserv-client-1.15.x.jar.
2. Neue Client Klassen für Steps von Typ
   • format (CIB format)
   • imageprocessing und imageconversion (CIB image toolbox)
   • invtb (CIB invoice toolbox)
   • lo-conversion (LibreOffice powered by CIB)
   • ocr (CIB ocr)
   • pdfjoin und pdfmerge (CIB pdf toolbox)
3. Datei-Entschlüsselung von Dokumenten durch den Befehl lo-conversion (LibreOffice Einbindung)li>

Migration von CIB documentServer 1.15 auf 1.16

1. Die in Client-Anwendungen verwendete CibDocumentServer.jar wird ersetzt durch die neuen .jar Dateien cibdocserv-common-1.15.x.jar, cibdocserv-client-1.16.x.jar.
2. Support für die Logging-Technologie log4j2 (mit Abwärtskompatibiltät mit log4j).

Anleitungen

Für viele bekannte Einsatz-Szenarien sind bereits Anleitungen vorhanden. Diese finden sie im separaten Dokument technischer Leitfaden CIB job. Dort finden Sie allgemeine häufig benötigte Informationen, zum Beispiel, wie Sie nötige Lizenzschlüssel hinterlegen, oder wo Sie Formulare und Textbausteine ablegen. Außerdem wird im CIB job-Leitfaden ein kompletter Aufruf mit dem Framework beschrieben: Auftragsdatei erzeugen, DocumentServer aufrufen, Auftragsergebnisdatei analysieren, Ergebnisdokumente auslesen. Zusätzlich finden Sie dort auch Hilfestellungen für den Entwurf von Auftragsdateien.

Anhang

Ü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

Überblick CIB Module

Beispielaufruf SOAP Webservice mit VB.net

Beispiel-Aufruf Webservice

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#

Beispiel-Aufruf Webservice

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

Beispiel für einen 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>

Beispiel für eine 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>

Fehlercodes der Socketserver

Die angegebenen Rückgabewerte können in den Logs des Application-Servers (Prozessor native CIB socketserver process at localhost:5000x terminated with exit code nnn) sowie gegebenenfalls im socketserver.log abgelesen werden.

Fehlercodes des CIB documentserver

Über die Aufrufschnittstelle des CIB documentServers können folgende Fehlercodes auftreten. Die angegebenen Fehlercodes sind in der XML Response des CIB documentServer enthalten und stammen entweder von CIB job oder aus dem CIB documentServer Java Framework.

Fehlercodes des Servermanagers

Die angegebenen Rückgabewerte werden vom nativen Servermanager ausgelöst, falls dieser zum Einsatz kommt (nicht empfohlen).

WSDL Webservice Description

In diesem Abschnitt ist die WSDL-Datei für die SOAP-Schnittstelle abgebildet.

Die aktuelle Fassung kann jederzeit bezogen werden unter 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 für CIB job ab Version 1.4.x.
       
       (c) CIB software GmbH 2005-2006
       $Revision: 2 $
       
       EINFÜHRUNG:
       Dieses Schema beschreibt formal die XML Struktur des SOAP-Envelope, in das
       CIB job Auftragsdateien sowie Auftragsergebnisdateien eingebettet werden.
       
       BEISPIEL:
       Eine SOAP-Message, um die Operation "generate" auszuführen, enthält außer dem
       Envelope ein Element "Generate", das die Knoten "Comod" und "Data" enthält.
       Die Namespaces sind weggelassen.
 
       <envelope>
             <header/>
             <body>
                    <Generate>
                           <Comod>
                                  <jobs>...</jobs>
                           </Comod>
                           <Data>...</Data>
                    </Generate>
             </body>
       </envelope>
       
       Und die Antwort:
       
       <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">
 
       <!-- Definiere Typen für die Messages -->
       <wsdl:types>
             <xsd:schema
                    targetNamespace="http://www.cib.de/schemas/soap/job/1.1"
                    xmlns:pref="http://www.cib.de/schemas/job/1.1">
                    
                    <!-- Importiere die 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>
                    
                    <!-- Definiere die Struktur der 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>
                    
                    <!-- Diese beiden Elementnamen treten im Body von Request bzw. 
                    Response auf, und haben jeweils ein Comod-Element. -->
                    <xsd:element name="Generate" type="soapjob:Request" />
                    <xsd:element name="GenerateResult" type="soapjob:Response" />
 
             </xsd:schema>
       </wsdl:types>
 
       <!-- Messages der nachher beschriebenen Operation deklarieren. -->
       <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>
 
       <!-- Operation abstrakt deklarieren -->
       <wsdl:portType name="cibjobInterface">
             <wsdl:operation name="generate">
                    <wsdl:input message="soapjob:generateMessage" />
                    <wsdl:output message="soapjob:generateResultMessage" />
             </wsdl:operation>
       </wsdl:portType>
 
       <!-- Operation konkret deklarieren. Wegen use="literal" werden in den SOAP-
       Messages die den Messages zugeordneten Elemente (Generate und ~Result) erwartet. -->
       <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>
       
       <!-- Deklariere den Service zu den konkreten Operationen -->
       <wsdl:service name="CibDocumentServer">
             <wsdl:port binding="soapjob:cibjobBinding"
                    name="cibjobService">
                    <!-- Die implementierende Adresse -->
                    <soap:address location="http://desiderata:8080/CibDocumentServer/soap/Generate" />
             </wsdl:port>
       </wsdl:service>

Lieferumfang

Im Lieferumfang des CIB documentServers sind ein Client- und ein Serverpaket enthalten, die aus folgenden Bestandteilen bestehen:

Clientpaket:

Das Clientpaket enthält unter anderem das CIB documentServer Framework, welches eine Einbindung des CIB documentServers für Java ermöglicht. Sie finden dazu die Javadoc der API sowie Codebeispiele und Beispielaufträge mit Templates

Serverpaket:

Um den CIB documentServer auf einem Server zu installieren, wird das in diesem Paket enthaltene Applikationsarchiv CibDocumentServer.war benötigt. Die mitgelieferten Konfigurationsdateien erleichtern die Konfiguration.