Systemhandbuch <System>

<Autor>

Version:	<Version>

Status:	<Status>

Stand:	00.00.0000

Vertraulichkeit:	Dokument ist nicht eingestuft

Dieses Dokument ist ein Teil der IsyFact-Standards. Alle Inhalte, insbesondere Texte und Grafiken, sind urheberrechtlich geschützt. Alle urheberrechtlichen Nutzungs- und Verwertungsrechte liegen beim Bundesverwaltungsamt.

Die Nutzung des „IsyFact Vorlage Systemhandbuch“
des Bundesverwaltungsamts ist unter den Lizenzbedingungen Creative Commons Namensnennung 4.0 International Lizenz gestattet.

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

Historie

Version	Status	Datum	Autor(en)	Erläuterung
1.0	Akzeptiert	Capgemini Deutschland GmbH
1.2	Ausgeliefert	03.12.2014	msg systems AG	Übernahme in „IsyFact“
1.3	Ausgeliefert	13.05.2015	msg systems AG	Korrekturen, Review, Bereinigung von Kommentaren
1.4	Ausgeliefert	25.08.2015	Capgemini Deutschland GmbH	Smoketest-Checkliste in Kapitel 6.1.1 aufgenommen
1.5	Akzeptiert	19.11.2018	msg systems AG	Einrichten, Aktualisierung des DB-Schemas mit DB_Skripten in Kapitel 4.1.2 eingepflegt
1.6	11.09.2023	msg systems AG	Anpassung an das auf GitHub abgelegte Systemhandbuch

Inhaltsverzeichnis

1	Einleitung	2

2	Überblick	3

2.1	Fachliche Beschreibung	3

2.1.1	Anwendergruppen	4

2.1.2	Anwendungsfälle	4

2.2	Technische Beschreibung	5

2.2.1	Architekturkomponenten des technischen Verfahrens	6

2.2.2	Nachbarsysteme	7

2.2.3	Verteilungssicht	7

3	Bauen der Anwendung	8

3.1	Bau der Beispielverzeichnis-GA und Beispielverzeichnis-Batch	8

3.2	Bau der Beispielverzeichnis-GA und Beispielverzeichnis-Batch	9

3.3	Bau des Beispielverzeichnis-SGW	10

4	Vorbereitung der Systemumgebung	10

4.1	Anlegen der Betriebssystemnutzer und -gruppen	11

4.2	Einrichten der Datenbank	11

4.3	Konfiguration Benutzer- und Behördenverzeichnis	11

4.4	Schlüsselverzeichnis	12

4.5	Apache Konfiguration	12

4.5.1	uriworkermap.properties	12

4.5.2	worker.properties	13

4.6	Mail-Server Konfiguration	13

5	Installation der Anwendung	13

5.1	Installation des Default-Tomcats	13

5.2	Installation der IT-Systeme	14

6	Konfiguration der Anwendung	14

6.1	Konfiguration der Beispielverzeichnis-GA	15

6.1.1	Konfigurationsdatei logback.xml	15

6.1.2	Konfigurationsdatei isy-bsp-ga.properties	15

6.1.3	Konfigartionsdatei jpa.properties	17

6.1.4	Konfigurationsdatei isAlive	18

6.2	Konfiguration der Beispielverzeichnis-Batch	18

6.2.1	Konfigurationsdatei logback-batch.xml	18

6.2.2	Konfigurationsdatei isy-bsp-ga.properties	18

6.3	Konfiguration des Beispielverzeichnis-SGW	19

6.3.1	Konfigurationsdatei logback.xml	19

6.3.2	Konfigurationsdatei servicegateway.properties	19

6.3.3	Konfigurationsdatei isAlive	20

7	Regulärer Wirkbetrieb	20

7.1	Log- und Konfigurationsdateien	20

7.2	Datenbankschema	21

7.3	Start, Stopp, Statusprüfung der Server-Prozesse	22

7.4	Batch-Prozesse	22

7.4.1	Batch: Beispiel	23

7.4.1.1	Aufruf	23

7.4.1.2	Parameter	23

7.4.1.3	Rückgabewerte:	24

7.4.1.4	Ergebnis	24

7.5	Monitoring	24

7.5.1	Standard-Metriken	25

7.5.2	Informationen der Beispielverzeichnis-GA und des Beispielverzeichnis-SGW	26

7.5.3	Monitoring Batches	26

7.6	Backup und Recovery	27

8	Hinweise für Störungsdiagnose und -behandlung	27

8.1	Verfügbare Hilfsmittel	27

8.1.1	Smoke-Test	27

8.1.2	Debug-Logging	28

8.2	Fehler und Fehlerbehebungsmaßnahmen	28

8.2.1	Fehlercodes	29

8.2.2	Fehlerszenarien	29

9	Anhang	31

9.1	Anhang A: Historie	31

9.2	Anhang B. Fachliches Glossar	31

9.3	Anhang C: Vollständige Liste der Fehlercodes	32

10	Quellen	32

10.1	Systemspezifikation	32

10.2	Systementwurf	32

Allgemeine Hinweise zur Dokumentvorlage

Zweck dieses Dokuments

Die Dokumentvorlage enthält die Gliederung für ein Systemhandbuch. Das Systemhandbuch ist die Dokumentation eines IT-Systems aus betrieblicher Sicht. Dazu gehören insbesondere Informationen zur Installation, Konfiguration, Batches, Fehleranalyse und Backup.

Das Dokument wird durch die Entwickler der Software erstellt und gepflegt. Es enthält nur solche Informationen, welche die eigentliche Software betreffen, Informationen zu Systemumgebungen, Hardware usw. werden vom Betrieb in separaten Dokumenten gepflegt.

In diesem Dokument werden alle IT-Systeme einer Anwendung gemeinsam beschrieben. Die Abgrenzung, welche IT-Systeme zusammen beschrieben werden, ist ggf. im Einzelfall abzuwägen. Typischerweise werden eine Geschäftsanwendung und ein zugehöriges Service-Gateway gemeinsam beschrieben, aber z.B. nicht zwei Geschäftsanwendungen die zu unterschiedlichen Fachverfahren gehören, auch wenn Sie sich gegenseitig aufrufen. Ein wichtiges Kriterium für die Auswahl der IT-Systeme ist deren Entwicklungszyklus. IT-Systeme, die immer gemeinsam weiterentwickelt werden, können gut in einem gemeinsamen Dokument beschrieben werden. Querschnittsanwendungen werden in eigenen Dokumenten beschrieben.

Die Vorlage enthält bewusst auch Kapitel für Themen, die nicht für alle Systeme benötigt werden. Dies soll eine möglichst große Vollständigkeit der damit erstellten Dokumentationen begünstigen.

Bei Bedarf können Kapitel entfernt werden.

Hinweis: In diesem Dokument werden die Systemtypen und Kürzel der Vorlage-Anwendung der IsyFact durchgängig eingesetzt: GA für Geschäftsanwendung, REG für Register und SGW für Service-Gateway. Dies sind lediglich Beispiele und müssen an die Namenskonventionen angepasst werden, die im jeweiligen Kontext gelten, in der die IsyFact eingesetzt wird.

Verwendung von Dokumentenattributen

