Daten importieren
Table of Contents
RowImport
Der RowImport (teilweise auch nur Import genannt) kann aus einer Datei (XLS, XLSX, CSV) die Daten zeilenweise importieren. Mit dem RowImport ist es nicht möglich nicht-zeilenbasierte Importe umzusetzen. Genauso wenig ist es möglich anhand des Styling der Zellen Daten zu importieren.
Um einen RowImport anzulegen, werden zwei Dinge erledigt werden: Zum einen muss eine ImportDefinition angelegt werden, dort wird konfiguriert welche Felder pro Zeile importiert werden können. Desweiteren muss eine RowImport-Klasse erstellt werden. In dieser Klasse wird programmiert, wie eine Zeile aussehen muss, damit die Daten als gültig zählen und wie anschließend eine gültige Zeile importiert wird, also was aus den Daten gemacht werden soll (z.B. Teilnehmer mit diesem Namen anlegen).
ImportDefinition
Die ImportDefinition definiert, welche Felder importiert werden können. Die ImportDefinition wird im Backend angelegt als Konquadrat-Objekt #grid/ImportDefinition. Die Konfiguration muss in XML gemacht werden.
Die XML-Dokumentation für die ImportDefinition ist hier zu finden.
Beispiel:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<importDefinition xmlns="http://www.setasign.com/Konquadrat/ImportDefinition">
<fields>
<group name="participant">
<labels>
<label lang="de">Hauptteilnehmer</label>
<label lang="en">Participant</label>
</labels>
<content>
<fields ref="Person">
<excludes>
<field ref="id"/>
<field ref="parent"/>
<field ref="creationDateTime"/>
<field ref="changeDateTime"/>
</excludes>
</fields>
</content>
</group>
<group name="companion">
<labels>
<label lang="de">Begleitperson</label>
<label lang="en">Companion</label>
</labels>
<content>
<fields ref="Person">
<excludes>
<field ref="id"/>
<field ref="parent"/>
<field ref="creationDateTime"/>
<field ref="changeDateTime"/>
</excludes>
</fields>
</content>
</group>
</fields>
</importDefinition>
RowImport-Klasse
Jede ImportDefinition benötigt eine eigene RowImport-Klasse. Die Klasse muss in dem Namespace \com\setasign\Konquadrat\Custom\RowImport und damit in dem Ordner "kon2/classes/RowImport/".
Die RowImport-Klasse muss \com\setasign\Konquadrat\Import\RowImport\AbstractRowImport erweitern. Dadurch müssen zwei Methoden implementiert werden:
importRow()
Imports the row.
sanitizeRow()
Sanitize the row.
Die sanitize()-Methode hat die Aufgabe die Werte der Zeile zu bereinigen und eventuelle Fehler anzuzeigen. Falls die Felder in Gruppen eingeteilt wurden ist der Feldname wie folgt: "{Gruppe}_{Feldname}"
Um auf die Felder schneller und einfacher zugreifen zu können, kann das Row-Array in Gruppen-Rows geteilt und wieder zusammengeführt werden mit folgenden Methoden:
- \com\setasign\Konquadrat\Import\AbstractRowImport::getGroup()
- \com\setasign\Konquadrat\Import\AbstractRowImport::setGroup()
Falls eine Spalte ungültige Werte beinhaltet sollte der Fehler per \com\setasign\Konquadrat\Import\AbstractRowImport::registerError() registriert werden.
Die importRow()-Methode hat die Aufgabe aus der bereinigten Spalte die Konquadrat-Objekte zu erstellen. Dabei ist zu beachten, dass die Methode auf jeden Fall bereits in einer Transaktion läuft und dass Exceptions zu einem Rollback der Transaktion führt (alle Rows sind in einer Transaktion).
Import im Backend
Im Backend ist der Import-Dialog über die Adresse #import zu erreichen.
- Als erstes muss eine Import-Datei ausgewählen werden.
- Danach muss eine ImportDefinition ausgewählt werden.
- Anschließend kann ein ImportSchema erstellen. Hierbei müssen die Spalten aus der Import-Datei den Feldern der ImportDefinition zugewiesen werden.
- Danach kann man sich eine Vorschau anzeigen lassen. Dort sind die Werte aus jeder Zeile zu sehen und zu was die Werte bereinigt wurden von sanitizeRow(). Die Originalwerte können in der Tabelle verändert werden, danach muss die ganze Spalte aber erneut bereinigt werden.
- Zuletzt können alle Zeilen die auf "Sanitized" stehen durch einen Klick auf "Import" importiert werden.
CustomImport
Falls es nötig ist, Daten nicht zeilenbasiert aus einer Datei zu importieren, dann gibt es keine direkten Helferklassen. Der Import kann jedoch einen ProjectController umgesetzt werden. Mehr dazu hier. Es sollte darauf geachtet dass in der History ein Ursprung gesetzt wird (im Zweifelsfall ein leeres Import-Objekt verwenden), damit zu erkennen ist woher die Daten kommen.