Bulk Import

A complete guide on how to use the bulk import feature in Care

Overview

The Case Import Tool in CS Care is a sophisticated feature that allows administrators to bulk import case data from CSV files into the system. It uses a multi-step wizard interface to guide users through uploading, mapping, configuring, and importing case data with extensive validation and error handling.

🎯 Purpose & Use Cases

The Case Import Tool is designed for:

• Initial data migration from legacy systems to CS Care

• Bulk case creation from external data sources

• Periodic data synchronization with partner systems

• Updating existing cases with new information

📋 Step-by-Step Workflow

The import process follows a 4-step wizard:

Step 1: Upload CSV 📤

What happens:

• User selects and uploads a CSV file

• System parses the CSV and extracts headers

• CSV data is loaded into memory for preview

Technical Details:

• File is parsed using the csv-parse library

• System removes BOM (Byte Order Mark) if present

• All CSV headers become available for mapping

Best Practices:

• Ensure CSV is properly formatted with headers in the first row

• Use UTF-8 encoding

• Remove any special characters that might cause parsing issues

Step 2: Map Survey Fields 🗺️

Need to know which fields can be imported? Check out Allowable Fields

This is the most critical step where you map CSV columns to case form fields.

Key Features:

A. Two-Tab Interface:

• Demographic Survey Tab: Map personal information fields

• Intake Survey Tab: Map case-specific intake fields

B. Automatic Field Mapping: The system intelligently auto-maps fields based on:

• Exact header name matches with field paths or labels

• Value pattern recognition for select/dropdown fields

• Uses normalization to match similar names (case-insensitive, removes spaces/special characters)

C. Field Mapping Options:

For each CSV column, you can configure:

1. Simple Text Fields:

   • Direct mapping: csvField → formField

2. Select/Dropdown Fields:

   • Option Mappings: Map multiple CSV values to a single dropdown option

   • Fallback Option: Choose what to do with unmapped values

     • __KEEP_ORIGINAL__: Keep the original CSV value

     • Or select a specific dropdown option as default

3. Date Fields:

   • Specify date format for proper parsing

   • Supported formats: MM/DD/YYYY, YYYY-MM-DD, etc.

Search Functionality:

• Real-time search to filter CSV headers

• Makes it easy to find specific fields in large CSVs

Step 3: Import Settings ⚙️

Configure how the import should behave:

A. Source Name

• Purpose: Label for this import job (for tracking/reporting)

• Default: Auto-generated with date/time

• Example: "Import 10/24/2025_1430"

B. Case Code Field

• Purpose: CSV column containing unique case identifiers

• Usage: Required for updates, helps identify existing cases

C. Import Mode 🔄

Three modes available:

1. Create Only (CaseImportMode.Create)

   • Always creates new cases

   • Ignores existing case checks

   • Fastest import mode

2. Update Only (CaseImportMode.Update)

   • Only updates existing cases

   • Requires identifier attributes

   • Fails if case not found

3. Create or Update (CaseImportMode.CreateOrUpdate)

   • Checks if case exists first

   • Creates if not found, updates if found

   • Most flexible but slightly slower

D. Case Attributes

Define custom metadata to attach to cases:

interface ICaseAttributeMapping {
  csvField: string;        // Column in CSV
  attributeName: string;   // Name of the attribute
  isIdentifier: boolean;   // Use to find existing cases?
}

Example:

• CSV Field: external_id

• Attribute Name: legacy_system_id

• Is Identifier: true ✅

Identifiers:

• Used to locate existing cases during updates

• Can have multiple identifiers

• Checked in order until match is found

E. Status Field

• CSV column containing case status information

• Must map to valid project statuses

---

Step 4: Review 👀

Final verification before import starts:

Summary Display:

CSV Data:

• Total Records: Count of rows to import

• Total Fields: Number of CSV columns

• Mapped Fields: Successfully mapped columns

• Unmapped Fields: Columns that will be skipped

Import Settings:

• Source name

• Case code field

• Import mode

• Status field configuration

Case Attributes:

• List of all configured attributes

• Identifier status highlighted

Warnings:

• ⚠️ Unmapped Fields Warning: Lists any CSV columns that won't be imported

• Prevents accidental data loss

Submission:

• Click "Start Import" to queue the job

• Shows loading spinner during submission

• Displays success confirmation when queued

📝 Summary

The Case Import Tool is a powerful, user-friendly solution for bulk case management in CS Care. Its wizard-based interface, intelligent auto-mapping, flexible configuration options, and robust error handling make it suitable for everything from simple data loads to complex migration scenarios.

Key Strengths:

• ✅ Intuitive 4-step wizard

• ✅ Intelligent field auto-mapping

• ✅ Flexible create/update modes

• ✅ Comprehensive validation

• ✅ Asynchronous processing for large imports

• ✅ Real-time progress monitoring

• ✅ Detailed error tracking per row

By following the best practices and understanding each step, administrators can efficiently import thousands of cases while maintaining data integrity and minimizing errors.

---