Tabelle 1. Dokumentattribute der Vorlage für das Systemhandbuch	Attribut	Bedeutung	Standardwert
anwendung	Fachlicher Name der Anwendung	Beispielverzeichnis
anwendung-ga	Fachlicher Name der Geschäftsanwendung	Beispielverzeichnis-GA
anwendung-sgw	Fachlicher Name des Service-Gateways	Beispielverzeichnis-SGW
anwendung-batch	Fachlicher Name der Batch-Anwendung	Beispielverzeichnis-Batch
it-system-ga	Technischer Name der Geschäftsanwendung	isy-bsp-ga
it-system-sgw	Technischer Name des Service-Gateways	isy-bsp-sgw
it-system-batch	Technischer Name der Batch-Anwendung	isy-bsp-batch

Verwendung von Namenskonventionen

In diesem Dokument werden die Namenskonventionen der IsyFact verwendet. Die Namenskonventionen können dem jeweiligen Kontext, in dem die IsyFact eingesetzt wird, angepasst werden.

Einleitung

Dieses Dokument enthält das Systemhandbuch für die Anwendung Beispielverzeichnis.

Es umfasst die folgenden IT-Systeme:

Beispielverzeichnis-GA (technischer Name: isy-bsp-ga),

Beispielverzeichnis-SGW (technischer Name: isy-bsp-sgw),

Beispielverzeichnis-Batch (technischer Name: isy-bsp-batch).

Kapitel 2 (Überblick) bietet einen groben fachlichen, technischen sowie betrieblichen Überblick über die Anwendung und liefert Verweise auf weitergehende Dokumente. Es ist für alle Leser des Dokuments relevant.

Kapitel 3 (Bau der Anwendung) beschreibt, wie aus dem Quellcode die Deployment-Einheiten (RPMs) entstehen. Es ist im Wesentlichen für die Softwareentwicklungsabteilung relevant.

Kapitel 4 (Vorbereitung der Systemumgebung) beschreibt, wie die Systemumgebung auf den Betrieb der Anwendung hin zu konfigurieren ist. Es ist für den Betrieb und die Softwareentwicklung relevant.

Die Kapitel 5 & 6 (Installation der Anwendung, sowie Konfiguration der Anwendung) beschreiben die Installation und Konfiguration der Anwendung auf der Systemumgebung. Sie sind wiederum für den Betrieb und die Softwareentwicklung relevant.

Kapitel 6 (Regulärer Wirkbetrieb) liefert Informationen für den Betrieb der Anwendung. Es ist für den Betrieb relevant.

Das Kapitel 7 (Hinweise für Störungsanalyse und -behandlung) schließlich liefer Informationen zur Fehleranalyse. Es ist für den Betrieb und die Softwareentwicklung relevant.

Der Anhang bietet zusätzliche Informationen wie eine Historie der Anwendung, ein fachliches Glossar und eine vollständige Liste der Fehlercodes anhand von Tabellen an.

Überblick

In diesem Kapitel wird aus fachlicher und technischer Sicht ein Überblick über die Geschäftsprozesse gegeben, die mithilfe der Anwendung Beispielverzeichnis durchgeführt werden.

Fachliche Beschreibung

Kurze, prägnante fachliche Darstellung der Anwendung.

Abbildung 1. Beispielverzeucnis: Fachlicher Kontext

Hinweis: Weitere fachliche Details können in dem Dokument „Systemspezifikation“ nachgelesen werden.

Inhalt:

- Sehr kurze zusammenfassende fachliche Darstellung der Anwendung.

- Darstellung des fachlichen Kontextes.

- Verweis auf aktuelle Version der Systemspezifikation.

Quelle:
Systemspezifikation (Extrakt aus Einleitung / Überblick & fachlicher Kontext)

Dokumentationsform:
Freitext, fachliches Kontextdiagramm

Anwendergruppen

Die Anwendung Beispielverzeichnis hat folgende Anwendergruppen:

[Name der Anwendergruppe, aus fachlichem Kontext] ([wichtigster Anwendungsfall]),

…​

Inhalt:

Sehr knappe Zusammenfassung der Anwendergruppen und ihrer wichtigsten Anwendungsfälle. Ergänzungen können unterhalb der Liste vorgenommen werden, falls nötig.

Quelle:
Systemspezifikation

Dokumentationsform:
Liste, Freitext

Anwendungsfälle

Die Anwendung Beispielverzeichnis setzt die folgenden Anwendungsfälle um.

[Name des Anwendungsfalls]

[Beschreibung des Anwendungsfalls in einem Satz].

Inhalt:

Sehr knappe Zusammenfassung der Anwendungsfälle: Name und ein beschreibender Satz.

Quelle:
Systemspezifikation

Dokumentationsform:
Liste

Technische Beschreibung

Kurze, prägnante technische Darstellung der Anwendung.

Abbildung 2. Beispielverzeichnis: Technischer Kontext

Hinweis: Weitere technische Details können im Systementwurf nachgelesen werden.

Inhalt:
- Sehr kurze zusammenfassende technische Darstellung der Anwendung.

- Darstellung des technischen Kontextes.

- Verweis auf aktuelle Version der Systemspezifikation.

Quelle:
Systementwurf (Extrakt aus Einleitung / Überblick & technischer Kontext)

Dokumentationsform:
Freitext, technisches Kontextdiagramm

Architekturkomponenten des technischen Verfahrens

Die Laufzeitumgebung für das Beispielverzeichnis besteht aus den Produkten, die in folgender Tabelle dargestellt sind.

Tabelle 2. Beispeilverzeichnis: Produkte der Laufzeitumgebung

Kategorie	Name	Version	Bemerkung
Java Virtual Machine	OpenJDK (Eclipse Temurin von Adoptium)	17.x
Servlet-Container	Apache Tomcat	8.5.x
RDBMS	(Datenbank)	(Versio)
…	…	…

Inhalt:
Übersicht über alle Bestandteile der Laufzeitumgebung, die zum Betrieb der Anwendung nötig sind. Hierbei sind nur die direkten Abhängigkeiten aufzulisten. Transitive Abhängigkeiten, wie sie u.a. Betriebssysteme in der Regel darstellen, müssen nicht angegeben werden.

Quelle:
Systementwurf, Produktkatalog IsyFact

Dokumentationsform:
Tabelle, Freitext (für weitere Bemerkungen)

Nachbarsysteme

Die Anwendung Beispielverzeichnis benötigt die folgenden Nachbarsysteme, um alle Anwendungsfälle erfolgreich durchführen zu können.

Tabelle 3. Beispielverzeichnis: Benötigte Nachbarsysteme

Nachbarsystem	Schnitstelle	Version	Essenziell?
isy-nachbar-b-gk	(Schnittstelle)	(Version)	nein
isy-nachbar-c-gk	(Schnittstelle)	(Version)	ja
…	…	…	…

Inhalt:
Übersicht über alle Nachbarsystemen, die zum Betrieb der Anwendung nötig sind. Neben der Tabelle sollte in einem kurzen Text für jedes Nachbarsystem der Grund der Abhängigkeit beschrieben sein.

