1. Nachbarsystemschnittstellen
Ein UML-Komponentendiagramm gibt einen Überblick über die vom Anwendungssystem angebotenen Schnittstellen.
1.1. Angebotene Nachbarsystemschnittstelle NST_<Bezeichnung der Schnittstelle>
1.1.1. 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.
1.1.2. 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 (Eingabeparameter) links und die Ausgabeparameter (Ausgabeparameter) 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.
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 |
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 |
Liste der Schnittstellenentitätstypen, die von der Schnittstelle zurückgeliefert werden. Durch das Schnittstellendiagramm ist diese Information bereits dargestellt, daher ist die Auflistung optional. |
1.1.2.1. 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.
1.1.2.1.1. 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.
1.1.2.1.2. 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:
|
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 Nachbarschnittstellenattribute in nachfolgenden Zeilen |
Weitere Datentypen |
Weitere Beschreibungen |
1.1.2.2. 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.
1.1.2.2.1. 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:
|
|
Weitere Nachbarschnittstellenattribute in nachfolgenden Zeilen |
Weitere Datentypen |
Weitere Beschreibungen |
1.1.3. 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:
1.1.3.1. 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.
1.1.3.2. 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 |
|
10 |
ABCXY4567 |
Weiteres Attribut |
Weiterer Wertebereich |
||
1.1.3.3. 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 |
1.2. 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.
1.3. 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. |