Transformer Configuration for Master Data Imports

This guide describes how to view and adjust the Transformer Configuration of a master data import in the Workbench. The Transformer Configuration determines which file is read from the SFTP server (or from a file-based API upload), how it is read (encoding, delimiter, …), and how the columns of your file are mapped to the target schema expected by Workist.

Each lookup definition (articles, customers, customer contacts, addresses, conversion factors, framework contracts, order matching, offer matching) has its own Transformer Configuration.

---

Prerequisites

• A Workbench account with access to the master data imports of the relevant channel.
• An already configured lookup definition with at least one existing master data import. The configuration can only be opened from an existing import row.
• At least one sample file whose column names you know — otherwise you cannot map them to the target schema.

note

The Transformer Configuration controls how the file is read only if no customer-specific transformer script is in place. With customer-specific scripts, the effective fields are usually limited to file name pattern and selected parameters — in that case the column expression is ignored.

---

Step 1 — Open the master data imports

In the Workbench, switch to the channel whose master data you want to configure (e.g. an order or invoice channel) and open the Master Data Imports section from the navigation.

You will see a tabular overview of all previous import runs per lookup type (articles, addresses, customers, …) with status, duration, and references to the incoming and outgoing files.

At the far right of each row you will find a gear icon (Configure import). Click the gear in the row of the lookup type whose configuration you want to change.

No import has run yet? As long as no import run exists for a lookup type, the Master Data Imports table is empty for that type and there is no row with a gear there. In that case, open Channel Configuration → Master Data instead and click the gear next to the "Upload file" button of the relevant lookup type — you will end up in the same configuration dialog.

---

Step 2 — Understand the "Import Configuration" dialog

The Import Configuration dialog opens. It has two tabs:

• Form — guided entry for the most common fields. Inputs are validated against the target schema of the respective lookup type.
• Raw JSON — direct access to the complete Transformer Configuration. Here you can also configure fields that do not appear in the form (e.g. apply_common_functions, query, replace_nan).

The Form tab is divided into three sections:

1. File name pattern — which file(s) on the SFTP server should be read for this import.
2. File reader parameters — how the file is read (delimiter, encoding, …).
3. Column mappings — how the columns of your file are mapped to the columns of the Workist target schema.

---

Step 3 — File name pattern

In the File name pattern section, you define which files in your SFTP export directory count as input for this import.

• You can enter a fixed file name, e.g. customer_article_list.csv.
• Wildcards are allowed, e.g. *.csv or articles_*_full.csv.
• Use + Add pattern to enter multiple patterns.

If multiple patterns are entered, the import is triggered each time one file matching one of the patterns arrives.

tip

Use patterns that are as restrictive as possible. A pattern that is too broad, such as *.csv, may cause non-article files to be mistakenly interpreted as an article list.

---

Step 4 — File reader parameters

In the File reader parameters section, you configure how Workist should read your file. Each row is activated via the plus icon (+) and removed again via the trash icon. Default values apply as long as a parameter is not set.

Parameter	Meaning	Example
Delimiter	Column separator in CSV files. Detected automatically by default.	; , \t
Encoding	Character set of the file. The default is UTF-8.	utf-8, latin-1, cp1252
Quote character	Character used to enclose values in the CSV file.	" or '
Escape character	Character used to escape the quote character within a value.	\

note

For Excel files (.xls, .xlsx), these parameters are ignored — Workist detects the format based on the file extension and reads the table directly.

---

Step 5 — Column mappings

In the Column mappings section, you map the columns of your input file to the columns of the Workist target schema. When you first add mappings, the mandatory columns of the respective lookup type are inserted automatically and marked with a * — they cannot be removed.

Each row consists of two fields:

• Column name — the target name (Workist schema), selected from a list of the allowed columns of the current lookup type.

• Column expression — where the value comes from. Four types of expression are possible here:

  Expression	Meaning
  Artikelnummer	Direct column reference — the value is taken 1:1 from the column of the same name.
  {Bezeichnung1} {Bezeichnung2}	Template expression — placeholders in curly braces are replaced by column values.
  'STK'	String literal — the value is hardcoded (e.g. a constant unit).
  (empty)	Empty column — a new, empty target column is created.
  PASS	Keep if present — the column of the same name is passed through; if it is not there, the mapping is ignored.