Essenzielle Abhängigkeiten sind nötig, um die Kernfunktionalität der Anwendung bereitzustellen. Nicht essenzielle Abhängigkeiten hingegen bieten zusätzliche Funktionalität, falls benötigt.

Quelle:
Systementwurf

Dokumentationsform:
Tabelle, Freitext (für weitere Bemerkungen)

Verteilungssicht

Inhalt:
Deployment-Diagramm des Systems mi grober Erklärung

Folgende Aspekte sind im Diagramm darzustellen:

- Verteilung der IT-Systeme der Anwendung auf Server, also das Clustering der IT-Systeme,

- Laufzeitumgebungen (Tomcat),

- Genutzte andere Systeme und deren Kommunikationsbeziehungen,

- Genutzte technische System, z.B. Datenbank,

- Firewalls bzw. Netzwerkzonen,

- Kommunikationsprotokolle

Hinweis: Das Clustering von Nachbarsystemen kann vereinfacht dargestellt werden.

Quelle:
Systementwurf

Dokumentationsform:
Deployment-Diagramme, Tabellen, Freitext

Bauen der Anwendung

Das Bauen der Anwendung erfolgt über einen standardisierten Build-Mechanismus. Der Build benötigt die in Tabelle 3 aufgelisteten Werkzeuge und Technologien. Weitere Abhängigkeiten werden durch die erforderlichen Build-Werkzeuge selbstständig nachgeladen.

Tabelle 4. Erforderliche Build-Werkzeuge und Technologien

Werkzeug	Version
Maven	3.x
(RPM)	…
Java Developement Kit OpenJDK (Eclipse Temurin von Adoptium)	17.-x
(node.js)	…

Inhalt:
Falls nötig, Tabelle mit weiteren Werkzeugen und Technologien vervollständigen. Die obige Tabelle ist mit Vorgaben aus dem Produktkatalog gefüllt.

Dokumentationsform:
Tabelle

Bau der Beispielverzeichnis-GA und Beispielverzeichnis-Batch

Hinweis: Falls die Anwendung den traditionellen RPM Build (via ant und rpmbuild) nicht verwendet, kann dieser Abschnitt entfallen.

Zum Erzeugen der RPM-Pakete wird das Werkzeug rpmbuild mithilfe von Ant über Maven benutzt. Dies setzt ein Artefakt-Repository zum Auflösen von Paketabhängigkeiten voraus.

Der Build wird folgendermaßen ausgeführt:

mvn -Dbuild.number=<Build-Nummer> -Dtest=false -DfailIfNoTests=false clean package

Tipp: Die Build-Nummer (Argument -Dbuild.number) wird üblicherweise mit der Lieferungsnummer belegt. Das bedeutet z. B.: 1.0.0_14 wird zu 14, oder allgemein: 1.0.0_x wird zu x.

Nach erfolgreichem Build befinden sich im Ordner isy-bsp-ga-deployment/target/RPMS/noarch folgende RPM-Pakete:

isy-bsp-ga-<VERSION>.noarch.rpm: Beispielverzeichnis-GA,

isy-bsp-batch-<VERSION>.noarch.rpm: Beispielverzeichnis-Batch.

In den folgenden Kapiteln wird die Installation der einzelnen Pakete näher beschrieben.

Inhalt:
Für weitere Build-Schritte ggf. weitere Unterkapitel anlegen.

Die Anleitung soll hier vollständig sein und darf nicht auf andere Dokumente der IsyFact verweisen.

Quelle:

Entwicklerhandbuch

Dokumentationsform:
Freitext

Bau der Beispielverzeichnis-GA und Beispielverzeichnis-Batch

Hinweis: Falls die Anwendung den neuen RPM Build (via Maven-Plugin) nicht verwendet, kann dieser Abschnitt entfallen.

Zum Erzeugen der RPM-Pakete wird ein Maven-Plugin benutzt. Dies setzt ein Artefakt-Repository zum Auflösen von Paketabhängigkeiten voraus.

Der Build wird folgendermaßen ausgeführt:

mvn -Drpm.release=<Build-Nummer> -Dtest=false -DfailIfNoTests=false clean package

Tipp: Das Feld release (Argument -Drpm.release) wird üblicherweise mit der Lieferungsnummer belegt. Das bedeutet z. B.: 1.0.0_14 wird zu 14, oder allgemein: 1.0.0_x wird zu x.

Nach erfolgreichem Build befinden sich im Ordner isy-bsp-ga-deployment/target/RPMS/noarch folgende RPM-Pakete:

isy-bsp-ga-<VERSION>.noarch.rpm: Beispielverzeichnis-GA,

isy-bsp-batch-<VERSION>.noarch.rpm: Beispielverzeichnis-Batch.

In den folgenden Kapiteln wird die Installation der einzelnen Pakete näher beschrieben.

Inhalt:
Für weitere Build-Schritte ggf. weitere Unterkapitel anlegen.

Die Anleitung soll hier vollständig sein und darf nicht auf andere Dokumente der IsyFact verweisen.

Quelle:

Entwicklerhandbuch

Dokumentationsform:
Freitext

Bau des Beispielverzeichnis-SGW

Inhalt:
Build beschreiben, sofern er sich maßgeblich vom Build der GA und der Batches unterscheidet.

Die Anleitung soll auch hier vollständig sein und darf nicht auf andere Dokumente der IsyFact verweisen.

Quelle:
Entwicklerhandbuch

Dokumentationsform:
Freitext

Vorbereitung der Systemumgebung

Dieses Kapitel beschreibt, welche Vorbereitungen für den Betrieb der Anwendung Beispielverzeichnis in der Systemumgebung nötig sind.

Inhalt:
Beschreibung grundsätzlicher Konfigurationen der Systemumgebung. Dazu gehören Systembenutzer, sofern sie für mehrere Systeme benötigt werden.

Ebenso werden in eigenen Kapiteln die Einrichtung bzw. Konfiguration von technischen Systemen bzw. von benötigten Nachbarsystemen beschrieben.

Sofern Lizenz-Dateien o.Ä. benötigt werden, sollen diese ebenfalls hier aufgeführt werden.

Falls einzelne technische Systeme von sehr vielen Verfahren benötigt werden, ist es zweckmäßig, diese in eigene Dokumente auszulagern.

Quelle:
Entwicklerhandbuch, Systementwurf

Dokumentationsform:
Freitext

Anlegen der Betriebssystemnutzer und -gruppen

Die Anwendungen Beispielverzeichnis-GA und Beispielverzeichnis-SGW benötigen den Betriebssystemnutzer tomcat in der Benutzergruppe tomcat. Die Batch-Anwendung Beispielverzeichnis-Batch benötigt den Betriebssystemnutzer batch in der Benutzergruppe batch.

Die Erzeugung der Nutzer und Gruppen ist abhängig vom verwendeten Betriebssystem. Das Kennwort wird vom Betrieb vergeben. Der Tomcat-Nutzer und der Batch-Nutzer dürfen nicht das Recht besitzen, sich am System anzumelden.

Einrichten der Datenbank

Im Folgenden wird beschrieben, wie die Datenbank für die Anwendung Beispielverzeichnis vorbereitet wird.

Die DB-Skripte liegen im Verzeichnis:

isy-bsp-ga/src/main/skripte/sql/

