CIB webdesk technischer Leitfaden

1. Einleitung

Dieses Dokument gibt einen Überblick über den Aufbau der Applikation, ihre wichtigsten Komponenten und dient als Leitfaden für Installation, Konfiguration und Betrieb von CIB webdesk.

2. CIB Webdesk im kontext von CIB coSys

CIB webdesk dient im Rahmen von CIB coSys der Erzeugung von Korrespondenzen und deren anschließender Ablage und/oder Ausgabe über verschiedene Ausgabewege wie z.B. den Druck an einem lokalen Arbeitsplatzdrucker oder über eine zentrale Druckstraße im Rechenzentrum.

Der für die Korrespondenzerstellung notwendige Schritt der Datenerfassung zur Versorgung der Dokumentvorlagen mit den jeweils geeigneten Nutzdaten wird ebenfalls von CIB webdesk abgedeckt. Diese Datenerfassung erfolgt in der Regel über eine Reihe von nacheinander abzuarbeitenden Formularen, kann aber auch komplett ohne Benutzerinteraktion über die Dunkelverarbeitungsschnittstelle CIB darkdesk erfolgen. Der Vorgang der Datenerfassung über die Web-Oberfläche wird im Folgenden auch als Datenerfassungsinterview oder schlicht als Interview bezeichnet, wobei beide Begriffe sowohl den Vorgang der Datenerfassung als auch die Menge der dazu verwendeten Masken bezeichnen kann.

3. Grundlegendes zur Architektur

CIB webdesk ist eine Java Application nach Servlet Spezifikation Version 2.6, die für den Betrieb in einem Computercluster ausgelegt ist. Die einzelnen Funktionen der Applikation werden hierbei von Komponenten zur Verfügung gestellt und nach außen über eine Web Service Schnittstelle verfügbar gemacht.

Die Datenhaltung erfolgt mit Hilfe eines relationalen Datenbankmanagementsystems. CIB webdesk verfügt über eine im Web Browser ausgeführte Benutzeroberfläche. Ein großer Teil der Funktionali­tät steht aber über eine mit Hilfe von Web Services implementierte Dunkelverarbeitungs­schnitt­stelle zur Verfügung.

4. Wichtige Komponenten

Es folgt eine Kurzbeschreibung der Komponenten in CIB webdesk. Für Details siehe bitte die entsprechenden JavaDocs der jeweiligen APIs.

4.1. CIB darkdesk

darkdesk Info

DarkdeskInfo stellt Methoden zur Verfügung, um die Version des auf diesem Server installierten CIB webdesk abzufragen.

dardesk Generation

Stellt die Methoden zur Erzeugung und Nachmischen von Dokumenten zur Verfügung. Des Weiteren kann über diese Komponente die Support-Files abgerufen werden.

Die Methoden stehen meist in zwei Formen zur Verfügung: „einfache“ Erzeugung und „mehrfache“ Erzeugung. Die „mehrfache“ Erzeugung stellt die gleiche Funktionalität wie die „einfache“ Erzeugung dar, mit dem Unterschied dass in einem Aufruf mehrere Erzeugungen möglich sind.

Sollen Message Queues zur Verarbeitung genutzt werden, sind die Methoden mit „MQ“ im Namen zu verwenden.

dardesk Search

Die Komponente dient zur Suche nach CIB coSys Objekten wie Vorlagen, Paketen und deren Attributen.

dardesk Security

Über diese Komponente kann ein Benutzer authentifiziert werden.

dardesk FieldSettings

Über diese Komponente können Informationen, wie verwendete Bausteine und deren Variablenfelder von Paketen und Vorlagen abgefragt werden.

4.2. CIB darktom

CIB darktom stellt die Funktionen zur Bearbeitung und Administration von CIB coSys Objekten zur Verfügung.

darktom Core

In dieser Komponente werden die Basisfunktionalitäten bereitgestellt. Es ist möglich, CWPs ein- und aus zu checken, Objekte zu erstellen, zu ändern, zu löschen, zu exportieren und zu suchen.

Des Weiteren kann die Änderungshistorie eines Objekts abgefragt werden.

Diese Komponente dient zur Administration von Mandanten. Es können Mandanten angelegt, gelöscht und „eingefroren“ werden. Der Status der Pilotierung kann für Mandanten gesetzt werden. Zusätzlich ist es möglich, die existierenden Mandanten abzufragen.

darktom Extensions

Über die Komponente „CIB darktom Erweiterungen” können „Zuordnungen“ administriert und gesucht werden. Des Weiteren können darüber die „kundeneigenen Versionsdaten“ administriert werden.

darktom Reference Search

Über diese Komponente können Referenzen zwischen CIB coSys Objekten gesucht werden. Beispielsweise können alle Vorlagen, die einen bestimmten Baustein enthalten, gesucht

4.3. CIB darkdialog

CIB darkdialog stellt die Schnittstelle zu der Restdatenerfassung innerhalb CIB webdesk zur Verfügung. Über die Schnittstellen können Restdatenerfassungen vorbereitet werden, welche der Endbenutzer dann über die Weboberfläche von CIB webdesk aufrufen und bearbeiten kann. Über die Komponente kann dann das vom Endbenutzer abgespeicherte Ergebnis wieder abgerufen werden.

Für weiterführende Informationen, Konzepte und Details siehe Dokumentation „CIB webdesk - Anbindung CIB jrules und CIB webdialog“.

5. Installation

5.1. Einzelschritte zur Installation und Konfiguration

Folgende Schritte werden benötigt, um eine lauffähige CIB webdesk Installation herzustellen:

1. Bereitstellung der Laufzeitumgebung
2. Installation des Webservice Stacks
3. Konfiguration der Java Umgebung
4. Konfiguration Datenbank und Erstellung relevanter Datenbanktabellen
5. Konfiguration des Dateisystems
6. Installation CIB documentserver
7. Konfiguration CIB webdesk
8. Deployment CIB webdesk

