CSV- und XLSX-Daten importieren

Zweck und Einsatzbereich

Mit Daten-Import legen Sie Importaufträge für vier Datentypen an: Kunden, Kontakte, Seefracht-Import Akten und Container (Import). Ein Auftrag durchläuft Upload, Spalten-Mapping, Validierung und Übernahme. In der Übersicht Letzte Imports sehen Sie Datei, Typ, Zeilenzahl, Erstellzeit und Importstatus.

Die Produktnavigation führt im Ocean-Import-Arbeitsbereich über Daten-Import zur Workbench. Außerdem enthält Einstellungen den Eintrag Importe. Beide Wege können jedoch zu unterschiedlichen Ergebnissen führen, weil die Anzeige im Frontend und die Prüfung im Backend nicht dieselben Voraussetzungen verwenden; die Einschränkungen sind im folgenden Abschnitt beschrieben.

Voraussetzungen und Berechtigungen

Sie benötigen einen angemeldeten Mandantenzugang. Plattformadministratoren dürfen keine Mandantendaten importieren; der Dienst antwortet dann mit „Plattform-Admins importieren keine Mandantendaten“.

Für den produktiven Zugriff erzwingt der Importdienst das lizenzierte Modul Ocean Import. Die Hauptnavigation zeigt Daten-Import ebenfalls nur bei Ocean-Import-Zugriff. Für das Anlegen oder Übernehmen von Seefracht-Import Akten und Container (Import) ist zusätzlich die persönliche Freigabe zum Anlegen von Import-Akten erforderlich. Fehlt sie, lautet die Rückmeldung „Keine persönliche Freigabe zum Anlegen von Import-Akten“.

Der Backend-Zugriff prüft den Datentyp zusätzlich: Für Kunden und Kontakte ist dort CRM-Zugriff vorgesehen, für die beiden Seefracht-Typen Ocean-Import-Zugriff. ADMIN wird in dieser datentypspezifischen Prüfung zugelassen. Die allgemeine Modulprüfung vor allen Import-Endpunkten verlangt im Durchsetzungsmodus trotzdem Ocean Import. Deshalb ist ein reiner CRM-Zugang für Kunden- oder Kontaktimporte im geprüften Stand nicht ausreichend belegt.

Die Oberfläche unter Einstellungen → Importe ist ausschließlich für ADMIN sichtbar und nicht für Plattformadministratoren. Im Ocean-Import-Arbeitsbereich kann die Workbench dagegen bei vorhandenem Ocean-Import-Zugriff auch für andere Rollen sichtbar sein. Rollenrechte allein und sichtbare Navigation sind daher keine verlässliche Freigabe: maßgeblich sind Mandantenlizenz, aktuelle Organisationseinheit, Datentyp und bei Seefracht die persönliche Anlegefreigabe. Importaufträge anderer Organisationseinheiten sind für Benutzer ohne organisationsweiten Zugriff weder in der Liste noch per Direktaufruf verfügbar.

Schritt-für-Schritt-Anleitung

Öffnen Sie im Ocean-Import-Arbeitsbereich Daten-Import. Als ADMIN können Sie alternativ Einstellungen → Importe verwenden.
Wählen Sie unter Importtyp den passenden Datentyp. Prüfen Sie die darunter angezeigten Erwartete Spalten (Beispiel); sie sind eine Vorlage, keine vollständige Feldbeschreibung.
Wählen Sie eine Datei und dann Hochladen & analysieren. Die Anwendung legt einen Importauftrag mit dem Status Hochgeladen an und öffnet ihn.
Prüfen Sie im Abschnitt Spalten-Mapping jede Quellspalte. Wählen Sie rechts ein passendes Zielfeld oder – ignorieren –. Bereits erkannte Standardüberschriften werden beim Upload vorausgefüllt. Wählen Sie Mapping speichern.
Wählen Sie Validieren. Kontrollieren Sie die Kacheln Zeilen, Gültig, Fehler und Warnungen sowie die Tabelle Vorschau (erste 100). In der Spalte Hinweise stehen Zeilenfehler und gegebenenfalls Warnungen.
Korrigieren Sie die Datei oder das Mapping und validieren Sie erneut, bis die Fehlerzahl null ist. Die sichtbare Schaltfläche Übernehmen bleibt bei Fehlern deaktiviert.
Wählen Sie Übernehmen. Die Erfolgsmeldung nennt die vom Server gemeldeten Werte, zum Beispiel „Übernommen: 3 neu, 0 übersprungen, 0 Fehler“. Öffnen Sie den Auftrag später über Letzte Imports, wenn Sie Status oder Zeilenvorschau erneut prüfen möchten.

