Import Mapping
Import Mapping
The import mapping in Universal Import is used to transfer data from external files into Business Central in a structured way. It allows file columns to be assigned specifically to the corresponding fields and helps manage recurring imports efficiently.
For a clear overview and quick reference, the following table presents the individual elements of the Import Mapping section.
1. Create a mapping
A mapping is a reusable template that defines how the data from your file is assigned to fields in Business Central. It allows you to define once which table is imported which file format is used and how the system should behave during the import.
1.1 Create a New Mapping
How do you access the “Import Mapping Card”?
Open the “Universal Import” page using the Business Central search. In the menu that opens navigate to “Mapping Configuration” and select “Mapping”. Then click the three dots (...) to open the context menu and choose “+ New” to create a new mapping. You can now enter the required master data on the “Import Mapping Card” page that opens. Finally, save the record.
1.2 Fields on the mapping card
The most important fields in the mapping header are:
Name: A meaningful name for the mapping, for example “Items from Supplier Excel”.
File Type (Mapping Type): Excel, CSV, XML, or JSON. It must match the format of your source file.
The fields displayed and to be completed on the Import Mapping Card vary depending on the selected file type.
CSV Separator: The separator used for CSV files. A semicolon is typically used.
Target Table: Specify the BC table into which the data should be imported.
Use the table lookup (...) to open the list of available tables. In the “Select Target Table” menu a filter is applied by default so that only the most common entries are shown. To display all available lines click “Table ID” and select “Clear Filter” from the drop-down menu. You can then choose the desired target table.
Target Table Name: These fields are filled automatically based on the selected target table.
Item Template: Optional; only relevant when importing into the Item table. It defines which BC item template is used for newly created items.
JSON Record Path: The dot path to the record array in nested JSON (for example
data.items). Leave this field empty if the root element is already the array.Validate Fields: This option is enabled by default. Values are then validated automatically and other fields are filled accordingly.
For more complex tables, it may be better to disable this option to avoid errors.
Import action:
Used as the default option.
Creates new records and updates existing ones.
Example use: General use for initial data import and ongoing updates based on the same file logic.
Creates new records only; existing records are not overwritten.
Example use: Add new products without changing existing master data.
Updates existing records only; new keys from the file are not created.
Example use: Update prices or quantities without accidentally creating new items.
After creating the mapping upload a sample file on the “Universal Import” page. This allows the file columns to be recognized so that you can conveniently set up the column mapping.
For the import and the subsequent process refer to markdown. The further procedure is described in that section.
2. Assign Columns
Once you have uploaded a file on the import page, the “Column Mapping” section appears with all columns recognized from the file. There, you link each source column to a target field in BC and control the order as well as the activation.
Functions of the mapping list
Each row shows:
Source Column
Target field (BC-field)
Static value
Virtual column
active/inactive.
Color coding:
green border = assigned
grey = not assigned yet
yellow = virtual column
Change target field
Click the target field button to open the field selection dialog for the target table and change the field assignment.
Drag and Drop:
Drag rows with the mouse to change the processing order. This is important if the validation of field A only works after field B has been set.
Toggle all:
Use the active checkbox in the header row to enable or disable all columns at once.
Deactivated columns are skipped during the import.
3. Virtual columns
A virtual column provides the same predefined value for every imported line. It does not come from your file but is defined in the mapping. This is ideal when information is missing from the file but is the same for all lines.
On the Universal Import page or on the Mapping Card click “Add Virtual Column”. Then select the target field and enter the value.
Typical use cases
Your file does not contain a Price List Code column but all lines belong to the same price list.
You want to set the same source type for all imported price list lines.
All items should be assigned to the same vendor.
Virtual columns are highlighted in yellow in the mapping list and are always processed before the column-based values from the file. This is important if other fields depend on these values.
4. Copy and reuse
4.1 Copy mapping
In the "Import mapping" list select a mapping and choose the “Copy Mapping” action from the menu in the top-right corner (...) of the window. Enter a new name to create a complete copy including all settings and column mappings.
Example use: You create a basic mapping for your item import and copy it for slightly different scenarios such as a different price list or a different vendor file format. This saves time for recurring imports that are similar but not identical.
4.2 Import directly from the list
With “Start Import” you can jump directly from the mapping list to the “Universal Import” page, where the selected mapping is already preselected. This allows you to upload and import the file without any extra steps.
4.3 Reuse with Quick Import
Once your mappings have been set up Quick Import is ideal for recurring imports. The system identifies the correct mapping by matching the file’s column headers with the saved mappings.
Tip for partners
Consulting partners, for example suppliers with price lists, can set up mappings professionally once and then hand recurring imports over to end users. These users can simply use Quick Import without having to configure the mapping again each time.
Last updated