Skip to main content
Markdown

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 listTypically needed
Customers (ordering party / debtor)Required
ArticlesRequired
Delivery addressesoptional
Invoice addressesoptional
Customer contactsoptional
Customer-specific articlesoptional
Unit conversionoptional, if Workist should convert units
Framework agreementsoptional, only for RFQs and orders
Quotesoptional, only for orders
Orders to be matchedoptional, 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 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).

Who can set up master data​

Users with the Manager, IT or Admin role can use the Master Data Hub (see Users, roles & teams). 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. 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).
  3. Configure the import: Set the file name pattern, delimiter, encoding and column mapping (see Transformer configuration).
  4. Test with a dry run: Check the configuration with a sample file before you save (see Dry run).
  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 (status, rows, error message) and in the data explorer.

Choosing the transfer method​

Master data can be passed to Workist in three ways:

OptionRecommended for
SFTPRegular, file-based exports from the ERP — no own integration needed
APIProgrammatic connection, event-driven updates, large data volumes
Upload in the WorkbenchFirst 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​

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). Workist imports a file immediately when its name matches the file name pattern of a list. The SFTP documentation describes temporary files and further rules.

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 without uploading it again.

Option B: API​

Via the master data API, 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.

Option C: Upload in the 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: 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: 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. 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.