CSV-Import

Mit dem CSV-Importer können mehrere Datensätze, die in einer tabellarischen Struktur vorliegen, auf einmal hochgeladen werden. Diese Methode eignet sich besonders gut, um weniger umfangreiche Datensätze (etwa Listeneinträge oder Rumpfdaten eines Objekt-Datensatzes) in CODA einzuspielen. Der CSV-Importer stößt jedoch an seine Grenzen bei komplexen und verschachtelten Datensätzen (hierfür eignet sich der JSON-Importer besser, für individuelle Beratung steht das CODA-Team gerne zur Verfügung). Zur Durchführung eines Imports mit dem CSV-Importer müssen bestehende Datenquellen zunächst in das CSV-Format umgewandelt werden.

Vorbereitung

CSV-Datei generieren

Im CSV-Format (“Comma Separated Values”) sind Datensätze jeweils in Zeilen gespeichert. Die einzelnen Informationen aus den Datensätzen sind dann mit einem Trennzeichen (meist Kommata oder Semikola) voneinander getrennt. Die erste Zeile einer CSV-Datei wird meist als Überschrift für die einzelnen “Spalten” verwendet.

Beispiel einer CSV-Rohdatei:

Name;Geburtsdatum;WikiData-Item
Grace Jones;04.04.1948;Q297538
Karl Willetts;21.09.1966;Q4843436

Wird ausgespielt zu:

CSV-Dateien können leicht aus Excel-Tabellen erstellt werden, auch OpenRefine ermöglicht einen Export der Projekte als CSV-Datei. Wichtig ist dabei, dass die Datei mit UTF-8 oder UTF-16 kodiert ist, andernfalls werden Sonderzeichen nicht richtig dargestellt.

Damit deine CSV-Datei richtig ausgelesen wird, gilt es noch folgende Dinge zu beachten:

• Falls das Trennzeichen in einem Text in der CSV vorkommt, müssen Anführungszeichen (doppelt oder einfach) den Text umgeben. In Excel geschieht dies in der Regel automatisch, in OpenRefine sollte beim Export über die Schaltfläche “Custom tabular…” -> “Download” die Checkbox “Always quote text” angewählt werden.
• Das Format in jeder Spalte sollte immer gleich sein! Das gilt für Datumsangaben, Zahlen, Personennamen, etc.
• Zahlen sollten immer den gleichen Separator für Vor- und Nachkommastellen nutzen

CODA-spezifische Anforderungen

Mehrfachfelder

In einem Feld der CSV-Datei können mehrfache Einträge stehen, die in ein Mehrfachfeld in CODA gehören. Diese Einträge müssen aber durch Zeilenumbruch getrennt werden. Wenn also Objekt1 die zusätzlichen Bezeichnungen “Name_1” und “Name_2” hat, dann können diese in der CSV-Datei in einem Feld untergebracht werden, solange sie durch Zeilenumbruch getrennt sind.

• Wenn in einer Mehrfachgruppe verknüpfte Angaben stehen, zum Beispiel Personen mit ihrer jeweiligen Rolle, dann werden in Mehrfachfeldern die Felder in gleicher “Zeilenhöhe” miteinander gekoppelt:

Verweise auf Normdaten mit Plug-Ins (GND, Getty, GeoNames)

Hier muss ein Link und eine Bezeichnung angegeben werden, und zwar in folgendem Format, das immer gleich ist, egal auf welche der Datenbanken man verweist. Dabei kann man Zeilenumbrüche und Leerzeichen auch weglassen, wichtig ist nur, dass das Folgende in einem einzelnen Feld deiner Tabelle bzw. CSV-Datei steht. (Es handelt sich hier um ein JSON-Objekt, das in einem Feld der CSV-Datei steht.)

{
  "conceptURI": "https://d-nb.info/gnd/130579653",
  "conceptName": "Morlock, Max"
}

Über das Import-Mapping wird dann festgelegt, um welche Referenz es sich tatsächlich handelt (GND/Getty/GeoNames), sodass die Information in CODA dem richtigen Feld zugeordnet wird.

Links (in Link-Feldern)

Verweise auf alle anderen Datenbanken verwenden das CODA-Mehrfachfeld Klassifikationen (siehe hier). Hierfür kriegen der Klassifikationstyp und die URL in deiner Tabelle bzw. CSV-Datei je eine eigene Spalte. Der Link wird wieder als JSON-Objekt dargestellt und kann optional auch eine Link-Beschreibung enthalten (siehe Beispiel). Als Spaltennamen kannst du zwecks automatischen Import-Mappings folgende wählen: classification[].type und classification[].link. Zum Beispiel:

Koordinaten

Koordinaten werden ebenfalls als JSON-Objekt aufbereitet. Die eigentlichen Koordinaten stehen in Dezimalschreibweise (ohne N/E-Angabe) bei “lat” bzw. “lng”. Zusätzlich empfiehlt sich die Angabe eines Icons (FontAwesome) sowie einer Farbe für das Icon, damit die Koordinaten in der CODA-Nutzeroberfläche auf Karten dargestellt werden können. Folgendes steht in einem einzelnen Feld der Tabelle bzw. CSV-Datei (Zeilenumbrüche und Leerzeichen kann man weglassen):

