Schnittstellendokumentation <System>

Version:	<Version>

Status:	<Status>

Stand:	00.00.0000

Vertraulichkeit:	<Vertraulichkeitsstufe>

„IsyFact Vorlage Schnittstellendokumentation“
des Bundesverwaltungsamts ist lizenziert unter einer
Creative Commons Namensnennung 4.0 International Lizenz.

Die Lizenzbestimmungen können unter folgender URL heruntergeladen werden: http://creativecommons.org/licenses/by/4.0

Dieser Lizenztext bezieht sich auf die Vorlage. In Dokumenten, die auf der Vorlage basieren, ist dieser Text zu löschen.

Zusammenfassung

Dieses Dokument enthält Ausfüllhinweise für die Erarbeitung von Schnittstellendokumentationen nach dem V-Modell XT in einer für den Kunden angepassten Fassung. Es handelt sich um Empfehlungen, die im Einzelfall in Absprache mit dem Kunden abgewandelt werden können.

Historie

Version	Status	Datum	Autor(en)	Erläuterung
1.0	akzeptiert	01.07.2020	msg systems ag	Initiale Erstellung

Inhaltsverzeichnis

1	Allgemeines	3

1.1	Zusammenfassung (Management-Summary)	3

1.2	Leseanleitung	3

1.2.1	Verwendete Notation und Präfixe	3

1.2.2	Regeln für den Aufbau von Nachrichten	3

1.2.3	Beispiel zum Verwenden dieser Spezifikation	3

2	Fachlicher Überblick	3

2.1	Ziele und Rahmenbedingungen	3

2.2	Architekturüberblick	3

3	Nachbarsystemschnittstellen	3

3.1	Angebotene Nachbarsystemschnittstelle NST_<Bezeichnung der Schnittstelle>	3

3.1.1	Kommunikationsablauf NST_<Bezeichnung der Schnittstelle>	3

3.1.2	Aufbau NST_<Bezeichnung der Schnittstelle>	3

3.1.2.1.1	Eingabeparameter	3

3.1.2.1.2	Schnittstellenentitätstyp NSE_Meldung_Person	3

3.1.2.1.3	Schnittstellenentitätstyp NSE_<Name des Schnittstellenentitätstyps>	3

3.1.2.2	Ausgabeparameter	3

3.1.2.2.1	Schnittstellenentitätstyp NSE_<Name des Schnittstellenentitätstyps>	3

3.1.3	Regeln für den Aufbau der Anfragenachricht	3

3.1.3.1	Regeln der Schnittstellenentitäten	3

3.1.3.1.1	NSE_<Bezeichnung der Schnittstellenentität>	3

3.1.3.1.2	NSE_<Bezeichnung der Schnittstellenentität>	3

3.1.3.2	Regeln für Wertebereich der Schnittstellenentitätsattribute	3

3.1.3.3	Regeln für Zusammensetzung einer Anfrage	3

3.1.3.4	Prüfung der Berechtigungen	3

3.2	Angebotene Nachbarsystemschnittstelle NST_<Bezeichnung der Schnittstelle>	3

3.3	Datentypen	3

4	Fehlerbehandlung	3

4.1	Validierungsfehler	3

4.2	Verarbeitungsfehler	3

4.3	Aufbau der Fehlernachricht NSE_<Bezeichnung der Schnittstellenentität>	3

4.3.1	Schnittstellenentitätstyp NSE_Fehler	3

5	Schnittstellenverhalten	3

5.1	Performanz und Antwortzeitverhalten	3

5.2	Lastverhalten und Mengengerüst	3

5.3	Verfügbarkeit	3

6	Offene Punkte	3

7	Anhang	3

7.1	Glossar	3

7.2	Fehlercodes und Fehlertexte	3

7.3	Weiterführende Dokumente	3

7.4	Abbildungsverzeichnis	3

7.5	Tabellenverzeichnis	3

Allgemeine Hinweise zur Dokumentvorlage

Diese Dokumentvorlage enthält die Gliederung für eine V-Modell-konforme Schnittstellendokumentation eines Softwaresystems (Software-Entwicklungsprojekt) mitsamt Ausfüllhinweisen und Beispielen in den jeweiligen Kapiteln. Die Hinweise und Beispiele (auch dieser Abschnitt) sind in der Schnittstellendokumentation später zu entfernen. Sie dienen nur als Hilfestellung für die Erstellung des Dokuments.

Das Dokument enthält eine fachliche Beschreibung der angebotenen Nachbarsystemschnittstellen und richtet sich somit an Fachanwender, Softwareentwickler und Softwarearchitekten, die die beschriebenen Schnittstellen nutzen möchten. Dieses Dokument enthält keine Dokumentation der technischen Details der Nachbarsystemschnittstellen, wie z.B. Schnittstellentechnologie, Aufrufpfade oder Implementierungshinweise.

Bei Änderungen des Softwaresystems, die die Schnittstellen betreffen, ist dieses Dokument anzupassen und auf die Änderungen in der Historie hinzuweisen.

Dieses Dokument orientiert sich am Aufbau der V-Modell XT Vorlage „Externes-SW-Modul-Spezifikation“, da die Nachbarsystemschnittstelle ein externes Software-Modul darstellt. Da es sich bei diesem Dokument um eine rein fachliche Dokumentation und keine Spezifikation handelt, wird der Umfang und die Gliederung der Vorlage angepasst. Zudem ist die Sichtweise eine andere. In der Spezifikation werden Anforderungen an etwas Neues gestellt, in der Dokumentation wird etwas bereits Umgesetztes beschrieben. Das Mapping der Gliederung mit der Dokumentvorlage des V-Modells XT zeigt die nachfolgende Abbildung.

