Transformer-Konfiguration für Stammdaten-Importe

Diese Anleitung beschreibt, wie Sie im Master Data Hub die Importkonfiguration (Transformer-Konfiguration) einer Stammdatenliste einsehen und anpassen. Sie bestimmt, welche Datei vom SFTP-Server gelesen wird, wie sie eingelesen wird (Codierung, Trennzeichen, …) und wie die Spalten Ihrer Datei auf das von Workist erwartete Zielschema abgebildet werden. Dieselbe Konfiguration gilt für Dateien, die Sie in der Workbench hochladen oder über die API liefern.

Jede Stammdatenliste (Artikel, Kunden, Kundenkontakte, Adressen, Einheitenkonvertierung, Rahmenverträge, Bestellungen, Angebote) hat eine eigene Konfiguration.

Voraussetzungen

Ein Workbench-Konto mit der Rolle Manager, IT oder Admin (siehe Benutzer und Rollen).
Eine Stammdatenliste im Master Data Hub. Wie Sie eine Liste anlegen, steht unter Liste anlegen.
Mindestens eine Beispieldatei, deren Spaltennamen Sie kennen — sonst können Sie die Zuordnung auf das Zielschema nicht vornehmen.

Individuelle Importskripte

Für manche Listen richtet Workist ein individuelles Importskript ein, z. B. wenn mehrere Dateien zu einer Liste zusammengeführt werden. Dann wirken nur die Dateinamensmuster und die Dateileser-Parameter. Speichern Sie in diesem Fall keine Spaltenzuordnungen: Der Import schlägt sonst fehl.

Schritt 1 — Konfiguration öffnen

Öffnen Sie die Liste im Master Data Hub und wechseln Sie auf den Reiter für die Konfiguration. Sie gelangen auch aus einem Kanal dorthin:

über das Kanalmenü → Stammdaten verwalten und das Zahnrad (Import konfigurieren) in der Zeile der Liste, oder
über die Kanal-Konfiguration → Stammdaten und das Zahnrad neben dem Feld der Liste.

Beide Zahnräder öffnen die Liste in einem neuen Tab.

Schritt 2 — Aufbau der Seite

Der Reiter besteht aus drei Teilen:

Die Importkonfiguration mit den Bereichen Dateinamensmuster, Dateileser-Parameter und Spaltenzuordnungen.
Den Probelauf, der die Konfiguration testet, ohne etwas zu importieren (siehe Schritt 7).
Eine Leiste am unteren Rand, die zeigt, ob es ungespeicherte Änderungen gibt. Sie enthält die Schaltflächen zum Verwerfen und zum Speichern.

Schritt 3 — Dateinamensmuster

Im Abschnitt Dateinamensmuster legen Sie fest, welche Datei in Ihrem SFTP-Verzeichnis /export als Eingabe für diese Liste gilt.

Fester Dateiname, z. B. customer_article_list.csv.
Wildcard *, z. B. articles_*_full.csv.
Datums- und Zeitplatzhalter %Y, %m, %d, %H, %M und %S, z. B. %Y%m%d_Artikel.csv für 20240315_Artikel.csv. Wildcards und Datumsplatzhalter lassen sich nicht in einem Muster kombinieren.
Regulärer Ausdruck mit dem Präfix re:, z. B. re:Artikel_[0-9]+\.csv.

Passen mehrere Dateien auf das Muster, importiert Workist die neueste. Passt eine Datei auf die Muster mehrerer Listen, importiert Workist sie in jede dieser Listen.

Tragen Sie pro Liste ein Muster ein. Mit Muster hinzufügen lassen sich zwar weitere Muster ergänzen, die Standardverarbeitung importiert aber nur eine Datei pro Liste; mit mehreren Mustern schlägt der Import fehl. Mehrere Dateien führt nur ein individuelles Importskript von Workist zusammen.

Für Dateien, die Sie in der Workbench hochladen oder per API liefern, spielt der Dateiname keine Rolle.

tipp

Verwenden Sie möglichst restriktive Muster. Ein zu breites Muster wie *.csv kann dazu führen, dass artikelfremde Dateien versehentlich als Artikelliste interpretiert werden.

Schritt 4 — Dateileser-Parameter

