Artikel Import Wizard (BAS13)

Transaktion: BAS13 Artikel Import Wizard
UI-Pfad: /materialImport
Backend-Domain: MaterialImport, MaterialImportItem

Business-Zweck

BAS13 ist der geführte Artikel-Import in reybex. Partner legen eine Import-Vorlage an, konfigurieren Quelle und Verhalten, ordnen CSV-Spalten reybex-Feldern zu und starten den Import mit Fortschrittsanzeige und Protokoll.

Im Gegensatz zu BAS05 (reine Vorlagenverwaltung im gleichen technischen Modul) ist BAS13 die Standard-Transaktion für den Wizard-Flow: zweistufiger Dialog, Spaltenabgleich, Speichern & Import, Live-Progress und Import-Log.

Typische Einsatzfälle:

• Erst- oder Delta-Import aus PIM/ERP als CSV
• Wiederkehrender Abruf per FTP/SFTP (mit Job-Intervall)
• Branchenformate DATANORM, DATPREIS, PRICAT, FASHION
• Fulfillment-Rückmeldungen (Import-Typ 8)
• Bestands- oder Preis-Schnellimport, wenn nur wenige Zielspalten gemappt sind

Abgrenzung zu BAS05 und BAS22

Transaktion	Fokus
BAS13	Wizard: Vorlage anlegen, Mapping, Import starten, Fortschritt & Log
BAS05	Gleiche Datenbasis (MaterialImport), Fokus auf Vorlagenpflege ohne Wizard-Transaktionscode
BAS22	Bildimport zu Artikeln/Varianten (eigene Endpoints)

Technisch teilen BAS05 und BAS13 dieselbe API (/api/materialImport) und Domain-Modelle; die UI unter BAS13 öffnet den Wizard (TemplateDialog).

Oberflächen-Flow

Startseite

• Tab CSV-Import → Liste gespeicherter Import-Vorlagen
• Button Neu → Wizard im Erstellmodus
• Zeile bearbeiten → Wizard mit bestehender Vorlage
• Löschen → soft-delete der Vorlage inkl. Mapping-Zeilen

Schritt 1 – Import-Einstellungen

Pflichtfelder vor dem Weiter-Klick:

• Name der Vorlage
• Material-Template (Vorlage-Artikel als Default-Werte)
• Lager (Ziel-Lager für Bestandsbuchungen)

Optionale und Verhaltens-Felder siehe Vorlagenfelder (MaterialImport).

Schritt 2 – Datei-Einstellungen & Spalten-Mapping

Abhängig vom Import-Typ:

1. Datei-Parameter (Encoding, Trennzeichen, Anführungszeichen)
2. Quelle (Datei-Upload, FTP/HTTP, Branchenformat)
3. Button Spalten aus Datei lesen → automatisches Mapping via matchColumns
4. Manuelle Korrektur: Quellspalte → Ziel-Feld
5. Speichern oder Speichern & Import

Nach Speichern & Import erscheint der Fortschrittsdialog (Progress, succeeded, skipped, Abbruch).

Vorlagenfelder (MaterialImport)

Stammdaten der Vorlage

Feld	Typ	Pflicht	Beschreibung
name	String	Ja	Bezeichnung der Import-Vorlage
materialTemplate	Referenz Material	Ja	Default-Werte für neu angelegte Artikel
warehouse	Referenz Warehouse	Ja	Lager für Bestandsimport/-buchungen
brand	Referenz Brand	Nein	Standard-Marke für neue Artikel
customer	Referenz Customer	Nein	Kundenbezug (z. B. kundenspezifische Artikelnummern)
validFrom / validUntil	Date	Nein	Gültigkeit der Vorlage (optional)

Import-Modus (importMode)

Wert	Bedeutung
1	Anlegen und Aktualisieren – bestehende Artikel werden gematcht und aktualisiert, fehlende neu angelegt
2	Nur Anlegen – vorhandene Treffer werden übersprungen
3	Nur Aktualisieren – nur bestehende Artikel werden geändert

Artikel-Matching (materialMatchingType)

Steuert, welches Feld zum Finden bestehender Artikel verwendet wird:

Wert	Match-Feld
0	matCode (Artikelnummer)
1	eanCode (EAN der Basiseinheit)
2	description (Bezeichnung)
3	vendorMatCode (Lieferanten-Artikelnummer)
4	gtin
5	manufacturerNumber (Herstellernummer)
6	variant_sku (Varianten-SKU)

