ERPNext Data Import Tool

Wann nutze ich den Data Import?

Sie dient dazu, Daten strukturiert und fehlerfrei ins System zu übernehmen insbesondere für DocTypes wie (zu den einzelnen Besonderheiten später noch mehr):

Kunden (Customer, Address, Contact)
Artikel (Item, Item Price, Item Group, Taxes)
Lieferanten, Mitarbeiter, Preislisten, Steuern etc.

Einige DocTypes sind im Import-Tool nicht verfügbar. In diesen Fällen muss die Einstellung direkt im jeweiligen DocType angepasst werden (siehe Screenshot).
Dazu den Haken bei „Allow Import (via Data Import Tool)“ aktivieren – nur dann erscheint der DocType in der Auswahlliste des Import-Tools.

Datenimporte sind wesentlich aufwendiger als zunächst erwartet. Plane hier genug Zeit ein.

Wo finde ich den Data Import?

Home > Data Import and Settings > Import Data
Oder: Im jeweiligen Dokument, das hochgeladen werden soll

Vorraussetzungen:

1. Admin-Zugang mit Rechten für Data Import / Master Data.

2. Stammdaten vom Kunden sind aufbereitet als CSV, Excel oder als Google Sheet

1. Falls CSV dann: muss UTF-8 sein, Komma-getrennt (nicht Semikolon!) + keine leeren Zeilen oder zusätzliche Kommata am Ende.

Empfehlung Excel oder Google Sheet, CSV führt eher zu Problemen.

3. Feldnamenabgleich: Alle Spaltenüberschriften müssen exakt den Feldnamen in ERPNext entsprechen. Bei benutzerdefinierten Feldern (Custom Fields) gilt: Diese müssen vorher angelegt und aktiviert sein. ERPNext legt keine neuen Felder automatisch an.

4. Verknüpfungen prüfen: Referenzdatensätze müssen vor dem Upload existieren (besonders beim Artikelupload)

Nicht zu lange überlegen, welche Verknüpfungen bestehen – einfach ausprobieren und gegebenenfalls fehlende Datensätze nachtragen.

5. Datenvalidierung vor Import: Prüfung auf Duplikate, Pflichtfelder, und gültige Datentypen (z. B. Datumsformat YYYY-MM-DD, numerische Felder ohne Sonderzeichen).

Wie funktioniert der Upload generell - Schritt für Schritt:

Data Import Tool öffnen: Gehe zu Daten Import -> wähle das gewünschte Doctype. Entweder updatest du bereits existierenden Daten (hierzu später mehr) oder du lädst neue Stammdaten hoch.

Tipp: Lade das Template in Englisch herunter. Sonderzeichen in deutschen Feldnamen können beim Upload zu Fehlern führen.

Template herunterladen: Klicke auf Download Template, um es dem Kunden zur Verfügung zu stellen (oder die Daten selbst einzutragen). Beim Download werden die Feldnamen als Überschrift bereits zur Verfügung gestellt. Die Daten des Kunden werden dann auf die jeweiligen Felder gematched.

Lade das Template mit Beispieldatensätzen herunter. Lege zunächst einen Stammdatensatz (z. B. Kunde) in der Benutzeroberfläche an und lade anschließend das Template dieses Doctypes herunter. So erkennst du genau, welche Felder relevant sind.

Die Arbeit (mit dem Kunden) in einem Google Document ist zu empfehlen, da hier gemeinsam am Aufbereiten der Daten gearbeitet werden kann. ERP Next ermöglicht den Upload über Google Sheets. Das Template kannst du dir ebenfalls bereits als Google Sheet zur Verfügung stellen lassen.

Daten aufbereiten (selbst oder Kunde): Fülle die CSV oder ein Google Sheet mit den gelieferten Daten. Achte auf:
Achte auf:
- Pflichtfelder ausgefüllt (z. B. customer_name, item_code, customer_group, territory, naming_series)
- Keine zusätzlichen Leerzeilen
- Keine HTML-, Tab- oder Zeilenumbrüche in Textfeldern
- Datumsformat: YYYY-MM-DD
- Boolean-Felder: 1 (Ja) oder 0 (Nein)

