Import und Export¶

Deine Nutzer holen Zeilen aus CSV-, Excel- oder JSON-Dateien herein und bringen sie wieder hinaus, ohne dass du einen Parser oder eine Upload-Seite schreibst. Jede importierte Zeile läuft durch deinen eigenen Command. Berechtigungen, Organisation, Validierung und Audit-Log gelten also genauso, als hätte jemand das Formular ausgefüllt.

Freischalten pro Entity-Set¶

Ein Entity-Set wird importierbar, sobald du registrierst, wie aus einer Zeile ein Command wird. Sets ohne Registrierung lassen sich nur exportieren.

// Anlegen und Ändern: die Id ist bei neuen Zeilen null, bei Änderungen die der gefundenen Zeile
services.AddODataImport("Brands",
    (Guid? id, AddEditBrandRequest row) => new AddEditBrandCommand(id, row),
    id => new DeleteBrandsCommand([id]));   // optional: der letzte Import lässt sich rückgängig machen

// nur Anlegen
services.AddODataImport("Notes", (AddNoteRequest row) => new AddNoteCommand(row));
services.AddODataImport<AddNoteCommand>("Notes");   // der Command selbst ist die Zeile

Die öffentlichen Eigenschaften des Zeilentyps mit einfachen Typen (Text, Zahlen, Datum, Guid, bool, Enums) sind die Felder, denen du Spalten zuordnen kannst. Die Beschriftung kommt aus [Display], [DisplayName] oder [Description], sonst aus dem Namen ("MadeAt" wird zu "Made at"). [Required] und required markieren Felder, nach denen der Assistent fragt.

Eine Guid-Eigenschaft wie BrandId neben einer Navigation Brand auf ein anderes OData-Set ist ein Verweis: In der Datei darf statt der Id der Name der Marke stehen. Der Name ist die erste vorhandene Eigenschaft aus Name, Title, DisplayName, Code und Key, sonst die erste Text-Eigenschaft.

Der Assistent¶

CoworkeeDataTable zeigt mit Importable="true" einen Import-Button. Er öffnet ein Seitenpanel mit vier Schritten:

Datei: CSV, TSV, Excel (.xlsx) oder JSON bis 20 MB. Bei Textdateien erkennt der Assistent Kodierung (Byte Order Mark, sonst UTF-8 oder Windows-1252), Trennzeichen und ob die erste Zeile Spaltennamen enthält. Alles davon kannst du korrigieren.
Spalten: Jede Spalte bekommt ein vorgeschlagenes Feld, gefunden über Namen, Beschriftung oder die Beschriftung in der Sprache des Nutzers. Du wählst neue Zeilen anlegen, vorhandene Zeilen ändern oder ändern oder anlegen. Die beiden letzten brauchen eine Schlüsselspalte, etwa die Id oder den Namen. Bei Textdateien legst du die Sprache für Zahlen und Datumswerte fest (1.234,50 und 15.01.2026 in de-DE). Eine Zuordnung kannst du pro Entity-Set unter einem Namen speichern und für die nächste Datei desselben Lieferanten wieder laden.
Prüfen: Die ersten 200 Zeilen laufen durch Umwandlung, Schlüsselsuche und die FluentValidation-Validatoren der Commands, ohne dass etwas geschrieben wird. Du siehst, was jede Zeile tun würde und warum eine Zeile scheitert.
Import: Ein Probelauf prüft im Hintergrund jede Zeile, danach schreibt Import sie. Beides läuft als Hintergrundjob, der Fortschritt kommt live über das Realtime-Topic des Nutzers. Fehlerhafte Zeilen lädst du als CSV mit einer zusätzlichen Spalte Error herunter, korrigierst sie und importierst sie erneut. Import rückgängig machen löscht die Zeilen, die der letzte Import des Nutzers in diesem Set angelegt hat (geänderte Zeilen behalten ihre neuen Werte).

Änderungen starten bei der gespeicherten Zeile: Spalten, die du nicht zuordnest, behalten ihren Wert.

So werden Werte gelesen:

Typ	Akzeptiert
Zahlen	bei Textdateien in der gewählten Sprache, bei Excel und JSON sprachneutral; Ganzzahlen lehnen Nachkommastellen ab
Datum	zuerst ISO (`2026-01-15`), dann die gewählte Sprache
Wahrheitswerte	`true/false`, `yes/no`, `y/n`, `1/0`, `x`, `on/off` sowie Ja/Nein in der Sprache des Nutzers
Enums	Name, Zahl, Beschriftung (`[Display]`/`[Description]`) oder deren Übersetzung
Verweise	Id oder Anzeigetext, nur Zeilen, die der Nutzer lesen darf

Admin-Seite¶

Administration → System → Import und Export (/admin/data-transfer, Berechtigung DataTransfer.Use) listet alle Sets, die der Nutzer importieren darf, exportiert ganze Sets und zeigt seine Importe und Exporte mit Ergebnisdateien und Rückgängig-Funktion.

Export¶

Das Export-Menü einer Tabelle schreibt die aktuelle Ansicht: Suche, Facetten, Spaltenfilter, Sortierung und die sichtbaren Spalten. Excel, CSV und JSON kommen vom Server:

GET /api/v1/data/Products/export?format=csv&columns=Name,Rate&$filter=Rate gt 10&$orderby=Name

Bis Coworkee:OData:BackgroundExportRows Zeilen (Standard 10 000) kommt die Datei sofort zurück. Größere Exporte antworten mit 202 Accepted und einem Job; der Nutzer bekommt einen Hinweis mit Herunterladen-Button, sobald die Datei fertig ist. Coworkee:OData:MaxExportRows (Standard 100 000) begrenzt jeden Export. Berechtigungen, Entity-Filter und ausgeblendete Eigenschaften gelten wie in der Liste.

HTTP-API¶

Aufruf	Zweck
`GET /api/v1/data/imports`	importierbare Sets mit ihren Feldern
`POST /api/v1/data/{set}/import/file`	Upload (multipart, Feld `file`), antwortet mit den erkannten Spalten
`POST /api/v1/data/imports/{id}/sheet`	Upload mit anderem Trennzeichen, anderer Kodierung oder Kopfzeile neu lesen
`POST /api/v1/data/imports/{id}/preview`	die ersten Zeilen mit `ImportSettings` prüfen
`POST /api/v1/data/imports/{id}/start`	Import oder Probelauf (`dryRun: true`) als Job starten
`POST /api/v1/data/imports/{id}/undo`	den letzten Import rückgängig machen
`GET/POST /api/v1/data/{set}/import/profiles`, `DELETE /api/v1/data/import-profiles/{id}`	gespeicherte Zuordnungen
`GET /api/v1/data/jobs`, `GET /api/v1/data/jobs/{id}`, `GET /api/v1/data/jobs/{id}/file`	die Jobs des Nutzers und ihre Dateien
`POST /api/v1/data/{set}/import`	Import früherer Versionen in einem Schritt: Spalten heißen wie die Felder, nur neue Zeilen

Stand: Uploads und Ergebnisdateien liegen in der Job-Zeile in der Datenbank, das passt für Dateien von wenigen MB. Schlüssel- und Verweissuche stellen eine Abfrage pro Zeile und neuem Text. Rückgängig löscht nur angelegte Zeilen.