Connect Asana
Connect Asana with a personal access token, see which projects and tasks Gurusup reads, bring in past tasks, and fix a token Asana stops accepting.
Admins only. Gurusup also reads project status updates and every task's comments, so you can ask "What did we promise this customer, and where is it in Asana?" and get the task joined with the CRM deal and the meeting where it was agreed. Gurusup only reads Asana: the only things it creates there are its own webhooks, so it hears about changes.
At a glance
| Topic | Details |
|---|---|
| Who can connect | Admins |
| What you need | An Asana personal access token |
| What Gurusup reads | Projects shared with the whole Asana workspace, and their tasks |
| How changes arrive | As they happen, through webhooks, plus a daily check of shared projects |
| Past content | Import history, from last week to last year |
| Knowledge access | Default access, Restricted or Private. See Who can read it. |
Before you start
- You are an admin in Gurusup. Members see Ask your admin instead of Connect.
- You have an Asana personal access token. You create it in Asana under My settings > Apps > Developer apps.
- The token belongs to one person, and Gurusup reads what that person can see. Pick a member of the projects your team shares. Their private projects stay out.
- One Asana workspace per Gurusup organization. If the token is in several, you choose one when you connect.
Connect Asana
Open the Asana connector
In the sidebar, open Sources, then Catalog, find Asana (use Search sources if you need to) and click Connect on its row. Its page opens. Next to Organization accounts, click Connect for the organization. The dialog Connect Asana for the organization opens.
Create the token in Asana
In the dialog, below the fields, click Show steps, then Open Asana. In Asana, open My settings > Apps > Developer apps, create a personal access token and copy it.
Paste the token
Paste it in Personal access token. Gurusup says "Reading the projects this token reaches in Asana…" and then lists them under "Projects Gurusup will read in" with your Asana workspace name. Archived projects show Archived.
Check the workspace and the projects
If the token is in more than one Asana workspace, pick one in Workspace and the projects update. If private projects stay out, a line says how many, for example "2 private projects this token sees stay out: Gurusup only reads projects shared with the whole workspace." If Asana does not list the projects within 10 seconds, or does not answer, the list is replaced by "Counting is taking too long right now, usually because the workspace is large. You can still connect." and Connect stays available.
Choose who can read it (optional)
Under Who can read it, Access mode starts as Default access. Choose Restricted or Private to limit the source to the people you pick.
Connect
Click Connect (it stays off until Gurusup has read the projects). A message says "Asana connected." and the connection appears under Organization accounts with a Connected badge. Asana takes one connection, so Connect for the organization stays off while it exists.
What Gurusup reads
Each shared project and each task in it becomes its own document.
| Document | What it holds |
|---|---|
| A project | Name, owner, team, start and due dates, whether it is completed or archived, the names of its custom fields, its description, its sections, its latest status updates (up to 20, with title, status, author and date) and a link to open it in Asana |
| A task | The shared projects and sections it is in, assignee, start and due dates, completion date, tags, created and updated dates, custom field values, description, subtasks (with who they are assigned to, their notes and comments), comments with author and date, and a link to open it in Asana |
A change to a subtask updates its parent task's document. Gurusup also notes issue keys and Linear, Jira and GitHub links, to join a task to the issue it mentions.
What Gurusup does not read
| Left out | Why |
|---|---|
| Private projects | Gurusup only follows projects shared with the whole Asana workspace, even when the token sees more. In an Asana workspace that is not an organization, a project is shared when the workspace's team is a member. |
| Projects shared with one team only | In an Asana organization, only projects visible to the whole organization are read. |
| Tasks only in private projects | A task comes in while at least one of its projects is shared. |
| Names of private projects and their custom fields on a shared task | The task's document only names the shared projects. |
| Activity such as moves and assignments | Only comments are read, not the activity history around them. |
| Attachments on a task | Gurusup does not open files attached in Asana. |
How changes arrive
- Gurusup starts from now. It follows each shared project when you connect and reads what changes from then on: a task that changes, a project that is created, and a project's status updates. A project that already exists and has no news, and tasks that do not change, wait for an import. A comment on a task changes the task, not its project.
- As they happen. Gurusup sets up webhooks in Asana, one on the workspace and one per shared project. New, changed and deleted tasks, comments, sections and status updates arrive as they happen.
- New shared projects. When a project is created or shared with the whole workspace, Gurusup starts following it and reads its tasks changed since you connected. Gurusup also checks the list of shared projects once a day.
- Removed content. When a task or project is deleted, or a project is made private, Gurusup withdraws it with the tasks that were only in that project: what it learned only from them leaves, and anything other sources also back stays.
Everything Gurusup reads from Asana uses your usage.
Import past work
Until you import, History says "Only new content comes in until you import past content."
Open Import history
On Sources, open the Asana page. Under History, click Import history.
Pick how far back
Choose Last week, Last month, Last 3 months, Last 6 months or Last year. Gurusup counts the tasks changed in that window in your shared projects, for example "~120 tasks", or "500+ tasks" past 500, and shows what the import would use out of what you have left this month, in euros.
Import
Click Import. The message reads "Importing history. It keeps going in the background." When it is done, the row names the window imported, and that window shows "Already imported" next time.
What does not fit in your remaining usage waits until it renews. If the import stops, the button reads Try again.
Who can read it
Asana is one source. Gurusup does not copy who can see a project in Asana.
| Knowledge access | Who reads it in Brain |
|---|---|
| Default access | Everyone, according to what they are already allowed to see: admins every category, members and agent accounts the categories an admin granted them. |
| Restricted | Only the people you pick. Administrators are not included unless you pick them. |
| Private | Only you. Administrators are not included. |
A choice made when you connect applies before Gurusup reads anything. To change it later, open the Asana page and change Access mode under Knowledge access. It saves as soon as you change it ("Knowledge access saved."), and it covers only what arrives after that. See Restrict a source to specific people.
Check that it worked
- On Sources, an Asana row is there with the status Connected.
- Open Ingest and pick the Asana source in the source filter. Your shared projects move from Queued to Learning to Learned. See Follow ingestion.
- Add a comment to a task in a shared project. It appears on Ingest as an update for that task.
Reconnect
Open the Asana page from Sources. Under Organization accounts, the account shows its status and "Synced" with the time of its last read. To swap the token, for example when its owner leaves, click Reconnect on the account's row, paste a new token from the same Asana workspace and click Reconnect again. Gurusup keeps what it learned and replaces its webhooks.
If Asana stops accepting the token, the status reads Needs reconnect and the page does not list the projects Gurusup reads. Click Reconnect on the account's row and paste a new token. Until you reconnect, no changes come in.
Disconnect
On Sources, open the Asana page and, under Danger zone, click the menu on Disconnect, choose Disconnect and confirm. The three dots on the account's row ("More actions for" the account's name) do the same. Gurusup deletes its webhooks in Asana and forgets the token, which stays in Asana under My settings > Apps > Developer apps until you remove it; see Remove, disconnect and what stays.
If it does not work
| Message | What to do |
|---|---|
| "Asana didn't accept this token. It may have been revoked. Create a new one in Asana under My settings → Apps → Developer apps → Personal access tokens and paste it here." | Create a new token and paste it. |
| "This token can't read that Asana workspace. Use a token from a member of the workspace." | The token's owner is not a member of that Asana workspace, or the token cannot read it. Use a token from a member. |
| "This token isn't in any Asana workspace. Use a token from a member of your workspace." | Use a token from a member. |
| "Choose the Asana workspace to connect." | Pick one in Workspace. |
| "No shared projects yet" or "Gurusup reads projects shared with the whole workspace, and none are yet." | Share the projects you want Gurusup to read with the whole Asana workspace, or connect a different one. |
| "Asana needs to be reconnected with a new personal access token." | Asana refused the token. Paste a new one and click Reconnect. |
| "Gurusup couldn't read Asana just now. Try again in a minute, and contact support if it keeps failing." or "We couldn't read Asana because of a problem on our side. Nothing was changed. Try again in a few minutes, and contact support if it keeps failing." | Wait a few minutes and paste the token again. If it keeps failing, contact support. |
| "Could not connect Asana." followed by "We couldn't connect Asana because of a problem on our side. Nothing was connected. Try again in a few minutes, and contact support if it keeps failing." | Same as above. |
| "We couldn't read your Asana projects because of a problem on our side. Your connection is unchanged. We've logged the problem. Contact support for help." | Your connection keeps working. Contact support if it does not go away. |
| "Only organization admins can manage integrations." | Ask an admin to connect Asana. |
| "The import didn't finish. Try again, and contact support if it keeps failing." | Click Try again. If it keeps failing, contact support. |
| "Ingestion is paused for this organization. Ask your organization admin to resume ingestion before adding content." or "Demo Mode prevents changing external sources. Ask your organization admin to turn off Demo Mode to continue." | Connecting, reconnecting and changing what a source brings in are off. Disconnect still works while ingestion is paused, but not in Demo Mode. See Connectors overview. |
Nothing coming in and no message? See Connector troubleshooting.