Asana is a work tracking and collaboration tool. This guide is designed to give developers a brief overview of how Asana is structured. It is not meant to be exhaustive, as the intention is to describe the fundamental elements of Asana to help you scope apps and avoid common points of confusion.
Tasks are the basic unit of action in Asana. Tasks have many fields including a single assignee, name, notes, followers (i.e., collaborators), likes, and comments (among others). Tasks inherit custom fields from their parent project(s). Custom fields values are set for each individual task.
In addition to standard Create / Read / Update / Delete operations, there are a few things to watch out for when working with tasks:
- Tasks can be orphaned and belong to no projects, they can belong to one project, or they can be multi-homed across two or more projects. The
membershipsfield is a collection of the projects with which the task is associated. - Tasks can be multi-homed as subtasks. For example, task A can be in project B and the same task A can also be a subtask of task C.
A project is a collection of tasks that can be viewed as a list, board, timeline, and calendar. Projects can only exist in a single organization or workplace and only belong to a single team. Projects can be public in the team or private to project members. Among the many fields associated with projects, they can have global (shared across the organization) or local (project-specific) custom fields. A project’s custom fields will be displayed on each task within the project.
Portfolios are collections of projects (or other portfolios). Custom fields can be added to portfolios in addition to standard fields that are displayed on every portfolio. These fields provide a high-level overview of the status of each project within the portfolio.
A section is a group of tasks within a project. Sections let you divide tasks into categories, workflow stages, priorities, and more.
A subtask is exactly the same as tasks in a project, except that one (and only one) of its parents is a task (although subtasks can also simultaneously be organized into projects). To check if a task has a subtask, include the num_subtasks field when fetching the parent task.
Things to note when working with subtasks:
- Subtasks do not inherit the projects of their parent tasks.
- There can be up to 5 levels of subtasks below a task. We do not recommend making sub-subtasks.
- There is no way to fetch all subtasks of all tasks in a project in a single request.
A workspace is the highest-level organizational unit in Asana. All projects, tasks, and teams have an associated workspace.
An organization is a special kind of workspace that represents a company. Organizations connect all the employees at a company using Asana in a single space based on the company’s shared email domain. In an organization, you can group your projects into teams.
Teams are a subset of users in an organization who collaborate on projects together. Every project in an organization is associated with one team. Team messages are not currently available in the API.
A user object represents an account in Asana that can be given access to various workspaces, projects, and tasks. Asana accounts are free and tied to individuals; Asana accounts grant access to one or more shared workspaces and organizations to collaborate with other Asana users.
Users can invite clients, contractors, customers, or anyone else who does not have an email address at an approved organization email domain. These users join as organization guests. Guests have limited access in an organization. That is, guests can only see what is explicitly shared with them.
Note: it can be advantageous to use guests to create "bot" accounts. Due to the access restrictions, bots created from a guest account personal access token can be given fine-grained access to only the data that it needs to use.