Zum Hauptinhalt springen

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, auf welchem Weg sie übertragen werden können und wie Sie eine erste Datei zum Testen einspielen.

Welche Stammdaten werden benötigt?​

Workist unterstützt bis zu acht Stammdaten-Gruppen. Welche davon zwingend nötig sind, hängt von Ihrem Anwendungsfall ab — eine Pflichtangabe für nahezu jede Konfiguration sind Kunden und Artikel.

GruppeTypischer Pflichtcharakter
Kunden (Auftraggeber / Debitor)Pflicht
ArtikelPflicht
Lieferadressen (Warenempfänger)optional
Rechnungsadressenoptional
Ansprechpartneroptional
Kundenspezifische Artikeloptional
Rahmenverträgeoptional
Bestell- bzw. Angebotsabgleichoptional

Die genauen Felder pro Gruppe (Pflicht- und optionale Spalten) finden Sie im Bereich Stammdaten. Bereiten Sie pro Gruppe je einen aktuellen Export aus Ihrem ERP-System vor — idealerweise als CSV (UTF-8, ; oder , als Trennzeichen) oder Excel-Datei.

tipp

Beginnen Sie mit einem vollständigen Stammdaten-Export, nicht mit einem Delta. Im Standard läuft der Import im Batch-Modus — Zeilen, die nicht in der neuesten Datei enthalten sind, werden aus dem aktiven Datensatz entfernt.

Übertragungsweg wählen​

Stammdaten lassen sich auf zwei Wegen an Workist übergeben — Sie können sich frei entscheiden oder beide Optionen kombinieren:

OptionEmpfohlen für
SFTPRegelmäßige, datei-basierte Exporte aus dem ERP — keine eigene Integration nötig
APIProgrammatische Anbindung, ereignisgesteuertes Aktualisieren, große Datenmengen

Beide Wege laufen anschließend durch dieselbe Verarbeitungspipeline und erzeugen denselben aktiven Datensatz.

Option A: SFTP​

Beim SFTP-Import legt Ihr ERP-System die Stammdaten-Dateien in regelmäßigen Abständen im Workist-SFTP-Verzeichnis ab (siehe Schritt 1). Workist erkennt eingehende Dateien automatisch und ordnet sie der passenden Stammdaten-Gruppe zu — vorausgesetzt, für jede Gruppe ist eine Transformer-Konfiguration hinterlegt.

Transformer-Konfiguration​

Die Transformer-Konfiguration ist das Bindeglied zwischen Ihrer Datei und dem Workist-Zielschema. Sie legt drei Dinge fest:

  1. Dateinamensmuster — welche Datei (z. B. customer_article_list.csv oder articles_*.csv) zu welcher Stammdaten-Gruppe gehört.
  2. Dateileser-Parameter — Codierung, Trennzeichen, Anführungszeichen, Escape-Zeichen.
  3. Spaltenzuordnungen — wie die Spalten Ihrer Datei auf die Pflicht- und optionalen Spalten des Workist-Schemas abgebildet werden.

Jede Stammdaten-Gruppe (Artikel, Kunden, Adressen, …) besitzt eine eigene Transformer-Konfiguration. Diese wird in der Workbench im jeweiligen Kanal unter Stammdatenimporte über das Zahnrad-Symbol gepflegt — die vollständige Anleitung inklusive aller verfügbaren Parameter und JSON-Felder finden Sie unter Transformer-Konfiguration.

Wichtig

Ohne hinterlegte Transformer-Konfiguration wird eine eingehende Datei zwar im SFTP-Verzeichnis abgelegt, aber nicht importiert. Stellen Sie die Konfiguration daher fertig, bevor Sie produktive Lieferungen starten.

Ablauf​

  1. Stammdaten-Datei pro Gruppe aus dem ERP exportieren.
  2. Transformer-Konfiguration für die jeweilige Gruppe in der Workbench anlegen (Dateinamensmuster, Trennzeichen/Encoding, Spaltenzuordnung).
  3. Datei in das SFTP-Verzeichnis hochladen — Workist erkennt sie automatisch und löst den Import aus.
  4. Ergebnis prüfen unter Stammdatenimporte im Kanal (Status, Zeilenanzahl, Fehler).

Option B: API​

Über die Stammdaten-API lassen sich Stammdaten auf drei Arten übertragen:

  • Als Datei (Multipart-Upload) — z. B. dieselben CSV/XLSX-Dateien, die Sie auch per SFTP liefern würden.
  • Als Link zu einer öffentlich erreichbaren Datei.
  • Als Liste von Objekten im JSON-Format, optional in mehreren Chunks für große Mengen.
hinweis

