Implementationsgrundlagen

für die neuen Webservices

der Creditreform
1 Grundlagen
Die Creditreform stellt ihre Onlineservices auf eine neue Webschnittstelle um. Im
Gegensatz zur alten, nach Satzformaten strukturierten IP-Gateway-Schnittstelle
ist die neue Schnittstelle als XML/SOAP-basierter WEB-Service implementiert und
erfordert somit auch eine Neuimplementation der Client-seitigen Anbindung.
Neben den technischen Änderungen hat sich auch die Fachlichkeit des
gelieferten Ratings geändert. Diese fachliche Änderung wird für Bestandskunden
den Hauptanreiz für den Wechsel auf die neue Schnittstelle darstellen.

Die alte Version der Schnittstelle wird von VC noch für mehrere Jahre unterstützt
und ein Termin für die Einstellung der alten Schnittstelle ist momentan nicht
benannt. Zukünftige Neuentwicklungen seitens der Creditreform werden
allerdings nur in der neuen Schnittstellenversion realisiert. Die PSG plant eine
CAM-Integration der neuen Schnittstelle bis zum Kundentag 2011. Der
Schwerpunkt soll zunächst auf der Realisierung des Produktes „Vollauskunft“
liegen. Eine simultane Implementation der Produkte „Firmenkurzauskunft“ und
„Onlinekompaktauskunft“ erscheint auf Basis der vorliegenden Dokumentation
ohne wesentliche Mehraufwände möglich.

Die Entwicklung der neuen WEB-Services seitens der Creditreform ist momentan
noch nicht abgeschlossen. Insbesondere ist die vorliegende Dokumentation noch
sehr spartanisch (milde ausgedrückt, undiplomatisch: „nur knapp besser als nicht
vorhanden“). Die Dokumentation für die einzelne Services bestehen in
Wesentlichen nur aus Referenzen auf XML-Schema-Definition. Es liegen aber
Vorab-Versionen der WSDL und der XSD-Datei vor. Die gelieferte Schema-
Definition ist zu groß und unübersichtlich um per „Augenintegralmethode“
verwertbar zu sein. Generiert man sich mit dem WSimport-Task aus der Schema-
Datei eine Java-Klassen-Bibliothek, so erhält man ein Package mit 165 Klassen.
Diese generierte (und somit natürlich unkommentierte) Klassenbibliothek ist
momentan die beste Informationsquelle, die vorliegt. Entsprechend ist man auf
Plausibilitätsbetrachtungen und Kenntnis der Vorgänger-CGI-Gateway-
Schnittstelle angewiesen.

Ein Testsystem, gegen den Abfragen abgefeuert werden können, steht aber zur
Verfügung. In gewissem Umfang lassen sich damit Plausibilitätsbetrachtungen
verifizieren.

VORSICHT: In dem Projektverzeichnisunterverzeichnis für den neuen WEB-Service

steht auch ein XML-Sheet mit einer Abbildung der Satzarten/Satzart-Felder auf
XML-Felder. Dieses Mapping bezieht sich auf die alte XML-Schnittstelle, die bloß
ein „XML-Wrapping“ der alten IP-Gateway-Schnittstelle darstellt. Es handelt sich
NICHT um die XML-Struktur der neuen WEB-Service-Schnittstelle.

2 Änderungen und Neuerungen in der WEB-

Schnittstelle
2.1 Fachliche Änderung des Ratings
Das von der Creditreform als Bonitätsauskunft gelieferte Rating wird nach einer
neuen Methodik ermittelt. Prinzipiell ist diese Änderung aus rein technischer Sicht
ohne Belang. Zu dem Rating wird auch eine Ausfallwahrscheinlichkeit geliefert
(genauer zwei Ausfallwahrscheinlichkeiten: eine für das angefragte
Unternehmen, eine für den Firmen-Durchschnitt. Die „Grundmenge“ über die der
Durchschnitt gebildet wird – Land, Branche ??? – ist ggf. noch zu
recherchieren/nachzufragen).

