An dieser Stelle entsteht die öffentliche Dokumentation für Epigraf 5. Diese Seite ist noch in Bearbeitung.

Mit der Importfunktion von Epigraf können CSV-Dateien und XML-Dateien in die Datenbanken eingespielt werden - darüber lassen sich sowohl neue Artikel, Abschnitte und Kategorien anlegen als auch bestehende Datensätze aktualisieren. Ein entsprechender Button findet sich im Footer der Seiten, sofern die Rechte dafür freigegeben wurden.

CSV-Import

Wie ist die CSV-Datei aufgebaut?

Zur Orientierung empfiehlt es sich, einen Datensatz über den CSV-Button herunterzuladen und die Datei für den eigenen Import anzupassen. Die CSV-Datei enthält in der ersten Zeile die Spaltennamen. Als Trennzeichen zwischen den Feldern wird ein Semikolon erwartet, Datensätze werden über einen Zeilenumbruch getrennt. Felder, die ein Semikolon oder einen Zeilenumbruch enthalten, müssen in doppelte Anführungszeichen gesetzt werden. Anführungszeichen werden maskiert, indem sie verdoppelt werden. Beispiel:

lemma;comment
Stein;"Ein sogenanntes ""Lemma"" mit Anführungszeichen im Kommentarfeld"
Holz;"Ein zweites Lemma"

Ob die Datei korrekt aufgebaut ist, kann beim Importieren in der Vorschau kontrolliert werden.

Wie werden Datensätze importiert?

Zum Aufbau einer CSV-Datei ist ein Verständnis des Datenmodells hilfreich. In welche Tabelle der Datenbank eine CSV-Datei importiert wird, hängt davon ab, auf welcher Seite der Import-Button aufgerufen wird. Auf der Kategorienseite werden beispielsweise Datensätze in die Tabelle properties importiert, wobei die ausgewählte Kategorie als propertytype gesetzt wird. Auf der Artikelseite werden Artikel mit den zugehörigen Abschnitten und Inhalten importiert.

Die Tabelle eines Datensatzes lässt sich aber auch in der CSV-Datei explizit angeben, um gleichzeitig Datensätze für mehrere Tabellen zu importieren. Auf diese Weise lassen sich vollständige Artikel inklusive aller nötigen Kategorien, Bearbeiter- und Projektdatensätzen importieren. Die Zieltabelle für den Import ergibt sich für jede Zeile entweder aus der id des Datensatzes oder wird in der Spalte table angegeben:

table	id	articles_id	sections_id	name	content
articles	articles-tmp1			Ein Artikel
sections	sections-tmp1	articles-tmp1		Ein Abschnitt	Kommentar zum Abschnitt
items		articles-tmp1	sections-tmp1		Der Inhalt des Abschnitts

Im Beispiel ist die Angabe der Tabelle für den Artikel- und den Abschnittsdatensatz redundant. Es schadet aber auch nicht, die table- und die id-Spalten grundsätzlich auszufüllen. Zur Vereinfachung des Imports empfiehlt es sich allerdings, grundsätzlich mit IRI-Pfaden zu arbeiten, die in der ID-Spalte angegeben werden. Auf diese Weise lassen sich später auch noch Daten aktualisieren (siehe unten).

Welche Felder stehen zur Verfügung?

Grundsätzlich stehen alle Felder zur Verfügung, die beim Export eines Datensatzes enthalten sind bzw. die im Datenmodell dokumentiert sind. Alle Zieltabellen teilen sich in der CSV-Datei die Felder, zum Beispiel für den Namen eines Artikels und den Namen eines Abschnitts. Für einen Datensatz irrelevante Felder - bei Artikeln etwa das Feld content - bleiben leer.

Für einige Felder können alternative Spalten verwendet werden, um die Datei übersichtlicher zu halten:

In den jeweiligen Tabellen kann das Feld type anstelle von projecttype, articletype, sectiontype, itemtype, propertytype, usertype, scope oder from_tagname verwendet werden.
In der items-Tabelle kann das Feld to_id anstelle von links_tab und links_id verwendet werden, idealerweise enthält es einen IRI-Pfad.
In der links- und der footnotes Tabelle reicht das Feld root_id anstelle von root_tab und root_id, sofern daraus die Tabelle hervorgeht. Idealerweise wird ein IRI-Pfad verwendet. Gleiches gilt für from_id und to_id.

Projekte

Name	Erläuterung	Feld im Datenmodell
id	IRI-Pfad
published
type	IRI-Type	projecttype
iri	IRI-Fragment	norm_iri
sortno	Sortiernummer (Zahl)
signature	Kurztitel (Text)
name	Langtitel (Text)
content	Beschreibung (JSON)
norm_data	Normdaten (Text)

Artikel

Name	Erläuterung	Feld im Datenmodell
id	IRI-Pfad
published
type	IRI-Typ	articletype
iri	IRI-Fragment	norm_iri
sortno	Sortiernummer (Zahl)
signature	Identifikator (Text)
name	Titel (Text)
status	Status (Text)
norm_data	Normdaten (Text)
creator	Autor (IRI-Pfad)	created_by
modifier	Bearbeiter (IRI-Pfad)	modified_by
project	Projekt (IRI-Pfad)	projects_id

Abschnitte

Name	Erläuterung	Feld im Datenmodell
id	IRI-Pfad
published
type	IRI-Typ	sectiontype
iri	IRI-Fragment	norm_iri
sortno	Sortiernummer (Zahl)
number	Nummer (Zahl)
name	Bezeichnung (Text)
signature	Alternative Bezeichnung (Text)	alias
content	Notiz (Text)	comment
layout_cols	Anzahl der Spalten eines Gitters (Zahl)
layout_rows	Anzahl Zeilen eines Gitters (Zahl)
articles_id	Artikel (IRI-Pfad)
parent_id	ÜBergeordneter Abschnitt (IRI-Pfad)

Inhalte

Name	Erläuterung	Feld im Datenmodell
id	IRI-Pfad
published
type	IRI-Typ	itemtype
iri	IRI-Fragment	norm_iri
sortno	Sortiernummer (Zahl)
value	Einzelner Wert (Text)
content	Inhalt (Text)
translation	Übersetzung (Text)
property	Kategorie (IRI-Pfad)	properties_id
pos_x	Position im Gitter (Zahl)
pos_y	Position im Gitter (Zahl)
pos_z	Position im Gitter (Zahl)
sections_id	Abschnitt (IRI-Pfad)
articles_id	Artikel (IRI-Pfad)

To be added: to_id, flagged, file_*, date_*, source_*

Typen

Name	Erläuterung	Feld im Datenmodell
id	IRI-Pfad
type	IRI-Typ	scope
iri	IRI-Fragment	norm_iri
sortno	Sortiernummer (Zahl)
name	Name (Text)
caption	Beschriftung (Text)
mode	Modus (Text)
category	Kategorie (Text)
description	Beschreibung (Text)
config	Konfiguration (JSON)

Wie werden Datensätze miteinander verbunden?

Projekte enthalten Artikel, Artikel bestehen aus Abschnitten und Abschnitte umfassen Einträge. In den Einträgen wiederum wird auf Kategorien verwiesen. Die Verbindung zwischen all diesen Datensätzen erfolgt beim Importieren über die IDs. Für einen Abschnitt wird im Beispiel nicht nur eine eigene ID angegeben, sondern auch die ID des zugehörigen Artikels, gleiches gilt für den Item-Datensatz:

id	articles_id	sections_id	name	content
articles-tmp1			Ein Artikel
sections-tmp1	articles-tmp1		Ein Abschnitt	Kommentar zum Abschnitt
items-tmp1	articles-tmp1	sections-tmp1		Der Inhalt des Abschnitts

Die IDs können auf drei verschiedene Arten gebildet werden:

IRI-Pfade (Internationalized Resource Identifiers) sind besonders flexibel und empfehlenswert, da sie auch ohne Kenntnis datenbankinterner IDs den Datentransfer zwischen unterschiedlichen Datenbanken erlauben. Sie werden nach dem Schema <table>/<type>/<irifragment> gebildet. Beispiel: properties/languages/iso-de-de.
Temporäre IDs werden nicht in die Datenbank importiert, sondern nur für die Verknüpfung innerhalb einer CSV-Datei verwendet. Sie werden nach dem Schema <tabelle>-tmp<id> gebildet, das heißt auf die Angabe der Tabelle folgt nach einem Trennstrich das Präfix "tmp" und dann die Angabe einer Bezeichnung, die aus beliebigen Buchstaben und Zahlen zusammengesetzt sein kann. Beim Importieren werden automatisch datenbankspezifsche IDs angelegt und alle Datensätze korrekt verknüpft. Beispiel: articles-tmp123.
Datenbank-IDs müssen einem vorhandenen Datensatz entsprechen. Sie werden verwendet, um bestehende Daten zu überschreiben oder auf bestehende Daten zu verweisen. Diese IDs werden nach dem Schema <tabelle>-<id> gebildet, wobei der Platzhaltter <id> eine vorhandene numerische ID enthält. Beispiel: articles-1.

Inwiefern die IDs in einer CSV-Datei korrekt aufgelöst werden können, lässt sich in der Import-Vorschau kontrollieren. Alle in der Datenbank bestehenden Datensätze sind grün markiert.

Wie werden Datensätze aktualisiert statt neu angelegt?

Werden in der CSV-Datei IRIs oder Datenbank-IDs verwendet (siehe oben) und ein Datensatz ist bereits vorhanden, dann wird er nicht neu angelegt, sondern überschrieben. Zur Angabe der IRIs kommen zwei Varianten in Frage:

Ein vollständiger IRI-Pfad wird in der id-Spalte angegeben, zum Beispiel "properties/languages/iso-de-de".
Die Komponenten des IRI-Pfads werden in den jeweiligen Spalten angegeben. Der Tabellenname "properties" ergibt sich aus der table-Spalte (oder aus der temporären ID). Zusätzlich ist die Angabe des Datensatztyps "languages" in der types-Spalte erforderlich, damit automatisch der IRI-Pfad gebildet werden kann. Das IRI-Fragment wird in der iri-Spalte angegeben, etwa "iso-de-de".

Das weitere Verhalten kann bei Bedarf über die Spalten _action und _fields gesteuert werden:

_action=clear: Untergeordnete Datensätze werden gelöscht, um Platz für die folgenden Datensätze zu schaffen. So kann beispielsweise ein Abschnitt geleert werden, bevor in den folgenden Zeilen neue Einträge importiert werden.
_action=skip: Der Datensatz wird nicht importiert, also auch nicht überschrieben. Der Datensatz ist lediglich dazu da, Verknüpfungen zu ermöglichen. Dazu können im Datensatz eine temporäre ID (auf die andere Zeilen verweisen) und die dazugehörigen Komponenten des IRI-Pfades (der zu einer Datenbank-ID aufgelöst wird) angegeben werden. Einfacher ist in der Regel aber die Verwendung von IRI-Pfaden.
_fields: Alle Tabellen in einer CSV-Datei teilen sich die Spalten. Etwa werden der Kommentar eines Abschnitts ebenso wie der Text eines Eintrag in der Spalte content angegeben. Ist das Feld leer, wird es geleert. Mit einer Angabe in der _fields-Spalte wird alternativ festgelegt, dass nur die angegebenen Spalten berücksichtigt werden, um beispielsweise den Kommentar eines Abschnitts nicht zu überschreiben, aber den Inhalt eines Eintrags. Es müssen dazu mit einem Komma getrennt alle Felder aufgelistet werden, die zu berücksichtigen sind (Achtung: die ID-Felder nicht vergessen). Fehlt die _fields-Spalte oder ist sie leer, werden alle Felder berücksichtigt.

XML-Import

Vollständige Artikel können aus XML-Dateien importiert werden. Die Dokumentation wird noch ergänzt - ein Beispiel findet sich im Import-Ordner für Anima2 der Datenbank epi_mainz.