Import-Typ (importType)

Wert	Bezeichnung	Quelle / Verhalten
0	CSV/XML	Datei-Upload, manuelles Mapping
1	FTP	FTP/SFTP-Abruf (Port 22 = SFTP)
2	HTTP	HTTP-Abruf mit Job-Intervall
3	DATANORM	Branchenformat, eigene Parser-Logik
4	DATPREIS	Branchenformat Preise
5	PRICAT	Branchenformat Katalog
6	FASHION	Fashion-Schnittstelle (Passwort + Artikelnummern)
7	Custom XML	Individuelles XML (reybex-Kontakt nötig)
8	Fulfillment	Fulfillment-Rückmeldungen, eigenes Feld-Set

Datei- und FTP-Parameter

Feld	Typ	Beschreibung
characterEncoding	String	Zeichensatz (z. B. UTF-8, ISO-8859-1)
delimiter	Character	CSV-Trennzeichen (Standard ;)
quoteMode	Boolean	Anführungszeichen-Modus für CSV-Parser
hasHeader	Boolean	Erste Zeile enthält Spaltenüberschriften
server	String	FTP/HTTP-Host
port	Integer	Port (22 → SFTP)
username / password	String	Zugangsdaten
path	String	Remote-Pfad
filename	String	Dateiname auf dem Server
jobInterval	Short	Automatik: 0 manuell, 1–5 alle 2/4/8/12/24 h, 6 periodisch (hours)
hours	String	Stundenangabe bei jobInterval = 6
moveProcessedFiles	Boolean	Verarbeitete Dateien verschieben
readAllFiles	Boolean	Alle Dateien im Pfad lesen

Verhaltens-Schalter (Booleans)

Feld	Wirkung
matCodeFromExtern	Artikelnummer aus Importdatei übernehmen (statt Nummernkreis)
isGrossPrice	Importierte Preise als Bruttopreise interpretieren
isSetImport	Stücklisten-/Set-Import (Komponenten aus set:*-Feldern)
createMissingLookupData	Fehlende Lookup-Werte (Gruppe, Einheit, …) automatisch anlegen
isExternalStockCleared	Vor Import externen Bestand im Ziel-Lager auf 0 setzen
isStockExclusiveImport	Nur Bestand importieren (Spezialfall)
setAllMaterialCategoryLevels	Materialkategorie-Hierarchie vollständig setzen
isDebug	Debug-Modus
isReworkedImport	Beta-Flag für überarbeiteten Import
materialFieldsToImport	Komma-getrennte Feld-IDs für Marktplatz/Custom-XML (siehe unten)
customXmlTemplate	Referenz auf Custom-XML-Vorlage (Typ 7)

Marktplatz-Feldfilter (materialFieldsToImport)

Bei Import-Typ Custom XML (7) kann eingeschränkt werden, welche Datenbereiche aktualisiert werden. Mögliche Werte (Enum MaterialImportFields):

ID	Bereich
1	Name
2	Attribute
3	Lieferanten-Artikelnummer
4	SKU
5	Preis
6	Bestand
7	Beschreibung
8	Detailbeschreibung
9	Bilder
10	Varianten
11	Varianten-SKU
12	Kategorie
13	MwSt-Satz
14	Hersteller
15	SEO
16	GTIN
17	Varianten-EAN

Spalten-Mapping (MaterialImportItem)

Jede Mapping-Zeile verbindet eine Quellspalte der Datei mit einem Ziel-Feld in reybex:

Feld	Beschreibung
sourceColumn	Spaltenname/-index aus CSV (z. B. Artikelnr oder Column_1)
targetColumn	Technischer Feldname (siehe Importierbare Ziel-Felder)
columnOrder	Reihenfolge der Spalten
isConstant	Konstante Zuordnung (nicht aus Datei)

Beim Speichern sendet die UI pro Spalte sourceColumn{n} und targetColumn{n} sowie columnAmount.

Regeln:

• Jedes targetColumn darf pro Import nur einmal vorkommen (Ausnahme: materialAttributeValue)
• Ohne Mapping-Zeilen bricht der CSV-Import ab
• Auto-Mapping (matchColumns) erkennt Spalten anhand Domain-Feldnamen oder Übersetzungen (Localization)