Da dieses neue Rating aber den Hauptanreiz zum Umstieg auf die neue
Schnittstelle für Bestandskunden darstellt, erübrigt sich dadurch die
Notwendigkeit, über eine Migration von Altbeständen via Datenbankmigration
nachzudenken. Bei Umstieg eines Bestandskunden auf die neue Schnittstelle
muss der aktuelle Bestand an Auskünften über einen „Initial-Load“ neu geladen
werden. Wegen des Umfanges und den Strukturänderungen in den gelieferten
Daten in der neuen Version wäre auch rein technisch eine Migration auf
Datenbankebene via SQL-Skript kaum durchführbar.

2.2 Änderungen bzgl. der verwendeten Keys

In der alten Version der Schnittstelle sind für verschiedene Attribute in den
stukturierten Teilen der Auskünfte, z.B. Rechtsformen, Beteiligteneigenschaften
etc. Nummernkeise (Schlüssel) definiert, deren Ausprägungen in den Auskünften
in Form von Integern geliefert werden. Die Klartexte zu den jeweiligen Schüsseln
und Ausprägungen sind in einer eigenen Datei über das Portal der Creditreform
verfügbar. Zur Auflösung der Schlüsselwerte in Texte innerhalb der Client-
Anwendung mussten diese Schlüsselwerte in geeigneten Supporttabellen
importiert werden.

In der neuen Version der Schnittstelle werden die Werte innerhalb der
strukturierten Auskunft immer als Key/Text-Paare geliefert. Der Text wird
sprachabhängig geliefert, die Sprache jeweils beim Produktabruf angegeben. Die
Keys haben dabei als Präfix immer ein Kürzel für den jeweiligen Schüssel (bei
Schüsseln mit länderabhängigen Ausprägungen -z.B. Rechtsform- auch das Land,
in dem der Schlüssel verwendet wird), so dass die Schlüsselwerte global
eindeutig sind.

Bei Key-Werten innerhalb der Anfragedaten, z.B. angefordertes Produkt muss

lediglich der Key-Wert angegeben werden.

Die Creditreform behält sich zukünftige Ergänzungen der Schüsselwerte vor. Bei
den Anfragen über die Schnittstelle kann eine Versionsnummer für die von der
Client-Applikation verwendete Schlüsselliste angegeben werden. Bei Auskünften,
die Schlüsselausprägungen enthalten, die in der Versionsnummer der Anfrage
noch nicht verfügbar sind, wird seitens der Creditreform ein „Downmapping“
vorgenommen. Dabei wird ein Defaultwert „nicht abbildbar“ verwendet, wenn
eine fachlich sinnvolle Abbildung auf die ältere Schüsselliste nicht möglich ist.

Eine aktuelle, vorläufige Version der Schlüsselliste liegt als Excel-Datei vor. Die
Möglichkeit eines Abrufs der Schlüsselliste ist in der momentanen Vorab-
Testversion noch nicht implementiert. Das Pflegen und automatisierte Abrufen
von aktuellen Key-Listen erscheint aber ohnehin nicht sinnvoll, weil

• Im Client die Key-Werte nicht mehr in Klartexte aufgelöst werden müssen,

da hier ohnehin nur das von dem VC gelieferte PDF angezeigt wird.

• Bei Key-Werten, die im XPS (z.B. bei Übergabe der Rechtsform des
angefragten Unternehmens) oder bei der Ermittlung der wirtschaftlich
Berechtigten benötigt werden, neue Key-Werte ohnehin auch eine
entsprechende Anpassung der Systeme bzw. Algorithmen erfordern.

• Die Sinnhaftigkeit einer Anbindung bei Key-Werten aus den Request-

Formularen eher zu verneinen ist (siehe Diskussion bei der Logon-
Methode).

2.3 Lieferung der Klartextauskunft als PDF

In der alten Version der Schnittstelle wurde die Klartextauskunft im „Plain ASCII“-
Format geliefert. In der neuen Version der Schnittstelle werden die Auskünfte in
„lesbarer Form“ als PDF_Dateien in SOAP-Attachments geliefert.

2.4 Änderung der Fehlermeldungssystematik