Für Containerimporte muss die Zielakte bereits vorhanden sein. Bei einem Import von Seefracht-Importakten wird für jede gültige Zeile eine neue Akte im Status Entwurf angelegt; existiert der angegebene Kunde noch nicht, legt NeuraPort ihn dabei an. Ein mitgelieferter Container wird an dieser neuen Akte angelegt.

Feldreferenz

Feld	Pflicht	Bedeutung	Validierung
Importtyp	Ja	Bestimmt, welche Zeilenart importiert wird: Kunden, Kontakte, Seefracht-Import Akten oder Container (Import).	Nur diese vier Typen sind verfügbar.
Datei (CSV / XLSX, max. 10 MB)	Ja	Quelldatei des Importauftrags.	Die Oberfläche lässt `.csv`, `.xlsx` und `.tsv` auswählen. Der dokumentierte Importablauf ist CSV oder XLSX; Dateien über 10 MB werden abgewiesen.
Spalten-Mapping	Ja, soweit Daten übernommen werden sollen	Ordnet eine Spalte der Quelldatei einem Zielfeld zu.	Nicht zugeordnete Spalten können mit – ignorieren – ausgelassen werden. Das Speichern setzt den Auftragsstatus auf Spalten zugeordnet.
Firma	Ja bei Kunden	Name des Kunden.	Eine Kundendatenzeile ohne Firma führt zu „Firma/company_name fehlt“.
Kunde / Firma	Ja bei Kontakten	Verweist auf einen vorhandenen Kunden.	Fehlt der Wert, erscheint „Kunde/Firma fehlt“; ist der Kunde beim Übernehmen nicht vorhanden, erscheint „Kunde nicht gefunden“.
Name / Kontakt	Ja bei Kontakten	Vollständiger Name der Kontaktperson.	Fehlt der Wert, erscheint „Kontaktname fehlt“.
Kunde	Ja bei Seefracht-Importakten	Kunde der anzulegenden Importakte.	Fehlt der Wert, erscheint „Kunde fehlt“. Ein nicht vorhandener Kunde wird beim Übernehmen neu angelegt.
MBL, HBL oder Container	Mindestens eins bei Seefracht-Importakten	Master Bill of Lading, House Bill of Lading oder Containernummer zur Identifikation der Importakte.	Mindestens einer dieser Werte muss vorhanden sein; sonst „Mindestens MBL, HBL oder Container muss vorhanden sein“.
Akte	Ja bei Container (Import)	Aktennummer der bereits vorhandenen Zielakte.	Fehlt der Wert, erscheint „Akte/file_number fehlt“; eine nicht auffindbare Akte führt beim Übernehmen zu „Akte nicht gefunden“.
Container / Containernummer	Ja bei Container (Import)	Containernummer des anzulegenden Containers.	Vier Großbuchstaben und sieben Ziffern; Leerzeichen werden bei der Prüfung ignoriert. Andernfalls erscheint „Containernummer ist ungültig“.
Gewicht, VGM, CBM	Nein	Zahlenwerte für Akte oder Container.	Deutsche und internationale Dezimaltrennzeichen werden normalisiert; nicht lesbare Werte werden leer.
ETA, ATA, Frei bis, Gate In, Gate Out, Detention Deadline	Nein	Termin- und Freistellungsdaten.	Zulässige Eingaben sind `JJJJ-MM-TT`, `TT.MM.JJJJ`, `TT/MM/JJJJ` oder `MM/TT/JJJJ`; nicht lesbare Werte werden leer.

