Technische Dokumentation

Einleitung

WIAG stellt als eine frei verfügbare, browserbasierte Anwendung Forschungsdaten aus Sach- und Schriftquellen des Mittelalters und der Frühen Neuzeit zur Verfügung. Die Forschungsdaten werden gut erreichbar, interoperabel und nachnutzbar aufbereitet und veröffentlicht. Eingebettet in eine fachspezifische Wissensplattform, ermöglicht ein Redaktionssystem die Strukturierung, Standardisierung und Bereitstellung von Forschungsdaten.

Mit den umfangreichen Datensammlungen der Göttinger Akademieprojekte Deutsche Inschriften und Germania Sacra besteht eine zentrale Wissensbasis für die Mittelalter- und Frühneuzeitforschung.

Framework

Die Webanwendung WIAG ist als ein sogenannter LAMP-Stack aufgebaut: Auf einem UNIX- oder Linux-artigen Betriebsystem läuft ein Apache Webserver. Die Daten werden in einer MySQL-Datenbank verwaltet (alternativ MariaDb), und ein PHP-Framework wird verwendet, um die Seiten der Anwendung zu gestalten und mit Daten zu versorgen.

Für WIAG ist das PHP-Framework Symfony im Einsatz. Die aktuelle WIAG-Version von Symfony ist 5.4.22 (Long-Term Support Release mit Sicherheits-Patches bis Ende 2025).

WIAG verwendet TWIG-Templates und Bootstrap für die Gestaltung der Seiten. JavaScript wird über das Webpack API Webpack Encore und Stimulus eingebunden.

WIAG übernimmt die von Symfony vorgegebene Verzeichnisstruktur.

  • src/Controller: Klassen, welche die Anfragen entgegennehmen und eine HTML-Seite zurückliefern.
  • src/Entity: Datencontainer mit Zugriffsfunktionen und Funktionen zur Kombination von Datenfeldern. Im Allgemeinen entspricht jeweils eine Klasse einer Tabelle in der Datenbank.
  • src/Repository: Klassen zur Abfrage der Datenbank.
  • src/Service: Hilfsklassen mit Funktionen, welche die Controller-Klassen für bestimmte Aufgaben unterstützen.
  • src/Form: Formulare für Suchabfragen.
  • src/Form/Model: Datencontainer für Suchabfragen.
  • templates: TWIG-Templates mit dem Seitenaufbau.
  • assets/styles/app.scss: CSS-Klassen und -Parameter.
  • assets/controllers: Stimulus Controller (JavaScript).

WIAG installieren

Die Web-Anwendung verwendet eine MySQL-Datenbank oder MariaDB. Die Datenbank ist entsprechend dem Datenmodell aufzusetzen und zu befüllen.

Der Quellcode für WIAG liegt in einem GitHub-Repository und kann von dort bezogen werden. Man wechselt in ein geeignetes Verzeichnis und kopiert die Quellen von dort mit:

git clone github.com/WIAG-ADW-GOE/WIAGweb2.git

Es wird ein Verzeichnis WIAGweb2 angelegt. Es enthält die Datei .env. In diese Datei sind die Angaben zum Datenbank-Zugang einzutragen.

DATABASE_URL="mysql://db_user@127.0.0.1:3306/db_name?serverVersion=5.7" DATABASE_PASSWORD=db_password

Für eine Produktiv-Umgebung wird das Password verschlüsselt. Siehe Symfony Secrets.

Im Verzeichnis WIAGweb2 lädt man die Symfony-Module mit dem PHP dependency manager composer:

cd WIAGweb2

composer install

Die Node.js-Module lädt man mit dem package manager yarn:

yarn install

Es sind noch die WIAG-eigenen Style-sheets und JavaScript-Dateien zu erzeugen mit:

cd public yarn build

Hierzu finden sich Erläuterungen in der Dokumentation von Webpack encore.

Ein lokaler Server wird im Projektverzeichnis von WIAG gestartet:

cd ..

symfony serve

Die Web-Anwendung lässt sich mit dem Browser öffnen unter https:localhost:8000.

Inhaltliche Struktur und Datenmodell

Themen

WIAG gliedert sich nach Themen. Bisher umfasst die Anwendung Bistümer des Alten Reiches, Bischöfe des Alten Reiches, Domherren des Alten Reiches und Priester der mittelalterlichen Diözese Utrecht. In der Abfrage spiegelt sich diese Gliederung wider in den Menüeinträgen unter dem Hauptmenüpunkt „Datensammlungen“, bzw. in den Schaltflächen auf der Einstiegsseite.