Zum Anlegen des Datenbankschemas steht das Skript install-db-schema.sh zur Verfügung. Vorher müssen jedoch die Inhalte des Skripts, das die Umgebungsvariablen lädt (01_environment.sql), auf die jeweilige Umgebung angepasst werden.

Zur Aktualisierung des Datenbankschemas steht das Skript update-db-schema.sh bereit. Auch hier gibt es ein Skript für die Umgebungsvariablen (01_environment.sql), das angepasst werden muss.

Ausfüllhinweise
Benutzt die Anwendung die Versionierung von Datenbankschemas gemäß Detailkonzept Datenzugriff nicht, muss statt der Kurzzusammenfassung der genaue Ablauf zum Anlegen bzw. Aktualisieren des Datenbankschemas beschrieben werden.

Konfiguration Benutzer- und Behördenverzeichnis

Zur Nutzung des Verfahrens werden diverse Nutzer benötigt. Im Folgenden wird beschrieben, wie die Nutzer mit den benötigten Rollen im BBV angelegt werden. Die Anpassungen erfolgen über die Kommandozeile. Die benötigten Dateien befinden sich im Verzeichnis isy-bsp-ga/src/main/skripte/bbv/.

Es wird angenommen, dass diese Dateien in ein Verzeichnis kopiert wurden, das nachfolgend mit BBV_FILES bezeichnet wird.

Benutzerverzeichnisrollen anlegen mit:

cd /opt/plis-benutzerverzeichnis-batch/bin

./batch-benutzerverzeichnis-import.sh –ExcelDatei BBV_FILES/xxx-rollen.xls -ignoriereRestart

./batch-benutzerverzeichnis-import.sh –ExcelDatei BBV_FILES/xxx-benutzer.xls -ignoriereRestart

Sollten die Passwörter für die Benutzer geändert werden, sind folgende Punkte zu beachten:

Bei Änderung der Passwörter für externe Behörden müssen diese entsprechend in den Anfragen an Beispielverzeichnis-SGW von den Behörden angepasst werden.

Das Passwort des Nutzers XXX_Batch_Launcher muss mit dem Konfigurationsparameter batch.benutzer.passwort in der Datei /etc/isy-bsp-ga/isy-bsp-ga.properties übereinstimmen.

Ausfüllhinweise
Spezifische Änderungen an den Dateien (z.B. Entfernen von Testbenutzern oder Anpassungen an das konkrete Deployment) müssen beschrieben werden.

Schlüsselverzeichnis

Die Schlüssel und Mappings der Anwendung Beispielverzeichnis müssen in das Schlüsselverzeichnis importiert werden. Die entsprechende Datei ist mit den Schlüsseln und Mappings im Releaseletter der Beispielverzeichnis-GA angegeben.

Apache Konfiguration

Hinweis: Falls die Anwendung keine GUI besitzt, kann dieser Abschnitt entfallen.

Die Beispielverzeichnis-GA ist in der mod_jk-Konfiguration des Apache HTTP-Servers einzubinden.

uriworkermap.properties

Redirect an den Worker mit:

/isy-bsp-ga/=isy-bsp-gaWorker;use_server_errors=400

worker.properties

Worker-Konfiguration mit:

worker.list=..., isy-bsp-gaWorker

# Beispielverzeichnis-GA: isy-bsp-gaWorker

worker.isy-bsp-gaWorker.type=ajp13

worker.isy-bsp-gaWorker.host=(Host)

worker.isy-bsp-gaWorker.port=(IP)

worker.isy-bsp-gaWorker.cachesize=5

worker.isy-bsp-gaWorker.lbfactor=50

worker.isy-bsp-gaWorker.local_worker=1

Nach der Änderung muss der Apache neu gestartet werden.

Mail-Server Konfiguration

Inhalt:
Beschreibung der Einrichtung des Mail-Servers, z.B. benötigte Postfächer etc.

Quelle:
Entwicklerhandbuch, Systementwurf

Dokumentationsform:
Freitext

Installation der Anwendung

Als Ablageort und Stammverzeichnis der relativen Pfade in diesem Kapitel dient das Quellcode-Repository der Anwendung Beispielverzeichnis.

Installation des Default-Tomcats

Es müssen Tomcat-Basisinstallationen für die Anwendung vorliegen.

Tabelle 5. Installationspfade der Tomcats

IT-System	Tomcat-Installationspfad
Beispielverzeichnis-GA	/opt/isy-bsp-ga/tomcat
Beispielverzeichnis-SGW	/opt/isy-bsp-sgw/tomcat

Die Tomcat-Basisinstallation kann nur von einem Benutzer mit Root-Rechten vorgenommen werden.

Für die Erstinstallation muss der zum Beispielverzeichnis gehörende Default-Tomcat installiert werden:

Installation der Tomcats via RPM mit:

rpm -i isy-bsp-ga-tomcat-(version).x86_64.rpm

rpm -i isy-bsp-sgw-tomcat-(version).x86_64.rpm

Nach der Installation muss ggf. die Konfiguration des Wrappers angepasst werden. Dazu ist die Datei /opt/isy-bsp-ga/tomcat/conf/wrapper.conf anzupassen.

Wichtige Einstellungen umfassen:

das Setzen der Umgebungsvariable JAVA<X>_HOME auf den korrekten Wert (vor allem, wenn mehrere Java-Versionen installiert sind),

das Setzen von sinnvollen Werten für die Heap-Size (siehe Parameter wrapper.java.initmemory und wrapper.java.maxmemory).

Installation der IT-Systeme

Hinweis: Falls die Anwendung den traditionellen RPM Build (via ant und rpmbuild) verwendet, liegen die RPMs in einem zentralen Deployment-Modul.

Die RPM-Pakete können direkt über Kommandozeile installiert werden. Hierzu sind Root-Rechte erforderlich. Ein laufender Tomcat muss gegebenenfalls zuvor gestoppt werden.

Die manuelle Installation der IT-Systeme erfolgt mit:

rpm -fUhv isy-bsp-ga/target/RPMS/noarch/isy-bsp-ga-(version).noarch.rpm

rpm -fUhv isy-bsp-sgw/target/RPMS/noarch/isy-bsp-sgw-(version).noarch.rpm

rpm -fUhv isy-bsp-batch/target/RPMS/noarch/isy-bsp-batch-(version).noarch.rpm

Tipp: Die Option -U kann auch für die erstmalige Installation verwendet werden nicht nur für Upgrades.

Tabelle 6. Installationspfade der IT-Systeme

IT-System	RPM-Installationspfad	Owner
Beispielverzeichnis-GA	/opt/isy-bsp-ga	tomcat
Beispielverzeichnis-SGW	/opt/isy-bsp-sgw	tomcat
Beispielverzeichnis-Batch	/opt/isy-bsp-batch	Batch

Konfiguration der Anwendung

Als Ablageort und Stammverzeichnis der relativen Pfade in diesem Kapitel dient das Quellcode-Repository der Anwendung Beispielverzeichnis.

Konfiguration der Beispielverzeichnis-GA

Nach der Installation liegen die Konfigurationsdatein der isy-bsp-ga unter /etc/isy-bsp-ga.

