# Master Data

Master data forms the basis for correct automated processing. Workist matches all extracted document information against your master data.

You manage your master data in the [Master Data Hub](/en/docs/master-data/master-data-hub.md): there you create master data lists, assign them to channels, configure the import and check the imported data. [Step 2 of the implementation guide](/en/docs/implementation-guide/step-2-configure-and-upload-master-data.md) describes how to set up the first delivery.

## Master Data Types

| Type | Description |
|------|-------------|
| [Customers & Suppliers](/en/docs/master-data/customers.md) | Master data for recognising customers or suppliers |
| [Customer Contacts](/en/docs/master-data/customer-contacts.md) | Master data for recognising contact persons |
| [Delivery and Invoice Recipients](/en/docs/master-data/delivery-and-invoice-recipients.md) | Addresses for delivery and invoicing |
| [(Customer-specific) Articles](/en/docs/master-data/articles.md) | Article lists (at least one is required) |
| [Unit Conversion](/en/docs/master-data/unit-conversion.md) | Conversion quotients for units |
| [Framework Agreements](/en/docs/master-data/framework-agreements.md) | Master data for validating framework agreement numbers |
| [Quotes](/en/docs/master-data/quotes.md) | Master data for matching orders against your quotes |
| [Orders to Be Matched](/en/docs/master-data/orders-to-be-matched.md) | Master data for matching order confirmations and invoices against your orders |

:::warning
Even though customer data is treated as a type of address in many systems, Workist uses its own format for customers!
:::

## Which Document Type Uses Which List {#listen-pro-dokumenttyp}