Abbildung 1: Abbildung der Spezifikationsmethodik auf das V-Modell XT

Für die Bezeichnung von Elementen der Schnittstellendokumentation wird folgende Konvention verwendet, um den Typ des Elements kenntlich zu machen:

<Elementtypkürzel>_<Name_des_Elements>

Der Typ des Elements wird in gekürzter Form dem Elementnamen vorangestellt. Der Elementname wird mit Unterstrichen statt mit Leerzeichen notiert (z.B. NSE_Meldung_Person). Durch diese Schreibweise wird die spätere Durchsuchbarkeit und eindeutige Identifikation der Elemente gewährleistet.

Jedes Element wird im Dokument in einem Kapitel mit einer Überschrift im folgenden Format notiert:

<Elementtyp> <Elementtypkürzel>_<Name_des_Elements>

Zum Beispiel „Angebotene Nachbarsystemschnittstelle NST_Daten_lesen“.

Die Gliederung der Überschriften soll dem Muster aus diesem Dokument entsprechen. Die Inhalte der jeweiligen Kapitel werden nachfolgend beschrieben.

Für die Erstellung der UML- Diagramme, die in diesem Dokument als Beispiele aufgeführt sind, wurde das Werkzeug „Enterprise Architect“ der Firma SparxSystems verwendet. Abschnitte in dieser Darstellung erklären, wie das jeweils davor abgebildete Diagramm im Enterprise Architect zu erstellen ist.

Anstelle des Enterprise Architect kann auch jedes andere Modellierungswerkzeug eingesetzt werden, das den Sprachumfang von UML in hinreichender Breite abdeckt.

Allgemeines

Zusammenfassung (Management-Summary)

Unter diesem Kapitel soll eine Zusammenfassung des Dokuments auf wenigen Seiten erfolgen.

Beispiel: Dieses Dokument enthält Ausfüllhinweise für die Erarbeitung von Schnittstellendokumentationen nach dem V-Modell XT in einer für den Kunden angepassten Fassung. Es handelt sich um Empfehlungen, die im Einzelfall in Absprache mit dem Kunden abgewandelt werden können. Abweichungen, insbesondere in der Dokumentstruktur sind jedoch in Kapitel 1.2 anzugeben und mit einer Begründung zu versehen.

Leseanleitung

Die Leseanleitung enthält Hilfen für den Leserkreis. Inhalte sind zum Beispiel

Aufbau der Dokumentation (Aufteilung in Dokumente, interne Struktur)

Beschreibung der verwendeten Methodik

Empfehlungen für verschiedene Lesergruppen

Leseanleitung zu verwendeten Notationen (z.B. UML 2.0)

Im Folgenden sind einige Beispielkapitel vorhanden, die genutzt, erweitert oder auch gelöscht werden können.

Verwendete Notation und Präfixe

In diesem Kapitel wird kurz auf die verwendete Notation und verwendeter Präfixe für die Bezeichnung von Elementen eingegangen. Im Folgenden befindet sich eine Beispielbeschreibung, die je nach Bedarf und Lesergruppe angepasst werden kann.

Beispiel: Für die Beschreibung der Nachbarsystemschnittstellen wird eine angepasste Form der Notation UML 2.0 verwendet. Die in dieser Notation dargestellten Diagramme bestehen aus Elementen und ihren Beziehungen untereinander. Die Beziehungen werden je nach Art der Beziehung durch unterschiedliche Verbinder dargestellt. Zur Erläuterung werden in den folgenden Abschnitten die verwendeten Elemente und Verbinder genauer erklärt.

Zu jeder Schnittstelle werden die Eingabeparameter (<<verwendet als Parameter>>) links und die Ausgabeparameter (<<LiefertZurück>>) rechts neben dem Schnittstellensymbol aufgeführt.

Abbildung 2: Beispiel für die grafische Darstellung einer Nachbarsystemschnittstelle

Die Parameter können komplex sein. Um die Übersichtlichkeit zu erhöhen, ist ihre Struktur nicht direkt im Schnittstellendiagramm, sondern in separaten Kapiteln Aufrufparameter und Ausgabeparameter im Detail beschrieben. Die Spezifikation der Nachbarsystemschnittstellen umfasst grafische, tabellarische und textliche Beschreibungen.

Die Tabelle 1 enthält im Dokument verwendete Präfixe mit den zugehörigen Elementen.

Präfix	Element
DTY_	Datentyp
NSA_	Nachbarschnittstellen-Attribut
NSE_	Nachbarsystemschnittstellen-Entitätstyp
NST_	Nachbarsystemschnittstelle

Tabelle 1: Übersicht der verwendeten Namenspräfixe

Regeln für den Aufbau von Nachrichten

Dieses Kapitel gibt eine kurze Einführung in die Validierungsregeln von Nachrichten. Falls keine Validierung von Nachrichten benötigt wird, kann dieses Kapitel entfernt werden. Im Folgenden befindet sich eine Beispielbeschreibung, die genutzt werden kann.

Beispiel: Die Nachrichten werden vom Service-Gateway gegen Regeln validiert. Dabei wird u.a. geprüft,

ob die anfragende Behörde berechtigt ist

ob alle Pflichtattribute gesetzt sind

ob der Wertebereich der Attribute eingehalten wurde

ob die Nachricht mit dem Bestand kompatibel ist

etc.