In der IP-Gateway-Versionen der Schnittstelle existieren im Response-Header
Felder für zwei Integer-Werte Fehlerklasse und Fehlercode, in denen Server-
seitige Fehler mitgeteilt werden. In der momentanen CAM-Integration werden
diese Fehlercodes benutzt, um bei Fehlermeldungen zu klassifizieren, ob es sich
nur um einen temporär auftretenden Fehler, also z.B. eine temporäre
Unzugänglichkeit des Servers handelt. Ist dies der Fall, so wird die Anfrage
persistiert und durch einen im Hintergrund laufenden Server-Task in
regelmäßigen Abständen wiederholt. Der Benutzer spart somit den Aufwand für
manuelle Wiederholungen der Anfrage.

In der neuen Schnittstellenversion werden Fehlermeldungen mit dem SOAP-

Standardmechanismus als Fehler/Exception-XMLs transportiert und vom WEB-
Service-Engine im CAM-Server wieder in eine Java-Exception umgesetzt. Eine
Übermittlung des Fehlers als Fehler-Id erfolgt nicht mehr. Entsprechend ist eine
Umsetzung des alten, automatischen Wiederholungsmechanismus nicht mehr
möglich.
2.5 Versionskonzept
In der CGI-Gateway-Schnittstelle wurde im Header einer jeden Anfrage eine
Kommunikations-Versionsnummer übergeben. Die Implementation neuer
Features bzw. Ergänzung vorhandener Anfragen und Daten um neue Felder ging
immer mit einer entsprechenden Erhöhung der Versionsnummer einher. Bei
Anfragen mit älteren Versionsnummern wurden neue Satzarten und Felder nicht
geliefert. Dadurch konnten alle Kommunikationsnummern von dem Server auf
einer einzigen URL unterstützt werden.

Die Reimplementation der Schnittstelle als WEB-Service lässt dieses Konzept

nicht mehr zu, weil z.B. die strukturierten Daten eines Reports in einer älteren
Schnittstellen-Version nicht der XML-Schema-Definition der aktuellsten Version
entsprechen müssen. Der VC stellt daher die Versionen immer auf einer URL zur
Verfügung, in der die jeweilige Versionsnummer integriert ist. Neue Versionen der
Schnittstelle werden also immer auf einer neuen Server-URL zur Verfügung
gestellt. Die alte Version kann auf ihrer URL weiterhin benutzt werden. Aus rein
technischer Sicht besteht also kein Zwang zur Integration von Upgrades, die von
dem VC zur Verfügung gestellt werden.

2.6 Lieferung des Datums „Ende der Nachtragspflicht“

2.7 Neue Funktionalitäten

2.7.1.1 Produkt-Verfügbarkeit

2.8 Fehlende Funktionalitäten in der neuen Schnittstelle

KÜB?, Repost=Wiederholungsabruf über Mailbox, Initial Load? Repost/Initial-Load
wahrscheinlich mit Mailbox, Mailbox-Verzeichnis weiter möglich. KÜB
wahrscheinlich nur in Vorab-Version noch nicht implementiert. Diese Dinge noch
mal bei VC nachfragen.

2.9 Änderungen innerhalb der Services

2.9.1 Logon
In der neuen Version liefert der Logon eine sehr umfangreiche Liste mit
Validierungsregeln / zulässige Keywerte für die Requests (außer für Online-
Auskunft-Ziehen, die zulässigen Werte werden mit der neuen Funktion
ProductAvailibility geliefert). Die Response enthält eine Liste pro Service
(Bestellung / Suche / Bilanzinformationen /..) mit jeweils einer Liste pro Land mit
jeweils einer Liste von Parametern mit jeweils einer Liste von zulässigen Werten,
bzw.mit Valiadierungsregeln wie minimale Länge, maximale Länge, regular
Expression etc. pp. Wer sich ein Bild von Umfang und Komplexität der gelieferten
Daten machen will, findet die Response für unseren Testaccount aufbereitet für
die Konsole im Projektverzeichnis: LogonResponse.txt. In der von der VC bereit
gestellten Dokumentation wird darauf hingewiesen, dass aufgrund dieser Listen
eine Implementation dieses Service unumgänglich sei. Der Abruf der
entsprechenden Liste soll max. alle zwei Stunden und minimal einmal täglich
erfolgen. Ich vermute mal, dass man sich aufgrund von Streitigkeiten in der
Vorgängerversion schon mal für zukünftigen Ärger wappnen möchte. Anhand der
für unseren Testzugang gelieferten Daten halte ich es für sehr unwahrscheinlich,
dass sich einer der gelieferten zulässigen Werte bzw. Validierungsregeln
tatsächlich im laufenden Betrieb ändern. Einzig interessant scheinen mir die
gelieferten Rechtsformen (auch internationale). Eine tatsächliche
Implementation, wie in der VC Dokumentation vorgeschlagen, halte ich nicht für
ratsam, weil:

• Die Persistierung der gelieferten Daten mit ihren Listen in Listen in

Listen…-Struktur und eine Auswertung der Daten in den Validierungen der
Antrags-Oberflächen sehr aufwändig wäre. Die enthaltenen „Nutzdaten“
bilden nur einen Bruchteil der übertragenen Daten, der größte Teil der
gelieferten Daten besteht aus einer vielfachen Wiederholung des immer
gleichen, „dünn besetzten“ Datensatzes.

• Die Werte bei Online-Abruf einer Auskunft über die ProductAvailability

unmittelbar vor dem Aufruf des Request-Dialogs abgerufen werden.
Unzulässige Werte bei Suche und Bestellung werden hoffentlich (TODO:
gegen den Testserver checken) mit entsprechenden Fehlermeldung vom
VC-Server beantwortet. Mit solchen Fehlermeldungen vom Server müssen
(und können) unsere Kunden auch bei anderen Auskunftei-Modulen leben.
Ob das Merkmal „Rechtsform“ für die Identifizierung bei Suche und
Bestellung so wertvoll ist, dass sich eine solche Implementation lohnt,
bezweifle ich.

• Eine Änderung der gelieferten Daten im laufenden Betrieb sehr

unwahrscheinlich erscheint.

• Ein Update der Daten im laufenden Betrieb gegen den Testserver nicht
getestet werden kann.

• Falls ein Kunde z.B. seinen Zugang bei VC für neue Produkte freischalten
lässt ohnehin eine Anpassung der Installation (neue Page-Konfiguration in
der cam_config.ini) erfolgen muss

• Bei Hotline-Anfragen wegen intransparenter Validierungsfehler auch für

unseren Hotline-Service nicht nachvollziehbar ist, welche Validierung
durchgeführt werden, da diese nicht mehr aus dem Code ersichtlich sind.

• Weil der Service sich nicht in das angestrebte einheitliche Auskunftei-

Interface einfügt.

Stattdessen würde ich eine Implementierung angelehnt an unseren Standard in

den übrigen Auskunftei-Modulen empfehlen. Also

• Validierung von String-Längen etc. erfolgt mit statischen Werten innerhalb

der dafür vorgesehenen Validator-Klassen. Dass sich diese Werte zur
Laufzeit ändern, erscheint wenig plausibel. Bei der Implementierung der
 Validierungen kann die Rückgabe des Logons für unseren Testaccount ggf.
wertvolle Hinweise liefern.

• Für das Rechtsformmapping zwischen CAM und VC-Schnittstelle wird eine

Hook-Konstruktion verwendet. Die Implementation des Hook-Interfaces
kann einen Default-Wert „nicht abbildbar“ zurückgeben, was für das
jeweilige Stammdaten-Mapping bedeutet „Rechtsform wird nicht
übernommen“. Die Standardimplementation realisiert ein Mapping
zwischen den (deutschen) CAM-Standard-Rechtsformen und den VC-
definierten Rechtsformen. Die implementierende Klasse kann in der
cam_config.ini überschrieben werden, um im Kundenprojekt einen
ausgefeilteren Umgang mit internationalen Rechtsformen zu ermöglichen.
Eine Hook-Konstruktion ist ggf. auch notwendig um die Kombobox
„Rechtsform“ in der CAM-Suchmaske in Abhängigkeit des Landes zu
befüllen. (TODO: Wie sieht das beim Stammdatenabgleich aus?)

