# Master Data Hub

In the Master Data Hub you manage all master data lists of your organisation in one place. You create lists, assign them to channels, configure the import, upload files, search the imported data and check whether imports succeeded.

Users with the **Manager**, **IT** or **Admin** role can use the Master Data Hub (see [Users and roles](/en/docs/administration/users-and-roles.md)). Other users don't see it.

## Opening the Master Data Hub

- Click **Settings** at the bottom of the left navigation bar and select **Master data**.
- From a channel: open the channel menu and select **Manage master data**. You see the **Master data imports** of all lists of the channel. The gear at the end of a row (**Manage lookup**) opens the list in the Master Data Hub in a new tab.
- From the channel configuration: under **Master Data**, a gear next to each field opens the assigned list in the Master Data Hub.

## Overview

The overview has two tabs: **Provided data** (your imported master data lists) and **[Learned data](#gelernte-daten)**.

For each list, the table shows the **Name**, **Type**, **ID**, number of **Entries**, number of **Channels** that use the list, and the time of the **Last update**. You can filter by type and by channel and sort by name or last update. Clicking a name opens the list's detail page.

You need a list's ID when you deliver data via the [master data API](/en/docs/api-documentation/master-data-api.md).

## Creating a List {#liste-anlegen}

1. In the overview, click **Add lookup** at the top right.
2. Select the **Type**: **Articles**, **Customers**, **Customer contacts**, **Address**, **Unit conversions**, **Framework contracts**, **Orders** or **Offers**.
3. Enter a **Name** and click **Create**. Workist opens the detail page of the new list.

You need a separate list for each role in the channel. Delivery and invoice addresses are two lists of the type **Address**; the general and the customer-specific article list are two lists of the type **Articles**. The table under [Which document type uses which list](/en/docs/master-data.md#listen-pro-dokumenttyp) shows which list a document type uses.

:::tip
When a new channel is created, Workist already creates empty lists for the most important fields and assigns them to the channel. Before you create new lists, use the channel filter in the overview to check which lists a channel already has.
:::

## Detail Page of a List

The detail page has up to four tabs:

| Tab | What you do there |
| --- | --- |
| **General** | Change the name; view type, ID, number of entries and last update; [assign channels](#kanaele-zuordnen); [delete the list](#liste-loeschen) |
| **Data** | Search the imported records in the [data explorer](#datenexplorer) |
| **Imports** | View the [import history](#importhistorie), [import from SFTP](#import-aus-sftp), [upload a file](#datei-hochladen) |
| **Configuration** | Edit the [import configuration](/en/docs/master-data/transformer-configuration.md) and test it with a [dry run](#probelauf) |

Lists with learned data only have the first two tabs.

### Assigning Channels {#kanaele-zuordnen}

In the **Used by channels** card on the **General** tab, you see, for each document type, the fields in which this list type can be used, e.g. **Client Lookup ID** or **Article Lookup ID**.

1. Click the field (**Add channel…**) and select a channel. Workist immediately enters the list in the channel configuration.
2. If the field in the channel already points to another list, Workist shows a warning. Click **Replace** to replace the previous list, or **Cancel**.
3. To remove an assignment, remove the channel from the field.

Alternatively, select the list in the respective field of the channel configuration under **Master Data**.

### Renaming a List

Change the **Name** on the **General** tab and click **Save**. The name is for your overview only; channels refer to the list by its ID.

### Deleting a List {#liste-loeschen}

In the **Danger zone** at the end of the **General** tab, **Delete lookup** deletes the list with all its data. This cannot be undone. As long as the list is assigned to a channel, you cannot delete it: remove all assignments first.

## Configuring the Import

On the **Configuration** tab, you define which file Workist reads, how it reads it, and how the columns of your file are mapped to Workist's columns. The configuration applies to all delivery methods: SFTP, API and upload in the Workbench. The step-by-step guide is under [Transformer configuration](/en/docs/master-data/transformer-configuration.md).

Workist marks changes as **Unsaved changes**. Dry runs already use unsaved changes; imports only use them after you save.

### Dry Run {#probelauf}

A dry run tests the current configuration, including unsaved changes. Workist reads and transforms the file as in a real import, but imports and saves nothing.

1. Select the **Input files**:
   - **Latest imported files**: the latest imported file for each file name pattern, like a regular import,
   - **SFTP files**: the newest file in the SFTP folder for each file name pattern, including files that have not been imported yet, or
   - **Upload files**: a file from your computer (CSV or Excel, at most 25 MB in total). The file is not stored.
2. Click **Run dry run**.

Result:

- On success, Workist shows the number of transformed rows and a **Sample of the transformed result** as it would be imported. The dry run processes at most 100 rows; it does not detect errors in later rows.
- On failure, Workist shows the error message. The collapsible **Logs** show the individual processing steps.
- **Detected configuration:** Workist reads the delimiter, encoding and quote character from the file and maps columns whose names exactly match a Workist column. If this differs from your configuration, Workist shows the differences, and **Apply to form** takes them over into the form. File columns without a matching Workist column are added as **Not mapped** rows that you map yourself. Workist removes rows that are not mapped when you save. For lists with a custom import script, the dry run does not detect a configuration.

Only save the configuration once the dry run has succeeded.

## Importing Data

Workist imports a file automatically as soon as it arrives in the SFTP folder or is delivered via the API. On the **Imports** tab, you can also start an import yourself.

### Import from SFTP {#import-aus-sftp}

The **Import from SFTP** card shows, for each file name pattern, the newest matching file in your SFTP folder with name, pattern, size and modification date. **Import** imports these files immediately. For patterns without a file in the SFTP folder, Workist uses the last imported file.

This way you apply a changed configuration without uploading the file again. If no matching file is in the SFTP folder, the button is disabled.

### Uploading a File {#datei-hochladen}

1. Drop a CSV file onto the **Import file** card or click to select one. The card shows the columns that a file for this list type can contain.
2. Click **Import**.

Workist processes the file with the list's import configuration and replaces the previous data after a successful import (see [How an import replaces your data](/en/docs/master-data.md#importverhalten)). The confirmation in the browser only means that the file was accepted; you see the result in the import history. Deliver Excel files via SFTP.

### Import History {#importhistorie}

The **Import history** shows all import runs of the list with status, **Imported at**, **Duration**, **Started via** (Workbench, SFTP, API or Workist Support), **Input file** and **Output file**, each with rows and size. The output file contains the data as Workist imported it after the transformation; use it to check your column mapping. A check mark marks the import whose data is currently in use. **Only show master data in use** hides all other runs.

You see the same table for all lists of a channel under **Manage master data** in the channel.

| Status | Meaning |
| --- | --- |
| **Pending** | The import is waiting to start. |
| **Processing** | Workist is processing the file. With very many new rows, an import stays in this status longer. |
| **Successful** | The data is active. |
| **Failed** | The import failed. If reading or transforming the file fails, the previous data remains active. |
| **Canceled** | A newer import for the same list replaced this one, or the file contained no data rows. The previous data remains active. |

### Error Messages {#fehlermeldungen}

For a failed import, Workist shows an explanation on the status. The question mark next to it (**Show error details**) opens the full error message.

| Error | Cause | What you can do | Notification |
| --- | --- | --- | --- |
| **Unexpected file encoding** | The file does not have the encoding from the import configuration. | Deliver the file in the expected encoding or adjust the encoding in the configuration. | Email to the IT role |
| **Unexpected delimiter** | The file uses a different delimiter than set in the configuration. | Deliver the file with the expected delimiter or adjust the delimiter in the configuration. | Email to the IT role |
| **Unexpected file format** | A column from the column mapping is missing in the file. | Add the column to the file or adjust the column mapping. | Email to the IT role |
| **Unprocessable value** | A value cannot be converted, e.g. text in a price column, or the file is empty. | Correct the value in the row and column named. | Email to the IT role |
| **Unprocessable row** | A row has too many or too few delimiters or incorrect quotes. | Check and correct the row. | Email to the IT role |
| **Unknown input file** | The file does not match any list. | – | Workist |
| **Missing input file** | The list needs several files and one of them is missing. | Deliver the file named. | Workist |
| **Non-standard file format** | The transformed file does not match the Workist format. | – | Workist |
| **Temporary unavailable service** | Workist was temporarily unavailable. | Deliver the file again. | Workist |
| Other errors | e.g. a faulty import configuration | Check the configuration with a [dry run](#probelauf). | Workist |

### Email on a Failed Import

For the errors you can fix yourself (marked "Email to the IT role" in the table), all users with the **IT** role receive an email with the error message and a link to the channel's master data imports. This requires the list to be assigned to at least one channel. The system reports all other errors to Workist.

## Searching the Data {#datenexplorer}

The **Data explorer** on the **Data** tab shows the records of the active version as a table. Use the search fields in the column headers to filter by individual columns. **Load more** at the end of the table loads further records. Workist shows additional information from `extra_data` in a separate **Extra data** column.

## Learned Data {#gelernte-daten}

The **Learned data** tab of the overview lists mappings that Workist learns from your corrections in the assistance, e.g. which customer, contact, article or address belongs to a value on the document. Workist maintains these lists itself; you don't import anything.

The detail page shows the learned entries. In the **Danger zone**, **Reset data** deletes all entries created before a selected date, e.g. after your master data has changed fundamentally. This cannot be undone.

## Master Data Status in the Document

In the document, the master data button at the top of the assistance (**See master data status**) shows the **Master data status**: which state of each list Workist used to process the document (**Imported on**), and whether this is still the **Latest version** or an **Outdated version**. **See details** opens the master data imports.

If newer master data exists, Workist points this out. **Reprocess document** reprocesses the document with the current master data.