Folgende Konfigurationsdateien müssen für die Konfiguration angepasst werden:

logback.xml,

isy-bsp-ga.properties,

jpa.properties,

(Liste der Konfigurationsdateien der Tomcat-Anwendung).

Änderungen an den Konfigurationsdateien müssen bei heruntergefahrener Anwendung durchgeführt werden.

Wichtig: Dieses Verhalten gilt nicht für die Konfigurationsdatei logback.xml. Änderungen an dieser Konfigurationsdatei können bei laufender Anwendung ausgeführt werden.

Konfigurationsdatei logback.xml

Die Konfigurationsdatei logback.xml enthält die Logging-Einstellungen und ist nach den Logging-Vorgaben aufgebaut. Nach der Installation muss dort der Name der künftigen Log-Datei angegeben werden. Dazu ist in den folgenden Zeilen der HOSTNAME durch den tatsächlichen Hostnamen zu ersetzen.

Beispielverzeichnis-GA: Log.Dateiname

<property name="LOGFILE_PATH" value="/var/log/isy-bsp-ga/HOSTNAME_isy-bsp-ga" />

Die Logs werden nach /var/log/isy-bsp-ga geschrieben.

Konfigurationsdatei isy-bsp-ga.properties

Die Datei isy-bsp-ga.properties enthält alle weiteren Konfigurationseinstellungen der Beispielverzeichnis-GA.

Eine ausführliche Erläuterung der einzelnen Parameter ist ebenfalls in der Datei selbst enthalten.

Folgende Werte müssen nach der Erstinstallation angepasst werden:

Tabelle 7. Konfigurationsparameter Beispielverzeichnis-GA

Konfigurationsparameter	Beschreibung
behoerdenverzeichnis.service.url	Die Adresse des Behördenverzeichnisses. Beispiel: http(s)://isy.local.vm:50001/plis-behoerdenverzeichnis
gui.behoerdenverzeichnis.url	Die Adresse der GUI des Behördenverzeichnisses. Beispiel: http(s)://isy.local.vm/plis-behoerdenverzeichnis
schluesselverzeichnis.service.url	Die Adresse des Schlüsselverzeichnisses. Beispiel: http(s)://isy.local.vm:50002/plis-schluesselverzeichnis
batch.benutzer.kennung	System-Benutzer zum Ausführen der Batches.
batch.benutzer.passwort	Passwort des System-Benutzers zum Ausführen der Batches.
…	…

Inhalt:
Weitere Möglichkeiten der Konfiguration werden ab hier beschrieben, thematisch abgegrenzt und jeweils mit einer eigenen Tabelle dokumentiert.

Quelle:
Systementwurf.

Dokumentationsform:
Freitext & Tabellen

Die Anbindung an den IAM-Service wird wie folgt konfiguriert:

Tabelle 8 . Konfigurations des IAM-Service

Konfigurationsparameter	Beschreibung
sic.keycloak.auth-server-url.0	Basis-URL des IAM-Service. Schema: http(s)://<keycloak-host>:<keycloak-port>/auth/
sic.keycloak.realm.0	Realm der Client zur Anmeldung. Schema: <realm-name>
sic.keycloak.resource.0	Name des Clients, der die Authentifizierung des Benutzers durchführen wird. Schema: <client-name>
sic.keycloak.bearer-only.0	Auf false gesetzt, da ein "Bearer"-Client keine Authentifizierung für andere vornehmen darf. Default: false
sic.keycloak.credentials-secret.0	Per Vorgabe sind Clients vertrauenswürdig ("confidential"), weswegen ein "client secret" angegeben werden muss. Schema: <client-secret>

Konfigartionsdatei jpa.properties

Die Datei jpa.properties enthält die Konfiguration der Datenbank-Verbindung.

Folgende Werte müssen nach der Erstinstallation angepasst werden:

Tabelle 9. Konfigurationsparameter jpa.properties

Konfigurationsparameter	Beschreibung
database.url	Gibt die Adresse, den Port und die SID der Datenbank an. Beispiel: jdbc:oracle:thin:@<Datenbankserver-Adresse>:<Datenbankport>:<SID>
database.username	Name des technischen Benutzers für den Zugriff auf die Datenbank.
database.password	Name des Passworts des technischen Benutzers für die Datenbank. Das Passwort ist nicht verschlüsselt.
database.schema.default	Name des Datenbank-Schemas.

Konfigurationsdatei isAlive

Für Wartungszwecke kann es notwendig sein, dass die Anwendung keine weiteren Anfragen vom Loadbalancer mehr zugewiesen bekommt.

Dazu überprüft das Loadbalancer-Servlet regelmäßig, ob die folgende (leere) Datei existiert.

/opt/isy-bsp-ga/etc/isAlive

Nach der Erstinstallation ist diese Datei noch nicht vorhanden. Sie muss so angelegt werden, dass der Nutzer tomcat die Datei lesen kann, z. B. wie folgt:

touch /opt/isy-bsp-ga/etc/isAlive

Konfiguration der Beispielverzeichnis-Batch

Nach der Installation liegen die Konfigurationsdateien der Batch-Anwendung unter /etc/isy-bsp-batch.

Die Konfiguration der Beispielverzeichnis-Batch erfolgt analog zur Konfiguration der Konfiguration der Beispielverzeichnis-GA: Allein die Logging-Konfiguration unterscheidet sich minimal. Es ist daher möglich, die bereits angepassten Konfigurationsdateien der Beispielverzeichnis-GA in die Konfigurationsverzeichnisse der Beispielverzeichnis-Batch zu kopieren. Anschließend müssen dort nur noch die abweichenden Einstellungen angepasst werden.

Konfigurationsdatei logback-batch.xml

Diese Konfigurationsdatei ist analog zur Datei logback.xml aufgebaut. Sie wird für das Logging der Batches verwendet. Die Unterschiede zur logback.xml der Beispielverzeichnis-GA liegen darin:

dass ein eigener Pfad für das Logging verwendet wird und,

dass die Batch-Id an den Namen der Log-Datei angehängt wird.

Außerdem ist für die Batches keine Log-Rotation aktiviert.

Konfigurationsdatei isy-bsp-ga.properties

Inhalt:
Beschreibung der Unterschiede bei der Konfiguration der Batch-Anwendung

Quelle:
Systementwurf

Dokumentationsform:
Freitext

Konfiguration des Beispielverzeichnis-SGW

Nach der Installation liegen die Konfigurationsdateien des Beispielverzeichnis-SGW unter /etc/isy-bsp-sgw.

Folgende Konfigurationsdateien müssen für die Konfiguration angepasst werden:

logback.xml,

servicegateway.properties.

Änderungen an den Konfigurationsdateien müssen bei heruntergefahrener Anwendung durchgeführt werden.

Wichtig: Dieses Verhalten gilt nicht für die Konfigurationsdatei logback.xml. Änderungen an dieser Konfigurationsdatei können bei laufender Anwendung ausgeführt werden.

Konfigurationsdatei logback.xml

Die Konfigurationsdatei logback.xml enthält die Logging-Einstellungen und ist nach den Logging-Vorgaben aufgebaut. Nach der Installation muss dort der Name der künftigen Log-Datei angegeben werden. Dazu ist in den folgenden Zeilen der HOSTNAME durch den tatsächlichen Hostnamen zu ersetzen.

