# Step 2: Configure and upload master data

So that Workist can resolve incoming documents correctly (e.g. article numbers, customers, delivery addresses), the system needs an up-to-date copy of your master data. This step describes **which data to deliver**, **how to set up the import in the Master Data Hub** and **how** to transfer the data.

## Which master data is needed?

Which master data lists you need depends on your use case. For almost every configuration, you need **customers** and **articles**.

| Master data list | Typically needed |
| --- | --- |
| [Customers (ordering party / debtor)](/en/docs/master-data/customers.md) | Required |
| [Articles](/en/docs/master-data/articles.md) | Required |
| [Delivery addresses](/en/docs/master-data/delivery-and-invoice-recipients.md) | optional |
| [Invoice addresses](/en/docs/master-data/delivery-and-invoice-recipients.md) | optional |
| [Customer contacts](/en/docs/master-data/customer-contacts.md) | optional |
| [Customer-specific articles](/en/docs/master-data/articles.md) | optional |
| [Unit conversion](/en/docs/master-data/unit-conversion.md) | optional, if Workist should convert units |
| [Framework agreements](/en/docs/master-data/framework-agreements.md) | optional, only for RFQs and orders |
| [Quotes](/en/docs/master-data/quotes.md) | optional, only for orders |
| [Orders to be matched](/en/docs/master-data/orders-to-be-matched.md) | optional, for order confirmations and invoices |

Depending on the document type, there is also a receiver list (same format as customers) and a list of internal contacts (same format as customer contacts). The table under [Which document type uses which list](/en/docs/master-data.md#listen-pro-dokumenttyp) shows which document type uses which list.

Prepare a current export from your ERP system for each list — ideally as **CSV (UTF-8, `;` or `,` as delimiter)**. You can deliver Excel files (`.xls`, `.xlsx`) via SFTP.

:::tip
Start with a **complete** master data export, not a delta. Every import replaces the entire list — rows that are not in the newest file are removed from the active data set. Workist sets up delta imports on request (see [How an import replaces your data](/en/docs/master-data.md#importverhalten)).
:::

## Who can set up master data

Users with the **Manager**, **IT** or **Admin** role can use the [Master Data Hub](/en/docs/master-data/master-data-hub.md) (see [Users, roles & teams](/en/docs/administration/users-and-roles.md)). Users with the **IT** role also receive an email when an import fails with an error you can fix yourself.

---

## Overview of the process

1. **Create the list:** Create one list per master data list in the [Master Data Hub](/en/docs/master-data/master-data-hub.md#liste-anlegen). When a channel is created, Workist already creates empty lists for the most important fields; check these first.
2. **Assign channels:** Assign each list to the channels and fields that should use it (see [Assigning channels](/en/docs/master-data/master-data-hub.md#kanaele-zuordnen)).
3. **Configure the import:** Set the file name pattern, delimiter, encoding and column mapping (see [Transformer configuration](/en/docs/master-data/transformer-configuration.md)).
4. **Test with a dry run:** Check the configuration with a sample file before you save (see [Dry run](/en/docs/master-data/master-data-hub.md#probelauf)).
5. **Deliver the data:** via SFTP, via the API or as an upload in the Workbench (see below).
6. **Check the result:** in the [import history](/en/docs/master-data/master-data-hub.md#importhistorie) (status, rows, error message) and in the [data explorer](/en/docs/master-data/master-data-hub.md#datenexplorer).

---

## Choosing the transfer method

Master data can be passed to Workist in three ways:

| Option | Recommended for |
| --- | --- |
| **[SFTP](#option-a-sftp)** | Regular, file-based exports from the ERP — no own integration needed |
| **[API](#option-b-api)** | Programmatic connection, event-driven updates, large data volumes |
| **[Upload in the Workbench](#option-c-workbench)** | First test and occasional manual updates |

All methods run through the same import configuration of the list and produce the same active data set.

---

## Option A: SFTP {#option-a-sftp}

With the SFTP import, your ERP system places the master data files in the `/export` folder of the Workist SFTP server at regular intervals (see [Step 1](/en/docs/implementation-guide/step-1-establish-connection.md)). Workist imports a file immediately when its name matches the file name pattern of a list. The [SFTP documentation](/en/docs/data-exchange/sftp.md#stammdaten) describes temporary files and further rules.

:::info Important
Without a matching file name pattern, an incoming file is stored in the SFTP folder but **not imported**. Therefore, finish the import configuration before you start productive deliveries.
:::

### Process

1. Export one master data file per list from the ERP.
2. Set up the list's import configuration in the Master Data Hub (file name pattern, delimiter/encoding, column mapping) and test it with a dry run.
3. Upload the file to the SFTP folder `/export` — Workist detects it automatically and starts the import.
4. Check the result in the list's import history.

After changing the import configuration, re-import the last delivered file with [Import from SFTP](/en/docs/master-data/master-data-hub.md#import-aus-sftp) without uploading it again.

---

## Option B: API {#option-b-api}

Via the [master data API](/en/docs/api-documentation/master-data-api.md), master data can be transferred in three ways:

- **As a CSV file** (at most 10 MB). The API only accepts CSV files; deliver Excel files via SFTP.
- **As a link** to a publicly accessible CSV file.
- **As a list of objects in JSON format** (at most 10,000 rows per request), for larger volumes in several blocks.

:::note
All variants run through the list's import configuration. Workist first converts JSON data into a comma-separated CSV file (UTF-8) whose columns are the keys of your objects. For JSON deliveries, therefore use the Workist column names as keys and leave the delimiter and column mapping in the import configuration empty. Without an import configuration, Workist reads every file comma-separated and with the Workist column names.
:::

For API imports, you need the list's ID from the Master Data Hub. Authentication, endpoints, data models and notes on bulk imports are described under [Using the master data API](/en/docs/api-documentation/master-data-api.md).

---

## Option C: Upload in the Workbench {#option-c-workbench}

For the first test — before SFTP deliveries or the API integration go live — upload master data directly in the Master Data Hub. This lets you test a new import configuration without waiting for the next ERP export.

1. Open the [Master Data Hub](/en/docs/master-data/master-data-hub.md): **Settings** at the bottom of the left navigation bar, then **Master data**.
2. Open the list and switch to the **Imports** tab.
3. Drop a **CSV file** onto the **Import file** card and click **Import**.
4. Check the result in the **Import history** on the same tab.

### Important notes

- **CSV only.** The upload in the Workbench only accepts `.csv` files. Deliver Excel files via SFTP.
- **Same import configuration.** Delimiter, encoding and column mapping come from the list's configuration. If the configuration expects `;` as delimiter, your CSV file must use this delimiter.
- **Test first, then import.** A successful import replaces the previously active version **immediately** — there is no draft or approval mode. Therefore test your file beforehand with a [dry run](/en/docs/master-data/master-data-hub.md#probelauf): it transforms the file without importing anything.
- **Confirmation ≠ import success.** The green confirmation in the browser only means that the file was accepted. Errors only appear later in the import history as a failed run.
- **A full import deletes what is missing.** Rows that are no longer in the new file are removed from the active data set. So don't upload a shortened test file to a list that a productive channel uses.

---

## Help and support

If a master data import fails or the values do not end up in the Workist schema as expected, first check the [error message in the import history](/en/docs/master-data/master-data-hub.md#fehlermeldungen). Otherwise, contact your point of contact at Workist and have the following information ready:

- the **name of the list** in the Master Data Hub and the **master data type** (e.g. "Articles"),
- the **time** of the failed import (column **Imported at** in the import history),
- the **input file** of the import (linked in the import history),
- the **error message** of the import or the result of a dry run.