CSV Import Guide

This guide will help you import tasks from CSV files into Taskee with flexible column mapping and configuration options.

Table of Contents

1. Overview
2. Quick Start
3. CSV Format Requirements
4. Configuration Options
5. Column Mapping
6. Advanced Usage
7. Examples
8. Troubleshooting

---

Overview

The CSV import adapter allows you to:

• Import tasks from any CSV file format
• Configure delimiters, quotes, and encoding
• Map CSV columns to task fields
• Handle custom fields automatically
• Import large datasets efficiently

---

Quick Start

Basic Import Process

1. Navigate to your project in Taskee
2. Go to the Import section
3. Select CSV Import
4. Upload your CSV file
5. Configure settings (delimiter, headers, etc.)
6. Map columns to task fields
7. Preview the import
8. Confirm and import

---

CSV Format Requirements

Minimum Requirements

Your CSV file must have at least:

• One column for task title/name
• At least one row of data

That's it! Everything else is flexible.

Recommended Structure

For best results, include these columns:

Encoding Support

Supported encodings:

• UTF-8 (recommended)
• UTF-16
• ISO-8859-1 (Latin-1)
• Windows-1252

💡 Tip: If you have special characters (emojis, accents, etc.), use UTF-8.

---

Configuration Options

Delimiter

The character that separates columns.

Common options:

• , (comma) - Most common, default
• ; (semicolon) - Common in European locales
• \t (tab) - For TSV files
• | (pipe) - For pipe-separated files

Example:

Title,Status,Priority
Task 1,Open,High

Quote Character

Character used to wrap field values containing special characters.

Default: " (double quote)

Example:

Title,Description,Status
"Task with, comma","Description with ""quotes""",Open

Escape Character

Character used to escape special characters within quoted fields.

Default: " (double quote)

Common patterns:

• "" (double quote) - Excel/RFC 4180 standard
• \" (backslash) - Programming style

Has Header Row

Whether the first row contains column names.

Options:

• true - First row is headers (recommended)
• false - All rows are data, columns will be named "column1", "column2", etc.

---

Column Mapping

Map your CSV columns to Taskee's task fields.

Standard Field Mappings

Labels Format

Labels can be in your CSV in several formats:

• Comma-separated: bug, urgent, backend
• Semicolon-separated: bug; urgent; backend
• Pipe-separated: bug|urgent|backend

The importer will automatically detect and parse these formats.

Custom Fields

Any columns that aren't mapped to standard fields will be imported as custom fields in the task metadata.

Example: If your CSV has columns like "Story Points", "Sprint", or "Epic", these will be preserved in the task's metadata.

---

Advanced Usage

API-Based Import

For programmatic imports, use the CSV import API:

Step 1: Parse CSV

POST /api/adapters/csv/parse
Content-Type: multipart/form-data

file: <your-csv-file>
delimiter: ","
quote: "\""
escape: "\""
encoding: "utf-8"
hasHeader: "true"

Response:

{
  "columns": ["Title", "Description", "Status", "Priority"],
  "preview": [
    { "Title": "Task 1", "Description": "...", "Status": "Open", "Priority": "High" },
    { "Title": "Task 2", "Description": "...", "Status": "Done", "Priority": "Low" }
  ],
  "totalRows": 150
}

Step 2: Import with Mapping

POST /api/adapters/csv/import
Content-Type: application/json

{
  "projectId": "your-project-id",
  "csvContent": "<csv-file-content>",
  "delimiter": ",",
  "quote": "\"",
  "hasHeader": true,
  "columnMapping": {
    "title": "Title",
    "description": "Description",
    "status": "Status",
    "priority": "Priority",
    "assignee": "Assignee",
    "labels": "Tags"
  }
}

Response:

{
  "success": true,
  "imported": 150,
  "total": 150
}

Batch Import

The importer processes large files in batches of 100 rows to prevent timeouts and memory issues.

Recommended limits:

• Up to 10,000 rows: No issues
• 10,000 - 50,000 rows: May take a few minutes
• Over 50,000 rows: Consider splitting into multiple files

---

Examples

Example 1: Simple Task List

CSV File (tasks.csv):

Title,Status,Priority
Implement login page,To Do,High
Add user profile,In Progress,Medium
Fix navigation bug,Done,Low

Column Mapping:

{
  "title": "Title",
  "status": "Status",
  "priority": "Priority"
}

Example 2: Jira Export

CSV File (jira-export.csv):

Issue Key,Summary,Description,Status,Priority,Assignee,Labels,Created,Updated
PROJ-123,User Login,"Add OAuth support",In Progress,High,john@example.com,"auth,feature",2024-01-15,2024-01-20
PROJ-124,Bug Fix,"Fix login error",Done,Critical,jane@example.com,"bug,urgent",2024-01-16,2024-01-18

