Merge pull request #20 from Kentico/maint/code-cleanup

Code cleanup

Author: kentico-ericd

Directory.Build.props

@@ -6,7 +6,7 @@
     <Copyright>Copyright © $(Company) $([System.DateTime]::Now.Year)</Copyright>
     <Trademark>$(Company)™</Trademark>
     <VersionPrefix>1.0.0</VersionPrefix>
-    <VersionSuffix>prerelease-2</VersionSuffix>
+    <VersionSuffix>prerelease-3</VersionSuffix>
     <PackageLicenseExpression>MIT</PackageLicenseExpression>
 
     <PackageProjectUrl>https://github.com/Kentico/xperience-by-kentico-contacts-importer</PackageProjectUrl>

README.md

@@ -1,86 +1,50 @@
 # Xperience by Kentico Contacts Importer
 
 [![Kentico Labs](https://img.shields.io/badge/Kentico_Labs-grey?labelColor=orange&logo=data:image/svg+xml;base64,PHN2ZyBjbGFzcz0ic3ZnLWljb24iIHN0eWxlPSJ3aWR0aDogMWVtOyBoZWlnaHQ6IDFlbTt2ZXJ0aWNhbC1hbGlnbjogbWlkZGxlO2ZpbGw6IGN1cnJlbnRDb2xvcjtvdmVyZmxvdzogaGlkZGVuOyIgdmlld0JveD0iMCAwIDEwMjQgMTAyNCIgdmVyc2lvbj0iMS4xIiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciPjxwYXRoIGQ9Ik05NTYuMjg4IDgwNC40OEw2NDAgMjc3LjQ0VjY0aDMyYzE3LjYgMCAzMi0xNC40IDMyLTMycy0xNC40LTMyLTMyLTMyaC0zMjBjLTE3LjYgMC0zMiAxNC40LTMyIDMyczE0LjQgMzIgMzIgMzJIMzg0djIxMy40NEw2Ny43MTIgODA0LjQ4Qy00LjczNiA5MjUuMTg0IDUxLjIgMTAyNCAxOTIgMTAyNGg2NDBjMTQwLjggMCAxOTYuNzM2LTk4Ljc1MiAxMjQuMjg4LTIxOS41MnpNMjQxLjAyNCA2NDBMNDQ4IDI5NS4wNFY2NGgxMjh2MjMxLjA0TDc4Mi45NzYgNjQwSDI0MS4wMjR6IiAgLz48L3N2Zz4=)](https://github.com/Kentico/.github/blob/main/SUPPORT.md#labs-limited-support)
-
-[![CI: Build and Test](https://github.com/Kentico/xperience-by-kentico-contacts-importer/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/Kentico/xperience-by-kentico-contacts-importer/actions/workflows/ci.yml)
-
+[![CI: Build and Test](https://github.com/Kentico/xperience-by-kentico-contacts-importer/actions/workflows/ci.yml/badge.svg)](https://github.com/Kentico/xperience-by-kentico-contacts-importer/actions/workflows/ci.yml)
 [![NuGet Package](https://img.shields.io/nuget/v/Kentico.Xperience.Contacts.Importer.svg)](https://www.nuget.org/packages/Kentico.Xperience.Contacts.Importer)
 
-## About The Project
+## Description
 
-Enables bulk importing of Contacts into an Xperience by Kentico solution using a `.csv` file.
+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 during the import process.
 
-![View of the Import Upload dashboard](https://github.com/user-attachments/assets/ae48f836-db00-4bae-8b43-e39482d73a3a)
+## Requirements
 
-## Getting Started
+### Library Version Matrix
 
-### Prerequisites
+| Xperience Version | Library Version    |
+| ----------------- | ---------------    |
+| >= 30.5.1         | 1.0.0-prerelease-2 |
 
-- Xperience by Kentico >= 30.5.1
+### Dependencies
 
-  - <https://docs.kentico.com/documentation/changelog#hotfix-may-22-2025> 
+- [ASP.NET Core 8.0](https://dotnet.microsoft.com/en-us/download)
+- [Xperience by Kentico](https://docs.kentico.com)
 
-### Installation
+## Package Installation
 
 Add the package to your application using the .NET CLI
 
 ```powershell
-dotnet add package Kentico.Xperience.Contacts.Importer
+dotnet add package --prerelease Kentico.Xperience.Contacts.Importer
 ```
 
-### Add to your application dependencies
+## Quick Start
 
-```csharp
-builder.Services.AddKentico();
-// ... other registrations
-services.AddContactsImport();
-```
-
-### Add to your middleware pipeline
+Add `AddContactsImport()` and `UseContactsImport()` to your application startup code:
 
 ```csharp
+builder.Services.AddContactsImport();
+// ... other service registrations
+
 app.InitKentico();
-// ... other registrations
+// ... other middleware
 app.UseContactsImport();
 ```
 
-## Usage
-
-1. open contact importer application <br>
-   ![ContactImporterApplication](./images/ContactImporterApplication.png)
-1. select file
-1. select mode
-   1. Delete - this mode will delete contact by ContactGUID (CSV shall contain column with ContactGUID header)
-   1. Insert (skip existing) - this mode will import contacts (CSV shall contain column with ContactGUID)
-1. "Assign to contact group" - all contact (existing included) will be assigned to specified group
-1. Delimiter - delimiter used for CSV (common are `;`, `,`, `\\t`, ..)
-1. "Batch size" - size of batch used for database operation, for instances with limited resources this value should not exeed 5000, lower than 100 is not reccomended.
-1. Click "Send file" button
-
-> Depends on resources available to application, but degraded application performance is expected during import.
-
-Notes:
-
-- do not close window with progress, file is uploaded from that window.
-- do not manipulate file during import, close all applications write access to file (or lock)
-
-### Supported CSV columns
-
-| Column            | .NET Type | Required |
-| ----------------- | --------- | -------- |
-| ContactGUID       | Guid      | yes      |
-| ContactCreated    | DateTime  | yes      |
-| ContactFirstName  | string    | no       |
-| ContactLastName   | string    | no       |
-| ContactEmail      | string    | no       |
-| ContactAddress1	| string	| no	   |
-| ContactMiddleName | string    | no       |
-
-In the CSV file, define the first row as a header containing the names of the individual columns.
-Header validation is performed during the file upload. See example file [Contact Sample](https://github.com/Kentico/xperience-by-kentico-contacts-importer/blob/main/data/contact_sample.csv).
+## Full Instructions
 
-> [!IMPORTANT]  
-> For correct functionality, please make sure to add a newline at the end of the CSV file.
+View the [Usage Guide](./docs/Usage-Guide.md) for more detailed instructions.
 
 ## Contributing
 

docs/Usage-Guide.md

@@ -0,0 +1,45 @@
+# Usage Guide
+
+## Screenshot
+
+![Import page](../images/screenshot.png)
+
+## Importing and deleting contacts
+
+1. Open **Digital marketing > Contact importer** application
+
+    ![App tile](../images/app-tile.png)
+
+1. Upload your CSV file. See [Supported CSV columns](#supported-csv-columns) for help with formatting the data
+1. In the **Import mode** field, choose the import mode:
+    - Insert: Imports new contacts while skipping existing contacts with matching ContactGUIDs from the CSV file
+    - Delete: Deletes existing contacts using the ContactGUIDs from the CSV file
+1. If you would like to assign newly-imported contacts _and_ existing contacts to a contact group, select the group from the **Assign to contact group** dropdown. You may leave this option empty if you don't wish to assign the contacts to a group
+1. The **Delimiter** field can generally be skipped as the default character `,` is most common. Change this value if your CSV file uses a different character- common examples are `;` or `\\t`
+1. Customize the **Batch size** as needed. For instances with limited resources this value should not exeed 5000. A batch size lower than 100 is not recommended
+1. Click **Run import** to begin the process. Degraded application performance is expected during import
+
+> [!CAUTION]
+> During the import process, do not:
+>
+> - Close the window
+> - Shut down the application
+> - Modify the CSV file
+
+## Supported CSV columns
+
+| Column            | .NET Type | Required |
+| ----------------- | --------- | -------- |
+| ContactGUID       | Guid      | yes      |
+| ContactCreated    | DateTime  | yes      |
+| ContactFirstName  | string    | no       |
+| ContactLastName   | string    | no       |
+| ContactEmail      | string    | no       |
+| ContactAddress1   | string    | no       |
+| ContactMiddleName | string    | no       |
+
+The first row of the CSV file should contain the header names of the individual columns.
+Header validation is performed during the file upload. See the [sample file](https://github.com/Kentico/xperience-by-kentico-contacts-importer/blob/main/data/contact_sample.csv) for an example.
+
+> [!IMPORTANT]  
+> For correct functionality, please make sure to add a newline at the end of the CSV file.

images/ContactImporterApplication.png

@@ -1,2 +1 @@
-// Exposes components from the module. All added components need to be exported.
-export * from './import/ImportLayoutTemplate';
+export * from './templates/ImportLayoutTemplate';

images/app-tile.png

@@ -1,11 +1,41 @@
 {
     "integrations": {
-        "contactsimporter": {
-            "content": {
-                "headlines": {
-                    "main": "Upload/Delete Contacts"
-                }
-            }
+      "contactsimporter": {
+        "messages": {
+          "noFile": "No file was selected.",
+          "errorUploading": "An error occurred while uploading the file.",
+          "headersValidated": "CSV headers validated. Starting import.",
+          "uploadComplete": "File upload complete.",
+          "importComplete": "Import complete.",
+          "sendingFile": "Sending file of length",
+          "errorReading": "An error occurred while reading the file.",
+          "unexpectedFile": "Unexpected file read result type.",
+          "serverError": "Unexpected server error.",
+          "readComplete": "Completed reading file.",
+          "uploadPaused": "Pausing upload while contacts are imported."
+        },
+        "content": {
+          "headlines": {
+            "main": "Import contacts"
+          },
+          "labels": {
+            "importMode": "Import mode",
+            "insert": "Insert",
+            "delete": "Delete",
+            "contactGroup": "Assign to contact group",
+            "uploadFileLine1": "Drag & drop CSV",
+            "uploadFileLine2": "or",
+            "uploadButton": "Browse",
+            "delimiter": "Delimiter",
+            "batchSize": "Batch size",
+            "run": "Run import"
+          },
+          "explanations": {
+            "contactGroup": "Assigns all contacts in CSV file to the selected group. Leave empty to skip assignment.",
+            "delimiter": "The delimiter for CSV row data items.",
+            "batchSize": "The number of records that will be uploaded and processed at a time."
+          }
         }
+      }
     }
 }