clickup-migration-deep-dive

name	clickup-migration-deep-dive
description	Migrate to ClickUp from other project management tools (Jira, Asana, Trello) or migrate data between ClickUp workspaces using API v2. Trigger: "migrate to clickup", "clickup migration", "jira to clickup", "asana to clickup", "trello to clickup", "clickup data migration", "move tasks to clickup", "clickup import".
allowed-tools	Read, Write, Edit, Bash(npm:*), Bash(node:*), Bash(curl:*)
version	1.0.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","productivity","clickup"]
compatible-with	claude-code

ClickUp Migration Deep Dive

Overview

Migrate project data to ClickUp from external tools or between ClickUp workspaces using API v2. Covers data mapping, batch creation, custom field migration, and validation.

Migration Types

Source	Complexity	Key Challenge
Trello	Low	Board -> List mapping, labels -> tags
Asana	Medium	Sections -> statuses, custom fields
Jira	High	Epics/stories/subtasks, custom fields, workflows
Another ClickUp workspace	Medium	Custom field UUIDs differ per workspace

ClickUp Hierarchy Mapping

External Concept        ClickUp API v2 Target
─────────────────       ──────────────────────
Project/Board       →   Space   (POST /team/{team_id}/space)
Epic/Section        →   Folder  (POST /space/{space_id}/folder)
Sprint/Column       →   List    (POST /folder/{folder_id}/list)
Issue/Card/Task     →   Task    (POST /list/{list_id}/task)
Subtask             →   Task with parent  (parent field)
Label/Tag           →   Tag     (POST /task/{task_id}/tag/{tag_name})
Custom Field        →   Custom Field (POST /task/{task_id}/field/{field_id})
Comment             →   Comment (POST /task/{task_id}/comment)
Attachment          →   Attachment (POST /task/{task_id}/attachment)

Migration Script

// src/migrate-to-clickup.ts
interface MigrationItem {
  externalId: string;
  name: string;
  description: string;
  status: string;
  priority?: 'urgent' | 'high' | 'normal' | 'low';
  assigneeEmail?: string;
  dueDate?: string;
  labels?: string[];
  ?: [];
}

 : <, > = {
  : , : , : , : ,
};

 : <, > = {
  : ,
  : ,
  : ,
  : ,
  
};

  (): <{ : ; : <{ : ; :  }> }> {
   migrated = ;
   : <{ : ; :  }> = [];

   ( item  items) {
     {
       assignees = item. && memberEmails.(item.)
        ? [memberEmails.(item.)!]
        : [];

       task =  (, {
        : ,
        : .({
          : item.,
          : item.,
          : [item.] ?? ,
          : item. ? [item.] : ,
          assignees,
          : item. ?  (item.).() : ,
          : !!item.,
          : item. ?? [],
        }),
      });

      
       (item.?.) {
         ( subtask  item.) {
           (, {
            : ,
            : .({
              : subtask.,
              : subtask.,
              : task.,
              : [subtask.] ?? ,
            }),
          });
        }
      }

      migrated++;
      .();

      
        ( (r, ));
    }  (error) {
      errors.({ : item., : (error) });
    }
  }

   { migrated, errors };
}