Wenn bisher keine eigenen IDs für seine Stammdaten vergeben wurden, können diese Felder im Template leer gelassen werden. ERPNext generiert dann automatisch neue IDs. Aber Achtung: Wenn teilweise IDs vergeben und teilweise ausgelassen werden, können gemischte Datensätze entstehen. Bereits vorhandene IDs können zudem überschrieben werden, falls sie im System schon existieren.

Verknüpfte Doctypes berücksichtigen: Viele Datensätze hängen voneinander ab, daher ist die Reihenfolge des Uploads entscheidend (Mehr dazu in den spezifischen Stammdaten).
Mache einen Testimport: Lade 1–3 Datensätze hoch und überprüfe was im Import Log passiert:
- Grün = erfolgreich
- Gelb = Warnung
- Rot = Fehler
--> Öffne die importierten Datensätze im System und prüfe stichprobenartig die Feldwerte.
Bulk-Import
- Wenn der Test erfolgreich war, dann lade die vollständige Datei (max. 1000 Zeilen pro Lauf) hoch

Selbst nach dem Massen-Import sollte nochmal stichprobenartig durch die für dich zur Verfügung gestellte Daten-Tabelle geprüft werden. Öffne 5–10 zufällig ausgewählte Datensätze direkt im ERPNext. Lasse auch den Kunden ausführlich testen.

Typische Fehlerquellen:

Problem	Ursache	Lösung
`NoneType`-Fehler	Leere Zeile oder fehlendes Pflichtfeld	CSV prüfen, Leerzeilen löschen
„Cannot find DocType“	Doctype falsch geschrieben oder nicht aktiviert	Prüfen, ob Doctype im System existiert
Referenz nicht gefunden	z. B. `Customer Group` nicht vorhanden	Datensatz zuerst im ERPNext anlegen
Falsches Encoding	Excel speichert oft als `ISO-8859-1`	Beim Export als UTF-8 speichern
Falsche Trennzeichen	Semikolon statt Komma	„Komma-getrennt“ wählen
Feld „name“ manuell gesetzt	Konflikt mit Naming Series	Nur `customer_name` + `naming_series` verwenden
Boolean falsch	„Yes/No“ statt 1/0	Immer numerisch (1 = Ja, 0 = Nein)
Fremdzeichen in Feldnamen/Spaltenüberschriften	Umlaute, Sonderzeichen, Zeilenumbrüche. Sonderzeichen oder deutsche Feldnamen führen hier häufig zu Fehlern beim Upload.	UTF-8 sicherstellen oder entfernen

Besonderheiten beim Upload von Kundenstammdaten:

Achtung: Beim Kundenimport geht es nicht nur um den Kunden, sondern um mehrere verbundene DocTypes, die aufeinander aufbauen. Diese sind separat zu importieren und müssen in der richtigen Reihenfolge und korrekt verlinkt sein, damit sie sich in ERPNext verbinden.

Customer (Hauptdatensatz) --> Erst den Kundenstammdatensatz importieren.
Contact (Person, z. B. Ansprechpartner mit Telefonnummer und E-Mail Adresse) --> Danach Kontakte, die über Link-Felder mit Customer verknüpft werden.
Address (Adresse oder Rechnungsanschrift) --> Zuletzt Adressen, ebenfalls mit Link auf Customer.

Es ist möglich erst den Kontakt und die Adresse anzulegen, um danach den Customer mit den direkten Verlinkungen hochzuladen. Eher zu empfehlen für kleiner Datenmengen.

Diese Felder koppeln den Customer mit Contact und Address miteinander: link_doctype = Customer UND link_title = [Name des Kunden]

Pflichtfelder:

Feld	Beschreibung	Beispiel
`customer_name`	Anzeigename	Yoga mit Sandra
`customer_group`	Muss existieren	Commercial
`territory`	Muss existieren	All Territories
`customer_type`	Company oder Individual	Company
`naming_series` (optional)	Wenn du Serien nutzt, ansonsten wird der name von selbst erstellt	CUST-.YYYY.-