Für die automatische Zuordnung erkennt NeuraPort unter anderem die Überschriften Firma, Kunde, Referenz, MBL, HBL, Container, Terminal, Vessel, Voyage, ETA, Frei bis, Akte, Typ, Seal, VGM und Leercontainerdepot. Die genaue Liste hängt vom gewählten Importtyp ab.

Aktuelle Einschränkung: In der Mapping-Auswahl erscheinen neben bereits gespeicherten technischen Zielfeldern auch Beispielüberschriften aller Importvorlagen. Diese Beispielüberschriften sind nicht automatisch ein gültiges Zielfeld. Bevorzugen Sie die beim Upload automatisch vorbelegten Zuordnungen und validieren Sie nach jeder manuellen Änderung. Andernfalls können Pflichtfelder trotz sichtbarer Zuordnung als fehlend gemeldet werden.

Status und mögliche Übergänge

Ausgangszustand	Aktion	Ergebnis
—	Hochladen & analysieren	Hochgeladen; der Auftrag enthält seine Quelldaten und einen vorgeschlagenen Mapping-Entwurf.
Hochgeladen oder anderer vorhandener Zustand	Mapping speichern	Spalten zugeordnet.
Spalten zugeordnet oder anderer vorhandener Zustand	Validieren	Validiert, wenn keine Zeile Fehler enthält; sonst Validierung fehlgeschlagen.
Validiert	Übernehmen	Übernommen, wenn beim Anlegen der gültigen Zeilen kein Laufzeitfehler entsteht.
Validiert	Übernehmen und mindestens ein Laufzeitfehler	Teilweise übernommen. Erfolgreiche Zeilen bleiben übernommen; fehlgeschlagene Zeilen erhalten den Status Fehler.

Bei der Validierung erhalten einzelne Zeilen den Status gültig oder Fehler; neu hochgeladene Zeilen sind zunächst offen. Nach erfolgreicher Übernahme zeigt die Vorschau übernommen. Die Benutzeroberfläche zeigt höchstens die ersten 100 Zeilen. Der Server liefert für die Zeilenansicht höchstens 500 Zeilen; eine vollständige Fehlerdatei oder Rücknahme eines Imports ist in der geprüften Oberfläche nicht vorhanden.

Die sichtbare Schaltfläche Übernehmen verhindert eine Übernahme, solange die letzte Zusammenfassung Fehler enthält. Der Dienst validiert beim Übernehmen dennoch erneut. Direkte Integrationsaufrufe sollten deshalb nicht als Umgehung der Validierung verwendet werden: Zeilen mit Validierungsfehlern werden übersprungen. Der Auftragsstatus Teilweise übernommen steht dabei nur für Fehler, die erst beim eigentlichen Anlegen einer zuvor gültigen Zeile auftreten.

Was im Hintergrund passiert

NeuraPort speichert den Importauftrag in Ihrem Mandanten und in der beim Upload aktuellen Organisationseinheit. Zu jedem Auftrag werden die ursprünglichen Zeilen, das Mapping, die normalisierten Werte, der Zeilenstatus sowie Fehler- und Warnhinweise gespeichert. Upload, Mapping, Validierung und Übernahme werden im Auditprotokoll festgehalten.

CSV-Dateien werden mit einer erkannten Trennung aus Komma, Semikolon oder Tabulator gelesen. Die Zeichencodierung wird zuerst als UTF-8 mit BOM, dann als Windows-1252 und anschließend als Latin-1 verarbeitet. XLSX-Dateien werden aus dem ersten Tabellenblatt gelesen; die erste Zeile ist die Überschrift. Bei XLSX benötigt der Server die Komponente openpyxl; fehlt sie, kann der XLSX-Import nicht ausgeführt werden.

