WF-116: Bulk User Import

Workflow ID: WF-116 Category: User Management Priority: P1 Last Updated: January 11, 2026

---

Overview

This workflow handles bulk user import via CSV upload, including validation, team assignment, batch invitation sending, and progress tracking.

---

Trigger Events

• Admin uploads CSV file
• HR system integration sync
• Organization onboarding
• Team expansion

---

Sequence Diagram

---

Process Steps

1. CSV File Preparation

Required Format:

email,first_name,last_name,team,role
john@example.com,John,Doe,Engineering,member
jane@example.com,Jane,Smith,Sales,admin
bob@example.com,Bob,Wilson,Marketing,member

Required Columns:

Column	Type	Required	Description
email	string	Yes	Valid email address
first_name	string	Yes	User's first name
last_name	string	Yes	User's last name
team	string	No	Team name or ID
role	string	No	Role (member/admin)

Optional Columns:

Column	Type	Description
department	string	Department name
title	string	Job title
manager_email	string	Manager's email
start_date	date	Access start date
expiry_date	date	Access expiry date
license_type	string	License tier

2. Validation

Validation Rules:

Check	Rule	Action if Failed
Email format	RFC 5321 compliant	Mark row as error
Email uniqueness	Not already in system	Mark as duplicate
Team exists	Team name must exist	Create or error
Role valid	member/admin only	Default to member
CSV format	Proper escaping	Parse error
File size	Max 10MB / 10,000 rows	Reject file

Validation Response:

{
  "file_name": "users.csv",
  "total_rows": 150,
  "valid_rows": 145,
  "error_rows": 5,
  "duplicate_rows": 3,
  "errors": [
    {"row": 12, "column": "email", "error": "Invalid email format"},
    {"row": 45, "column": "team", "error": "Team 'Unknown' not found"},
    {"row": 78, "column": "email", "error": "Duplicate email in file"}
  ],
  "warnings": [
    {"row": 23, "column": "role", "warning": "Unknown role, defaulting to 'member'"}
  ],
  "can_proceed": true
}

3. Preview & Confirmation

Import Preview:

Metric	Value
Users to create	145
Teams affected	5
Invitations to send	145
License seats required	145
Seats available	200

Admin Options:

• Send invitations immediately
• Schedule invitations for date
• Skip duplicate emails
• Auto-create missing teams
• Set default role for missing

4. Batch Processing

Queue Processing:

Total: 145 users
├── Batch 1: 50 users (in progress)
├── Batch 2: 50 users (queued)
└── Batch 3: 45 users (queued)

Progress: 32/145 (22%)
├── Created: 30
├── Invited: 28
└── Errors: 2

Processing Order:

1. Create user record (status: pending)
2. Assign to team
3. Apply role/permissions
4. Send invitation email
5. Update status to invited

5. Invitation Sending

Batch Email Settings:

Setting	Default	Configurable
Rate limit	10/second	Yes
Retry attempts	3	Yes
Retry delay	60 seconds	Yes
Expiry period	7 days	Yes

Invitation Email:

Subject: You're invited to join [Organization] on CODITECT

Hi [First Name],

[Admin Name] has invited you to join [Team Name].

Accept your invitation: [INVITATION_URL]

This link expires in 7 days.

6. Progress Tracking

Real-Time Dashboard:

Status	Count	Percentage
Queued	50	34%
Processing	5	3%
Invited	85	59%
Failed	5	3%
Total	145	100%

Status Updates:

• WebSocket for real-time updates
• Polling fallback every 5 seconds
• Email summary when complete

---

API Endpoints

Endpoint	Method	Purpose
/api/v1/users/bulk-import	POST	Upload and validate CSV
/api/v1/users/bulk-import/preview	GET	Get import preview
/api/v1/users/bulk-import/confirm	POST	Confirm and execute
/api/v1/users/bulk-import/status	GET	Get progress status
/api/v1/users/bulk-import/cancel	POST	Cancel in-progress import

Request: Upload CSV

POST /api/v1/users/bulk-import
Content-Type: multipart/form-data

file: users.csv
options: {
  "skip_duplicates": true,
  "auto_create_teams": false,
  "default_role": "member",
  "send_invitations": true
}

Response: Validation Result

{
  "import_id": "imp_123",
  "status": "validated",
  "summary": {
    "total": 150,
    "valid": 145,
    "errors": 5,
    "duplicates": 3
  },
  "preview_url": "/api/v1/users/bulk-import/imp_123/preview",
  "expires_at": "2026-01-11T13:00:00Z"
}

Request: Confirm Import

POST /api/v1/users/bulk-import/imp_123/confirm
{
  "schedule": "immediate",
  "skip_errors": true,
  "notification_email": "admin@example.com"
}

---

CSV Template

Download template: /api/v1/users/bulk-import/template

# CODITECT Bulk User Import Template
# Required: email, first_name, last_name
# Optional: team, role, department, title

email,first_name,last_name,team,role,department,title
user@example.com,First,Last,TeamName,member,Engineering,Developer

---

Error Handling

Error	Cause	Resolution
FILE_TOO_LARGE	Exceeds 10MB	Split into smaller files
INVALID_FORMAT	Malformed CSV	Check CSV escaping
SEAT_LIMIT	Not enough licenses	Purchase more seats
RATE_LIMITED	Too many imports	Wait and retry
PARTIAL_FAILURE	Some users failed	Review error report

---

Audit Events

Event	Logged
bulk_import.started	Admin, File name, Row count
bulk_import.validated	Valid/Error counts
bulk_import.confirmed	Options selected
bulk_import.user_created	User ID, Email
bulk_import.invitation_sent	User ID, Email
bulk_import.completed	Success/Fail counts
bulk_import.cancelled	Admin, Reason

---

Related Workflows

• WF-114: Multi-OpUnit Access Assignment
• WF-115: Team Deletion/Archival
• WF-003: Team Invitation

---

Last Updated: January 11, 2026