Dokumentation CKAN-Uploader-Batch

Kurzbeschreibung

Mit dem CKAN-Uploader-Batch (CUB) werden Daten (Datensätze, Ressourcen, Gruppen) aus einem Excel nach CKAN importiert / hochgeladen.

CUB ist ein dockerisiertes Skript, das auf der Kommandozeile ausgeführt wird. Details dazu stehen im Readme des Repositories. CUB ist unter Linux getestet und benötigt Docker und Make.

Funktionsweise

Die Steuerung erfolgt mit einer Excel-Datei (xlsx). Diese ist wie folgt aufgebaut:

Aus dem Arbeitsblatt „datasets“ werden Datensätze erstellt/bearbeitet.

Jede Zeile enthält einen Datensatz, der an CKAN übertragen wird. Hierzu wird die CKAN-API genutzt.

Zur Übertragung muss das CKAN-Ziel angegeben werden:

  • CKAN-API-URL: http://<ckan-url>/api/3/action/
  • API-Token: Das API-Token kann ein CKAN-Benutzer auf seiner Profilseite erzeugen. Es wird als Sicherheitsschlüssel genutzt. Wenn das API-Token nicht mehr benötigt wird, sollte es auf der Profilseite wieder gelöscht werden.

Aufbau der Excel-Datei

In der Spalte „Action“ steht, was mit der Zeile gemacht werden soll:#

  • EXEC: führt die Zeile aus
  • IGNORE: ignoriert die Zeile und geht zur nächsten Zeile weiter

Nur die Spalten mit „ckan_…“ sind für das Skript relevant. Die anderen werden nicht beachtet.

Anmerkungen zu den Spalten:

  • ckan_action: Das ist die Funktion für diese Excel-Zeile.
    • package_create: Datensatz wird erzeugt. CKAN-Docs
    • package_delete: Datensatz wird widerruflich gelöscht bzw. in den Papierkorb geschoben (Achtung: die id ist gültig)
    • dataset_purge: Datensatz wird unwiderruflich gelöscht
    • package_update: Alle CKAN-Felder werden aktualisiert
    • package_patch: Nur die nichtleeren CKAN-Felder werden aktualisiert
  • ckan_name: „Name“ des Datensatzes (z.B. in der URL verwendet)
    • minimal 2, maximal 100 Zeichen
    • erlaubt sind Kleinbuchstaben, Zahlen, Bindestriche und Unterstriche
  • ckan_id: sollte gleich sein wie „ckan_name“
  • ckan_owner (optional): die ID einer Organisation, die in CKAN angelegt sein muss. Die ID bekommt man aus der URL. Beispiel: https://<ckan-url>/organization/orga1 enthält „orga1“ als Organisations-ID
  • ckan_author (optional): Name des Autors. Autor ist in CKAN wer die Daten aufbereitet, sammelt oder zur Veröffentlichung autorisiert.
  • ckan_author_email (optional): Email-Adresse des Autors/der Autorin
  • ckan_maintainer (optional): Name des Datensatz-Erstellers in CKAN
  • ckan_maintainer_email (optional): Email-Adresse des Datensatz-Erstellers in CKAN
  • ckan_notes (optional): Zentrale Bescheibung des Datensatzes in Freitext. Die Formatierung erfolgt in Markdown (ohne HTML-Tags)
  • ckan_private (optional): kann false oder true sein. Bei true ist der Datensatz in CKAN nur für den Ersteller sichtbar
  • license_id (optional): Lizenzangabe für den Datensatz. Da Ressourcen keine eigene Lizenzangabe haben, sollte diese Lizenzangabe für alle Angaben zu Datensatz und zu den Ressourcen gelten. Alle verfügbaren license_id’s können mit https://<ckan-url>/api/3/action/license_list ermittelt werden
  • ckan_url (optional): Die URL, die Informationen zum Datensatz bereitstellt. Achtung: Primär sollten Ressourcen für URLs genutzt werden. Eine Datensatz-URL ist sinnvoll, wenn sie z.B. einen Überblick über den Datensatz, den Herausgeber oder Ressourcen gibt.
  • ckan_version (optional): Version des Datensatzes. Es wird die Nutzung der  Semantic Versioning 2.0.0 empfohlen. Beispiel: 1.0.0
  • ckan_groups (optional): Gruppen, denen dieser Datensatz zugeordnet ist. Die Gruppen-ID bekommt man aus der URL. Beispiel: https://<ckan-url>/group/agri enthält „agri“ als Gruppen-ID. Es können mehrere Gruppen-ID’s angegeben werden. Diese müssen durch ein Komma getrennt sein. Beispiel: „agri,tech,educ“. Die Standard-DCAT-Gruppen der EU sind in den EU Vocabularies definiert.
  • ckan_tags (optional): Tags, die diesen Datensatz verschlagworten. Ein Tag (Tag-Name) darf Zeichen, Zahlen, Unterstriche, Bindestriche oder Punkte enthalten. Es können mehrere Tags angegeben werden. Diese müssen durch ein Komma getrennt sein.

Hinweis: „optional“ bedeutet, dass eine Zelle leer bleiben kann.

Tipps und Tricks

Eine bestehende Excel-Tabelle mit Datensätzen kann wie folgt zerstörungsfrei umgebaut werden: Alle Spalten werden nach rechts verschoben und links die jeweiligen CKAN-Spalten eingefügt. Die CKAN-Spalten enthalten dann die Verweise auf die bestehenden Zellen. Alternativ könnte ein neues Arbeitsblatt „datasets“ und den CKAN-Spalten hinzugefügt werden. Die Zellen enthalten dann Verweise auf das Arbeitsblatt mit den Daten.

Wenn CKAN mit ckanext_scheming um Metadatenfelder erweitert wurde, können diese mit eigenen Spalten angegeben werden. Beispiel: ckan_meineigenesfeld

Fehlerhinweise

Bei den Felder ckan_tags und ckan-groups dürfen keine Leerzeichen enthalten sein. Auch ein Komma am Ende oder doppelte Kommas erzeugen Fehler.