Bulk Import

Quickly add large numbers of acronyms to your workspace using CSV files. This guide covers CSV format, deduplication, preview mode, and streaming import.

Accessing Bulk Import

1. From the main navigation, click Admin → Import
2. Or navigate directly to /admin/import

Before You Start

Bulk import is designed for:

• Migrating from another system: Existing acronym database
• Bootstrapping: Initial population of a new workspace
• Batch updates: Adding 50+ items at once
• Seasonal uploads: Periodic additions (e.g., quarterly planning terms)

Not recommended for:

• Individual additions (use manual form instead)
• Frequent small batches (consider API instead)
• Complex transformations (prepare data in advance)

CSV Format

Prepare your data in CSV format with these columns:

Required Columns

Optional Columns

Complete Example

term,title,description,categories,tags,sentiment
API,Application Programming Interface,A set of rules for software communication,Engineering;Technology,web;protocol,Neutral
OKR,Objectives and Key Results,Goal-setting framework for team alignment,Product;Management,goals;planning,Positive
SQL,Structured Query Language,Database query language,Engineering;Data,database;query,Neutral

CSV Preparation

Column Headers

Your CSV must include headers in the first row. Required header: term

term,title,description,categories
API,Application Programming Interface,...

Data Format Rules

• Term: Required; alphanumeric (spaces, hyphens allowed)
• Title: Optional; becomes expansion if provided
• Description: Optional; up to 1000 characters (falls back to title if empty)
• Categories: Comma or semicolon separated; case-insensitive matching against existing categories; auto-creates new ones if not found
• Tags: Comma or semicolon separated; auto-creates new tags
• Sentiment: One of: Positive, Neutral, Negative (defaults to Neutral if not provided)

Handling Special Characters

• Commas in fields: Wrap in quotes: "API, REST, or JSON"
• Quotes in fields: Double quotes: API "calls"
• Line breaks: Use \n or avoid (keep descriptions single-line)
• Newlines: Use standard CSV escaping:

  term,description
  API,"A protocol enabling communication
  between software components"

File Size & Row Limits

• File Size: Up to 50 MB
• Row Limit: Maximum 5,000 rows per import
• Larger imports: System rejects files exceeding limit with message: "Please split this file into smaller batches (max 5,000 rows)"
• Workaround: Create multiple CSVs and import sequentially

Uploading Your File

Step 1: Select File

1. Click Choose File or drag-and-drop a CSV
2. System validates:
   • File format (CSV required)
   • Column headers present
   • Row count (≤5,000)
3. If validation passes: Move to Step 2 (Preview)
4. If validation fails: Error message explains issue

Step 2: Preview Changes

Before importing, review what will be added or updated:

1. System scans for existing acronyms (case-insensitive term matching)

2. Displays preview:

   • New: Acronyms not in workspace (will be created)
   • Updated: Existing acronyms (will be updated if content differs)
   • Unchanged: Existing acronyms (exact match to import; will be skipped)
   • Categories: Which categories will be created vs. linked

3. Review the preview table:

Step 3: Deduplication Settings

Configure how updates are handled:

Default: updateExisting = true

• Matching: Case-insensitive term matching
• Behavior: If term exists in workspace:
  • Compares CSV data to database
  • Updates if different (new or changed content)
  • Skips if identical (no changes needed)
• Benefits: Safe re-importing; duplicates prevented; can run repeatedly

Alternative: updateExisting = false

