Asana

What your agents can doCopy Anchor Link

Agents use Asana's REST API to work with tasks, projects, and related resources. Helios attaches the connection's token to API requests.

• Create tasks from a request, with an assignee, a due date, a project, and a section
• Move tasks between sections, change their fields, and mark them complete
• Comment on tasks, reply to comments, and upload files as attachments
• Create and update projects, sections, tags, portfolios, and goals
• List a project's open tasks and summarize its status and blockers

Agents act as the connected Asana user and can only see and change what that user can. The agent's API tool can only reach Asana's API at app.asana.com/api/1.0. Some admin endpoints, such as the audit log, organization exports, and workspace events, accept only a service account token. See Asana Personal Access Token.

AuthenticationCopy Anchor Link

See Integration authentication for how credentials are stored and injected.

Asana Personal Access TokenCopy Anchor Link

Any Asana user can create a personal access token. On Enterprise plans, admins can limit which personal access tokens can connect to Asana.

1. Open the Asana developer console.
2. Click + Create new token, enter a Token name, and click Create token.
3. Copy the token. Asana shows it only once.
4. In Helios, choose Asana Personal Access Token and paste the token into Personal Access Token.
5. Optional: for triggers, enter a project's ID in Project and a workspace's ID in Workspace. See Triggers.
6. Save.

Personal access tokens are long-lived. If you delete the token in Asana, the connection stops working and Asana removes its webhooks. To change the token, create a new one, enter it through Manage, and save.

Service accounts. The Personal Access Token field also takes a service account token. Service accounts are an Enterprise feature, and only a super admin can create one, under Apps > Service Accounts in the admin console. A service account with Full Permissions reaches all data in the domain, and its scopes can add the audit log, organization exports, and workspace events APIs. Those three APIs also need an Enterprise+ plan, or Enterprise with the Compliance Management add-on for the audit log and workspace events. See Asana's authentication guide.

Your own Asana OAuth appCopy Anchor Link

You need an Asana account in the workspace that will use the app. Any member can approve the app. In Enterprise organizations, admins can approve or block apps in the admin console. If yours does, an admin has to approve the app first.

1. In the developer console, click Create new app and create the app.

2. On the app's OAuth tab, add this redirect URL:

   Copy Text

   https://api.heliosapp.com/integrations/asana/oauth_callback

3. On the same tab, under Permission scopes, turn on Full permissions and save.

4. On the Manage distribution tab, choose Specific workspace, click + Add workspace, and pick your workspace. Asana only lets users approve an app that is available in their workspace.

5. In Helios, choose Your own Asana OAuth app and enter the app's Client ID and Client Secret from its OAuth tab. Optional: for triggers, enter a project's ID in Project and a workspace's ID in Workspace.

6. Save, then approve access in Asana.

Helios asks for one scope:

An app with Full permissions on can't ask for specific scopes, and an app without it can't ask for default.

Asana has no admin scopes for OAuth apps, so this method has no Admin access option.

Access tokens last an hour, and Helios renews them with the refresh token Asana issues. If you reset the client secret in Asana, enter the new one in Helios through Manage and connect again.

TriggersCopy Anchor Link

Asana can start a Workflow when something happens in a project or a workspace. Helios registers the webhooks when you save the connection, so there is nothing to set up in Asana. Deleting the connection removes them.

• Project is the ID of a project to watch, the number after /project/ in the project's URL. Helios registers a webhook on that project. It receives events on the project and on the tasks, comments, and sections in it, including subtasks.
• Workspace is the ID of a workspace to watch, the number after /1/ in an Asana URL such as https://app.asana.com/1/1234567890/project/.... Helios registers a second webhook on the workspace. It receives project, portfolio, goal, and project template events from across the workspace, and team and workspace membership events.

Both are optional. Without Project, the task, comment, story, section, attachment, project member, and time tracking events are unavailable. Without Workspace, the project, project template, portfolio, goal, and membership events are unavailable, except project.changed, project.deleted, and project.undeleted for the watched project. The trigger picker shows unavailable events and the reason.

The connected user needs access to the project and must be a member of the workspace. If Asana refuses the webhook on the project or the workspace, Helios keeps the other webhook and marks the refused webhook's events unavailable, with Asana's reason.

All filters are optional patterns, and case matters.

• Changed field matches the name of the field Asana reports as changed, such as assignee, due_on, completed, name, notes, or custom_fields. To start a run when a task is completed, use task.changed with Changed field set to completed. Events without a changed field don't match when it is set.
• Subtype matches the subtype of the task or the activity. Tasks are default_task, milestone, or approval. Activity records name what happened, such as marked_complete, assigned, due_date_changed, or section_changed.
• Parent type matches the kind of object the item was added to or removed from, such as project, section, task, or tag. For example, task.added with Parent type section matches a task moved into a section. Parent type project also matches a task in the watched project being added to another project.

Asana sends compact events that name the object by ID, so the agent reads the details through the API. For comments and activity records, the event's resource is the story Asana recorded, and its parent is the task. Only added and removed events have a parent.

Deliveries are verified with the HMAC-SHA256 X-Hook-Signature header, using the secret Asana sends when each webhook is created. Helios ignores events more than a day old.

Asana's delivery rules:

• Asana retries a failed delivery for up to 24 hours. After that, it deletes the webhook. It also deletes a webhook that doesn't answer its eight-hourly check for 24 hours. Save the connection again to register new webhooks.
• Asana delivers each event at most once, so in rare cases an event never arrives.
• If the token's user loses access to the project, the webhook stays but no events arrive.
• Events arrive in under a minute on average, and most arrive within 10 minutes.

Check that it worksCopy Anchor Link

• The connection: after you save, the connection's status shows Connected. Error means the connection test failed. Check the error details and see Common errors.
• A trigger:
  1. Add task.added to a workflow with no filters.
  2. Create a test task in the watched project.
  3. Check that a run starts. Then open the connection in Helios and click Webhook events to see the event.
• The webhooks: to see the webhooks Helios registered, ask an agent to call GET /webhooks with your workspace ID.

Common errorsCopy Anchor Link

LimitsCopy Anchor Link

• Rate limits: Asana allows 150 requests a minute per token in free domains, and 1,500 in paid domains. Each token can also run 50 read requests and 15 write requests at once, and search allows 60 requests a minute. A separate per-minute limit on computing cost can stop costly requests sooner, such as ones that fetch many related objects. See Asana's rate limits.
• Webhooks: Asana allows 1,000 webhooks on one object and 10,000 for one token. See Asana's webhook limits.
• Plans: Portfolios, goals, and time tracking need the Advanced plan or higher. Users with a view-only license have limited access to the API.
• Projects: each connection watches one project and one workspace for triggers. Agents can still work in every project the token can see.