Bei den datei-basierten API-Varianten (Multipart-Upload, Link) durchläuft die Datei dieselbe Transformer-Konfiguration wie ein SFTP-Import. Auch hier muss die Konfiguration für die jeweilige Gruppe also vorab gepflegt sein — ohne sie scheitert die Verarbeitung. Nur der JSON-Upload umgeht die Transformer-Schicht, da die Daten dort bereits im Workist-Schema vorliegen.

Authentifizierung, Endpunkte, Datenmodelle und Hinweise zu Massen-Importen finden Sie unter Benutzung der Stammdaten-API.

Initialer Test über die Workbench​

Für den ersten Smoke-Test — bevor SFTP-Lieferungen oder API-Integration produktiv laufen — können Stammdaten direkt in der Workbench hochgeladen werden. So lässt sich eine neue Transformer-Konfiguration oder ein angepasstes Spalten-Mapping testen, ohne auf den nächsten ERP-Export warten zu müssen.

Voraussetzungen​

  • Eine Stammdaten-Gruppe (Lookup) ist im Kanal bereits angelegt; das Feld lookupDefinitionId enthält eine gültige UUID. Erst dann ist die Schaltfläche Datei hochladen aktiv.
  • Ihr Benutzer hat Manager-Rechte (Workist-Mitarbeitende, Kunden-Admin oder Power-User). Andere Benutzer sehen zwar die Schaltfläche, der Upload wird aber serverseitig mit 403 abgewiesen.
  • Die Transformer-Konfiguration für die Gruppe ist gespeichert — der manuelle Upload nutzt dieselben Einstellungen (Trennzeichen, Encoding, Spaltenzuordnung).

Ablauf​

  1. Den Kanal in der Workbench öffnen und in der linken Unter-Navigation unter Dokumentenverarbeitung auf Stammdaten klicken. Sie sehen die Karte Stammdaten Lookups mit je einer Zeile pro Lookup-Typ.

    Stammdaten-Tab der Kanal-Konfiguration mit einer Zeile pro Lookup

  2. In der Zeile der gewünschten Gruppe (z. B. Artikel) auf Datei hochladen klicken.

    Schaltfläche „Datei hochladen" hervorgehoben

  3. Es öffnet sich der Dialog Stammdaten aus CSV-Datei importieren mit Drop-Bereich und der Liste der erwarteten Spalten. Über Beispieldatei herunterladen lässt sich bei Bedarf eine Vorlage laden.

    Upload-Dialog mit Drop-Bereich und erwarteten Spalten

  4. Eine CSV-Datei in den Drop-Bereich ziehen und auf Datei importieren klicken.

  5. Das Ergebnis im Bereich Stammdatenimporte prüfen (Status, Zeilenanzahl, ggf. Fehlermeldung).

Wichtige Hinweise​

  • Nur CSV. Der manuelle Upload akzeptiert ausschließlich .csv-Dateien. XLSX wird abgelehnt; nutzen Sie für Excel-Dateien den SFTP- oder API-Weg.
  • Dateileser-Parameter sind nicht überschreibbar. Trennzeichen, Codierung und Anführungszeichen ergeben sich aus der Transformer-Konfiguration der Gruppe. Wenn die Konfiguration ; als Trennzeichen erwartet, muss Ihre CSV diesem Format entsprechen.
  • Erfolgreicher Upload aktiviert sofort. Ein erfolgreicher Import ersetzt die bisher aktive Version unmittelbar — es gibt keinen Entwurfs- oder Freigabemodus. Verwenden Sie für produktive Kanäle bewusst Testdaten oder einen separaten Kanal.
  • Toast ≠ Importerfolg. Die grüne Bestätigung im Browser bedeutet lediglich, dass die Datei angenommen wurde. Parser- oder Transformer-Fehler erscheinen erst später im Stammdatenimporte-Log als fehlgeschlagener Lauf.
  • Batch-Modus 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 Test-Datei auf einen produktiven Kanal.

Hilfe und Support​

Wenn ein Stammdaten-Import scheitert oder die Werte nicht wie erwartet im Workist-Schema landen, wenden Sie sich an Ihre Ansprechperson bei Workist und halten Sie die folgenden Informationen bereit:

  • den Kanalnamen und die betroffene Stammdaten-Gruppe (z. B. „Artikel"),
  • den Zeitpunkt des fehlgeschlagenen Imports (Spalte Importiert am unter Stammdatenimporte),
  • die Eingabedatei des Imports (in der Tabelle verlinkt),
  • bei eigenen Anpassungen: das aktuelle JSON der Transformer-Konfiguration aus dem Reiter Rohes JSON.