Den Themen entsprechen datentechnisch Einträge in der der Tabelle item_type. Die Tabelle enthält weitere Einträge zu Entitäten, welche die für die Erfassung und Beschreibung der Karrierewege von Personen genutzt werden: Kloster, Domstift, religiöser Orden und Amt.

Auszug aus item_type.

id note (table_name)

1 Diözese des Alten Reiches (diocese)

2 Kloster (institution)

3 Domstift (institution)

4 Bischof oder Patriarch des Alten Reiches (person)

5 Domherr des Alten Reiches (person)

6 Domherr des Alten Reiches aus der Personendatenbank der Germania Sacra (person)

7 Religiöser Orden (religious_order)

8 Amt, Rolle (role)

9 Bischof des Alten Reiches aus der Personendatenbank der Germania Sacra (person)

10 Priester des Bistums Utrecht nach Stapel (person)

Datenmodell

Metadaten, Inhalte und technische Hilfsdaten entsprechen jeweils einer eigenen Gruppe von Tabellen. Metadaten zum Redaktionsprozess enthalten die Tabellen: user_wiag, item, item_type, item_property_type, place_type

Technische Hilfstabellen, z.B. um Abfragen effizienter zu machen, sind die Tabellen name_lookup und canon_lookup.

Die restlichen Tabellen enthalten Eigenschaften zu Personen und deren Karrieren. Eine vollständige Übersicht findet sich in ein einem ergänzenden Dokument zu diesem Handbuch.

Datenabfrage HTML

Suche und Navigation sind über die Themenfelder hinweg in ähnlicher Art und Weise aufgebaut. Die Themenfelder umfassen im Moment

  • Die Patriarchen, Erzbischöfe, Bischöfe, Weihbischöfe und weitere diözesane Leitungspersonen des Alten Reiches (nach Erwin Gatz)
  • Die Erzbistümer und Bistümer des Alten Reiches (nach Erwin Gatz)
  • Domherren des Alten Reiches
  • Priester des Bistums Utrecht

Nach dem Aufruf eines der Themen erscheint im oberen Teil der Seite eine Suchmaske mit mehreren Filterfeldern. Die Filter sind untereinander auf der Ebene der Personen UND-verknüpft, das heißt, ein Element in der Trefferliste muss alle Kriterien erfüllen. Eine Ausnahme sind die Felder Erzbistum/Bistum und Amt. Sie sind auf der Ebene eines Amtseintrages UND-verknüpft, das heißt, eine Person wird nur dann in die Trefferliste aufgenommen, wenn sie in Amt mit der gesuchten Bezeichnung in einem Bistum mit der gesuchten Bezeichnung innehatte. Dabei werden auch Teilzeichenketten in den Filterfeldern akzeptiert. Die Eingabe „berg“ findet also sowohl „Henneberg“ als auch „Arnbergh“ oder „Bergheim“.

Suchmaske

Das Feld Name prüft Kombinationen von Vorname, Namenspräfix und Familienname, sowie Namensvarianten. Damit die Suche effizient ist, wird die technische Hilfstabelle name_lookup verwendet. Die Tabelle verzeichnet Kombinationen aus Vornamen und Familiennamen mit und ohne Namenspräfix. So kann Joseph Dominikus Reichsgraf von Lamberg auch gefunden werden, indem man lediglich „Joseph Lamberg“ in das Feld „Name“ eingibt.

Weiteres Beispiel

  • Johann von Eppes
  • Johann von Eps
  • Johann von Aps
  • Jean von Eppes
  • Jean von Eps
  • Johann Eppes
  • Johann Eps
  • Johann Aps
  • Jean Eppes
  • Jean Eps

Das Feld Erzbistum/Bistum sucht Personen aus dem Themenfeld „Bischof“, die mindestens ein Amt in dem betreffenden Bistum haben. Diesem Feld entspricht für das Themenfeld „Domherr“ das Feld Domstift.

Das Feld Amt prüft auf Personen, die mindestens ein Amt mit der betreffenden Bezeichnung innehatten. Die Felder Erzbistum/Bistum und Amt sind, wie oben beschrieben, auf der Ebenen eines Amtseintrags UND-verknüpft.

Das Feld Jahr prüft auf Personen, deren Amtsausübung oder Lebensspanne das angegebene Jahr umfasst. Toleranzwert ist 1. Siehe ItemRepository::MARGIN_YEAR und CanonLookupRepository::MARGIN_YEAR.

Das Feld Nummer prüft auf Personen, deren WIAG-ID die angegebene Nummer/ID zumindest enthält. Es werden auch Einträge gefunden, wenn eine externe ID (GND, Digitales Personenregister der Germania Sacra, Wikidata, VIAF) die angegeben Nummer/ID enthält.