Schlägt die Prüfung fehl, gibt das Service-Gateway eine Fehlernachricht mit Fehlercodes und Fehlertext an den Aufrufer zurück.

Bei jeder Schnittstelle sind die Regeln beschrieben, die beim Aufbau der Nachricht eingehalten werden müssen.

Zu jeder Regel ist angegeben, welcher Fehlercode bei einer Regelverletzung in der Fehlermeldung zurückgegeben wird. Die zugehörigen Fehlertexte können im Anhang nachgelesen werden.

Beispiel zum Verwenden dieser Spezifikation

Im Folgenden wird beschrieben, wie diese Dokumentation verwendet werden kann, um eine Nachricht für eine Nachbarsystemschnittstelle zu erstellen. Der Aufbau ist exemplarisch und kann bei Bedarf angepasst werden. Da dieses Dokument in der Regel mehrere Nachbarsystemschnittstellen dokumentiert, sollte die Beschreibung der Verwendung möglichst allgemeingültig verfasst werden, sodass sie auf alle Nachbarsystemschnittstellen zutrifft.

Beispiel: Hier wird beschrieben, wie der Anwender mit Hilfe dieser Spezifikation eine Nachricht aufbauen kann.

Die benötigte Schnittstelle ist NST_<Nachbarsystemschnittstelle>.

In Kapitel <Kapitel der NST> ist diese Schnittstelle beschrieben.

Es muss eine NSE_<Schnittstellenentität der Anfrage> aufgebaut werden; der Aufbau ist in Abbildung 1: dargestellt. Hier sieht man, welche Entitäten enthalten sein müssen und welche Entitäten enthalten sein können (Kardinalitäten an den Verbindern).

Für jede NSE sind die Attribute im Kapitel Eingabeparameter beschrieben.

Für jedes Attribut ist der Datentyp im Kapitel 3.3 Datentypen beschrieben.

Durch die Regeln für den Aufbau der Nachricht werden die Wertebereiche der Attribute genauer bestimmt (z.B. kann auch ‚+‘ für unbekannt in Namensattributen angegeben werden, aber es muss mindestens Vorname oder Nachname bekannt sein).

Durch die Regeln werden die Attribute miteinander in Beziehung gesetzt, z.B. muss sich ein gemeldeter „Anderer Name“ von den Grundpersonalien unterscheiden, und eine Organisation darf nur bei bestimmten Sachverhalten und Sachverhaltskennungen gemeldet werden.

Unter Berücksichtigung dieser Informationen, kann die NSE_<Schnittstellenentität der Anfrage> korrekt aufgebaut werden.

Fachlicher Überblick

Ziele und Rahmenbedingungen

Die zentralen Ziele und Rahmenbedingungen bilden das einleitende Kapitel einer Schnittstellendokumentation. Damit wird ein inhaltlicher Einstieg in die Schnittstellendokumentation gegeben. Es werden die folgenden Themen behandelt:

Zweck und Ziele des Systems bzw. des Projektes

Ausgrenzungen bezüglich des Projektumfangs

Projektbeteiligte und Nutzer des Systems

Vorgaben und Rahmenbedingungen des Projektes (fachlich, technologisch, organisatorisch, politisch, gesetzlich, etc.)

Architekturüberblick

Der Architekturüberblick beschreibt die angebotenen Schnittstellen und identifiziert Nachbarsysteme. Die Darstellung erfolgt rein aus fachlicher Sicht und differenziert nicht zwischen Schnittstellentechnologien. Jede angebotene Schnittstelle wird in Kapitel 3 detailliert beschrieben. Dieses Kapitel bietet somit einen fachlichen Gesamtüberblick über alle Schnittstellen. Je nach Komplexität kann das Diagramm auf Anwendungsebene oder auf Komponentenebene erstellt werden. Im Folgenden wird die Sicht auf die Aufwendungsebene beschrieben.

Der Architekturüberblick sollte knapp und klar gestaltet werden. Ein gutes Übersichtsbild listet Schnittstellen und externe Nachbarsysteme auf.

Neben dem Übersichtsbild werden die angebotenen Schnittstellen tabellarisch aufgelistet und kurz fachlich beschrieben.

Schnittstelle	Typ	Beschreibung
NST_<Bezeichnung der Schnittstelle>	Falls es eine fachliche Unterscheidung gibt (z.B. Meldung, Auskunft, etc.)	Kurze Beschreibung der Schnittstelle - Zweck/Ziel der Schnittstelle - Rückgabewertwerte (z.B. Trefferliste)
Weitere Schnittstellen	Weitere Typen	Weitere Beschreibungen

Tabelle 2: Schnittstellen des <System>

Nachbarsystemschnittstellen

Ein UML-Komponentendiagramm gibt einen Überblick über die vom Anwendungssystem angebotenen Schnittstellen.

Abbildung 3: Angebotene Schnittstellen

Angebotene Nachbarsystemschnittstelle NST_<Bezeichnung der Schnittstelle>

Kommunikationsablauf NST_<Bezeichnung der Schnittstelle>

In diesem Kapitel wird der Kommunikationsablauf zwischen einem anderen System und der angebotenen Nachbarsystemschnittstelle beschrieben.

Der Kommunikationsablauf wird in einem Sequenzdiagramm dargestellt. Das Sequenzdiagramm enthält die beteiligten Akteure und die Eingabe- und Ausgabeparameter. Im Anschluss an das Sequenzdiagramm wird dieses erläutert.

Abbildung 4: Kommunikationsablauf NST_Meldung_durchführen

Aufbau NST_<Bezeichnung der Schnittstelle>