Achtung: name und customer_name sind nicht das Gleiche. Wir sehen im Frontend überall den customer_name, aber intern arbeitet ERP Next mit dem Feld name --> Das ist die ID (Field Name)

Das Feld name ist die interne, immer eindeutige Kennung eines Feldes in ERPNext, während das field label die sichtbare Bezeichnung für Nutzer ist. Labels können mehrfach vorkommen, sollten aber beim Datenimport eindeutig zugeordnet werden, um Fehler zu vermeiden.

Festlegen von Name:

Fall 1: Du nutzt eine Naming Series (Standard)

Beispiel: name CUST-.YYYY.- → CUST-2025-0001, customer_name Yoga mit Sandra

ERPNext vergibt automatisch den internen Namen (name) nach dieser Serie.
Dein Import-Feld customer_name ist dann nur der Anzeigename.
Du brauchst das Feld naming_series im Import, damit ERPNext weiß, welche Serie verwendet wird.
Du darfst kein Feld name manuell angeben (sonst kommt es zu Konflikten).

Fall 2: customer_name soll → YOGINI-001

Du lässt naming_series leer.
Du setzt im Feld customer_name deine eigene ID (z. B. YOGINI-001).
ERPNext verwendet dann automatisch deinen Eintrag als internen Namen (name).

Von mir empfohlene Felder:

Feld	Zweck	Beispiel
`customer_code`	Falls du eigene Kundennummern führst	YOGINI-001
`default_price_list`	z. B. “Standard Selling” - Falls abweichend dann auswählbar	Standard Selling
`tax_id`	USt-ID falls notwendig	DE123456789
`language`	Für Kommunikation	de
`sales_partner`	Wenn Partnerstruktur vorhanden	–

Besonderheiten beim Upload von Artikeln:

Achtung: Beim Artikelimport geht es nicht nur um die Artikel selbst, sondern um mehrere verbundene Stammdatensätze, die vorher vorhanden sein müssen, damit dein Import ohne Fehler läuft.

Vor dem Upload: Bevor wir überhaupt Artikel anlegen, muss folgendes vorhanden sein:
1. UOMs - die Einheiten müssen alle vorhanden sein. Prüfe, ob dein Kunde besondere Einheiten hat und falls ja, dann lege auch die über einen Import an.
2. Item Tax Template - Wenn dein Kunde Artikel mit unterschiedlichen Steuersätzen (Beispiel: 7% und 19%), dann müssen diese als Steuervorlagen abgelegt werden, sodass du auf sie verweisen kannst.
3. Artikelgruppen - müssen ebenfalls angelegt sein im Vorhinein
4. Lager und Standardlieferant - Falls deine Produkte gelagert werden, braucht es ein angelegtes Standard-Lager auf das du verweisen kannst. Gleiches gilt für deinen Standardlieferant (gerade bei Dropshipping sehr wichtig!)
Preise: Preise gehören nicht in den Artikel Import, sondern gesondert nach dem Upload der Artikel in den DocType "Artikelpreise". Dieser DocType wird dann mit dem Artikel verlinkt.

Die Pflichtfelder - also die müssen ausgefüllt sein vor dem Upload. Achtung: Felder item_code und item_name dürfen keine Sonderzeichen oder Zeilenumbrüche enthalten.

Feld	Erklärung	Beispiel
`item_code`	Eindeutige Artikelnummer	“YOG-001”
`item_name`	Anzeigename	“Yogamatte aus Kautschuk”
`item_group`	Kategorie	“Yogamatten”
`is_stock_item`	Ja/Nein (1/0)	1
`stock_uom`	Einheit	“Nos”, “Kg”
`default_warehouse`	(optional) Standardlager	“Celias Yoga Lager”
`description`	(optional) Text	“Handgelenk-freundliche Yogamatte”

Der Upload:
1. Immer erst 1–3 Testartikel importieren.
2. Nach erfolgreichem Test:
  - Preise separat via Item Price importieren.
  - Prüfe ob die Steuer richtig angezeigt wird mit einer Test-Rechnung.
3. Dann erst vollständiger Bulk-Import.