IsyFact Systemhandbuch <System>

Vorlage

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

Creative Commons Namensnennung Die Nutzung ist unter den Lizenzbedingungen der Creative Commons Namensnennung 4.0 International gestattet.

Allgemeine Hinweise zur Dokumentvorlage

Dieses Kapitel wird in der finalen Fassung des Systemhandbuchs entfernt.

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.

Verwendung von Dokumentattributen

Die Vorlage verwendet für zentrale Begriffe Dokumentattribute, damit diese an zentraler Stelle änderbar sind.

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.

1. 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).

Das Kapitel Ü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.

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

Das Kapitel 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 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.

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

Das Kapitel Hinweise für Störungsdiagnose 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.

2. Ü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.

2.1. Fachliche Beschreibung

Kurze, prägnante fachliche Darstellung der Anwendung. […]

Abbildung 1. Beispielverzeichnis: Fachlicher Kontext

Weitere fachliche Details können in der 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

2.1.1. 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

2.1.2. 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

2.2. Technische Beschreibung

Kurze, prägnante technische Darstellung der Anwendung. […]

Abbildung 2. Beispielverzeichnis: Technischer Kontext

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

2.2.1. Laufzeitumgebung

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

Tabelle 2. Beispielverzeichnis: Produkte der Laufzeitumgebung
Kategorie	Name	Version
Java Virtual Machine	OpenJDK (Eclipse Temurin von Adoptium)	17.x
Servlet-Container	Apache Tomcat	8.5.x
RDBMS	(Datenbank)	(Version)
…	…	…

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 weitergehende Bemerkungen)

2.2.2. 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	Schnittstelle	Version	Essenziell?
`isy-nachbar-b-gk`	(Schnittstelle)	(Version)	nein
`isy-nachbar-c-qk`	(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 weitergehende Bemerkungen)

2.2.3. Verteilungssicht

Inhalt

Deployment-Diagramm des Systems mit 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

3. Bau der Anwendung

Das Bauen der Anwendung erfolgt über einen standardisierten Build-Mechanismus. Der Build benötigt die in Tabelle 1 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 Development 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

3.1. Bau der Beispielverzeichnis-GA und Beispielverzeichnis-Batch

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:

Listing 1. Maven-Befehl zum Build der Beispielverzeichnis-GA & Beispielverzeichnis-Batch

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

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

3.2. Bau der Beispielverzeichnis-GA und Beispielverzeichnis-Batch

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:

Listing 2. Maven-Befehl zum Build der Beispielverzeichnis-GA & Beispielverzeichnis-Batch

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

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 jeweiligen Modul unter target die 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

3.3. 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

4. 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

4.1. 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.

4.2. Einrichten der Datenbank

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

Die DB-Skripte liegen im Verzeichnis

Listing 3. Pfad für die Datenbankskripte

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.

4.3. 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.

Listing 4. Benutzerverzeichnisrollen anlegen

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.

4.4. 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.

4.5. Apache Konfiguration

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

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

4.5.1. `uriworkermap.properties`

Listing 5. Redirect an den Worker

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

4.5.2. `workers.properties`

Listing 6. Worker-Konfiguration

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.

4.6. Mail-Server Konfiguration

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

5. Installation der Anwendung

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

5.1. Installation der 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:

Listing 7. Installation der Tomcats via RPM

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).

5.2. Installation der IT-Systeme

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.

Listing 8. Manuelle Installation der IT-Systeme

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

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

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`

6. Konfiguration der Anwendung

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

6.1. Konfiguration der Beispielverzeichnis-GA

Nach der Installation liegen die Konfigurationsdateien 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.

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

6.1.1. 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.

Listing 9. 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.

6.1.2. 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. Konfiguration 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>`

6.1.3. Konfigurationsdatei 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.

6.1.4. 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

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

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

6.2. 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 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.

6.2.1. 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.

6.2.2. Konfigurationsdatei `isy-bsp-ga.properties`

Inhalt: Beschreibung der Unterschiede bei der Konfiguration der Batch-Anwendung
Quelle: Systementwurf
Dokumentationsform: Freitext

6.3. 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.

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

6.3.1. Konfigurationsdatei `logback.xml`

Listing 10. Beispielverzeichnis-SGW: Log-Dateiname

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

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

6.3.2. 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`
`…`	…

6.3.3. 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

7. Regulärer Wirkbetrieb

7.1. 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

Der Platzhalter HOSTNAME im Dateinamen steht für den Namen des Servers, auf dem das IT-System ausgeführt wird. Die ZEITSTEMPEL werden durch die Log-Rotation erzeugt und markieren ältere Log-Dateien.

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

7.2. Datenbankschema

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.

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

Die Anwendung Beispielverzeichnis enthält kein Datenbankschema.

7.3. 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

7.4. 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/

Eine wichtige Voraussetzung für die Ausführung von Batches ist das Setzen der Variable JAVA<X>_HOME. Dieser Schritt ist in Installation der 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 Batch-Ketten beschrieben werden.

In der Regel wird pro Batch ein Unterkapitel angelegt.
Quelle: Systementwurf
Dokumentationsform: Tabelle, Freitext, Diagramme

7.4.1. Batch: Beispiel

Ausfüllhinweise

Inhalt: Kurze Beschreibung was der Batch macht. Genaue Dokumentation der Start-Parameter, Ausgaben bzw. und Return-Codes des Batches.
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 …

7.4.1.1. Aufruf

batch-ausfuehren.sh STARTART KONFIGURATION [ERGEBNIS]

7.4.1.2. 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.

7.4.1.3. Rückgabewerte

Listing 11. Rückgabewerte des Beispiel-Batches

    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.

7.4.1.4. 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 definierten Ort.

7.5. 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

7.5.1. 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 Startzeit 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: Metriken, die nicht angeboten werden, müssen aus der Tabelle entfernt werden. Ebenso müssen Lücken gefüllt werden, da sie anwendungsspezifisch sind.

7.5.2. 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.	`durchschnittsDauer.LetzteAufrufe`

7.5.3. 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`	Schlüssel des letzten verarbeiteten Satzes.
`ZeitSeitLetztemSatz`	Zeitraum in Millisekunden, der bereits für den aktuellen Satz benötigt wurde.
`BatchId`	Die ID des aktuellen Batches.

