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:

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.

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:

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.