5.2. Bereitstellung der Laufzeitumgebung

Zur Installation von CIB webdesk ist es nötig eine geeignete Laufzeitumgebung zur Verfügung zu stellen. Folgende Komponenten werden als Laufzeitumgebung benötigt:

• Java Development Kit (JDK) (Version 1.8). Es wird empfohlen, die 64 Bit Version zu verwenden, damit CIB webdesk mehr RAM nutzen kann. Möglich sind Oracle sowie OpenJDK. Ab Version 4.5.2 werden auch JDK Version 9, 11 und 13 unterstützt.
• Apache Tomcat Servlet Container (Version 8.5 sowie 9.X) oder Oracle Weblogic 12c
• Datenbank (Oracle 12, 18 und 19c)

Die Installation dieser Komponenten ist in der Dokumentation des jeweiligen Produkts erläutert. Zusätzlich sind allerdings einige manuelle Schritte notwendig, um den von CIB webdesk verwendeten Web Service Stack korrekt zu installieren.

Informationen zu aktuell freigegebenen Laufzeitumgebung sind über den CIB Support erhältlich.

5.3. Installation des web service Stacks (Bis Version 4.5.1)

Ab Version 4.5.2 nicht mehr notwendig. Aus bereits gepatchten Application-Servern müssen die JAX-WS Libraries entfernt werden.

CIB webdesk verwendet JAX-WS um Web Services anbieten und konsumieren zu können. Hierbei wird die Referenzimplementierung der JAX-WS verwendet, die kostenlos heruntergeladen werden kann.

Folgende JAX-WS Versionen sind produktiv im Einsatz:

• JAX-WS RI 2.2.6b21
• JAX-WS RI 2.2.8
• JAX-WS RI 2.3.1