Spezial-Import-Pfade

Der Service erkennt anhand der gemappten Felder alternative Importwege:

Gemappte Felder	Verhalten
stockItems, stockItems_batchnum, stockItems_stockPlaceCode, stockItems_licenseKey, stockItems_expiryDate, variant_sku	Bestands-Schnellimport (importStock)
purPrice, salesPriceGross	Preis-Schnellimport (importPrice)
importType = 8	Fulfillment-Import
isSetImport = true	Set-/Stücklisten-Import

Importierbare Ziel-Felder

Die Liste wird dynamisch über listMaterialProperties() erzeugt. Partner sehen in der UI die übersetzte Beschreibung, technisch relevant ist der name-Wert.

Artikel-Stammdaten (Material)

Alle persistenten Material-Felder außer System-/Relationsfelder:

lastUpdated, dateCreated, createdBy, updatedBy, salesItems, variants, stocks, attachments, tenantId, prices, isDelete, materialStockStatistics, translations, stock, transfers, purItems, materialBoms, rawMaterials, marktplaces, collectibles, materialAttributes, materialClones, salesCustomerPrices, variant, hasPictures, uniqueName, isVoucher, isMaterialEditable

Identifikation & Texte

Ziel-Feld	Typ	Hinweis
matCode	String	Interne Artikelnummer
printMatCode	String	Druck-Artikelnummer
sku	String	SKU (eindeutig inkl. Varianten)
masterSku	String	Master-SKU (Intercompany)
asin	String	Amazon ASIN
gtin	String	GTIN
pzn	String	Pharmazentralnummer
vendorMatCode	String	Lieferanten-Artikelnummer
manufacturerNumber	String	Herstellernummer
name	String	Bezeichnung
description	String	Kurzbeschreibung
detailDescription	String	Langtext
setupManual	String	Aufbauanleitung
note	String	Notiz
content	String	Inhalt (z. B. Mengenangabe)
searchKey / searchValue	String	Suchbegriffe
productLink	String	Produkt-URL
customNum	String	Freies Kennzeichen
statMatNum	String	Statistik-Artikelnummer

Preise & Bewertung

Ziel-Feld	Typ	Hinweis
purPrice	Double	Einkaufspreis
aquisitionPrice	Double	Bezugspreis
costPrice	Double	Einstandspreis
salesPrice	Double	VK netto
salesPriceGross	Double	VK brutto
cashRegisterPrice	Double	Kassenpreis
averagePrice	Double	Durchschnittspreis
lastPurPrice	Double	Letzter EK
lowestPurPrice	Double	Niedrigster EK
rrp	Double	UVP
rrpIsLocked	Boolean	UVP gesperrt
accessoryPrice	Double	Zubehörpreis
productionCost	Double	Herstellkosten
evaluationType	Short	1 Standard-EK, 2 letzter EK, 3 Ø-Preis
surchage1toAquisition … surcharge2toSales	Double	Aufschläge
priceUnit	Double	Preiseinheit (Menge)
balanceDiscountSurchargeReason	String	Rabatt-/Zuschlagsgrund

Maße & Gewichte

Ziel-Feld	Typ
netWeight, grossWeight, volume	Double
width, height, length	Double
hazardousVolume, hazardousWeight	Double
bottleCountInBox	Integer

Referenz-Felder (Lookup per Code/Name): netWeightUnit, grossWeightUnit, warehouseUnit, secondWarehouseUnit, purUnit, salUnit, baseUnit, basePriceUnit, capacityUnit, packUnit

Lager & Disposition

Ziel-Feld	Typ	Hinweis
safetyStockLevel	Double	Sicherheitsbestand
reorderStockLevel	Double	Meldebestand
maxStockLevel	Double	Maximalbestand
fixOrderQuantity	Double	Fixbestellmenge
minOrderQuantity	Double	Mindestbestellmenge
maxOrderQuantity	Double	Maximalbestellmenge
batchSize / salesBatchSize	Double	Losgrößen
abcCategory	String	ABC-Klasse
deliveryDays	Integer	Lieferzeit
automaticOrderDays	Integer	Auto-Bestellung
stockCarrierSku	String	Träger-Artikel-SKU
stockCarrierBookingMultiplier	Double	Buchungsfaktor
parentVariantSku	String	Eltern-Variante

