CSV Import
Package: BASIC
1. General
The file format CSV stands for Comma-Separated Values and describes the structure of a text file for storing or exchanging simply structured data.
The file extension is .csv.
CSV files can contain tables or lists of varying length. Within the text file, certain characters have a special function for structuring the data. Depending on the software used and user settings, these are often the comma, semicolon, or colon characters.
The first record can be a header record that defines the column names.
In most cases, Excel files are used as the basis for a CSV import. The following section Convert Source File explains how to convert the source file (.xlsx) into a CSV file (.csv).
Excel is not the first choice in practice for creating or editing CSV files. Nevertheless, experience shows that Excel is often used because many users are familiar with it.
Recommended alternatives are "Notepad++" on Windows and "BBEdit" or "TextMate" on macOS.
For users, the "readability" in Excel is generally better, but especially in the case of formatting issues, the alternative CSV programs are very helpful.
View of the sample CSV file in Excel
View of the sample CSV file in Notepad++
2. Convert Source File
This description assumes that the source file is a Microsoft Excel file (.xlsx) that must first be converted into a format compatible with brainX (.csv).
The content of the source file should meet the following criteria:
- The first row should be the header row to make it easier to map the columns during the import. Ideally, the columns should be named like the target fields in brainX.
- The source file must contain at least as many columns as there are mandatory fields defined in the target module in brainX. If mandatory fields are missing or empty, the record cannot be imported.
- The field "responsible" is essential for the import. This field is used to assign the records being imported to a brainX user. It is important that the value in this column must always be the username and the spelling must match exactly 1:1.
- Instead of a user, a group can also be used in the "responsible" column. Here, too, the spelling must match exactly.
- Columns and values whose target field is a selection list in brainX must match 1:1 with the spelling of the existing selection list values.
2.1. Conversion Steps
- The file must first be opened in Microsoft Excel.
- In the "File" toolbar, select the "Save As" option.
- In the dialog window that opens, select the file type "CSV (Comma delimited) (.csv)*".
1. Enter an appropriate file name and then click Save.
1. Confirm the displayed message with "Yes".
1. The source file is now in CSV format and ready for import.
This completes the conversion of the Microsoft Excel file into a format compatible with brainX. It is now a text file of type CSV, the delimiter is a semicolon, and the encoding is (predefined by Microsoft) of type ANSI (ISO-8859-1)).
2.2. CSV Syntax
The syntax in the CSV file must be observed, which depends on the field types/values. If values are to be imported into a field of type "Selection List" or "Multi-Select List", these values must be enclosed in single quotes. If multiple values are to be imported into a multi-select list, they must be separated by a comma followed by a space.
For the CSV import example in the Contacts module, it is assumed that the fields First Name, Last Name, Lead Source, and responsible are imported and the selection list values of the Lead Source field internally are:
Value1
Value2
Header: First Name;Last Name;Lead Source;responsible
Field values: Max;Mustermann; 'Value1', 'Value2';admin
3. Background Task for CSV Import
For a CSV import to be executed, the background task CSV/ICS Import must be active. This background task checks at regular intervals whether new imports are pending and executes them.
The minimum execution interval is one minute for every cloud variant.
Only one CSV/ICS import can be registered per user and module. As long as this has not been executed, no further imports can be registered. In this case, the following notice is displayed:
As long as the background task has not yet executed the registered CSV/ICS import, it can be deleted at any time and a different CSV/ICS import can then be registered.
4. CSV Import Settings and Limits
There is no setting in brainX for the maximum number of records to be imported. However, there are certain technical limits.
The number of records to be imported depends on the following settings:
- Upload limit for records
- Record limit for imports with event handling This value is set to 100 by default in brainX systems. This means that if the Allow Events toggle is set to on in Step 1 of the import, a maximum of 100 records are possible.
If events are enabled, mechanisms such as automations and change tracking are executed during the import. This can increase the duration of the import and may slow down brainX somewhat — depending on the cloud variant.
5. Importing a CSV File
Whether a user is allowed to perform a CSV import — i.e., whether the CSV Import action is available in the list view — can be configured individually per module via the profile settings.
For the import, it is important that the user performing the action has the necessary permissions. If active permission management is in place (e.g., modules are private, functions disabled), it must be ensured that the target module is active for the user and the function for importing data from CSV files is enabled.
In general, a user can import records for any users and groups. It should be noted that due to permission settings, not all records may be displayed after the import and may also not be considered in the manual search for duplicates.
5.1. Import Steps
The following describes the import steps using the Leads module as an example.
The CSV import is identical in all modules, with the exception of two special cases:
Clicking the Actions button in the list view of the module opens a popup menu showing all available actions for that module.
After clicking the CSV Import action, Step 1 of 3 opens, which are described in detail below.
5.1.1. Step 1 — Select CSV File
CSV Import — Select CSV File
In the first step, there are the following fields/settings:
- Encoding → The values UTF-8 and ISO-8859-1 are available here. For the example, "ISO-8859-1" is selected.
- Delimiter → The values Semicolon and Comma are available here. For the example, "Semicolon" is selected.
- Has Header Row → Toggle to specify whether the CSV file contains a header row. For the example, "yes" (toggle on) is selected.
- Allow Events → Toggle to specify whether events are allowed during the import. For the example, "no" (toggle off) is selected.
- File Upload → CSV files can be dropped here (Drag & Drop) or selected via the file explorer of the operating system. For the example, the file "Leads.csv" is selected.
Now click the Continue button at the bottom right to proceed to the next step.
If no CSV file has been selected/uploaded, a corresponding notice is displayed:
Notice: missing CSV file
If a CSV file is correctly selected, after clicking the Continue button, the CSV file is checked for validity. If the CSV file is not valid, the errors found are displayed accordingly:
Notice: file contains errors
After successful validation, a corresponding notice is displayed:
Notice: validity checked
Now click the Continue button in the notice popup to proceed to Step 2.
5.1.2. Step 2 — Field Mapping
In the second step Field Mapping of the import, the records contained in the CSV file are displayed in a list view:
CSV Import — Display & Field Mapping
There are various setting and selection options here:
- Display of the number of records to be imported
- Selection of the language of the CSV file
- Create or select field mappings
- Selection of the columns to be imported
- Adding additional columns (fields)
- Setting up automatic creation of missing selection list values
If the CSV file to be imported contains very many columns, these are not immediately visible in the list view due to space constraints.
At the bottom of the list view there is a horizontal scrollbar, which must be used to see all columns and configure them as needed (select/deselect fields, set default values, set missing field values, etc.).
5.1.2.1. Display Number of Records
Directly to the left above the list view is the display of the number of detected records.
5.1.2.2. Selection of CSV File Language
The Language of CSV File selection list defines the source language of the CSV file. If it is English, for example, the value US English must be selected.
Based on this information, the system attempts to identify values whose target field is a selection list and assign them accordingly. If the value cannot be identified in the existing selection list and the corresponding option was selected, a new value is created and assigned to the record.
General information about language settings is available in the following sections:
5.1.2.3. Create or Select Field Mappings
Using the Existing Field Mappings selection list, either an existing field mapping can be selected or a new field mapping can be saved.
After clicking the selection list, a flyout window opens:
Selection list: existing field mappings
If multiple field mappings already exist, one can be selected.
To save a new field mapping — which was configured beforehand — simply enter a name in the input field and click the Save button:
New field mapping
After saving the new field mapping, the flyout window looks as follows:
New field mapping saved
Existing field mappings can be deleted using the Recycle Bin actions icon.
Saving field mappings is useful when CSV files with the same structure are used regularly.
5.1.2.4. Selection of Columns to Import
The selection of columns to be imported is done using the checkbox to the left of the column header.
In the following screenshot, the columns Salutation, First Name, Last Name, and Organization were selected. The Phone column was deselected and will therefore not be imported.
CSV Import — Column Selection
5.1.2.5. Adding Additional Columns
During the CSV import, additional columns can be added that are not contained in the CSV file in order to fill them with default values.
To add additional columns, click the Add Column actions icon (Plus icon), which is always located at the far right in the column header row.
Action: Add Column
After clicking the Add Column actions icon, the Add Column popup window opens:
Add Column popup
The Column Title selection list lists all fields from the detail view of a record for the respective module:
Column Title selection list
In the Default Value selection list, a default value can now be selected:
Column Title selection list — Default Value
Clicking the Save button in the Add Column popup applies the selected configuration.
5.1.2.6. Setting Missing Selection List Values
For fields of type Selection List and Multi-Select Box, missing values can be created automatically. Whether this action should be executed can be specified using the Create Missing Values checkbox. The Create Missing Values checkbox is displayed in every column of type selection list.
For missing values in the CSV file, default values can be defined for fields of type Selection List and Multi-Select Box.
Actions icon: Set Default Value
After clicking the Set Default Value actions icon (Gear icon), the Set Default Value popup window opens:
Set Default Value popup
In the Default Value selection list, a default value can now be selected.
Clicking the Save button in the Set Default Value popup applies the selected configuration.
5.1.2.7. Missing Field Mapping
If column headers are not automatically recognized as existing fields in the respective module when reading the CSV file, the field mapping can be done manually.
Missing field mappings are highlighted in color in the list view and the column header Missing Mapping is displayed:
Notice: missing mapping
To perform a field mapping, click the angle bracket icon. A flyout window opens listing all fields from the detail view of a record for the respective module:
Selection list: missing mapping
After clicking a field name, the selection is applied.
5.1.3. Step 3 — Merge Duplicates
In the third step Merge Duplicates, it is possible to detect duplicates during the import. There are two options: manual merging and automatic merging.
CSV Import — Merge Duplicates
In manual merging, a list of all identified duplicates is displayed after the import, and the decision on how to handle them is left to the user. In the case of automatic merging, a selection can be made as to whether duplicates should be ignored or overwritten during the import. In both cases, only a summary is displayed after the import, without the ability to influence the import or the duplicates.
The Select criteria for duplicate check section allows you to define which fields the import uses to compare the data to be imported with existing data and thereby detect duplicates. To achieve the highest possible uniqueness, it is recommended to choose a combination of several fields.
For automatic merging with overwriting, the following points must be observed:
- If the option to overwrite records is selected, this cannot be undone!
- If automatic merging is selected to update records, all columns in Step 2 — Field Mapping must be mapped, otherwise unmapped fields will be overwritten with empty values!
- If more than one record is found as a duplicate based on non-uniquely selected criteria, the first one is overwritten and the remaining ones are deleted from the system!
After clicking the Save button, the import is registered for execution. The import is then carried out the next time the background task CSV/ICS Import runs.
The user is regularly informed about the progress of the import via notifications in the navigation bar.
5.2. Messages During CSV Import
If the configuration of the CSV import has not been done correctly, corresponding messages are displayed.
During the CSV import, country codes, among other things, are validated. The currency itself is also validated (e.g. the word “Euro” or the code “EUR”) – not to be confused with the validation of amount fields.
Fields were selected multiple times:
One or more mandatory fields are not present in the CSV file, or were not selected:
Only after the conflicts have been resolved can the CSV import be carried out.
5.3. Import Summary and Completion
At the end of the import, a final message is displayed which may contain the following information (depending on the result of the import):
- Number of imported records
- Number of records not imported
- Number of records ignored due to duplicates
- Number of overwritten records
- Link to the list of imported records
- Link to manual merging of duplicates
- Link to undo the import
- If records were not imported or ignored, a link to a log file appears, listing the reasons for the corresponding rows of the CSV file.
5.4. Special Case: CSV Import of Contacts
For the CSV import of records in the Contacts module, there are two additional options in the Field Mapping step:
- Data enrichment when creating a new organization
- Data enrichment when creating a new partner
CSV Import of Contacts
If the checkbox is checked here, certain data from the contact (such as email and address data) is also transferred to the organization or partner when they are newly created. Existing records in the Organizations and Partner modules are not overwritten.
In general, the search for already existing organizations or partners to be referenced is done based on the organization or partner name.
After the Field Mapping step, there is an additional Reference Settings step in the CSV import of contacts.
CSV Import Contacts — Mapping of Reference Settings
For the reference settings mapping, the following options are available for the type of referencing:
- Standard referencing → the columns Organization and Partner are used automatically (if present)
- Extended reference mapping → a field from brainX and a column from the CSV file can be selected for organizations as well as partners.
5.5. Special Case: CSV Import of Users
As a rule, new brainX users are created manually by the administrator in Global Settings — Users and Groups.
New brainX users can alternatively also be created via a CSV Import.
The procedure is described in detail in the section Global Settings — Users and Groups — Import Users.
6. Practical Examples
1 - Import customer data after switching to brainX
Situation: A company switches from another CRM system to brainX. The existing customer data is available as an Excel file and should be imported as organizations into brainX.
Approach: The Excel file is cleaned up and the column headers are adjusted to match the field names in brainX. A responsible column is added and filled with the correct username. The file is saved as CSV (semicolon-delimited, ISO-8859-1). In the Organizations module, the CSV Import action is started. In the Merge Duplicates step, automatic merging with Ignore is selected, since this is an initial import. After the background task runs, all records are available in brainX.
Result: All customer data is fully and correctly imported into brainX — without manual individual entry.
2 - Import trade fair leads collected in bulk as CSV
Situation: After a trade fair, the collected contact data is available in an Excel spreadsheet. All leads should be assigned to the lead source Trade Fair and assigned to a specific sales representative.
Approach: The Excel file is saved as CSV. In the Field Mapping step, the field Lead Source is added with the default value Trade Fair using Add Column. The responsible field is already filled in the CSV with the username of the sales representative. The import is started with events disabled, since no automations should be triggered.
Result: All trade fair leads are created in brainX, correctly assigned, and immediately available for further processing by the sales team.
3 - Save field mapping for recurring imports
Situation: A company receives a structured file from an external service provider every month, which is regularly imported as leads into brainX. The column names in the file differ from the brainX field names.
Approach: During the first import, the field mapping is done manually in the Field Mapping step and then saved under a meaningful name. For all subsequent imports, the saved field mapping is selected directly — manual mapping is no longer necessary.
Result: Recurring imports are completed in just a few clicks. Mis-mappings due to manual input are avoided.
7. FAQ
Why are special characters (umlauts) displayed incorrectly after the import?
The cause is usually an incorrect encoding. If a CSV file is saved in Excel on Windows, Excel uses ISO-8859-1 (ANSI) by default. In Step 1 of the import, ISO-8859-1 must therefore be selected as the encoding. If the CSV file is created in another tool or on macOS, UTF-8 is often the correct choice. In case of doubt, it is recommended to check the file in Notepad++ (Windows) or a comparable text editor.
Why are some records not created during the import?
The most common causes are missing or incorrectly spelled mandatory fields, an unrecognized username in the responsible field (spelling must match exactly), or incorrectly formatted selection list values (missing quotes, spelling differs). The exact error causes are listed in the log file, which is accessible after the import via the corresponding link in the import summary.
What happens to empty fields in the CSV file?
Empty fields are treated as empty during the import and, when automatic merging with Overwrite is enabled, overwrite the existing field value with an empty value. If empty fields should not be overwritten, it is recommended to use CSV Update instead of the import with the overwrite option.
Can the import be undone?
Yes, immediately after the import, an Undo Import link is available in the import summary. However, this is only available directly after the import. If the summary has been closed, undoing is no longer possible — in this case, the records must be deleted manually.
How many records can be imported at once?
This depends on the system-side limits. If the Allow Events option is active during the import, a maximum of 100 records per import are possible by default. If events are disabled, the general upload limit of the system applies. For very large amounts of data, it is recommended to split the import into several smaller files.
What should be especially noted when importing contacts?
When importing contacts, there is an additional Reference Settings step in which it is specified how the contact is assigned to an organization or partner. If a new organization should be automatically created during the import and enriched with contact data, the corresponding checkbox must be activated in the Field Mapping step. Existing organizations are not overwritten in the process.