# Schritt 2: Stammdaten konfigurieren und hochladen Damit Workist eingehende Dokumente korrekt auflösen kann (z. B. Artikelnummern, Kunden, Lieferadressen), benötigt das System eine aktuelle Kopie Ihrer Stammdaten. Dieser Schritt beschreibt, **welche Daten zu liefern sind**, **wie Sie den Import im Master Data Hub einrichten** und **auf welchem Weg** Sie die Daten übertragen. ## Welche Stammdaten werden benötigt? Welche Stammdatenlisten nötig sind, hängt von Ihrem Anwendungsfall ab. Für nahezu jede Konfiguration brauchen Sie **Kunden** und **Artikel**. | Stammdatenliste | Typischer Bedarf | | --- | --- | | [Kunden (Auftraggeber / Debitor)](/docs/master-data/customers.md) | Pflicht | | [Artikel](/docs/master-data/articles.md) | Pflicht | | [Lieferadressen](/docs/master-data/delivery-and-invoice-recipients.md) | optional | | [Rechnungsadressen](/docs/master-data/delivery-and-invoice-recipients.md) | optional | | [Kundenkontakte](/docs/master-data/customer-contacts.md) | optional | | [Kundenspezifische Artikel](/docs/master-data/articles.md) | optional | | [Einheitenkonvertierung](/docs/master-data/unit-conversion.md) | optional, wenn Workist Einheiten umrechnen soll | | [Rahmenverträge](/docs/master-data/framework-agreements.md) | optional, nur für Anfragen und Bestellungen | | [Angebote](/docs/master-data/quotes.md) | optional, nur für Bestellungen | | [Abzugleichende Bestellungen](/docs/master-data/orders-to-be-matched.md) | optional, für Auftragsbestätigungen und Rechnungen | Dazu kommen je nach Dokumenttyp eine Empfängerliste (Format wie Kunden) und eine Liste interner Kontakte (Format wie Kundenkontakte). Welcher Dokumenttyp welche Liste nutzt, zeigt die Tabelle unter [Welcher Dokumenttyp welche Liste nutzt](/docs/master-data.md#listen-pro-dokumenttyp). Bereiten Sie pro Liste einen aktuellen Export aus Ihrem ERP-System vor — idealerweise als **CSV (UTF-8, `;` oder `,` als Trennzeichen)**. Excel-Dateien (`.xls`, `.xlsx`) können Sie per SFTP liefern. :::tip Beginnen Sie mit einem **vollständigen** Stammdaten-Export, nicht mit einem Delta. Jeder Import ersetzt die gesamte Liste — Zeilen, die nicht in der neuesten Datei enthalten sind, werden aus dem aktiven Datensatz entfernt. Delta-Importe richtet Workist auf Anfrage ein (siehe [Wie ein Import Ihre Daten ersetzt](/docs/master-data.md#importverhalten)). ::: ## Wer Stammdaten einrichten kann Den [Master Data Hub](/docs/master-data/master-data-hub.md) nutzen Benutzer mit der Rolle **Manager**, **IT** oder **Admin** (siehe [Benutzer, Rollen & Teams](/docs/administration/users-and-roles.md)). Benutzer mit der Rolle **IT** erhalten außerdem eine E-Mail, wenn ein Import mit einem Fehler fehlschlägt, den Sie selbst beheben können. --- ## Ablauf im Überblick 1. **Liste anlegen:** Legen Sie im [Master Data Hub](/docs/master-data/master-data-hub.md#liste-anlegen) eine Liste pro Stammdatenliste an. Beim Anlegen eines Kanals legt Workist für die wichtigsten Felder bereits leere Listen an; prüfen Sie diese zuerst. 2. **Kanälen zuordnen:** Ordnen Sie jede Liste den Kanälen und Feldern zu, die sie nutzen sollen (siehe [Kanälen zuordnen](/docs/master-data/master-data-hub.md#kanaele-zuordnen)). 3. **Import konfigurieren:** Legen Sie Dateinamensmuster, Trennzeichen, Codierung und Spaltenzuordnung fest (siehe [Transformer-Konfiguration](/docs/master-data/transformer-configuration.md)). 4. **Mit einem Probelauf testen:** Prüfen Sie die Konfiguration mit einer Beispieldatei, bevor Sie speichern (siehe [Probelauf](/docs/master-data/master-data-hub.md#probelauf)). 5. **Daten liefern:** per SFTP, über die API oder als Upload in der Workbench (siehe unten). 6. **Ergebnis prüfen:** in der [Importhistorie](/docs/master-data/master-data-hub.md#importhistorie) (Status, Zeilen, Fehlermeldung) und im [Datenexplorer](/docs/master-data/master-data-hub.md#datenexplorer). --- ## Übertragungsweg wählen Stammdaten lassen sich auf drei Wegen an Workist übergeben: | Option | Empfohlen für | | --- | --- | | **[SFTP](#option-a-sftp)** | Regelmäßige, datei-basierte Exporte aus dem ERP — keine eigene Integration nötig | | **[API](#option-b-api)** | Programmatische Anbindung, ereignisgesteuertes Aktualisieren, große Datenmengen | | **[Upload in der Workbench](#option-c-workbench)** | Erster Test und gelegentliche manuelle Aktualisierungen | Alle Wege laufen durch dieselbe Importkonfiguration der Liste und erzeugen denselben aktiven Datensatz. --- ## Option A: SFTP {#option-a-sftp} Beim SFTP-Import legt Ihr ERP-System die Stammdaten-Dateien in regelmäßigen Abständen im Verzeichnis `/export` des Workist-SFTP-Servers ab (siehe [Schritt 1](/docs/implementation-guide/step-1-establish-connection.md)). Workist importiert eine Datei sofort, wenn ihr Name zum Dateinamensmuster einer Liste passt. Temporäre Dateien und weitere Regeln beschreibt die [SFTP-Dokumentation](/docs/data-exchange/sftp.md#stammdaten). :::info Wichtig Ohne passendes Dateinamensmuster wird eine eingehende Datei zwar im SFTP-Verzeichnis abgelegt, aber **nicht importiert**. Stellen Sie die Importkonfiguration daher fertig, bevor Sie produktive Lieferungen starten. ::: ### Ablauf 1. Stammdaten-Datei pro Liste aus dem ERP exportieren. 2. Importkonfiguration der Liste im Master Data Hub einrichten (Dateinamensmuster, Trennzeichen/Codierung, Spaltenzuordnung) und mit einem Probelauf testen. 3. Datei in das SFTP-Verzeichnis `/export` hochladen — Workist erkennt sie automatisch und startet den Import. 4. Ergebnis in der Importhistorie der Liste prüfen. Nach einer Änderung der Importkonfiguration importieren Sie die zuletzt gelieferte Datei mit dem [Import aus dem SFTP-Verzeichnis](/docs/master-data/master-data-hub.md#import-aus-sftp) erneut, ohne sie noch einmal hochzuladen. --- ## Option B: API {#option-b-api} Über die [Stammdaten-API](/docs/api-documentation/master-data-api.md) lassen sich Stammdaten auf drei Arten übertragen: - **Als CSV-Datei** (höchstens 10 MB). Die API nimmt nur CSV-Dateien an; Excel-Dateien liefern Sie per SFTP. - **Als Link** zu einer öffentlich erreichbaren CSV-Datei. - **Als Liste von Objekten im JSON-Format** (höchstens 10.000 Zeilen pro Anfrage), für größere Mengen in mehreren Blöcken. :::note Alle Varianten durchlaufen die Importkonfiguration der Liste. JSON-Daten wandelt Workist vorher in eine kommagetrennte CSV-Datei (UTF-8) um, deren Spalten die Schlüssel Ihrer Objekte sind. Verwenden Sie bei JSON-Lieferungen deshalb die Workist-Spaltennamen als Schlüssel und lassen Sie in der Importkonfiguration Trennzeichen und Spaltenzuordnung leer. Ohne Importkonfiguration liest Workist jede Datei kommagetrennt und mit den Workist-Spaltennamen. ::: Für API-Importe brauchen Sie die ID der Liste aus dem Master Data Hub. Authentifizierung, Endpunkte, Datenmodelle und Hinweise zu Massen-Importen finden Sie unter [Benutzung der Stammdaten-API](/docs/api-documentation/master-data-api.md). --- ## Option C: Upload in der Workbench {#option-c-workbench} Für den ersten Test — bevor SFTP-Lieferungen oder die API-Integration produktiv laufen — laden Sie Stammdaten direkt im Master Data Hub hoch. So testen Sie eine neue Importkonfiguration, ohne auf den nächsten ERP-Export warten zu müssen. 1. Öffnen Sie den [Master Data Hub](/docs/master-data/master-data-hub.md): unten in der linken Navigationsleiste **Einstellungen** und dann den Eintrag für die Stammdaten. 2. Öffnen Sie die gewünschte Liste und wechseln Sie auf den Reiter für die Importe. 3. Ziehen Sie eine **CSV-Datei** in die Karte zum Hochladen und klicken Sie auf die Schaltfläche zum Importieren. 4. Prüfen Sie das Ergebnis in der Importhistorie auf demselben Reiter. ### Wichtige Hinweise - **Nur CSV.** Der Upload in der Workbench nimmt ausschließlich `.csv`-Dateien an. Excel-Dateien liefern Sie per SFTP. - **Dieselbe Importkonfiguration.** Trennzeichen, Codierung und Spaltenzuordnung ergeben sich aus der Konfiguration der Liste. Wenn die Konfiguration `;` als Trennzeichen erwartet, muss Ihre CSV-Datei dieses Trennzeichen verwenden. - **Erst testen, dann importieren.** Ein erfolgreicher Import ersetzt die bisher aktive Version **unmittelbar** — es gibt keinen Entwurfs- oder Freigabemodus. Testen Sie Ihre Datei deshalb vorher mit einem [Probelauf](/docs/master-data/master-data-hub.md#probelauf): Er wandelt die Datei um, ohne etwas zu importieren. - **Bestätigung ≠ Importerfolg.** Die grüne Bestätigung im Browser bedeutet lediglich, dass die Datei angenommen wurde. Fehler erscheinen erst später in der Importhistorie als fehlgeschlagener Lauf. - **Vollimport löscht Fehlendes.** Zeilen, die in der neuen Datei nicht mehr enthalten sind, werden aus dem aktiven Datensatz entfernt. Laden Sie also keine gekürzte Testdatei in eine Liste, die ein produktiver Kanal nutzt. --- ## Hilfe und Support Wenn ein Stammdaten-Import scheitert oder die Werte nicht wie erwartet im Workist-Schema landen, prüfen Sie zuerst die [Fehlermeldung in der Importhistorie](/docs/master-data/master-data-hub.md#fehlermeldungen). Wenden Sie sich sonst 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** in der Importhistorie), - die **Eingabedatei** des Imports (in der Importhistorie verlinkt), - die **Fehlermeldung** des Imports bzw. das Ergebnis eines Probelaufs.