In its configuration, a channel points to one master data list per field. The same list can be used in several channels. Delivery and invoice addresses have the same structure, and so do general and customer-specific articles; the channel field determines the role a list plays. You make the assignment in the [Master Data Hub](/en/docs/master-data/master-data-hub.md#kanaele-zuordnen).

| Master data list | Channel field | RFQs | Orders | Order confirmations | Invoices | Delivery notes | Lists of services |
| --- | --- | --- | --- | --- | --- | --- | --- |
| [Customers](/en/docs/master-data/customers.md) | Client Lookup ID | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| [Receivers (customer list)](/en/docs/master-data/customers.md) | Receiver Lookup ID |  |  | ✓ |  | ✓ |  |
| [Customer contacts](/en/docs/master-data/customer-contacts.md) | Contact Lookup ID | ✓ | ✓ |  | ✓ |  | ✓ |
| [Internal contacts (contact list)](/en/docs/master-data/customer-contacts.md) | Internal Contact Lookup ID | ✓ | ✓ |  |  |  |  |
| [Framework agreements](/en/docs/master-data/framework-agreements.md) | Framework Contract Lookup ID | ✓ | ✓ |  |  |  |  |
| [Invoice addresses](/en/docs/master-data/delivery-and-invoice-recipients.md) | Invoice Address Lookup ID | ✓ | ✓ |  | ✓ |  | ✓ |
| [Delivery addresses](/en/docs/master-data/delivery-and-invoice-recipients.md) | Delivery Address Lookup ID | ✓ | ✓ | ✓ |  | ✓ | ✓ |
| [Articles (general list)](/en/docs/master-data/articles.md) | Article Lookup ID | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| [Customer-specific articles](/en/docs/master-data/articles.md) | Debtor Article Lookup ID | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| [Unit conversion](/en/docs/master-data/unit-conversion.md) | Conversion Factor Lookup ID | ✓ | ✓ |  |  | ✓ |  |
| [Orders to be matched](/en/docs/master-data/orders-to-be-matched.md) | Order Matching Lookup ID |  |  | ✓ | ✓ |  |  |
| [Quotes](/en/docs/master-data/quotes.md) | Offer Matching Lookup ID |  | ✓ |  |  |  |  |

There are also fields for learned assignments (mappings). Workist fills these lists itself, see [Learned data](/en/docs/master-data/master-data-hub.md#gelernte-daten).

## File Format {#dateiformat}

Workist imports CSV files. Files delivered via SFTP can also be Excel files (`.xls`, `.xlsx`). The first row contains the column names.

You set the delimiter and encoding in the list's [import configuration](/en/docs/master-data/transformer-configuration.md). Without a setting, Workist reads the file comma-separated and as UTF-8. Workist does not detect the delimiter automatically during the import; the [dry run](/en/docs/master-data/master-data-hub.md#probelauf) suggests suitable values, though.

Workist recommendation:

| Parameter | Value |
|-----------|-------|
| Delimiter | `;` or `,` |
| Escape character | `\` |
| Quote character | `"` |
| Encoding | UTF-8 |

## How Workist Normalises Values During the Import {#werte-vereinheitlichen}

- **Spaces and line breaks:** Workist removes leading and trailing spaces from values and column names. It replaces line breaks within a cell with spaces.
- **Duplicate rows:** Workist imports identical rows only once.
- **Numbers** (prices, quantities): both comma and point are allowed as decimal separator. If a value contains both, the last one is the decimal separator: `1.234,56` and `1,234.56` both result in 1234.56. Workist always reads a single separator as the decimal separator: `1.000` results in 1. Exception: the `conversion_quotient` of the [unit conversion](/en/docs/master-data/unit-conversion.md) requires a point as decimal separator.
- **Dates:** `YYYY-MM-DD` (e.g. `2024-12-31`) or with the day first (e.g. `31.12.2024`). Dates that Workist cannot read are left empty.
- **Countries** (`country`): Workist converts country names and country codes to the two-letter ISO code (e.g. `Germany` → `DE`). Values it does not recognise are left empty.
- **Domains** (`domain`): Workist lowercases domains and drops free-mail domains such as `gmail.com`.
- **Unit lists** (`order_units`, `sales_units`): as a list in one cell, e.g. `["BOX","PCE"]` or `['BOX','PCE']`. A single value becomes a list with one entry; `BOX,PCE` without square brackets is a single unit. An empty cell is imported as `["ST"]`.
- **`partition_id`:** Workist stores an empty `partition_id` as `main`, see the next section.

## Assignment to Customers: `partition_id` {#partition-id}

Many lists have a `partition_id` column. It contains the `client_id1` of the customer (or business partner) a row belongs to. Workist then only searches the rows of the recognised customer, which significantly improves recognition.

- **Empty `partition_id`:** Workist stores the row with the partition `main`. Workist offers contacts, addresses, framework agreements, quotes and orders with `main` for every customer, in addition to the rows of the recognised customer.
- **Articles:** There is no fallback to `main` here. Rows with a `partition_id` only apply to this customer. Maintain the general article list without a `partition_id`.
- **Unit conversion:** The `partition_id` only takes effect if partition-specific unit conversion is enabled in the channel. If Workist finds no conversion for the customer, it uses the conversions without a `partition_id`.
- **No check:** During the import, Workist does not check whether a customer exists for the `partition_id`.

## How an Import Replaces Your Data {#importverhalten}

- **Full import (default):** Every successful import replaces the entire content of the list. Workist removes rows that are missing from the new file. The new version is active immediately; there is no draft or approval mode.
- **Delta import (on request):** On request, Workist sets up delta imports for a list. Your file then only contains changed rows and a status column: Workist creates or updates rows with the status `A`, deletes rows with any other status (e.g. `X`), and leaves rows that are not in the file unchanged. Workist agrees with you during setup which columns uniquely identify a row and what the status column is called. If a file has no status column or the column is empty, Workist treats the file as a full import.
- **Empty file:** If a file contains no data rows after reading, Workist cancels the import and keeps the previous data.
- **Unchanged file:** If neither the file nor the import configuration has changed since the last successful import, Workist takes over its result without processing the file again.
- **Newer delivery:** If a new file arrives for a list while an older import is still waiting, Workist cancels the older import and imports the new file.
- **At most about 12 imports per hour:** Per list, Workist starts at most about 12 imports per hour. Workist skips files delivered via SFTP beyond that; via the API and when importing from the SFTP folder in the Master Data Hub, you get an error message.

## Data Model

The lists are linked to each other by numbers. These are loose references: during the import, Workist does not check whether a referenced number exists. `client_id1` and `article_id1` do not have to be unique; an article can, for example, appear several times per customer or per sales organisation. Delivery and invoice addresses (`DeliveryAddress`, `InvoiceAddress`) have the same structure, and so do general and customer-specific articles (`Article`, `ClientArticle`). The `extra_data` column is not shown, for clarity.

```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
```