# Stammdaten

Stammdaten bilden die Basis für eine korrekte automatische Verarbeitung. Workist gleicht alle extrahierten Dokumentinformationen gegen Ihre Stammdaten ab.

Sie verwalten Ihre Stammdaten im [Master Data Hub](/docs/master-data/master-data-hub.md): Dort legen Sie Stammdatenlisten an, ordnen sie Kanälen zu, konfigurieren den Import und prüfen die importierten Daten. Wie Sie die erste Lieferung einrichten, beschreibt [Schritt 2 des Implementierungsleitfadens](/docs/implementation-guide/step-2-configure-and-upload-master-data.md).

## Stammdaten-Typen

| Typ | Beschreibung |
|-----|-------------|
| [Kunden & Lieferanten](/docs/master-data/customers.md) | Stammdaten zur Erkennung von Kunden bzw. Lieferanten |
| [Kundenkontakte](/docs/master-data/customer-contacts.md) | Stammdaten zur Erkennung von Ansprechpersonen |
| [Liefer- und Rechnungsempfänger](/docs/master-data/delivery-and-invoice-recipients.md) | Adressen für Lieferung und Rechnung |
| [(Kundenspezifische) Artikel](/docs/master-data/articles.md) | Artikellisten (mindestens eine ist Pflicht) |
| [Einheitenkonvertierung](/docs/master-data/unit-conversion.md) | Umrechnungsquotienten für Einheiten |
| [Rahmenverträge](/docs/master-data/framework-agreements.md) | Stammdaten zur Validierung von Rahmenvertragsnummern |
| [Angebote](/docs/master-data/quotes.md) | Stammdaten zum Abgleich von Bestellungen mit Ihren Angeboten |
| [Abzugleichende Bestellungen](/docs/master-data/orders-to-be-matched.md) | Stammdaten zum Abgleich von Auftragsbestätigungen und Rechnungen mit Ihren Bestellungen |

:::warning
Auch wenn Kundendaten in vielen Systemen als eine Art von Adressen behandelt werden, gilt in Workist für Kunden ein eigenes Format!
:::

## Welcher Dokumenttyp welche Liste nutzt {#listen-pro-dokumenttyp}