Beispielverzeichnis-SGW: Log-Dateiname ist:

<property name="LOGFILE_PATH" value="/var/log/{it-system-sgw}/HOSTNAME_{it-system-sgw}" />

Die Logs werden nach /var/log/isy-bsp-sgw geschrieben.

Konfigurationsdatei servicegateway.properties

Die Datei servicegateway.properties enthält alle weiteren Konfigurationseinstellungen von Beispielverzeichnis-SGW.

Eine ausführliche Erläuterung der einzelnen Parameter ist ebenfalls in der Datei selbst enthalten.

Folgende Werte müssen nach der Erstinstallation angepasst werden:

Tabelle 10. Konfigurationsparameter servicegateway.properties

Konfigurationsparameter	Beschreibung
ga.service.url	Die Adresse der Beispielverzeichnis-GA. Beispiel: http(s)://isy.local.vm:50001/isy-bsp-ga
…	…

Konfigurationsdatei isAlive

Für Wartungszwecke kann es notwendig sein, dass die Anwendung keine weiteren Anfragen vom Loadbalancer mehr zugewiesen bekommt. Dazu überprüft das Loadbalancer-Servlet regelmäßig, ob die folgende (leere) Datei existiert

/opt/isy-bsp-sgw/etc/isAlive

Nach der Erstinstallation ist diese Datei noch nicht vorhanden. Sie muss so angelegt werden, dass der Nutzer tomcat die Datei lesen kann, z. B. wie folgt:

touch /opt/isy-bsp-sgw/etc/isAlive

Im Regelbetrieb ist das Loadbalancer-Servlet unter folgender URL erreichbar:

http(s)://<host>:<port>/Loadbalancer

Regulärer Wirkbetrieb

Log- und Konfigurationsdateien

Tabelle 11. Log-Dateien

Log-Datei	Inhalt / Bemerkung
Beispielverzeichnis-GA (/var/log/isy-bsp-ga)
HOSTNAME_isy-bsp-ga.log	Log-Datei
HOSTNAME_isy-bsp-ga_ZEITSTEMPEL.log	Rotierte Log-Datei
Beispielverzeichnis-SGW (/var/log/isy-bsp-sgw)
HOSTNAME_isy-bsp-sgw.log	Log-Datei
HOSTNAME_isy-bsp-sgw_ZEITSTEMPEL.log	Rotierte Log-Datei

Tabelle 12. Konfigurationsdateien

Konfigurationsdatei	Inhalt / Bemerkung
Beispielverzeichnis-GA (/etc/isy-bsp-ga)
isAlive	Steuerdatei für Loadbalancer
isy-bsp-ga.properties	Konfiguration der Anwendung
jpa.properties	Konfiguration der Datenbank-Verbindung
logback.xml	Logging-Konfiguration
Beispielverzeichnis-SGW (/etc/isy-bsp-sgw)
isAlive	Steuerdatei für Loadbalancer
isy-bsp-sgw.properties	Konfiguration der Anwendung
jpa.properties	Konfiguration der Datenbank-Verbindung
logback.xml	Logging-Konfiguration

Datenbankschema

Hinweis: Falls die Anwendung kein Datenbankschema enthält, kann dieser Abschnitt entfallen. Andernfalls ist der Verweis auf den Systementwurf der Anwendung zu korrigieren.

Das Datenbankschema ist vollständig im Systementwurf dokumentiert.

Hinweis: Falls die Anwendung ein Datenbankschema enthält, kann dieser Abschnitt entfallen.

Die Anwendung Beispielverzeichnis enthält kein Datenbankschema.

Start, Stopp, Statusprüfung der Server-Prozesse

Das Starten, Stoppen und die Statusüberprüfung der Tomcat-Installationen wird über ein Skript in /etc/init.d durchgeführt.

Tabelle 13 . Funktionen des Start-/Stopp-Skripts

Befehl	Beschreibung
/etc/init.d/isy-bsp-ga-tomcat start	Start der Beispielverzeichnis-GA
/etc/init.d/isy-bsp-ga-tomcat stop	Stopp der Beispielverzeichnis-GA
/etc/init.d/isy-bsp-ga-tomcat status	Statusüberprüfung der Beispielverzeichnis-GA
/etc/init.d/isy-bsp-sgw-tomcat start	Start des Beispielverzeichnis-SGW
/etc/init.d/isy-bsp-sgw-tomcat stop	Stopp des Beispielverzeichnis-SGW
/etc/init.d/isy-bsp-sgw-tomcat status	Statusüberprüfung des Beispielverzeichnis-SGW

Die Aufrufe werden in der Produktionsumgebung über die Batch-Steuerung in die betrieblichen Abläufe integriert. Das Skript wird dabei nicht in die Runlevel des Betriebssystems integriert. Die Tomcats werden ausschließlich über die betriebliche Batch-Steuerung gestartet und gestoppt.

In allen anderen Umgebungen wird das Skript von Hand aufgerufen. Ein Eintrag in die Runlevel kann bei Bedarf erfolgen.

Eine weitere Möglichkeit zur Überprüfung der Tomcat-Prozesse bietet folgender Befehl:

ps -u tomcat -f

Batch-Prozesse

In diesem Abschnitt wird das Ausführen der Batch-Anwendung beschrieben. Die Batches sind unabhängig voneinander, d.h. sie können in beliebiger Reihenfolge ausgeführt werden.

Die Batch-Anwendungen werden auf der Kommandozeile über ein Startskript gestartet. Das Startskript batch-ausfuehren.sh liegt in dem Verzeichnis:

/opt/isy-bsp-batch/bin/

Wichtig: Eine wichtige Voraussetzung für die Ausführung von Batches ist das Setzen der Variable JAVA<X>_HOME. Dieser Schritt ist in Installation des Default-Tomcats beschrieben.

Ausfüllhinweise

Inhalt:
Beschreibung aller Batches zu den einzelnen IT-Systemen.
Wichtig ist Abhängigkeiten zwischen den Batches zu beschreiben. Komplexere Abläufe sollen in Form von Batchketten beschrieben werden.
In der Regel wird pro Batch ein Unterkapitel angelegt.

Quelle:
Systementwurf

Dokumentationsform:
Tabelle, Freitext, Diagramme

Batch: Beispiel

Ausfüllhinweise

Inhalt:
Kurze Beschreibung, was der Batch macht. Genaue Dokumentation der Start-Parameter, Ausgaben bzw. und Return-Codes des Batchs.

Hinweise für den Betrieb, was ist bei einem Restart zu beachten?

Quelle:
Systementwurf

Dokumentationsform:
Tabelle, Freitext

Bezug zur Spezifikation: Batch BAT_…​

Dieser Batch prüft …

Aufruf

batch-ausfuehren.sh STARTART KONFIGURATION [ERGEBNIS]

Parameter

STARTART	-start oder –restart

Gibt an, ob das Skript neu gestartet wird oder ein abgebrochener Batch-Lauf fortgesetzt werden soll.

KONFIGURATION	-cfg /resources/batch/beispiel.properties

Gibt den auszuführenden Batch an.