Die Übernahme wirkt je Zeile. Bei Kunden wird ein bereits vorhandener Kunde mit gleichem Firmen- oder Kurznamen wiederverwendet. Diese Wiederverwendung wird vom aktuellen Zähler dennoch als „neu“ gezählt; der Wert ist deshalb kein sicherer Nachweis, dass tatsächlich ebenso viele Kundendatensätze angelegt wurden. Kontakte werden immer einem bereits gefundenen Kunden zugeordnet. Importakten erhalten eine neue Aktennummer, die Richtung Import und den Status Entwurf. Containerimporte legen einen Container an der angegebenen Akte an.

Importaufträge, wiederverwendete Stammdaten und neu entstehende Verknüpfungen dürfen ausschließlich der aktuell freigegebenen Organisationseinheit zugeordnet sein. Prüfen Sie deshalb Kunden, Kontakte und Zielakten vor der Übernahme in den sichtbaren Listen der zuständigen Einheit. Ist die organisatorische Zugehörigkeit nicht eindeutig bestätigt, brechen Sie den Import ab und lassen den Zuordnungsfall administrativ prüfen.

Typische Fehler und Lösungen

Meldung oder Beobachtung	Ursache	Lösung
„Upload fehlgeschlagen“	Die Oberfläche konnte keinen Importauftrag anlegen.	Prüfen Sie Dateigröße, Importtyp, Ihre Mandantenlizenz und den angemeldeten Zugang. Öffnen Sie die Ansicht erneut und wiederholen Sie den Upload.
„Importdatei ist zu groß (max. 10 MB)“	Die Quelldatei überschreitet 10 MB.	Datei aufteilen oder nicht benötigte Spalten und Zeilen entfernen.
„Die Importdatei enthält keine Daten“	Es wurden nach der Überschriftszeile keine Datenzeilen gelesen.	Prüfen Sie Tabellenblatt, Überschriftszeile und Dateiinhalt.
„Unbekannter Importtyp“	Der angeforderte Typ gehört nicht zu den vier unterstützten Typen.	Wählen Sie den Importtyp in der Workbench neu aus; verwenden Sie keine manuell geänderte Anfrage.
„XLSX-Import benötigt openpyxl auf dem Server“	Die notwendige Serverkomponente für Excel-Dateien fehlt.	Verwenden Sie vorübergehend CSV oder lassen Sie die Serverinstallation durch die Administration prüfen.
„Mapping fehlgeschlagen“	Das Mapping konnte nicht gespeichert werden.	Ansicht neu laden, Zuordnungen erneut vornehmen und prüfen, ob Ihr Importauftrag noch in Ihrer Organisationseinheit liegt.
Pflichtfeldfehler trotz manuell gewählter Zuordnung	Die Auswahl kann Beispielüberschriften enthalten, die kein gültiges Zielfeld darstellen.	Automatisches Mapping wiederherstellen oder die Dateiüberschriften an die angezeigte Vorlage anpassen; anschließend erneut validieren.
„Validierung fehlgeschlagen“	Mindestens eine Zeile ist ungültig.	In Vorschau (erste 100) die Spalte Hinweise prüfen, Datei oder Mapping korrigieren und erneut validieren.
„Übernahme fehlgeschlagen“	Die Übernahme konnte nicht abgeschlossen werden.	Auftragsstatus und Zeilenhinweise prüfen. Bei Teilweise übernommen nur die Fehlerzeilen korrigieren und als neuen Import einreichen; es gibt keine sichtbare Rücknahme.
„Keine Berechtigung für diesen Import“ oder keine Importansicht	Modul-, Datentyp- oder Rollenvoraussetzung fehlt.	Ocean-Import-Lizenz, CRM-Zugriff für Stammdatenimporte, persönliche Import-Aktenfreigabe und aktuelle Organisationseinheit durch die Administration prüfen lassen.
„Eintrag nicht gefunden“ oder „Import nicht gefunden“	Der Auftrag liegt außerhalb Ihres Mandanten oder Ihrer zugelassenen Organisationseinheiten, oder existiert nicht.	In die passende Organisationseinheit wechseln oder Zugriffsbereich prüfen lassen.