Status & Flags (Boolean/Short)

isStocked, isSet, isNotDiscountable, isSerialManagement, isSerialNumberRequired, isLotEnabled, isShelfLife, isService, isTemplate, isDiverse, isCollectible, isProvisionable, isPrePayment, isThirdParty, isPackaging, isPacked, isAutomaticOrder, isGroupOrdersByVendor, isAttributeStocked, isAutoPrintIncomingGoodsLabel, isSoftSerialManagement, isStockFreeze, ignoreExternalStocks, isZeroPriceMaterial, isVatKeyReduced, isDemoData, hasVariants, justInTimeProduction

Referenzen (Lookup)

Ziel-Feld	Domain
matGroup	Artikelgruppe
matStatus	Artikelstatus
materialType	Materialtyp
brand	Marke
vatKey	MwSt-Schlüssel
countryOrigin / countryHome	Land
mrpMethod	Dispositionsverfahren
substituteMaterial / replacementMaterial	Ersatzartikel
costCenter	Kostenstelle
accountPurchaseInland … accountSalesOverseas	Konten
danger / dangerousCode	Gefahrgut
purDepartment	Einkaufsabteilung
prodDocType	Produktionsbelegart
qualityPlan	Prüfplan
packaging	Verpackung
vendor	Lieferant
materialEnergyEfficiency	Energieeffizienz
alternativeBomHead	Stückliste

Technische / Zeichnungs-Felder

drawNumber, drawVersion, drawingDate, revisionNumber, salesUnitCode, salesPositionsTypeText, bookingNotes, customsName, warrantyPeriod, weeeNumber, ktbl, planHorizontType

Gültigkeit

validFrom, validUntil

Einheiten & EAN

Ziel-Feld	Typ	Beschreibung
eanCode	MaterialUnit	EAN der Basiseinheit
material_materialUnits	MaterialUnits	Einheitsdefinitionen

Stücklisten (Set-Import)

Ziel-Feld	Typ
set:matCode	MaterialBom – Komponenten-Artikelnummer
set:description	MaterialBom – Bezeichnung
set:amount	MaterialBom – Menge
set:unit	MaterialBom – Einheit

Merkmale & Attribute

Ziel-Feld	Typ
materialAttributeValue	Freies Merkmal (mehrfach erlaubt)
attribute_{id}	Merkmal an Artikel (ID aus Attribut-Stamm)
variant_attribute_{id}	Merkmal an Variante

Bilder

Ziel-Feld	Typ
picture1 … picture10	Bild-URL oder Pfad

Varianten (variant_*)

Ziel-Feld	Beschreibung
variant_name	Variantenname
variant_eanCode	EAN
variant_sku	SKU (auch Matching-Typ 6)
variant_asin	ASIN
variant_order	Sortierung
variant_marketplaceVariantId	Marktplatz-Varianten-ID
variant_volume	Volumen
variant_stockCarrierSku	Träger-SKU
variant_stockCarrierBookingMultiplier	Buchungsfaktor
variant_netWeight / variant_grossWeight	Gewichte
variant_netWeightUnit	Gewichtseinheit

Lagerplätze & Chargen (stockItems_*)

Ziel-Feld	Beschreibung
stockItems	Bestandsmenge
stockItems_batchnum	Charge
stockItems_stockPlaceCode	Lagerplatz
stockItems_licenseKey	Lizenzschlüssel
stockItems_expiryDate	MHD
stockItems_materialStockPlaceCode	Material-Lagerplatz
stockItems_materialStockPlaceCodeIsDefault	Standardplatz
stockItems_materialStockPlaceCodeIsPickplace	Pickplatz
stockItems_materialStockPlaceCodeIsDefaultIn	Standard Eingang
stockItems_materialStockPlaceCodeIsDefaultOut	Standard Ausgang
stockItems_materialStockPlaceCodeIsDelete	Lagerplatz löschen

Übersetzungen (language_{code}_{feld})

Pro aktivierter Sprache (de, en, …) und Feld aus:

name, description, detailDescription, imagesAltText, keyWord, metaTitle, urlkey, metaDescription

Beispiel: language_en_name = englische Bezeichnung.

Preislisten (materialPrices_*)