Ein Kanal verweist in seiner Konfiguration pro Feld auf eine Stammdatenliste. Dieselbe Liste kann in mehreren Kanälen verwendet werden. Liefer- und Rechnungsadressen sowie allgemeine und kundenspezifische Artikel haben jeweils dieselbe Struktur; welche Rolle eine Liste spielt, legt erst das Feld im Kanal fest. Die Zuordnung nehmen Sie im [Master Data Hub](/docs/master-data/master-data-hub.md#kanaele-zuordnen) vor.

| Stammdatenliste | Feld im Kanal | Anfragen | Bestellungen | Auftragsbestätigungen | Rechnungen | Lieferscheine | Leistungsverzeichnisse |
| --- | --- | --- | --- | --- | --- | --- | --- |
| [Kunden](/docs/master-data/customers.md) | Client-Lookup-ID | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| [Empfänger (Kundenliste)](/docs/master-data/customers.md) | Empfänger-Lookup-ID |  |  | ✓ |  | ✓ |  |
| [Kundenkontakte](/docs/master-data/customer-contacts.md) | Kontakt-Lookup-ID | ✓ | ✓ |  | ✓ |  | ✓ |
| [Interne Kontakte (Kontaktliste)](/docs/master-data/customer-contacts.md) | – | ✓ | ✓ |  |  |  |  |
| [Rahmenverträge](/docs/master-data/framework-agreements.md) | ID der Rahmenvertragsuche | ✓ | ✓ |  |  |  |  |
| [Rechnungsadressen](/docs/master-data/delivery-and-invoice-recipients.md) | Rechnungsadressen-Lookup-ID | ✓ | ✓ |  | ✓ |  | ✓ |
| [Lieferadressen](/docs/master-data/delivery-and-invoice-recipients.md) | Lieferadressen-Lookup-ID | ✓ | ✓ | ✓ |  | ✓ | ✓ |
| [Artikel (allgemeine Liste)](/docs/master-data/articles.md) | Artikel-Lookup-ID | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| [Kundenspezifische Artikel](/docs/master-data/articles.md) | Debitorenartikel-Lookup-ID | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| [Einheitenkonvertierung](/docs/master-data/unit-conversion.md) | Umrechnungsfaktor-Lookup-ID | ✓ | ✓ |  |  | ✓ |  |
| [Abzugleichende Bestellungen](/docs/master-data/orders-to-be-matched.md) | Bestellabgleich-Lookup-ID |  |  | ✓ | ✓ |  |  |
| [Angebote](/docs/master-data/quotes.md) | Angebotsabgleich-Lookup-ID |  | ✓ |  |  |  |  |

Daneben gibt es Felder für gelernte Zuordnungen (Mappings). Diese Listen füllt Workist selbst, siehe [Gelernte Daten](/docs/master-data/master-data-hub.md#gelernte-daten).

## Dateiformat {#dateiformat}

Workist importiert CSV-Dateien. Per SFTP gelieferte Dateien dürfen auch Excel-Dateien (`.xls`, `.xlsx`) sein. Die erste Zeile enthält die Spaltennamen.

Trennzeichen und Codierung legen Sie in der [Importkonfiguration](/docs/master-data/transformer-configuration.md) der Liste fest. Ohne Angabe liest Workist die Datei kommagetrennt und als UTF-8. Beim Import erkennt Workist das Trennzeichen nicht automatisch; der [Probelauf](/docs/master-data/master-data-hub.md#probelauf) schlägt aber passende Werte vor.

Vorschlag von Workist:

| Parameter | Wert |
|-----------|------|
| Trennzeichen | `;` oder `,` |
| Escape-Zeichen | `\` |
| Anführungszeichen | `"` |
| Codierung | UTF-8 |

## Wie Workist Werte beim Import vereinheitlicht {#werte-vereinheitlichen}

- **Leerzeichen und Zeilenumbrüche:** Leerzeichen am Anfang und Ende von Werten und Spaltennamen entfernt Workist. Zeilenumbrüche innerhalb einer Zelle ersetzt es durch Leerzeichen.
- **Doppelte Zeilen:** Identische Zeilen importiert Workist nur einmal.
- **Zahlen** (Preise, Mengen): Komma und Punkt sind als Dezimaltrennzeichen erlaubt. Enthält ein Wert beides, gilt das zuletzt stehende Zeichen als Dezimaltrennzeichen: `1.234,56` und `1,234.56` ergeben beide 1234,56. Ein einzelnes Trennzeichen liest Workist immer als Dezimaltrennzeichen: `1.000` ergibt 1. Ausnahme: Der `conversion_quotient` der [Einheitenkonvertierung](/docs/master-data/unit-conversion.md) braucht einen Punkt als Dezimaltrennzeichen.
- **Datumsangaben:** `JJJJ-MM-TT` (z. B. `2024-12-31`) oder mit dem Tag zuerst (z. B. `31.12.2024`). Datumsangaben, die Workist nicht lesen kann, bleiben leer.
- **Länder** (`country`): Ländernamen und Ländercodes wandelt Workist in den zweistelligen ISO-Code um (z. B. `Deutschland` → `DE`). Nicht erkannte Werte bleiben leer.
- **Domains** (`domain`): Workist schreibt Domains klein und verwirft Freemail-Domains wie `gmail.com`.
- **Einheitenlisten** (`order_units`, `sales_units`): als Liste in einer Zelle, z. B. `["KAR","ST"]` oder `['KAR','ST']`. Ein einzelner Wert wird zu einer Liste mit einem Eintrag; `KAR,ST` ohne eckige Klammern ist eine einzige Einheit. Eine leere Zelle wird als `["ST"]` importiert.
- **`partition_id`:** Eine leere `partition_id` speichert Workist als `main`, siehe nächster Abschnitt.

## Zuordnung zu Kunden: `partition_id` {#partition-id}

Viele Listen haben eine Spalte `partition_id`. Sie enthält die `client_id1` des Kunden (bzw. Geschäftspartners), zu dem eine Zeile gehört. Workist sucht dann nur unter den Zeilen des erkannten Kunden, was die Erkennung deutlich verbessert.

- **Leere `partition_id`:** Workist speichert die Zeile mit der Partition `main`. Kontakte, Adressen, Rahmenverträge, Angebote und Bestellungen mit `main` bietet Workist bei jedem Kunden an, zusätzlich zu den Zeilen des erkannten Kunden.
- **Artikel:** Hier gibt es keinen Rückfall auf `main`. Zeilen mit einer `partition_id` gelten nur für diesen Kunden. Die allgemeine Artikelliste pflegen Sie ohne `partition_id`.
- **Einheitenkonvertierung:** Die `partition_id` wirkt nur, wenn im Kanal die partitionsspezifische Einheitenkonversion aktiv ist. Findet Workist für den Kunden keine Umrechnung, verwendet es die Umrechnungen ohne `partition_id`.
- **Keine Prüfung:** Workist prüft beim Import nicht, ob es zur `partition_id` einen Kunden gibt.

## Wie ein Import Ihre Daten ersetzt {#importverhalten}

- **Vollimport (Standard):** Jeder erfolgreiche Import ersetzt den gesamten Inhalt der Liste. Zeilen, die in der neuen Datei fehlen, entfernt Workist. Die neue Version ist sofort aktiv; einen Entwurfs- oder Freigabemodus gibt es nicht.
- **Delta-Import (auf Anfrage):** Auf Wunsch richtet Workist für eine Liste Delta-Importe ein. Ihre Datei enthält dann nur geänderte Zeilen und eine Statusspalte: Zeilen mit dem Status `A` legt Workist an oder aktualisiert sie, Zeilen mit einem anderen Status (z. B. `X`) löscht es, und Zeilen, die nicht in der Datei stehen, bleiben unverändert. Welche Spalten eine Zeile eindeutig kennzeichnen und wie die Statusspalte heißt, legt Workist bei der Einrichtung mit Ihnen fest. Fehlt die Statusspalte in einer Datei oder ist sie leer, behandelt Workist die Datei als Vollimport.
- **Leere Datei:** Enthält eine Datei nach dem Einlesen keine Datenzeilen, bricht Workist den Import ab und behält die bisherigen Daten.
- **Unveränderte Datei:** Haben sich Datei und Importkonfiguration seit dem letzten erfolgreichen Import nicht geändert, übernimmt Workist dessen Ergebnis, ohne die Datei erneut zu verarbeiten.
- **Neuere Lieferung:** Kommt für eine Liste eine neue Datei an, während ein älterer Import noch wartet, bricht Workist den älteren Import ab und importiert die neue Datei.
- **Höchstens etwa 12 Importe pro Stunde:** Pro Liste startet Workist höchstens etwa 12 Importe pro Stunde. Darüber hinaus per SFTP gelieferte Dateien überspringt Workist; über die API und beim Import aus dem SFTP-Verzeichnis im Master Data Hub erhalten Sie eine Fehlermeldung.

## Datenmodell

Die Listen sind über Nummern miteinander verknüpft. Es sind lose Verweise: Workist prüft beim Import nicht, ob eine referenzierte Nummer existiert. `client_id1` und `article_id1` müssen nicht eindeutig sein; ein Artikel kann z. B. pro Kunde oder pro Vertriebsorganisation mehrfach vorkommen. Liefer- und Rechnungsadressen (`DeliveryAddress`, `InvoiceAddress`) haben dieselbe Struktur, ebenso allgemeine und kundenspezifische Artikel (`Article`, `ClientArticle`). Die Spalte `extra_data` ist der Übersicht halber nicht dargestellt.

```mermaid
classDiagram
class Client{
    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
}
class Contact{
    contact_id
    first_name
    last_name
    phone
    mobile_phone
    email
    partition_id
}
class DeliveryAddress{
    partition_id
    address_id1
    address_id2
    address_id3
    name
    address1
    street_name
    street_number
    address2
    zip_code
    city
    country_subdivision
    country
    po_box
    misc
    contact_person
    phone
}
class InvoiceAddress{
    partition_id
    address_id1
    address_id2
    address_id3
    name
    address1
    street_name
    street_number
    address2
    zip_code
    city
    country_subdivision
    country
    po_box
    misc
    contact_person
    phone
}
class FrameworkContract{
    partition_id
    client_id
    client_name
    contract_id1
    contract_id2
    contract_name
}
class Article{
    partition_id
    article_id1
    article_id2
    article_id3
    description
    article_status
    gross_price
    order_units
    sales_units
    sales_organisation
    variants
}
class ClientArticle{
    partition_id
    article_id1
    article_id2
    article_id3
    description
    article_status
    gross_price
    order_units
    sales_units
    sales_organisation
    variants
}
class ConversionFactor{
    partition_id
    article_id
    source_unit
    target_unit
    conversion_quotient
}
class Order{
    partition_id
    order_number
    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
}
class Offer{
    partition_id
    offer_number
    valid_from
    valid_until
    position_number
    article_id1
    article_id2
    article_id3
    article_description
    quantity
    unit
}

Client "0..1" -- "*" Contact : partition_id
Client "0..1" -- "*" DeliveryAddress : partition_id
Client "0..1" -- "*" InvoiceAddress : partition_id
Client "0..1" -- "*" FrameworkContract : partition_id
Client "1" -- "*" ClientArticle : partition_id
ClientArticle "*" --> "1" Article : article_id1
Client "0..1" -- "*" ConversionFactor : partition_id
ConversionFactor "*" --> "1" Article : article_id
Client "0..1" -- "*" Order : partition_id
Order "*" --> "0..1" Article : article_id1
Order "*" --> "0..1" DeliveryAddress : delivery_address
Order "*" --> "0..1" Client : receiver_number
Client "0..1" -- "*" Offer : partition_id
Offer "*" --> "0..1" Article : article_id1
```