Die Nachbarsystemschnittstelle wird in einem oder mehreren Diagrammen grafisch dargestellt. Dabei werden die Parameter und Rückgabewerte als Nachbarschnittstellenentitäten dargestellt. Diese beschreiben den Aufbau der Schnittstelle. Der Aufbau der Schnittstellenentitäten kann dem Aufbau eines Datenmodells ähneln. Meist ergeben sich aber doch Abweichungen, zum Beispiel, weil Attribute erst vom aufgerufenen Anwendungsfall berechnet und gespeichert werden.

Für die Beschreibung der Nachbarsystemschnittstellen wird eine angepasste Form der Notation UML 2.0 verwendet. Die in dieser Notation dargestellten Diagramme bestehen aus Elementen und ihren Beziehungen untereinander. Die Beziehungen werden je nach Art der Beziehung durch unterschiedliche Verbinder dargestellt. Zur Erläuterung werden in den folgenden Abschnitten die verwendeten Elemente und Verbinder genauer erklärt.

Zu jeder Schnittstelle werden die Eingabeparameter (<<verwendet als Parameter>>) links und die Ausgabeparameter (<<LiefertZurück>>) rechts neben dem Schnittstellensymbol aufgeführt. Die Parameter können komplex sein. Um die Übersichtlichkeit zu erhöhen, ist ihre Struktur nicht direkt im Schnittstellendiagramm, sondern in separaten Kapiteln Aufrufparameter und Ausgabeparameter im Detail beschrieben.

Nachbarschnittstellenentitäten können über mehrere Schnittstellen hinweg wiederverwendet werden.

Wenn das Diagramm der Schnittstelle zu umfangreich wird, kann es auf mehrere Diagramme aufgeteilt werden.

NSE_Fehler – NSE_Meldung_Maßnahme – NSE_Meldung_Person

Abbildung 5: NST_Meldung_durchführen

Erstellung des Diagramms im Enterprise Architect:

Man zieht die Nachbarsystemschnittstelle aus dem UML-Profil „Nachbarschnittstellen“ in ein Composite Structure Diagramm und benennt sie richtig. Die Schnittstellenentitätstypen werden erst erstellt und dann in diesem Diagramm verwendet. Zwischen den Schnittstellenentitätstypen werden Verknüpfungen definiert. Typischerweise ergeben sich eine oder mehrere baumartige Strukturen, analog zum Datenmodell. Deren „Wurzeln“ werden mit der Schnittstelle verknüpft, entweder als Parameter oder als Rückgabe. Beide Verknüpfungen stammen aus dem UML-Profil „Nachbarschnittstellen“.

Kurzbeschreibung	Welche fachlichen Dienste werden durch die Schnittstelle bereitgestellt? Welchen fachlichen Hintergrund haben die ausgetauschten Daten?
Synchron/Asynchron	Bei synchronen Schnittstellen blockiert der aufrufende Bearbeitungsablauf so lange, bis das aufgerufene Anwendungssystem eine Antwort zurückgesendet hat (enge Kopplung). Bei asynchronen Schnittstellen fährt der aufrufende Bearbeitungsablauf sofort mit weiteren, lokalen Schritten fort (lose Kopplung). Falls eine Reaktion vom aufgerufenen Anwendungssystem erwartet wird, so muss sie über einen asynchronen Mechanismus wie z.B. ein Aufgabensystem in den Bearbeitungsprozess wieder eingegliedert werden.
Verwendete Entitätstypen (Input)	Liste der Schnittstellenentitätstypen, die Parameter beim Aufruf der Schnittstelle durch ein Nachbarsystem sind. Durch das Schnittstellendiagramm ist diese Information bereits dargestellt, daher ist die Auflistung optional.
Verwendete Entitätstypen (Output)	Liste der Schnittstellenentitätstypen, die von der Schnittstelle zurückgeliefert werden. Durch das Schnittstellendiagramm ist diese Information bereits dargestellt, daher ist die Auflistung optional.

Eingabeparameter

Die Eingabeparameter der Nachbarsystemschnittstelle werden beschrieben. Wenn es viele Überschneidungen zwischen den Eingabeparametern der verschiedenen angebotenen Nachbarsystemschnittstellen gibt, kann dieser Abschnitt auch einmalig nach den Nachbarsystemschnittstellen beschrieben werden.

Schnittstellenentitätstyp NSE_Meldung_Person

Namen von Schnittstellenentitätstypen beginnen mit dem Präfix „NSE_“ gefolgt von einem Substantiv, z.B. „NSE_Person“. Falls nötig, kann noch ein Adjektiv vor das Substantiv gestellt werden. Es hat sich als sinnvoll erwiesen, zusätzlich eine Kurzfassung des Namens der Schnittstelle in den Namen der Entität aufzunehmen, z.B. „NSE_Meldung_Person“. Wenn die Schnittstellenentität einem Entitätstyp im Datenmodell der Systemspezifikation entspricht, sollte sie auch analog heißen.

Falls der Schnittstellenentitätstyp aus mehreren Entitäten zusammensetzt ist, kann dieser (nach einer kurzen Gesamtübersicht) in die einzelnen Entitäten zerlegt und diese anschließend ausführlich beschrieben werden. Dieses Vorgehen wird exemplarisch in diesem Dokument gezeigt.

Abbildung 6: NSE_Meldung_Person

Schnittstellenentitätstyp NSE_<Name des Schnittstellenentitätstyps>