ERGEBNIS	-Batchrahmen.Ergebnisdatei <ergebnisdatei.xml>

Gibt die XML-Datei an, in der die Ergebnisse gespeichert werden. Diese Angabe ist optional.

Rückgabewerte:

0:	Verarbeitung ohne Fehler durchgeführt

1:	Verarbeitung mit Fehlern durchgeführt

2:	Verarbeitung mit Fehlern abgebrochen

3:	Batch konnte wegen Fehlern in den Aufrufparametern nicht gestartet	werden

4:	Batch konnte wegen Fehlern in der Batch-Konfiguration nicht

gestartet werden

143:	Batch wurde vom Benutzer abgebrochen.

Ergebnis

Die Ergebnisdatei mit dem Verarbeitungsergebnis liegt im Ordner:

/opt/isy-bsp-batch/out/batch-beispiel_out.xml

Datei(en) mit Log-Informationen liegen im Ordner:

/var/log/isy-bsp-batch

oder an dem in der Konfigurationsdatei logback-batch.xml Konfigurationsdatei logback-batch.xml definierten Ort.

Monitoring

Ausfüllhinweise

Inhalt:
In diesem Kapitel wird beschrieben, welche Monitoring-Schnittstellen das System für den Betrieb anbietet. Im Wesentlichen sind dies die von der IsyFact über Micrometer bereitgestellten Metriken. Nicht beschrieben werden soll die konkrete Einbindung des Systems in die betriebliche Überwachung.

Quelle:
Systementwurf

Dokumentationsform:
Tabelle, Freitext

Standard-Metriken

Die Anwendung Beispielverzeichnis stellt folgende Standard-Metriken über den Endpunkt /actuator/metrics zur Verfügung.

Tabelle 14. Standard-Metriken

Metriken	Beschreibung	Namespace
JVM	Metriken zum Speicherverbrauch, zur Garbage Collection, Threads und geladenen Klassen.	jvm.
System	Metriken zur CPU-Auslastung, dem Dateisystem und der Uptime der Anwendung.	system.process. disk.
Application Startup	Metriken zur CPU-Auslastung, dem Dateisystem und der Uptime der Anwendung.	application.
Logger	Metriken zu Logging-Events.	logback.events.
Task Scheduling	Metriken zu ausgeführten Tasks.	…
Rest Services	Metriken zu aufgerufenen REST-Services.	http.server.requests
HTTP Client	Metriken zum Aufruf Services via HTTP. Ausgenommen hiervon ist der Aufruf von HTTP Invoker Services!	http.client.requests
Cache	Metriken zu applikationsspezifischen Caches.	cache
Hibernate	Metriken zu Datenbankzugriffen.	hibernate
Spring Data	Metriken zu Zugriffen über Repositories.	spring.data.repository.invocations

Ausfüllhinweise

Inhalt:
Metriken, die nicht angeboten werden, müssen aus der Tabelle entfernt werden. Ebenso müssen Lücken gefüllt werden, da sie anwendungsspezifisch sind.

Informationen der Beispielverzeichnis-GA und des Beispielverzeichnis-SGW

Tabelle 15. Metriken für HTTP Invoker Services

Metrik	Beschreibung	Namespace
Erfolgreiche Aufrufe	Liefert die Anzahl der nicht fehlerhaften Aufrufe in der letzten Minute.	anzahlAufrufe.LetzteMinute
Fehlerhafte Aufrufe	Liefert die Anzahl der fehlerhaften Aufrufe in der letzten Minute.	anzahlFehler.LetzteMinute
Fachlich fehlerhafte Aufrufe	Liefert die Anzahl der fachlich fehlerhaften Aufrufe in der letzten Minute.	anzahlFachlicheFehler.LetzteMinute
Durchschnittliche Dauer der Aufrufe	Liefert die durchschnittliche Dauer der letzten 10 Aufrufe in Millisekunden.	anzahlFachlicheFehler.LetzteMinute

Monitoring Batches

Die Batch-Anwendungen werden durch die Skripte zunächst ohne JMX gestartet. Wenn diese mit JMX verwaltet und beobachtet werden, so muss vor dem Aufruf des Startskriptes auf der Kommandozeile folgendes aufgerufen werden:

export JAVA_OPTS= "-Dcom.sun.management.jmxremote.port=28000"

Obiges Beispiel startet einen JMX-Agenten für den Port 28000. Der Port kann vom Betrieb frei gewählt werden.

Nach dem Aufruf des Skriptes sollte die Variable JAVA_OPTS auf leer gesetzt werden. Damit wird verhindert, dass andere Java-Programme die ggf. die gleiche Variable verwenden, automatisch ebenfalls über JMX gesteuert werden können.

export JAVA_OPTS=

Nach Aktivierung von JMX stellt jeder Batch-Prozess folgende Informationen per JMX bereit:

Tabelle 16. Überwachungsinformation der Batches

Bezeichnung	Beschreibung
de.bund.bva.visa.common:type=Batchrahmen,name=“Batchrahmen-Verarbeitung“
SaetzeGesamt	Die Gesamtanzahl der zu bearbeitenden Sätze. Falls diese nicht bekannt ist: -1
SaetzeVerarbeitet	Die Anzahl bereits verarbeiteter Sätze.
SchluesselLetzterSatz	Die Anzahl bereits verarbeiteter Sätze.
ZeitSeitLetztemSatz	Schlüssel des letzten verarbeiteten Satzes.
BatchId	Zeitraum in Millisekunden, der bereits für den aktuellen Satz benötigt wurde.

Backup und Recovery

Ausfüllhinweise

Inhalt:
Auflistung von Dateien, Datenbank-Schemata, die zum Verfahren gehören und die mit in das Backup einbezogen werden müssen. Dateien, die durch eine Neuinstallation des Verfahrens wiederhergestellt werden können, sind hier nicht aufzuführen.
Die Informationen in diesem Kapitel dienen als Grundlage für die Erstellung des Datensicherungskonzeptes, in dem dann Details zu Sicherungsintervallen, Abhängigkeiten zu anderen Systemen usw. beschrieben werden.

Quelle:
Systementwurf

Dokumentationsform:
Tabelle, Freitext

Hinweise für Störungsdiagnose und -behandlung

Verfügbare Hilfsmittel

Smoke-Test

Folgender Test kann ausgeführt werden, um zu prüfen ob die Anwendung läuft:

Im Info-Log (siehe Log- und Konfigurationsdateien) kann der Start des Systems nachvollzogen werden. Außerdem werden Fehlermeldungen des Selbsttests der Anwendung dort sowie im Error-Log geloggt.

Tabelle 17 Fehlercodes Smoke-Tests

Smoke-Test Checkliste	Erledigt
Prüfen der Logdateien der Anwendung: Das Error-Log der Anwendung darf nach dem Starten des Tomcats keine Fehler enthalten. Außerdem sollte die Wrapper-Logdatei als letzte Zeile folgenden Hinweis enthalten: INFO: Server startup in <ZAHL> ms
Verfügbarkeit der Services prüfen: Mit einem REST-Client den Endpunkt /actuator/health aufrufen. Die Health muss UP betragen.
Test der Batches Alle Batches ausführen. Die Log-Datei der Batch-Anwendung darf keine Fehler enthalten.

