CSV Import

What is CSV Import?

• bulk load: Bring tasks in from spreadsheets quickly.
• smart mapping: Auto‑detects common headers; you can adjust mappings.
• validation & fixes: See errors/warnings with guided quick‑fixes before importing.
• hierarchy & links: Detects levels and predecessor relationships.

How to Import CSV

Step 1: Open Import Dialog

1. Click "Tools" in the toolbar
2. Select "Import Tasks"
3. The Import CSV dialog opens

Step 2: Upload or Paste CSV

Option A: Upload file

• Click "Choose CSV File…"
• Select your .csv file
• Content loads and parsing starts

Option B: Paste content

• Copy CSV data from your spreadsheet
• Paste into the text area
• Validation begins immediately

Download template: Click "Download Template" for a sample CSV and format guide

Step 3: Review mapping (if needed)

If headers differ from our schema, you’ll see a mapping step with confidence levels. Map each CSV column to a target field. Required: name (Task Name).

Typical mappings:

• "Task Name" → name
• "Start Date" → startDate
• "Duration (workdays)" → durationDays
• "Finish Date" → finishDate
• "Predecessors" → predecessorExternalIds
• "Deliverable (Y/N)" → isDeliverable
• "% Complete" → percentComplete
• "Status" → status
• "Owner" → owner
• "Notes" → notes
• "Level" → level

Step 4: Preview & validation

You’ll see:

• summary: totals for valid, warnings, errors
• quick fixes: Apply suggested auto‑fixes
• issue list: Row‑by‑row messages with field and suggestions

Common quick fixes include:

• Normalize dates (e.g., convert 10/21/2025 → 2025-10-21)
• Normalize status (Todo → Not Started)
• Normalize duration (10d → 10)
• Boolean coercion (Yes/True/1 → true)

Step 5: Choose placement

Select how to import tasks:

Append: Add new tasks after existing tasks

• Keeps all current tasks
• New tasks are added after the existing list

Replace: Delete all existing tasks and import only the CSV data

• Permanent action if you confirm

Step 6: Complete import

Click the import button. Tasks are created, dependencies linked, and the dialog closes.

CSV format

Required fields

• Task Name (name)

Optional fields

All other fields are optional but recommended:

Date formatting

Supported formats:

• YYYY-MM-DD (recommended)
• MM/DD/YYYY
• ISO dates like 2025-10-21T08:00:00Z

Validation:

• Dates are normalized to YYYY-MM-DD
• Weekend alignment happens during scheduling, not in the CSV
• Invalid/unparseable dates are flagged

Duration formatting

Supported formats:

• Whole numbers: 5
• With suffix: 10d, 2 days
• Decimals: 5.5

Business day rules:

• Weekends (Saturday, Sunday) are excluded
• Duration 1 = same‑day task

Hierarchy detection

Plan Builder detects hierarchy using multiple signals:

Method 1: WBS codes in ID

ID: 1       → Level 0
ID: 1.1     → Level 1
ID: 1.2     → Level 1
ID: 1.2.1   → Level 2

Method 2: Indented task names

Task Name: Project Phase 1        → Level 0
Task Name:   Requirements         → Level 1 (indented)
Task Name:     User Stories       → Level 2 (double‑indented)

Method 3: Explicit Level column

Level: 0  → Top‑level task
Level: 1  → Subtask
Level: 2  → Nested subtask

Conflicts: Explicit level overrides other signals.

Dependency formatting

Format: Comma/semicolon/space‑separated list of task IDs

• 1 depends on task 1
• 1,2 depends on tasks 1 and 2
• 1,2,5 depends on tasks 1, 2, and 5

Validation:

• All referenced IDs must exist in the file
• No circular or self‑dependencies

Validation and errors

Validation Rules

Date validation:

• Provide at least 2 of: Start Date, Finish Date, Duration (or provide one and we infer with business‑day rules)
• Finish date must be after start date when both are provided
• Dates must be parseable

Dependency validation:

• Predecessor IDs must reference existing tasks in the same file
• No circular or self‑dependencies

Milestone rules:

• Milestones should have durationDays = 0; start and finish align to the same business day

Required:

• Task Name (name) cannot be empty

Error Types

Errors (block import):

• Missing required fields
• Invalid/unparseable dates
• Circular dependencies
• Predecessor references to non‑existent tasks

Warnings (can import):

• Missing optional fields
• Ambiguous hierarchy signals

Auto‑fixes

Common auto‑fixes include:

• Date normalization: Convert MM/DD/YYYY or ISO to YYYY-MM-DD
• Duration normalization: Convert 10d to 10
• Status normalization: Convert Todo to Not Started
• Boolean normalization: Coerce Yes/True/1 to true

Import workflow example

Sample CSV

ID,task name,duration,start,finish,predecessors,% complete,status
1,Project Kickoff,0,2025-10-20,2025-10-20,,0,Not Started
2,Requirements Gathering,5,2025-10-21,2025-10-27,1,0,Not Started
3,Design Phase,10,2025-10-28,2025-11-10,2,0,Not Started
4,Implementation,15,2025-11-11,2025-12-03,3,0,Not Started
5,Testing & QA,10,2025-12-04,2025-12-19,4,0,Not Started
6,Go-Live,0,2025-12-20,2025-12-20,5,0,Not Started

Import steps

1. Upload CSV: File loads, validation runs
2. Review Stats: 6 rows, 6 valid, 0 errors
3. No Mapping Needed: All fields recognized
4. No Auto-Fixes: All data valid
5. Choose Append: Add tasks after existing
6. Preview: See task list will be:
   • Existing tasks (1-10)
   • New tasks (11-16)
7. Import: Click "Import 6 Tasks"
8. Done: Tasks appear in plan

Tips & best practices

Preparing your CSV

• Use the template: Download template to ensure correct format
• Test with small file: Import 5-10 rows first to verify format
• Standardize dates: Use YYYY-MM-DD format consistently
• Check dependencies: Ensure predecessor IDs exist in file
• Validate hierarchy: Use consistent WBS codes or indentation

Importing large files

• Break into chunks: Import phases separately (100-200 tasks at a time)
• Validate locally: Fix issues in spreadsheet before importing
• Use auto-fixes: Apply suggested corrections to speed import
• Review warnings: Address warnings before re-importing

Handling errors

• Read error messages: Each error explains what's wrong
• Check row numbers: Errors reference specific CSV rows
• Fix in CSV: Correct issues in your file, then re-import
• Contact support: If errors persist, export current plan to compare

Import best practices

• Backup first: Export current plan before importing
• Append mode: Use Append instead of Replace when possible
• Verify hierarchy: Check parent-child relationships after import
• Test dependencies: Verify predecessor links work correctly

Troubleshooting

Import failed with "Invalid date format"

Answer: Ensure dates are in YYYY-MM-DD or MM/DD/YYYY format. See the Date formatting section above.

Predecessor references don't work

Answer: Predecessor IDs must match task IDs exactly. Check for extra spaces or mismatched ID formats.

Hierarchy not preserved

Answer: Use consistent WBS codes in the ID column, or add an explicit Level column (0, 1, 2).

Can I import partial data?

Answer: Yes. Provide at least Task Name. Start, Finish, and Duration are optional.

Can I import subtasks?

Answer: Yes. Use WBS codes (1.1, 1.2) or an explicit Level column (0, 1, 2).

What if I import duplicate IDs?

Answer: Duplicate IDs are auto‑generated to ensure uniqueness. Original IDs are preserved in the externalId field.

Last updated: 2025-10-24