Nach Priestern des Bistums Utrecht kann auch nach Geburtsort und Ordenszugehörigkeit über das Feld Orden gesucht werden.

Die Abfrage verwendet das Formularsystem von Symfony und wertet POST-Requests aus.

Die Suche kann für die Themen „Bischof“ und „Domherr“ über sogenannte Facetten verfeinert werden. Die Facetten schränken die Suche ein in Bezug auf eine oder mehrere der Folgenden Kriterien: Bistum, Domstift, Amt, Ort oder externe URL. Facetten ermöglichen es, verschiedene Alternativen zu kombinieren, also mit logisch ODER zu verknüpfen, um zum Beispiel die Domherren aus den Domstiften Lübeck und Osnabrück zusammen aufzurufen. Die Facetten liefern zugleich eine quantitative Übersicht über die Ergebnislisten, indem sie die jeweiligen Trefferzahlen auflisten.

Ansichten/Navigation

In jedem der Themenfelder zeigt WIAG als Ergebnis der Suche eine Liste der Treffer mit einigen ausgewählten Informationen an. Zu jedem Treffer kann eine Detailansicht mit den vollstängigen Angaben geöffnet werden. In der Detailansicht sind auch die jeweiligen Referenzwerke angegeben, aus denen die Amtsangaben entnommen sind. Die Daten können ferner sowohl aus der Listenansicht heraus als auch für die Detailansicht in einem strukturierten Format aufgerufen werden. Als Formate werden angeboten: CSV, JSON, RDF-XML, JSON-LD.

Verlinkungen

Die Detailansichten verlinken zu weiterführenden Informationen innerhalb und außerhalb von WIAG. Ortsangaben, wie zum Beispiel der Bischofssitz von Bistümern, verweisen auf eine Seite bei GeoNames. Externe Identifier verweisen auf Einträge bei den entsprechenden Datensammlungen. Die wichtigsten sind:

Die Amtseinträge für Bischofsämtern verweisen auf die Seite des jeweiligen Bistums innerhalb von WIAG. Die Amtseinträge von anderen Ämtern verweisen häufig auf Domstifte oder Klöster aus der Klosterdatenbank der Germania Sacra.

Inhalte aus mehreren Quellen

Es gibt Personen, die in mehreren Quellen beschrieben sind. Die relevanten Quellen sind hierbei:

  • Digitales Personenregister der Germania Sacra,
  • Domherren-Datenbank,
  • Gatz-Bischofslisten.

Diese Personen können je nach Quellen sowohl über das Thema „Bischof“ als auch über das Thema „Domherr“ gefunden werden.

Für die Anzeige des Namens und der Lebensdaten werden die Daten aus der Gatz-Bischofsliste und aus der Domherrendatenbank priorisiert. D.h. Angaben zum Namen aus der Personendatenbank sind nur dann sichtbar, wenn sie die einzige Quelle ist. Beispiele: Burkard, WIAG-Pers-EPISCGatz-05243-001, ist in der Personendatenbank mit „Burghard I.“ eingetragen. „Burkhard“ ist der Name, der auf der Detailseite erscheint. Johann von Rüttich, WIAG-Pers-CANON-90865-001, hingegen ist nur in der Personendatenbank verzeichnet und erscheint folglich mit dem Namen, der dort angegeben ist. Falls unterschiedliche Angaben in den Gatz-Bischofslisten und der Domherrendatenbank vorliegen werden beide Versionen durch einen Schrägstrich, “/”, getrennt angegegen. Beispiel: Heinrich/Heinrich Graf von Henneberg, WIAG-Pers-EPISCGatz-05067-001, oder Franz Karl Ludwig Reichsfreiherr von Boos zu Waldeck/Karl Franz Boos von Waldeck, WIAG-Pers-EPISCGatz-10069-001.

Die Ämterlisten der Personen werden ebenfalls für die Anzeige nach der Quelle priorisiert. Listenansicht: Bei Bischöfen erscheinen die Ämter aus den Gatz-Bischofslisten. Bei Domherren erscheinen bevorzugt die Ämter aus der Domherrendatenbank, dann diejenigen aus der Personendatenbank. Falls es mehr als eine Quelle gibt, wird das durch eine Ellipse “…” sichtbar gemacht. Detailansicht: Hier erscheinen die Ämter aus allen verfügbaren Quellen nach Quelle in Abschnitten gegliedert. Beim Zugang über das Thema „Bischöfe des Alten Reiches“ sind im ersten Abschnitt die Ämter aus den Gatz-Bischofslisten zu sehen, gefolgt von Ämtern aus der Personendatenbank und schließlich den Ämtern aus der Domherrendatenbank. Beim Zugang über das Thema „Domherren des Alten Reiches“ sind im ersten Abschnitt die Ämter ist die Reihenfolge: Domherren-Datenbank, Personendatenbank, Gatz-Bischofslisten. Beispiel: Heinrich/Heinrich Graf von Henneberg, WIAG-Pers-EPISCGatz-05067-001, oder Albert von Hoya, WIAG-Pers-EPISCGatz-05438-001.

