Export und Import

Im CMS-Frontend wird sowohl für einen ganzen Namensraum als auch für eine einzelne API eine Schaltfläche Export angeboten, die nach Betätigen ein ZIP Archiv mit allen entsprechenden Datensätzen zum Herunterladen anbietet. Da diese aktuell auch sämtliche Mediendateien enthält, kann das Archiv doch recht umfangreich werden.

Die Export Funktionalität basiert auf einem einfachen HTTP GET Aufruf: /data/Namensraum/_export/Vergleichsmuster:

• Namensraum: Der Namensraum, aus dem Daten exportiert werden sollen
• Vergleichsmuster: Ein regulärer Ausdruck, der die zu exportierenden APIs festlegt. Im CMS-Frontend wird für den Export einer einzelnen API deren Namen verwendet (e.g. /data/tutorial/_export/api1) und für alle APIs eines Namensraums (e.g. /data/tutorial/_export/.*). Dabei sind der Phantasie allerdings keine Grenzen gesetzt und es sollten im direkten Zugriffe alle Bedürfnisse erfüllt werden können - e.g. /data/tutorial/_export/(api\d+|languages) zum Export aller APIs im Namensraum tutorial, deren Namen mit api beginnt und nur mit Ziffern fortgesetzt wird sowie zusätzlich der API languages.

Alternativ wird für die Projektverwaltung auch ein Export auf Basis von Projekt- und Anwendungsnamen angeboten, ebenfalls umgesetzt über ein einfaches HTTP GET:

• /projects/_export/Projektname: exportiert alle APIs eines Projektes, gegebenenfalls auch aus unterschiedlichen Namensräumen.
• /projects/_export/Projektname*!*Anwendungsname: beschränkt dies auf eine einzelne Anwendung, die natürlich wieder verschiedene APIs in potentiell unterschiedlichen Namensräumen enthalten kann.

Für einen Import wird ein HTTP POST direkt an das CMS gesendet, wobei als Daten eine über den Export erstelltes ZIP Archiv (Content-Type application/zip) übermittelt wird: /import. Im CMS-Frontend wird dazu die Schaltfläche Import auf der Startseite angeboten.

Eine Auswahl der im Archiv enthaltenen APIs ist nicht vorgesehen, allerdings kann der Einspielvorgang über URL Parameter gesteuert werden, e.g. /import?execute&insertOnly:

• execute: Ist dieser Parameter nicht gesetzt, so wird das Archiv nur auf Nutzbarkeit geprüft. Es werden keine Daten verändert.
• insertOnly: Existieren in einer API bereits Daten, so werden nur bisher unbekannte Datensätze (_id) aus dem Archiv übernommen. Existierenden Datensätze werden niemals verändert.
• allowDataLoss: Bereits existierende Datensätze werden vor dem Einspielen entfernt, die zugehörige API entspricht nach dem Vorgang exakt dem Stand aus dem Archiv.
• skipProtectedApis: Enthält das Archiv APIs zu denen keine Datensätze eingespielt werden dürfen, so werden diese einfach ignoriert.
• skipProtectedNamespaces: Enthält das Archiv APIs in Namensräumen zu denen keine APIs angelegt oder verändert werden dürfen, so werden diese Namensräume ignoriert.

Die Parameter sollten mit Sorgfalt gewählt und nicht unnötig aktiviert werden - mit Ausnahme von execute selbstverständlich. Nachlässigkeiten zum Beispiel bei allowDataLoss können zum unwiderbringlichen Verlust des vorhandenen Datenbestands führen.

Grundsätzlich arbeitet der Einspielvorgang wie folgt:

• Das Schema aller betroffenen APIs wird auf den Stand aus dem Archiv gebracht - vorhandene Daten werden dadurch eventuell ungültig, eine Datenmigration ist nicht vorgesehen. Wenn möglich, wird die existierende API dazu gelöscht - wenn noch keine Daten existieren oder allowDataLoss angegeben wurde.
• Existieren Daten und allowDataLoss sowie insertOnly sind beide nicht gesetzt, so bricht der Einspielvorgang ab.
• Dürfen im Namensraum keine APIs angelegt oder verändert werden und ist skipProtectedNamespaces nicht gesetzt, so wird ebenfalls ein Fehler samt Abbruch ausgelöst.
• Alle Datensätze und zugehörigen Dateien aus dem Archiv werden eingespielt. Sind identische Datensätze bereits vorhanden, so werden diese nicht verändert - das kann nur bei importOnly auftreten, da ansonsten die existierende API samt allen Daten bereits im Vorfeld gelöscht wurde.
• Dürfen in der API keine Datensätze angelegt, gelöscht oder verändert werden und ist skipProtectedApis nicht gesetzt, so wird der Einspielvorgang mit einer Fehlermeldung beendet.

Eine JSON Struktur als Antwort beschreibt das Ergebnis des Einspielvorgangs. In der Pflegeoberfläche wird dies für jede im Archiv enthaltene API protokolliert und auch der Gesamterfolg gemeldet:

In diesem Dialog sind die einzelnen Parameter des Einspielvorgangs auch noch einmal etwas ausführlicher erläutert.