Table of Contents

Import data how-to

This how-to explains the end-to-end workflow for setting up and running a CSV import with the NeosDataExchange module.

It focuses on the user-facing tasks required to prepare an import, validate it, and execute it safely.

Before you start

To use the import features, the module must be available in your cluster and the relevant user permissions must be enabled.

You also need:

  • an entity view registered as an import target,
  • an import template,
  • a column mapping model,
  • a CSV file with a header row.

Example scenario

Imagine you need to import customers from a CSV file with the following columns:

CustomerCode;DisplayName;Email;IsActive
CUST-001;Contoso Ltd;[email protected];true
CUST-002;Northwind Traders;[email protected];true

In that case, the import template should target the customer entity view, use ; as the separator, and define mappings such as:

  • CustomerCode -> Code
  • DisplayName -> Name
  • Email -> EmailAddress
  • IsActive -> IsActive

Register an import entity view

An import starts from an entity view that has been registered as an import target in the business assembly.

Use RegisterImportEntityView in the cluster startup code to expose the entity view to the import pipeline:

public static void ConfigureServices(IServiceCollection services)
{
    services.RegisterImportEntityView<IYourEntityView>();
}

If the entity view is not registered, it cannot be used by the import user interface.

Expose the import UI methods in your views

The data import module provides UI methods that you can call from your own views or menus.

Use these methods when you want to offer a direct entry point to the import experience:

  • NeosDataImport.ShowImportTemplateSettingsAsync(null) opens the import template settings screen,
  • NeosDataImport.ShowImportDialogAsync(this, "YourEntityViewName") opens the import dialog for a specific entity view.

Example: add an import entry point from the home page

In a home page or settings menu, you can add a dedicated action that opens the import template settings:

- Name: ShowImportTemplates
  BeginGroup: true
  Caption: Data integration
  Code: _ = UIMethods.NeosDataImport.ShowImportTemplateSettingsAsync(null);
  IconName: NeosDataImportIntegration
  Location: ChildOf
  ParentActionName: Settings
  Position: 3

This pattern is useful when you want users to manage import templates before they start a file import.

Example: launch an import from a business screen

From an entity view such as a journal entry screen, you can expose an import action that targets the current import model:

- Name: ImportData
  Caption: Import data
  Code: _ = UIMethods.NeosDataImport.ShowImportDialogAsync(this, "JournalEntryView");
  IconName: ImportFile
  Position: 4
  Style: Positive

Use this pattern when the user should start the import directly from the business context instead of navigating to the import management screen first.

Create an import template

The import template defines how a given import behaves and which target model it uses.

Open the import template editor and create a new template.

Template parameters

The main template parameters are:

  • Template name: the name used to identify the template,
  • Mapping model: the import type or target model,
  • Separator: the CSV column separator,
  • File format: the file format to read,
  • Batch size: the number of rows processed in a single batch,
  • Validation mode: the execution mode used during validation,
  • Update kind: whether the import creates, updates, or both,
  • Enable validation rules: runs validation rules during save,
  • Enable event rules: runs event rules during save,
  • Enable query logging: logs queries during save.

How to choose the parameters

Separator must match the source file. The default separator is usually ;, but other common delimiters are also supported when the source file uses them.

For example, if the source file looks like this:

CustomerCode;DisplayName;Email;IsActive
CUST-001;Contoso Ltd;[email protected];true

then the separator must be ;. If the file uses commas instead, the template must use ,.

Batch size controls how many rows are processed at once. A larger batch usually improves throughput but consumes more memory and makes a failure affect more rows. A smaller batch is safer for large or unstable imports, but takes longer to complete.

Note

For example, a batch size of 1000 is a good starting point for a medium-sized import, while 100 can be more practical when you want quicker feedback during template testing.

Validation mode defines how the import is executed:

  • Run: the import is executed and data is saved,
  • DryRun: the import is simulated in memory,
  • TransactionalDryRun: the import runs against the database but is rolled back at the end.