7.6. 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

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

8.1. Verfügbare Hilfsmittel

8.1.1. Smoke-Test

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

In der Log-Datei (siehe Kapitel Log- und Konfigurationsdateien) kann der Start des Systems nachvollzogen werden. Außerdem werden Fehlermeldungen des Selbsttests der Anwendung dort ausgegeben.

Tabelle 17. Fehlercodes Smoke-Tests
Smoke-Test Checkliste	Erledigt
Prüfen der Log-Datei: Die Log-Datei der Anwendung darf nach dem Starten des Tomcats keine Fehler enthalten. Außerdem sollte die Wrapper-Log-Datei 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.

8.1.2. 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.

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

8.2. 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.

8.2.1. Fehlercodes

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

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

Tabelle 18. Fehlercodes Beispielverzeichnis-GA
Fehler	Mögliche Ursachen	Identifikation und Behebung
XXXXX50000	Die Datenbank ist nicht erreichbar.	Log-Datei 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

8.2.2. 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, Liste, Freitext

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

Die Dokumentation der IsyFact enthält ebenfalls Vorlagen zu diesen Dokumenten.

IsyFact Systemhandbuch <System>

Vorlage

Allgemeine Hinweise zur Dokumentvorlage

Zweck dieses Dokuments

Verwendung von Dokumentattributen

Verwendung von Namenskonventionen

1. Einleitung

2. Überblick

2.1. Fachliche Beschreibung

2.1.1. Anwendergruppen

2.1.2. Anwendungsfälle

2.2. Technische Beschreibung

2.2.1. Laufzeitumgebung

2.2.2. Nachbarsysteme

2.2.3. Verteilungssicht

3. Bau der Anwendung

3.1. Bau der Beispielverzeichnis-GA und Beispielverzeichnis-Batch

3.2. Bau der Beispielverzeichnis-GA und Beispielverzeichnis-Batch

3.3. Bau des Beispielverzeichnis-SGW

4. Vorbereitung der Systemumgebung

4.1. Anlegen der Betriebssystemnutzer und -gruppen

4.2. Einrichten der Datenbank

4.3. Konfiguration Benutzer- und Behördenverzeichnis

4.4. Schlüsselverzeichnis

4.5. Apache Konfiguration

4.5.1. uriworkermap.properties

4.5.2. workers.properties

4.6. Mail-Server Konfiguration

5. Installation der Anwendung

5.1. Installation der Default-Tomcats

5.2. Installation der IT-Systeme

6. Konfiguration der Anwendung

6.1. Konfiguration der Beispielverzeichnis-GA

6.1.1. Konfigurationsdatei logback.xml

6.1.2. Konfigurationsdatei isy-bsp-ga.properties

6.1.3. Konfigurationsdatei jpa.properties

6.1.4. Konfigurationsdatei isAlive

6.2. Konfiguration der Beispielverzeichnis-Batch

6.2.1. Konfigurationsdatei logback-batch.xml

6.2.2. Konfigurationsdatei isy-bsp-ga.properties

6.3. Konfiguration des Beispielverzeichnis-SGW

6.3.1. Konfigurationsdatei logback.xml

6.3.2. Konfigurationsdatei servicegateway.properties

6.3.3. Konfigurationsdatei isAlive

7. Regulärer Wirkbetrieb

7.1. Log- und Konfigurationsdateien

7.2. Datenbankschema

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

7.4. Batch-Prozesse

7.4.1. Batch: Beispiel

7.4.1.1. Aufruf

7.4.1.2. Parameter

7.4.1.3. Rückgabewerte

7.4.1.4. Ergebnis

7.5. Monitoring

7.5.1. Standard-Metriken

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

7.5.3. Monitoring Batches

7.6. Backup und Recovery

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

8.1. Verfügbare Hilfsmittel

8.1.1. Smoke-Test

8.1.2. Debug-Logging

8.2. Fehler und Fehlerbehebungsmaßnahmen

8.2.1. Fehlercodes

8.2.2. Fehlerszenarien

Anhang

Anhang A: Historie

Anhang B: Fachliches Glossar

Anhang C: Vollständige Liste der Fehlercodes

Quellen

Systemspezifikation & Systementwurf

4.5.1. `uriworkermap.properties`

4.5.2. `workers.properties`

6.1.1. Konfigurationsdatei `logback.xml`

6.1.2. Konfigurationsdatei `isy-bsp-ga.properties`

6.2.1. Konfigurationsdatei `logback-batch.xml`

6.2.2. Konfigurationsdatei `isy-bsp-ga.properties`

6.3.1. Konfigurationsdatei `logback.xml`