So vermeiden Sie typische Fehler in Schnittstellenbeschreibungen

Da wir EDIFACT-Prüfschnittstellen auf der Basis bestehender Handbücher entwickeln, lesen wir mehrmals pro Woche Anleitungen über den geforderten Aufbau von EDI-Nachrichten. Im Laufe der Zeit ist uns aufgefallen, dass bestimmte Fehler oder Ungenauigkeiten häufiger in Dokumentationen auftauchen. Wenn Sie diese Fallstricke vermeiden, erleichtern Sie Ihren Partnern den Einstieg in den Datenaustausch mit Ihrem Unternehmen.

Zu den Eigenheiten von EDIFACT gehört, dass innerhalb einer Nachricht an verschiedenen Stellen mehrere Segmente in einer Gruppe gebündelt werden. Jede Segmentgruppe hat einen eigenen Status, der unabhängig vom Status der darin zusammengefassten Segmente ist. Ist die Segmentgruppe als Ganzes optional, müssen die enthaltenen Segmente nicht zwingend in der Nachricht gesetzt werden, selbst wenn sie alle den Status „verpflichtend“ haben. Man könnte auch sagen „Eine Segmentgruppe kann optional sein, aber WENN die Gruppe dargestellt werden soll, müssen die enthaltenen Pflichtsegmente gesetzt werden.“.

Das gilt auch für Segmentgruppen, die in einer übergeordneten Segmentgruppe enthalten sind. Ist die untergeordnete Segmentgruppe optional, so müssen die darin enthaltenen Segmente nicht zwingend in der Nachricht gesetzt werden, selbst wenn die übergeordnete Segmentgruppe verpflichtend ist. Sie sollten daher bei jeder Überarbeitung eines Handbuchs prüfen, ob nicht nur der Status der Segmente, sondern auch der der Segmentgruppen richtig gesetzt ist.

Eine sehr ähnliche Logik existiert auch innerhalb der Segmente: Ein Segment kann eines oder mehrere Composite-Datenelemente enthalten. Diese bündeln wiederum Datenelemente, in denen dann die eigentlichen Informationen stehen. Da auch Composite-Datenelemente einen Status unabhängig vom Status der enthaltenen Datenelemente haben, sollten Sie darauf achten, ob dieser korrekt ist.

Viele Handbücher umfassen verschiedene Ausprägungen einer Nachricht. Welche Segmente gesetzt und welche Datenelemente befüllt werden, hängt dann davon ab, was die Nachricht repräsentieren soll. Im Handbuch drückt sich das darin aus, dass ein Segment oder ein Datenelement den Status „abhängig“ erhält, oft abgekürzt mit einem „D“. Das Problem ist, dass häufig keine Erklärung vorhanden ist, unter welchen Umständen Segment oder Datenelement gesetzt werden müssen. In der Folge muss der Nachrichten-Implementierer dieses Wissen anderweitig abfragen oder auf der Basis seiner Erfahrung abschätzen, was zu tun ist. Beides ist nicht ideal, daher sollte bei jedem abhängigen Element eine kurze Erklärung stehen, wann es zu setzen ist. Die Erklärung muss nicht einmal im Handbuch selbst stehen, ein Verweis auf ein anderes Dokument oder eine Website kann auch schon genügen.

Jedes Datenelement in EDIFACT hat Standardwerte bei der minimalen und maximalen Länge seines Inhalts sowie bei seinem Format. Das Format gibt vor, ob Zahlen, Buchstaben oder Beides gesetzt werden dürfen. Die Herausgeber eines Handbuchs dürfen diese Standards aber an ihre Bedürfnisse anpassen. Von dieser Möglichkeit sollten Sie regen Gebrauch machen, denn so können Sie Ihren Partnern zusätzliche Hilfestellung bei der Implementierung ihrer Mappings geben. Wenn beispielsweise ein Datenelement im Standard alphanumerisch ist und die Länge 1 bis 35 haben kann, in Ihrer Guideline hier aber eine achtstellige Nummer eingefügt werden soll, macht es Sinn, die Standardwerte entsprechend zu überschreiben. Damit helfen Sie auch uns: Bei der Nachrichtenvalidierung überprüfen wir auch die Feldlängen und das Format. Sind diese bereits im Handbuch korrekt dargestellt, können wir die Prüfschnittstelle schneller umsetzen.

Grundsätzlich sind Beispielnachrichten sehr hilfreich für Implementierer. Mit ihrer Hilfe lässt sich leicht erkennen, wie Inhalte zusammenspielen und wie die Nachricht grundsätzlich auszusehen hat. Sie haben aber auch Tücken: Etwa, wenn bei der Aktualisierung des Handbuchs vergessen wird, auch die Beispielnachricht entsprechend anzupassen. Diese Gefahr steigt mit der Anzahl der Beispielnachrichten. Paradoxerweise kann also die gute Absicht, durch viele Beispiele eine möglichst umfangreiche Erklärung abzuliefern, dazu führen, dass Ihre Partner durch veraltete Dateien in der Mapping-Entwicklung ausgebremst werden.

Ein anderer Fallstrick sind unkommentierte Beispiele bei einer Schnittstelle, die verschiedene Geschäftsprozesse abdeckt. Hier kann es schwer sein, die Beispielnachrichten den jeweiligen Prozessen zuzuordnen. Im schlimmsten Fall kann dies dazu führen, dass ein Partner ein Mapping falsch entwickelt und es mehrfach überarbeiten muss. Es kann also sinnvoller sein, weniger Beispiele bereit zu stellen, diese aber sorgfältig zu kuratieren und zu kommentieren.

Klagen über Stammdaten-Fehler sind im Datenaustausch allgegenwärtig, unabhängig von der Branche oder dem Fachbereich. Sie können aber zumindest einen Teil der Fehler vermeiden, wenn Sie die Listen mit den vorgegebenen Werten zentral Ihren Partnern zur Verfügung stellen und verwalten. Der Grund: Wenn dieselben Werte, beispielsweise Abladestellen, in unterschiedlichen Handbüchern hinterlegt werden, ist die Gefahr hoch, dass bei einer Erweiterung nicht jede Dokumentation aktualisiert wird. Wenn Sie dagegen in den Handbüchern nur die Referenz auf die Listen hinterlegen - beispielsweise in Form einer URL - können Sie sicher sein, dass Ihre Partner die passenden Werte finden. Darauf aufbauend, könnten Sie ein System entwickeln, das Stakeholder automatisiert über Updates in den Wertelisten informiert.