Add CSV bulk import utilities for imapsync

[stephdl]

Why
Sysadmins currently have to create email synchronization tasks manually one by one, which is slow and prone to error, especially during large migrations. Making this process easier will save time and reduce mistakes.

Purpose
To streamline migrations when moving to NethServer or similar environments, so sysadmins can handle many tasks quickly with a single step.

Proposed solution
Implement a CSV-based import feature for both user accounts and email synchronization tasks, allowing admins to prepare a CSV file and import all users/tasks in bulk. Scripts and documentation should guide the format and usage, including validation of data before import.

Alternative solutions

• Manual creation of accounts and sync tasks (current method)
• Custom scripts for each migration, resulting in inconsistent and error-prone workflows

Additional context
Related work:

• Add bulk user import functionality from CSV (ns8-imapsync)
• Add CSV import functionality for bulk synchronization tasks (ns8-docs)

This feature will help sysadmins perform smooth, large-scale migrations and onboarding, especially when switching platforms.

See also

• Add bulk user import functionality from CSV ns8-imapsync#63
• Add CSV import functionality for bulk synchronization tasks ns8-docs#207

[stephdl]

QA Test Case: CSV Bulk Import for Email Synchronization Tasks

target is ghcr.io/nethserver/imapsync:1.2.2-dev.1

Test Objective

Verify that the import-csv-tasks utility correctly imports email synchronization tasks from a CSV file in bulk.

Test Steps

Test 1: Valid CSV Import

1. Create a CSV file with valid data:

   localusername,remoteusername,remotepassword,remotehostname,remoteport,security
   user1,user1@example.org,password123,imap.example.org,993,ssl
   user2,user2@example.org,password456,imap.example. org,143,tls
   

2. Run: runagent -m imapsync1 import-csv-tasks < users.csv
3. Expected: All tasks are created successfully; no errors returned

valid data makes the tasks running in the UI, bad data the tasks is created but the tasks cannot run

Test 2: CSV Validation (Check Mode)

1. Use the same CSV file
2. Run: runagent -m imapsync1 import-csv-tasks -c < users.csv
3. Expected: Validation passes without creating any tasks

Information is given about bad data in the csv

Test 3: Missing Required Field

1. Create CSV missing localusername column
2. Run import command
3. Expected: Error indicating missing required column

the row with bad data is not used, the importation must continue

Test 4: Special Characters in Password

1. Create CSV with password containing special characters (quoted): "p@ss! ,word#123"
2. Run import command
3. Expected: Task created with correct password

the row with the deliminator , inside the password is well imported and the task is running

Test 5: Help Command

1. Run: runagent -m imapsync1 import-csv-tasks -h
2. Expected: Help text displays with usage instructions

The help is displayed

Success Criteria

• ✓ Valid CSV imports create all tasks without errors
• ✓ Validation mode checks data integrity without creating tasks
• ✓ Error handling catches invalid data (missing fields)
• ✓ Special characters in passwords are handled correctly
• ✓ Help documentation is accessible and accurate

[mrmarkuz]

All test cases verified