• Behavior: If term exists, create new definition (don't update)
• Result: Acronym may have multiple definitions
• Use case: Adding alternative definitions to existing terms

Step 4: Category Handling

Categories in your CSV are processed as follows:

Matching:

• Case-insensitive match against existing categories
• "engineering" matches "Engineering" (if exists)
• Multiple categories per row: comma or semicolon separated

Auto-Creation:

• If category doesn't exist, it's created automatically
• New categories are assigned a color from the palette
• New categories are checked for profanity

Example:

• CSV has categories: "Engineering, New Security Team, Data"
• "Engineering" exists → linked
• "New Security Team" doesn't exist → created with auto-assigned color
• "Data" exists → linked

Import Progress

When you start the import:

Real-Time Progress Tracking

1. Click Start Import
2. A progress bar updates as rows are processed
3. You'll see:
   • Current row being processed
   • Total rows to process
   • Live status for each item (created, updated, or skipped)

Import Status

Each row processed shows:

• Created: New acronym added to workspace
• Updated: Existing acronym modified
• Skipped: Acronym unchanged (no import needed)
• Error: Issue with row (validation failed, profanity detected, etc.)

Estimated Duration

• Speed: ~10-20 rows per second
• 1,000 rows: ~50-100 seconds
• 5,000 rows: ~4-8 minutes

Large imports may take several minutes. Do not close the browser tab during import.

Soft-Deleted Acronyms & Restore

If an acronym was previously soft-deleted (moved to trash):

Behavior on Import

Case 1: updateExisting = true

• Detection: System finds soft-deleted acronym with matching term
• Action: Clears deleted_at timestamp, restores acronym
• Result: Acronym returns to active workspace
• No UNIQUE violation: Soft-deleted rows don't block imports

Case 2: updateExisting = false

• Action: Creates new definition (doesn't restore)
• Result: Acronym has multiple definitions (including restored)

Example

1. Workspace has: "API" (soft-deleted, term matches)
2. CSV import: "API" with description "Application Programming Interface"
3. Import result: "API" restored, description updated
4. No duplicate acronym created

This feature enables safe re-importing and safe recovery of accidentally deleted items.

Empty Descriptions

When a description field is empty or missing:

Fallback Logic

• If title provided: Description uses title value
• If neither provided: Description is empty (optional field)
• Fallback operator: Uses || operator (not ??), so empty strings treated as falsy

Example:

Import Validation

System validates data before import:

Pre-Import Validation

• CSV format: Valid UTF-8, proper escaping
• Headers: Required "term" column present
• Row count: ≤5,000 rows
• Duplicate terms: Warns if CSV has duplicate terms (first wins)
• Reserved terms: Cannot import system-reserved acronyms

Per-Row Validation

• Term format: Alphanumeric validation
• Description length: Max 1000 characters
• Category names: Alphanumeric, length limits
• Profanity: Description, title, and category names checked; flagged rows show warning
• Encoding: Non-UTF-8 characters replaced or rejected

Error Handling

If validation fails:

• CSV file: Error in file format (e.g., invalid UTF-8)
  • Message: "Invalid CSV format"
  • Remediation: Re-save file as UTF-8
• Rows: Individual row errors show in preview
  • Message: "Row 5: Description exceeds 1000 character limit"
  • Remediation: Edit row or skip

Profanity Filtering

All imported text is checked for inappropriate language:

Content Checking

The system checks for:

• Profanity and offensive terms
• Common evasion techniques (slang, symbols)
• Custom blocklists (enterprise feature)

Flagged Rows

Rows with detected profanity:

• Status: Marked as "Flagged" (not rejected by default)
• Warning: Visible in preview with explanation
• Override: Admins can confirm and import anyway (with audit trail)
• Custom List: Workspace-specific profanity lists can be configured (enterprise)

Post-Import

After import completes:

What Happens Next

1. Search Indexes: Updated so all new acronyms are searchable
2. Webhooks: Events sent to integrations (if configured)
3. Audit Log: Import recorded with row count and status
4. Activity Feed: Shows "Bulk Import" activity on the dashboard

Import Summary

View import results:

• Created: Count of new acronyms
• Updated: Count of modified acronyms
• Skipped: Count of unchanged acronyms
• Errors: Count of rows with issues
• New Categories: Count of auto-created categories
• Duration: Total import time

Undo Import

To reverse an import:

• Option 1: Soft-delete all newly created acronyms (manual or bulk delete)
• Option 2: Contact support for database rollback (if within 24 hours)
• No built-in undo: Plan carefully before large imports

Preview Endpoint

For programmatic import preparation:

POST /api/internal/admin/bulk-import/preview
Content-Type: application/json

{
  "rows": [
    {
      "term": "API",
      "title": "Application Programming Interface",
      "categories": "Engineering,Technology"
    }
  ]
}

Response:

{
  "preview": [
    {
      "term": "API",
      "action": "new",
      "categories": [
        {"name": "Engineering", "exists": true},
        {"name": "Technology", "exists": false}
      ]
    }
  ]
}

Use this to build custom UI or pre-validate before import.

Bulk Import Endpoint

For programmatic imports:

POST /api/internal/admin/bulk-import
Content-Type: multipart/form-data

{
  "file": <CSV file>,
  "updateExisting": true
}

Response: Real-time progress updates streamed as the import runs.

Best Practices

Before You Import

1. Validate Data: Check for:

   • Duplicate terms (remove before import)
   • Encoding issues (save as UTF-8)
   • Missing required fields (add "term" column)
   • Profanity (use profanity checker tool)

2. Test First: Create test workspace and import subset

3. Backup: Take export of existing workspace before large import

4. Plan Categories: Decide if auto-create or pre-create categories

5. Document Source: Keep import source and date for audit trail

During Import

1. Monitor Progress: Watch streaming response
2. Don't Close Tab: Import must complete
3. Review Errors: If any rows fail, note them for remediation
4. Check Results: Verify created/updated counts match expectations

After Import

1. Spot Check: Randomly select 5-10 imported items to verify
2. Review Categories: Check auto-created categories have correct colors
3. Test Search: Verify acronyms appear in search results
4. Notify Team: Announce newly available acronyms

Handling Large Datasets

• Split into batches: 5,000 rows max, create multiple files
• Sequential imports: Run one after another (can take time)
• Incremental approach: Import core terms first, add specialized ones later
• Monitor performance: Large imports may impact search performance temporarily

Deduplication Strategy

• updateExisting = true: Safe for repeated imports; use for ongoing updates
• updateExisting = false: Use only if you want multiple definitions per acronym
• Case sensitivity: Always case-insensitive matching (term = title comparison)
• Exact matching: Only term and title; description changes always trigger update

Troubleshooting

Import Fails on File Upload

Error: "Invalid CSV format"

Solutions:

• Ensure file is valid CSV (not Excel .xlsx)
• Save as UTF-8 (not ANSI or other encoding)
• Check for proper line breaks (LF or CRLF)
• Verify header row present

Rows Not Importing

Error: "Row validation failed"

Solutions:

• Check for missing "term" column
• Verify no duplicate terms in CSV (first occurrence wins)
• Check for excessive description length (>1000 chars)
• Review profanity warnings

Categories Not Created

Error: "Category creation failed"

Solutions:

• Check category names for invalid characters
• Verify category name not already reserved
• Try manually pre-creating category
• Contact support if issue persists

Import Takes Too Long

Error: "Import still processing after 30 minutes"

Solutions:

• Check browser console for errors
• Verify stable internet connection
• Try with smaller CSV (fewer rows)
• Split into multiple imports

Soft-Deleted Acronyms Not Restored

Error: "Acronym still shows as deleted"

Solutions:

• Verify term matches exactly (case-insensitive)
• Check updateExisting = true (not false)
• Confirm acronym was only soft-deleted (not permanently deleted)
• Manually restore if needed

Import History

View all past imports:

1. Click Import History tab

2. See list of imports with:

   • Date and time
   • User who imported
   • Row count (created, updated, skipped)
   • CSV filename (if available)
   • Status (completed, failed)

3. Click import to view detailed log of each row

Next Steps: Learn about Export to download workspace data, or explore Webhooks to automate import workflows.