Migrate Asana projects to OpenProject
Move Asana projects to OpenProject with a task-to-work-package map, explicit history and attachment treatment, permission checks and controlled cutover.
Last updated
In short
- Asana tasks can belong to multiple projects; avoid duplicate target work packages.
- CSV creation does not preserve every hierarchy, relation or attachment.
- Keep original IDs and accepted history exceptions in the migration ledger.
On this page (7)
Migration plans · Part of OpenProject
Editable source-to-target ledger with fidelity and acceptance fields.
Download the migration mapping worksheetTranslate the project model before exporting
Asana tasks and OpenProject work packages can both represent work, but their project membership, fields, workflow states and history models differ. A migration should preserve the information people need to continue the project while explicitly recording what is rebuilt or archived.
This is a reference mapping and acceptance procedure, not a tested importer. Record the Asana plan and export/API access, OpenProject release and edition, required modules and target workflow configuration. Verify available features in the selected edition rather than assuming that every source feature has a free equivalent.
Build a field and relationship map
| Asana element | Proposed OpenProject treatment | Fidelity decision |
|---|---|---|
| Project | Project or other agreed grouping | Preserve owner and visibility |
| Task | Work package | Store source task ID |
| Section | Status, category or grouping | Choose based on actual meaning |
| Subtask | Parent/child work-package relationship | Rebuild after base objects exist |
| Assignee | Mapped target user | Resolve inactive or missing users |
| Due/start date | Supported date fields | Preserve date semantics and timezone where relevant |
| Custom field | Compatible configured field or retained source note | Record type and unsupported values |
| Comments/activity | API-assisted reconstruction or readable archive | Preserve provenance without fabricating authorship |
| Attachments | Download and reattach through supported method | Verify content and access |
| Rules and automations | Rebuild separately | Validate triggers and notifications |
Asana’s project-task API notes that tasks can belong to multiple projects. Use the stable task ID as the deduplication key. Decide whether the target should have one work package with cross-project references or another explicitly agreed representation; importing each project independently can duplicate the same work.
Choose CSV or API work according to fidelity
OpenProject’s current CSV importer creates work packages and documents important exclusions, including hierarchy, relations, custom fields and attachments. It also does not update existing work packages through repeated imports. Verify those limits against your selected release.
CSV can be appropriate for a simple task list. Richer migration needs additional steps through the work-package API or manual reconstruction. Create base objects first, persist source-to-target IDs, then apply relationships and attachments. Do not rerun a creation import blindly after a partial failure.
Retrieve all required source fields explicitly and follow API pagination. A compact task response or the first page of results is not a complete export. Include completed tasks according to the agreed historical scope rather than relying on a default filter.
Preserve history honestly
Asana’s stories endpoint provides task activity and comments. Distinguish human comments from system events. Decide whether each belongs as a target comment, a structured migration note or an attached archive.
If the target API records the migration account as the creator, retain the original author and timestamp as clearly labelled source metadata. Do not present a reconstructed comment as though the original person posted it natively in OpenProject. Keep the source record ID and original URL for audit and support use.
Download attachments while the source credentials remain valid. An attachment URL may depend on authentication or expire; a copied hyperlink is not the same as preserving the file. Compare byte counts or digests and verify the target user’s access to the resulting attachment.
Rehearse with a deliberately varied project
Use synthetic tasks covering an unassigned task, a completed task, a subtask, a multi-project task, an attachment, a custom field and several comments. Include a private project and an external collaborator.
| Check | Passing evidence |
|---|---|
| Object counts | Unique source IDs reconcile to target IDs or accepted exclusions |
| Ownership | Assignees map to the correct active users |
| Hierarchy | Parent/child and dependency relationships match the chosen model |
| Fields | Dates, status and custom values preserve meaning |
| History | Comments and provenance remain readable |
| Attachments | Files open and content checks match |
| Permissions | Outsider cannot discover private work packages or files |
| Notifications | Rehearsal does not send unintended messages |
Have project owners review workflow behavior, not just the imported table. A task marked “waiting for supplier” may need a different target state from a task awaiting internal approval, even if both were in the same visual section.
Cut over with a change ledger
Freeze source edits or record a defined delta window. Capture tasks and comments changed after the rehearsal export, then apply the reviewed delta using the mapping ledger. Reconcile open work, assignments and due dates before directing users to the new project.
Disable source automations and enable target notifications in a controlled sequence. Update links in team documentation and explain changed workflows. Keep the source accessible for the agreed transition and historical-reference period.
Roll back without duplicating work
If acceptance fails before target work starts, return users to the source and retain the failed import for diagnosis. If users have already changed target work packages, export or record those changes and reconcile them back before switching authority. Repeating a CSV import can create duplicates, so use the ledger to distinguish existing and missing objects.
Back up the target database, attachments, configuration and required secrets. Revoke temporary migration credentials after acceptance and retain exports only under the organization’s retention policy. Completion means owners accept the ongoing project workflow, permission boundary and documented fidelity exceptions, not merely that every CSV row produced a work package.
Sources and further reading
Use the linked documentation to confirm the version, edition and contract that apply to your project.
