Teamwork CSV Import Guide¶

CMS Planner generates CSV files formatted for direct import into Teamwork. This guide covers the import process, troubleshooting, and best practices.

CSV Format¶

The generated CSV uses Teamwork's standard import format with these columns:

Import Process¶

Step 1: Prepare CSV File¶

The CSV file is generated as [project-name]-backlog-teamwork.csv in your project directory.

Verify the file contains: - ✅ Proper column headers - ✅ Task hierarchy with -, --, --- prefixes - ✅ Story point tags (SP-3, SP-5, SP-13, etc.) - ✅ Phase tags (Phase-1, Phase-2, etc.) - ✅ All tasks have "Active" status

Step 2: Open Teamwork Project¶

1. Log into Teamwork
2. Navigate to your project
3. Go to the Tasks section

Step 3: Import CSV¶

1. Click Options (three dots menu)
2. Select Import Tasks
3. Choose CSV Import
4. Click Choose File and select your CSV
5. Review the import preview

Step 4: Map Columns¶

Teamwork usually auto-detects columns, but verify:

Step 5: Review and Import¶

1. Check the preview of tasks to be imported
2. Verify hierarchy is preserved (parent/child relationships)
3. Confirm story point tags are recognized
4. Click Import Tasks
5. Wait for import to complete

Step 6: Verify Import¶

After import:

1. ✅ Check task lists created correctly
2. ✅ Verify task hierarchy (epics → stories → tasks)
3. ✅ Confirm descriptions imported fully
4. ✅ Check tags created (SP-X, Phase-X)
5. ✅ Verify priorities set correctly
6. ✅ Ensure all tasks are "Active"

Task Hierarchy¶

CMS Planner uses prefixes to create task hierarchy:

Hierarchy Prefixes¶

[EPIC] Feature Name [21 points]          ← Parent task (no prefix)
- [STORY] Sub-feature [8 points]         ← First level child (-)
-- [TASK] Implementation [3 points]      ← Second level child (--)
-- [TASK] Testing [2 points]             ← Second level child (--)
--- [SUBTASK] Unit tests [1 point]       ← Third level child (---)

Teamwork Structure¶

After import, this becomes:

Feature Name [21 points]
  └─ Sub-feature [8 points]
      ├─ Implementation [3 points]
      ├─ Testing [2 points]
      │   └─ Unit tests [1 point]

Tags¶

CMS Planner generates two types of tags:

Story Point Tags¶

Format: SP-X where X is the story point value

Examples: - SP-1 - 1 story point - SP-3 - 3 story points - SP-5 - 5 story points - SP-13 - 13 story points - SP-21 - 21 story points

Usage: - Filter tasks by story points - Calculate sprint velocity - Track completed points

Phase Tags¶

Format: Phase-X where X is the phase number

Examples: - Phase-1 - Phase 1 tasks - Phase-2 - Phase 2 tasks - Phase-3 - Phase 3 tasks

Usage: - Filter tasks by implementation phase - Track phase progress - Plan phase releases

Creating Filters¶

In Teamwork, create saved filters:

Sprint Backlog Filter: - Tag contains: SP-5 OR SP-3 OR SP-2 OR SP-1 - Status: Active - Sort by: Priority, then Story Points

Phase 1 Tasks: - Tag contains: Phase-1 - Status: Active - Sort by: Priority

High Priority Epics: - Tag contains: SP-13 OR SP-21 OR SP-34 - Priority: High - Status: Active

Task Lists¶

Tasks are organized into task lists by phase:

Generated Task Lists¶

- Phase 1: Setup & Foundation
- Phase 2: Core Features
- Phase 3: Advanced Features
- Phase 4: Integration
- Phase 5: Testing & Polish
- Phase 6: Launch Preparation

Customizing Task Lists¶

After import, you can:

1. Rename task lists - Use your naming conventions
2. Merge task lists - Combine phases if needed
3. Create new lists - Add task lists for specific teams
4. Reorder lists - Drag and drop in Teamwork

Assignees¶

By default, the "Assign to" column is blank. After import:

Assign Tasks¶

1. Bulk assign - Select multiple tasks, assign to team member
2. Auto-assign - Use Teamwork's workload balancing
3. Manual assign - Assign individually as needed

Re-import with Assignees¶

To import with assignees pre-assigned:

1. Open the CSV in a spreadsheet
2. Add email addresses to "Assign to" column
3. Save CSV
4. Import again (Teamwork will update existing tasks)

Email format:

"john@company.com"                    ← Single assignee
"john@company.com,jane@company.com"  ← Multiple assignees

Dates¶

By default, "Start date" and "Due date" columns are blank.