Example for an article list:

Column name	Column expression
article_id1 *	Artikelnummer
description *	{Bezeichnung_DE} {Farbe}
partition_id	'main'
gross_price	Listenpreis
order_units	Bestelleinheit

Columns that exist in your input file but are not allowed in the Workist schema are marked with an orange ! — they will be ignored later during the import.

Use + Add column mapping to add further mappings until all columns of the target schema are used. Each optional mapping can be removed again via the trash icon.

---

Step 6 — "Raw JSON" tab for advanced fields

Via the Raw JSON tab, you see the complete Transformer Configuration as a JSON document and can edit it directly.

In the JSON tab, fields that are not shown in the form are available in particular:

• apply_common_functions — a list of predefined transformations that are applied to the file in the specified order, e.g.:
  • query — filter out rows based on a condition ("query": "source_unit != target_unit").
  • strip — remove leading and trailing whitespace.
  • drop_column — remove a column from the result.
  • remove_duplicated_rows — remove duplicate rows.
  • remove_leading_zeros — strip leading zeros from a column (common for article numbers).
  • set_default_order_unit / set_default_order_unit_to_sales_unit / ensure_sales_unit_in_order_unit — standardize order units.
  • eval_expression — evaluate an expression to compute a new column value (e.g. a composite customer description).
  • add_incremental_id — add a sequential ID as a column.
  • filter_by_length / detect_chars — filter rows based on the length or a pattern in a column.
• replace_nan — replace empty values of a column with a default value.
• query — global filter condition that is evaluated immediately after reading the file.

Example JSON for an article list with mandatory handling:

{
  "file_name_patterns": ["customer_article_list.csv"],
  "file_reader_kwargs": {
    "encoding": "utf-8",
    "delimiter": ";"
  },
  "columns": {
    "article_id1": "Artikelnummer",
    "description": "{Bezeichnung_DE} {Farbe}",
    "partition_id": "'main'",
    "gross_price": "Listenpreis",
    "order_units": "Bestelleinheit",
    "sales_units": "Verkaufseinheit"
  },
  "apply_common_functions": [
    { "strip": "description" },
    { "remove_leading_zeros": "article_id1" },
    { "remove_duplicated_rows": ["article_id1"] }
  ]
}

As soon as you change something in the JSON, a red notice appears at the bottom if the JSON is not syntactically valid. Use Format JSON to indent and tidy the text without changing its content.

warning

The column names on the left side of "columns" must come from the target schema of the respective lookup type — otherwise the configuration is rejected on save.

---

Step 7 — Save

Click Save at the bottom right. On success, the dialog does not close; instead, the display is refreshed and you see the saved configuration. With Cancel, you discard all changes made since the last save.

When does the new configuration take effect?

Only on the next import run. Already completed imports are not reprocessed retroactively. If the new configuration should take effect immediately, re-upload the input file to the SFTP server after saving, or have your contact at Workist trigger the import again.

---

Allowed target columns per lookup type

Which columns are available for selection in the Column name field depends on the lookup type. An overview of the most important schemas (mandatory columns in bold):

Lookup type	Mandatory columns	Important optional columns
Articles	article_id1, description	article_id2, article_id3, gross_price, order_units, sales_units, partition_id, article_status, extra_data
Customers	client_id1	company_name, address1, street_name, zip_code, city, country, iln, vat, iban, partition_id
Customer contacts	partition_id, contact_id, first_name, last_name	email, phone, extra_data
Addresses	address_id1	name, address1, street_name, zip_code, city, country, phone, partition_id
Conversion factors	source_unit, target_unit, conversion_quotient	article_id, partition_id
Framework contracts	partition_id, contract_id1	client_id, client_name, contract_id2, contract_name
Order matching	order_number	order_date, delivery_address, article_id1, quantity, total_price, payment_terms_due_days, iban
Offer matching	offer_number	valid_from, valid_until, article_id1, quantity, unit

Columns outside these lists are rejected by the import path.

---

Help and support

If the import continues to fail after a change, or the desired values do not end up in the Workist schema, contact your point of contact at Workist and have the following information ready:

• the channel name and the lookup type (e.g. "Articles"),
• the time of the failed import (column Imported on),
• the input file of the import (linked in the table),
• for changes to the JSON: the complete JSON document from the Raw JSON tab.