Import reference
What each importer brings across, what it does not, its limits, and how people are
matched. For the walk-through, see the
migration guide.
Before you import
| Plan |
Importing is included in Pro and Ultra, and both start with a 30-day trial. Connecting a
tracker and previewing it are part of the same plans. A CSV file can be previewed on any plan. |
| Role |
Settings → Import is shown to Admin and Owner. |
| Token |
Read access to the source is enough. The token is used for the run and is not saved on the import job. |
| Target |
An xpntl project you choose. ClickUp is the exception: it creates the project from the Space. |
How an import runs
- Connect. Pick the source and supply its token. xpntl reads the source. It never edits or deletes anything there.
- Preview. xpntl lists what it found under Choose issues to import, with every row selected. Filter by title, deselect rows, or deselect a whole status. Nothing is written at this step.
- Map assignees. See Matching people.
- Import. The run is a background job. The screen shows the total, how many were imported and how many failed, with a reason for each failed row.
What every import does
| Keys |
Each issue gets a new key in the target project. The key or number it had in the source is not kept. |
| Creator |
The person who ran the import is recorded as the creator of each issue. |
| Completion date |
No importer reads a completion date. An issue that arrives in a completed state is stamped with the time of the import. |
| Labels |
A label that already exists by name is reused. New ones are created gray. ClickUp tags keep their color. |
| States |
A source status maps to your first workflow state of the matching type: Todo, In Progress, Done and so on. ClickUp and CSV look for a state with the same name first. |
Running an import twice
The Azure DevOps importer records each work item it brings over, so a second run skips what
is already there and imports what is new.
The importers for Jira, GitHub, ClickUp, Asana, Trello and CSV keep no such record. A second
run creates every selected issue again, as duplicates. To bring more from one of those
sources later, deselect in the preview what you already imported.
Matching people
Jira, GitHub, Asana, Trello, Azure DevOps and CSV show a Map assignees panel
above the preview. It lists each distinct assignee found. A value that equals a teammate's
email, the part of it before the @, or their display name is matched for you. Choose a
teammate for any other value, or leave it at Unassigned.
- An assignee left unmapped imports as unassigned. It does not block the import.
- Jira, Azure DevOps and CSV also match on email when no mapping is given.
- GitHub provides logins and no emails, so GitHub assignees come only from the mapping.
- ClickUp has no mapping panel. It matches assignees by email, and an assignee with no matching email is not assigned.
By source
Jira Cloud
| Needs | Site URL, account email and an API token |
| Maps | One Jira project into an xpntl project you choose |
| Comes across | Summary. Description, converted from Jira's rich text. Status by category: To Do, In Progress and Done map to your Todo, In Progress and Done states. Priority: Highest becomes Urgent, High stays High, Medium stays Medium, Low and Lowest become Low. Labels. Assignee. Comments with their dates. Created and updated dates. |
| Does not come across | Attachments: a line naming each one stays in the text. Sub-task and epic hierarchy. Sprints, components, issue links, custom fields, due dates and issue type. |
| People | Mapping by display name, then a matching email. A comment keeps its author when the author's email matches a teammate. Otherwise it is posted by the person who ran the import. |
| Limits | The preview lists the first 2,000 issues. With every listed issue selected, the whole project is imported. |
GitHub Issues
| Needs | The repository as owner/repo and a token with read access to it |
| Maps | One repository's issues into an xpntl project you choose |
| Comes across | Title. Body. Open issues land in Todo and closed issues in Done. Labels. The first assignee, when its login is mapped. Created and updated dates. |
| Does not come across | Comments. Milestones. Assignees after the first. Pull requests, which are skipped. Priority is left unset. |
| People | Mapping by login. There is no email match. |
| Limits | The first 1,000 issues, oldest first |
ClickUp
| Needs | A personal API token (pk_...) |
| Maps | One Space becomes an xpntl project of the same name, or fills an existing project with that name. Lists become lists. A list inside a folder is named Folder / List. |
| Comes across | Name. Description. Custom fields, as a list at the end of the description. Status, by state name and then by type. Priority. Tags, with their colors. Every assignee whose email matches a teammate. Sub-tasks, as sub-issues. Comments with their dates. Attachments. Start and due dates. Created and updated dates. |
| Does not come across | Archived lists and tasks. Custom fields as fields. Dependencies, checklists and time tracking. |
| People | Email match only. There is no mapping panel. |
| Limits | 2,000 tasks a run. 25 MB an attachment. |
| Also | An agent can run this import over MCP with xpntl_clickup_browse, xpntl_clickup_import and xpntl_import_status. |
Azure DevOps
| Needs | The organization name or its dev.azure.com URL, and a personal access token with Work Items (Read) scope |
| Maps | One project's work items into an xpntl project you choose |
| Comes across | Title. Description as Markdown, with repro steps for a bug and acceptance criteria under its own heading. Work item type: Epic, Feature, Story, Task and Bug. Any other type becomes Issue. State by category: New to Backlog, Active to In Progress, Resolved to Review, Closed to Done, Removed to Canceled. Priority: 1 becomes High, 2 becomes Medium, 3 and 4 become Low. Tags. Assignee. Parent links. Comments with their dates. Created and changed dates. |
| Does not come across | Attachments. Iterations and area paths. Links other than parent. Custom fields. Test plans, test suites and test cases, which are skipped. |
| People | Mapping by display name, then a matching email. A comment keeps its author when the author's email matches a teammate. Otherwise it is posted by the person who ran the import and opens with the author's name. |
| Limits | The preview lists the first 2,000 work items. 5,000 work items a run, and 200 comments a work item. Run it again for the rest. Azure DevOps Services only. |
Asana
| Needs | The project id or URL, and a personal access token |
| Maps | One project's tasks into an xpntl project you choose |
| Comes across | Name. Notes. Completed tasks land in Done and the rest in Todo. Tags, as labels. Assignee, when mapped. Created and modified dates. |
| Does not come across | Comments. Subtasks. Sections: the preview shows them, the import does not keep them. Due dates, custom fields and attachments. Priority is left unset. |
| People | Mapping by name, or by email where Asana gives no name |
| Limits | The first 1,000 tasks |
Trello
| Needs | The board id or URL, an API key and a token |
| Maps | One board's cards into an xpntl project you choose |
| Comes across | Name. Description. State from the list: archived cards, and cards on a list whose name includes Done, Complete, Closed, Shipped, Resolved or Archive, land in Done. The rest land in Todo. Labels, by name, or by color where a label has no name. The first member, as assignee, when mapped. |
| Does not come across | Comments. Checklists. Attachments. Due dates. Members after the first. The created date: a card is dated by its last activity. |
| People | Mapping by member name |
| Limits | 1,000 cards |
CSV file
| Needs | A CSV file with a header row |
| Maps | One file into an xpntl project you choose. You map columns to fields. Title is required. |
| Comes across | Title. Description. Priority, as a number from 0 to 4. State, when the cell equals the name of one of your states. Assignee. |
| Does not come across | Labels, comments, dates and hierarchy |
| People | Mapping first, then a cell that equals a teammate's email |
| Limits | 1,000 rows an import. 5 MB a file. |