Im Abschnitt Dateileser-Parameter stellen Sie ein, wie Workist Ihre Datei einliest. Jeder Parameter steht zunächst auf Nicht gesetzt; dann gilt der Standardwert.

Parameter	Bedeutung	Beispiel
Trennzeichen	Spaltentrenner in CSV-Dateien. Standard ist das Komma. Workist erkennt das Trennzeichen beim Import nicht automatisch: Verwendet die Datei ein anderes Trennzeichen als eingestellt, schlägt der Import mit Unerwartetes Trennzeichen fehl.	`;` oder `,`
Codierung	Zeichensatz der Datei. Standard ist UTF-8. Für CSV-Dateien aus Excel mit „UTF-8 mit BOM“ wählen Sie `utf-8-sig`.	`utf-8`, `utf-8-sig`, `utf-16`, `latin-1`, `cp1252`, `ascii`
Anführungszeichenzeichen	Zeichen, mit dem Werte in der CSV-Datei eingefasst sind. Standard ist `"`.	`"` oder `'`
Escape-Zeichen	Zeichen zum Maskieren des Anführungszeichens innerhalb eines Wertes.	`\`

Welche Werte zu Ihrer Datei passen, schlägt der Probelauf vor.

hinweis

Für Excel-Dateien (.xls, .xlsx) lassen Sie alle Parameter auf Nicht gesetzt. Workist erkennt das Format an der Dateiendung; gesetzte Parameter lassen den Import von Excel-Dateien fehlschlagen.

Schritt 5 — Spaltenzuordnungen

Im Abschnitt Spaltenzuordnungen ordnen Sie die Spalten Ihrer Eingabedatei den Spalten des Workist-Zielschemas zu.

Jede Zeile besteht aus zwei Feldern:

Spaltenname — die Zielspalte, ausgewählt aus den Spalten des Stammdatentyps (siehe Zielspalten je Stammdatentyp).

Spaltenausdruck — woher der Wert kommt. Fünf Ausdrucksarten sind möglich:

Ausdruck	Bedeutung
`Artikelnummer`	Direkte Spaltenreferenz — der Wert wird 1:1 aus der gleichnamigen Spalte übernommen.
`{Bezeichnung1} {Bezeichnung2}`	Vorlagen-Ausdruck — Platzhalter in geschweiften Klammern werden durch Spaltenwerte ersetzt.
`'STK'`	Stringliteral — der Wert wird fest hinterlegt (z. B. eine konstante Einheit).
`PASS`	Beibehalten, wenn vorhanden — die gleichnamige Spalte wird durchgereicht; ist sie nicht da, wird die Zuordnung ignoriert.
(leer)	Keine Zuordnung — die Zeile wird beim Speichern entfernt.

Beispiel für eine Artikelliste:

Spaltenname	Spaltenausdruck
`article_id1` *	`Artikelnummer`
`description` *	`{Bezeichnung_DE} {Farbe}`
`gross_price`	`Listenpreis`
`order_units`	`Bestelleinheit`

Was Sie dabei beachten sollten:

Nur zugeordnete Spalten werden importiert. Sobald eine Zuordnung gespeichert ist, übernimmt Workist ausschließlich die zugeordneten Spalten; alle anderen Spalten der Datei ignoriert es. Ohne Zuordnungen übernimmt Workist die Spalten der Datei unverändert. Dann müssen sie bereits wie die Workist-Spalten heißen.
Mit * markierte Zeilen zeigt das Formular für jeden Stammdatentyp immer an; Sie können sie nicht entfernen. Lassen Sie den Spaltenausdruck leer, wenn Sie für eine solche Spalte keine Zuordnung brauchen. Der Import prüft nicht, ob diese Spalten gefüllt sind. Welche Spalten Workist für die Erkennung wirklich braucht, steht auf den Seiten der einzelnen Stammdaten-Typen.
partition_id belegt das Formular mit 'main' vor. main bedeutet: Die Zeile gilt für alle Kunden (siehe Zuordnung zu Kunden). Enthält Ihre Datei eine Spalte mit der Kundennummer, ersetzen Sie 'main' durch deren Namen.
Nicht zugeordnete Zeilen fügt der Probelauf für Spalten Ihrer Datei hinzu, die keiner Workist-Spalte entsprechen. Wählen Sie dafür eine Zielspalte; andernfalls entfernt Workist die Zeile beim Speichern.
Ein orangefarbenes ! markiert eine Zielspalte, die es für diesen Stammdatentyp nicht gibt. Eine solche Zuordnung lässt den Import fehlschlagen; entfernen Sie die Zeile.

Mit Spaltenzuordnung hinzufügen lassen sich weitere Zuordnungen ergänzen, bis alle Spalten des Zielschemas verwendet sind. Über das Mülleimer-Symbol kann jede optionale Zuordnung wieder entfernt werden.

Schritt 6 — Reiter „Rohes JSON" für fortgeschrittene Felder

Über den Reiter Rohes JSON sehen Sie die komplette Transformer-Konfiguration als JSON-Dokument und können sie direkt bearbeiten.

Reiter „Rohes JSON" mit aktueller Konfiguration

Im JSON-Reiter sind insbesondere Felder verfügbar, die im Formular nicht angezeigt werden:

apply_common_functions — eine Liste vordefinierter Transformationen, die in der angegebenen Reihenfolge auf die Datei angewendet werden, z. B.:
- query — Zeilen anhand einer Bedingung herausfiltern ("query": "source_unit != target_unit").
- strip — führende und folgende Leerzeichen entfernen.
- drop_column — eine Spalte aus dem Ergebnis entfernen.
- remove_duplicated_rows — doppelte Zeilen entfernen.
- remove_leading_zeros — führende Nullen in einer Spalte abschneiden (häufig bei Artikelnummern).
- set_default_order_unit / set_default_order_unit_to_sales_unit / ensure_sales_unit_in_order_unit — Bestelleinheiten standardisieren.
- eval_expression — einen Ausdruck zur Berechnung eines neuen Spaltenwerts auswerten (z. B. zusammengesetzte Kundenbezeichnung).
- add_incremental_id — eine fortlaufende ID als Spalte hinzufügen.
- filter_by_length / detect_chars — Zeilen anhand der Länge oder eines Musters in einer Spalte filtern.
replace_nan — leere Werte einer Spalte durch einen Standardwert ersetzen.
query — globale Filter-Bedingung, die direkt nach dem Einlesen ausgewertet wird.

Beispiel-JSON für eine Artikelliste mit Pflicht-Pflege:

{
  "file_name_patterns": ["customer_article_list.csv"],
  "file_reader_kwargs": {
    "encoding": "utf-8",
    "delimiter": ";"
  },
  "columns": {
    "article_id1": "Artikelnummer",
    "description": "{Bezeichnung_DE} {Farbe}",
    "partition_id": "'main'",
    "gross_price": "Listenpreis",
    "order_units": "Bestelleinheit",
    "sales_units": "Verkaufseinheit"
  },
  "apply_common_functions": [
    { "strip": "description" },
    { "remove_leading_zeros": "article_id1" },
    { "remove_duplicated_rows": ["article_id1"] }
  ]
}

Sobald Sie etwas am JSON ändern, erscheint unten ein roter Hinweis, falls das JSON syntaktisch nicht gültig ist. Über JSON formatieren lässt sich der Text einrücken und ordnen, ohne den Inhalt zu verändern.

warnung

Die Spaltennamen auf der linken Seite von "columns" müssen aus dem Zielschema des jeweiligen Lookup-Typs stammen — andernfalls wird die Konfiguration beim Speichern abgelehnt.

Schritt 7 — Testen und speichern

Testen Sie die Konfiguration mit einem Probelauf. Er verwendet auch ungespeicherte Änderungen und zeigt, wie Workist Ihre Datei umwandelt. Eine Zuordnung auf eine unbekannte Zielspalte oder eine fehlende Spalte in der Datei fällt hier auf, bevor ein echter Import scheitert.
Klicken Sie in der Leiste am unteren Rand auf Speichern. Workist lädt danach die gespeicherte Konfiguration neu. Ungespeicherte Änderungen können Sie dort auch verwerfen.

Wann greift die neue Konfiguration?

Ab dem nächsten Import. Bereits importierte Daten verarbeitet Workist nicht automatisch neu. Um die neue Konfiguration sofort anzuwenden, starten Sie im Master Data Hub einen Import aus dem SFTP-Verzeichnis, laden die Datei erneut hoch oder liefern sie erneut per SFTP. Auch eine unveränderte Datei verarbeitet Workist nach einer Konfigurationsänderung neu.

Zielspalten je Stammdatentyp

Welche Spalten im Spaltenname-Feld zur Auswahl stehen, hängt vom Stammdatentyp ab. Was jede Spalte bedeutet und wofür Workist sie braucht, steht auf der jeweils verlinkten Seite.

Stammdatentyp	Im Formular immer angezeigt (`*`)	Weitere Zielspalten
Artikel	`article_id1`, `description`	`partition_id`, `article_id2`, `article_id3`, `article_status`, `gross_price`, `order_units`, `sales_units`, `sales_organisation`, `variants`, `extra_data`
Kunden	`client_id1`	`client_id2`, `client_id3`, `company_name`, `address1`, `street_name`, `street_number`, `address2`, `zip_code`, `city`, `country_subdivision`, `country`, `po_box`, `misc`, `client_type`, `client_contact_person1`, `domain`, `iln`, `vat`, `iban`, `swift`, `locale_numeric`, `locale`, `internal_note`, `partition_id`, `extra_data`
Kundenkontakte	`contact_id`, `first_name`, `last_name`, `partition_id`	`phone`, `mobile_phone`, `email`, `extra_data`
Adressen	`address_id1`	`partition_id`, `address_id2`, `address_id3`, `name`, `address1`, `street_name`, `street_number`, `address2`, `zip_code`, `city`, `country_subdivision`, `country`, `po_box`, `misc`, `contact_person`, `phone`, `extra_data`
Einheitenkonvertierung	`source_unit`, `target_unit`, `conversion_quotient`	`partition_id`, `article_id`, `extra_data`
Rahmenverträge	`partition_id`, `contract_id1`	`client_id`, `client_name`, `contract_id2`, `contract_name`, `extra_data`
Bestellungen	`order_number`	`partition_id`, `external_reference`, `order_date`, `delivery_address`, `receiver_number`, `order_total_price`, `iban`, `swift`, `account`, `payment_terms_type`, `payment_terms_discount`, `payment_terms_due_days`, `position_number`, `article_id1`, `article_id2`, `article_id3`, `article_description`, `article_price`, `price_unit`, `quantity`, `unit`, `total_price`, `delivery_date`, `extra_data`
Angebote	`offer_number`	`partition_id`, `valid_from`, `valid_until`, `position_number`, `article_id1`, `article_id2`, `article_id3`, `article_description`, `quantity`, `unit`

Die mit * markierten Spalten zeigt das Formular immer an; Pflicht im Sinne einer Importprüfung sind sie nicht. Bei Artikeln enthält die Auswahl außerdem description_boosted und die order_unit_conversion_*-Spalten. Diese sind intern bzw. veraltet; für Einheiten nutzen Sie die Einheitenkonvertierung. Verwenden Sie nur die Zielspalten aus dieser Tabelle.

Hilfe und Support

Wenn der Import nach einer Änderung weiterhin scheitert oder die gewünschten Werte nicht im Workist-Schema landen, wenden Sie sich an Ihre Ansprechperson bei Workist und halten Sie die folgenden Informationen bereit:

den Namen der Liste im Master Data Hub und den Stammdatentyp (z. B. „Artikel“),
den Zeitpunkt des fehlgeschlagenen Imports (Spalte Importiert am),
die Eingabedatei des Imports (in der Importhistorie verlinkt),
die Fehlermeldung des Imports bzw. das Ergebnis eines Probelaufs.

Voraussetzungen​

Schritt 1 — Konfiguration öffnen​

Schritt 2 — Aufbau der Seite​

Schritt 3 — Dateinamensmuster​

Schritt 4 — Dateileser-Parameter​

Schritt 5 — Spaltenzuordnungen​

Schritt 6 — Reiter „Rohes JSON" für fortgeschrittene Felder​

Schritt 7 — Testen und speichern​

Zielspalten je Stammdatentyp​

Hilfe und Support​