Kurzbeschreibung	Die Beschreibung des Schnittstellenentitätstyps ermöglicht dem Leser, den Namen der Entität zu verstehen. Für die Begriffserklärung können Synonyme oder Oberbegriffe benutzt werden (Beispiel: „Ein Mitarbeiter ist eine natürliche Person“…"). Anschließend wird der Begriff inhaltlich und zeitlich abgegrenzt, d.h. es wird erläutert, unter welchen Bedingungen eine Ausprägung zu diesem Entitätstyp gehört. Die Beschreibung kann Beispiele, weitere Erläuterungen und Anmerkungen enthalten.

Attribut	Datentyp	Bedeutung	Pflicht
Name des Nachbarschnittstellenattributs beginnend mit dem Präfix „NSA_“.	Verweis auf den fachlichen Datentyp (siehe Kapitel „3. 3 Datentypen“) oder auf einen einfachen Datentyp („Zeichenkette“, „Ganzzahl“, „Fließkommazahl“ etc.).	Die Beschreibung des Attributes sollte einen inhaltlichen Mehrwert bringen (also Beschreibungen wie „Datum ist das Datum der Buchung“ vermeiden). Folgende Fragestellungen können bei der Beschreibung helfen: Ist diese Information immer oder nur unter bestimmten Bedingungen vorhanden? Wann und wo entsteht diese Information? Wie entsteht diese Information im Unternehmen? (Die Information kann festgestellt, festgelegt und abgeleitet sein.) Für welchen Zeitraum bzw. bis zu welchem Zeitpunkt ist diese Information gültig?	Gibt an, ob es sich um ein Pflichtfeld handelt (J/N). Weitere Details sind in den entsprechenden Kapiteln zu den Befüllungsregeln der Nachrichten beschrieben. Bei einem Pflichtfeld muss ein Wert gesetzt sein. Bei einigen Attributen sind auch unscharfe Angaben erlaubt (z.B. NSA_Geburtsdatum und NSA_Vorname) Bei einem Datum erkennt man das am Datentyp (DTY_unsicheres_Datum) bei einem Textattribut erkennt man es bei den Regeln für den Aufbau der Nachrichten (z.B. beim NSA_Vorname ist die Angabe ‚+‘ erlaubt, das steht für einen unbekannten Wert). Bei Ausgabeparametern bedeutet die Pflichtangabe, ob das Attribut in der Rückgabe immer gesetzt ist.
Weitere Nachbarschnittstellenattributs in nachfolgenden Zeilen	Weitere Datentypen	Weitere Beschreibungen

Ausgabeparameter

Die Ausgabeparameter der Nachbarsystemschnittstelle werden analog zu den Eingabeparametern beschrieben. Wenn es viele Überschneidungen zwischen den Ausgabeparametern der verschiedenen angebotenen Nachbarsystemschnittstellen gibt, kann dieser Abschnitt auch einmalig nach den Nachbarsystemschnittstellen beschrieben werden. Zurückgegebene Fehlermeldungen (z.B. NSE_Fehler) werden in Kapitel 4 beschrieben. Diese sollen an dieser Stelle nicht beschrieben werden.

Schnittstellenentitätstyp NSE_<Name des Schnittstellenentitätstyps>

Kurzbeschreibung	Die Beschreibung des Schnittstellenentitätstyps ermöglicht dem Leser, den Namen der Entität zu verstehen. Für die Begriffserklärung können Synonyme oder Oberbegriffe benutzt werden (Beispiel: „Ein Mitarbeiter ist eine natürliche Person“…"). Anschließend wird der Begriff inhaltlich und zeitlich abgegrenzt, d.h. es wird erläutert, unter welchen Bedingungen eine Ausprägung zu diesem Entitätstyp gehört. Die Beschreibung kann Beispiele, weitere Erläuterungen und Anmerkungen enthalten.

Attribut	Datentyp	Bedeutung	Mindestangabe
Name des Nachbarschnittstellenattributs beginnend mit dem Präfix „NSA_“.	Verweis auf den fachlichen Datentyp (siehe Kapitel „3.3 Datentypen“) oder auf einen einfachen Datentyp („Zeichenkette“, „Ganzzahl“, „Fließkommazahl“ etc.).	Die Beschreibung des Attributes sollte einen inhaltlichen Mehrwert bringen (also Beschreibungen wie „Datum ist das Datum der Buchung“ vermeiden). Folgende Fragestellungen können bei der Beschreibung helfen: Ist diese Information immer oder nur unter bestimmten Bedingungen vorhanden? Wann und wo entsteht diese Information? Wie entsteht diese Information im Unternehmen? (Die Information kann festgestellt, festgelegt und abgeleitet sein.) Für welchen Zeitraum bzw. bis zu welchem Zeitpunkt ist diese Information gültig?
Weitere Nachbarschnittstellenattributs in nachfolgenden Zeilen	Weitere Datentypen	Weitere Beschreibungen

Regeln für den Aufbau der Anfragenachricht

In diesem Kapitel wird beschrieben, welche Regeln beim Aufbau der Anfragenachrichten eingehalten werden müssen. Diese Regeln werden vom System geprüft. Ist die Regel nicht erfüllt, erzeugt das System in der Regel eine Fehlernachricht mit dem angegebenen Fehlercode und einem Fehlertext.

Geprüft werden kann zum Beispiel,

•	ob der Anfragende berechtigt ist

•	ob alle Pflichtattribute gesetzt sind

•	ob der Wertebereich der Attribute eingehalten wurde

•	etc.

Zu jeder Regel muss angegeben werden, welcher Fehlercode bei einer Regelverletzung in der Fehlermeldung zurückgegeben wird. Die zugehörigen Fehlertexte werden im Anhang verfasst.

Die Art und der Umfang der Regeln bestimmen die Kapitelstruktur. Die folgenden Kapitel stellen keine abschließende Auflistung von Regeltypen dar. Die Beschreibung der Regeln erfolgt auf Schnittstellenentitäts- und Attributsebene. Die Regeln sind tabellarisch zu beschreiben und mit dem Fehlercode zu versehen, der bei einem Regelbruch zurückgeliefert wird. Beispielhaft kann folgende Struktur als Grundlage gewählt werden:

Regeln der Schnittstellenentitäten

Hier werden Regeln definiert, die für eine komplette Schnittstellenentität gelten. Dies kann zum Beispiel die Prüfung auf Vollständigkeit sein.

NSE_<Bezeichnung der Schnittstellenentität>

Regel	Fehlercode
Es muss stets eine verantwortliche Organisation angegeben werden.	ABCXY0123
Weitere Regeln	Weitere Fehlercodes

Regeln für Wertebereich der Schnittstellenentitätsattribute

Hier werden Regeln für die Wertebereiche der einzelnen Schnittstellenentitätsattribute definiert. Auf eine Gruppierung nach Schnittstellenentität in Form von Unterkapiteln kann bei Bedarf verzichtet werden, da typischerweise gleiche Attribute über mehrere Schnittstellenentitäten hinweg verwendet werden und der Übersicht halber nur einmal beschrieben werden sollen.

Typische Regeln:

Max. Länge des anzunehmenden Wertes

erlaubte Zeichen

Format ggfs. mit regulären Ausdrücken

Verwendung von Wildcards

Attribut	Wertebereich	Max. Länge	Fehlercode
NSA_Datum	Ein Datum ist syntaktisch korrekt, wenn es die in der ISO 8601 festgelegte Form (JJJJ-MM-TT) hat, wobei T, M und J Ziffern sind. Beispiele: 2000-02-29, 1999-00-00 Es muss ein gültiger Kalendertag (inkl. Schalttage) sein.	10	ABCXY4567
Weiteres Attribut	Weiterer Wertebereich

Regeln für Zusammensetzung einer Anfrage

Oft sind weitere Regeln notwendig, um die korrekte Zusammensetzung einer Anfrage aus mehreren Schnittstellenentitäten oder Schnittstellenentitätsattributen zu gewährleisten.

Typische Regeln

Einhaltung der Kardinalität

Einhaltung von logischen Verknüpfungen

Einhaltung von WENN-DANN Beziehungen (z.B. wenn NSA_Alter < 18, dann muss NSE_Erziehungsberechtigter in der Nachricht enthalten sein.)

Regel	Fehlercode
Bei einer Anfrage muss entweder NSE_Organisation oder NSE_Person befüllt sein.	ABCXY789

Prüfung der Berechtigungen

Beschreibt, welche Rollen oder Berechtigungen für die Benutzung der Schnittstelle notwendig sind. Sind je nach Aufbau der Nachricht verschiedene Berechtigungen nötig, so sind diese Fälle an dieser Stelle zu beschreiben.

Angebotene Nachbarsystemschnittstelle NST_<Bezeichnung der Schnittstelle>

Dieser Abschnitt ist ein Platzhalter, um zu verdeutlichen, dass ab hier weitere angebotene Schnittstellen mit ihren Ein- und Ausgabeparametern zu beschreiben sind.

Datentypen

Fachliche Datentypen gruppieren Typen und Wertebereichsangaben von Attributen. Die Datentypen werden in einem Datentypverzeichnis verwaltet. Beispiele: ISBN, Fahrgestellnummer, Aufzählungstypen.

Im Fall von trivialer Fachlichkeit (z.B. Beschreibungstexte, einfache Nummern) verzichten wir auf fachliche Datentypen und verwenden direkt die technischen Basistypen Zeichenkette, Ganzzahl, Kommazahl etc. Eigenschaften des Attributes und der Datentyp sollten voneinander getrennt werden.

Typischerweise verwenden verschiedene Anwendungssysteme ähnliche Datentypen. Innerhalb einer Anwendungslandschaft müssen gleich benannte Datentypen auch den gleichen Inhalt haben. Ähnliche, aber inhaltlich unterschiedliche Datentypen sollten auch über die Anwendungssysteme der Anwendungslandschaft explizit unterschiedlich benannt werden, um hier Verwirrung zu vermeiden.

Datentyp	Basistyp	Bedeutung	Wertebereich
Name des Datentyps beginnend mit dem Präfix „DTY_“.	Technischer Basistyp wie „String“, „Integer, „Float“, „Alphanum“ oder ähnliche.	Fachliche Bedeutung des Datentyps. Hier sollen auch Plausibilisierungen und Prüfungen beschrieben werden.	Mögliche Ausprägungen des Datentyps.

Fehlerbehandlung

In diesem Kapitel wird die Fehlerbehandlung der angebotenen Schnittstellen beschrieben. Neben der Beschreibung von Validierungs- und Verarbeitungsfehlern, können der Beschreibung auch weitere Fehlerarten hinzugefügt werden.

Validierungsfehler

Validierungsfehler werden durch fehlerhafte fachliche Bedingungen beim Eingang von Nachrichten ausgelöst. Zu einer Nachricht werden alle Validierungsfehler gesammelt und an den Aufrufer übermittelt. Die möglichen Validierungsfehler sind bei den Aufbauregeln der einzelnen Anfragenachrichten beschrieben. In diesem Kapitel sollen mindestens folgende Aspekte beschrieben werden:

Validierungsarten (Format, Fachliche Anforderungen, etc.)

Behandlung der Validierungsfehler (Organisationssicht)

Verarbeitungsfehler

Verarbeitungsfehler sind technische Ausnahmefehler, die zum Beispiel bei technischen Verarbeitungsproblemen oder einer nicht Schemakonformen-Nachricht auftreten können.

In diesem Kapitel sollen mindestens folgende Aspekte beschrieben werden:

Behandlung der Verarbeitungsfehler (Organisationssicht)

Aufbau der Fehlernachricht NSE_<Bezeichnung der Schnittstellenentität>

In diesem Kapitel wird der Aufbau der Fehlernachricht beschrieben, die bei einem Validierungs- oder Verarbeitungsfehler an den Aufrufer zurückgegeben wird. Die Fehlernachricht ist als Schnittstellenentität ein Teil der Schnittstellenbeschreibung in Kapitel 3. Da in vielen Fällen die gleiche Schnittstellentität als Fehlernachricht für mehrere Schnittstellen verwendet wird, wird die Fehlernachricht zentral in diesem Kapitel beschrieben.

Abbildung 7: NSE_Fehlernachricht

Kurzbeschreibung	Die Fehlernachricht enthält alle Entitäten um die fachlichen Fehler bei einem Schnittstellenaufruf zurückzuliefern.

Schnittstellenentitätstyp NSE_Fehler

Kurzbeschreibung	Enthält die Beschreibung des aufgetretenen Fehlers.

Attribut	Datentyp	Bedeutung
Name des Nachbarschnittstellenattributs beginnend mit dem Präfix „NSA_“.	Verweis auf den fachlichen Datentyp (siehe Kapitel „3.3 Datenmodell) oder auf einen einfachen Datentyp („Zeichenkette“, „Ganzzahl“, „Fließkomma-zahl“ etc.).	Kurze Beschreibung des Attributs.
NSA_Fehlertext	DTY_Zeichenkette	Textuelle Kurzbeschreibung des fachlichen Fehlers.

Schnittstellenverhalten

In diesem Kapitel soll das Verhalten der Schnittstellen beschrieben werden. Als Grundlage dient hierfür die Umsetzung der nicht-funktionalen Anforderungen aus der Systemspezifikation. Im Fokus steht vor allem das Performanzverhalten und mögliche Einschränkungen im Mengengerüst von Anfragen.

Performanz und Antwortzeitverhalten

Das Antwortzeitverhalten von Nachbarsystemschnittstellen ist ein wichtiger Bestandteil der Schnittstellendokumentation, da es darüber Auskunft gibt, wie lange ein externes System in der Regel auf eine Antwort wartet. Oft erhält man hier Angaben wie "Antwortzeit beträgt max. 10 Sekunden". Falls das Performanz- und Antwortverhalten je Nachbarsystemschnittstelle differenziert, sollten die Angaben je Nachbarsystemschnittstelle dokumentiert werden. Die Angaben können je nach Umfang in Text- oder Tabellenform erfolgen.

Lastverhalten und Mengengerüst

Mengengerüste können sich auf Aspekte wie Benutzungshäufigkeit, zeitliche Verteilung der Benutzung, der Menge fachlicher Objekte und Datenvolumen beziehen. Zusammen mit dem Performanzverhalten stellt das Mengengerüst einen wichtigen Faktor in Leistung einer Schnittstelle dar. Zum Beispiel ist das Performanzverhalten nur dann aussagekräftig, wenn sie sich als Voraussetzung und Annahme auf ein konkretes Mengengerüst beziehen. Das Mengengerüst selbst ist auch ein wichtiger Aspekt, der für die Nutzung der Schnittstelle eine große Bedeutung besitzt.

Verfügbarkeit

In diesem Kapitel werden besondere Aspekte der Verfügbarkeit dokumentiert. Die Verfügbarkeit wird über einen Prozentwert gemessen, der unter Berücksichtigung von definierten Betriebs- und Wartungsfenstern angibt, wie ausfallsicher ein Anwendungssystem sein sollte und tatsächlich ist. Dokumentiert wird die geplante Betriebszeit. Zum Beispiel wird hier angegeben, dass die Schnittstelle jeweils Montag bis Freitag von 07:00 bis 19:00 Uhr zur Verfügung steht. Alternativ wird auch einfach nur ein Prozentwert angegeben, zum Beispiel 99%.

Offene Punkte

Die zur Abnahme des Dokuments noch zu klärenden offenen Punkte in Listenform.

Nummer	Beschreibung
1	Ein offener Punkt

Anhang

Glossar

Das Glossar definiert die wichtigen fachlichen und technischen Begriffe und Abkürzungen des Projekts. Zudem werden häufig verwendete fremdsprachige Begriffe übersetzt und erläutert. Das Glossar klärt somit Begriffsbedeutungen und beugt Missverständnissen vor. Es erleichtert das gemeinsame Verständnis von Fachlichkeit und Technik, sowie die Einarbeitung der Projektbeteiligten. Schließlich etabliert das Glossar eine gemeinsame Sprache aller Projektbeteiligten, sowohl im Entwicklungsprojekt wie auch auf Kundenseite.

Beispielhaft ein Glossar zu den in diesem Dokument verwendeten Begriffen:

Begriff	Kategorie	Erläuterung	Synonym(e) oder Übersetzung(en)
Anwendungskomponente	Architektur	Eine Anwendungskomponente beschreibt eine Menge funktional zusammenhängender Anwendungsfälle.
Anwendungslandschaft	Architektur	Die Anwendungslandschaft einer Organisation ist bestimmt durch die Menge der von der Organisationseinheit betriebenen Anwendungssysteme.	IT-Anwendungslandschaft
Anwendungssystem	Architektur	Ein Anwendungssystem ist eine zusammengehörende, logische Einheit aus Funktionen, Daten und Benutzungsschnittstellen.	Anwendung, IT-System
Attribut	Daten	Als „Attribut“ versteht man eine dem Entitätstyp zugeordnete Information.
Entität	Daten	Als Entität wird ein eindeutig zu bestimmendes Objekt bezeichnet, dem Informationen zugeordnet werden. Die Objekte können materiell oder immateriell sein.	Informationsobjekt, Objekt
Entitätstyp	Daten	Jede Entität (das einzelne Objekt) wird einem Entitätstyp zugeordnet. Entitäten sind konkrete Ausprägungen eines Entitätstyps.	Klasse
Fachlicher Datentyp	Daten	Ein fachlicher Datentyp beschreibt das Format und den Wertebereich eines Nachbarsystemschnittstellen-Attributs. Die Namen der fachlichen Datentypen beginnen mit dem Präfix „DTY_“. Datentypen, die eine Liste von Schlüsselwertpaaren repräsentieren, heißen Aufzählungstypen. Namen von Aufzählungstypen beginnen mit dem Präfix „DTY_“ und enden mit dem Suffix „Code“.	Datentyp
Nachbarsystem	Architektur	Ein externes System mit dem über eine Schnittstelle kommuniziert wird.
Nachbarsystemschnittstelle	Architektur	Die Nachbarsystemschnittstelle eines Systems ermöglicht es anderen Systemen, Daten mit diesem zu einem bestimmten fachlichen Zweck auszutauschen. Die Namen von Nachbarsystemschnittstellen sind in der fachlichen Schnittstellenbeschreibung durch den Präfix "NST_" gekennzeichnet.	Schnittstellen
Nachbarsystemschnittstellen-Attribut	Daten	Ein Nachbarsystemschnittstellen-Attribut entspricht einer einzelnen fachlichen Information, die über die Nachbar-systemschnittstelle ausgetauscht wird. Die Namen der Nachbarsystemschnittstellen-Attribute beginnen mit dem Präfix „NSA_“. Zum Beispiel enthält das Attribut NSA_Staat der Entität NSE_Geburtsort den Staat des Geburtsorts.
Nachbarsystemschnittstellen-Entitätstyp	Daten	Nachbarsystemschnittstellen-Entitätstypen gruppieren einzelne, fachliche Attribute der Nachbarsystem-schnittstelle. Nachbarsystemschnittstellen-Entitäten sind konkrete Ausprägungen eines Entitätstyps. Die Namen der Nachbarsystemschnittstellen-Entitätstypen beginnen mit dem Präfix "NSE_“.
Projekt	Vorgehen	Ein Projekt ist ein Vorhaben, bei dem innerhalb einer definierten Zeitspanne ein definiertes Ziel erreicht werden soll, und das sich dadurch auszeichnet, dass es im Wesentlichen ein einmaliges Vorhaben ist.	IT-Projekt
Protokollierung	Nichtfunktionale Anforderungen	Die Protokollierung erfasst Informationen zu fachlichen Abläufen, um diese zu einem späteren Zeitpunkt nachvollziehbar zu machen. Es handelt sich nicht um Logging!
UML-Klassendiagramm	Methodik	Ein Klassendiagramm ist in der Informatik eine grafische Darstellung von Entitätstypen sowie der Assoziationen zwischen diesen Entitätstypen.
UML-Komponentendiagramm	Methodik	Das Komponentendiagramm ist ein Strukturdiagramm. Es zeigt eine bestimmte Sicht auf die Struktur des modellierten Anwendungssystems.
Unified Modelling Language (UML)	Methodik	Die Unified Modeling Language (UML) ist eine von der Object Management Group (OMG) entwickelte und standardisierte Sprache für die Modellierung von Software und anderen Anwendungssystemen.

Fehlercodes und Fehlertexte

In diesem Kapitel werden alle Fehlercodes und dazugehörige Fehlertexte aufgelistet, die die Schnittstellen zurückliefern können.

In der folgenden Tabelle sind alle Fehlercodes mit den zugehörigen Fehlertexten als Nachschlagewerk aufgelistet.

Fehlercode	Fehlertext
ABCXY0123	Die Anfrage konnte nicht verarbeitet werden, da die Anfragenachricht nicht vollständig ist. Es fehlt: Organisation.

Weiterführende Dokumente

Liste mit Referenzen auf weiterführende Dokumentation.

Kürzel	Beschreibung	Ablage
[Kürzel]	Eine Beschreibung des Dokuments	Verweis auf den Ablageort des Dokuments, z.B. eine URL.

Abbildungsverzeichnis

Abbildung 1: Abbildung der Spezifikationsmethodik auf das V-Modell XT	3

Abbildung 2: Beispiel für die grafische Darstellung einer Nachbarsystemschnittstelle	3

Abbildung 3: Angebotene Schnittstellen	3

Abbildung 4: Kommunikationsablauf NST_Meldung_durchführen	3

Abbildung 5: NST_Meldung_durchführen	3

Abbildung 6: NSE_Meldung_Person	3

Abbildung 7: NSE_Fehlernachricht	3

Tabellenverzeichnis

Tabelle 1: Übersicht der verwendeten Namenspräfixe	3

Tabelle 2: Schnittstellen des <System>	3