Update kind defines the business behavior:

  • CreateOnly: only create new records,
  • UpdateOnly: only update existing records,
  • CreateOrUpdate: create new records or update existing ones.
Note

For example, when you import a new customer master file, CreateOnly avoids overwriting existing data. When you resynchronize an existing customer list, CreateOrUpdate is usually the safest option.

The save options are useful when you need to tune robustness and diagnostics:

  • Enable validation rules keeps business validation active,
  • Enable event rules keeps event processing active,
  • Enable query logging helps troubleshoot the execution.

Create a column mapping model

The mapping model links source CSV columns to target entity-view properties.

Each mapping usually defines:

  • the source column name,
  • the target property name,
  • optional default values,
  • optional formatting or length settings,
  • the display order of the mapping.

Create mappings manually

Use the mapping table in the import template editor when you already know the structure of the file.

Recommended steps:

  1. Open the import template.
  2. Go to the mapping model or mapping table section.
  3. Add one mapping per source column.
  4. Select the matching target property.
  5. Adjust any property-specific settings if needed.
  6. Reorder the mappings if the display order matters.

Manual mapping is the best option when the source file format is stable and already documented.

Note

For example, if the CSV header is CustomerCode;DisplayName;Email;IsActive, you can map it directly to Code, Name, EmailAddress, and IsActive without needing any automatic discovery.

Create mappings from a CSV file

Use the column mapping screen to load a reference CSV file and populate the mapping table from its header.

Recommended steps:

  1. Open the import template.
  2. Launch the add-from-file workflow.
  3. Select the CSV reference file.
  4. Choose the correct column separator.
  5. Make sure the file contains a header row.
  6. Load the header column names.
  7. Match the source columns to the target properties.

If the file has no header or the separator is wrong, the header extraction step fails and the mapping table cannot be prefilled correctly.

Warning

For example, if the file contains only data rows such as CUST-001;Contoso Ltd;[email protected];true without a header line, the import cannot infer which source column should be mapped to which target property.

Run an import

When the template and mappings are ready, start the import from the staging workflow.

Recommended steps:

  1. Open the import setting screen for the data screen.
  2. Upload the CSV file.
  3. Confirm the separator and file options.
  4. Start the validation step.
  5. Review the staging summary and the row details.
Note

For example, after uploading customers-2026-06.csv, the staging summary should show the processed row count, the number of valid rows, and any warnings or errors before you proceed.

The staging screen shows the file name, summary counters, and row-level results so you can monitor the execution without leaving the business context.

Validate data

Validation checks whether the CSV file and the mapping model are ready for integration.

Note

For example, use DryRun when you want to check the mapping and business rules without saving anything, or TransactionalDryRun when you want to test the full execution path but still roll back the data at the end.

During data validation, review:

  • file structure,
  • header presence,
  • source-to-target matching,
  • row-level warnings and errors,
  • staging counters and summary values.

A successful validation means the import is structurally ready. It does not mean the data has already been committed to the target entity view.

Note

For example, if EmailAddress is mandatory and one source row has an empty email value, validation should surface that row before you launch the real integration.

Warning

An import that still contains rows in Error status cannot be validated. Fix the source file, reload it, and run validation again.

Validate an import

After data validation, run the integration to persist the imported data into the target entity view.

Recommended steps:

  1. Review the validation results.
  2. Make sure the rows you want to process are eligible.
  3. Launch the integration.
  4. Select the update kind if the integration screen asks for it.
  5. Monitor the integrated row count and any warnings or errors.
Note

For example, if 200 rows were validated successfully, the integration screen should show how many were actually created or updated and whether any rows were skipped because of a business conflict.

Note

The integration uses the template options, save options, and update strategy defined for the import.

There is no in-staging correction feature.

If an import result is wrong, fix the source file and run the import again.

Warning

For example, if one customer code is wrong in the CSV, correct the source line, reload the file, and rerun the import instead of trying to edit the staging row manually.

See also