Der Download liefert ein ZIP-Archiv mit mehreren Verzeichnissen und Dateien. Entpacken Sie dieses Archiv in ein beliebiges Verzeichnis auf Ihrer Festplatte und führen Sie anschließend die folgenden Schritte aus.

        1.      Kopieren Sie sämtliche JAR-Dateien aus dem Verzeichnis JAXWS_UNZIP_DIR/jaxws-ri/lib in das Verzeichnis CATALINA_HOME/shared/lib

        2.      Bearbeiten Sie die Datei CATALINA_HOME/conf/catalina.properties mit einem beliebigen Texteditor. Suchen Sie nach der Zeile die mit der Zeichenkette „shared.loader=“ beginnt.

         ${catalina.base}/shared/lib,${catalina.base}/shared/lib/*.jar,${catalina.home}/shared/lib,${catalina.home}/shared/lib/*.jar

Hierbei bezeichnet der Platzhalter JAXWS_UNZIP_DIR das Verzeichnis, in welches Sie die JAX-WS Referenzimplementierung entpackt haben. CATALINA_HOME bezeichnet das Installationsverzeichnis von Apache Tomcat.

Informationen zu aktuell freigegebenen JAX-WS-RI Version sind über den CIB Support erhältlich.

5.4. Installation des Datenbanktreibers

Der Datenbanktreiber kann direkt bei Oracle heruntergeladen werden. Der Einsatz der Die aktuellste Version für JAVA 8, ojdbc8.jar, wird empfohlen. Informationen zu aktuell freigegebenen OJDBC Version sind über den CIB Support erhältlich.

Die JAR kann der JAX-WS Libraries in das Verzeichnis CATALINA_HOME/shared/lib kopiert werden. Siehe Vorgehen in 2 Installation des Webservice Stacks beschrieben.

5.5. Konfiguration der Java Umgebung

Es wird empfohlen, folgende Einstellungen an der Java Virtual Machine, in der der Apache Tomcat läuft, vorzunehmen. Details zu den Einstellungen siehe Oracle Dokumentation.

Ab webdesk Version 4.5.2 nicht mehr unterstützt:

5.6. Konfiguration Datenbank

Allgemein

CIB webdesk benötigt eine Datenbank für den Betrieb. Die Installation eines relationalen Datenbankmanagementsystems wird an dieser Stelle übersprungen, da dies außerhalb des Rahmens dieses Dokuments liegt. Ein solches System steht in vielen Fällen bereits zur Verfügung oder muss entsprechend der zughörigen Dokumentation separat installiert werden.

Dazu sind mehrere Informationen aus dieser Dokumentation zu berücksichtigen, die in den folgenden Abschnitten aufgeführt sind (siehe „Datenbank-Zeichensatz“ und folgende).

Im Hinblick auf CIB webdesk ist letztlich das Anlegen des von CIB webdesk benötigten Datenbankschemas und der relevanten Tabellen vorzunehmen und die Anpassung der Konfigurationsdatei von CIB webdesk durchzuführen.

Zur Anlage der Tabellen sind jeweils aktuelle SQL-Skripten zu verwenden. Diese können über den CIB Support angefordert werden.

Für die Installation der SQL-Skripte und für den Betrieb müssen die Rechte

• create or replace view
• create or replace TRIGGER
• create sequence
• create index

dem Datenbankbenutzer hinzugefügt werden.

Datenbank-Zeichensatz

Characterset                             AL32UTF8 (Oracle)

Im Umfeld PostgreSQL wird UTF-8 verwendet.

Diese Zeichensätze sind fest in der DB definiert und können in der Regel nicht nachträglich geändert werden.

Benutzte DB-Optionen

Es sind keine besonderen Optionen bekannt oder vereinbart.

Datenbankbenutzer

CIB webdesk benötigt genau einen technischen Datenbankbenutzer. Der Datenbankbenutzer benötigt mindestens folgende Rechte:

• Lesen der CIB webdesk Datenbanktabellen (SELECT)
• Schreiben der CIB webdesk Datenbanktabellen (UPDATE, INSERT, DELETE)
• Es wird empfohlen, keine diesem Benutzer Speicherbegrenzung („Quota“) zuzuordnen.

Datenbanktabellen

Konfiguration der Datenbankverbindung

Die Datenbankverbindung wird über eine Reihe von Parametern konfiguriert, die in der Datei webdesk.properties zu finden sind.

Details dazu finden Sie im Kapitel Datenbank.

5.7. Konfiguration Dateisystem

CIB webdesk sowie die nativen CIB Module arbeiten auch auf Dateisystemebene. Dabei dürfen keine UNC-Pfade zum Einsatz kommen. Sollte ein nicht auf dem Server befindliches Dateisystem genutzt werden, muss die Einbindung des Dateisystems derart erfolgen, dass für die Installation von CIB webdesk und CIB documentServer das Dateisystem wie das lokale Dateisystem angesprochen werden kann.

Beispielsweise müssen Network File Systeme unter einem Linux direkt gemountet werden. UNC Pfade unter Windows sind nicht erlaubt. (z.B. „\\docserv\jobs“).

Es muss sichergestellt sein, dass die Verzeichnisse existieren, die in der Konfiguration von CIB webdesk (siehe Beschreibung unter „Platzhalter & Pfade“) sowie der Logdatei Konfiguration eingestellt sind, bevor CIB webdesk ausgeführt wird. CIB webdesk legt diese Verzeichnisse nicht selbständig an sondern protokolliert ihr Fehlen im Log. Bei Fehlen der Verzeichnisse kann CIB webdesk nicht ordnungsgemäß starten oder es treten bei Verwendung Fehler auf.

Wichtiger Hinweis zu dem Zusammenspiel CIB webdesk und CIB documentServer:

Bestimmte Pfade bzw. Verzeichnisse müssen zwingend von CIB webdesk und CIB documentServer gleichermaßen erreichbar sein. Erkennbar sind die Verzeichnisse anhand der Namen in der Konfiguration von CIB webdesk. Endet der Parametername eines Konfigurationsparameters auf „FromDocumentServerView“, so handelt es sich dabei um ein Verzeichnis, das von CIB webdesk und CIB documentServer für den Datenaustausch genutzt wird. Damit können die Verzeichnisse aus beiden Perspektiven unterschiedlichen montiert sein (mount point) und die Module auf getrennten Maschinen betrieben werden.

Beispiel: „superFolder“ und „superFolderFromDocumentServerView“.

Beispiel A

CIB webdesk und CIB documentserver laufen auf der gleichen Instanz, z.B. innerhalb derselben Tomcat-Instanz bzw. auf einem System: Es kann direkt ein Verzeichnis konfiguriert werden:

Beispiel B

CIB webdesk und CIB documentServer laufen auf unterschiedlichen Instanzen in getrennten Systemen: Es muss sichergestellt werden, dass die Verzeichnisse zwischen den Instanzen bzw. Systemen erreichbar sind. Beispielsweise kann ein Network File System genutzt werden, welches auf den Instanzen von CIB webdesk und CIB documentServer unterschiedlich montiert wird.

Gegeben ist ein zentrales NFS „nfsmount“.

Instanz A, CIB webdesk: NFS gemounted nach „/var/webdesk/nfsmount“

Instanz B, CIB documentserver: NFS gemounted nach „/var/documentserver/nfsmount“

Daraus ergibt sich die Konfiguration des CIB webdesk:

So kann für unterschiedliche, getrennte CIB webdesk-Instanzen ein gemeinsamer CIB documentServer genutzt werden.

5.8. Installation CIB Documentserver

Damit CIB webdesk Dokumente erstellen kann, benötigt CIB webdesk den CIB documentServer. Zur Installation dieser Webapplikation siehe „Technischer Leitfaden CIB documentServer“.

6. Konfiguration CIB webdesk

CIB webdesk benötigt pro Instanz, bzw. Knoten eines Clusters, eine eigene Konfiguration. Beim Deployment von CIB webdesk muss die Konfiguration des CIB webdesk eingestellt werden.

6.1. Funktionsweise der Konfiguration

Allgemein

CIB webdesk wird mit Hilfe einer beim Start der Webapplikation eingelesenen Properties-Datei konfiguriert, welche im ausgelieferten WAR-Archiv enthalten ist.

Die CIB webdesk Properties Datei kann an folgenden Orten abgelegt werden

• Im Classpath
• Im „user.home“ Verzeichnis
• In einem beliebigen Verzeichnis, das über die Tomcat Aufrufparameter (z.B. in /etc/default/tomcat8 oder in CATALINA_HOME/bin/setenv.sh) „-DWBD_CONFIG_DIR“ gesetzt werden kann

CIB webdesk verfügt über einen Plugin-Mechanismus, der es erlaubt, die Applikation mit einer eigenen Komponente zu erweitern, die sich in den Einlesevorgang der Konfigurationsdatei einklinkt und beliebige Konfigurationsschlüssel übersteuert. Alternativ kann die im WAR enthaltene Konfigurationsdatei vor dem Deployment manuell oder per Skript angepasst werden.

Das Plugin-Konzept von CIB webdesk

Grundsätzlich werden dafür nur Standardmechanismen für Web-Applikationen genutzt.

Intern verwendet CIB webdesk das Spring Framework, das auch für die Implementierung des Plugin-Mechanismus verwendet wurde. Ein Plugin für CIB webdesk besteht daher mindestens aus einer Spring Konfigurationsdatei, in welcher Beans definiert werden, die vom Spring Framework beim Startup der Applikation automatisch erzeugt werden. In der Regel beinhaltet ein Plugin außerdem eigene Klassen, die in einem JAR-Archiv bereitgestellt werden können.

Die Konfigurationsdatei des Plugins ist eine XML-Datei, deren Dateiname auf „-config.xml“ enden muss. Sie muss zudem in das Verzeichnis WEB-INF/plugins unterhalb des Deployment-Verzeichnisses von CIB webdesk kopiert werden. In dieser Datei werden Beans definiert, die dann bei Initialisierung der Webapplikation vom Spring Framework instanziiert werden. Ein Beispiel für eine einfache Bean-Definition kann dem folgenden Listing entnommen werden.

<?xml version="1.0" encoding="UTF-8"?>
<!--  SPRING CONFIG -->
<beans xmlns="http://www.springframework.org/schema/beans"

       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:context="http://www.springframework.org/schema/context"
       xsi:schemaLocation="http://www.springframework.org/schema/beans 
            http://www.springframework.org/schema/beans/spring-beans-2.5.xsd 
            http://www.springframework.org/schema/context
            http://www.springframework.org/schema/context/spring-context-2.5.xsd">

       <bean class="com.example.MyBeanClass" scope="singleton">
            <property name="foo" value="bar" />
      </bean>
</beans>
Diese Konfiguration erzeugt beim Hochfahren
des Spring Application Context, was bei der Initialisierung von CIB webdesk
geschieht, ein Objekt vom Typ com.example.MyBeanClass und setzt die Property
„foo“ dieser Bean auf den Wert „bar“. Der Wert „singleton“ des scope-Attributs
legt dabei fest, dass die Bean nur einmal im Application Context abgelegt wird
und alle Anfragen auf die Bean dieselbe Instanz zurückliefern.

Eine umfassende Erläuterung würde den Rahmen dieses Dokuments sprengen. Es sei deshalb auf die Dokumentation des Spring Frameworks verwiesen.

Wenn CIB webdesk Plugin-spezifische Klassen beinhalten soll, müssen diese in einem JAR-Archiv im Verzeichnis WEB-INF/lib unterhalb des Deployment-Verzeichnisses von CIB webdesk zur Verfügung gestellt werden. Um das Beispiel aus dem obigen Listing aufzugreifen, müsste hier also ein JAR-Archiv bereitgestellt werden, welches (mindestens) das Paket com.example und darin die Klasse MyBeanClass enthält.

Wichtig: Achten Sie darauf, dass die in der XML-Konfiguration definierten Properties Ihrer Beans korrekt geschrieben und öffentlich (public) sichtbar sind. Wenn die Konfiguration fehlerhaft ist, kann CIB webdesk nicht ordnungsgemäß gestartet werden.

Einsteuern von Konfigurationseigenschaften mit Hilfe eines Plugins

Ein Plugin zur Einsteuerung von externen Konfigurationsparametern in CIB webdesk muss eine Bean im Singleton-Scope ablegen, die das Interface de.cib.webdesk.configuration.application.ExternalConfigPlaceholderResolver implementiert. Dieses Interface definiert eine einzige Methode namens resolvePlaceholder, die einen Wert für einen als Parameter übergebenen Schlüssel zurückliefert. So kann ein Plugin entwickelt werden, das z.B. Werte aus einem externen Web Service oder einer Konfigurations­Datenbank zurückliefert.

6.2. Konfigurationsparameter

Im Folgenden werden die wichtigsten Konfigurationsparameter für CIB webdesk beschrieben. Erforderliche Konfigurationsparameter, die nicht über einen direkt verwendbaren Default-Wert verfügen sind hierbei farblich gekennzeichnet.

Allgemeine Parameter

Datenbank

Vorlagencache

Cleaning (DB und Festplatte)

CIB documentServer

Platzhalter & Pfade

Restdatenerfassung

Beispiel:

webdialog.sessionCleaning.age: 24:00:00
webdialog.sessionCleaning.maxNumberEntries: 100 
webdialog.sessionCleaning.beginTime: (leer)
webdialog.sessionCleaning.endTime: (leer)
webdialog.sessionCleaning.frequency: 00:15:00 

Job löscht kontinuierlich Einträge die älter als 24 Stunden sind; alle viertel Stunde 100 Zeilen aus der Tabelle.

PDF-Erstellung

Darkdesk-Benachrichtigungen

Serienbrief-Erstellung

Verschiedenes

6.3. Konfiguration Logging

Im Regelfall wird die Konfiguration des Loggings von CIB software GmbH mitgeliefert. CIB webdesk nutzt ab Version 4.5.2 Log4j2 zum Loggen von Nachrichten in Log-Dateien.

Die Konfiguration der zu schreibenden Log-Dateien muss durch den Kunden in dieser Datei angepasst werden.

Im Folgenden ein Beispiel der Log4j2 Konfiguration des CIB webdesk:

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="WARN">
       <Properties>
             <Property name="defaultFormat">%5p %d{dd.MM.yy HH:mm:ss} [%t] [%c] %m%n</Property>
             <Property name="logDir">${sys:catalina.base}/logs</Property>
       </Properties>
       <Appenders>
             <Console name="console" target="SYSTEM_OUT">
                    <PatternLayout pattern="${defaultFormat}" />
             </Console>
             <File name="webdesk" fileName="${logDir}/webdesk.${date:yyyy-MM-dd}.log">
                    <PatternLayout pattern="${defaultFormat}" />
             </File>
       </Appenders>
       <Loggers>
             <Logger name="de.cib.webdesk" level="WARN" additivity="false">
                    <AppenderRef ref="console" />
                    <AppenderRef ref="webdesk" />
             </Logger>
             <Logger name="de.cib.darkdesk_1_0_0" level="WARN" additivity="false">
                    <AppenderRef ref="console" />
                    <AppenderRef ref="webdesk" />
             </Logger>
             <Logger name="de.cib.darkdesk_1_5_0" level="WARN" additivity="false">
                    <AppenderRef ref="console" />
                    <AppenderRef ref="webdesk" />
             </Logger>
             <Logger name="de.cib.darkdesk_1_6_0" level="WARN" additivity="false">
                    <AppenderRef ref="console" />
                    <AppenderRef ref="webdesk" />
             </Logger>
             <Logger name="de.cib.darktom_1_0_0" level="WARN" additivity="false">
                    <AppenderRef ref="console" />
                    <AppenderRef ref="webdesk" />
             </Logger>
             <Logger name="de.cib.darktom_1_5_0" level="WARN" additivity="false">
                    <AppenderRef ref="console" />
                    <AppenderRef ref="webdesk" />
             </Logger>
             <Logger name="de.cib.darkdialog_1_0_0" level="WARN" additivity="false">
                    <AppenderRef ref="console" />
                    <AppenderRef ref="webdesk" />
             </Logger>
             <Logger name="de.cib.darkdialog" level="WARN" additivity="false">
                    <AppenderRef ref="console" />
                    <AppenderRef ref="webdesk" />
             </Logger>
             <Logger name="de.cib.rules" level="WARN" additivity="false">
                    <AppenderRef ref="console" />
                    <AppenderRef ref="webdesk" />
             </Logger>
             <Logger name="de.cib.webdialog" level="WARN" additivity="false">
                    <AppenderRef ref="console" />
                    <AppenderRef ref="webdesk" />
             </Logger>
             <Logger name="performance" level="WARN" additivity="false">
                    <AppenderRef ref="console" />
                    <AppenderRef ref="webdesk" />
             </Logger>
             <Logger name="de.cib.webdesk.jaxwshandler.SoapCallLoggingHandler" level="WARN" additivity="false">
                    <AppenderRef ref="console" />
                    <AppenderRef ref="webdesk" />
             </Logger>
             <Logger name="de.cib.webtom" level="WARN" additivity="false">
                    <AppenderRef ref="console" />
                    <AppenderRef ref="webdesk" />
             </Logger>
             <!-- Silence unwanted 3rd-party logging -->   
             <Logger name ="org.hibernate.event.def.AbstractFlushingEventListener"
level="INFO" additivity="false"/>
             <Logger name ="org.hibernate.util.JDBCExceptionReporter" level="INFO" additivity="false"/>
             <Root level="ERROR">
                    <AppenderRef ref="console" />
             </Root>
       </Loggers>
</Configuration>

6.4. Wertetabellen

Allgemein

CIB webdesk bietet die Möglichkeit verschiedene Eigenschaften in der Oberfläche per Wertetabellen zu konfigurieren. Dies sind insbesondere die unter 7.4.1 Konfigurierbare Wertetabellen aufgeführten Wertetabellen für die Vorbelegung von Auswahlfeldern (ComboBox) in CIB webdesk Interview-Masken. Es sei angemerkt, dass sich Eigenschaften nicht nur auf die Oberfläche auswirken können, sondern auch auf die interne technische Repräsentation sowie die Verarbeitung.

Aus diesem Grund sollten Änderungen mit Vorsicht durchgeführt werden. Es wird abgeraten zusätzliche Werte hinzuzufügen. Die Spaltennamen in den Wertetabellen dürfen nicht verändert oder entfernt werden.

Verkleinerung oder Ändern der Initialmenge (Entfernen, Umbenennung von Einträgen) ist in der Regel unproblematisch möglich.

Die Einstellungen aus CIB webTom werden beim Laden einer Vorlage für ein Interview in CIB webdesk ausgewertet. Daher ist bei Änderungen zu bedenken, dass Eingabefelder die im CIB webTom für die Vorlagenadmi­nistration genutzt werden, dort identisch konfiguriert sind (identisch Auswahlmenge mit übereinstimmenden IDs – weitere Details dazu sind in Technischer Leitfaden CIB webTom). Sind in CIB TOM Auswahlen möglich, die in CIB webdesk nicht vorgesehen sind, wird die Auswahl in der Regel auf einen verfügbaren Wert (i.d.R. erster) oder leer eingestellt.

Will man zu einem späteren Zeitpunkt Auswahlmöglichkeiten entfernen oder überarbeiten, ist zu bedenken, dass Entwürfe und noch nicht abgeschlossene Dokumente diese Daten enthalten können. Hier kann es zu unerwarteten Situationen kommen, da CIB webdesk in der Regel davon ausgeht, dass dieser Wert nicht mehr zu verwenden ist und die Einstellung beim Zugriff (d.h. Laden eines Entwurfs oder Dokuments) ohne weiteren Hinweis auf einen gültigen Auswahlwert oder eine leere Auswahl umstellt.

In bestimmten Fällen kann es notwendig sein weitere Konfigurationsdateien anzupassen. Dies trifft insbesondere auf Konfigurationsdateien für die Nachverarbeitung zu, da die Auswahlwerte aus CIB webdesk (z.B. Archivschlüssel) zusammen mit dem Dokument abgelegt und an die Nachverarbeitung weitergereicht werden.

Die Wertetabellen finden sich im Verzeichnis WEB-INF/valuetables, die Namen haben das Format cib_ref_[name].csv.  Die Tabellen liegen in dem Format CSV (comma separated values) vor und lassen sich mit einem beliebigen Texteditor bearbeiten. Das Character-Encoding ist UTF-8.

Es wird zwischen Einzel- und Multiwerttabellen unterschieden. Einzelwerttabellen bilden eine einfache Primärschlüssel-Wert Beziehung ab. Multiwerttabellen bieten die Möglichkeit zu einem Primärschlüssel mehrere Werte anzugeben. Die Konfiguration der Multiwerttabellen wird in der korrespondierenden cib_ref_[name].properties vorgenommen.

Wertetabellen, die im Weiteren nicht aufgeführt sind, werden ausschließlich intern durch CIB webdesk genutzt und sollten auf keinen Fall verändert werden.

Konfigurierbare Wertetabellen

Die folgende Liste führt die Wertetabellen auf, die bei Bedarf angepasst werden können:

• cib_ref_envelopeType.csv                    Briefumschlagsart
• cib_ref_letterType.csv                           Briefart
• cib_ref_paperWeight.csv                      Papiergewicht
• cib_ref_shippingNote.csv                     Versandvermerk
• cib_ref_shippingType.csv                     Versandart
• cib_ref_forwardRule.csv                       Vorausverfügung
• cib_ref_branchOfficeSource.csv          Ansprechpartnerdaten

Es handelt sich um die entsprechenden Auswahlfelder (Combobox) im webdesk.

Beispiele für Wertetabellen

Nachfolgend sind je ein Beispiel für eine Einzelwerttabelle und eine Multiwerttabelle aufgeführt.

Einzelwertabelle:

cib_ref_shippingType.csv
ID;VALUE
-;---
0;Einschreiben
1;Einschreiben mit Rückschein 
2;SB-Einschreiben
3;Übergabeeinschreiben
4;Einschreiben Einwurf
5;Einschreiben eigenhändig
6;Expressbrief 

Diese Tabelle steuert den Inhalt der ComboBox „Versandart“ im Reiter „Empfänger“ im Interview.

Multiwertabelle:

cib_ref_letterType.csv

ID;SORT_INDEX;VALUE;COST;BASE_WEIGHT;FACTOR
1;1;Brief Standard;0.58;0;0
2;2;Brief Kompakt;0.90;0;0
3;3;Brief Gross;1.45;0;0
4;4;Infopost Standard;0.25;0;0
5;5;Infopost Kompakt;0.28;20;0.352
6;6;Infopost Gross;0.36;20;0.352

 Diese Tabelle steuert den Inhalt der Combobox  „Papiergewicht“  für den zentralen Druck und Postversand im Reiter „Dokumenterstellung“ im Interview. Hierfür werden die Spalten ID und VALUE verwendet. Die weiteren Werte werden bei der Berechnung der erwarteten Portokosten eines Serienbriefs verwendet.

Hinweis: Werte aus dieser Tabelle werden in der Nachverarbeitung verwendet, wobei nur die IDs durchgereicht werden Eine Änderung auf CIB webdesk Seite erfordert zumindest eine Überprüfung der Konfiguration bzw. des Verhaltens in der Nachverarbeitung – ggf. sind dort ebenfalls Konfigurationsänderungen notwendig.

6.5. URL-Parameter

Allgemein

Das Verhalten von CIB webdesk kann durch eine Reihe von URL-Parametern festgelegt werden. Die Namen dieser Parameter sind konfigurierbar, um eine nahtlose Integration in das Kundenumfeld und etwaige Namenskonflikte zu vermeiden. Die Namen der verfügbaren URL-Parameter können in der Datei urlParametersMapping.properties im Verzeichnis WEB-INF/properties eingetragen werden.

Hinweis: Bitte beachten Sie, dass Sie in der Datei urlParametersMapping.properties nicht die Werte der jeweiligen Parameter bearbeiten können, sondern die Namen dieser Parameter. Wenn Sie also zum Beispiel in dieser Datei folgende Zeile eintragen

j_username=webdeskUsername

so hat dies zur Folge, dass Der Benutzername für den direkten Login in CIB webdesk spezifiziert werden kann, indem man in der Adresszeile den URL-Parameter webdeskUsername angibt.

Anmeldung

Vorbelegung Datensevice-Eingabefelder

Abhängig vom jeweiligen Kundenoverlay.

Kundenoverlay GAD und Präsentationssystem

WS-Plugin Klasse „de.gad.services.GAD_KorrespondenzDatenVerwalterPOJOIF“

Kundenoverlay cosys4cib

WS-Plugin Klasse „de.cib.webdesk.cibac.data.CIBACDataConnector“

Kundenoverlay LHM

WS-Plugin Klasse „de.cib.webdesk.services.dataproviders.LHMLDAPDocumentDataProvider“

Vorlagenauswahl und Interviewaktionen

„j_first_tab“ und „j_first_tab_selector“

• j_first_tab entspricht dem CIB webTom-Parameter "Erster Reiter".
• Mit j_first_tab_selector kann gesteuert werden, ob die CIB webTom oder der URL-Parameter verwendet wird. Dabei verstehen wir unter CIB webTom-Parameter, die Parameter die an der Vorlage hinterlegt sind.
• Wird j_first_tab nicht gesetzt, entspricht dies dem CIB webTom-Parameter "Informationen zur Vorlage".
• Für j_first_tab_selector können folgende Werte definiert werden:
• tom ist der Standardwert und verwendet die Parameter der Vorlage
• url verwendet die übergebenen Parameter
• Sind beide Parameter nicht gesetzt, entspricht dies dem aktuellen Verhalten, wenn im CIB webTom kein Wert gesetzt ist.
• Daraus ergeben sich folgende, für diesen Anwendungsfall relevante Beispiele: 

Beschreibung der Werte für den URL-Parameter j_first_tab:

Anpassung der Oberfläche

Einsprung in Entwurf, Workflow, Wiedervorlage

Einsprung in CIB doXiview

Aktivierung Techadmin Funktion

Diese Feature ist aus Sicherheits- und Datenschutzgründen deaktiviert!

7. Betrieb

7.1. Deployment des CIB webdesk

Da CIB webdesk die Konfiguration jeweils innerhalb des von CIB software GmbH bereitgestellten WAR Files mitbringt, muss bei dem Deployment auf die jeweilige Apache Tomcat die Konfiguration angepasst werden. Auch bei Nutzung des „Plugin Konzepts“ muss die von CIB Software GmbH gelieferte WAR Datei vom Kunden selbst angepasst werden.

Im Folgenden wird ein allgemeines, beispielhaftes Vorgehen des Deployments beschrieben. Je nach Umgebung bei Kunden kann das automatische Deployment angepasst sein oder auf andere Art und Weise von statten gehen.

Für das Deployment sind folgende Schritte notwendig:

1. Lieferung einer WAR bzw. ZIP Datei durch CIB software GmbH
2. Gegebenenfalls Anpassungen des Kunden-Deployment-Systems, der Konfiguration, der Kunden-Plugins oder der Umgebung. Die notwendigen Anpassungen werden im Normalfall durch CIB software GmbH in bei der Freigabe der CIB webdesk Version kommuniziert.
3. Einstellung der CIB webdesk Version in das Kunden-Deployment-System
4. Anpassung des WAR Files durch das Kunden-Deployment-System, beispielsweise:
1. Auspacken der WAR Datei
2. Anreicherung der kundenspezifischen Plugins durch kopieren der entsprechenden Konfigurationsdateien nach „/WEB-INF/plugins“ und der benötigten Libraries nach „/WEB-INF/lib“ (Siehe Kapitel „Das Plugin-Konzept von CIB webdesk“)
3. Anpassung der webdesk.properties Datei falls das Plugin Konzept nicht genutzt wird
5. Gegebenenfalls Undeployment der alten CIB webdesk Version, falls eine Version bereits im Einsatz ist
6. Herunterfahren der jeweiligen Servlet Containers
7. Aufspielen des CIB webdesk auf den Servlet Container
8. Starten des Servlet Containers durch das entsprechende Skript

Undeployment und Deployment sind abhängig von der Umgebung des Kunden und des eingesetzten Servlet Containers. Beispielsweise je nach Einstellungen der Apache Tomcat muss CIB webdesk unterschiedlich in die Apache Tomcat deployed werden. Ist „Autodeployment“ konfiguriert, genügt es, die WAR Datei direkt in den webapps Ordner zu kopieren. Andernfalls kann auch direkt das entpackte WAR-File im Apache Tomcat eingespielt werden.

Hinweis zu Apache Tomcat: Es wird nicht empfohlen, das automatische Redeployment zur Laufzeit über den Tomcat-Manager zu verwenden, da dies zu einem inkonsistenten Zustand der CIB webdesk Instanz führen kann.

7.2. Monitoring des CIB webdesk

Ping

Beim Kunden-Deployment kann in den Hauptordner des CIB webdesk eine entsprechende HTML-Datei hinterlegt werden, die von der Überwachung periodisch aufgerufen werden kann. Damit kann die grundsätzliche Erreichbarkeit des CIB webdesk im erwarteten Kontext geprüft werden.

Log-Dateien

CIB webdesk nutzt „Log4j2“ (Siehe Kapitel Konfiguration Logging) zum Loggen von Nachrichten in Log-Dateien.

Folgende Dateien werden im Regelfall geschrieben:

• webdesk-<Datum>.log
• Logdateien des verwendeten Web-Containers entsprechend Konfiguration (z.B. catalina.out bei Tomcat als Standard-Logdatei unterhalb des Verzeichnis logs)
  

Mittels individueller Log4j2- Konfiguration können die Log-Dateien an die spezifischen Erfordernisse angepasst werden.

Die Log-Dateien können automatisiert ausgewertet werden. Siehe dazu Abschnitt „Beschreibung wichtiger Log-Einträge“.

7.3. Melden von Fehlern

CIB webdesk und die weiteren CIB Produkte benötigen einen Service- und Wartungsvertrag. Bei Fragen dazu steht support@cib.de zur Verfügung.

Potentielle Fehler können in den CIB helpdesk http://helpdesk.cib.de eingestellt werden. Sollte kein Benutzer zur Verfügung stehen, steht der CIB support per E-Mail support@cib.de oder Telefonisch (siehe www.cib.de ) zur Verfügung.

• Folgende Informationen werden zur Bearbeitung des Fehlers benötigt:
• Version des CIB webdesk
• Versionen der Laufzeitumgebung des CIB webdesk
• Namen der verwendeten Komponenten (Datenbank, Servlet Container etc.)
• Beschreibung der Handlungsfolge
• Zeitpunkt des Fehlers
• Log-Dateien des CIB webdesk
• Gegebenenfalls weitere Dateien und Informationen, um den Fehler nachstellen zu können wie RTF-Dateien.
• Gegebenenfalls Screenshots des Fehlers wenn in der CIB webdesk Oberfläche. Wenn möglich, den gesamten sichtbaren Bereich auf dem Screenshot unterbringen.
• Ansprechpartner auf Kundenseite, der für Rückfragen zur Verfügung steht

7.4. Beschreibung wichtiger Log-Einträge

Verschiedene Fehlersituationen finden sich in der Log-Datei als Java-Exceptions wieder.
Ein Eintrag entspricht dabei dem folgenden Muster:

ERROR … :Exception occured (oder andere Meldung)
ERROR … : vollqualifizierter Name der Exception …
ERROR … : mehrzeiliger Stacktrace mit Methodennamen und Zeilennummern
ERROR … : Caused by: Gekapselte Exception
ERROR … : mehrzeiliger Stacktrace mit Methodennamen und Zeilennummern

Es folgt eine Beschreibung besonderer Exceptions nach denen die Logdatei durchsucht werden können um Probleme in der technischen Infrastruktur oder beim Zusammenspiel der einzelnen Komponenten automatisiert zu erkennen. Die Meldungen bei den gekapselten Exceptions geben typischerweise genaueren Hinweis auf die konkrete Ursache.

Nachfolgende eine Liste von Exceptions, die im Regelbetrieb in der Logdatei auftreten können – typischerweise aber kein technisches Problem indizieren:

Andere Exceptions in den Logs deuten auf Fehler in der Fachlichkeit hin und müssen bei Auftreten durch CIB geprüft werden.

7.5. Temporäre Dateien und Bereinigung des Dateisystems

CIB webdesk verwendet Dateien bei unterschiedlichen Funktionen. Diese Dateien werden teils von automatisierten Lösch-Jobs periodisch entfernt, teils muss die betreibende Instanz selbst für die Bereinigung der entsprechenden Daten sorgen, da die Entscheidung, welche Daten wann gelöscht werden können nicht von der CIB als Produktanbieter, sondern nur vom Kunden als Integrator getroffen werden kann.

Folgende Daten werden automatisch bereinigt (per Konfiguration einzeln deaktivierbar):

• Jobs-Verzeichnis: Die für die Dokumenterzeugung benötigten Artefakte werden von CIB webdesk in dynamisch erzeugten Unterverzeichnissen des Jobs-Verzeichnisses abgelegt, welches durch den Konfigurationsparameter webdesk.jobPath bestimmt wird. Pro Dokumenterzeugungsauftrag wird hierbei ein Verzeichnis angelegt, in dem dann unter anderem die Eingabedateien für die Dokumenterzeugung, aber auch Zwischen- und Endergebnis abgelegt werden.
  Die Konfigurationsparameter webdesk.cleanJobs bzw. darkdesk.cleanJobs können genutzt werden, um festzulegen, nach welchem Zeitraum ein Job-Verzeichnis gelöscht werden soll.
  Hierbei ist zu beachten, dass CIB webdesk in keinem Fall das Job-Verzeichnis eines noch in Bearbeitung befindlichen Jobs löscht.
Die Konfigurationsparameter webdesk.cleanJobs bzw. darkdesk.cleanJobs können genutzt werden, um festzulegen, nach welchem Zeitraum ein Job-Verzeichnis gelöscht werden soll.
Hierbei ist zu beachten, dass CIB webdesk in keinem Fall das Job-Verzeichnis eines noch in Bearbeitung befindlichen Jobs löscht.

• jview Temp: CIB webdesk lädt CIB jView Dateien für die Verarbeitung nicht vollständig in den Hauptspeicher. Stattdessen werden diese Dateien in einem temporären Verzeichnis im Dateisystem des Servers abgelegt und dann gepuffert verarbeitet um die Hauptspeicherlast so gering wie möglich zu halten. Der Konfigurationsparameter webdesk.cleanJobs wird auch herangezogen, um zu bestimmen, wann die Dateien im jView Temp Verzeichnis gelöscht werden.
• Sequence Tracking Daten: Im Transaction Cache Verzeichnis sammelt CIB webdesk zu Supportzwecken die Daten, die im Rahmen einer Dokumenterzeugungssequenz entstehen. Eine solche Sequenz beginnt mit der Erfassung der Daten und endet mit der Generierung des Ergebnisdokuments. Da es sich bei diesen Daten um Support-Daten handelt, ist es nicht sinnvoll, diese Daten länger aufzuheben als zu Supportzwecken nötig ist. Aus diesem Grund werden auch die Sequence Tracking Daten periodisch automatisch gelöscht. Das maximale Dateialter wird hierbei über den Konfigurationsparameter webdesk.transactionTracking.autoClean.fileAge festgelegt.
• Content Cache: CIB webdesk verfügt über einen Dateisystem-basierten Cache Mechanismus, der große Objekte zur Schonung des Hauptspeichers im lokalen Dateisystem des Servers vorhält. Das Verzeichnis, in dem diese Cache-Komponente die von ihr benötigten Dateien ablegt, wird jeweils beim Hochfahren von CIB webdesk automatisiert geleert.

Ferner gibt es eine Reihe von Verzeichnissen, deren Inhalt nach Ermessen des Betriebs regelmäßig gelöscht werden sollten. Es handelt sich dabei um die folgenden Verzeichnisse:

• Support Repository: Die im Support Repository im Fehlerfall abgelegten Dateien sollten gelöscht werden, wenn sie nicht mehr benötigt werden.
• Repository-Verzeichnis: Kommt die Dokumentfreigabe-Komponente von CIB webdesk zum Einsatz, so sollten die im Repository-Verzeichnis abgelegten Dateien nach erfolgreicher Nachverarbeitung gelöscht werden.
• wbd_shared: Die Dateien, die beim Upload von Eingabedateien über die Web-Oberfläche von CIB webdesk im wbd_shared-Verzeichnis abgelegt werden, sollten regelmäßig gelöscht werden.
• Package-Verzeichnis: Im Package-Verzeichnis legt CIB webdesk den Inhalt der Pakete ab, aus denen sich eine Dokumentvorlage zusammensetzt. Da Änderungen an den Paketen (bzw. den darin enthaltenen Bausteinen) alte Paketversionen obsolet machen können, empfiehlt es sich, dieses Verzeichnis regelmäßig zu leeren.
• Webdialog Repositories: In diesem Verzeichnis werden die Artefakte abgelegt, die von CIB webdialog benötigt werden. Auch sie werden möglicherweise obsolet, wenn eine Dokumentvorlage oder ihre Pakete bearbeitet werden. Aus diesem Grund sollte auch dieses Verzeichnis regelmäßig geleert werden.

7.6. Bereinigung der Dokumentablage

Da die Dokumentablage über die Zeit eine beachtliche Größe erreichen kann (sofern sie denn benutzt wird) und auch nicht unbedingt als Langzeitarchiv gedacht ist die Verwendung von periodischen Löschläufen sinnvoll. Hierbei werden Dokumente die ein gewisses Alter erreicht haben endgültig gelöscht – geschützt sind nur solche auf die eine Wiedervorlage besteht, da diese nicht mehr richtig funktionieren würde wenn das Ursprungsdokument fehlt.

Die restlichen Dokumente werden in 3 Kategorien unterschieden für die das Löschalter separat konfiguriert werden kann. Die zugehörigen Properties dafür lauten

filing.ageLimitCommittedDocuments=1
filing.ageLimitUncommitedDocuments=1
stack.maxAgeUntilErased=0

Es gibt 2 Varianten des Löschlaufes die im Folgenden beschrieben werden.

Löschlauf als Serverkomponente

In der webdesk-Webapplikation läuft ein eigener Thread der die genannten Löschkommandos periodisch durchführt. Zusätzlich zu den oben genannten Properties kann das Intervall über

filing.cleaningPeriod

Löschlauf als unabhängiges Programm

Es steht auch eine eigene Java-Bibliothek zur Verfügung über die die Löschläufe explizit angestoßen werden können. Eine Konfiguration des Intervalls gibt es hier nicht, es wird genau ein Durchlauf ausgeführt, die Steuerung obliegt dem Aufrufer. Die Integration kann Java seitig über die Klasse

FilingCleaner

java -jar filing_cleaner.jar

filing.maxResultsPerCleaningTask=5