Debug-Logging

Die Konfiguration wird mit Log-Level INFO ausgeliefert, d.h. das Loggen von Debug-Ausgaben ist ausgeschaltet. Es kann aber wie folgt eingeschaltet werden:

Die Konfigurationsdatei logback.xml (bzw. logback-batch.xml) enthält folgende Zeile:

<root level="INFO">

Wird der Eintrag INFO auf DEBUG umgestellt, so werden auch Debug-Meldungen geschrieben.

Achtung: Das Logging sollte auf der Produktiv-Umgebung nie auf DEBUG gestellt werden. Aufgrund der zahlreichen und umfangreichen Datenausgabe könnte es zu Performance-Problemen kommen. Gleichzeitig ist nicht sichergestellt, dass keine sicherheitsrelevanten Daten ausgegeben werden.

Fehler und Fehlerbehebungsmaßnahmen

Die folgenden Abschnitte enthalten Tabellen, die bei der Identifikation und Behandlung von betrieblich relevanten Fehlern helfen. Die Tabellen geben sowohl Hilfestellung auf Basis von einzelnen Fehlercodes als auch in Form von wahrscheinlichen Fehlerszenarien.

Fehlercodes

Die folgende Tabelle beschreibt alle betrieblich relevanten Fehlercodes, mögliche Ursachen und Hinweise zur Identifikation des dahinter liegenden Fehlers und seiner Behebung.

Wichtig: Eine Übersicht aller Fehlercodes der IT-Systeme findet sich im Anhang C: Vollständige Liste der Fehlercodes.

Tabelle 18 Fehlercodes

Fehler	Mögliche Ursachen	Identifikation und Behebung
XXXXX50000	Die Datenbank ist nicht erreichbar.	Error-Log analysieren.
…	…	…

Ausfüllhinweise

Inhalt:
Auflistung der Fehler, die von den IT-Systemen der Anwendung auf den Log-Levels WARN und ERROR ausgegeben werden. Diese Fehler müssen nach den Vorgaben des Bausteins Logging betriebliche Relevanz besitzen!

Fehler auf dem Log-Level INFO, z.B. regulär vorkommende Fehler bei der fachlichen Bearbeitung oder in querschnittlicher Funktionalität, werden im Anhang beschrieben.

Es ist eine Tabelle pro IT-System anzulegen.

Quelle:
Systementwurf, Entwicklung

Dokumentationsform:
Tabelle

Fehlerszenarien

Die folgende Tabelle beschreibt alle betrieblich relevanten Fehlersituationen, ihre Entstehungsorte sowie Hinweise darauf, wie die IT-Systeme mit diesem Fehlerszenario umgehen und reagieren.

Tabelle 19 Fehlerszenarien Beispielverzeichnis

Nr.	Fehlersituation	Ort der Entstehung	Behandlung und Reaktion des Systems
1	Nachbarsystem nicht erreichbar	Beispielverzeichnis-GA, Beispielverzeichnis-Batch	Das System schreibt den Fehler in die Log-Datei und gibt den für den Anwender maskierten Fehler als XXXXX99999 über die Außenschnittstelle an den Aufrufer zurück. Interne Fehlercodes: …​
2	Konfigurationsfehler	Beispielverzeichnis-GA, Beispielverzeichnis-Batch	Die Anwendung startet nicht. Fehlercode: …​
3	Konfigurationsfehler	Beispielverzeichnis-GA, Beispielverzeichnis-Batch	Die Anwendung startet. Zur Laufzeit kommt es vermehrt zum Fehlercode …​
4	Technischer Fehler in der Verarbeitung	Beispielverzeichnis-GA, Beispielverzeichnis-Batch	Das System schreibt den Fehler in die Log-Datei und gibt den für den Anwender maskierten Fehler als XXXXX99999 über die Außenschnittstelle an den Aufrufer zurück. Interne Fehlercodes: …​

Ausfüllhinweise

Inhalt:
Auflistung von Fehlerszenarien, die zu betrieblich lösbaren Fehlern führen.

"Behandlung und Reaktion des Systems" meint nicht die Fehlerbehandlung durch den Betrieb, sondern wie die IT-Systeme mit dem Fehlerszenario umgehen und auf welchen Kanälen (z.B. über Schnittstellen oder Logs) sie wie reagieren.

Quelle:
Systementwurf, Entwicklung

Dokumentationsform:
Tabelle

Anhang

Anhang A: Historie

Die folgende Tabelle zeigt eine grobe Historie der Anwendung Beispielverzeichnis.

Tabelle 20 . Historie Beispielverzeichnis

Version	Datum des Release	Wichtige Änderungen
3.0.0	04.03.2020	Neue Schnittstelle für mehr Beispiele hinzugefügt. Tech-Update auf IsyFact 2.1.
…	…	…

Inhalt:
Auflistung der wichtigsten Versionen der Anwendung und der zugehörigen Änderungen. In der Tabelle sollten, falls Semantic Versioning eingehalten wird, hauptsächlich Major Releases aufgeführt sein.

Es reicht aus, die dargestellten Versionen auf die im Wesentlichen unterstützten Versionen zu begrenzen. Veraltete (d.h. nicht mehr in Weiterentwicklung befindliche) Versionen der Anwendung müssen nicht aufgeführt werden.

Dokumentationsform:
Tabelle

Anhang B. Fachliches Glossar

Inhalt:
Auflistung der wichtigsten fachlichen Begriffe, die betrieblich relevant sind. Dies sind z.B. Begriffe, die für das Verständnis im Zuge der Konfiguration oder Fehlerbehandlung erforderlich oder hilfreich sind.

Ein reiner Verweis auf die Systemspezifikation reicht nicht aus, auch wenn dies ggf. zu redundanten Inhalten führt. Für ein tiefergehendes Verständnis darf hingegen gern auf die Systemspezifikation verwiesen werden.

Quelle:

Systemspezifikation

Dokumentationsform:
Tabelle

Anhang C: Vollständige Liste der Fehlercodes

Tabelle 21 . Fehlercodes Beispielverzeichnis-GA

Fehler	Mögliche Ursachen	Identifikation und Behebung
XXXXX12345	Ungültige Parameter für interne Berechnung.	Entwicklung kontaktieren.
…	…	…

Inhalt:
Auflistung aller Fehler, die ein IT-System ausgeben kann. Die Tabelle geht über die Tabelle in Fehlercodes hinaus, da sie auch Fehler beinhaltet, die betrieblich nicht relevant sind. Solche Fehler können auf unvorhergesehene fachliche und technische Konstellationen oder auf Programmierfehler hinweisen.

Es ist eine Tabelle pro IT-System anzulegen.

Der Hauptnutzen dieser Tabelle in Verbindung mit der Tabelle in Fehlercodes ist, dass schnell klar ist, ob der Fehler betrieblich behoben werden kann und, falls nicht, wer zu informieren ist.

Quelle:

Entwicklung

Dokumentationsform:
Tabelle

Quellen

Dieses Kapitel gehört nicht zum Inhalt und listet die Dokumente auf, auf die das Systemhandbuch verweist.

Systemspezifikation

Systementwurf