Column Mapping:

{
  "externalId": "Issue Key",
  "title": "Summary",
  "description": "Description",
  "status": "Status",
  "priority": "Priority",
  "assignee": "Assignee",
  "labels": "Labels",
  "createdAt": "Created",
  "updatedAt": "Updated"
}

Example 3: Excel Export (Semicolon Delimiter)

CSV File (tasks-excel.csv):

Task Name;Description;State;Importance
"Login feature";"OAuth integration";"Active";"High"
"Bug fix";"Navigation issue";"Completed";"Low"

Configuration:

{
  "delimiter": ";",
  "quote": "\"",
  "hasHeader": true
}

Column Mapping:

{
  "title": "Task Name",
  "description": "Description",
  "status": "State",
  "priority": "Importance"
}

Example 4: Custom Fields

CSV File (tasks-with-custom.csv):

Title,Status,Story Points,Sprint,Epic,Team
Login Page,To Do,5,Sprint 1,Authentication,Frontend
API Endpoint,In Progress,8,Sprint 1,Authentication,Backend

Column Mapping:

{
  "title": "Title",
  "status": "Status"
}

Result: "Story Points", "Sprint", "Epic", and "Team" will be stored as custom fields.

---

Date Formats

The importer supports multiple date formats:

Supported Formats

• ISO 8601: 2024-01-15T10:30:00Z or 2024-01-15
• US Format: 01/15/2024 or 1/15/24
• European Format: 15-01-2024 or 15.01.2024
• Text Format: January 15, 2024

💡 Tip: ISO 8601 format (YYYY-MM-DD) is the most reliable.

---

Troubleshooting

Issue: "CSV file is empty"

Cause: The uploaded file has no content or only has headers.

Solution:

• Ensure the file has at least one data row
• Check the file isn't corrupted

Issue: "Row X has Y columns, expected Z columns"

Cause: Inconsistent number of columns in rows.

Solution:

• Check for missing or extra commas/delimiters
• Ensure all values with commas are properly quoted
• Use a CSV validator to check your file

Issue: "Could not parse date: [date]"

Cause: Date format not recognized.

Solution:

• Use ISO 8601 format (YYYY-MM-DD)
• Convert dates to a standard format before import
• Leave the date field empty to use import time

Issue: "Import timeout"

Cause: File too large or server timeout.

Solution:

• Split large files into smaller chunks (< 5000 rows each)
• Import during off-peak hours
• Contact support for bulk import assistance

Issue: "Encoding errors / strange characters"

Cause: File encoding doesn't match configuration.

Solution:

• Save your CSV as UTF-8 encoding
• Try different encoding settings
• Open in a text editor to check actual encoding

Issue: "Missing required column mapping"

Cause: Title field not mapped.

Solution:

• Ensure you map at least the title field
• Check column names match exactly (case-sensitive)

---

Best Practices

1. Prepare Your Data

• Clean your data before import
• Remove empty rows at the end
• Standardize formats (dates, status values, etc.)
• Check for special characters in text fields

2. Test First

• Import a small sample (5-10 rows) first
• Verify the mapping is correct
• Check imported data in Taskee
• Then import the full dataset

3. Backup Your Data

• Keep the original CSV file
• Export your project before large imports
• Test with a copy of your project first

4. Optimize for Performance

• Remove unnecessary columns before import
• Split large files (> 10,000 rows)
• Use simple date formats
• Avoid complex HTML in descriptions

---

Limitations

Current limitations:

• ❌ No sync-back support: CSV import is one-way only
• ❌ No subtasks: Subtasks not supported via CSV import
• ❌ No attachments: File attachments cannot be imported
• ❌ No relationships: Task dependencies/links not supported
• ⚠️ File size: Recommended max 10MB per file

---

Template CSV Files

Basic Template

Title,Description,Status,Priority,Assignee,Labels
"Example Task 1","This is a description","To Do","High","john@example.com","feature,important"
"Example Task 2","Another description","In Progress","Medium","jane@example.com","bug"

Download basic template

Advanced Template

Title,Description,Status,Priority,Assignee,Labels,Story Points,Sprint,Created,Updated
"User Authentication","Implement OAuth 2.0","In Progress","High","dev@example.com","feature,auth",8,"Sprint 1","2024-01-15","2024-01-20"
"Dashboard Layout","Create responsive dashboard","To Do","Medium","designer@example.com","ui,feature",5,"Sprint 1","2024-01-16","2024-01-16"

Download advanced template

---

Additional Resources

• RFC 4180 - CSV Format Specification
• CSV Lint - Online CSV Validator
• Excel CSV Export Guide

---

Support

If you need help:

1. Check this guide and examples
2. Validate your CSV file format
3. Try with a smaller sample file first
4. Contact support with your CSV file and error message

---

Last Updated: November 2024