Auch in der neuen Version liefert der Logon ein Flag, ob sich in der Mailbox
ungelesene Einträge befinden. In der Integration der alten Schnittstelle wird
dieses Flag im Mailbox-Task benutzt, um zu Beginn zu prüfen, ob die Mailbox
überhaupt abgerufen werden muss. Wegen des Umfangs der über den Logon
gelieferten Daten, sollte diese Abfrage in der neuen Version über den Aufruf
„Mailbox-Verzeichnis“ erfolgen, da dieser im Regelfall ein geringere Datenmenge
liefert (insbesondere wenn die Mailbox leer ist) und die Daten aus der Response
beim folgenden Mailbox-Abruf ohnehin benötigt werden.

2.9.2 Suche
TODOC:

• Nur noch Sucharten „exakt“ und „fuzzy“ möglich, keine 7 Sucharten mehr.

2.9.3 Online-Produkt-Abruf
TODOC:

• Flag „auch veraltete Auskunft liefern“ fehlt. (Wie momentan in Stecker

implementiert?). Konsequent, da mit neuer Funktionalität
„Produktverfügbarkeit“ wohl obsolet.

• Nachtragsdatum wird geliefert.

2.9.4 Bestellung
• Ausprägung ‚KÜB bestellen‘, ‚KÜB abbestellen‘ in der Auftragsart fehlen in
der Schlüsselliste.

2.9.5 Mailbox
TODOC:

• Mailboxeinträge nur noch über Referenz aus Mailboxverzeichnis-Aufruf

verfügbar.
 • Alte Repost-Funktionalität der Mailbox über Mailboxverzeichnis
nachstellbar?

• Initial-Load wie in CGI-Gateway über Mailbox/Repost?

2.9.6 Verflechtungsauskunft
Die Verflechtungsdatenbank soll in der ersten Version nicht auf Basis der neuen
Schnittstelle implementiert werden.

TODOC:

• Buchhaltung, ob kostenpflichtiger Erstabruf oder kostenfreier Folgeabaruf

erfolgt jetzt serverseitig.

• WBs werden immer noch nicht von VC geliefert.

• Als Attachment wird ein PDF mit der Graphik geliefert: angefragtes
Unternehmen im Zentrum, jeweils eine Beteiligungs/Beteiligten-Ebene
nach oben und unten

2.9.7 Auskunftsformat
Die strukturierten Daten werden jetzt in einem XML geliefert, das im Vergleich zu
dem Format der CGI-Gateway-Schnittstelle viel stärker strukturiert ist. Eine
Dokumentation der fachlichen Bedeutung aller Felder durch die VC liegt nicht vor
(und wird wahrscheinlich auch in Zukunft nicht vorliegen). Da eine
Nachdokumentation durch Nachfragen bei VC erhebliche Zeitaufwände bedeuten
würde, werden wir uns (ähnlich wie bei schon bei SVC) darauf beschränken, die
Daten zu identifizieren, auf die tatsächlich ein strukturierter Zugriff erforderlich
ist. In der Standard-Version sind das die Daten, die dem XPS übergeben werden
müssen (Bonitätsauskunft, ggf. Ende der Nachtragspflicht), ggf. die Daten zum
Anbindung der Funktionalität „automatische Übernahme Stammdaten“, ggf. die
Daten für den Abgleich mit der Personen-Blacklist. (Bei Argumentation: kein
Persistieren der Daten in strukturierter Form, weil Standardkunde braucht Boni-
Index strukturiert und den Rest nur in lesbarer Form -> aber
Stammdatenübernahme und Personen-Blacklist doch im Standard????). Die
hierfür erforderlichen Daten sind im gelieferten XML-Schema identifizierbar.

3 Implementationsschritte
3.1 „Externe“ –Java-Bibliothek

3.2 CAM-Integration

3.3 XPS-Properties

3.4 Reports