IthuraDocs
Open app

Import from Asana

Bring an Asana project into an Ithura project. The importer reads a project's tasks over the Asana REST API and re-creates each one as an Ithura issue, carrying across the task name, notes, comments, tags as labels, assignee, section as state, and dates. Every run happens in the background and lands in the Recent imports list when it finishes.

Asana is one of several import sources. For the shared mechanics and the other sources, see the Imports overview.

Before you start

  • An Asana personal access token. Generate one in Asana under Profile, then My Apps, then the Developer Console. This is your own token for your own Asana account, entered per import (Ithura does not store a shared Asana connection).
  • You do not need to create a destination project first: each Asana project you select imports into its own new Ithura project, named after it.

Step by step

Open Workspace settings -> Imports at /{workspace}/settings/imports, then click Asana.

  1. Connect. Paste your Asana personal access token and click Next: preview. Ithura validates the token and reads the projects it can see across your workspaces.

    Connect Asana: a personal access token.

  2. Select projects. The preview lists the Asana projects the token can reach, each shown as "Workspace / Project" with a checkbox. Tick one or more. Every project you pick imports into its own new Ithura project, named after it, so you can move several across in a single run. Re-importing a project that already has a same-named Ithura project updates it in place rather than creating a duplicate. Click Continue.

    Select one or more Asana projects to import.

  3. Review the combined preview. Ithura validates each selected project and shows the summed task and comment counts. When the totals look right, click Run import.

    Combined preview: total task and comment counts across the selected projects.

  4. Watch it run. Each selected project starts as its own background job and appears at the top of Recent imports, refreshing on its own with the status and how many tasks have been processed. When every job reaches completed, the import is done.

    Recent imports: the Asana jobs completed.

What comes across

For each task in the project, the importer maps:

  • Task. The task name becomes the issue name and the task notes become the Ithura description. Created date, completed date, and due date carry across.
  • Comments. Each comment story on the task is recreated with its text and creation time. Non-comment stories (system activity) are skipped. The comment author is matched to an Ithura account by email where the address is available.
  • Tags as labels. Every Asana tag on the task becomes an Ithura label, created in the destination project if it does not exist yet.
  • Assignee. The assignee is matched to an Ithura account by email. If no workspace member has that email, the issue falls back to you (the person who ran the import).
  • Section as state. A completed task lands in the completed state group. An open task takes its state from the name of the section it sits in: sections containing "done" or "complete" map to completed, "cancel" to cancelled, "progress", "doing", or "started" to started, "todo", "to do", or "ready" to unstarted, and "backlog" to backlog. Anything else falls back to backlog. The section name is preserved as the state name.
  • Priority. Asana tasks arrive with no priority set. Set priorities in Ithura after the import if you need them.

Good to know

  • Sections drive the state mapping. The importer reads a task's first section membership and matches the section name against common column names. If your board uses unusual section names, those tasks land in backlog and you can move them afterward.
  • Only comment stories become comments. Asana records many kinds of story (assignments, section changes, and so on). Only the ones typed as comments are imported; the rest are ignored.
  • Re-running is safe. Imports are idempotent: each task is tracked by its Asana id, so re-running the same project creates no duplicates.

What is not imported

  • System stories (only comment stories become comments).
  • Sub-tasks as a hierarchy, custom fields, dependencies, and attachments.
  • Rich formatting beyond plain text.

Troubleshooting

  • The connection fails at Connect or Preview. The personal access token is wrong or lacks access. Generate a fresh token in the Asana Developer Console and paste it again.
  • No projects appear. The token can only see workspaces and projects your Asana account belongs to. Use a token from an account that is a member of the project you want.
  • Tasks landed in the wrong state. Their section names did not match the known column keywords, so they fell back to backlog. Move them in Ithura, or rename the Asana sections and re-import into a clean project.
  • Assignees are missing after the import. Those Asana members have no Ithura account with a matching email, so their tasks were attributed to you. Invite them and reassign, or reassign by hand.
  • A job is stuck pending or running. Expand it in Recent imports and click Cancel, then start a new import.