Asana
By integrating Asana with DX, you can analyze issue data, cycle time metrics, and projects. Please refer to the API documentation below and our schema explorer to see what data DX imports.
Prerequisites
To connect Asana to DX, you need:
- an Asana service account
Setup instructions
Follow the steps below to connect Asana to DX.
Step 1
Create an Asana service account to be used for DX, and ensure that the service account is granted access to the projects that you want to import into DX.
Step 2
Navigate to My apps in Asana, and click create a new token with the name “DX”.
Step 3
- Navigate to the connections page in DX and select “+ Connection” in the top right.
- Enter the credentials you have generated in the previous steps—refer to the information below for errors and troubleshooting.
Required permissions
DX authenticates with an Asana personal access token, which carries the full access of the user or service account that created it. Make sure that account can see every workspace, team, and project you want imported.
If you use a token that is restricted by scope, it must include the following scopes:
| Scope | Used for |
|---|---|
workspaces:read |
/workspaces |
users:read |
/users |
teams:read |
/workspaces/{workspace_id}/teams |
team_memberships:read |
/teams/{team_id}/team_memberships |
projects:read |
/teams/{team_id}/projects, /projects/{project_id} |
tasks:read |
/workspaces/{workspace_id}/tasks/search |
stories:read |
/tasks/{task_id}/stories |
custom_fields:read |
/workspaces/{workspace_id}/custom_fields |
Asana does not document a scope for /projects/{project_id}/sections. DX skips sections if access to that endpoint is denied, so it does not need to be granted.
DX only reads data and never writes to Asana. When you add the connection, DX calls the workspaces, teams, users, custom fields, task search, team memberships, and projects endpoints to confirm the token has access, and returns invalid_permissions if any of them is denied.
API reference
The table below lists the specific API endpoints that are used by DX.
| Endpoint | Documentation |
|---|---|
| /workspaces | Link |
| /workspaces/{workspace_id}/tasks/search | Link |
| /users | Link |
| /teams/{team_id}/projects | Link |
| /workspaces/{workspace_id}/teams | Link |
| /teams/{team_id}/team_memberships | Link |
| /projects/ | Link |
| /tasks/{task_id}/stories | Link |
| /projects/{project_id}/sections | Link |
| /workspaces/{workspace_id}/custom_fields | Link |
Errors
The table below lists potential error codes when adding a connection in DX.
| Error | Description |
|---|---|
invalid_credentials |
Your API credentials entered are not valid. |
invalid_permissions |
Your API token does not have the permissions required by DX. |
no_resources |
DX cannot access any projects or repositories. |