{
   "mapPosition":{
      "iconName":"fa-map-marker",
      "iconColor":"#b8bfc4",
      "position":{
         "lat":8,
         "lng":10
      }
   }
}

Dateien/Digitalisate

Es besteht die Möglichkeit, während des CSV-Imports bereits in CODA vorhandene Digitalisate mit den neuen Objekt-Datensätzen zu verknüpfen oder neue Digitalisate im gleichen Zug mit hochzuladen. Dies funktioniert ähnlich wie bei den Mehrfachfeldern auch mit mehreren Digitalisaten gleichzeitig.

Willst du bestehende Dateien verknüpfen, so kannst du in einer Spalte die Namen (Titel) der Digitalisate angeben und während des Import-Mappings diese Spalte dem Feld files[].file und dann dem Sub-Feld name#de-DE bzw. name#en-US (je nach Sprache, in dem die Datensätze zum Digitalisat vorliegen) zuordnen.

Um neue Digitalisate oder Dateien direkt während des CSV-Imports hochzuladen, müssen diese über einen Server bereitgestellt werden. Sollten die Daten auf der Festplatte deines PCs vorliegen, eignet sich die Nutzung eines lokalen Webservers, den du zum Beispiel mit der Software Servez erstellen kannst. Wähle in Servez das Verzeichnis aus, das deine Digitalisate enthält und achte darauf, dass die Checkbox bei “Set CORS headers” ausgewählt ist. Mit einem Klick auf “Start” kannst du den Server starten (er muss während des gesamten Importvorgangs live geschaltet sein). Anschließend bekommst du unten im Bereich “Log” eine URL angezeigt, unter der deine Dateien zu finden sind (du kannst dies auch mit dem Browser testen). Füge diese URL (inklusive des Ports, z.B. 8080) an den Dateinamen deiner Digitalisate an.

Beispiel (s. Spalte digitalisat):

Beispiel nach Korrektur der Dateinamen (s. Spalte digitalisat):

Während des Imports werden die Digitalisate über den lokalen Server bereitgestellt und von dort in CODA hochgeladen.

Objektbiographie/Ereignisse

Relationen

Wenn ein Objekt eine Referenz auf ein anderes Objekt enthält, dann können nicht beide gleichzeitig per CSV importiert werden, weil man nur Referenzen zu Objekten erstellen kann, die bereits in CODA vorhanden sind. Daher muss man die Objekte, die einander referenzieren, in unterschiedliche Tabellen bzw. CSV-Dateien packen. Bei dem Objekt, das zuerst importiert werden soll, darf die Referenz nicht importiert werden. Das Objekt, das als zweites importiert wird, kann mit der Referenz zum ersten Objekt importiert werden. Das kannst du umsetzen, indem du das Feld für die Referenz nur beim Import-Mapping für das zweite Objekt auswählst. (Die wechselseitige Referenz wird dann beim Import automatisch erstellt.)

Import-Workflow

Den CSV-Importer findest du über einen Klick auf das Werkzeug-Symbol (  ) auf der linken Seite:

CSV-Importer

Im Importer gibt es zur Linken zwei Reiter mit Einstellungen, “Import-Einstellungen” und “Import-Mapping”, und einen Reiter “Status”.

Zur Rechten gibt es die Reiter “Tabellen-Ansicht”, “Datensatz-Vorschau” und “JSON-Vorschau”, die zur Übersicht dienen. “Tabellen-Ansicht” zeigt dir deine CSV-Datei an, die “Datensatz-Vorschau” zeigt dir an, wie der Ziel-Datensatz in CODA mit den gewählten Import-Einstellungen aussehen würde, und die “JSON-Vorschau” zeigt beides an.

Der Workflow

1. Überprüfe deine Daten / deine CSV-Datei:

• Entsprechen sie den Anforderungen an Daten und Formate?
• Sind sie insbesondere in UTF-8 oder UTF-16 kodiert?
• Beim Import von Listeneinträgen: Entsprechen die Einträge den Anforderungen an die Datenqualität?

2. Wähle in der CODA-Nutzeroberfläche bei den Werkzeugen “CSV-Importer” aus.
3. Import-Einstellungen: Hier wählst du deine CSV-Datei aus und gibst an, welche Art von Daten du wie importieren möchtest. Handelt es sich z.B. um Sammlungsobjekte oder um Materialien, die du in die Material-Liste importieren möchtest?
4. Import-Mapping: Hier ordnest du jedem zu importierenden Feld in deiner CSV-Datei ein Feld in einem CODA-Datensatz zu. Je nach Größe deiner Tabelle kann dieser Schritt etwas mühselig sein, da z.B. verschachtelte Mehrfachfelder nicht immer automatisch zugeordnet werden.
5. Wenn deine Einstellungen gesetzt sind, klicke rechts unten auf “Vorbereiten”
6. Wenn im “Status”-Reiter keine Fehler auftauchen und in der Datensatz-Vorschau (rechts im Fenster) alles gut aussieht, dann kannst du die Daten einfügen bzw. aktualisieren, indem du rechts unten auf den entsprechenden Button klickst.