Abfrage der Datenbank

Themenfeld „Bischof“: Die Angaben zu Ämtern aus mehreren Quellen werden über die Einträge in der Tabelle url_external zusammengeführt. Siehe Quelltextdatei ItemRepository.php.

Themenfeld „Domherr“: Hier wird die Tabellen canon_lookup als technische Hilfstabelle verwendet. Die Tabelle wurde eingerichtet, um einen effzienten Zugriff auf die unterschiedlichen Quellen zu haben, die schon bei der Listenansicht eine Rolle spielen. Sie hat folgenden Aufbau:

id     person_id_name     person_id_role     prio_role
534667          703426          767308          1
534666          703426          703426          2
531999          703427          738539          1
531998          703427          768046          2
531997          703427          703427          3

id ist eine fortlaufende tabelleneigene ID. person_id_name ist die ID der Person aus der Quelle, deren Namensdaten relevant sind. person_id_role ist die ID der Person aus der Quelle, deren Amtsdaten relevant sind. prio_role ist die Reihenfolge für die Anzeige über den Zugang „Domherren des Alten Reiches“. Es kommen folgende Kombinationen in Bezug auf die Quellen vor:

  • nur Digitales Personenregister der Germania Sacra
  • nur Domherrendatenbank
  • Domherrendatebank mit Digitalem Personenregister
  • Gatz-Bischofslisten mit Digitalem Personenregister, Beispiel: Heinrich Hartard Freiherr von Rollingen, WIAG-Pers-EPISCGatz-10628-001
  • Gatz-Bischofslisten mit Domherrendatebank
  • Gatz-Bischofslisten mit Domherrendatebank und Digitalem Person

Redaktion

Die Redaktionsseiten machen die zu bearbeitenden Datensätze ähnlich wie die Abfrageseiten über ein Formular und eine Listenausgabe zugänglich. Die Suchmaske ist erweitert um weitere Eingabefelder, wie z.B. Referenz, und um Felder zu redaktionellen Metadaten, z.B. zum Datum der letzten Änderung. Hier ist es möglich, auch Datumsbereiche anzugeben.

PHP beschränkt die Zahl der Eingabevariablen auf 1000. Daher werden die Eingabemasken für die einzelnen Datensätze bei Bedarf via AJAX nachgeladen. Die Zahl der gleichzeitig an den Server übermittelten Variablen bleibt so begrenzt. Die Eingabmasken werden nicht über das Symfony-Formular-Modul erzeugt, sondern direkt in den Templates aufgebaut. Die Eingabmasken sind erweiterbar, da eine Person eine theoretisch beliebig große Anzahl von Ämtern, externen Identifiern oder Referenzen haben kann. Die entsprechende Funktionalität ist mithilfe von Stimulus umgesetzt; entsprechende Teilformulare werden vom Server nachgeladen.

Das Redaktionsmodul umfasst Eingabemasken für

  • Literatur/Referenzen,
  • Normdaten/Externe Ressourcen,
  • Attribute: frei vergebbare Attribute zu Personen oder zu Amtsangaben,
  • Ämter,
  • Klöster: hier wird ein Abfrage für aktuelle Daten aus der Klosterdatenbank angestoßen,
  • Bistümer,
  • Personen des Themenfelds „Bischof“,
  • Personen des Themenfelds „Domherr“.

API

Die Daten zu Personen und Bistümern können in verschiedenen Formaten auch über ein API (Application Programming Interface) abgerufen werden. Die URLs lauten

Parameter-Liste: Parameter-Zuordnung(&Parameter-Zuordnung)
Parameter-Zuordnung: parameter=wert

Beispiel: https://wiag-vocab.adw-goe.de/domherr/data?name=Hohen&domstift=Bamberg

Folgende Ausgabeformate werden unterstützt: CSV, JSON, RDF-XML, JSON-LD. Das Format wird über den Parameter format angegeben. Ohne eine Angabe zu diesem Parameter wird JSON ausgeliefert.

Die Paramter entsprechen dabei den Eingabefeldern der Suchmaske in der Abfrage

  • Thema „Bischof“: name, diocese, office, year, someid
  • Thema „Domherr“: name, domstift, office, year, someid
  • Thema „Bistum“: name