XperienceCommunity.ContactsImporter 1.0.0

Xperience Community Contacts Importer

Description

Enables bulk import and deletion of contacts in an Xperience by Kentico solution using a .csv file. Imported contacts can be automatically assigned to a contact group or recipient list during the import process.

This is a community-maintained fork of the original Kentico/xperience-by-kentico-contacts-importer, updated for .NET 10 and Xperience by Kentico 31.5.x.

Requirements

Dependencies

• ASP.NET Core 10.0
• Xperience by Kentico version 31.5.3 or higher
• Node.js >=20.13 <=21 (only required when building the admin UI client from source)

Package Installation

Add the package to your application using the .NET CLI:

dotnet add package XperienceCommunity.ContactsImporter

Quick Start

Add AddContactsImport() and UseContactsImport() to your application startup code:

builder.Services.AddContactsImport();
// ... other service registrations

app.InitKentico();
// ... other middleware
app.UseContactsImport();

Usage

1. Open the Xperience administration, go to the Contact importer application (under Digital marketing).
2. Choose the import kind (insert new contacts or delete existing contacts).
3. (Optional) Select a contact group or recipient list to assign imported contacts to.
4. Configure the CSV delimiter and batch size.
5. Upload your .csv file and start the import.

CSV format

For inserts, the importer maps the following (case-insensitive) columns. Only ContactEmail is required:

ContactGUID, ContactCreated, ContactFirstName, ContactLastName, ContactEmail, ContactAddress1, ContactMiddleName

For deletes, only the ContactEmail column is used.

Logging

Import progress and errors are logged through Xperience's ILogger<> integration (see Kentico logging documentation). Errors that occur during an import — including per-record failures and web socket/producer/consumer failures — are written at the Error level, and each import logs an Information-level start and finish summary. These entries are visible in the configured logging providers (for example the Xperience Event log).

Building the admin UI client

The administration UI is a React/TypeScript client located in src/Admin/Client. The compiled bundle is emitted to src/Admin/Client/dist and embedded into the NuGet package.

To build the client manually:

cd src/Admin/Client
npm install
npm run build

The build is run automatically as part of dotnet build / Rebuild (see below), so a manual build is only needed when iterating on the client in isolation.

Building the project

This repository uses a .slnx solution file. To build the project:

dotnet build xperience-community-contacts-importer.slnx

The project's MSBuild targets automatically run npm install and npm run build for the admin client on every build/rebuild, so the embedded UI bundle is always up to date. To skip the npm build (for a faster .NET-only inner loop) pass:

dotnet build xperience-community-contacts-importer.slnx -p:SkipNpmBuild=true

License

Distributed under the MIT License. See LICENSE for more information.