Soweit der Ablauf im Groben. Wichtig sind natürlich die Import-Einstellungen, die nun im Detail erläutert werden.

Import-Einstellungen

Im Reiter Import-Einstellungen findest du allgemeine Import-Einstellungen. Welche Datei willst du importieren, zu welchem Objekttyp in CODA sollen deine Daten werden, etc. Die Optionen sind im Folgenden aufgelistet. Viele dieser Optionen werden aber erst sichtbar, wenn man eine CSV-Datei eingelesen und eine Maske ausgewählt hat.

Optionen mit Sternchen (*) sind verpflichtend.

Import-Mapping

Damit im Reiter Import-Mapping überhaupt irgendwelche Felder angezeigt werden, musst du bei den Import-Einstellungen zuerst eine Maske auswählen. Deren Felder werden dann angezeigt.

Und zwar werden links alle Spaltennamen deiner CSV-Datei angezeigt. In den ausklappbaren Menüs rechts daneben werden dir alle Felder des Datenmodells angeboten, die auch in der gewählten Maske enthalten sind.

So kannst du dann für jede Spalte deiner Tabelle auswählen, mit welchem Feld im Datenmodell du ihre Inhalte verknüpfen willst. Dabei sind die Ansichten auf der rechten Seite des Fensters nochmal nützlich, um den Überblick zu behalten. Neben der “Datensatz-Vorschau” und “JSON-Vorschau” ist vor allem die “Tabellen-Ansicht” praktisch.

Hier ein Beispiel, wo die Import-Einstellung “Anzeigenamen verwenden” aktiviert ist. Der Spalte “name.de-DE” in der CSV-Datei wurde hier das Feld “Bezeichnung” im Datenmodell zugeordnet. Da dieses Feld sowohl eine deutsche als auch englische Variante hat, kann man deshalb auch noch die Sprache “de-DE” auswählen.

Upload-Template

Daten, die für den CSV-Import vorgesehen sind, können auf ähnliche Weise wie in diesem Template formatiert werden: Download des CSV-Upload-Templates (.xslx, 673 KB)

Es handelt sich hierbei um ein Template für Objektdatensätze. Bei Listeneinträgen sind die Felder andere (siehe auch Listeneinträge anlegen), aber das Prinzip ist im Grunde das gleiche. Auf Anfrage können wir auch beispielhaft ein Template für die Einträge einer Liste bereitstellen. Da je nach Liste die Felder variieren, müsste das Listen-Template dann auch entsprechend für andere Listen angepasst werden.

In der folgenden Auflistung sind die Spaltentypen im Upload-Template mit ihrer Beschreibung angegeben. Dabei entspricht bspw. der Spaltentyp “Objekttitel (Pflichtfeld)” einer Spalte im Upload-Template bzw. einem Feld im Datenmodell von CODA. Eine Zeile im Upload-Template entspricht dann einem konkreten Datensatz eines Sammlungsobjektes, siehe dafür das Template. Und die Information in einem Feld des Templates entspricht der Information, die in CODA in einem bestimmten Datensatz in einem bestimmten Feld landet.

Bedingte Pflichtfelder beziehen sich hier auf die Mehrfachgruppe “Ereignis” (siehe dazu Datensätze anlegen - Objektbiographie). Jedes Objekt soll mindestens ein Ereignis mit Ereignistyp haben, der Ereignistyp ist also ein Pflichtfeld. Und innerhalb der Mehrfachgruppe Ereignis soll dann noch zumindest eines der folgenden Unterfelder ausgefüllt werden: Ort, Datierung, Epoche, Person, Gruppe, Institution. Dies sind also bedingte Pflichtfelder, denn es müssen nicht alle von ihnen ausgefüllt werden, nur mindestens eins.

Bei dem Template handelt es sich allerdings nicht um das vollständige Datenmodell (siehe hierzu den Feldkatalog). Falls du noch Informationen für weitere CODA-Felder hinzufügen möchtest, brauchst du nur eine neue Spalte dafür anzulegen.

Häufig sind die Daten auch schon in einer tabellarischen Form vorhanden. In dem Fall musst du prüfen, ob die Tabelle den Anforderungen an Daten und Formate genügen, damit es beim Import nicht zu Komplikationen kommt.

Wie im Import-Workflow nachzulesen ist, kann man im CSV-Importer die Zeilen der Tabelle händisch einem beliebigen CODA-Feld zuordnen. Wenn man die Tabellenzeilen aber im Vorhinein schon mit den passenden Feldnamen benennt, dann kann der CSV-Importer das teilweise automatisch zuordnen. Das wurde im Template auf den Sheets “import-file_de” und “import-file_en” gemacht (siehe dort).

Das sieht in der Tabelle mit den verschachtelten Feldnamen vielleicht nicht so schön aus, aber man kann sich beim Import dadurch etwas Geklicke ersparen. All diese Feldnamen sind auch im Feldkatalog verzeichnet.

Weitere Informationen

• Beschreibung des CSV-Imports in der easyDB-Doku

• Beschreibung des CSV-Imports in der fylr-Doku