Ziel-Feld	Beschreibung
materialPrices_marktplace	Marktplatz
materialPrices_customerGroup	Kundengruppe
materialPrices_percentFromSurcharge	Prozent vom Aufschlag
materialPrices_price	Preis
materialPrices_currency	Währung
materialPrices_unit	Einheit
materialPrices_unitQuantity	Einheitsmenge
materialPrices_validFrom / validUntil	Gültigkeit
materialPrices_salesPriceGross	Bruttopreis
materialPrices_quantity / quantityTo	Staffelmenge
customerGroup_materialPrices	Kundengruppen-Preise

Marktplatz-Felder (marketplace_{feld}_{marktplaceId})

Pro konfiguriertem Marktplatz dynamisch – abhängig vom Provider (Amazon, eBay, …) oder generisches MARKETPLACE_FIELDS-Set. Typische Bereiche: Listing-Titel, Kategorien, Versandprofile, Marktplatz-spezifische Attribute.

Fulfillment (Import-Typ 8)

Ziel-Feld	Beschreibung
head_receiptRequestNumber	Wareneingangsnummer
head_processNumber	Vorgangsnummer (Auftrag)
head_reasonCode	Grundcode
head_customerNumber	Kundennummer
head_customerName	Kundenname
item_quantity	Menge
item_articleNumber	Artikelnummer
item_reasonCode	Positions-Grundcode

Import-Ausführung & Protokoll

Ablauf

1. Vorlage speichern (POST /api/materialImport/)
2. Optional: Fortschritt zurücksetzen (GET /api/materialImportLog/resetProcessStatus/{id})
3. Import starten (POST /api/materialImport/doMaterialImportFromCsv) → HTTP 202 Accepted
4. Fortschritt pollen (GET /api/materialImportLog/processStatus/{materialImportId})
5. Abbruch (GET /api/materialImportLog/abortImport/{id})
6. Detail-Log (GET /api/materialImportLog/{id}, Zeilen via getImportLogItems)

Protokoll-Felder (ImportLogItem)

Feld	Bedeutung
recordNumber	Zeilennummer in der Quelldatei
isSuccessful	Zeile erfolgreich
skipped	Zeile übersprungen
message	Fehler- oder Hinweistext
code	Artikelkennung aus Import

ProcessStatus

Feld	Bedeutung
progress	0–100 %
succeeded	Anzahl erfolgreicher Datensätze
skipped	Anzahl übersprungener Datensätze
abortImport	Abbruch angefordert

Partner-Szenarien

CSV-Delta mit matCode-Matching

1. Import-Modus Anlegen und Aktualisieren, Matching matCode
2. Mapping: Artikelnr → matCode, VK → salesPrice, Bestand → stockItems
3. createMissingLookupData aktiv, wenn neue Gruppen/Einheiten mitgeliefert werden
4. Nach Import Log auf skipped und message prüfen

Nächtlicher FTP-Import

1. Import-Typ FTP, Zugangsdaten testen (Verbindung senden)
2. jobInterval = 24 h, filename und path setzen
3. Job importMaterialsPerJob (Scheduler) oder manueller Start aus UI

Nur Bestand aktualisieren

Mapping minimal: variant_sku + stockItems. Service nutzt importStock ohne vollständigen Artikel-Parser.

Externen Bestand ersetzen

isExternalStockCleared = true → vor Import wird externer Bestand im Ziel-Lager auf 0 gesetzt, danach neu gebucht.

Voraussetzungen

• Prüftabellen: Einheiten, Artikelgruppen, MwSt
• Material-Template mit sinnvollen Defaults
• Schreibberechtigung BAS13
• Bei FTP: Firewall-Freigabe, Test via checkFtpConnection

Typische Fehlerquellen

Symptom	Ursache
Doppeltes Ziel-Feld	Gleiches targetColumn zweimal gemappt
Keine Zeilen verarbeitet	Kein Mapping oder leere Datei
Demo-Limit	Mandant im Demo-Modus – max. Artikelanzahl überschritten
Encoding-Fehler	Umlaute falsch – characterEncoding anpassen
Match findet nichts	Falscher materialMatchingType oder Import-Modus „nur anlegen“
FTP schlägt fehl	Port 21 vs. 22 (SFTP), Pfad oder Dateiname

Weiterlesen

• Artikel-Import Vorlagen & Bilder (BAS05/BAS22)

• Artikelstamm (BAS02)