Setting Dates After Import¶

1. Bulk set dates - Select phase tasks, set start/due dates
2. Use dependencies - Set dependencies, dates auto-calculate
3. Gantt view - Drag to set dates visually

Re-import with Dates¶

To import with dates pre-set:

1. Open CSV in spreadsheet
2. Add dates to "Start date" and "Due date" columns
3. Use Teamwork's date format (check your localization settings)
4. Save and re-import

Date format examples:

"2025-02-01"           ← ISO format (recommended)
"02/01/2025"           ← US format
"01/02/2025"           ← European format

Estimated Time¶

The "Estimated time" column is initially blank.

Converting Story Points to Time¶

Use your team's story point → hours conversion:

Example: 1 story point = 6 hours

CSV format:

"6"              ← Hours only
"01:30"          ← Hours:minutes
"1h 30m"         ← With units
"2 days"         ← Days

Priority Levels¶

CMS Planner sets priorities based on:

Adjusting Priorities¶

After import, adjust as needed:

1. Review critical path - Ensure dependencies have high priority
2. Adjust for sprints - Prioritize current sprint work
3. Stakeholder input - Reflect business priorities

Troubleshooting¶

Import Fails¶

Problem: CSV import fails with error

Solutions: 1. ✅ Check CSV has all required columns 2. ✅ Verify no special characters breaking format 3. ✅ Ensure file is saved as UTF-8 4. ✅ Try re-exporting from CMS Planner 5. ✅ Remove any empty rows at end of file

Hierarchy Not Preserved¶

Problem: Task hierarchy appears flat

Solutions: 1. ✅ Verify prefixes: - for level 1, -- for level 2, etc. 2. ✅ Ensure no spaces before prefixes 3. ✅ Check parent tasks exist before child tasks in CSV

Tags Not Created¶

Problem: Tags don't appear after import

Solutions: 1. ✅ Verify tags column format: SP-5,Phase-1 (comma-separated, no spaces) 2. ✅ Check Teamwork permissions (need tag creation permission) 3. ✅ Manually create tags, then re-import

Descriptions Truncated¶

Problem: Task descriptions cut off

Solutions: 1. ✅ Check description field is properly quoted in CSV 2. ✅ Verify no unescaped quotes within description 3. ✅ Try importing in smaller batches 4. ✅ Use Teamwork's API for very long descriptions

Assignees Not Found¶

Problem: Email addresses don't match users

Solutions: 1. ✅ Verify email addresses match Teamwork user accounts exactly 2. ✅ Check users are members of the project 3. ✅ Leave blank and assign after import

Best Practices¶

Before Import¶

1. ✅ Review FRD - Ensure requirements are finalized
2. ✅ Validate CSV - Open in spreadsheet, check formatting
3. ✅ Test import - Import to test project first
4. ✅ Backup - Export existing tasks if re-importing

After Import¶

1. ✅ Verify hierarchy - Check parent/child relationships
2. ✅ Assign tasks - Distribute work to team
3. ✅ Set dates - Add sprint or phase dates
4. ✅ Review priorities - Adjust based on current needs
5. ✅ Create filters - Set up saved filters for sprints, phases

Sprint Planning¶

1. Filter by story points - Use SP-X tags
2. Calculate velocity - Sum points from past sprints
3. Select sprint tasks - Choose tasks totaling sprint velocity
4. Create sprint milestone - Group sprint tasks
5. Track progress - Monitor completed points

Reporting¶

Use Teamwork reports with tags:

• Burndown by Story Points - Track SP-X tags
• Phase Progress - Filter by Phase-X tags
• Velocity Tracking - Completed points per sprint
• Team Capacity - Points assigned vs capacity

Alternative Import Methods¶

Teamwork API¶

For large imports or automation:

# Using Teamwork API
curl -X POST \
  https://yoursite.teamwork.com/projects/123/tasks.json \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "task": {
      "name": "Task name",
      "description": "Task description",
      "tags": ["SP-5", "Phase-1"]
    }
  }'

Spreadsheet Editing¶

To customize before import:

1. Open CSV in Google Sheets or Excel
2. Add assignees, dates, estimates
3. Adjust priorities or descriptions
4. Save as CSV (UTF-8)
5. Import to Teamwork

Resources¶

• Teamwork Import Guide: https://support.teamwork.com/
• CSV Format Reference: https://support.teamwork.com/importing-tasks
• Teamwork API: https://developer.teamwork.com/

Getting Help¶

• Documentation: https://kanopi.github.io/cms-planner/
• GitHub Issues: https://github.com/kanopi/cms-planner/issues
• Email: code@kanopi.com

Next: Contributing | Changelog